# Urbicon UI – Full API Reference for LLMs

> This file is optimized for LLM consumption. It contains everything needed to correctly generate code using Urbicon UI.

## Installation

Urbicon UI packages are published on the public npm registry — no registry configuration needed:

```bash
bun add @urbicon-ui/blocks @urbicon-ui/i18n
```

Requirements: Svelte 5, Vite and Tailwind 4. SvelteKit is **not** required — `blocks`, `table` and
`i18n` import neither `$app/*` nor `@sveltejs/kit`, so a plain Vite + Svelte project runs them
(`@urbicon-ui/auth` and `@urbicon-ui/sveltekit-utils` are the SvelteKit-bound packages).

In a SvelteKit project the `sv` add-on does the packages **and** the CSS wiring below in one step
(non-interactive form — pre-answer Tailwind's plugin prompt so the run never blocks). The add-on is
SvelteKit-only; elsewhere use the install plus the CSS setup below:

```bash
bunx sv add tailwindcss=plugins:none @urbicon-ui
```

CSS setup (in your app's root layout or entry CSS) — already done for you on the add-on path. Your
app owns the Tailwind import and it MUST come first; the Urbicon UI CSS that follows depends on it
and overrides its defaults:
```css
@import 'tailwindcss';
@import '@urbicon-ui/blocks/style/index.css'; /* tokens + @source directives */
@import '@urbicon-ui/table/style/index.css';  /* only if you use @urbicon-ui/table */
@import '@urbicon-ui/auth/style/index.css';   /* only if you use @urbicon-ui/auth */
```

Import the single `style/index.css` — **not** the `foundation`/`semantic`/`interaction`
subfiles. `index.css` ships the design tokens, global classes (`.sr-only`, mint styles),
and the Tailwind `@source` directives that make Tailwind scan the component classes inside
`node_modules`. You do **not** need to add any manual `@source` directives; importing the
subfiles (which omit those directives) is the usual cause of responsive utilities like
`lg:hidden` going missing in production.

## Import Pattern

ALWAYS import from the package root:
```svelte
<script>
  import { Button, Input, Card, Dialog, Badge } from '@urbicon-ui/blocks';
</script>
```

NEVER import from internal paths like `@urbicon-ui/blocks/primitives/Button`.

---

## Shared API Grammar

Every component follows a predictable API. Learn once, apply everywhere.

### `intent` – Semantic Color

Values: `primary` | `secondary` | `success` | `warning` | `danger` | `neutral`
Default: `neutral` (action elements), `primary` (form/decorative elements)

### `variant` – Visual Weight

Values: `filled` | `outlined` | `ghost` | `text` (component-dependent)
- `filled`: Solid background, highest emphasis
- `outlined`: Border only, transparent background
- `ghost`: No border, no background
- `text`: Minimal, text-only (Button only)

### `size` – Dimensions

Standard scale: `xs` | `sm` | `md` | `lg` | `xl`
Default: `md` for all components.

| Size | Height | Font     |
|------|--------|----------|
| xs   | h-6    | text-xs  |
| sm   | h-8    | text-sm  |
| md   | h-10   | text-base|
| lg   | h-12   | text-lg  |
| xl   | h-14   | text-xl  |

### `unstyled` – Strip All Default Styles

```svelte
<Button unstyled class="my-custom-classes">Custom</Button>
```

### `slotClasses` – Override Specific Slots

Each component documents its slots. Override without losing other styles:
```svelte
<Card slotClasses={{ header: 'bg-primary-subtle', footer: 'border-t-2' }}>
  ...
</Card>
```

### `mint` – Micro-Interactions (opt-in)

No setup required — unknown names demand-load the built-in set on first use.
Values: `'scale'` | `'translate'` | `'rotate'` | `'glow'` | `'pulse'` | `'wiggle'` (hover, held
while the pointer stays) | `'bounce'` | `'shake'` | `'ripple'` (click, one-shot) | `'none'` |
array of these | `{ name, config }` entries with `duration`/`easing` (`intensity`: scale only).

```svelte
<Button mint="scale">Hover me</Button>
<Card mint={['scale', 'glow']}>Interactive</Card>
<Button mint={[{ name: 'glow', config: { duration: 500 } }]}>Slow glow</Button>
```

### `preset` – Apply a Named Project Style

Values: any preset name registered via `<BlocksProvider presets={{...}}>` (project-specific).

Presets are the correct escape hatch when you need a look **outside the semantic intent palette**
(`primary | secondary | success | warning | danger | neutral`) — e.g. a dark translucent overlay
button on top of an image, a brand-colored button, or a "glass" surface. They keep hover/active/
dark-mode logic coherent AND make the custom look reusable across the project.

```svelte
<Button preset="overlay">Reinholen</Button>
<Card preset="glass">...</Card>
```

Registration happens once at the app root — see `Customization` → `Level 2: Presets` below.

**DO NOT** reach for `class="bg-…! hover:bg-…! active:bg-…!"` when the intent palette doesn't fit.
That pattern defeats the component's hover/active/dark-mode cascade and leaks visual decisions
into every call site. Register a preset instead.

### `class` – Additional CSS Classes

Merged with variant classes. Always available on every component.

---

## Component Families

Every component belongs to exactly one of the families in the table below. The family decides ARIA role, tier-system membership, and border-token source. Pick the right family up-front to avoid categorical bugs (button that looks like an input, menu that doubles as a listbox, avatar that mutates when commit-radii flatten).

### Family table

| Family             | Members                                                                                                                                  | ARIA role                                                       | Tier default                                                                                | Border source                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
| Action             | Button, ButtonGroup, Menu, Toolbar, Toggle                                                                                               | `button`, `menu`, `menuitem`, `toolbar`, `switch`               | `commit` (tier-aware)                                                                       | Intent (`border-neutral` etc.)       |
| Form               | Input, Select, Combobox, Textarea, Checkbox, RadioGroup, Slider, FormField                                                               | `textbox`, `listbox`, `combobox`, `checkbox`, `radio`, `slider` | `modify` (tier-aware)                                                                       | Surface (`border-border-subtle`)     |
| Navigation         | Breadcrumb, Pagination, SegmentGroup, Stepper, Tab, JourneyTimeline                                                                      | `navigation`, `tablist`, `tab`                                  | per-component (tier-aware)                                                                  | mixed                                |
| Container          | Card, Alert, Accordion, Collapsible, Dialog, Drawer, Popover, Tooltip, Sidebar, Separator, ConfirmDialog                                 | `dialog`, `tooltip`, `region`, `aside`                          | `contain` (tier-aware)                                                                      | Surface or Hairline                  |
| Feedback / Ambient | Toast, Spinner, Progress, Skeleton, Badge                                                                                                | `status`, `alert`, `progressbar`                                | **not tier-aware** (Badge is the documented edge case)                                      | Intent (status-tinted) or none       |
| Identity           | Avatar                                                                                                                                   | `img` or `button`                                               | **not tier-aware** — own shape axis (`circle` / `rounded` / `square`)                       | none                                 |
| Conversation       | Chat, ChatMessageList, ChatMessage, PromptInput, StreamingMarkdown, CodeBlock, ToolCallCard, ReasoningDisclosure, CitationChip, A2UIView | `log`, `textbox`, `region`                                      | mixed — `bridge` for the bubble, `contain` for the framed blocks, `modify` for the composer | Surface, on the outermost frame only |

### Action — interactive triggers

- ARIA: items dispatch `onSelect` / `onclick`; never hold a value.
- Border: must read as interactive even in `intent="neutral"` — uses Intent tokens (~neutral-500 in light).
- Industry analogue: Radix DropdownMenu, Headless UI Menu.
- Pick `Menu` for one-off action lists; `Button` for single triggers; `ButtonGroup` for grouped triggers; `Toolbar` for free-form bars; `Toggle` for bistable switches.

### Form — value holders

- ARIA: control owns a value, emits `onValueChange` / `bind:value`.
- Border: must read as a container, not a button — uses Surface tokens (~neutral-200 in light).
- Industry analogue: Radix Select / Combobox, Headless UI Listbox / Combobox.
- Pick `Select` for value pickers; `Combobox` for searchable Select; `Select multiple` for multi-select (NOT `Menu multiple`); `Menu` (Action family) for one-off action lists.

### Navigation — section / route selection

- ARIA: `<nav aria-label>`, `role="tablist"` + `role="tab"`, `aria-current` for breadcrumbs / pagination.
- Border: per-component; SegmentGroup indicator uses Intent (active item reads as action-like).
- Pick `Tab` for sectioned content; `SegmentGroup` for inline pickers (holds value, unlike ButtonGroup); `Stepper` for linear progress; `Breadcrumb` for route context; `Pagination` for list paging.

### Container — content surfaces

- ARIA: `<dialog>`, `role="tooltip"`, `<aside>`, `<details>` / `aria-expanded`.
- Border: never Intent in default state — Surface or Hairline. If a container border reads as a button, family mismatch.
- Pick `Card` / `Alert` for in-page surfaces; `Dialog` / `Drawer` / `ConfirmDialog` for modal overlays; `Popover` for anchored floating; `Tooltip` for hover-described inline targets; `Sidebar` for persistent app-shell; `Accordion` / `Collapsible` for disclosure.

### Feedback / Ambient — status communication

- ARIA: `role="alert"`, `role="status"`, `role="progressbar"`. Spinner inherits `aria-busy` from host.
- Tier: NOT tier-aware. Geometry is per-component (e.g. Spinner is always `rounded-full`, Toast is always `rounded-contain`). A wrapping `<Toolbar tier="modify">` does NOT flatten a Toast.
- Badge exception: Badge DOES expose a `tier` prop (`commit` default, `modify` opt-in for inline Toolbar strips) — but the family rule remains: Feedback geometry is per-component, not per-context.
- Pick `Toast` for system notifications; `Alert` for in-page banners; `Spinner` / `Progress` / `Skeleton` for loading states; `Badge` for status tags / counters (see Badge Patterns section for the 5 use cases).

### Identity — Avatar only

- Avatar lives outside the tier system. Its `variant` axis (`circle` / `rounded` / `square`) is identity-shape, not layout-tier. A brand that flattens `--radius-commit` (squared pill buttons) keeps circular avatars.
- Avatar uses no border in its default render; `ring` is the only border-adjacent affordance.

### Conversation — streamed, partially settled content

- ARIA: `role="log"` with `aria-live="off"` on the conversation (token-by-token output would flood a screen reader; a separate polite region announces start and completion once each), a `<textarea>` composer, and a message that is a plain `<div>` carrying `data-role` / `data-status`.
- Tier: three tiers meet in one tree — the bubble is `bridge` (it is content), the framed blocks (`CodeBlock`, `ToolCallCard variant="card"`) are `contain`, the composer is `modify`.
- Border: Surface, and **only the outermost frame draws one** — a block that frames itself inside an already-framed parent stacks outlines at the same radius. `CodeBlock variant="plain"` exists for exactly that case; the parent owns the framing decision, the child owns the content.
- Untrusted content: assistant output never reaches the DOM as markup (no `{@html}`), and every URL is policy-checked before render.
- Industry analogue: Vercel AI SDK UI, `assistant-ui`, Copilot Kit — content that is streamed, partially settled, and not authored by the application.

### Cross-family disambiguation

- `Menu` vs `Select` — Menu for one-off actions (Action), Select for value pickers (Form). Different ARIA, different border family.
- `ButtonGroup` vs `SegmentGroup` — ButtonGroup dispatches actions, SegmentGroup holds a value. If you `bind:value` on a ButtonGroup, switch to SegmentGroup.
- `Sidebar` vs `Drawer` — Sidebar for persistent layout (`<aside>`, no backdrop by default), Drawer for transient modal (`<dialog>`, always backdrop + focus-trap).
- `Popover` vs `Tooltip` — Popover hosts a focus-trapped panel for click-interactions, Tooltip is non-focusable for hover-descriptions.
- `Alert` vs `Toast` — Alert is in-page and announces at the urgency its `intent` implies (`role="alert"` for `danger`/`warning`, `role="status"` otherwise), Toast is system-level + stacking.

### Tier-aware components (read the tier context)

The tier context is a context, not a component: a wrapping container calls `setTierContext()` and a tier-aware component reads it with `getTierContext()`. Seventeen components expose a `tier` prop AND inherit from a wrapping context when it is unset:

| Component      | Default tier | Family     |
| -------------- | ------------ | ---------- |
| Button         | `commit`     | Action     |
| ButtonGroup    | `commit`¹    | Action     |
| Menu           | `commit`     | Action     |
| Toggle         | `commit`     | Action     |
| Badge          | `commit`     | Feedback   |
| SegmentGroup   | `commit`     | Navigation |
| Stepper        | `commit`     | Navigation |
| PaginationItem | `commit`     | Navigation |
| Tab            | `modify`     | Navigation |
| RadioGroup     | `commit`     | Form       |
| Checkbox       | `modify`     | Form       |
| Input          | `modify`     | Form       |
| Select         | `modify`     | Form       |
| Combobox       | `modify`     | Form       |
| Textarea       | `modify`     | Form       |
| PinInput       | `modify`     | Form       |
| TimeInput      | `modify`     | Form       |

¹ `ButtonGroup`'s unset default is `modify` on a **connected vertical** group — a pill cap
domes a stack of text buttons into a lozenge. An explicit `tier`, or a wrapping Toolbar's or
ButtonGroup's context, still wins.

Two components **set** the context: `Toolbar`, which only sets — its own surface is `rounded-contain` and its `tier` prop dresses the controls inside the strip rather than the strip — and `ButtonGroup`, which both sets and reads.

Everything else sits on a fixed tier and never consults the context: Container components are `contain` (only `Card` takes a `tier` prop, with the different values `contain | bridge`), `Slider` and `FormField` sit outside the Form cascade, `Breadcrumb` and `JourneyTimeline` outside the Navigation one, and Feedback / Identity components are not tier-aware at all — `Badge` excepted, above.

---

## Components

---

## A2UIView
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Renders a trusted-catalog A2UI (Agent-to-UI, v0.9.1 `basic`
subset) payload into live, interactive Urbicon components. Fail-loud and
whitelist-only: only the mapped catalog components and their declared props
ever reach the DOM. Unknown components/props, prototype-pollution keys and
function-call bindings are rejected, never rendered, and reported through
`onValidationError` (spec-compatible issues a consumer can relay to the agent
as a `VALIDATION_FAILED` error). Inputs are two-way (typing writes into the
local data model; bound text updates live); actions dispatch a spec-exact
`A2uiActionEvent`. Images and links are gated by the same strict-by-default
`urlPolicy` as StreamingMarkdown. It is NOT a default ChatMessage
renderer, so wire it in per surface via `partRenderers.a2ui` to keep it out of
the base bundle. Generate the agent-side prompt with the shipped
`a2uiSystemPrompt()`; validate a payload without a DOM with
`createA2uiProcessor()`; never hand-roll either. Opt into the richer
Urbicon-native catalog (real intents/variants, Section, RichText, Accordion)
by passing `catalogs={[urbiconA2uiCatalog]}` (tree-shaken out otherwise), and
type-check the data model with an optional `dataSchema`. One view owns the
surfaces of ONE payload; to let an agent patch a surface it sent in an earlier
chat turn (multi-step forms), route the later envelopes into that payload with
`A2uiSurfaceRouter`; never give a second view the same surfaceId.

**Import:** `import { A2UIView } from '@urbicon-ui/blocks';`

### Examples
```svelte
{#snippet a2uiPart(part)}
<A2UIView
payload={part.payload}
streaming={message.status === 'streaming'}
{urlPolicy}
onAction={(event) => sendUserTurn(`[ui-action] ${JSON.stringify(event)}`)}
onValidationError={(issues) => reportToAgent(issues)}
/>
{/snippet}
<ChatMessage {message} {urlPolicy} partRenderers={{ a2ui: a2uiPart }} />
```

```svelte
<A2UIView payload={envelopes} onAction={(e) => console.log(e)} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| payload | `unknown` | yes |  | The A2UI payload. Accepts an array of envelopes (the accumulated JSONL sequence — stream by extending it immutably: `[...prev, envelope]`), a single envelope object, or the golden-file `{ messages: [...] }` wrapper. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class') |
| blockedImageLabel | `string` | no | 'Image blocked' | Chip label shown in place of a policy-blocked image. |
| catalogs | `readonly A2uiCatalog[]` | no |  | Additional A2UI catalogs this view can render, beyond the always-present Basic catalog (which is prepended automatically as the default/fallback). A surface renders through the catalog whose id its `createSurface.catalogId` names. Pass the shipped `urbiconA2uiCatalog` to enable the Urbicon-native catalog. Resolved once at init (icon setup reads context) — keep it referentially stable. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| dataSchema | `A2uiDataSchema` | no |  | Optional surface data schema. When set, every `updateDataModel` write is validated against it (type mismatch on a declared pointer → error; undeclared top-level branch → warning), reported via `onValidationError`. Document the same schema to the agent with `a2uiDataSchemaSection`. Keep it referentially stable. |
| errorTitle | `string` | no | 'Invalid UI payload' | Title of the top-level error Alert for envelope-level faults. |
| onAction | `(event: A2uiActionEvent) => void` | no |  | Fired when a Button is activated, with the spec-exact resolved action event. |
| onValidationError | `(issues: A2uiValidationIssue[]) => void` | no |  | Fired whenever the validation-issue list changes (errors AND warnings, each with a `severity`). Relay error-severity issues to the agent as an A2UI `error` message. |
| pendingLabel | `string` | no | 'Loading UI' | Screen-reader label of the streaming placeholder. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ A2UIView: {...} }}>`. Prefer this over `class` overrides for reusable custom looks. |
| slotClasses | `Partial<Record<A2UIViewSlots, string>>` | no |  | Per-slot class overrides. Slots: `root`, `surface`, `errorList`, `errorChip`, `errorIcon`, `pending`, `column`, `row`, `list`, `listItem`, `heading`, `caption`, `inlineText`, `image`, `blockedChip`, `icon`, `svgIcon`, `choiceGroup`, `choiceLabel`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| streaming | `boolean` | no | false | While true, a reference to a not-yet-defined component renders a placeholder instead of a fault chip (mid-stream tolerance). Flip to false when the stream settles so dangling references become errors. |
| unstyled | `boolean` | no |  | Strip the component's default tv() classes, and those of every catalog component the surface renders (Button, Input, Card …). |
| unsupportedLabel | `string` | no | 'Unsupported component' | Fault-chip label for an unknown/unsupported/incomplete component. |
| urlPolicy | `MarkdownUrlPolicy` | no |  | URL policy for `Image` sources (and Text markdown links). Strict by default: every external image is blocked unless its prefix is allowlisted. Keep the object referentially stable. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'class'> (omit-pattern)

### Types
```ts
interface MarkdownUrlPolicy {
/**
   * Allowed link protocols (with trailing colon). Relative URLs are always
   * allowed for links. @default ['http:', 'https:', 'mailto:', 'tel:']
   */
  allowedLinkProtocols?: string[];
  /**
   * Prefix allowlist for image sources, matched against the normalized
   * absolute URL. Empty (the default) blocks every external image; relative
   * sources are allowed. Prefer deep, specific prefixes — broad ones are
   * open-redirect bait. `data:` images are blocked unless a `data:` prefix
   * is listed explicitly.
   * @default []
   */
  allowedImagePrefixes?: string[];
  /** Observability hook — fires once per blocked URL occurrence. */
  onBlocked?: (kind: 'link' | 'image', url: string) => void;
}
```

```ts
interface A2uiActionEvent {
name: string;
  surfaceId: string;
  sourceComponentId: string;
  /** ISO 8601 timestamp (`new Date().toISOString()`). */
  timestamp: string;
  context: Record<string, unknown>;
  /**
   * The surface's complete data model — present only when the surface was
   * created with `sendDataModel: true`.
   *
   * The spec calls this the client data model and has the client append it to
   * the metadata of every message sent to the agent, but leaves WHERE metadata
   * travels to the transport binding (A2A `metadata`, HTTP headers, …). This
   * field is that payload; put it wherever your transport carries metadata.
   *
   * It is the antidote to a half-filled `context`: the agent sees everything the
   * user entered, including fields it forgot to list on the action.
   */
  dataModel?: unknown;
}
```

```ts
interface A2uiValidationIssue {
severity: A2uiIssueSeverity;
  code: string;
  surfaceId?: string;
  path?: string;
  message: string;
}
```

```ts
interface A2uiCatalog {
Node: Component<A2uiNodeProps>;
  createIcons: () => {
    icons: Readonly<Record<string, IconComponent>>;
    fallbackIcon: IconComponent;
  };

  // ── inherited from A2uiCatalogSpec ──
  /** Catalog id advertised in `createSurface` and matched against incoming surfaces. */
  catalogId: string;
  /** Additional ids that resolve to this catalog (version/back-compat aliases). */
  catalogIdAliases?: readonly string[];
  /** Component name → spec (the single source of truth for validation AND the prompt). */
  registry: Readonly<Record<string, A2uiComponentSpec>>;
  /** Mapped `Icon.name` values; an unmapped name degrades to a fallback glyph. */
  iconNames: readonly string[];
  /** Real catalog components deliberately not rendered (error chip, not "unknown"). */
  unsupportedComponents: ReadonlySet<string>;
  /** Props recognised anywhere but dropped before render (validation warning only). */
  ignoredProps: ReadonlySet<string>;
  /** Component names whose DIRECT children may carry a `weight` (flex-grow). */
  flexContainers: ReadonlySet<string>;
  /** Optional per-component post-validation checks, keyed by component name. */
  componentChecks?: Readonly<Record<string, A2uiComponentCheck>>;
}
```

```ts
type A2uiDataSchema = Readonly<Record<string, A2uiSchemaField>>
```

```ts
type A2uiIssueSeverity = 'error' | 'warning'
```

```ts
type IconComponent = Component<IconProps>
```

```ts
interface A2uiSchemaField {
type: A2uiSchemaType;
  /** Agent-facing description; emitted into the prompt verbatim. */
  description?: string;
  /** Allowed literal values (documented + enforced for string/number fields). */
  enum?: readonly (string | number)[];
  /** A format hint (e.g. `date`, `time`, `email`) — documented, not enforced in v1. */
  format?: string;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
interface A2uiRenderNode {
key: string;
  id: string;
  instance: A2uiComponentInstance | null;
  /** Template-item scope for relative-path resolution and two-way write-back. */
  scopePrefix: string | undefined;
  children: A2uiRenderNode[];
  /** flex-grow, present only when this node is a direct Row/Column child with a finite `weight`. */
  weight?: number;
  /**
   * The parent prop this child came from (e.g. Card `header`/`footer`/`child`).
   * Lets a dispatcher with several named childId slots pick the right child by
   * name instead of position; single-slot / list components ignore it.
   */
  slot?: string;
}
```

- `interface A2uiRenderContext` — 15 members, definition omitted (45 lines; full definition: packages/blocks/src/lib/components/Chat/A2UIView/a2ui-render.ts)

```ts
type A2uiSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object'
```

---

## Accordion
Collapsible content sections with expand/collapse animation.
Supports single or multiple open items, keyboard navigation, and ARIA accordion pattern.

**Import:** `import { Accordion } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Accordion>
  <AccordionItem value="faq-1" title="What is Urbicon UI?">
    A Svelte 5 component library with built-in i18n and design tokens.
  </AccordionItem>
  <AccordionItem value="faq-2" title="How does dark mode work?">
    Semantic tokens automatically handle light/dark via the CSS light-dark() function.
  </AccordionItem>
</Accordion>
```

```svelte
<Accordion type="multiple" variant="card" bind:value={openItems}>
  <AccordionItem value="section-1" title="Section 1">Content</AccordionItem>
  <AccordionItem value="section-2" title="Section 2">Content</AccordionItem>
</Accordion>
```

### Variants
- variant: card, default, ghost (default: default)
- size: lg, md, sm (default: md)
- expanded: false, true

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Accordion items |
| ...AccordionVariants | `VariantProps` | no |  | Styling variants from AccordionVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Custom CSS class. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| collapsible | `boolean` | no | true | Whether items can be fully collapsed |
| defaultValue | `string | string[]` | no |  | Default open item(s) |
| disabled | `boolean` | no | false | Disable all items |
| onValueChange | `(value: string | string[]) => void` | no |  | Callback when open items change |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Accordion: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size |
| slotClasses | `Partial<Record<AccordionSlots, string>>` | no |  | Per-slot class overrides, accordion-wide: the item slots (item | trigger | chevron | content | contentInner) apply to every AccordionItem; an item's own slotClasses win their bucket. Slots: base | item | trigger | chevron | content | contentInner. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| transitionDuration | `number` | no |  | Override every item's expand/collapse animation duration in milliseconds. Defaults to the `--blocks-collapse-duration` token (the `normal` 250ms). Respects `prefers-reduced-motion`. |
| transitionEasing | `string` | no |  | Override every item's expand/collapse easing as a CSS `<easing-function>` — e.g. `'ease-in-out'`, `'cubic-bezier(0.4,0,0.2,1)'`, or a token like `'var(--blocks-ease-springy)'`. Defaults to the `--blocks-collapse-easing` token. (A CSS string, not the `(t) => number` easing function the overlay components take — Accordion animates via CSS.) |
| type | `'single' | 'multiple'` | no | 'single' | Allow single or multiple items open at once |
| unstyled | `boolean` | no |  | Remove default styles |
| value | `string | string[]` | no |  | Controlled open item(s) – string for single, string[] for multiple |
| variant | `'default' | 'card' | 'ghost'` | no | 'default' | Visual style |
| expanded | `'false' | 'true'` | no |  | Controls the expanded behavior and appearance of the Accordion component. Available options: false, true. |

Inherited from:
- AccordionVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface AccordionContext {
toggle: (value: string) => void;
  isOpen: (value: string) => boolean;
  variant: AccordionVariants['variant'];
  size: AccordionVariants['size'];
  disabled: boolean;
  /**
   * The accordion-level slotClasses, shared with every item. The Accordion
   * prop TYPE always declared the item slots (trigger, contentInner, …), but
   * only `base` ever reached the DOM — an accordion-wide
   * `slotClasses={{ trigger: 'px-4' }}` was a type-checked no-op until
   * 2026-08-16. Item-own slotClasses merge after these and win their bucket.
   */
  readonly slotClasses: Partial<Record<Exclude<AccordionSlots, 'base'>, string>> | undefined;
}
```

### Slots (slotClasses keys)
`base`, `item`, `trigger`, `chevron`, `content`, `contentInner`

---

## AccountSettings
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Self-service account-settings panel: change name, email and
password, and delete the account. Each section talks to `apiPath` (default
`/api/auth/account`); pair them with the server handlers
`createUpdateProfileHandler`, `createChangeEmailHandler`,
`createChangePasswordHandler` and `createDeleteAccountHandler`. The new-password
field gates against the server's policy, read from `policyPath`
(`createPasswordPolicyHandler`).

**Import:** `import { AccountSettings } from '@urbicon-ui/auth';`

### Examples
```svelte
<AccountSettings {user} onProfileUpdated={(u) => (auth.user = u)} onDeleted={() => goto('/')} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| user | `AuthUser | null` | yes |  | The current authenticated user: its `name` pre-fills the profile field and its `email` is shown as the current address. Pass `locals.user` / your auth store's user. While `null` nothing renders. |
| apiPath | `string` | no | '/api/auth/account' | API base path for the account endpoints. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| onDeleted | `() => void` | no |  | Called after the account has been deleted (e.g. redirect to a goodbye page). |
| onProfileUpdated | `(user: AuthUser) => void` | no |  | Called with the refreshed user after a successful profile change (update your store here). |
| passwordPolicy | `PasswordPolicy` | no |  | The password policy the new-password field gates against, when you already have it server-side (`resolvePasswordPolicy(config.password)`). Supplying it skips the `policyPath` request. |
| policyPath | `string | null` | no | '/api/auth/password-policy' | Endpoint serving `createPasswordPolicyHandler`, read once on mount so the checklist and the submit gate match what the server enforces. `null` disables the request and falls back to the package defaults (min 8, no character classes). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ AccountSettings: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| showRequirements | `boolean` | no | true | Show the real-time password requirements checklist under the new password. |
| slotClasses | `Partial<Record<'root' | 'title' | 'section' | 'sectionTitle' | 'field' | 'requirements' | 'submit' | 'danger', string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface PasswordPolicy {
/** Minimum length. @default 8 */
  minLength: number;
  /** Require at least one `A-Z`. @default false */
  requireUppercase: boolean;
  /** Require at least one `a-z`. @default false */
  requireLowercase: boolean;
  /** Require at least one `0-9`. @default false */
  requireDigit: boolean;
  /** Require at least one character outside `A-Za-z0-9`. @default false */
  requireSpecial: boolean;
}
```

```ts
interface AuthUser {
id: string;
  email: string;
  name: string;
  role: R;
  emailVerified: boolean;
  /**
   * Whether TOTP two-factor authentication is active on the account. A public
   * account-status flag in the same spirit as `emailVerified` — it drives the
   * `TwoFactorManager` UI and the login two-step, and never carries the secret
   * itself. `false` for every user until they finish 2FA setup, and for
   * consumers who don't wire 2FA at all (the adapter defaults a missing column
   * to `false`).
   */
  totpEnabled: boolean;
}
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`, `title`, `section`, `sectionTitle`, `field`, `requirements`, `submit`, `danger`

---

## Alert
Persistent inline notification for communicating status, warnings, errors,
or informational messages. Supports icons, titles, descriptions, actions, and dismissal.
The announced live-region role follows `intent`: `danger` and `warning` render
`role="alert"` (implicitly assertive — it interrupts whatever a screen reader is saying),
every other intent renders `role="status"` (polite). An explicit `role` always wins —
pass `role="alert"` where a success or info message must interrupt, `role="note"` for a
static callout that announces nothing, and `role={undefined}` to drop the attribute when
the Alert already sits inside a live region of its own.

**Import:** `import { Alert } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Alert intent="success" title="Saved successfully">
  Your changes have been saved.
</Alert>
```

```svelte
<Alert intent="danger" variant="inline" dismissible onDismiss={() => (visible = false)}>
  {#snippet icon()}<AlertCircleIcon size={20} />{/snippet}
  Something went wrong. Please try again.
  {#snippet actions()}<Button size="sm" variant="ghost">Retry</Button>{/snippet}
</Alert>
```

### Variants
- intent: danger, info, neutral, primary, success, warning (default: primary)
- variant: filled, inline, soft (default: soft)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...AlertVariants | `VariantProps` | no |  | Styling variants from AlertVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'title' | 'children') |
| actions | `Snippet` | no |  | Action buttons snippet |
| children | `Snippet` | no |  | Description content (children slot) |
| class | `string` | no |  | Custom CSS class. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| dismissible | `boolean` | no | false | Show dismiss/close button |
| icon | `Snippet` | no |  | Custom icon snippet (replaces default intent icon) |
| intent | `'primary' | 'info' | 'success' | 'warning' | 'danger' | 'neutral'` | no | 'primary' | Semantic color intent — and the announced urgency with it: `danger` and `warning` render `role="alert"` (assertive), every other intent `role="status"` (polite). An explicit `role` overrides the derived one. |
| onDismiss | `() => void` | no |  | Callback when dismissed |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Alert: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size |
| slotClasses | `Partial<Record<AlertSlots, string>>` | no |  | Per-slot class overrides. Slots: base | icon | content | title | description | actions | dismissButton. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| title | `string` | no |  | Alert title (bold header text) |
| unstyled | `boolean` | no |  | Remove default styles |
| variant | `'soft' | 'inline' | 'filled'` | no | 'soft' | Visual style |

Inherited from:
- AlertVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> (omit-pattern)

### Slots (slotClasses keys)
`base`, `icon`, `content`, `title`, `description`, `actions`, `dismissButton`

---

## ApiReference
Structured API reference table for component documentation.
Renders props via `@urbicon-ui/table` with per-column cell snippets
and `Badge` indicators for source/required status.

**Import:** `import { ApiReference } from '@urbicon-ui/docs';`

### Examples
```svelte
<ApiReference props={componentData.props} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| props | `ApiProp[]` | yes |  | Array of prop definitions to display. |
| ...ApiReferenceVariantProps | `VariantProps` | no |  | Styling variants from ApiReferenceVariantProps |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| slotClasses | `Partial<Record<ApiReferenceSlots, string>>` | no |  | Per-slot class overrides for the wrapper elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| types | `Array<{ name: string }>` | no |  | Type entries rendered by a `TypesReference` **on the same page** — pass the same array you pass to `<TypesReference types={…} />`.  Type names in the Type column that exactly match an entry become in-page links to it. Omit this (the default) and the column stays plain text: linking is opt-in precisely because a link is only correct when the target is actually on the page. |
| unstyled | `boolean` | no | false | Remove all default tv styles from the wrapper and cell content. |
| usageNotes | `Snippet` | no |  | Optional usage notes rendered below the table. |

Inherited from:
- ApiReferenceVariantProps (external)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
interface ApiProp {
name: string;
  type: string;
  required?: boolean;
  defaultValue?: string;
  description?: string;
  /**
   * A navigable `@see` target — absolute URL, route-relative path
   * (`/blocks/primitives/button#variants`) or bare fragment (`#type-Foo`).
   * Rendered as a link wrapping the prop's type.
   */
  seeAlso?: string;
  /**
   * Prose `@see` references (bare type/member names such as
   * `HTMLButtonAttributes.value`). They have no doc URL, so they render as
   * literal text under the description instead of as a link.
   */
  seeAlsoRefs?: string[];
  values?: string[];
  /**
   * `@deprecated` on the prop's JSDoc. The message carries the replacement and
   * is the whole point of the tag — a badge alone would say "don't", not "use
   * what instead", so it renders in the expanded row as well.
   */
  deprecated?: { message: string; since?: string; alternative?: string };
  /** `@experimental` on the prop's JSDoc — the prop moves while its component holds still. */
  experimental?: boolean;
  source?: {
    type: 'direct' | 'variant' | 'inherited';
    name?: string;
    package?: string;
    url?: string;
  };
}
```

### Slots (slotClasses keys)
`base`, `stats`, `requiredCount`, `nameCell`, `typeChips`, `nameCode`, `deprecatedCode`, `spreadCode`, `typeCode`, `typeChip`, `defaultCode`, `description`, `deprecationNote`, `descriptionClamped`, `expandedPanel`, `signature`, `sourceSection`, `sourceName`, `sourceLink`, `valuesSection`, `seeAlsoRefs`, `seeAlsoRef`, `placeholder`, `link`, `typeLink`, `highlightRing`, `usageNotes`

---

## AreaChart
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Area chart for trends with volume emphasis — filled regions
under each series, optionally stacked. Zero-dependency SVG on the design-
token palette, responsive, dark-mode aware, with a screen-reader data-table
fallback.

**Import:** `import { AreaChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<AreaChart
  stacked
  data={[
    { label: 'Jan', values: [4, 6] },
    { label: 'Feb', values: [7, 3] }
  ]}
  series={[{ label: 'New' }, { label: 'Returning' }]}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `CartesianDatum[]` | yes |  | Ordered categories with per-series values. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| fillOpacity | `number` | no | 0.2 (overlay) / 0.85 (stacked) | Opacity of the area fill (0–1). |
| formatValue | `(value: number) => string` | no |  | Format values for axis labels, tooltips, and the data table. |
| height | `number` | no | 240 | SVG height in px. |
| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
| margin | `ChartMargin` | no |  | Plot margins; merged over the defaults. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| series | `ChartSeries[]` | no |  | Series metadata (labels + colors); defaults to one per value column. |
| showGrid | `boolean` | no | true | Render horizontal gridlines. |
| showLegend | `boolean` | no | true | Show the series legend (only renders with >1 series). |
| slotClasses | `AreaChartSlotClasses` | no |  | Per-slot class overrides. A series is drawn as two paths and `mark` lands on both of them, so a utility that sets a paint there reaches both: `fill-*` fills the top edge's open polyline, `stroke-*` outlines the band. Use `area` for the filled band alone and `areaOutline` for its top edge alone; each is folded against `mark` rather than appended to it, so an entry there wins its Tailwind bucket outright instead of by stylesheet order. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| stacked | `boolean` | no | false | Stack series cumulatively instead of overlaying them. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px; omit for responsive width. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
type AreaChartSlotClasses = Partial<Record<AreaChartSlot, string>>
```

```ts
interface CartesianDatum {
/** Category label rendered on the x-axis. */
  label: string;
  /** Values in series order; missing entries are treated as 0. */
  values: number[];
}
```

```ts
interface ChartMargin {
top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}
```

```ts
interface ChartSeries {
/** Legend + tooltip label. */
  label: string;
  /** Explicit color; defaults to the cycled categorical palette. */
  color?: string;
}
```

```ts
type AreaChartSlot = (typeof AREA_CHART_SLOTS)[number]
```

---

## Avatar
User profile image component with fallback initials, multiple sizes, and interactive states.

**Import:** `import { Avatar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Avatar src="/user-photo.jpg" name="John Doe" size="lg" />
```

```svelte
<Avatar name="Jane Smith" randomColor clickable onclick={() => showProfile()} />
```

```svelte
<Avatar name="Ada Lovelace" status="online" pulse />
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- variant: circle, rounded, square (default: circle)
- size: 2xl, lg, md, sm, xl, xs (default: md)
- interactive: true (default: false)
- pulse: true (default: false)
- ring: true (default: false)
- ringIntent: danger, neutral, primary, secondary, success, warning (default: primary)
- status: away, busy, offline, online
- statusPosition: bottom-left, bottom-right, top-left, top-right (default: bottom-right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...AvatarVariants | `VariantProps` | no |  | Styling variants from AvatarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| alt | `string` | no |  | Alt text for the image. Defaults to `name`. |
| children | `Snippet` | no |  | Custom fallback content rendered instead of auto-generated initials. Useful for overflow counters, icons, or fully custom avatars with `unstyled`. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clickable | `boolean` | no |  | Mark the avatar as clickable (adds hover/focus styles and keyboard support). Alias for the `interactive` variant. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the avatar. Only applies while interactive (`clickable`, `interactive`, or `onclick`). |
| name | `string` | no |  | Full user name — used for initials generation, `randomColor` hashing, and `aria-label`. |
| onclick | `(event: MouseEvent) => void` | no |  | Click handler. Automatically enables interactive styles. |
| onHover | `(hovered: boolean) => void` | no |  | Called when the hover state changes. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Avatar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| randomColor | `boolean` | no |  | Derive a deterministic background color from `name`. The same name always produces the same color, making it easy to visually distinguish users without images. Overrides `intent`. Picks from the 12-slot identity palette (`--color-avatar-1` … `--color-avatar-12`), which resolves light/dark automatically — override those tokens to rebrand it. Without a `name` there is no identity to encode, so the avatar keeps its neutral background. |
| ringColor | `string` | no |  | Custom ring color (CSS value). Overrides `ringIntent` when set. |
| slotClasses | `Partial<Record<AvatarSlots, string>>` | no |  | Per-slot class overrides merged with tv styles. Slots: base | frame | image | fallback | status. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| src | `string` | no |  | Image URL. Falls back to initials or `children` when empty or on load error. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Avatar. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| variant | `'circle' | 'rounded' | 'square'` | no | circle | Controls the visual style and presentation of the Avatar. Determines the component's visual treatment. Available options: circle, rounded, square. |
| size | `'2xl' | 'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Avatar. Affects the component's physical footprint. Available options: 2xl, lg, md, and 3 more. |
| interactive | `'true'` | no | false | Controls the interactive behavior and appearance of the Avatar component. Available options: true. |
| pulse | `'true'` | no | false | Controls the pulse behavior and appearance of the Avatar component. Available options: true. |
| ring | `'true'` | no | false | Controls the ring behavior and appearance of the Avatar component. Available options: true. |
| ringIntent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the ringIntent behavior and appearance of the Avatar component. Available options: danger, neutral, primary, and 3 more. |
| status | `'away' | 'busy' | 'offline' | 'online'` | no |  | Controls the status behavior and appearance of the Avatar component. Available options: away, busy, offline, online. |
| statusPosition | `'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'` | no | bottom-right | Controls the statusPosition behavior and appearance of the Avatar component. Available options: bottom-left, bottom-right, top-left, top-right. |

Inherited from:
- AvatarVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `frame`, `image`, `fallback`, `status`

---

## AvatarGroup
Stacks avatars into an overlapping row with an optional "+N" overflow chip,
for a set of collaborators, assignees or participants. Pass an `items` array of Avatar
props; a shared `size` and a cut-out ring apply to every avatar so the stack reads cleanly
on any background.

**Import:** `import { AvatarGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<AvatarGroup items={[{ name: 'Ada Lovelace' }, { name: 'Alan Turing' }]} />
```

```svelte
<AvatarGroup items={team} max={4} size="lg" />
```

### Variants
- spacing: loose, normal, tight (default: normal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `AvatarProps[]` | yes |  | The avatars to stack. Each entry is a full set of Avatar props (src, name, status, …). |
| ...AvatarGroupVariants | `VariantProps` | no |  | Styling variants from AvatarGroupVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| borderColor | `string` | no | 'var(--color-surface-base)' | Ring colour drawn around each avatar so the overlap reads as a cut-out. Any CSS colour; defaults to the base background so the stack looks punched out of the page. |
| class | `string` | no |  | Additional CSS class merged onto the root row. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| max | `number` | no |  | Maximum avatars to render. When `items` exceeds it, `max - 1` avatars are shown plus a single "+N" overflow chip (N is the count of hidden avatars), so the total rendered count is exactly `max`. Unset (or `0`/negative) shows every avatar with no chip; use `≥ 2` so the chip sits alongside at least one visible face. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ AvatarGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic palette. |
| size | `AvatarProps['size']` | no |  | Shared size applied to every avatar and the overflow chip. One of xs, sm, md (default), lg, xl, 2xl. |
| slotClasses | `Partial<Record<AvatarGroupSlots, string>>` | no |  | Per-slot class overrides. Slots: base | overflow. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| spacing | `'tight' | 'normal' | 'loose'` | no |  | Overlap amount between avatars: tight, normal (default), loose. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with slotClasses to rebuild from scratch. |

Inherited from:
- AvatarGroupVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

### Slots (slotClasses keys)
`base`, `overflow`

---

## Badge
Compact label for status, categories, counters, and notifications.

Badge props are a discriminated union. The pure-indicator dot — spelled
canonically as `purpose="dot"` or via the deprecated `variant="dot"` —
forbids `children` / `counter` / `removable` / `interactive` / `onRemove`
at the type level, while the label arms (`filled` / `outlined` / `soft`;
`purpose` `status` / `tag` / `counter` / `chip`) accept the full surface.
A badge with an `onclick` handler is announced as a `button` and joins the
tab order. A static one takes its role from `purpose`: `status` and `dot`
are a `status` live region; `tag`, `counter` and `chip` carry no role and
render a plain span, so a tag inside a link is a label and not a live region;
without `purpose` it stays a `status`. Override via `role`. Its accessible
name is always the visible label; a removable badge's ✕ control names itself
("Remove badge").
Takes no `href`. A link that should look like a Badge is an `<a>` with `badgeVariants({ … }).base()` on it — the recipe in `urbicon primer` under "A link that looks like a button".

**Import:** `import { Badge } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Badge purpose="status" intent="success">Active</Badge>
<Badge purpose="counter" intent="danger">5</Badge>
<Badge purpose="chip" removable onRemove={() => removeTag('react')}>React</Badge>
<Badge purpose="dot" intent="warning" />
```

```svelte
<div class="relative">
<Button>Notifications</Button>
<Badge purpose="counter" intent="danger" placement="top-end" border>5</Badge>
</div>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- variant: dot, filled, outlined, soft (default: filled)
- size: lg, md, sm, xs (default: md)
- border: true (default: false)
- counter: true (default: false)
- disabled: true (default: false)
- interactive: true (default: false)
- placement: bottom, bottom-end, bottom-start, left, right, top, top-end, top-start
- pulse: true (default: false)
- removable: true (default: false)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| purpose | `'dot'` | yes |  | The canonical dot spelling — forces the pure-indicator look regardless of `variant`. For the label roles use `status` / `tag` / `counter` / `chip` (their own arm). |
| border | `boolean` | no |  | Add a ring outline in the page background color — useful to visually separate overlapping or positioned badges from their parent. |
| children | `Snippet` | no |  | Badge content (text, icons, numbers). |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| counter | `boolean` | no |  | Display as a compact pill for numeric counts (tightens padding, tabular-nums). Keeps the pre-`purpose` ARIA default with the rest of the low-level props: a badge driven by this boolean stays a `"status"` live region, where `purpose="counter"` carries no role. A count that must be announced when it changes sets `role="status"` explicitly. |
| disabled | `boolean` | no |  | Visually disable the badge (reduced opacity, no pointer events). |
| interactive | `boolean` | no |  | Enable the interactive look (pointer cursor, hover/press scale, mint). Automatically enabled when `onclick` is provided — and only the handler makes the badge a tab stop with Enter/Space activation; `interactive` alone never creates a focus stop that answers no key. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the badge. Only applies while interactive (`purpose="chip"`, `interactive`, or `onclick`) and not disabled. |
| onclick | `(event: MouseEvent) => void` | no |  | Click handler. Makes the badge operable: interactive styles, a tab stop, Enter/Space activation and `role="button"`. |
| onHover | `(hovered: boolean) => void` | no |  | Called when the hover state changes. |
| onRemove | `() => void` | no |  | Fired when the remove button is clicked (only when `removable` is true). |
| placement | `BadgePlacement` | no |  | Anchor the badge absolutely within a `position: relative` parent. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Badge: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| pulse | `boolean` | no |  | Add a pulsing animation to draw attention (e.g. for live indicators). Stilled under `prefers-reduced-motion`. |
| removable | `boolean` | no |  | Show a remove (×) button. |
| role | `'status' | 'alert' | 'button'` | no |  | ARIA role. Derived from `purpose` when unset: `status` and `dot` render `"status"` — a polite live region, right for a state marker; `tag`, `counter` and `chip` render no role — a category, a count or a filter chip announces nothing when it changes, so it stays a plain `span`: a label inside a link rather than a live region inside one. A badge with an `onclick` handler (when not `disabled`) is a `"button"` whatever its purpose, so assistive tech announces its activation semantics; `purpose="chip"` or `interactive` alone change only the look — without a handler there is nothing to activate, so no button is announced and the badge stays outside the tab order. Without `purpose` a static badge keeps `"status"`, and so does the deprecated `counter` boolean. Set explicitly to override: `"status"` for a count that must be announced when it changes, `"alert"` for a time-sensitive notification. An explicit value always wins over the derived default. |
| slotClasses | `Partial<Record<BadgeSlots, string>>` | no |  | Per-slot class overrides merged with tv styles. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| variant | `'filled' | 'outlined' | 'soft'` | no | 'filled' | Visual variant. `dot` renders a pure indicator (content hidden); the label variants accept the full surface. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Badge. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Badge. Affects the component's physical footprint. Available options: lg, md, sm, xs. |
| tier | `'commit' | 'modify'` | no | commit | Selects the semantic radius tier of the Badge — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

### Types
```ts
type BadgeProps = BadgeDotByPurposeProps | BadgeDotProps | BadgeStandardProps
```

```ts
type BadgePlacement = (typeof PLACEMENT_VALUES)[number]
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `content`, `removeButton`, `removeIcon`

---

## BarChart
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Categorical bar chart — single, grouped, or stacked. Zero-
dependency SVG rendering on the design-token chart palette, responsive via
ResizeObserver, dark-mode aware, with a screen-reader data-table fallback.

**Import:** `import { BarChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<BarChart
  data={[
    { label: 'Q1', values: [12, 8] },
    { label: 'Q2', values: [19, 11] }
  ]}
  series={[{ label: 'Revenue' }, { label: 'Cost' }]}
  formatValue={(v) => `${v}k`}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `BarChartDatum[]` | yes |  | Categories with per-series values. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| formatValue | `(value: number) => string` | no |  | Format values for axis labels, tooltips, and the data table. |
| height | `number` | no | 240 | SVG height in px. |
| locale | `string` | no |  | BCP-47 locale for the default number formatter (when no `formatValue`). |
| margin | `ChartMargin` | no |  | Plot margins; merged over the defaults. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| series | `ChartSeries[]` | no |  | Series metadata (labels + colors). Defaults to one generic series per value column found in `data`. |
| showGrid | `boolean` | no | true | Render horizontal gridlines. |
| showLegend | `boolean` | no | true | Show the series legend (only renders with >1 series). |
| slotClasses | `BarChartSlotClasses` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| stacked | `boolean` | no | false | Stack series instead of grouping them side by side. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px; omit for responsive width. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
type BarChartDatum = CartesianDatum
```

```ts
type BarChartSlotClasses = Partial<Record<BarChartSlot, string>>
```

```ts
interface CartesianDatum {
/** Category label rendered on the x-axis. */
  label: string;
  /** Values in series order; missing entries are treated as 0. */
  values: number[];
}
```

```ts
interface ChartMargin {
top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}
```

```ts
interface ChartSeries {
/** Legend + tooltip label. */
  label: string;
  /** Explicit color; defaults to the cycled categorical palette. */
  color?: string;
}
```

```ts
type BarChartSlot = (typeof BAR_CHART_SLOTS)[number]
```

---

## Breadcrumb
Navigation aid showing the current page's location in a hierarchy.
Renders an accessible nav with structured items and customizable separators.

**Import:** `import { Breadcrumb } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Breadcrumb items={[
  { label: 'Home', href: '/' },
  { label: 'Products', href: '/products' },
  { label: 'Widget' }
]} />
```

```svelte
<Breadcrumb items={breadcrumbs} size="sm">
  {#snippet separator()}<ChevronRightIcon size={14} />{/snippet}
</Breadcrumb>
```

```svelte
<Breadcrumb items={deepTrail} maxItems={4} />
```

```svelte
<Breadcrumb items={[
{ label: 'Home', href: '/', icon: HomeIcon },
{ label: 'Settings' }
]} />
```

### Variants
- size: lg, md, sm (default: md)
- wrap: false, true (default: true)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `BreadcrumbItem[]` | yes |  | Ordered breadcrumb items (last item is current page) |
| ...BreadcrumbVariants | `VariantProps` | no |  | Styling variants from BreadcrumbVariants |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| aria-label | `string` | no |  | Accessible label for the nav element. Defaults to the localized `accessibility.breadcrumb`. |
| class | `string` | no |  | Custom CSS class. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| expandLabel | `string` | no |  | Accessible label for the "…" button that expands a collapsed trail. Defaults to the localized `accessibility.breadcrumbExpand`. |
| itemsAfterCollapse | `number` | no | 1 | Trailing items kept visible when collapsed; the current page is always included. |
| itemsBeforeCollapse | `number` | no | 1 | Leading items kept visible when collapsed. |
| maxItems | `number` | no |  | Collapse the trail when it has more than this many items: the middle items fold into a single "…" button that expands the full trail on click. The first `itemsBeforeCollapse` and last `itemsAfterCollapse` items stay visible (the current page is always kept). Omit to never collapse. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Breadcrumb: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| separator | `Snippet` | no |  | Custom separator snippet (default: "/") |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size |
| slotClasses | `Partial<Record<BreadcrumbSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove default styles |
| wrap | `boolean` | no | true | Let the trail wrap onto multiple lines (`true`, default) or keep it on a single line where the current page truncates and the ancestor links hold their width (`false`). Use `false` for tight single-line bars such as a sticky header or toolbar. |

Inherited from:
- BreadcrumbVariants (external)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
interface BreadcrumbItem {
/** Display label */
  label: string;
  /**
   * Leading icon rendered before the label, inside the crumb's own link (or
   * inside the current-page span for the last item). Pass the icon *component*
   * — `import { HomeIcon } from '@urbicon-ui/blocks'` — never an icon name: a
   * name has to be resolved through the registry at runtime, and that dynamic
   * lookup drags all 315 icons into the consumer bundle (see
   * docs/ICON-DESIGN.md). Decorative by contract — the icon is wrapped in an
   * `aria-hidden` span, so the crumb still announces as its `label` alone.
   * Give an icon-led crumb an `aria-label` if its `label` is too terse to
   * stand on its own.
   */
  icon?: IconComponent;
  /** Navigation URL (omit for current page) */
  href?: string;
  /**
   * Click handler. Use alongside or instead of `href` when navigation
   * happens through a client-side router or shouldn't follow the link
   * (e.g. demos with non-existent routes — call `event.preventDefault()`).
   */
  onclick?: (event: MouseEvent) => void;
  /**
   * Accessible name override for this crumb, replacing `label` for assistive
   * technology.
   *
   * On a linked crumb this is an `aria-label` on the `<a>`, which every
   * implementation honours. On the current page it rides on a generic element,
   * and implementations disagree there: Chrome computes the name, while a
   * strict ARIA 1.2 reading ignores an author name on `generic` and falls back
   * to the content. So give an icon-led last crumb a real `label` rather than
   * relying on the override alone.
   */
  'aria-label'?: string;
}
```

```ts
type IconComponent = Component<IconProps>
```

### Slots (slotClasses keys)
`nav`, `list`, `item`, `link`, `currentPage`, `icon`, `ellipsis`, `separator`

---

## Button
Versatile button component with multiple variants, sizes, intents, and micro-interaction patterns.
Built with Svelte 5 and optimized for performance and accessibility.
Takes no `href`. A link that should look like a Button is an `<a>` with `buttonVariants({ … }).base()` on it — the recipe in `urbicon primer` under "A link that looks like a button".

**Import:** `import { Button } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Button variant="filled" intent="primary" size="md">
  Click me
</Button>
```

```svelte
<Button variant="outlined" intent="danger" mint={['shake', 'ripple']}>
  Delete Item
</Button>
```

```svelte
<!-- Register once at app root: -->
<BlocksProvider
presets={{
Button: {
overlay: {
slotClasses: {
 base: 'bg-black/20 hover:bg-black/30 active:bg-black/40 text-white border-transparent'
}
}
}
}}
>
<Button preset="overlay">Reinholen</Button>
</BlocksProvider>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- variant: filled, ghost, outlined, text (default: filled)
- size: 2xs, lg, md, sm, xl, xs (default: md)
- active: false, true (default: false)
- buttonGroupConnected: true
- loading: false, true (default: false)
- loadingPlacement: end, overlay, start (default: start)
- pressed: true (default: false)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...ButtonVariants | `VariantProps` | no |  | Styling variants from ButtonVariants |
| ...HTMLButtonAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| active | `boolean` | no | false | Whether the button is visually active/selected (e.g. in a ButtonGroup with selection). Unlike `pressed` (momentary feedback), `active` represents a persistent selected state. |
| children | `Snippet` | no |  | The content of the button |
| class | `string` | no |  | Custom CSS class name. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | Whether the button is disabled |
| loading | `boolean` | no | false | Whether the button is in a loading state |
| loadingPlacement | `'overlay' | 'start' | 'end'` | no | 'overlay' | Where the loading indicator should appear when loading is true - 'overlay': spinner overlays content and hides it (default) - 'start': spinner appears before the content - 'end': spinner appears after the content |
| mint | `MintProp` | no | 'scale' | Micro-interaction preset applied to the button. Only applies while the button is neither disabled nor loading. Inside a ButtonGroup, the group's `mint` always wins over this prop.  `mint="none"` also flattens the press sink — the dip under a held pointer — leaving a button that reacts in colour and depth but never moves. Every ButtonGroup renders its children that way by default (its own `mint` defaults to `'none'` and wins over this prop), which is what keeps a connected group's shared seam still on click; it is also what a large or full-width trigger row wants, where the dip reads as a wobble. |
| onclick | `(event: MouseEvent) => void` | no |  | Click handler |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Button: {...} }}>`. Prefer this over `class="bg-…!"` overrides when the requested look is outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| pressed | `boolean` | no | false | Whether the button is pressed (for toggle buttons) |
| slotClasses | `Partial<Record<ButtonSlots, string>>` | no |  | Per-slot class overrides merged with tv styles. Slots: base | content | spinner. A button never shrinks below its label and never clips it; to truncate a long label instead, let the button shrink (`class="min-w-0"`) and wrap the label in a block that clips it: `<span class="block truncate">…</span>`. Not `slotClasses={{ content: 'truncate' }}` — the content slot is a flex row, and `text-overflow` paints its ellipsis only on a block container. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Remove the default variant classes and apply yours instead. Not an empty element: the `blocks-*` hooks stay on the root (`blocks-button`, `blocks-intent-*`) so a stylesheet can still reach the button — see ARCHITECTURE.md § The override cascade. |
| value | `string` | no |  | The value associated with the button (useful in ButtonGroups) |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Button. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| variant | `'filled' | 'ghost' | 'outlined' | 'text'` | no | filled | Controls the visual style and presentation of the Button. Determines the component's visual treatment. Available options: filled, ghost, outlined, text. |
| size | `'2xs' | 'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Button. Affects the component's physical footprint. Available options: 2xs, lg, md, and 3 more. |
| buttonGroupConnected | `'true'` | no |  | Controls the buttonGroupConnected behavior and appearance of the Button component. Available options: true. |
| tier | `'commit' | 'modify'` | no | commit | Selects the semantic radius tier of the Button — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

Inherited from:
- ButtonVariants (external)
- Omit<HTMLButtonAttributes, 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `content`, `spinner`

---

## ButtonGroup
Groups related buttons with shared styling, layout, and optional selection behaviour.
Supports single-select (radio), multi-select (checkbox), or no selection.
Note the default `variant` is `outlined`, not `filled` as on a lone Button: a connected group
with a selected state reads as a segmented control, which needs an outline to sit in and a
filled active segment to stand out — three filled buttons side by side carry no hierarchy.
Pass `variant="filled"` explicitly for a row of equally weighted actions.

**Import:** `import { ButtonGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ButtonGroup selection="single" bind:value={selectedView}>
  <Button value="list">List</Button>
  <Button value="grid">Grid</Button>
</ButtonGroup>
```

```svelte
<ButtonGroup
  selection="multiple"
  bind:value={selectedFormats}
  connected
  size="sm"
  variant="outlined"
>
  <Button value="bold">B</Button>
  <Button value="italic">I</Button>
  <Button value="underline">U</Button>
</ButtonGroup>
```

### Variants
- connected: false, true (default: true)
- disabled: true (default: false)
- orientation: horizontal, vertical (default: horizontal)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label for the group (prefer this over `aria-label` for correct HTML attribute). |
| ariaLabelledBy | `string` | no |  | ID of the element that labels the group. |
| children | `Snippet` | no |  | Button children to group. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| connected | `boolean` | no |  | Visually connect buttons (overlapping borders, shared rounding). When `false`, buttons are spaced with a small gap. |
| disabled | `boolean` | no |  | Disable the entire group and all child Buttons. |
| intent | `ComponentIntent` | no |  | Semantic colour propagated to child Buttons. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to each child Button (per-item via context); overrides each button's own `mint` prop.  The `'none'` default also flattens each button's press sink, so a connected group's shared seam stays still on click instead of one segment shrinking away from its neighbours. Buttons keep reporting the press in depth and colour. Name any real mint here to give the whole group its movement back. |
| onSelectionChange | `(value: ButtonGroupValue, selectedValues: string[]) => void` | no |  | Fired when selection changes. Receives the new value and an array of all selected values. |
| orientation | `ButtonGroupOrientation` | no |  | Stack direction. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ButtonGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| selection | `ButtonGroupSelection` | no |  | Selection mode. `"single"` = radio-group, `"multiple"` = checkbox-group, `"none"` = no selection. |
| size | `ComponentSize` | no |  | Size propagated to child Buttons (the group value wins over a Button's own `size`). |
| slotClasses | `Partial<Record<ButtonGroupSlots, string>>` | no |  | Per-slot class overrides. Slots: base. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tier | `InteractiveTier` | no |  | Semantic radius tier propagated to child Buttons. `commit` → pill caps for the group; `modify` → soft caps. Inherits from a wrapping Toolbar via TierContext when not set explicitly. The unset default is `commit`, except on a connected vertical group, where the pill cap domes the stack into a lozenge — that one defaults to `modify`. Set `tier="commit"` explicitly to get the capsule back (right for a narrow, icon-only stack). |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| value | `ButtonGroupValue` | no |  | Current selection value. Bind with `bind:value` for two-way sync. String for single, string[] for multiple. |
| variant | `ButtonVariants['variant']` | no |  | Visual weight propagated to child Buttons. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type ButtonGroupSelection = 'none' | 'single' | 'multiple'
```

```ts
type ButtonGroupOrientation = 'horizontal' | 'vertical'
```

```ts
type ButtonGroupValue = string | string[] | undefined
```

```ts
interface ButtonGroupContext {
readonly orientation: ButtonGroupOrientation;
  readonly connected: boolean;
  readonly size: ComponentSize;
  readonly intent: ComponentIntent;
  readonly variant: ComponentVariant;
  readonly selection: ButtonGroupSelection;
  readonly disabled: boolean;
  readonly mint: MintProp;
  readonly selectedValues: Set<string>;

  registerButton: (value: string | undefined) => {
    readonly isSelected: boolean;
    onClick: () => void;
    getButtonProps: () => {
      role?: 'radio' | 'checkbox';
      'aria-checked'?: boolean;
      /**
       * The Button's selection value, exposed on the element so the group can
       * resolve the selected radio by matching value instead of by position
       * (robust against duplicate values and runtime add/remove).
       */
      'data-value'?: string;
    };
  };
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type ComponentIntent = (typeof INTENTS)[number]
```

```ts
type ComponentSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`

---

## Calendar
Flexible calendar component with month, year, week, and day views.
Renders timed appointments, multi-day spans and recurrence on a time grid, with
event display, date selection and configurable layout. For a headless grid that
buckets your own domain content (meals, shifts, bookings) per day, use `Planner`.
For one lane per resource (rooms, chairs, vehicles) with bars spanning the days
each is occupied, use `ResourceTimeline`.

**Import:** `import { Calendar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Calendar
  events={wasteEvents}
  categories={wasteCategories}
  bind:value={selectedDate}
  showEventList
  showLegend
  locale="de-DE"
/>
```

```svelte
<Calendar view="week" bind:value={selectedDate} />
```

```svelte
<Calendar selectionMode="range" bind:value={dateRange}>
  {#snippet children()}
    <CalendarHeader showViewSwitcher />
    <CalendarGrid />
  {/snippet}
</Calendar>
```

```svelte
<script lang="ts">
  import { MediaQuery } from 'svelte/reactivity';

  // A week keeps seven columns behind a horizontal scroll on a phone. Where a
  // single day is the better answer, pick the view from the viewport and take
  // `week` out of the switcher with it.
  //
  // The `false` is the SSR answer, not a default worth omitting: without it a
  // prerendered page ships the wide branch and swaps to `day` on hydration —
  // a visible flip on the phone this is for. Spell out whichever branch the
  // server should render.
  const narrow = new MediaQuery('(max-width: 48rem)', false);
</script>

<Calendar
  view={narrow.current ? 'day' : 'week'}
  views={narrow.current ? ['day', 'agenda'] : ['month', 'week', 'day', 'agenda']}
/>
```

### Variants
- variant: bordered, default, ghost (default: default)
- size: lg, md, sm (default: md)
- navPlacement: next
- showToday: false, true
- showWeekNumbers: false, true
- stacksOnNarrow: false, true

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CalendarVariants | `VariantProps` | no |  | Styling variants from CalendarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| agendaDays | `number` | no | 30 | How many days the agenda lists, counted **from the reference date** — the day `value`/`defaultDate` anchors on, or today. So `agendaDays={1}` next to a `defaultDate` is one day's list, and the default is roughly a month ahead of that day rather than the calendar month it sits in.  The arrows, `ArrowLeft`/`ArrowRight` and the swipe step the whole window, so the next list starts the day after the current one ends, and `minDate`/ `maxDate` bound the WINDOW rather than its anchor: a step clamps span-preserving and the arrows disable once an edge is reached. Navigation reports through `onNavigate` — uniformly, including at `agendaDays={1}`, rather than switching callbacks on a prop value; the header's month picker still reports `onMonthChange`, because a month is what it picks.  The window is always exactly this many days; the RENDERING skips days with no events, so a month-long window of one busy day is one heading, and a window of nothing renders the empty state.  Values outside 1–366 (and non-numbers) fall back to the default and warn in DEV — a list is not a place to accidentally walk a decade. |
| animated | `boolean` | no | true | Enable animated transitions for navigation. |
| categories | `DateCategory[]` | no | [] | Event categories for color coding and legend. |
| children | `Snippet` | no |  | Default children snippet for custom layout composition. |
| class | `string` | no |  | Extra CSS classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| dayCell | `Snippet<[DayCellContext]>` | no |  | Custom snippet for rendering a day cell. |
| defaultDate | `Date` | no |  | Initial reference day the grid is anchored on, without selecting it. Use this to open a **week** or **day** view on a specific week — `defaultMonth`/ `defaultYear` resolve to the 1st, whose week can fall mostly in the previous month. Ignored when `value` is set (the selection anchors instead); takes priority over `defaultMonth`/`defaultYear`. Read at mount only. |
| defaultMonth | `number` | no |  | Initial displayed month (0–11). Used only when `value` and `defaultDate` are unset; when `value` is provided, the calendar opens on the value's month. Best for month/year views — for week/day views prefer `defaultDate`. Defaults to current month. |
| defaultYear | `number` | no |  | Initial displayed year. Used only when `value` is unset; when `value` is provided, the calendar opens on the value's year. Defaults to current year. |
| disabled | `boolean` | no | false | Disable the entire calendar. |
| disabledDates | `Date[]` | no |  | Specific dates that are disabled (not selectable). |
| draggable | `boolean` | no | false | Enable drag & drop to move events between dates. |
| eventItem | `Snippet<[EventItemContext]>` | no |  | Custom snippet for rendering an event item in the list-based views (agenda and the month event list). Time-grid views (week/day) render events through their hour grid and ignore this snippet.  Replaces the default row entirely, including the clock time an event with `allDay: false` shows there — format it from `event.start`/`event.end` yourself (`formatTimeRange` from `@urbicon-ui/blocks/date` is the same helper the default uses). For a multi-day event the context's `isStart` / `isEnd` say which end of the span this row is: the default prints `start` on the first day, "until <end>" on the last, nothing in between, because `event.start` is the same instant on every row. The chronological order of a day is not part of the snippet's job: the calendar sorts each day before rendering. |
| eventPopover | `boolean` | no | false | Show a rich popover on hover/focus for days with events (month view). |
| events | `CalendarEvent[]` | no | [] | Array of events to display on the calendar. |
| fixedWeeks | `boolean` | no | false | Always show 6 weeks in the grid. |
| header | `Snippet<[HeaderContext]>` | no |  | Custom snippet for the header area. |
| highlightToday | `boolean` | no | true | Visually mark today across every view — the month cell, the week column header, the year mini-day, the agenda day header and the mini calendar. `aria-current="date"` is **not** affected: it is a semantic pointer, so a screen-reader user keeps the orientation a purely visual preference should not take away. Neither is the time grid's current-time line, which marks the current *time* rather than the day (see `timeGridHourHeight`'s neighbours). Matches `Planner`'s prop of the same name. |
| isDateDisabled | `(date: Date) => boolean` | no |  | Function to test whether a date is disabled. |
| locale | `string` | no | 'auto' | BCP 47 locale tag for date formatting — month names, weekday names, the header title and the clock time of timed events in the list-based views (hour cycle, separator and padding all follow the locale, so a 12-hour locale renders "9:05 AM"). Defaults to `'auto'`, which follows the active `<I18nProvider>` locale, so an app that already declares its language does not have to repeat it here. SSR-safe: the locale comes from context, so the server and the client resolve the same tag (`Intl` with `undefined` would follow the runtime and disagree across hydration). Falls back to the base locale (`en`) when no provider is mounted. Pass an explicit tag (e.g. `'de-DE'`, `'ja-JP'`) to override. |
| maxDate | `Date` | no |  | Latest selectable/navigable date. |
| minDate | `Date` | no |  | Earliest selectable/navigable date. |
| miniCalendarPosition | `'left' | 'right'` | no | 'left' | Position of the mini calendar sidebar. |
| onDateClick | `(date: Date) => void` | no |  | Fires when a date cell is clicked (regardless of selection change). |
| onDateCreate | `(date: Date, view: CalendarViewMode) => void` | no |  | Fires on double-click on a day cell for event creation. The consumer shows their own form. |
| onDayChange | `(date: Date) => void` | no |  | Fires when the displayed day changes (day view). |
| onEventClick | `(event: CalendarEvent) => void` | no |  | Fires when an event is clicked. |
| onEventMove | `(event: CalendarEvent, newStart: Date, newEnd: Date) => void` | no |  | Fires when an event is moved via drag & drop. |
| onEventResize | `(event: CalendarEvent, newEnd: Date) => void` | no |  | Fires when an event is resized via drag handle. |
| onMonthChange | `(month: number, year: number) => void` | no |  | Fires when the displayed month/year changes via navigation — the month and year views, and the header's month picker in any view. The agenda's arrows step a window of days instead of a month and report through `onNavigate`. |
| onNavigate | `(date: Date, range: DateRange) => void` | no |  | Fires after **any** navigation, in every view, with the new reference date and the visible range — load data here. A **view switch** counts as one: it changes the window (a padded month grid, seven days, `agendaDays` from the anchor …) without moving the reference date, and a loader that missed it rendered the new view against the old view's rows. The per-view callbacks (`onMonthChange` / `onWeekChange` / `onDayChange`) still fire and are the better fit when you only care about one view; this one spares you reconstructing the window yourself — and in the agenda it is the *only* navigation callback, whose window no per-view callback can name. The range is view-accurate: month spans the padded cell grid (spill days included), week/day the visible days, year 1 Jan–31 Dec, agenda `agendaDays` from the reference date. Matches `Planner`'s `onNavigate`. |
| onTimeSlotCreate | `(start: Date, end: Date) => void` | no |  | Fires on click on an empty time slot for event creation. Returns default 1h duration. |
| onValueChange | `(value: CalendarSelection) => void` | no |  | Fires when the selected date(s) change. |
| onViewChange | `(view: CalendarViewMode) => void` | no |  | Fires when the view mode changes — before `onNavigate`, which the switch also fires because the visible window changed with it. A switch to the view already on screen is a no-op and fires neither. |
| onWeekChange | `(weekStart: Date) => void` | no |  | Fires when the displayed week changes (week view). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Calendar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| resizable | `boolean` | no | false | Enable resize handles on timed events in the time grid. |
| selectionMode | `'single' | 'range' | 'multiple'` | no | 'single' | Selection behavior. |
| showEventList | `boolean` | no |  | Whether to show the detail list when a date is selected. Auto-enabled when events are provided. |
| showLegend | `boolean` | no |  | Whether to show the built-in legend. Defaults to true when categories are provided. |
| showMiniCalendar | `boolean` | no | false | Show a mini month calendar sidebar (week/day/agenda views). |
| showOutsideDays | `boolean` | no | true | Show days from previous/next months to fill the grid. |
| showViewSwitcher | `boolean` | no | true | Show the view switcher in the header. Below `sm` its labels condense to their short form; the full label stays the accessible name. |
| showWeekNumbers | `boolean` | no | false | Show ISO week numbers in the left margin. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Component size. |
| slotClasses | `Partial<Record<CalendarSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| swipeable | `boolean` | no | true | Enable swipe gestures for touch navigation. |
| timeGridEndHour | `number` | no | 20 | Last visible hour in time grid (exclusive). |
| timeGridHourHeight | `number` | no |  | Height of one hour row in the time grid, in pixels. Left unset it follows `size` (sm 40 · md 48 · lg 64), which is the only reason a nine-hour day costs 432 px of card height whether or not the consumer has it. Set a smaller number for a compact day, a larger one for finer slots. Drives the label column, the slot rows, the grid's `min-height` and the auto-scroll to the current time, so it is a number rather than a CSS variable — the scroll math has to read it. |
| timeGridInterval | `30 | 60` | no | 60 | Time slot interval in minutes. |
| timeGridStartHour | `number` | no | 7 | First visible hour in time grid. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. |
| value | `CalendarSelection` | no |  | Currently selected date(s). Supports bind:value. |
| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style. |
| view | `CalendarViewMode` | no | 'month' | Active view mode. Supports bind:view.  `week` and `day` are hour grids. The week's seven columns keep at least `--blocks-calendar-day-min-width` each (5 rem at `size="sm"`, 6 rem at `md`, 7 rem at `lg`); once they no longer fit, the grid scrolls sideways instead of shrinking the days to a stripe. The hour gutter stays pinned to the left while it does and the day heads — with the all-day band under them — to the top, and arrow-key navigation brings the focused day into view. Set the property on the calendar — `style="--blocks-calendar-day-min-width: 8rem"` — to trade more scrolling for wider days.  While the week is scrolling, a horizontal touch drag belongs to the scroller: it moves the days rather than paging to the next week. A week that fits keeps the swipe. The header arrows, `ArrowLeft`/`ArrowRight` and `bind:view` are unaffected either way. On a phone the honest week is often no week at all: bind this prop to a `MediaQuery` and narrow `views` with it (the `MediaQuery` example on the component) rather than handing over seven columns behind a scrollbar. |
| views | `CalendarViewMode[]` | no | ['month', 'week', 'day', 'year', 'agenda'] | Which views the header's switcher offers. It filters the switcher only: a `view` left out of the list still renders, so narrowing the list is how a layout hides a view it cannot serve while still choosing it itself — the viewport-driven pairing under `view`. |
| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |
| navPlacement | `'next'` | no |  | Controls the navPlacement behavior and appearance of the Calendar component. Available options: next. |
| showToday | `'false' | 'true'` | no |  | Controls the showToday behavior and appearance of the Calendar component. Available options: false, true. |
| stacksOnNarrow | `'false' | 'true'` | no |  | Controls the stacksOnNarrow behavior and appearance of the Calendar component. Available options: false, true. |

Inherited from:
- Omit<CalendarVariants, 'dayState' | 'hasEvents'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type CalendarSlotName = CalendarSlots
```

```ts
interface CalendarEvent {
/** Unique identifier. */
  id: string;
  /** Event title. */
  title: string;
  /** Start date/time. */
  start: Date;
  /** End date/time. Optional for all-day events. */
  end?: Date;
  /**
   * Whether this is an all-day event. An explicit `false` is what marks an
   * event as happening AT a time: it then lands on the week/day time grid, and
   * the list-based views (agenda, month event list) print its clock time ahead
   * of the title and sort it after the day's all-day events.
   *
   * A timed event spanning several days states one time per row, the one that
   * is true for that day: `start` (with `end`, when `end` falls on the same
   * calendar day) on its first day, "until <end>" on its last, and nothing on
   * the days in between — those rows carry the "Day 2 of 3" badge instead.
   * @default true
   */
  allDay?: boolean;
  /** Category ID linking to a {@link DateCategory} in `categories`. */
  categoryId?: string;
  /** Optional description or status text. */
  description?: string;
  /** Optional secondary helper text. */
  helperText?: string;
  /** Arbitrary metadata for consumer use. */
  meta?: Record<string, unknown>;
  /** Recurrence rule for repeating events. */
  recurrence?: RecurrenceRule;
}
```

```ts
type CalendarSelection = Date | DateRange | Date[]
```

```ts
type CalendarViewMode = 'month' | 'year' | 'week' | 'day' | 'agenda'
```

```ts
interface DateCategory {
/** Stable id — what an item's category accessor returns. */
  id: string;
  /** Display label, shown in the legend. */
  label: string;
  /** CSS colour value for the dot, bar or border. */
  color: string;
}
```

```ts
interface DateRange {
start: Date;
  end: Date;
}
```

```ts
interface DayCellContext {
date: Date;
  events: CalendarEvent[];
  isToday: boolean;
  isSelected: boolean;
  isDisabled: boolean;
  isOutsideMonth: boolean;
  isFocused: boolean;
}
```

```ts
interface EventItemContext {
event: CalendarEvent;
  category?: DateCategory;
  /** 0-based index: which day of the multi-day event (only set for multi-day). */
  dayIndex?: number;
  /** Total duration in days (only set for multi-day, > 1). */
  totalDays?: number;
  /** Whether this date is the start of the event. */
  isStart?: boolean;
  /** Whether this date is the end of the event. */
  isEnd?: boolean;
}
```

```ts
interface HeaderContext {
view: CalendarViewMode;
  month: number;
  year: number;
  title: string;
  navigate: (delta: number) => void;
  navigateMonth: (delta: number) => void;
  goToToday: () => void;
  canGoBack: boolean;
  canGoForward: boolean;
  /** Whether today is within `[minDate, maxDate]`; gate a custom Today control on it. */
  canGoToToday: boolean;
}
```

```ts
interface RecurrenceRule {
/** How often the event repeats. */
  frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
  /** Repeat every N periods (e.g. 2 = every 2 weeks). @default 1 */
  interval?: number;
  /**
   * Weekdays the rule applies to — 0=Sun, 1=Mon, ..., 6=Sat. Values outside
   * that range match no day at all and warn in DEV. An empty array reads as
   * "no restriction", not "exclude everything".
   *
   * Its meaning depends on `frequency`, following RFC 5545:
   * - `weekly` — GENERATES one occurrence per listed day, in every interval-th
   *   week. `{ weekly, interval: 2, byDay: [1,2,3,4,5] }` = weekdays of every
   *   other week.
   * - `daily` — FILTERS the days the rule would otherwise produce.
   *   `{ daily, interval: 2, byDay: [1,2,3,4,5] }` = every other day, but only
   *   when it falls on a weekday.
   *
   * The two are not interchangeable once `interval` is involved.
   *
   * Only the occurrence's START day is tested, so on a multi-day event a
   * weekday-only rule still draws across the weekend. Read by `daily` and
   * `weekly` only; `monthly` uses `byMonthDay`, `yearly` repeats the start date.
   */
  byDay?: number[];
  /** Specific day(s) of month, 1-31. Read by `monthly` only. */
  byMonthDay?: number[];
  /** End date — recurrence stops after this date (inclusive). */
  until?: Date;
  /**
   * Maximum number of occurrences the series yields. Days removed by `byDay`
   * are not occurrences and do not count against it — `{ daily, count: 3,
   * byDay: [1..5] }` starting on a Sunday yields the following Mon/Tue/Wed. The
   * original start date counts when it is itself an occurrence.
   */
  count?: number;
  /** Exception dates where the event does NOT occur. */
  exceptions?: Date[];
}
```

### Slots (slotClasses keys)
`base`, `header`, `title`, `nav`, `titleGroup`, `switcher`, `actions`, `navButton`, `grid`, `weekdayHeader`, `weekday`, `weekRow`, `weekNumber`, `day`, `dayNumber`, `dotContainer`, `dot`, `list`, `dateHeader`, `empty`, `item`, `colorBar`, `eventTime`, `eventTitle`, `eventDescription`, `eventHelper`, `legend`, `legendItem`, `legendDot`, `legendLabel`, `yearGrid`, `yearMonth`, `yearMonthTitle`, `yearMiniDay`, `yearMiniDot`, `weekColumnHeader`, `weekColumnDayName`, `weekColumnDayNumber`, `weekAllDayEvent`, `multiDayBar`, `multiDayBarContainer`, `dayView`, `dayViewHeader`, `agendaView`, `agendaDayGroup`, `agendaDayHeader`, `agendaEventList`, `timeGrid`, `timeGutter`, `timeHeadCell`, `timeCorner`, `timeLabel`, `timeSlotRow`, `timeDayColumn`, `timeEvent`, `allDayArea`, `currentTimeLine`, `weekTimeLayout`, `eventPopover`, `eventPopoverItem`, `miniCalendar`, `miniCalendarHeader`, `miniCalendarTitle`, `miniCalendarNavButton`, `miniCalendarWeekday`, `miniCalendarDay`

---

## Card
Flexible container for grouping related content with optional header, footer,
and interactive states. Renders as div, button, or anchor depending on the provided props.

Shape follows the container tier (`--radius-contain`), so retuning that token moves every
Card along with Dialog, Alert and Popover. `tier="bridge"` is the one sanctioned deviation
and it is optical, not decorative: radius scales with the area it turns, so the hairline
edge that reads as precise on a wide panel reads as an untouched rectangle on a small
tinted tile. Reach for it when a Card is a content chip rather than architecture — and not
to give one card a different look, which splits the family (see the `variant` axis for
weight, and `BlocksProvider` `defaults` for a project-wide Card treatment).

**Import:** `import { Card } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Card padding="lg">
  {#snippet header()}
    <h3>Title</h3>
  {/snippet}
  <p>Body content</p>
</Card>
```

```svelte
<Card variant="elevated" dividers onclick={() => navigate('/detail')}>
  {#snippet header()}
    <div class="flex items-center gap-3">
      <Avatar name="Jane Doe" size="sm" />
      <span class="font-medium">Jane Doe</span>
    </div>
  {/snippet}
  <p>Interactive card that navigates on click.</p>
  {#snippet footer()}
    <span class="text-text-tertiary text-sm">2 min ago</span>
  {/snippet}
</Card>
```

### Variants
- variant: elevated, floating, outlined, quiet (default: quiet)
- disabled: true (default: false)
- dividers: true (default: false)
- padding: lg, md, none, sm, xl (default: md)
- tier: bridge, contain (default: contain)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CardVariants | `VariantProps` | no |  | Styling variants from CardVariants |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| children | `Snippet` | no |  | Main body content. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clickable | `boolean` | no |  | Force `<button>` rendering and interactive hover styles without providing an `onclick` handler — useful when delegating clicks through a wrapper component or library. `onclick` and `href` already enable interactive styles automatically; reach for `clickable` only when neither is appropriate.  Don't combine with an outer `<a href>` or inner interactive content — `<a><Card clickable>…</Card></a>` produces nested interactive elements (invalid HTML, a11y violation). Prefer `<Card href={…}>` so the card itself becomes the anchor. |
| footer | `Snippet` | no |  | Content rendered below the body. With `dividers`, a hairline separates body from footer. |
| header | `Snippet` | no |  | Content rendered above the body. With `dividers`, a hairline separates header from body. |
| href | `string` | no |  | URL target. When provided, the card renders as `<a>`. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the card. Only applies while the card is interactive (`clickable`, `onclick`, or `href`) and not disabled. |
| onclick | `(event: MouseEvent) => void` | no |  | Click handler. When provided, the card renders as `<button>` and gains interactive styles. |
| onHover | `(hovered: boolean) => void` | no |  | Called when hover state changes. Receives `true` on mouse-enter, `false` on mouse-leave. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Card: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project.  A conditional `overrides` rule on a Card keys on its variant axes, and one of those is not a prop: `interactive` is the axis `clickable`, `onclick` and `href` all resolve to, so `overrides: [{ interactive: true, … }]` styles every card that has a click source, whichever of the three gave it one. It is deliberately not settable — a card made to look interactive without one would be a `<div>` with `cursor-pointer` and a hover-lift and no way to operate it (WCAG 3.2 Predictable). |
| slotClasses | `Partial<Record<CardSlots, string>>` | no |  | Per-slot class overrides. Slots: base | header | content | footer. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| variant | `'elevated' | 'floating' | 'outlined' | 'quiet'` | no | quiet | Controls the visual style and presentation of the Card. Determines the component's visual treatment. Available options: elevated, floating, outlined, quiet. |
| disabled | `'true'` | no | false | Controls the disabled behavior and appearance of the Card component. Available options: true. |
| dividers | `'true'` | no | false | Controls the dividers behavior and appearance of the Card component. Available options: true. |
| padding | `'lg' | 'md' | 'none' | 'sm' | 'xl'` | no | md | Controls the padding behavior and appearance of the Card component. Available options: lg, md, none, and 2 more. |
| tier | `'bridge' | 'contain'` | no | contain | Selects the semantic radius tier of the Card — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: bridge, contain. |

Inherited from:
- Omit<CardVariants, 'elementType' | 'interactive'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `header`, `content`, `footer`

---

## ChartFrame
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Responsive SVG chart shell: measures its width via
ResizeObserver, applies plot margins, and hands the drawable plot geometry
to a child snippet. The building block under every cartesian chart in the
family — use it directly only for fully custom marks.

**Import:** `import { ChartFrame } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ChartFrame height={200} ariaLabel="Weekly revenue">
  {#snippet children({ innerWidth, innerHeight })}
    <!-- map your data onto innerWidth / innerHeight, then draw SVG marks -->
    <polyline points={pts} fill="none" class="stroke-primary" stroke-width="2" />
  {/snippet}
</ChartFrame>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label for the chart image (role="img"). |
| children | `Snippet<[ChartPlot]>` | no |  | Renders the SVG plot content; receives the `ChartPlot` geometry. |
| class | `string` | no |  | Extra classes merged onto the <figure> wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| fallback | `Snippet` | no |  | Screen-reader fallback (e.g. a data table) rendered visually hidden. |
| height | `number` | no | 240 | Fixed SVG height in px. |
| legend | `Snippet` | no |  | Optional legend rendered (as HTML) below the SVG. |
| margin | `ChartMargin` | no |  | Plot margins; merged over the frame defaults. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| slotClasses | `ChartFrameSlotClasses` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px. Omit for responsive width measured from the container (the common case); set it only for SSR-stable, non-responsive output. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
type ChartFrameSlotClasses = Partial<Record<ChartFrameSlot, string>>
```

```ts
interface ChartMargin {
top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}
```

```ts
interface ChartPlot {
/** Full SVG width (px). */
  width: number;
  /** Full SVG height (px). */
  height: number;
  /** Drawable width inside the margins (px). */
  innerWidth: number;
  /** Drawable height inside the margins (px). */
  innerHeight: number;
  /** Resolved margins (all sides present). */
  margin: Required<ChartMargin>;
}
```

```ts
type ChartFrameSlot = (typeof CHART_FRAME_SLOTS)[number]
```

---

## Chat
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Thin full-height layout shell for a chat surface: an optional pinned
`header` (border-b), the scrollable conversation area as `children` (the consumer
drops a ChatMessageList here — the shell itself never scrolls, the body child does),
and an optional pinned `composer` at the bottom (border-t, e.g. PromptInput). No
state, no context, no provider — pure structure with `min-h-0` flex discipline so it
fills its parent and hands scrolling to its body.

**Import:** `import { Chat } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Chat>
  {#snippet header()}<Toolbar aria-label="Conversation actions">…</Toolbar>{/snippet}
  <ChatMessageList {messages} />
  {#snippet composer()}<PromptInput onSubmit={send} />{/snippet}
</Chat>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...ChatVariants | `VariantProps` | no |  | Styling variants from ChatVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| children | `Snippet` | no |  | The scrollable conversation area — typically a ChatMessageList. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| composer | `Snippet` | no |  | Optional pinned composer rendered below the conversation (border-t) — e.g. PromptInput. |
| header | `Snippet` | no |  | Optional pinned header rendered above the conversation (border-b). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Chat: {...} }}>`. Prefer this over `class` overrides for reusable custom looks. |
| slotClasses | `Partial<Record<ChatSlots, string>>` | no |  | Per-slot class overrides. Slots: root | header | body | composer. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |

Inherited from:
- ChatVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

---

## ChatMessage
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Renders one `ChatMessageData` — its ordered parts (markdown text via
StreamingMarkdown, reasoning, tool-call status lines, policy-checked attachment
chips) plus a citation footer, streaming placeholder, error/aborted Alert, a
hover-revealed copy/regenerate action bar and a timestamp. `layout="bubble"`
(default) tints and aligns per role; `layout="plain"` is a document-like
full-width Claude-style column. Untrusted URLs never render as inline media —
only as `urlPolicy`-checked download links. Compose many of these under
ChatMessageList; the consumer owns the `ChatMessageData[]`.

**Import:** `import { ChatMessage } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ChatMessage message={msg} onRegenerate={() => regenerate(msg.id)} />
```

### Variants
- density: comfortable, compact (default: comfortable)
- layout: bubble, plain (default: bubble)
  - plain — Document-like: full-width content under an avatar + role header row.

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| message | `ChatMessageData` | yes |  | The message to render. The component never mutates it. |
| ...ChatMessageVariants | `VariantProps` | no |  | Styling variants from ChatMessageVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| abortedLabel | `string` | no | 'Generation stopped' | Alert title for `status === 'aborted'`. |
| actions | `Snippet<[{ message: ChatMessageData }]>` | no |  | Action-bar override. Receives the message; default is copy (+ regenerate when `onRegenerate` is set). |
| avatar | `Snippet<[{ role: ChatRole }]>` | no |  | Avatar override. Receives the message role; default is the Avatar primitive with a role icon. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| copiedLabel | `string` | no | the `accessibility.copied` translation | Label shown briefly after a successful copy. |
| copyFailedLabel | `string` | no | the `accessibility.copyFailed` translation | Label shown briefly after a FAILED copy — e.g. a denied clipboard permission or a non-secure context. |
| copyLabel | `string` | no | the `accessibility.copy` translation | Accessible label / tooltip for the copy action. |
| errorLabel | `string` | no | 'Something went wrong' | Alert title for `status === 'error'`. |
| metadata | `Snippet<[{ message: ChatMessageData }]>` | no |  | Metadata override. Receives the message; default is `createdAt` as a `<time>` element. |
| onRegenerate | `() => void` | no |  | Provide to render a "Regenerate" action. Called on click. |
| onRetry | `() => void` | no |  | Provide to render a "Retry" button in the error/aborted Alert. Called on click. |
| partRenderers | `ChatPartRenderers` | no |  | Per-part-type render overrides (see `ChatPartRenderers`). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ChatMessage: {...} }}>`. Prefer this over `class` overrides for reusable custom looks. |
| regenerateLabel | `string` | no | 'Regenerate' | Accessible label / tooltip for the regenerate action. |
| retryLabel | `string` | no | 'Retry' | Label for the retry button in the error/aborted Alert. |
| roleLabels | `Partial<Record<ChatRole, string>>` | no |  | Display names per role, shown in the `plain`-layout header. |
| slotClasses | `Partial<Record<ChatMessageSlots, string>>` | no |  | Per-slot class overrides. Slots: root | container | header | roleName | avatar | column | bubble | partsFlow | attachment | attachmentIcon | attachmentName | attachmentSize | sourcesFooter | placeholder | statusAlert | footer | actions | actionButton | metadata. `column` wraps the bubble with everything under it (citations, status alert, footer) and carries the role-dependent alignment — override it to re-align a message's whole stack, not just the bubble. Reasoning and tool-call parts render through ReasoningDisclosure / ToolCallCard, which take their own `slotClasses`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes, from this component and the ones it renders (Avatar, Alert, Tooltip, the part renderers). |
| urlPolicy | `MarkdownUrlPolicy` | no |  | URL policy applied to attachment links and forwarded to StreamingMarkdown / CitationChip. Strict by default (untrusted LLM/server output). Keep it referentially stable to avoid re-parsing streamed markdown. |
| density | `'comfortable' | 'compact'` | no | comfortable | Controls the density behavior and appearance of the ChatMessage component. Available options: comfortable, compact. |
| layout | `'bubble' | 'plain'` | no | bubble | Controls the layout behavior and appearance of the ChatMessage component. Available options: bubble, plain. |

Inherited from:
- Omit<ChatMessageVariants, 'role'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
type ChatPartRenderers = {
  [K in Exclude<ChatMessagePart['type'], 'source'>]?: Snippet<
    [Extract<ChatMessagePart, { type: K }>]
  >;
}
```

```ts
interface ChatMessageData {
/** Stable unique id — keyed `{#each}` identity, never an array index. */
  id: string;
  role: ChatRole;
  /** Ordered renderable segments. A plain text answer is `[{ type: 'text', text }]`. */
  parts: ChatMessagePart[];
  createdAt?: Date;
  /** Omitted counts as `complete`. */
  status?: ChatMessageStatus;
  /** Consumer-defined extras (model name, token counts, …). Not rendered by defaults. */
  metadata?: Record<string, unknown>;
}
```

```ts
type ChatMessagePart = | { type: 'text'; text: string }
  /** Model reasoning. Collapsed, tertiary presentation; `durationMs` feeds the "Thought for Xs" label. */
  | { type: 'reasoning'; text: string; durationMs?: number }
  /** A tool invocation with its lifecycle state. Rendered as a ToolCallCard by default; override via `partRenderers`. */
  | {
      type: 'tool-call';
      id: string;
      name: string;
      state: 'pending' | 'running' | 'complete' | 'error';
      input?: unknown;
      output?: unknown;
      errorMessage?: string;
    }
  /** A cited source. Same shape as CitationSource — also feeds StreamingMarkdown's `sources` for `[id]` markers. */
  | ({ type: 'source' } & CitationSource)
  /**
   * A file attached to the message. `url` is only ever rendered as a
   * policy-checked download link (never as an inline image/iframe) — LLM- or
   * server-supplied URLs are untrusted input.
   */
  | { type: 'attachment'; name: string; mimeType: string; size?: number; url?: string }
  /** Declarative A2UI payload (P4). Validated fail-loud by A2UIView; ignored by default renderers until then. */
  | { type: 'a2ui'; payload: unknown }
```

```ts
type ChatRole = 'user' | 'assistant' | 'system'
```

```ts
interface MarkdownUrlPolicy {
/**
   * Allowed link protocols (with trailing colon). Relative URLs are always
   * allowed for links. @default ['http:', 'https:', 'mailto:', 'tel:']
   */
  allowedLinkProtocols?: string[];
  /**
   * Prefix allowlist for image sources, matched against the normalized
   * absolute URL. Empty (the default) blocks every external image; relative
   * sources are allowed. Prefer deep, specific prefixes — broad ones are
   * open-redirect bait. `data:` images are blocked unless a `data:` prefix
   * is listed explicitly.
   * @default []
   */
  allowedImagePrefixes?: string[];
  /** Observability hook — fires once per blocked URL occurrence. */
  onBlocked?: (kind: 'link' | 'image', url: string) => void;
}
```

```ts
type ChatMessageStatus = 'streaming' | 'complete' | 'error' | 'aborted'
```

```ts
interface CitationSource {
/** Stable id — matches the `[id]` marker in the streamed markdown. */
  id: string;
  /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
  title: string;
  /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
  url?: string;
  /** Short excerpt shown under the title, clamped to ~3 lines. */
  snippet?: string;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`root`, `container`, `header`, `roleName`, `avatar`, `column`, `bubble`, `partsFlow`, `attachment`, `attachmentIcon`, `attachmentName`, `attachmentSize`, `sourcesFooter`, `placeholder`, `statusAlert`, `footer`, `actions`, `actionButton`, `metadata`

---

## ChatMessageList
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Scrollable conversation log with a stick-to-bottom engine: follows
streaming content while the reader is at the bottom, breaks off on upward scroll,
and offers a floating jump-back button with a new-message counter. Anchors the
scroll position when older history is prepended. Announces generation start and
the completed answer once to screen readers instead of every token. Renders
ChatMessage per entry by default; override per message via the `message` snippet.

**Import:** `import { ChatMessageList } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ChatMessageList
  {messages}
  onRegenerate={(m) => regenerate(m.id)}
  onStickChange={(stuck) => (following = stuck)}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| messages | `ChatMessageData[]` | yes |  | The conversation, oldest first. The component never mutates it. Note: rest attributes (incl. a raw `onscroll`) land on the non-scrolling root — observe follow-state via `onStickChange` instead. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| abortedLabel | `string` | no |  | Screen-reader announcement when a stream ends in `aborted` without text. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| density | `ChatMessageProps['density']` | no |  | Message density handed to every default ChatMessage. |
| empty | `Snippet` | no |  | Empty-state content. Default: an EmptyState with `emptyTitle`/`emptyDescription`. |
| emptyDescription | `string` | no |  | Empty-state description. |
| emptyTitle | `string` | no |  | Empty-state heading. |
| errorLabel | `string` | no |  | Screen-reader announcement when a stream ends in `error` without text. |
| generatingLabel | `string` | no |  | Screen-reader announcement when an assistant message starts streaming. |
| layout | `ChatMessageProps['layout']` | no |  | Message layout handed to every default ChatMessage. |
| listLabel | `string` | no |  | Accessible name of the scrollable conversation region. |
| message | `Snippet<[ChatMessageListItemContext]>` | no |  | Per-message renderer override. Default: `<ChatMessage>` wired with the props below. |
| newMessagesLabel | `string` | no |  | Label suffix of the jump button while new messages are pending (prefixed with the count). |
| onRegenerate | `(message: ChatMessageData) => void` | no |  | Regenerate handler — wired only to the last message when it is an assistant message. |
| onRetry | `(message: ChatMessageData) => void` | no |  | Retry handler for messages in `error`/`aborted` status. |
| onStickChange | `(stuck: boolean) => void` | no |  | Fires when the list starts (`true`) or stops (`false`) following new content. |
| partRenderers | `ChatMessageProps['partRenderers']` | no |  | Part-renderer overrides handed to every default ChatMessage. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ChatMessageList: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette. |
| scrollToBottomLabel | `string` | no |  | Accessible label of the jump button when there are no new messages. |
| slotClasses | `Partial<Record<ChatMessageListSlots, string>>` | no |  | Per-slot class overrides. Slots: root | viewport | content | empty | newButton. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes, from this component and the ones it renders (the messages, the empty state, the jump badge). |
| urlPolicy | `MarkdownUrlPolicy` | no |  | URL policy handed to every default ChatMessage (links, citations, attachments). |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface ChatMessageListItemContext {
message: ChatMessageData;
  index: number;
  isLast: boolean;
}
```

```ts
interface ChatMessageData {
/** Stable unique id — keyed `{#each}` identity, never an array index. */
  id: string;
  role: ChatRole;
  /** Ordered renderable segments. A plain text answer is `[{ type: 'text', text }]`. */
  parts: ChatMessagePart[];
  createdAt?: Date;
  /** Omitted counts as `complete`. */
  status?: ChatMessageStatus;
  /** Consumer-defined extras (model name, token counts, …). Not rendered by defaults. */
  metadata?: Record<string, unknown>;
}
```

```ts
interface MarkdownUrlPolicy {
/**
   * Allowed link protocols (with trailing colon). Relative URLs are always
   * allowed for links. @default ['http:', 'https:', 'mailto:', 'tel:']
   */
  allowedLinkProtocols?: string[];
  /**
   * Prefix allowlist for image sources, matched against the normalized
   * absolute URL. Empty (the default) blocks every external image; relative
   * sources are allowed. Prefer deep, specific prefixes — broad ones are
   * open-redirect bait. `data:` images are blocked unless a `data:` prefix
   * is listed explicitly.
   * @default []
   */
  allowedImagePrefixes?: string[];
  /** Observability hook — fires once per blocked URL occurrence. */
  onBlocked?: (kind: 'link' | 'image', url: string) => void;
}
```

```ts
type ChatRole = 'user' | 'assistant' | 'system'
```

```ts
type ChatPartRenderers = {
  [K in Exclude<ChatMessagePart['type'], 'source'>]?: Snippet<
    [Extract<ChatMessagePart, { type: K }>]
  >;
}
```

```ts
type ChatMessagePart = | { type: 'text'; text: string }
  /** Model reasoning. Collapsed, tertiary presentation; `durationMs` feeds the "Thought for Xs" label. */
  | { type: 'reasoning'; text: string; durationMs?: number }
  /** A tool invocation with its lifecycle state. Rendered as a ToolCallCard by default; override via `partRenderers`. */
  | {
      type: 'tool-call';
      id: string;
      name: string;
      state: 'pending' | 'running' | 'complete' | 'error';
      input?: unknown;
      output?: unknown;
      errorMessage?: string;
    }
  /** A cited source. Same shape as CitationSource — also feeds StreamingMarkdown's `sources` for `[id]` markers. */
  | ({ type: 'source' } & CitationSource)
  /**
   * A file attached to the message. `url` is only ever rendered as a
   * policy-checked download link (never as an inline image/iframe) — LLM- or
   * server-supplied URLs are untrusted input.
   */
  | { type: 'attachment'; name: string; mimeType: string; size?: number; url?: string }
  /** Declarative A2UI payload (P4). Validated fail-loud by A2UIView; ignored by default renderers until then. */
  | { type: 'a2ui'; payload: unknown }
```

```ts
type ChatMessageStatus = 'streaming' | 'complete' | 'error' | 'aborted'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface CitationSource {
/** Stable id — matches the `[id]` marker in the streamed markdown. */
  id: string;
  /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
  title: string;
  /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
  url?: string;
  /** Short excerpt shown under the title, clamped to ~3 lines. */
  snippet?: string;
}
```

### Slots (slotClasses keys)
`root`, `viewport`, `content`, `empty`, `newButton`

---

## Checkbox
Accessible checkbox with indeterminate support, semantic intents, and form integration.
Uses a hidden native input for correct form behavior and ARIA semantics.

**Import:** `import { Checkbox } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Checkbox label="Accept terms" bind:checked />
```

```svelte
<Checkbox
  label="Select all"
  indeterminate
  onCheckedChange={(val) => console.log(val)}
/>
```

```svelte
<div class="space-y-2">
  <Checkbox label="Email updates" />
  <Checkbox label="SMS alerts" />
</div>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- variant: filled, ghost, outlined (default: outlined)
- size: lg, md, sm, xs (default: md)
- disabled: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CheckboxVariants | `VariantProps` | no |  | Styling variants from CheckboxVariants |
| ...HTMLInputAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'type' | 'size' | 'checked' | 'class' | 'children') |
| checked | `boolean` | no |  | Current checked state. Supports two-way binding via `bind:checked`. |
| class | `string` | no |  | Extra classes merged onto the wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no |  | Prevent interaction and dim the control. |
| error | `string` | no |  | Error message that replaces `helper`, styles the message red, and sets `aria-invalid` on the input. |
| helper | `string` | no |  | Hint text shown below the control. Hidden when `error` is set. |
| id | `string` | no |  | Explicit `id` to link `<label>` and `<input>`. Auto-generated if omitted. |
| indeterminate | `boolean` | no |  | Visual-only third state showing a dash icon. Resets to unchecked on next user toggle. Does not affect the submitted form value. Supports `bind:indeterminate`. |
| label | `string` | no |  | Text label displayed to the right of the checkbox box. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the box (the visible control, not the sr-only input). Click-triggered engine mints listen on the surrounding label; `ripple` ignites only on the box itself. Only applies while not disabled. |
| name | `string` | no |  | The `name` attribute of the underlying `<input>`. Used for form submission. |
| onCheckedChange | `(checked: boolean) => void` | no |  | Fired after the checked state changes. Receives the new `checked` value. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Checkbox: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no |  | Mark the native input as required for form validation. Also draws the family's required marker beside the label text (never beside the box); it needs a `label` to sit after, and `slotClasses.requiredMark: 'hidden'` takes it away. |
| slotClasses | `Partial<Record<CheckboxSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. Slots: wrapper (root — what `class` also targets) | control | box | icon | label | requiredMark | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tier | `InteractiveTier` | no |  | Semantic radius tier. Default `modify` — checkbox is an input-tap surface. Inherited from TierContext when omitted; falls back to `modify` outside of any tier-aware container. |
| unstyled | `boolean` | no |  | Strip all default variant classes. Use with `slotClasses` for a fully custom look. The box exposes `data-state` for conditional styling. |
| value | `string` | no |  | The value submitted when checked. Defaults to `'on'`. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Checkbox. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| variant | `'filled' | 'ghost' | 'outlined'` | no | outlined | Controls the visual style and presentation of the Checkbox. Determines the component's visual treatment. Available options: filled, ghost, outlined. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Checkbox. Affects the component's physical footprint. Available options: lg, md, sm, xs. |

Inherited from:
- Omit<CheckboxVariants, 'error' | 'checked' | 'indeterminate'> (omit-pattern)
- Omit<HTMLInputAttributes, 'type' | 'size' | 'checked' | 'class' | 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`wrapper`, `control`, `box`, `icon`, `label`, `requiredMark`, `message`

---

## CitationChip
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Compact source marker rendered for a `[id]` citation. StreamingMarkdown wires it up automatically from its `sources` prop — each in-text marker becomes a CitationChip whose click opens a Popover with the source title, snippet, and a policy-checked outbound link. Also usable standalone for source footers / reference lists outside a streamed message.

**Import:** `import { CitationChip } from '@urbicon-ui/blocks';`

### Variants
- citationStyle: label, numeric (default: numeric)
  - label — Label marker — carries the source title, capped so a long title can't stretch the chip across the line.
  - numeric — Numeric marker — a fixed-width numeric pill; no truncation.

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| source | `CitationSource` | yes |  | The cited source. Required. |
| ...HTMLButtonAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class' | 'children') |
| citationStyle | `'numeric' | 'label'` | no | 'numeric' | What the chip shows: `numeric` renders `index` (or `source.id` as a fallback) as a compact numeric pill; `label` renders the (truncated) `source.title`. |
| class | `string` | no |  | Extra classes merged onto the trigger chip (the root slot). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| index | `number` | no |  | 1-based ordinal shown as the chip label under `citationStyle="numeric"`. Falls back to `source.id` when omitted. |
| label | `string` | no |  | Override the trigger's `aria-label`. Defaults to `Source {index}: {title}` (or `Source: {title}` without an index). |
| openLabel | `string` | no | 'Open source' | Text of the outbound link in the popover. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CitationChip: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette. |
| slotClasses | `Partial<Record<CitationChipSlots, string>>` | no |  | Per-slot class overrides. Slots: `trigger` (root chip), `popover` (content wrapper), `title`, `snippet`, `link`, `linkIcon`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip all default tv() classes, the surrounding Popover's included; combine with `class` / `slotClasses` for a custom look. |
| urlPolicy | `MarkdownUrlPolicy` | no |  | URL policy applied to `source.url` before it becomes a link (same strict default as the streaming-markdown engine — untrusted LLM output). A blocked URL yields no link in the popover, only title/snippet. |

Inherited from:
- Omit<HTMLButtonAttributes, 'class' | 'children'> (omit-pattern)

### Types
```ts
interface CitationSource {
/** Stable id — matches the `[id]` marker in the streamed markdown. */
  id: string;
  /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
  title: string;
  /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
  url?: string;
  /** Short excerpt shown under the title, clamped to ~3 lines. */
  snippet?: string;
}
```

```ts
interface MarkdownUrlPolicy {
/**
   * Allowed link protocols (with trailing colon). Relative URLs are always
   * allowed for links. @default ['http:', 'https:', 'mailto:', 'tel:']
   */
  allowedLinkProtocols?: string[];
  /**
   * Prefix allowlist for image sources, matched against the normalized
   * absolute URL. Empty (the default) blocks every external image; relative
   * sources are allowed. Prefer deep, specific prefixes — broad ones are
   * open-redirect bait. `data:` images are blocked unless a `data:` prefix
   * is listed explicitly.
   * @default []
   */
  allowedImagePrefixes?: string[];
  /** Observability hook — fires once per blocked URL occurrence. */
  onBlocked?: (kind: 'link' | 'image', url: string) => void;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

### Slots (slotClasses keys)
`trigger`, `popover`, `title`, `snippet`, `link`, `linkIcon`

---

## CodeBlock
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Read-only code display with a one-click copy interaction: the copy
button swaps its icon and label to a confirmation for two seconds and fires `onCopy`.
Renders raw text only — no built-in syntax highlighting; a consumer or the
StreamingMarkdown renderer can layer highlighting in via a snippet. Used by
StreamingMarkdown for fenced code blocks, and standalone for any code snippet.
`variant="card"` (default) brings its own surface, outline and radius;
`variant="plain"` drops all three for embedding inside a parent that supplies
its own framing (as ToolCallCard does).

**Import:** `import { CodeBlock } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CodeBlock lang="ts" code={`const x = 1;`} onCopy={(c) => track(c)} />
```

### Variants
- variant: card, plain (default: card)
- wrap: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| code | `string` | yes |  | The code to display and copy. Rendered as raw text (no highlighting). |
| ...CodeBlockVariants | `VariantProps` | no |  | Styling variants from CodeBlockVariants |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| actions | `Snippet` | no |  | Extra header actions rendered in the header, just before the copy button. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| copiedLabel | `string` | no | 'Copied' | Label shown for two seconds after a successful copy. |
| copyFailedLabel | `string` | no | 'Copy failed' | Label shown for two seconds after a FAILED copy — e.g. a denied clipboard permission or a non-secure context. |
| copyLabel | `string` | no | 'Copy' | Accessible label / tooltip for the copy button at rest. These labels are plain English defaults rather than i18n-resolved, so this leaf stays out of the i18n registry. Pass your own strings to localise. |
| label | `string` | no |  | Header caption, shown instead of `lang`. For an embedded block, naming what the payload *is* ("Input", "Response body") is often clearer than the language it is serialised in. `lang` still names the scrollable region for screen readers when both are given. |
| lang | `string` | no |  | Language label shown in the header. Display-only — does not drive highlighting. |
| onCopy | `(code: string) => void` | no |  | Called with the copied code after a successful clipboard write. |
| onCopyError | `(error: unknown) => void` | no |  | Called with the thrown reason when the clipboard write fails. Without a handler the failure is logged; either way the button reports it. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CodeBlock: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette. |
| showCopy | `boolean` | no |  | Show the copy button in the header. |
| slotClasses | `Partial<Record<CodeBlockSlots, string>>` | no |  | Per-slot class overrides. Slots: root | header | langLabel | copyButton | pre | code. Note `variant="plain"` deliberately leaves root/header/pre without surface, outline or padding — the embedding parent supplies those. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| wrap | `boolean` | no |  | Soft-wrap long lines. `false` (default) scrolls horizontally inside the block; `true` wraps with `whitespace-pre-wrap` + word breaking. |
| variant | `'card' | 'plain'` | no | card | Controls the visual style and presentation of the CodeBlock. Determines the component's visual treatment. Available options: card, plain. |

Inherited from:
- CodeBlockVariants (external)
- Omit<HTMLAttributes<HTMLElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`root`, `header`, `langLabel`, `copyButton`, `pre`, `code`

---

## CodeExample
Code example with optional live preview, syntax highlighting, and copy-to-clipboard.
Delegates code display to the shared CodePanel primitive.

**Import:** `import { CodeExample } from '@urbicon-ui/docs';`

### Examples
```svelte
<CodeExample title="Basic Usage" code={`<Button>Click me</Button>`} language="svelte">
  <Button>Click me</Button>
</CodeExample>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CodeExampleVariantProps | `VariantProps` | no |  | Styling variants from CodeExampleVariantProps |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'title') |
| children | `Snippet` | no |  | Live preview content rendered above the code block. |
| class | `string` | no |  | Extra classes merged onto the root container element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| code | `string` | no |  | Source code string to display with syntax highlighting. |
| defaultExpanded | `boolean` | no |  | Override the default expanded state from the global code-visibility context. |
| description | `string` | no |  | Short description shown between title and preview. |
| headingLevel | `1 | 2 | 3 | 4 | 5 | 6` | no | 3 | Heading level for the example title, clamped to 1..6. Examples usually sit inside a titled `<Section>` (`h2`), so `h3` is the default.  Pass `2` on a page whose body is a single untitled `<Section>` — the table feature pages are built that way, and there the fixed `h3` followed the page `h1` directly. The title styling is class-driven, so the level never changes how the card looks. |
| isolate | `boolean` | no |  | Opt-in for the Vite plugin: children are auto-extracted as `code` at build time. |
| language | `string` | no |  | Language for syntax highlighting (e.g. 'svelte', 'typescript', 'css'). |
| preview | `boolean` | no | true | Render the live preview section above the code block. |
| previewClass | `string` | no |  | CSS classes for a wrapper div around the preview content. Applies whether or not `isolate` is set; with `isolate` and no `previewClass`, the wrapper falls back to a wrapping, centred flex row.  The preview stage is itself a centring flex row, which makes every child shrink to fit — so an example with more than one child (a field and the value it is bound to, say) needs a `flex-col` here or the two land beside each other, and a wrapper around a `width: 100%` component needs `w-full` or it collapses to whatever else it holds. |
| slotClasses | `Partial<Record<CodeExampleSlotName, string>>` | no |  | Per-slot class overrides for internal elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| title | `string` | no |  | Title displayed in the card header. |
| unstyled | `boolean` | no |  | Remove all default tv styles from internal slots. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CodeExample. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- Omit<CodeExampleVariantProps, 'hasPreview'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> (omit-pattern)

### Types
```ts
type CodeExampleSlotName = | CodeExampleSlots
  | 'codeSection'
  | Extract<
      CodePanelSlotName,
      'toolbar' | 'codeToggle' | 'codeChevron' | 'languageTag' | 'copyButton' | 'codeCollapse'
    >
```

```ts
type CodePanelSlotName = CodePanelSlots
```

### Slots (slotClasses keys)
`container`, `title`, `description`, `preview`, `previewContent`

---

## CodePanel
Shared code display primitive with Shiki syntax highlighting, collapsible panel, and copy-to-clipboard.

**Import:** `import { CodePanel } from '@urbicon-ui/docs';`

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| code | `string` | yes |  | Source code string to display with syntax highlighting. |
| ...CodePanelVariantProps | `VariantProps` | no |  | Styling variants from CodePanelVariantProps |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| expanded | `boolean` | no |  | Controlled expanded state. When omitted, the panel manages its own state. |
| label | `string` | no |  | Human-readable title that names the read-only code region for assistive tech (`aria-label` on the `role="textbox"`). Composed as `Code example: {label}`; falls back to `Code example` when omitted so the name is never empty. |
| language | `string` | no | 'svelte' | Language for syntax highlighting and the toolbar language tag. |
| lineNumbers | `boolean | 'auto'` | no | 'auto' | Show line numbers in the gutter.  `'auto'` (the default) shows them only from `LINE_NUMBER_AUTO_THRESHOLD` lines up — a snippet short enough to take in at a glance (an import one-liner) gains nothing from a `1` in front of it. Pass `true`/`false` to force it either way.  Numbers are rendered as CSS generated content, so they are never part of the copied text or a selection. |
| onToggle | `() => void` | no |  | Called when the toggle button is clicked. Required when `expanded` is controlled. |
| slotClasses | `Partial<Record<CodePanelSlotName, string>>` | no |  | Per-slot class overrides for internal elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| unstyled | `boolean` | no |  | Remove all default tv styles from internal slots. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CodePanel. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- CodePanelVariantProps (external)

### Types
```ts
type CodePanelSlotName = CodePanelSlots
```

### Slots (slotClasses keys)
`root`, `toolbar`, `codeToggle`, `codeChevron`, `languageTag`, `copyButton`, `copySeparator`, `codeCollapse`, `codeDisplay`, `codeContent`

---

## Collapsible
A single expand/collapse panel with animated content, trigger button,
and full ARIA support. Can be used standalone or as the foundation for compound
components like Accordion.

Need the wiring without the layout — trigger and content as siblings, e.g. two
rows of one grid? `useDisclosure()` from `@urbicon-ui/blocks` is the same
contract without the markup: open state, one toggle, and the attribute records
to spread. Collapsible itself is built on it.

**Import:** `import { Collapsible } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Collapsible title="Show details">
  <p>Hidden content revealed when expanded.</p>
</Collapsible>
```

```svelte
<Collapsible bind:open={isOpen} variant="card">
  {#snippet trigger({ open, toggle })}
    <button onclick={toggle}>
      {open ? 'Hide' : 'Show'} settings
    </button>
  {/snippet}
  <SettingsForm />
</Collapsible>
```

### Variants
- variant: card, default, ghost (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Collapsible content |
| ...CollapsibleVariants | `VariantProps` | no |  | Styling variants from CollapsibleVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Custom CSS class. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| defaultOpen | `boolean` | no | false | Initial open state for uncontrolled usage |
| disabled | `boolean` | no | false | Disable the trigger |
| name | `string` | no |  | Base name for generating ARIA IDs. Defaults to auto-generated. |
| onOpenChange | `(open: boolean) => void` | no |  | Callback fired once per trigger-driven open transition, after the state is applied. Not fired for consumer writes via `bind:open`. |
| open | `boolean` | no |  | Whether the content is visible. Supports bind:open. Trigger-driven transitions are applied optimistically: `open` is updated first, then `onOpenChange` reports the change. When passing `open` without `bind:`, mirror every `onOpenChange` back into your state — an ignored change leaves the component and your source of truth diverged. To conditionally reject transitions, drive `open` from your own state and toggle it from a custom `trigger` snippet instead of calling the provided `toggle`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Collapsible: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<CollapsibleSlots, string>>` | no |  | Per-slot class overrides. Slots: base | trigger | chevron | content | contentInner. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| title | `string` | no |  | Trigger label text (used by the default trigger) |
| transitionDuration | `number` | no |  | Override the expand/collapse animation duration in milliseconds. Defaults to the `--blocks-collapse-duration` token (the `normal` 250ms). Set globally via that CSS custom property or per-instance here. Respects `prefers-reduced-motion` (near-instant). |
| transitionEasing | `string` | no |  | Override the expand/collapse easing as a CSS `<easing-function>` — e.g. `'ease-in-out'`, `'cubic-bezier(0.4,0,0.2,1)'`, or a token such as `'var(--blocks-ease-springy)'`. Defaults to the `--blocks-collapse-easing` token.  Note: unlike the overlay components (Dialog/Drawer), whose Svelte transitions take an easing **function** `(t: number) => number`, Collapsible animates via CSS — so its easing is a CSS string. Same intent, representation follows the transition mechanism. |
| trigger | `Snippet<[
      {
        open: boolean;
        toggle: () => void;
        disabled: boolean;
        triggerId: string;
        contentId: string;
      }
    ]>` | no |  | Custom trigger snippet — receives open state, toggle fn, disabled flag, and ARIA IDs |
| unstyled | `boolean` | no |  | Remove default styles |
| variant | `'card' | 'default' | 'ghost'` | no | default | Controls the visual style and presentation of the Collapsible. Determines the component's visual treatment. Available options: card, default, ghost. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Collapsible. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- CollapsibleVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`base`, `trigger`, `chevron`, `content`, `contentInner`

---

## Combobox
Searchable menu (autocomplete) combining a text input with a
filterable option list. Implements the ARIA combobox pattern with keyboard
navigation, custom filtering, and two-way bindable state. Single-select by
default; pass `multiple` for an array-bound multi-select that renders picks as
removable tag chips.

**Import:** `import { Combobox } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Combobox
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' }
  ]}
  bind:value={selected}
  placeholder="Search fruit…"
/>
```

```svelte
<Combobox
options={tenants.map((t) => ({ label: t.name, value: t.id }))}
bind:value={tenantId}
/>
```

```svelte
<Combobox
options={skills}
multiple
bind:value={selectedSkills}
maxItems={5}
placeholder="Add skills…"
/>
```

```svelte
<Combobox
groups={[
{ label: 'Fruit', options: [{ label: 'Apple', value: 'apple' }] },
{ label: 'Veg', options: [{ label: 'Carrot', value: 'carrot' }] }
]}
bind:value={food}
/>
```

```svelte
<Combobox
label="Venue"
options={venues}
bind:value={venue}
allowCustom
clearable
placeholder="Search or type a venue…"
/>
```

### Variants
- variant: bare, filled, ghost, outlined, underline (default: outlined)
- size: lg, md, sm, xl, xs (default: md)
- disabled: true (default: false)
- error: true (default: false)
- open: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| allowCustom | `T extends string ? boolean : never` | no | false | Open the closed option list: whatever the user types becomes selectable as a value of its own, with `options` / `groups` / `queryFn` left as the suggestion set. A trailing row ("Use “Kino 46”", localized) appears once the trimmed query is non-empty and no option the field knows carries that label case-insensitively — including `groups`, `queryFn` results and the labels behind the current selection, but not a `disabled` option, whose label names nothing that can be picked. It is an ordinary option: the arrow keys reach it, Enter picks it, and `onValueChange` receives the trimmed query. In multi-select it obeys `maxItems` like any unselected option — at the cap it renders disabled and Enter on it does nothing until a tag is removed. While an async `queryFn` request is in flight no row is offered; it returns with the results.  **String values only.** The selected value is the query text, so the prop is typed away for a numeric or boolean `T` — `Combobox<number>` cannot mint a number out of free text, and a caller who needs one parses the string themselves in `onValueChange`.  The stored label is the raw query, not the row's prompt: the input (single mode) and the tag (multi) read "Kino 46". A value picked this way therefore needs no `seedOptions` entry on a later mount, and the DEV orphan warning stays quiet for every string value while this is set. In `queryFn` mode a pre-bound single value is exempt: there it is an id whose label is still coming from the server, so it follows the async rule and needs `seedOptions` until the results supply the label.  `customOption` is not called for this row — it renders the built-in prompt, since the option behind it is in none of your arrays. For a row that renders differently, or a value that is not the query text, leave `allowCustom` off and append an option of your own instead. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clearable | `boolean` | no | false | Show a clear button when a value is selected. Click or press Escape to reset. |
| closeOnClickOutside | `boolean` | no |  | Whether the listbox closes on outside click. Default `true`. Set to `false` to pin the listbox open while the consumer manages dismissal explicitly. |
| closeOnEscape | `boolean` | no |  | Whether the listbox closes on Escape key. Default `true`. Set to `false` for inline contexts where Escape should be intercepted by an outer widget (e.g. a row editor that wants to revert on Escape). |
| customOption | `Snippet<[ComboboxOption<T>, boolean]>` | no |  | Custom option renderer. Receives the option and whether it is selected. |
| customTag | `Snippet<[ComboboxOption<T>, () => void]>` | no |  | Custom tag renderer replacing the default chip. Receives the selected option and a `remove` callback — call it to drop the tag (fires `onRemoveTag` + `onValueChange`). Use it to render a `<Badge>` or any bespoke chip.  Positional args: `(option, remove)`. |
| debounceMs | `number` | no | 250 | Debounce applied to `queryFn` in milliseconds. |
| disabled | `boolean` | no | false | Disable the entire combobox. |
| error | `string` | no |  | Error message — replaces helper text, flags the field as invalid (`aria-invalid`) and paints the shared danger frame on the input (single mode) or the tokenizer control (multi). The string prop shadows the boolean `error` variant axis, which the component derives from it (mirrors Input / Select) — that is what the `Omit` above is for. |
| filter | `(option: ComboboxOption<T>, query: string) => boolean` | no |  | Custom filter replacing the built-in case-insensitive label match. Return `true` to include an option. Ignored when `queryFn` is set (the server filters). |
| groups | `ComboboxGroup<T>[]` | no |  | Grouped options with section labels, at parity with Select. Takes precedence over `options` when set. Filtering runs per group; groups whose options all filter out are hidden, and keyboard navigation flows across the flattened, still-visible options exactly as it does for a flat list. |
| helper | `string` | no |  | Helper text shown below the field. Hidden when an error is set. |
| id | `string` | no |  | Deterministic HTML `id` for the component. Auto-generated when omitted. |
| label | `string` | no |  | Field label rendered above the input. |
| loadingText | `string` | no | 'Loading…' | Text shown in the listbox while an async `queryFn` request is in flight. |
| maxItems | `number` | no |  | Cap the number of selected values. Once reached, options that aren't already selected become non-selectable (and are skipped by keyboard navigation) until a tag is removed; already-selected options can still be toggled off. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the search input (the `role="combobox"` element). Only applies while not disabled. |
| multiple | `'false' | 'true'` | no |  | Single-select mode (the default). Omit or set to `false` explicitly. |
| name | `string` | no |  | Shared `name` for a hidden input for native form submission. In multi-select mode one hidden input is emitted per selected value. |
| noResultsText | `string` | no | 'No results found' | Text displayed when the filter produces no matches. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the listbox. Use for analytics or side-effects on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnClickOutside`. |
| onError | `(error: unknown) => void` | no |  | Fired when `queryFn` rejects (aborted / superseded requests are ignored). The loading state ends and the previous option list stays in place — use this to surface the failure (toast, inline message). Without a handler the rejection is logged DEV-only (`console.warn`) and swallowed in production; it never escapes as an unhandled promise rejection. |
| onEscape | `() => void` | no |  | Fires after Escape closes the listbox. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the listbox opens or closes from user interaction (focus, typing, chevron toggle, selection, Escape, outside click). Receives the new open state — use it e.g. to lazy-load options on first open. Not called when the consumer writes `bind:open` directly. |
| onRemoveTag | `(value: T) => void` | no |  | Fires when a single value is removed from the selection — via the tag's remove button, Backspace on an empty query, or toggling a selected option off. Receives the removed value. `onValueChange` fires alongside it with the resulting array; use `onRemoveTag` for per-tag side effects (analytics, exit animations). Note: the bulk clear button does NOT fire this per tag — it signals through `onValueChange([])` only. |
| onValueChange | `(value: T | null) => void` | no |  | Fires after the selected value changes. Receives the new value or `null` on clear. |
| open | `boolean` | no | false | Controls the open state of the listbox. Supports `bind:open`. |
| options | `ComboboxOption<T>[]` | no |  | Array of selectable options. Each needs a unique `value`. |
| placeholder | `string` | no | 'Search…' | Placeholder shown when the input is empty. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Combobox: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| query | `string` | no |  | Current search query text. Supports `bind:query` for external control (e.g. server-side filtering). |
| queryFn | `(query: string, signal: AbortSignal) => Promise<ComboboxOption<T>[]>` | no |  | Server-side search (analogous to the Table remote-mode API). When set, the Combobox stops filtering client-side and instead calls `queryFn` — debounced by `debounceMs` — on each query change, replacing the option list with the resolved result. The `AbortSignal` is aborted when a newer query supersedes an in-flight request, so a slow stale response never clobbers a fresh one. Aborted rejections are swallowed; other rejections end the loading state, leave the previous options in place, and are reported via `onError`. `options`/`groups` are ignored in this mode. The selected option's label is cached so it survives result sets that no longer contain it. |
| required | `boolean` | no | false

In multi-select mode this is visual only — the transient search input
carries no native `required` (it is cleared after each pick), so enforce a
minimum selection in your submit handler. | Marks the field as required. Adds the asterisk on the label. |
| seedOptions | `ComboboxOption<T>[]` | no |  | Label seed for pre-selected values whose options are not (yet) in the option list — the async-mode pattern of binding `value` on mount before any `queryFn` result has arrived. Consulted as the LAST lookup source when resolving a selected value's label (current options first, then the pick-cache, then this seed), so it can never shadow a live option, and it works identically for single and multi selection. Without a matching seed such a value renders as its raw `String(value)` (and warns DEV-only). Declarative and idempotent — not a second selection source: `value` alone decides what is selected; `seedOptions` only supplies labels. A string value under `allowCustom` needs no seed and raises no DEV warning — there the value is its own label, in the input and on the tag alike. The exception is `queryFn` mode, where a pre-bound single value still needs a seed until the server supplies its label. |
| slotClasses | `Partial<Record<ComboboxSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: base | label | requiredMark | inputWrapper | input | message | helper | listbox | option | optionActive | optionSelected | optionHint | optionCheck | group | groupLabel | loading | noResults | clear | chevron | control | search | tag | tagLabel | tagRemove. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Remove all default tv() classes — only user-provided classes apply. |
| value | `T[]` | no | [] | Currently selected values. Supports `bind:value`. |
| variant | `ComboboxVariants['variant']` | no | 'outlined' | Visual style, at parity with Input / Textarea / Select. - `outlined` (default) — visible border, surface-base background - `filled` — surface-interactive fill, no border - `ghost` — transparent until hover/focus - `underline` — bottom-line only, no border-box - `bare` — no frame, no fill, no padding, no fixed height: an inline   autocomplete that reads as the text it sits in. `size` keeps only the   type step, and focus is an outline in `--blocks-focus-ring-color` |
| size | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Combobox. Affects the component's physical footprint. Available options: lg, md, sm, and 2 more. |
| tier | `'commit' | 'modify'` | no | modify | Selects the semantic radius tier of the Combobox — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

### Types
```ts
interface ComboboxOption {
label: string;
  value: T;
  disabled?: boolean;
  /**
   * Trailing secondary text on the option row — a facet count ("24"), a unit,
   * a price. It is part of the option's text content, so the row's accessible
   * name reads "Noir 24" rather than dropping the number.
   *
   * A string, not a number: formatting and locale belong to the caller
   * (`String(count)`, or an `Intl.NumberFormat` result). Ignored while
   * `customOption` draws the row — that snippet owns the whole row. Not matched
   * by the built-in filter, which reads `label` only.
   */
  hint?: string;
}
```

```ts
interface ComboboxGroup {
label: string;
  options: ComboboxOption<T>[];
}
```

```ts
type ComboboxProps = | ComboboxSingleProps<T>
  | ComboboxMultipleProps<T>
```

```ts
type ComboboxOptionType = ComboboxOption<T>
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type SelectValue = string | number | boolean
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `label`, `requiredMark`, `inputWrapper`, `input`, `message`, `helper`, `listbox`, `option`, `optionHint`, `optionActive`, `optionSelected`, `optionCheck`, `group`, `groupLabel`, `noResults`, `loading`, `clear`, `chevronButton`, `chevron`, `control`, `search`, `tag`, `tagLabel`, `tagRemove`

---

## CommandPalette
Keyboard-driven command palette with search, grouped results,
and arrow-key navigation. Composes Dialog + search input into a ready-to-use overlay.
Open via bind:open or the built-in Cmd+K shortcut.

**Import:** `import { CommandPalette } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CommandPalette
  items={commands}
  bind:open
  onSelect={(item) => handleCommand(item)}
  placeholder="Type a command..."
/>
```

```svelte
<CommandPalette
  items={[
    { id: 'new', label: 'New File', category: 'File', shortcut: 'Ctrl+N' },
    { id: 'open', label: 'Open File', category: 'File', shortcut: 'Ctrl+O' },
    { id: 'theme', label: 'Toggle Theme', category: 'Settings' },
    { id: 'search', label: 'Search', category: 'Navigation', shortcut: 'Ctrl+F' }
  ]}
  bind:open={paletteOpen}
  onSelect={(item) => runAction(item.id)}
  size="md"
  showFooter
/>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `CommandPaletteItem[]` | yes |  | Items to display. Grouped automatically by `category`. |
| class | `string` | no |  | Additional CSS classes on the root wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| customEmpty | `Snippet<[query: string]>` | no |  | Custom empty-state renderer. Receives the current query string. |
| customItem | `Snippet<[item: CommandPaletteItem, highlighted: boolean, index: number, select: () => void]>` | no |  | Replace the default per-row rendering. Receives the item, whether its row is highlighted, the item's flat index into the filtered list, and a `select` callback (call it to run the same selection the row's click runs; it is a no-op on a disabled item).  **Render visible content only — nothing focusable, nothing interactive.** A `<button>` or `<a>` inside the row is nested-interactive HTML on the `role="option"` container, a tab stop inside the Dialog's focus trap that the input's keyboard handling never reaches, and a click that bubbles into the row's own, so `onSelect` fires twice. `select` is for a snippet that dispatches from its own non-interactive logic — a pointer gesture on the content, say — and for parity with Select's `toggle`.  The outer `<div role="option">` container is still owned by CommandPalette: its id is what the input's `aria-activedescendant` points at, its `data-command-palette-selected` attribute is what the scroll-into-view query finds, and it carries the row's click and hover-highlight.  Styling the row is `slotClasses.item` plus the state slot (`itemHighlighted`, `itemDisabled` or `itemDefault`), which reach the container here as well; the `itemIcon`, `itemText`, `itemLabel`, `itemExcerpt` and `itemShortcut` slots style the default contents and go unused under `customItem`.  Positional args: `(item, highlighted, index, select)`. |
| emptyText | `string` | no | 'No results found.' | Message shown when the filter returns no results. |
| filter | `(item: CommandPaletteItem, query: string) => boolean` | no |  | Custom filter function. Receives each item and the current query. Return `true` to keep the item. When omitted, a case-insensitive label + category substring match is used. |
| onOpenChange | `(open: boolean) => void` | no |  | Fired when the open state changes (close via Escape, backdrop, or selection). |
| onSelect | `(item: CommandPaletteItem) => void` | no |  | Fired when an item is selected via click or Enter. |
| open | `boolean` | no | false | Controls visibility. Supports `bind:open`. |
| placeholder | `string` | no | 'Search...' | Placeholder text for the search input. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CommandPalette: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| query | `string` | no | '' | Current search text. Supports `bind:query`. Reset to `''` whenever the palette opens.  For async or remote search, watch the bound `query`, fetch your own results, and pass them back via `items` with `filter={() => true}` so the built-in label match does not filter them a second time. |
| shortcut | `string | false` | no | 'mod+k' | Register a global keyboard shortcut that toggles the palette. `mod` is Cmd on macOS and Ctrl elsewhere. Set to `false` to disable. |
| showFooter | `boolean` | no | true | Show keyboard-shortcut hints in the footer. |
| size | `CommandPaletteVariants['size']` | no | 'md' | Maximum width of the palette panel. |
| slotClasses | `Partial<Record<CommandPaletteSlots, string>>` | no |  | Per-slot class overrides. An option row is built from four sources in order — the library's `item` classes, the library's classes for the row's state (`itemHighlighted` when selected, `itemDisabled` when the item is disabled, `itemDefault` otherwise), then your `item` entry, then your entry for that state slot. Each source displaces the earlier ones per Tailwind bucket, so an `item` entry that collides with a state class *removes* it: `slotClasses={{ item: 'bg-white' }}` also drops the selected row's `bg-primary-subtle`. Write the state slot as well to keep both. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Strip all default styles, the modal Dialog's included. |

### Types
```ts
interface CommandPaletteItem {
/** Unique identifier. Falls back to `label` when omitted. */
  id?: string;
  /** Display text shown in the list. */
  label: string;
  /**
   * Secondary line rendered under the label, truncated to one line. Use it for
   * context the label cannot carry — a description, or an excerpt around a
   * search match.
   */
  excerpt?: string;
  /** Group header this item belongs to. Items with the same category are grouped together. */
  category?: string;
  /** Optional keyboard shortcut displayed on the right side. */
  shortcut?: string;
  /**
   * Leading icon component. Pass an icon directly (`import { SearchIcon } from
   * '@urbicon-ui/blocks'`), not an icon *name* — a name would have to be
   * resolved through the registry at runtime, and that dynamic lookup drags all
   * the entire icon set into the consumer bundle (see docs/ICON-DESIGN.md). Rendered at
   * the slot's own size, inheriting `currentColor`.
   */
  icon?: IconComponent;
  /** Whether the item is non-selectable. @default false */
  disabled?: boolean;
  /** Arbitrary payload forwarded to `onSelect`. */
  data?: unknown;
}
```

```ts
type IconComponent = Component<IconProps>
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`wrapper`, `inputWrapper`, `input`, `inputIcon`, `clearButton`, `list`, `groupLabel`, `item`, `itemHighlighted`, `itemDefault`, `itemDisabled`, `itemIcon`, `itemText`, `itemLabel`, `itemExcerpt`, `itemShortcut`, `empty`, `footer`, `footerHint`, `kbd`, `separator`

---

## CompositionBar
Stacked bar with legend that breaks an aggregate value down into
its components. Suited for budget splits, pool composition, resource
allocation, token vesting — anywhere `pool = a + b + c` should be visible
at a glance.

Small segments (< 2% of the total width) are kept minimally visible;
hovering/focusing the bar or the legend highlights the counterpart in
sync. Tooltip content is fully overridable via the `tooltip` snippet.

**Import:** `import { CompositionBar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CompositionBar
  items={[
    { label: 'Gas',         value: 220609, intent: 'primary' },
    { label: 'Power',       value: 112731, intent: 'secondary' },
    { label: 'Maintenance', value:  36102, intent: 'success' }
  ]}
  formatValue={(v) => formatCurrency(v)}
  size="lg"
  legendPlacement="right"
  showTotal
/>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning
- size: lg, md, sm (default: md)
- dimmed: false, true
- fill: danger, neutral, primary, secondary, success, warning
- legendPlacement: bottom, left, right, top (default: bottom)
- orientation: horizontal, vertical (default: horizontal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `CompositionItem[]` | yes |  | Composition shares in the order they should appear in the bar. |
| ...CompositionBarVariants | `VariantProps` | no |  | Styling variants from CompositionBarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| formatPercent | `(percent: number) => string` | no |  | Format function for percentages. Default: 1 fraction digit, formatted with the active locale (e.g. `12.3 %`). |
| formatValue | `(value: number) => string` | no |  | Format function for values (tooltip, legend, total). |
| intent | `CompositionBarIntent` | no | 'primary' | Default intent for items without their own `intent`/`color`. |
| legendItem | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom rendering of a legend entry. Receives the item and its percentage. Fully replaces the default rendering (dot + label + value/percent). |
| minSegmentPercent | `number` | no | 1.5 | Minimum segment width in percent. Values below it are raised to this width so small shares stay visible. Larger segments are shrunk proportionally so the total still adds up to 100%. |
| onItemSelect | `(item: CompositionItem, index: number) => void` | no |  | Selection callback fired when a bar segment or legend entry is clicked. Receives the item and its index. Providing it makes the segments interactive (pointer cursor and click handling). |
| preset | `string` | no |  | Preset name (registered via `<BlocksProvider presets={{ CompositionBar: {...} }}>`). |
| showLegend | `boolean` | no | true | Show the legend. Position it with `legendPlacement`. |
| showPercentages | `boolean` | no | true | Show percentages in legend and tooltip. |
| showTotal | `boolean` | no | false | Render the total value after the legend. |
| showValues | `boolean` | no | false | Render the value directly inside the bar segment, in addition to the legend. Only segments wide enough (≥ 8% or ~40 px) show their value, so narrow ones do not overflow. Handy for print or PDF export, where there is no hover tooltip. |
| slotClasses | `Partial<Record<CompositionBarSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tooltip | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom tooltip content. Replaces the default layout (label, value, percent). |
| total | `number` | no |  | Optional fixed total value. Default: the sum of the item values. If the explicit total exceeds the sum, the remaining area is rendered neutrally ("unaccounted share"). If it is below the sum, segments are scaled to 100% and a console warning is emitted. |
| totalLabel | `string` | no |  | Label rendered before the total. Defaults to the localized "Total" label from the blocks i18n bundle. |
| unstyled | `boolean` | no |  | Remove all default classes; only the layout structure remains. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CompositionBar. Affects the component's physical footprint. Available options: lg, md, sm. |
| dimmed | `'false' | 'true'` | no |  | Controls the dimmed behavior and appearance of the CompositionBar component. Available options: false, true. |
| fill | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no |  | Controls the fill behavior and appearance of the CompositionBar component. Available options: danger, neutral, primary, and 3 more. |
| legendPlacement | `'bottom' | 'left' | 'right' | 'top'` | no | bottom | Controls the legendPlacement behavior and appearance of the CompositionBar component. Available options: bottom, left, right, top. |
| orientation | `'horizontal' | 'vertical'` | no | horizontal | Controls the orientation behavior and appearance of the CompositionBar component. Available options: horizontal, vertical. |

Inherited from:
- Omit<CompositionBarVariants, 'isHovered'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type CompositionBarIntent = | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'danger'
  | 'neutral'
```

```ts
interface CompositionItem {
/** Stable ID for highlight synchronization and snippet identity. */
  id?: string | number;
  /** Display label in the legend and the default tooltip. */
  label: string;
  /** Numeric value, defines the segment width. */
  value: number;
  /** Overrides the default intent from the component palette. */
  intent?: CompositionBarIntent;
  /** Raw color value (CSS color), bypasses the token system. Takes precedence over `intent`. */
  color?: string;
  /** Arbitrary metadata — passed through to snippets. */
  meta?: Record<string, unknown>;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`wrapper`, `barWrapper`, `bar`, `segment`, `segmentRest`, `tooltip`, `tooltipLabel`, `tooltipDetail`, `legend`, `legendItem`, `legendDot`, `legendLabel`, `legendValue`, `total`, `totalLabel`

---

## ConfirmDialog
Pre-configured Dialog for confirming a single, often
destructive action. Replaces the native `window.confirm()` with a
styleable, focus-trapped, keyboard-accessible modal that matches the
design system's intent palette.

`onConfirm` may be `async`; while the returned promise is pending the
dialog locks itself (no backdrop dismiss, no escape, confirm button
shows a spinner). Auto-closes on resolve; on reject it stays open and
re-enables, handing the error to `onError`.

**Import:** `import { ConfirmDialog } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  let confirmOpen = $state(false);
</script>
<Button intent="danger" onclick={() => (confirmOpen = true)}>Delete</Button>
<ConfirmDialog
  bind:open={confirmOpen}
  title="Delete project?"
  description="This cannot be undone."
  intent="danger"
  confirmLabel="Delete"
  onConfirm={async () => { await deleteProject(id); }}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| title | `string` | yes |  | Heading shown in the dialog header. |
| ...HTMLDialogAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'open' | 'title' | 'draggable') |
| cancelLabel | `string` | no |  | Label of the cancel button. Defaults to the localized `button.cancel`. |
| children | `Snippet` | no |  | Optional richer markup rendered below `description`. |
| class | `string` | no |  | Extra classes merged onto the dialog **panel** — the card, not the full-viewport `<dialog>` shell around it. Forwarded to `DialogProps.class`, which lands on the same element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| closeOnBackdropClick | `boolean` | no | true | Whether the backdrop click cancels. |
| closeOnEscape | `boolean` | no | true | Whether Escape cancels. |
| confirmIntent | `ConfirmIntent` | no |  | Override for the confirm button alone, leaving the header strip on `ConfirmDialogProps.intent`. Defaults to that `intent`; pass `'primary'` to put the accent on a neutral dialog's confirm button. |
| confirmLabel | `string` | no |  | Label of the confirm button. Defaults to the localized `button.confirm`. |
| description | `string` | no |  | Description rendered above the footer. Use `children` for richer markup. |
| intent | `DialogIntent` | no | 'danger' | Intent of the dialog. It tints the header title and icon for every value except `neutral`, which leaves them in the resting tone, and it is what the confirm button wears by default — `neutral` reaches that button unchanged, as a filled neutral confirm, because the accent belongs to the primary action rather than to every confirmation. |
| loading | `boolean` | no | false | Externally controlled loading flag. Combined with the internal `busy` flag from an async `onConfirm`. While truthy, the confirm button is busy (spinner, still focusable, clicks dropped), the cancel button is disabled, and dismissal is blocked — Escape, backdrop and the close button. A close request that is not a key press (back gesture, assistive tech) is vetoed twice; the browser honours the third without user activation, and that arrives as an ordinary close. |
| onCancel | `() => void` | no |  | Fired when the user cancels (button, backdrop, or Escape). |
| onConfirm | `() => void | Promise<void>` | no |  | Confirm handler. May return a promise — the dialog stays open and shows a loading state while it resolves, then auto-closes on success. If the promise rejects the dialog stays open and re-enables; the rejection is reported via `ConfirmDialogProps.onError`. |
| onError | `(error: unknown) => void` | no |  | Fired when an async `onConfirm` rejects (or a sync one throws). The dialog stays open and re-enables so the user can retry or cancel — use this to surface the failure (toast, inline message). Without a handler the rejection is logged DEV-only (`console.error`) and swallowed in production; it never escapes as an unhandled promise rejection. |
| open | `boolean` | no |  | Controls visibility. Supports bind:open. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ConfirmDialog: {...} }}>`. Resolved against the **`ConfirmDialog`** key, not `Dialog`: a preset written for the confirmation would otherwise style every dialog under the provider. `defaults.Dialog` still applies — the resolved preset reaches Dialog as instance `slotClasses`, so it wins over the provider's dialog-wide defaults and loses to `slotClasses` / `class` written on this component. A preset's `overrides` rules are matched against what you wrote here plus Dialog's own variant defaults. Dialog's three axes (`size`, `placement`, `intent`) are all received rather than derived, so no such mismatch exists today — see #360 for the shape it takes where an axis is derived. |
| slotClasses | `Partial<Record<DialogSlots, string>>` | no |  | Per-slot class overrides, forwarded to the underlying Dialog. Slots: dialog | backdrop | panel | content | header | title | body | footer. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| transitionDuration | `number` | no |  | Override the enter/exit animation duration in milliseconds, forwarded to the underlying `Dialog`. Defaults to the overlay token `--blocks-overlay-enter-duration` / `--blocks-overlay-exit-duration` (200ms / 180ms). Respects `prefers-reduced-motion`. |
| transitionEasing | `(t: number) => number` | no |  | Override the enter/exit easing function, forwarded to the underlying `Dialog`. Defaults to the overlay token easing (`quintOut`). |
| unstyled | `boolean` | no | false | Strip the underlying Dialog's default styles. Combine with `slotClasses` for a fully custom appearance. |

Inherited from:
- Omit<HTMLDialogAttributes, 'children' | 'open' | 'title' | 'draggable'> (omit-pattern)

### Types
```ts
type ConfirmIntent = DialogIntent
```

```ts
type DialogIntent = NonNullable<DialogVariants['intent']>
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

---

## CopyButton
One-tap copy-to-clipboard button with built-in success feedback (the icon
swaps to a check and the intent flips to success for a moment). Icon-only by default;
pass `label` for the string shorthand or `children` to fill it like any other Button.
Forwards `variant`/`intent`/`size`/`tier` to the underlying Button, so it inherits the
full button styling vocabulary.

**Import:** `import { CopyButton } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CopyButton value="npm i

```svelte
<CopyButton value={apiKey} label="Copy key" variant="outlined" />
```

### Variants
- size: 2xs, lg, md, sm, xl, xs (default: md)
- state: copied, error, idle (default: idle)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| value | `string` | yes |  | The text written to the clipboard when pressed. |
| ...HTMLButtonAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'value' | 'onclick' | 'class' | 'disabled' | 'children') |
| children | `Snippet<[CopyPhase]>` | no |  | Button content, like any other Button — an icon plus text, a `Kbd`, whatever the action needs. Wins over `label`, which stays as the string shorthand for the common case. Receives the copy phase, so the content can answer the copy itself; ignoring the argument keeps the content static while the icon and intent still flip. |
| class | `string` | no |  | Additional CSS class merged onto the underlying Button. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| copiedLabel | `string` | no | the i18n "Copied" string | Visible label shown for `timeout` ms after a successful copy. |
| disabled | `boolean` | no | false | Whether the button is disabled |
| hideIcon | `boolean` | no | false | Hide the copy/check icon (label-only). |
| intent | `'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral'` | no |  | Inherited from ButtonProps. |
| label | `string` | no |  | Optional visible label next to the icon. When omitted the button is icon-only. |
| onCopy | `(value: string) => void` | no |  | Called with `value` after it is written to the clipboard. |
| onError | `(error: unknown) => void` | no |  | Called with the thrown error when the clipboard write fails (permission denied, insecure context, …). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CopyButton: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent. |
| slotClasses | `Partial<Record<CopyButtonSlots, string>>` | no |  | Per-slot class overrides. Slots: base | icon | label. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tier | `'commit' | 'modify'` | no |  | Inherited from ButtonProps. |
| timeout | `number` | no | 2000 | How long the success/error state stays before reverting, in ms. `0` keeps it until the next copy. |
| unstyled | `boolean` | no |  | Strip all default styles; forwarded to the underlying Button. |
| variant | `'filled' | 'outlined' | 'ghost' | 'text'` | no |  | Inherited from ButtonProps. |
| size | `'2xs' | 'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the CopyButton. Affects the component's physical footprint. Available options: 2xs, lg, md, and 3 more. |
| state | `'copied' | 'error' | 'idle'` | no | idle | Controls the visual state representation of the CopyButton to communicate status to users. Available options: copied, error, idle. |

Inherited from:
- Pick<ButtonProps, 'variant' | 'intent' | 'size' | 'tier' | 'disabled'> (pick-pattern)
- Omit<HTMLButtonAttributes, 'value' | 'onclick' | 'class' | 'disabled' | 'children'> (omit-pattern)

### Types
```ts
type CopyPhase = 'idle' | 'copied' | 'error'
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

### Slots (slotClasses keys)
`base`, `icon`, `label`

---

## CurrencyInput
Locale-aware monetary input that stores values in **minor units**
(cents for EUR/USD, pennies for GBP, etc.). The field is a fixed-scale mask
rather than free text: it re-formats on every keystroke, the fraction is a
fixed row of slots (deleting a cent digit zeroes it instead of pulling the
separator along), and the caret is carried as a digit position so the grouping
separators appearing and disappearing under it never move it. The currency
symbol is rendered as a static adornment (left or right of the field) and
stays visible at all times.

Storing cents as integers avoids floating-point drift when summing, sorting,
or persisting amounts. Parsing also goes through string splits — never
`parseFloat * factor` — so `1,005` lands on the `100` minor units it reads as,
rather than the `99` IEEE-754 drift produces. A digit past the last place is
truncated, never rounded: `1,999` is `199`. Use
`CurrencyInputProps.precision` for currencies with non-2 decimal
places (JPY = 0, BHD = 3).

**Import:** `import { CurrencyInput } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
// "1.234,56 €" under a `de` provider, "1,234.56 €" under `en` (the default)
let priceCents = $state(1234_56);
</script>
<CurrencyInput label="Price" bind:value={priceCents} />
```

```svelte
<CurrencyInput
label="Amount"
bind:value={amountCents}
locale="en-US"
currency="USD"
symbolPosition="prefix"
/>
```

```svelte
<CurrencyInput bind:value={yen} locale="ja-JP" currency="JPY" precision={0} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| autoComplete | `string` | no |  | HTML autocomplete hint for browser autofill. |
| children | `Snippet` | no |  | Snippet content rendered below the input for advanced layouts. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clearable | `boolean` | no | false | Show a clear button when the input has a value. Press Escape or click the button to clear. Fires `onClear` after clearing. |
| currency | `string` | no | 'EUR' | ISO-4217 currency code. Determines the symbol when `CurrencyInputProps.symbolPosition` is `'prefix'` or `'suffix'`. |
| disabled | `boolean` | no | false | disabled property |
| error | `string` | no |  | Error message below the input. When set, overrides `helper` and forces danger border styling regardless of `intent`. |
| helper | `string` | no |  | Helper text below the input — hidden when `error` is present. |
| label | `string` | no |  | Label text displayed above the input, auto-linked via `for`/`id`. |
| leftIcon | `Snippet` | no |  | Icon snippet rendered on the left side of the input field. |
| leftIconAriaLabel | `string` | no |  | Accessible label for the clickable left icon button. Required when `onLeftIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| locale | `string` | no | 'auto' | BCP 47 locale used for formatting (`Intl.NumberFormat`). Controls the grouping separator (`.` vs `,`) and decimal separator. Defaults to `'auto'`, which follows the active `<I18nProvider>` locale — SSR-safe (server and client resolve the same locale, no hydration flash) and consistent with the rest of the library's number formatting. Falls back to the base locale (`en`) when no provider is mounted. Pass an explicit BCP 47 string (e.g. `'de-DE'`, `'ja-JP'`) to override. `currency` is intentionally **not** auto-detected, since it is orthogonal to locale (a `de-CH` user may still bill in EUR). |
| mint | `InputProps['mint']` | no | 'none' | Micro-interaction preset forwarded to the inner Input. Redeclared from InputProps so the inheritance is a documented contract rather than an accident of the Omit list. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the input element. Only applies while not disabled. |
| name | `string` | no |  | Shared `name` for native form submission. When set, a hidden input is rendered carrying the integer minor-unit value (matching `CurrencyInputProps.value`) — never the locale-formatted display string. The visible Input itself stays unnamed so the formatted text is not submitted alongside.  Empty / `null` values submit as `""` so the field still appears in the FormData payload (consumers can disambiguate "untouched" via server-side schema parsing). |
| onLeftIconClick | `() => void` | no |  | When provided, the left icon becomes a clickable button. |
| onRightIconClick | `() => void` | no |  | When provided, the right icon becomes a clickable button. |
| onValueChange | `(cents: number | null) => void` | no |  | Fires whenever the parsed value changes. Receives the new value in minor units (or `null`). |
| persistDebounceMs | `number` | no | 300 | Debounce interval (ms) for storage writes. |
| persistKey | `string` | no |  | Key for persisting the input value to storage. |
| persistNamespace | `string` | no |  | Namespace (e.g. user id) to scope the persist key. |
| persistStorage | `'localStorage' | 'sessionStorage'` | no | 'localStorage' | Storage backend for persistence. |
| persistVersion | `number` | no | 1 | Version stamp included in the storage key. |
| precision | `number` | no | 2 | Number of fractional digits stored in `CurrencyInputProps.value`. For most currencies `2`; for JPY use `0`, for BHD/KWD use `3`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CurrencyInput: {...} }}>`. Resolved against the **`CurrencyInput`** key, not `Input`: a preset written for the money field would otherwise style every text field under the provider. `defaults.Input` still applies — the resolved preset reaches Input as instance `slotClasses`, so it wins over the provider's input-wide defaults and loses to `slotClasses` / `class` written on this component. A preset's `overrides` rules are matched against what you wrote here plus Input's own variant defaults; an axis Input derives or coerces for itself (`tier`, `messageType`, `error`, `hasRightIcon`, `iconPosition`) can match the wrong state — #360. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Input: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| readonly | `boolean` | no | false | readonly property |
| required | `boolean` | no | false | Adds a required asterisk to the label and sets the native `required` attribute. |
| rightIcon | `Snippet` | no |  | Icon snippet rendered on the right side of the input field. |
| rightIconAriaLabel | `string` | no |  | Accessible label for the clickable right icon button. Required when `onRightIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| slotClasses | `Partial<Record<InputSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | container | base (the `<input>` element) | label | requiredMark | message | iconContainer | iconButton | iconDecoration. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| symbolPosition | `CurrencySymbolPosition` | no | 'suffix' | Where the currency symbol is rendered as a static adornment. The symbol is shown in the input's left or right icon slot (always visible, including while focused) — it is never embedded in the editable text. Use `'none'` for headless numeric editing (no symbol shown at all). |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |
| value | `number | null` | no | null | Current monetary value in **minor units** (e.g. cents). Use `null` for "no value entered yet"; the input renders empty. |

Inherited from:
- Omit<
    InputProps,
    | 'type'
    | 'value'
    | 'onClear'
    | 'inputmode'
    | 'oninput'
    | 'onchange'
    | 'onblur'
    | 'onfocus'
    | 'name'
  > (omit-pattern)

### Types
```ts
type CurrencySymbolPosition = 'prefix' | 'suffix' | 'none'
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

---

## DatePicker
Date input with calendar popup for selecting a single date. Supports min/max constraints, disabled dates, and format customization.

The `value` prop accepts either a `Date` or an ISO timestamp string —
useful when surrounding state is hydrated from JSON or a SQL driver
that serialises timestamps as strings. `onValueChange` always reports
back a `Date` (or `undefined`); use `toDateInputValue` from
`@urbicon-ui/blocks` to project it back into a string state.

**Import:** `import { DatePicker } from '@urbicon-ui/blocks';`

### Examples
```svelte
<DatePicker
  bind:value={selectedDate}
  label="Date of birth"
  placeholder="Select a date"
  locale="en-US"
  clearable
/>
```

```svelte
<script>
import { DatePicker, toDateInputValue } from '@urbicon-ui/blocks';
let isoDate = $state('2026-04-22T08:00:00Z');
</script>
<DatePicker
value={isoDate}
onValueChange={(d) => (isoDate = toDateInputValue(d))}
label="Period start"
/>
```

```svelte
<DatePicker
  bind:value={deadline}
  label="Deadline"
  minDate={new Date()}
  maxDate={new Date(2026, 11, 31)}
  isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
  required
  error={deadlineError}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| calendarVariant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style of the calendar popup. |
| class | `string` | no |  | class property. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clearable | `boolean` | no | true | Allow clearing the selected date. |
| closeOnClickOutside | `boolean` | no | true | Whether the popover closes on outside click. |
| closeOnEscape | `boolean` | no | true | Whether the popover closes on Escape key. |
| closeOnSelect | `boolean` | no | true | Close popover after selecting a date. |
| defaultMonth | `MonthIndex` | no |  | Default month shown when the picker opens without a value. `0`–`11`. |
| defaultYear | `number` | no |  | Default year shown when the picker opens without a value. |
| disabled | `boolean` | no | false | Disable the entire picker. |
| disabledDates | `Date[]` | no |  | Specific dates that are disabled. |
| displayFormat | `DateFormatOptions` | no |  | Intl.DateTimeFormat options for the displayed date. |
| error | `string` | no |  | Error message shown below the input. |
| fixedWeeks | `boolean` | no | true | Always show 6 week rows, so the overlay keeps its height while paging months. Set `false` to let it shrink to 4 or 5 rows. |
| helper | `string` | no |  | Helper text shown below the input. |
| inputVariant | `'outlined' | 'filled' | 'ghost' | 'underline'` | no | 'outlined' | Input variant. |
| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate that disables specific dates. Errors thrown by the predicate are caught and logged; the date is then treated as allowed so a faulty consumer callback can't take the picker down. |
| label | `string` | no |  | Label above the input. |
| locale | `string` | no | 'auto' | BCP 47 locale tag for date formatting — month names, weekday names and the header title. Defaults to `'auto'`, which follows the active `<I18nProvider>` locale, so an app that already declares its language does not have to repeat it here. SSR-safe: the locale comes from context, so the server and the client resolve the same tag (`Intl` with `undefined` would follow the runtime and disagree across hydration). Falls back to the base locale (`en`) when no provider is mounted. Pass an explicit tag (e.g. `'de-DE'`, `'ja-JP'`) to override. |
| maxDate | `Date` | no |  | Latest selectable date. |
| minDate | `Date` | no |  | Earliest selectable date. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset forwarded to the inner Input. |
| name | `string` | no |  | Shared `name` for native form submission. When set, a hidden input is rendered carrying the serialized date — matching what the user picked, so the visible input's locale-formatted display string is never submitted instead.  Empty / unset values submit as `""` so the field still appears in the FormData payload. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the popover opens or closes. |
| onValueChange | `(value: Date | undefined) => void` | no |  | Fires when the selected date changes. |
| placeholder | `string` | no |  | Placeholder when no date is selected. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| required | `boolean` | no | false | Mark input as required. |
| showOutsideDays | `boolean` | no | true | Show days from adjacent months. |
| showWeekNumbers | `boolean` | no | false | Show ISO week numbers. |
| size | `'xs' | 'sm' | 'md' | 'lg' | 'xl'` | no | 'md' | Component size. |
| slotClasses | `Partial<Record<DatePickerSlots, string>>` | no |  | Per-slot class overrides. `base` is the positioning wrapper the field and the popover anchor sit in, `iconButton` the clear / open-calendar buttons in the field's right-icon area. The field itself is an `Input` and the overlay a `Calendar`; restyle those under their own names. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip the default tv() classes of the wrapper AND of the Input, Popover and Calendar it renders; `slotClasses` and `class` then stand alone. |
| value | `Date | string | null` | no |  | Currently selected date. Supports bind:value. Accepts a `Date`, an ISO timestamp string, or `null` / `undefined`. Internally coerced to a `Date`; the picker emits `Date` instances via `DatePickerProps.onValueChange`. When both `bind:value` and `onValueChange` are wired, both fire on every user-driven change — pick one to drive side-effects (saves, analytics) to avoid duplicates. |
| valueFormat | `'date' | 'iso'` | no | 'date' | Format used to serialise the date for the hidden form input. - `'date'` (default): `YYYY-MM-DD` in the local timezone — matches   the native `<input type="date">` payload and Zod schemas like   `z.string().regex(/^\d{4}-\d{2}-\d{2}$/).transform((v) => new Date(v))`. - `'iso'`: full ISO-8601 with `Z` suffix (UTC). Use this when the   downstream schema expects a parseable timestamp string (e.g. a   Drizzle `timestamp({ withTimezone: true, mode: 'date' })` column).  Only relevant when `DatePickerProps.name` is set. |
| weekStartsOn | `WeekdayIndex` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface DatePickerPreset {
label: string;
  value: Date;
}
```

```ts
interface DateRangePreset {
label: string;
  value: DateRange;
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MonthIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
```

```ts
type WeekdayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6
```

```ts
interface DateRange {
start: Date;
  end: Date;
}
```

```ts
type DateFormatOptions = Intl.DateTimeFormatOptions
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `iconButton`

---

## DateRangePicker
Date range picker with a dual-calendar popup for selecting a start and end date — min/max constraints, disabled dates, and native form submission via paired hidden inputs.

**Import:** `import { DateRangePicker } from '@urbicon-ui/blocks';`

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| calendarVariant | `'default' | 'bordered' | 'ghost'` | no |  | calendarVariant property |
| class | `string` | no |  | class property. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clearable | `boolean` | no |  | clearable property |
| closeOnClickOutside | `boolean` | no | true | Whether the popover closes on outside click. |
| closeOnEscape | `boolean` | no | true | Whether the popover closes on Escape key. |
| closeOnSelect | `boolean` | no | true | Close popover after selecting both dates. |
| defaultMonth | `MonthIndex` | no |  | Default month shown when the picker opens without a value. `0`–`11`. |
| defaultYear | `number` | no |  | Default year shown when the picker opens without a value. |
| disabled | `boolean` | no |  | disabled property |
| disabledDates | `Date[]` | no |  | disabledDates property |
| displayFormat | `DateFormatOptions` | no |  | Intl.DateTimeFormat options for displayed dates. |
| error | `string` | no |  | error property |
| fixedWeeks | `boolean` | no |  | fixedWeeks property |
| helper | `string` | no |  | helper property |
| inputVariant | `'outlined' | 'filled' | 'ghost' | 'underline'` | no |  | inputVariant property |
| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate that disables specific dates. Throws are caught and logged; the date is then treated as allowed. |
| label | `string` | no |  | Label above the input. |
| locale | `string` | no | 'auto' | BCP 47 locale tag for date formatting — month names, weekday names and the header title. Defaults to `'auto'`, which follows the active `<I18nProvider>` locale, so an app that already declares its language does not have to repeat it here. SSR-safe: the locale comes from context, so the server and the client resolve the same tag (`Intl` with `undefined` would follow the runtime and disagree across hydration). Falls back to the base locale (`en`) when no provider is mounted. Pass an explicit tag (e.g. `'de-DE'`, `'ja-JP'`) to override. |
| maxDate | `Date` | no |  | maxDate property |
| minDate | `Date` | no |  | minDate property |
| mint | `MintProp` | no | 'none' | Micro-interaction preset forwarded to the inner Input. |
| name | `string` | no |  | Shared base `name` for native form submission. When set, two hidden inputs are rendered — `{name}_start` and `{name}_end` — each carrying the serialized date, so the visible input's locale-formatted display string is never submitted instead.  Empty range submits both halves as `""`. The `_start` / `_end` convention reflects the picker's domain language — date ranges read naturally as start/end rather than min/max. |
| onClickOutside | `() => void` | no |  | Notification only — does NOT govern close behavior. |
| onEscape | `() => void` | no |  | Notification only — does NOT govern close behavior. |
| onOpenChange | `(open: boolean) => void` | no |  | onOpenChange property |
| onValueChange | `(value: DateRange | undefined) => void` | no |  | Fires when the selected range changes. During calendar selection the user clicks twice — once to set the start, once to set the end. `onValueChange` only fires when the range is *complete* (start ≠ end); the intermediate `{ start: d, end: d }` state does NOT fire this callback. Use `bind:value` if you need the in-progress state. |
| placeholder | `string` | no |  | Placeholder when no range is selected. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| required | `boolean` | no |  | required property |
| showOutsideDays | `boolean` | no |  | showOutsideDays property |
| showWeekNumbers | `boolean` | no |  | showWeekNumbers property |
| size | `'xs' | 'sm' | 'md' | 'lg' | 'xl'` | no |  | size property |
| slotClasses | `Partial<Record<DatePickerSlots, string>>` | no |  | Per-slot class overrides. `base` is the positioning wrapper the field and the popover anchor sit in, `iconButton` the clear / open-calendar buttons in the field's right-icon area. The field itself is an `Input` and the overlay a `Calendar`; restyle those under their own names. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip the default tv() classes of the wrapper AND of the Input, Popover and Calendar it renders; `slotClasses` and `class` then stand alone. |
| value | `DateRange` | no |  | Currently selected date range. Supports bind:value. |
| valueFormat | `'date' | 'iso'` | no | 'date' | Format used to serialise both range halves. See `DatePickerProps.valueFormat` for semantics. |
| weekStartsOn | `WeekdayIndex` | no |  | weekStartsOn property |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface DatePickerPreset {
label: string;
  value: Date;
}
```

```ts
interface DateRangePreset {
label: string;
  value: DateRange;
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MonthIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
```

```ts
type WeekdayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6
```

```ts
interface DateRange {
start: Date;
  end: Date;
}
```

```ts
type DateFormatOptions = Intl.DateTimeFormatOptions
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

---

## Dialog
Overlay dialog built on native dialog element. Can be used as a simple
content-agnostic overlay or as a structured dialog with title, optional header icon and
footer. `intent` tints the header markers (title, icon) and is exposed as `data-intent`
on the panel; the panel surface itself stays neutral, because a tinted surface under a
consumer's form or table would hijack that content's contrast ratios.

**Import:** `import { Dialog } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Dialog bind:open>
<p>Are you sure?</p>
<Button onclick={() => (open = false)}>Close</Button>
</Dialog>
```

```svelte
<Dialog bind:open title="Confirm deletion" intent="danger">
<p>This action cannot be undone.</p>
{#snippet footer()}
<Button variant="ghost" onclick={() => (open = false)}>Cancel</Button>
<Button intent="danger" onclick={handleDelete}>Delete</Button>
{/snippet}
</Dialog>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- size: full, fullscreen, lg, md, sm, xl (default: sm)
- placement: center, top (default: center)
  - center — Mobile keeps the bottom-sheet alignment so a swipe-up gesture hits the bottom edge; desktop opens centered.

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Dialog body content. When `title` is omitted the content fills the entire panel. |
| ...HTMLDialogAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'open' | 'draggable') |
| class | `string` | no |  | Additional CSS classes applied to the dialog panel. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| closeOnBackdropClick | `boolean` | no | true | Whether clicking the backdrop dismisses the dialog.  Turning this off together with `closeOnEscape` and `hideCloseButton` is a legitimate pattern for a forced choice (terms to accept, data loss to confirm, an expired session) — but only when the dialog itself renders the action that resolves it. Without one there is no way out, and DEV warns. |
| closeOnEscape | `boolean` | no | true | Whether pressing Escape dismisses the dialog.  The ARIA APG recommends Escape and does not forbid disabling it; the same condition as `closeOnBackdropClick` applies — with every exit closed, the dialog must carry its own action.  Escape is dismissed one layer at a time: a control INSIDE the dialog that handles Escape itself — an open `Select`/`Combobox`/`Menu` panel, a `clearable` `Input` with text in it — consumes the key, and the dialog stays up. The second Escape closes the dialog. This is about controls in the content; it does not apply to a consumer `onkeydown` on the Dialog itself, which cannot veto the dismiss (see utils/compose-handlers.ts) — use this prop for that. |
| draggable | `boolean` | no | false | Let the user reposition the dialog by dragging its header. Off by default. The structured header (rendered when `title` is set) becomes the drag handle; the close button and any header controls stay clickable, and the offset resets each time the dialog reopens. Most useful for a dialog the user may want to shove aside to see the content behind it. Requires a `title` — without a header there is nothing to grab. Overrides the native HTML `draggable` attribute, which has no meaningful use on a dialog. |
| footer | `Snippet` | no |  | Action buttons rendered in a footer bar. Only rendered when provided. |
| hideCloseButton | `boolean` | no | false | Hides the built-in close button. Only takes effect when `title` is also set — the close button only renders in the structured (titled) header. Without a title, no close button exists to hide.  The last of the three exits; see `closeOnBackdropClick` for what closing all of them requires. |
| icon | `Snippet` | no |  | Icon rendered before the title in the header bar. Takes its colour from `intent`, so a bare icon component is enough — no wrapper needed. Marked `aria-hidden`: it repeats the intent the title already carries in words. Requires `title` (no header renders without one). |
| intent | `DialogVariants['intent']` | no | 'neutral' | Semantic purpose marker (e.g. `danger` for destructive actions). Tints the header markers — the title and, when given, `icon`. The panel surface stays neutral by design: this is a container for arbitrary content, and a tinted surface would hijack the contrast ratios of the form, table or code block inside it (the Toast makes the same split). The value is additionally exposed on the panel as `data-intent="…"` for presets and CSS overrides. |
| onClose | `() => void` | no |  | Fires when the dialog is dismissed via Escape, backdrop click, or close button. |
| open | `boolean` | no |  | Controls whether the dialog is visible. Supports bind:open. |
| placement | `DialogVariants['placement']` | no | 'center' | Vertical placement within the viewport. Use 'top' for command-palette style positioning. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Dialog: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `DialogVariants['size']` | no | 'sm' | Controls the maximum width of the dialog panel. |
| slotClasses | `Partial<Record<DialogSlots, string>>` | no |  | Per-slot class overrides merged with variant styles. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| title | `string` | no |  | Heading displayed in a header bar. Enables the structured header/body/footer layout. |
| transitionDuration | `number` | no |  | Override the enter/exit animation duration in milliseconds. Defaults to the overlay token `--blocks-overlay-enter-duration` / `--blocks-overlay-exit-duration` (200ms / 180ms). Set globally via the CSS custom properties or per-instance via this prop. Respects `prefers-reduced-motion`. |
| transitionEasing | `(t: number) => number` | no |  | Override the enter/exit easing function. Defaults to the overlay token easing (`quintOut`). |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with slotClasses for fully custom appearance. |

Inherited from:
- Omit<HTMLDialogAttributes, 'children' | 'open' | 'draggable'> (omit-pattern)

### Types
```ts
type DialogSize = NonNullable<DialogVariants['size']>
```

```ts
type DialogPlacement = NonNullable<DialogVariants['placement']>
```

```ts
type DialogIntent = NonNullable<DialogVariants['intent']>
```

### Slots (slotClasses keys)
`dialog`, `backdrop`, `panel`, `content`, `header`, `titleGroup`, `icon`, `title`, `closeButton`, `body`, `footer`

---

## DocsLayout
Standard documentation page layout with optional table of contents.
Provides a responsive two-column layout: a rail on desktop, a popover in the
pinned strip below it.

The strip renders whenever it has something to carry — a title or
`breadcrumbs` (shown as a trail), a `sourceHref`, or the mobile table of
contents. It stays pinned for the whole scroll, and the hero title morphs
into its last crumb once the header scrolls out of view.

Anchor jumps land clear of it: the strip publishes its height, and every
`<Section>` reads the resulting `--docs-anchor-offset` as its scroll margin.

**Import:** `import { DocsLayout } from '@urbicon-ui/docs';`

### Examples
```svelte
<DocsLayout
  title="Badge"
  description="Status and labels"
  breadcrumbs={[
    { label: 'Blocks', href: '/blocks' },
    { label: 'Primitives', href: '/blocks/primitives' }
  ]}
  showToc
  navigation={nav}
>
  <Section id="examples">...</Section>
</DocsLayout>
```

### Variants
- centered: true (default: false)
- maxWidth: 2xl, 7xl, lg, md, sm, xl (default: lg)
- sidebar: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...DocsLayoutVariantProps | `VariantProps` | no |  | Styling variants from DocsLayoutVariantProps |
| breadcrumbs | `BreadcrumbItem[]` | no |  | Structured breadcrumb trail (ancestors only, title is appended automatically). A top-level page needs none — the strip then shows the title alone. |
| children | `Snippet` | no |  | Page body content. |
| class | `string` | no |  | Extra classes merged onto the root container. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| description | `string` | no |  | Short description rendered below the title. |
| navigation | `TocNavigationItem[]` | no | [] | Navigation items for the table of contents (nested children supported). |
| related | `RelatedLink[]` | no |  | Optional related-links list — passed through to the TableOfContents as a `// RELATED` block below the page sections. Each entry needs a pre-resolved `href`; the layout does not call `resolve()` on it. |
| showCodeToggle | `boolean` | no | true | Show the global code-visibility toggle for collapsing all code examples. |
| showToc | `boolean` | no | false | Show a table of contents: the sticky rail on desktop, a popover in the pinned strip below `lg`. Both halves follow this one prop, so switching it off leaves neither behind. Needs `navigation` to have entries. |
| slotClasses | `Partial<Record<DocsLayoutSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| sourceHref | `string` | no |  | GitHub blob URL for the component's source file — rendered as a `source ↗` link next to the stability badge when present. |
| stability | `'experimental' | 'beta' | 'stable' | 'deprecated'` | no |  | Editorial stability badge — drives the `[STABLE]` / `[BETA]` / etc. stamp above the page title. When omitted, no badge renders; the default is applied upstream in docs-gen, so component pages receive `'stable'` automatically via `componentData?.stability`. |
| title | `string` | no |  | Page title rendered as an h1 in the header area. |
| unstyled | `boolean` | no | false | Remove all default tv styles. |
| centered | `'true'` | no | false | Controls the centered behavior and appearance of the DocsLayout component. Available options: true. |
| maxWidth | `'2xl' | '7xl' | 'lg' | 'md' | 'sm' | 'xl'` | no | lg | Controls the maxWidth behavior and appearance of the DocsLayout component. Available options: 2xl, 7xl, lg, and 3 more. |
| sidebar | `'true'` | no | false | Controls the sidebar behavior and appearance of the DocsLayout component. Available options: true. |

Inherited from:
- DocsLayoutVariantProps (external)

### Types
```ts
interface BreadcrumbItem {
label: string;
  href?: string;
}
```

```ts
interface RelatedLink {
label: string;
  href: string;
}
```

```ts
interface TocNavigationItem {
id: string;
  title: string;
  href?: string;
  children?: Array<{ id: string; title: string; href?: string }>;
}
```

### Slots (slotClasses keys)
`container`, `stickyBarHeight`, `wrapper`, `main`, `content`, `header`, `headerInner`, `title`, `subtitle`, `stickyBar`, `stickyBarInner`, `stickyToc`, `stickyTocButton`, `stickyTocNav`, `stickyTocLink`

---

## DonutChart
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Donut (or pie) chart for part-to-whole composition. Zero-
dependency SVG arcs on the design-token palette, dark-mode aware, with an
optional center total, legend, and a screen-reader data-table fallback. Set
`innerRadiusRatio={0}` for a full pie. Pairs with CompositionBar for the
linear equivalent.

**Import:** `import { DonutChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<DonutChart
  data={[
    { label: 'Direct', value: 45 },
    { label: 'Referral', value: 30 },
    { label: 'Organic', value: 25 }
  ]}
  showTotal
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `DonutDatum[]` | yes |  | Slices; angle is each value's share of the total. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| formatValue | `(value: number) => string` | no |  | Format values for the center total, tooltips, and the data table. |
| innerRadiusRatio | `number` | no | 0.6 | Inner-hole radius as a fraction of the outer radius (0 = pie). |
| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
| padAngle | `number` | no | 0 | Gap between slices in degrees. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| showLegend | `boolean` | no | true | Show the legend. |
| showTotal | `boolean` | no | false | Show the summed total in the center hole. |
| size | `number` | no | 220 | Square SVG size in px. |
| slotClasses | `DonutChartSlotClasses` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| totalLabel | `string` | no |  | Caption under the center total (e.g. "Total"). |
| unstyled | `boolean` | no |  | Remove all default tv classes. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
interface DonutDatum {
/** Slice label (legend + data table). */
  label: string;
  /** Numeric value; the slice angle is its share of the total. */
  value: number;
  /** Explicit color; defaults to the cycled categorical palette. */
  color?: string;
}
```

```ts
type DonutChartSlotClasses = Partial<Record<DonutChartSlot, string>>
```

```ts
type DonutChartSlot = (typeof DONUT_CHART_SLOTS)[number]
```

---

## Drawer
Slide-in panel overlay from any edge of the viewport.
Uses native dialog with focus trap, backdrop click dismiss, and Escape key support.

**Import:** `import { Drawer } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Drawer bind:open title="Settings" placement="right">
  <p>Drawer content here</p>
</Drawer>
```

```svelte
<Drawer bind:open title="Menu" placement="left" size="sm">
  <nav>...</nav>
</Drawer>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- size: full, lg, md, sm, xl (default: md)
- accentEdge: false, true (default: false)
- placement: bottom, left, right, top (default: right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Content rendered inside the drawer body. |
| ...HTMLDialogAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'open') |
| accentEdge | `DrawerVariants['accentEdge']` | no | false | Tint the panel's docked (viewport-facing) edge with a 2px accent border in the `intent` colour — `border-right` for `left`, `border-left` for `right`, `border-bottom` for `top`, `border-top` for `bottom`. Off by default, keeping symmetry with Dialog; opt in for a coloured seam that ties the drawer to a semantic purpose (e.g. a `danger` confirm drawer). |
| class | `string` | no |  | Additional CSS classes applied to the drawer panel. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| closeOnBackdropClick | `boolean` | no | true | Whether clicking the backdrop closes the drawer. |
| closeOnEscape | `boolean` | no | true | Whether pressing Escape closes the drawer.  Escape is dismissed one layer at a time: a control INSIDE the drawer that handles Escape itself — an open `Select`/`Combobox`/`Menu` panel, a `clearable` `Input` with text in it — consumes the key, and the drawer stays up. The second Escape closes the drawer. This is about controls in the content; it does not apply to a consumer `onkeydown` on the Drawer itself, which cannot veto the dismiss (see utils/compose-handlers.ts) — use this prop for that. |
| footer | `Snippet` | no |  | Action buttons rendered in the drawer footer. |
| hideCloseButton | `boolean` | no | false | Hides the built-in close button in the header. |
| intent | `DrawerVariants['intent']` | no | 'neutral' | Semantic purpose marker (mirrors Dialog). By default the Drawer paints no accent border — the value is exposed on the panel as `data-intent="…"` so consumers can hook presets, CSS overrides, or icon/title color via their own snippets. Set `accentEdge` to also tint the docked edge in this colour. |
| onClose | `() => void` | no |  | Fires when the drawer is dismissed via Escape, backdrop click, or close button. |
| open | `boolean` | no |  | Controls whether the drawer is visible. Supports `bind:open`. |
| placement | `DrawerVariants['placement']` | no | 'right' | Edge of the viewport from which the drawer slides in. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Drawer: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `DrawerVariants['size']` | no | 'md' | Width (for left/right) or height (for top/bottom) of the drawer panel. |
| slotClasses | `Partial<Record<DrawerSlots, string>>` | no |  | Per-slot class overrides merged with variant styles. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| title | `string` | no |  | Heading displayed in the drawer header. |
| transitionDuration | `number` | no |  | Override the enter/exit animation duration in milliseconds. Defaults to the overlay token `--blocks-overlay-enter-duration` / `--blocks-overlay-exit-duration` (200ms / 180ms). Respects `prefers-reduced-motion`. |
| transitionEasing | `(t: number) => number` | no |  | Override the enter/exit easing function. Defaults to the overlay token easing (`quintOut`). |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with slotClasses for fully custom appearance. |

Inherited from:
- Omit<HTMLDialogAttributes, 'children' | 'open'> (omit-pattern)

### Slots (slotClasses keys)
`dialog`, `backdrop`, `panel`, `header`, `title`, `closeButton`, `body`, `footer`

---

## EmptyState
Centered placeholder block for "no data yet" / "no results"
states. Pairs an optional icon with a heading, supporting text, and an
optional call-to-action slot.

**Import:** `import { EmptyState } from '@urbicon-ui/blocks';`

### Examples
```svelte
<EmptyState
  icon={BuildingIcon}
  title="No apartments yet"
  description="Get started by adding the first apartment to the system."
>
  {#snippet cta()}
    <Button intent="primary" onclick={openCreate}>Add apartment</Button>
  {/snippet}
</EmptyState>
```

### Variants
- density: compact, default (default: default)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| title | `string` | yes |  | Heading line. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'title') |
| children | `Snippet` | no |  | Optional richer content rendered below the description. |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| cta | `Snippet` | no |  | Action buttons rendered below the description. |
| density | `'compact' | 'default'` | no | 'default' | Visual density. `compact` is suitable for inline empty rows in tables or cards; `default` for full-page empty states. |
| description | `string` | no |  | Supporting paragraph below the title. |
| icon | `Component<IconProps>` | no |  | Icon component rendered above the title. Pass any icon from `@urbicon-ui/blocks` (or a compatible stroke icon). Its round container is filled `bg-surface-subtle text-text-tertiary` — an empty state is not the call to action, `cta` is. That fill reads as a faint wash on the page ground and as nothing at all inside an elevated container (Card, Popover), where `surface-subtle` and `surface-elevated` resolve to the same colour. For a fill that always reads, or for the accent back, pass `slotClasses={{ iconWrapper: 'bg-primary-subtle text-primary-text' }}`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ EmptyState: {...} }}>`. Prefer this over `class` overrides when the same look should be reused across the project. |
| slotClasses | `Partial<Record<EmptyStateSlots, string>>` | no |  | Per-slot class overrides. Slots: base | iconWrapper | title | description | children | cta. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> (omit-pattern)

### Types
```ts
type SlotNames = keyof ReturnType<T> & string
```

### Slots (slotClasses keys)
`base`, `iconWrapper`, `title`, `description`, `children`, `cta`

---

## FileUpload
Drag-and-drop file upload with validation, image previews, progress tracking, and animated file list.

**Import:** `import { FileUpload } from '@urbicon-ui/blocks';`

### Examples
```svelte
<FileUpload
  bind:files
  multiple
  maxFiles={5}
  maxFileSize={10 * 1024 * 1024}
  title="Drop files here or click to browse"
  description="PDF, DOCX, XLSX — max 10 MB per file"
/>
```

```svelte
<FileUpload
  bind:files
  accept={IMAGE_MIME_TYPES}
  multiple
  maxFiles={8}
  title="Upload images"
  description="PNG, JPG, WebP — max 5 MB"
  onFileReject={(rejections) => console.log('Rejected:', rejections)}
/>
```

### Variants
- intent: neutral, primary (default: neutral)
- size: lg, md, sm (default: md)
- disabled: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...FileUploadVariants | `VariantProps` | no |  | Styling variants from FileUploadVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| accept | `string | string[]` | no |  | Accepted MIME types or file extensions (e.g. 'image/*', '.pdf'). |
| allowDrop | `boolean` | no | true | Enable drag-and-drop. |
| allowPaste | `boolean` | no | false | Enable paste from clipboard. |
| children | `Snippet` | no |  | Default slot for fully custom dropzone content. |
| class | `string` | no |  | Additional CSS class for the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| description | `string` | no |  | Dropzone description text (accepted types, limits). |
| disabled | `boolean` | no |  | Disable all interaction. |
| dropzoneIcon | `Snippet` | no |  | Custom dropzone icon snippet. |
| file | `File | null` | no |  | Convenience binding for single-file uses. Two-way: - Reads as `files[0]?.file ?? null`. - Setting to a `File` replaces the current selection (object URLs are   revoked, no validation re-runs — assumes the caller already validated). - Setting to `null` clears the list.  Recommended when `maxFiles === 1` (e.g. logo / avatar uploads). Use `bind:files` instead when you need progress, errors, or status metadata. |
| fileItem | `Snippet<[FileItemContext]>` | no |  | Custom file item renderer. Receives file entry and remove callback. |
| files | `FileUploadFile[]` | no |  | Current file list. Supports two-way binding. |
| maxFiles | `number` | no |  | Maximum number of files. |
| maxFileSize | `number` | no |  | Maximum file size in bytes. |
| minFileSize | `number` | no |  | Minimum file size in bytes. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the dropzone. Only applies while not disabled. |
| multiple | `boolean` | no |  | Allow selecting multiple files. |
| name | `string` | no |  | Shared `name` for native form submission. When set, the underlying hidden `<input type="file">` carries the current file list — including files added via drag/drop, paste, or programmatic `bind:files`, not just files picked through the file dialog. Submits as a `File[]` under `{name}` in the FormData payload. |
| onFileAccept | `(files: FileUploadFile[]) => void` | no |  | Fires when valid files are accepted. |
| onFileReject | `(rejections: FileRejection[]) => void` | no |  | Fires when files are rejected by validation. |
| onFileRemove | `(file: FileUploadFile) => void` | no |  | Fires when a file is removed. |
| onFilesChange | `(files: FileUploadFile[]) => void` | no |  | Fires when the file list changes (add or remove). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ FileUpload: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| preventDocumentDrop | `boolean` | no | true | Prevent browser navigation when files are dropped outside the zone. |
| required | `boolean` | no |  | Mark as required for form validation. |
| slotClasses | `Partial<Record<FileUploadSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| title | `string` | no |  | Dropzone title text. |
| unstyled | `boolean` | no |  | Strip all default styles. |
| validate | `(file: File) => FileUploadError[] | null` | no |  | Custom validation function. Return errors array or null. |
| intent | `'neutral' | 'primary'` | no | neutral | Controls the color theme and semantic meaning of the FileUpload. Affects the overall appearance and user perception. Available options: neutral, primary. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the FileUpload. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- Omit<FileUploadVariants, 'dragging' | 'invalid'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface FileItemContext {
/** The file entry. */
  fileEntry: FileUploadFile;
  /** Remove this file from the list. */
  remove: () => void;
}
```

```ts
type FileUploadSlotName = FileUploadSlots
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
interface FileIntakeRejection {
/** The rejected file. */
  file: File;
  /** Why it was rejected. */
  errors: FileIntakeError[];
}
```

```ts
interface FileIntakeError {
/** Machine-readable error code. */
  code: FileIntakeErrorCode;
  /** Human-readable error message. */
  message: string;
}
```

```ts
type FileIntakeErrorCode = | 'FILE_INVALID_TYPE'
  | 'FILE_TOO_LARGE'
  | 'FILE_TOO_SMALL'
  | 'TOO_MANY_FILES'
  | 'FILE_EXISTS'
  | 'CUSTOM'
```

```ts
interface FileIntakeEntry {
/** Unique identifier for this file entry. */
  id: string;
  /** The native File object. */
  file: File;
  /** Object URL for image previews (auto-generated, auto-revoked). */
  preview?: string;
  /** Upload progress 0–100. Undefined when not tracking. */
  progress?: number;
  /** Current lifecycle status. */
  status: FileIntakeStatus;
  /** Validation or upload errors. */
  errors: FileIntakeError[];
}
```

```ts
type FileIntakeStatus = 'pending' | 'uploading' | 'complete' | 'error'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`root`, `dropzone`, `dropzoneIcon`, `dropzoneTitle`, `dropzoneDescription`, `fileList`, `fileItem`, `fileItemPreview`, `fileItemInfo`, `fileItemName`, `fileItemSize`, `fileItemProgress`, `fileItemRemoveButton`, `fileItemError`, `fileItemStatusIcon`

---

## ForgotPasswordPage
Pre-built forgot-password page. Sends POST to `apiPath` (default `/api/auth/forgot-password`).
Pair with `createForgotPasswordHandler(authDeps)` on the server. Timing-safe to prevent email enumeration.

**Import:** `import { ForgotPasswordPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<ForgotPasswordPage {t} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/auth/forgot-password' | API endpoint for the reset-request. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| footer | `Snippet` | no |  | Content rendered below the form, above links. |
| header | `Snippet` | no |  | Content rendered between the heading and the form. |
| links | `Snippet` | no |  | Replaces the link area below the form. |
| loginUrl | `string` | no | '/auth/login' | URL for the login page link. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ForgotPasswordPage: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
interface AuthPageSlotClasses {
/** Outermost wrapper element. */
  root?: string;
  /** Card container around the form. */
  card?: string;
  /** Page heading (h1). */
  title?: string;
  /** Form element wrapping all fields. */
  form?: string;
  /** Individual form field (Input). */
  field?: string;
  /** Submit button. */
  submit?: string;
  /** Error alert container. */
  error?: string;
  /** Success message container. */
  success?: string;
  /** Links area below the form (e.g. "Forgot password?"). */
  links?: string;
  /** Password requirements checklist (RegisterPage, ResetPasswordPage). */
  requirements?: string;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

---

## FormField
Layout wrapper for composite form fields that need a label,
helper text, and error message but cannot rely on the built-in slots of
primitives like `InputProps` or `SelectProps`. Examples:
a custom file picker, a slider/number-input pair, a media uploader.

The `id` is auto-generated and forwarded to the slot via the `for`
snippet parameter so the rendered control can wire `aria-describedby`
and `aria-invalid` correctly.

**Import:** `import { FormField } from '@urbicon-ui/blocks';`

### Examples
```svelte
<FormField label="Document" required error={fileError} helper="PDF, JPG, PNG — max 10 MB">
  {#snippet children({ id, describedBy, invalid })}
    <FileUpload {id} aria-describedby={describedBy} aria-invalid={invalid} bind:files />
  {/snippet}
</FormField>
```

### Variants
- required: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet<[FormFieldSlotContext]>` | yes |  | Snippet receiving wiring metadata (`id`, `describedBy`, `invalid`, `required`, `disabled`). The wrapped control should spread or apply these to itself for accessibility. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| disabled | `boolean` | no | false | Disables visual emphasis. Pass through to the slot's control as needed. |
| error | `string` | no |  | Error message shown below the control. Replaces the helper text and propagates `invalid: true` to the slot for ARIA wiring. |
| helper | `string` | no |  | Helper text shown below the control. Hidden when `error` is present. Named `helper` to match the built-in helper prop of the form primitives (Input, Select, Toggle, …) — one vocabulary across the API seam. |
| id | `string` | no |  | Explicit HTML `id` for the control. Auto-generated when omitted, then forwarded to the slot. Caller may use it to attach external `<label for>`. |
| label | `string` | no |  | Label rendered above the control. Auto-linked to the slot via the generated `id`. |
| required | `boolean` | no | false | Adds a required asterisk to the label and propagates `required: true` to the slot. Does **not** apply the native `required` attribute — the slot's control is responsible for that. |
| slotClasses | `Partial<Record<FormFieldSlots, string>>` | no |  | Per-slot class overrides. Slots: wrapper (what `class` also targets) | label | requiredMark | message | helper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface FormFieldSlotContext {
/** Auto-generated or caller-provided HTML id. Set on the control. */
  id: string;
  /** Space-separated list of message ids; assign to `aria-describedby`. */
  describedBy: string | undefined;
  /** Whether the field is in an error state. Assign to `aria-invalid`. */
  invalid: boolean;
  /** Mirrors {@link FormFieldProps.required}. */
  required: boolean;
  /** Mirrors {@link FormFieldProps.disabled}. */
  disabled: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

### Slots (slotClasses keys)
`wrapper`, `label`, `requiredMark`, `message`, `helper`

---

## Guide
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
The guided-tour renderer: the opt-in, intrusive Guide component.
Renders the active tour the controller drives (`startTour`/`next`/`prev`/
`skip`/`finish`): a spotlight that dims everything but a cut-out hole over the current step's
target (the one *subtractive* Guide treatment, D5) plus an anchored bubble with the step
title, body, dot progress, and Back / Next / Skip controls. Mount once inside `GuideProvider`;
it renders nothing until a tour starts. Top-layer (native popover), so it clears app stacking
contexts; it steps aside (pauses) when a foreign modal stacks above it. A step with no `target`
renders centered over a full scrim. Renders inert without a `GuideProvider`.

**Import:** `import { Guide } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  import { GuideProvider, Guide, GuideController } from '@urbicon-ui/blocks';
  const guide = new GuideController();
  const tour = {
    id: 'welcome',
    steps: [
      { target: 'save-button', title: 'Save', body: 'Persist your changes here.' },
      { target: 'filter-control', title: 'Filter', body: 'Narrow the list.', interactive: true }
    ]
  };
</script>

<GuideProvider controller={guide}>
  <Guide />
  <button onclick={() => guide.startTour(tour)}>Take the tour</button>
</GuideProvider>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| arrow | `boolean` | no | true | Render the bubble's pointer arrow on anchored steps. |
| class | `string` | no |  | Additional classes on the bubble. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| padding | `number` | no | 8 | Padding in px between the step target and the spotlight hole edge. Also frames the additive highlight ring the engine paints on the target. |
| placement | `Placement` | no | 'bottom' | Preferred bubble placement when a step omits its own `placement`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Guide: {...} }}>`. |
| radius | `number` | no |  | Spotlight hole corner radius in px. When omitted, it follows the target's own border-radius (plus `padding`), clamped to the hole size. Set a number to force it. |
| slotClasses | `Partial<Record<GuideTourSlots | 'skip' | 'prev' | 'next', string>>` | no |  | Per-slot class overrides. Beyond the tour's own `tv()` slots, `skip` / `prev` / `next` forward to the footer's nested `<Button>`s (which own their internal markup). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

---

## GuideArticle
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
A single help article inside a `GuidePanel`. Registers itself in the panel's
list (by `title`) and renders its content only when it is the active article
(`controller.activeArticle === id`). Use `GuideMention` inside to link back to UI elements.

**Import:** `import { GuideArticle } from '@urbicon-ui/blocks';`

### Examples
```svelte
<GuideArticle id="seats" title="Seats & billing">
  <p>Each <GuideMention for="seat-count">seat</GuideMention> is one team member.</p>
</GuideArticle>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| id | `string` | yes |  | Unique article id — referenced by `GuideMarker` and `openPanel(id)`. |
| title | `string` | yes |  | Title shown in the panel list and header. |
| children | `Snippet` | no |  | Article body. |
| class | `string` | no |  | Additional classes on the article root. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| group | `string` | no |  | Optional section this article belongs to in the panel index. Articles that share a `group` are rendered under one section header (sections appear in the order their first article is defined); articles without a `group` stay in an ungrouped block. When no article sets a `group`, the index is a flat list — unchanged from today. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideArticle: {...} }}>`. |
| slotClasses | `Partial<Record<GuideArticleSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`article`

---

## GuideBeacon
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
A waiting, pulsing hotspot that invites the user into an opt-in guided tour (§6.3)
— the gentlest tour entry point, the opposite of an auto-starting tour. A real `<button>` the
consumer positions (inline, or absolutely over a feature corner); on activation it starts the
given `tour` and/or calls `onActivate`. Hides itself once that tour has been seen. The pulse
halts under `prefers-reduced-motion` (static dot). Renders inert without a `GuideProvider`.

**Import:** `import { GuideBeacon } from '@urbicon-ui/blocks';`

### Examples
```svelte
<span class="relative">
  New feature
  <GuideBeacon class="absolute -right-3 -top-1" {tour} />
</span>
```

### Variants
- size: md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Additional classes on the beacon button (use for absolute positioning over a target). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| label | `string` | no | i18n `guide.startTour` | Accessible label for the button. |
| onActivate | `() => void` | no |  | Called on activation (click / Enter / Space), after `tour` is started when both are set. |
| once | `boolean` | no | true | Hide the beacon once its `tour` has been seen (and while that tour is running). Needs `tour`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideBeacon: {...} }}>`. |
| size | `GuideBeaconVariants['size']` | no | 'md' | Visual size of the hotspot. |
| slotClasses | `Partial<Record<GuideBeaconSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tour | `GuideTour` | no |  | The tour to start when the beacon is activated. When set, the beacon also hides itself once the tour has been seen (subject to `once`). Omit to drive everything from `onActivate`. |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`beacon`, `ping`, `dot`

---

## GuideHint
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
A contextual, non-blocking hint anchored to a `data-guide` element via
`floating.ts` (flip/shift/arrow), rendered in the native popover top-layer. Waits at the
right element rather than interrupting: shows on mount (or when `open` for `trigger="manual"`),
persists "seen" so it appears once (`once`), and steps aside while a foreign modal or guided
tour is open. Dismissable; announces itself via `aria-live`. Renders inert without a provider.

**Import:** `import { GuideHint } from '@urbicon-ui/blocks';`

### Examples
```svelte
<button data-guide="export">Export</button>

<GuideHint for="export" title="New: scheduled exports">
  You can now export on a schedule from here.
</GuideHint>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| for | `string` | yes |  | `data-guide` id of the element to anchor to. Required — a hint with no anchor has nothing to point at. |
| arrow | `boolean` | no | true | Render the pointer arrow. |
| children | `Snippet` | no |  | Hint body. |
| class | `string` | no |  | Additional classes on the hint root. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| once | `boolean` | no | true | When dismissed, persist a "seen" flag (via the controller's StorageAdapter) so the hint does not reappear on later mounts. Mirrors the tour's "mark seen on end" rule — a hint shown but never dismissed may show again. Set `false` to always show. |
| onDismiss | `() => void` | no |  | Called when the hint is dismissed (close button or Escape). |
| open | `boolean` | no | false | Manual visibility for `trigger="manual"` (the on-route / on-condition strategy). Ignored for `trigger="mount"`. Re-raising it to `true` after a dismiss re-surfaces the hint (subject to `once`). |
| placement | `Placement` | no | 'bottom' | Preferred placement relative to the target. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideHint: {...} }}>`. |
| seenId | `string` | no | the `for` id | Persistence key for the "seen once" state, decoupled from the anchor (this is *not* a DOM id — the popover gets none). Override only to track two hints on one element independently, or to keep a stable key across a renamed anchor. |
| slotClasses | `Partial<Record<GuideHintSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| title | `string` | no |  | Optional bold heading above the body. |
| trigger | `'mount' | 'manual'` | no | 'mount' | When the hint may appear: `'mount'` shows it as soon as it mounts; `'manual'` waits for `open` to become `true` (the consumer's route/condition logic). |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`hint`, `title`, `body`, `dismiss`, `arrow`

---

## GuideMarker
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Direction A of the bidirectional link (UI → Guide): a discreet "ⓘ" trigger
that sits on a UI element and opens the `GuidePanel` at the matching article. A real
`<button>` with `aria-controls`/`aria-expanded` — deliberately *not* a status `Badge`
(which is a non-interactive label, not a trigger). Renders inert without a `GuideProvider`,
or when the topic's direction excludes UI→Guide (`'to-ui'`).

**Import:** `import { GuideMarker } from '@urbicon-ui/blocks';`

### Examples
```svelte
<h3>Billing <GuideMarker for="billing" article="billing-help" /></h3>
```

### Variants
- size: md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| article | `string` | no |  | Article to open in the panel. Overrides the topic meta's `article`; falls back to `for`. |
| children | `Snippet` | no |  | Custom trigger content, replacing the default "ⓘ" icon. |
| class | `string` | no |  | Additional classes on the marker button. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| direction | `GuideDirection` | no | the topic's `direction`, or `'both'` | Override the topic's link direction. The marker is live unless this resolves to `'to-ui'`. |
| for | `string` | no |  | `data-guide` topic id this marker explains. Resolves the article (from topic meta) and the link direction. Optional (unlike `GuideMention.for`) because `article` can stand alone — supply one of the two. With neither, the marker opens the panel index. |
| label | `string` | no | i18n `guide.infoAbout` (with the topic's label) or `guide.info` | Accessible label for the icon button. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideMarker: {...} }}>`. |
| size | `GuideMarkerVariants['size']` | no | 'md' | Icon size. |
| slotClasses | `Partial<Record<GuideMarkerSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`marker`, `icon`

---

## GuideMention
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Direction B of the bidirectional link (Guide → UI): an inline reference inside a
`GuideArticle` that highlights the matching UI element on hover *and* focus (keyboard parity).
Additive `outline` ring, no scrim, no layout shift (D5); clicking also scrolls the element into
view (reduced-motion-aware). A real `<button>`; degrades to plain inline text without a
`GuideProvider` or when the topic's direction excludes Guide→UI (`'to-guide'`).

**Import:** `import { GuideMention } from '@urbicon-ui/blocks';`

### Examples
```svelte
<p>Click the <GuideMention for="save-button">Save button</GuideMention> to persist.</p>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| for | `string` | yes |  | `data-guide` id of the UI element to highlight. Required (unlike `GuideMarker.for`): a mention with no target has nothing to highlight. |
| children | `Snippet` | no |  | The mention text. |
| class | `string` | no |  | Additional classes on the mention. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| direction | `GuideDirection` | no | the topic's `direction`, or `'both'` | Override the topic's link direction. The mention is interactive unless this resolves to `'to-guide'`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideMention: {...} }}>`. |
| scroll | `boolean` | no | true | Scroll the target into view on click (reduced-motion-aware). |
| slotClasses | `Partial<Record<GuideMentionSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`mention`

---

## GuidePanel
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Non-modal help panel for the Guide system. Slides in (default from the right)
without a backdrop or focus trap, so the app stays interactive behind it — this is what lets
a `GuideMention` highlight a UI element while the panel is open (D1). Visibility is driven by
the controller (`openPanel`/`closePanel`), not a local prop. Place `GuideArticle` children
inside: the panel shows a list of them, or the active article's content with a back button.

**Import:** `import { GuidePanel } from '@urbicon-ui/blocks';`

### Examples
```svelte
<GuidePanel title="Help">
  <GuideArticle id="saving" title="Saving your work">
    <p>Use the Save button to persist your changes.</p>
  </GuideArticle>
</GuidePanel>
```

### Variants
- size: lg, md, sm (default: md)
- placement: left, right (default: right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | no |  | `GuideArticle` children and any custom content. |
| class | `string` | no |  | Additional classes on the panel root. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| closeOnEscape | `boolean` | no | true | Close the panel when Escape is pressed. |
| footer | `Snippet` | no |  | Optional footer content. |
| id | `string` | no | auto-generated (`guide-panel-<id>`) | Stable DOM id for the panel root. `GuideMarker`s reference it via `aria-controls`. |
| placement | `GuidePanelVariants['placement']` | no | 'right' | Side the panel docks to. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuidePanel: {...} }}>`. |
| searchable | `boolean` | no | false | Render a filter input above the article index that matches article titles (case-insensitive). Off by default. Pairs with article grouping — filtered results keep their section headers and empty sections disappear. |
| size | `GuidePanelVariants['size']` | no | 'md' | Panel width. |
| slotClasses | `Partial<Record<GuidePanelSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| title | `string` | no | i18n `guide.openHelp` | Heading shown when no article is open. |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`panel`, `header`, `backButton`, `title`, `closeButton`, `body`, `searchInput`, `noResults`, `groupHeader`, `list`, `listItem`, `footer`

---

## GuideProvider
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Root provider for the Guide help system. Instantiates a `GuideController`
and shares it via context with all Guide components (Panel, Marker, Mention, Hint, Tour).
Place once near the app root. The context is optional: a component used without a provider
renders inert rather than throwing.

**Import:** `import { GuideProvider } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  import { GuideProvider, GuideController } from '@urbicon-ui/blocks';
  const guide = new GuideController();
</script>

<GuideProvider controller={guide}>
  <App />
</GuideProvider>

<button onclick={() => guide.startTour(welcomeTour)}>Take the tour</button>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | App subtree wired to the Guide context. |
| controller | `GuideController` | no |  | Supply a pre-created `GuideController` for programmatic access from outside the provider (start tours, open the panel, query `hasSeen`). When omitted, the provider creates one internally and shares it via context. When supplied, `storage` and `navigate` are ignored. |
| navigate | `(route: string) => void | Promise<void>` | no | undefined | Navigation hook for declarative cross-route tours, forwarded to the internally created controller. A SvelteKit consumer wires `(route) => goto(route)`; a step's `route` then navigates before its spotlight. Ignored when a `controller` is supplied (set it there). |
| storage | `GuideStorageAdapter` | no | localStorage-backed adapter | Persistence adapter for "seen" state (tours/hints). |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

---

## GuideRef
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
An inline article→article link inside a `GuideArticle` body — the
help-internal analogue of `GuideMention` (which links out to a UI element). A real
`<button>` that navigates the open `GuidePanel` to the target article via the
controller (`setArticle`). Degrades to plain inline text without a `GuideProvider`,
outside a `GuidePanel`, or for an unknown `article` id; keyboard/focus parity with
`GuideMention`.

**Import:** `import { GuideRef } from '@urbicon-ui/blocks';`

### Examples
```svelte
<GuideArticle id="cost-pot" title="Cost pot">
  <p>The pot is split by the <GuideRef article="splitting">splitting method</GuideRef>.</p>
</GuideArticle>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| article | `string` | yes |  | Id of the `GuideArticle` to navigate to. Inert (plain text) for an unknown id. |
| children | `Snippet` | no |  | The link text. |
| class | `string` | no |  | Additional classes on the ref. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideRef: {...} }}>`. |
| slotClasses | `Partial<Record<GuideRefSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Strip all default styles. |

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`ref`

---

## InfoCard
Simple memo-style card for inline callouts or notes within docs content.

**Import:** `import { InfoCard } from '@urbicon-ui/docs';`

### Examples
```svelte
<InfoCard title="Tip" icon="lightbulb">Use variants to change tone.</InfoCard>
```

### Variants
- intent: api, danger, example, info, neutral, playground, primary, secondary, success, warning (default: info)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'title') |
| ...InfoCardVariantProps | `VariantProps` | no |  | Styling variants from InfoCardVariantProps |
| children | `Snippet` | no |  | Card body. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| headingLevel | `1 | 2 | 3 | 4 | 5 | 6` | no | 3 | Heading level for the card title, clamped to 1..6. Cards usually sit inside a `<Section>` (`h2`), so `h3` is the default.  It was a fixed `h4` until 2026-08, which put an `h2 → h4` skip into the outline of every page that used a card directly under a section, and an `h1 → h4` one on the pages that use cards as their landing grid. Pass an explicit level where the nesting differs. The title styling is class-driven, so the level never changes how the card looks. |
| href | `string` | no |  | Render the card as a link to this URL. Falls back to an `<aside>` when omitted. |
| icon | `string` | no |  | Decorative glyph rendered before the title. Purely visual — it is hidden from assistive tech, so never put meaning here that the title does not carry. |
| slotClasses | `Partial<Record<InfoCardSlots, string>>` | no |  | Per-slot class overrides for internal elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| title | `string` | no |  | Heading shown above the body. Also becomes the card's accessible name (`aria-label`), so it is deliberately not the native `title` tooltip. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with `slotClasses` to rebuild from scratch. |
| intent | `'api' | 'danger' | 'example' | 'info' | 'neutral' | 'playground' | 'primary' | 'secondary' | 'success' | 'warning'` | no | info | Controls the color theme and semantic meaning of the InfoCard. Affects the overall appearance and user perception. Available options: api, danger, example, and 7 more. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the InfoCard. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- InfoCardVariantProps (external)
- Omit<HTMLAttributes<HTMLElement>, 'children' | 'title'> (omit-pattern)

### Slots (slotClasses keys)
`container`, `header`, `icon`, `title`, `content`

---

## InlineCode
The documentation surfaces carry strings that were written for a
markdown reader: prop descriptions come from JSDoc, where naming a field in
backticks is the convention, and 78% of them do it. Rendered as text those
backticks reach the reader as characters.

This turns paired backticks into `<code>` and leaves everything else alone. It
is not a markdown renderer — no emphasis, no links — and it never uses
`{@html}`, so a string is escaped whatever it contains.

**Import:** `import { InlineCode } from '@urbicon-ui/docs';`

### Examples
```svelte
<InlineCode text="Set `defaults` to the table's own props." />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| codeClass | `string` | no |  | Classes for the generated `<code>` elements. The default follows body copy; a table cell or a caption can pass its own scale. |
| text | `string` | no |  | The string to render. Paired backticks become `<code>`; an unpaired one is left as a character. |

---

## Input
Text input with labels, validation states, icons, and clearable functionality.
Supports the outlined, filled, ghost, underline and bare visual variants, with
automatic ARIA linking.

**Import:** `import { Input } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Input label="Email" placeholder="name@example.com" required />
```

### Variants
- intent: danger, default, success, warning (default: default)
- variant: bare, filled, ghost, outlined, underline (default: outlined)
- size: lg, md, sm, xl, xs (default: md)
- disabled: true (default: false)
- hasLeftIcon: true (default: false)
- hasRightIcon: true (default: false)
- iconPosition: left, right (default: left)
- readonly: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLInputAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'size' | 'class' | 'disabled' | 'readonly' | 'children') |
| ...InputVariants | `VariantProps` | no |  | Styling variants from InputVariants |
| autoComplete | `string` | no |  | HTML autocomplete hint for browser autofill. |
| children | `Snippet` | no |  | Snippet content rendered below the input for advanced layouts. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clearable | `boolean` | no | false | Show a clear button when the input has a value. Press Escape or click the button to clear. Fires `onClear` after clearing. |
| disabled | `boolean` | no | false | disabled property |
| error | `string` | no |  | Error message below the input. When set, overrides `helper` and forces danger border styling regardless of `intent`. |
| helper | `string` | no |  | Helper text below the input — hidden when `error` is present. |
| label | `string` | no |  | Label text displayed above the input, auto-linked via `for`/`id`. |
| leftIcon | `Snippet` | no |  | Icon snippet rendered on the left side of the input field. |
| leftIconAriaLabel | `string` | no |  | Accessible label for the clickable left icon button. Required when `onLeftIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the input element. Only applies while not disabled. |
| onClear | `() => void` | no |  | Fired after the value is cleared via the clear button or Escape key. |
| onLeftIconClick | `() => void` | no |  | When provided, the left icon becomes a clickable button. |
| onRightIconClick | `() => void` | no |  | When provided, the right icon becomes a clickable button. |
| persistDebounceMs | `number` | no | 300 | Debounce interval (ms) for storage writes. |
| persistKey | `string` | no |  | Key for persisting the input value to storage. |
| persistNamespace | `string` | no |  | Namespace (e.g. user id) to scope the persist key. |
| persistStorage | `'localStorage' | 'sessionStorage'` | no | 'localStorage' | Storage backend for persistence. |
| persistVersion | `number` | no | 1 | Version stamp included in the storage key. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Input: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| readonly | `boolean` | no | false | readonly property |
| required | `boolean` | no | false | Adds a required asterisk to the label and sets the native `required` attribute. |
| rightIcon | `Snippet` | no |  | Icon snippet rendered on the right side of the input field. |
| rightIconAriaLabel | `string` | no |  | Accessible label for the clickable right icon button. Required when `onRightIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| slotClasses | `Partial<Record<InputSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | container | base (the `<input>` element) | label | requiredMark | message | iconContainer | iconButton | iconDecoration. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |
| intent | `'danger' | 'default' | 'success' | 'warning'` | no | default | Controls the color theme and semantic meaning of the Input. Affects the overall appearance and user perception. Available options: danger, default, success, warning. |
| variant | `'bare' | 'filled' | 'ghost' | 'outlined' | 'underline'` | no | outlined | Controls the visual style and presentation of the Input. Determines the component's visual treatment. Available options: bare, filled, ghost, and 2 more. |
| size | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Input. Affects the component's physical footprint. Available options: lg, md, sm, and 2 more. |
| hasLeftIcon | `'true'` | no | false | Controls the hasLeftIcon behavior and appearance of the Input component. Available options: true. |
| hasRightIcon | `'true'` | no | false | Controls the hasRightIcon behavior and appearance of the Input component. Available options: true. |
| iconPosition | `'left' | 'right'` | no | left | Controls the iconPosition behavior and appearance of the Input component. Available options: left, right. |
| tier | `'commit' | 'modify'` | no | modify | Selects the semantic radius tier of the Input — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

Inherited from:
- Omit<InputVariants, 'error' | 'messageType'> (omit-pattern)
- Omit<HTMLInputAttributes, 'size' | 'class' | 'disabled' | 'readonly' | 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`wrapper`, `container`, `base`, `label`, `requiredMark`, `message`, `iconContainer`, `iconButton`, `iconDecoration`

---

## InvitationManager
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Admin panel for managing invitation-gated registration with email toggle.
Communicates with `apiPath` (default `/api/invitations`). Pair with `createInvitationHandlers(authDeps, { authorize, roles })` on the server — mount its `POST` + `GET` on `/api/invitations` and `DELETE` on `/api/invitations/[id]`.

**Import:** `import { InvitationManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<InvitationManager {t} roles={[{ value: 'ADMIN', label: 'Admin' }, { value: 'USER', label: 'User' }]} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| roles | `RoleOption[]` | yes |  | Available roles for the invitation menu. |
| apiPath | `string` | no | '/api/invitations' | API base path for the invitation endpoints. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ InvitationManager: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| slotClasses | `Partial<Record<'root' | 'title' | 'form' | 'list' | 'item' | 'empty' | 'error' | 'inviteLink', string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
interface RoleOption {
/** Internal value sent to the API. */
  value: string;
  /** Display label shown in the menu. */
  label: string;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`, `title`, `form`, `list`, `item`, `empty`, `error`, `inviteLink`

---

## JourneyTimeline
Retrospective chronicle timeline (focus + context): an ordered
record of what happened / where things stand — shipment tracking, audit
trails, travel logs, billing runs. Exactly one focusable node is in focus and
shows rich detail (`node` snippet); the rest stay quiet, compact context
rows. The chronicle axis is first-class: per-node `meta` (time/date/actor)
renders on a meta rail, connectors carry meaning (`solid | dashed | dotted`)
and `segmentLabel` annotates the stretch between nodes. Rows extend without
forking the layout: a `marker` snippet puts glyphs inside the status dots, a
`trailing` snippet adds badges/help/actions beside each header (outside the
button — safe for interactive elements), and the `attention` status flags
optional-but-noteworthy rows. Detail placement is configurable:
`detail="inline"` expands in place (vertical default); `detail="panel"`
renders a stable readout beside (wide) or docked below (narrow) the rail —
horizontal always uses the panel. Use `Stepper` for a prospective
wizard/progress indicator and `Tab` for switching between peer views;
JourneyTimeline is read-only observation of a sequence, not process control
or navigation.

**Import:** `import { JourneyTimeline } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script lang="ts">
import { JourneyTimeline, type JourneyNode } from '@urbicon-ui/blocks';
const run: JourneyNode[] = [
{ id: 'readings', title: 'Meter readings', status: 'complete', meta: '3 Jun', segmentLabel: '2 days · validation' },
{ id: 'validate', title: 'Validation', status: 'complete', meta: '5 Jun', connector: 'dashed', segmentLabel: 'manual review' },
{ id: 'statement', title: 'Statements', status: 'active', meta: '6 Jun' },
{ id: 'dispatch', title: 'Dispatch', status: 'pending' }
];
let focusId = $state('statement');
</script>

<JourneyTimeline items={run} bind:focusId>
{#snippet node(item)}
<p>Details for {item.title}…</p>
{/snippet}
</JourneyTimeline>
```

```svelte
<JourneyTimeline items={phases} orientation="horizontal" onFocusChange={(id) => track(id)}>
{#snippet node(item)}
<PhaseSummary phase={item.id} />
{/snippet}
</JourneyTimeline>
```

### Variants
- size: lg, md, sm (default: md)
- orientation: horizontal, vertical (default: vertical)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `JourneyNode[]` | yes |  | The ordered journey nodes. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...JourneyTimelineVariants | `VariantProps` | no |  | Styling variants from JourneyTimelineVariants |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| defaultFocusId | `string` | no |  | Initial focused node id in uncontrolled mode. Ignored once `focusId` is bound. |
| detail | `'inline' | 'panel'` | no | 'inline' (vertical) / 'panel' (horizontal) | Where the focused node's detail renders. `inline` expands in place inside the rail; `panel` renders a stable readout — beside the rail on wide viewports, docked to the viewport bottom on narrow ones. Horizontal orientation always uses the panel and ignores `inline` (DEV warning). |
| focusId | `string` | no |  | The focused node id. Supports `bind:focusId`. When omitted the component is uncontrolled and falls back to `defaultFocusId`, then the first `active` node, then the first focusable node. |
| marker | `Snippet<[JourneyNode]>` | no |  | Custom content *inside* each status dot — a glyph, count or icon. The dot keeps its status colour, shape and size contract (scale it via `slotClasses.marker`, e.g. `size-5`). Markers stay decorative (`aria-hidden`); the status is still announced through the hidden label. |
| meta | `Snippet<[JourneyNode]>` | no |  | Rich override for the meta rail — receives each `JourneyNode` and replaces the plain `item.meta` text (e.g. planned + actual time with a Badge). |
| node | `Snippet<[JourneyNode]>` | no |  | Renders the detail of the focused node. Receives the focused `JourneyNode`. |
| onFocusChange | `(id: string) => void` | no |  | Fires when the focused node changes (click or keyboard). |
| orientation | `'vertical' | 'horizontal'` | no | 'vertical' | Layout direction. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ JourneyTimeline: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Marker + label scale. |
| slotClasses | `Partial<Record<JourneyTimelineSlots, string>>` | no |  | Per-slot class overrides. Slots: base | rail | node | metaColumn | meta | markerColumn | marker | connector | content | card | header | trigger | trailing | labelGroup | title | subtitle | segment | detail | detailInner | detailContent | panel. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| trailing | `Snippet<[JourneyNode]>` | no |  | End-of-row content beside each node's header — status badges, a help affordance, quick actions. Renders *outside* the trigger button (a sibling in the header row), so interactive elements are valid HTML and activating them never moves the focused node. Right-aligned in vertical orientation, appended to the label pill in horizontal. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |

Inherited from:
- Pick<JourneyTimelineVariants, 'orientation' | 'size'> (pick-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type JourneyStatus = 'complete' | 'active' | 'pending' | 'attention' | 'blocked' | 'skipped'
```

- `interface JourneyNode` — 8 members, definition omitted (41 lines; full definition: packages/blocks/src/lib/primitives/JourneyTimeline/index.ts)

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`base`, `rail`, `node`, `metaColumn`, `meta`, `markerColumn`, `marker`, `connector`, `content`, `card`, `header`, `trigger`, `trailing`, `labelGroup`, `title`, `subtitle`, `segment`, `detail`, `detailInner`, `detailContent`, `panel`

---

## Kbd
Keyboard-key hint. Renders one or more keys as a compact, physical-looking
keycap — the canonical way to show shortcuts (⌘K, Ctrl + S) in menus, tooltips, command
palettes and docs. Pure display; emits a semantic `<kbd>` element.

**Import:** `import { Kbd } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Kbd keys="⌘K" />
```

```svelte
<Kbd keys={['Ctrl', 'K']} />
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...KbdVariants | `VariantProps` | no |  | Styling variants from KbdVariants |
| children | `Snippet` | no |  | Custom content; overrides `keys`. |
| class | `string` | no |  | Additional CSS class merged onto the root `<kbd>`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| keys | `string | string[]` | no |  | The key(s) to display. A single string renders one label; an array renders each entry joined by `separator` (e.g. `['Ctrl', 'K']` → `Ctrl + K`). Ignored when `children` is provided. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Kbd: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic palette — presets keep dark-mode logic coherent and reusable. |
| separator | `string` | no | '+' | Separator rendered between multiple `keys`. |
| size | `'sm' | 'md' | 'lg'` | no |  | Keycap size — sm, md (default), lg. |
| slotClasses | `Partial<Record<KbdSlots, string>>` | no |  | Per-slot class overrides. Slots: base | separator. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with slotClasses to rebuild from scratch. |

Inherited from:
- KbdVariants (external)
- Omit<HTMLAttributes<HTMLElement>, 'children' | 'class'> (omit-pattern)

### Slots (slotClasses keys)
`base`, `separator`

---

## LineChart
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Line chart for trends over an ordered category axis. One path
per series on the design-token palette; zero-dependency SVG, responsive,
dark-mode aware, with optional points, gridlines, legend, and a screen-
reader data-table fallback.

**Import:** `import { LineChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<LineChart
  data={[
    { label: 'Mon', values: [12] },
    { label: 'Tue', values: [18] },
    { label: 'Wed', values: [9] }
  ]}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `CartesianDatum[]` | yes |  | Ordered categories with per-series values. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| formatValue | `(value: number) => string` | no |  | Format values for axis labels, tooltips, and the data table. |
| height | `number` | no | 240 | SVG height in px. |
| includeZero | `boolean` | no | false | Start the value axis at zero instead of framing the data range. |
| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
| margin | `ChartMargin` | no |  | Plot margins; merged over the defaults. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| series | `ChartSeries[]` | no |  | Series metadata (labels + colors); defaults to one per value column. |
| showGrid | `boolean` | no | true | Render horizontal gridlines. |
| showLegend | `boolean` | no | true | Show the series legend (only renders with >1 series). |
| showPoints | `boolean` | no | true | Render a dot at each data point; style them via `slotClasses.point`. |
| slotClasses | `LineChartSlotClasses` | no |  | Per-slot class overrides. `mark` is the line path — one per series — and `point` the dots on it, one per series *and* datum. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px; omit for responsive width. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
interface CartesianDatum {
/** Category label rendered on the x-axis. */
  label: string;
  /** Values in series order; missing entries are treated as 0. */
  values: number[];
}
```

```ts
interface ChartMargin {
top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}
```

```ts
interface ChartSeries {
/** Legend + tooltip label. */
  label: string;
  /** Explicit color; defaults to the cycled categorical palette. */
  color?: string;
}
```

```ts
type LineChartSlotClasses = Partial<Record<LineChartSlot, string>>
```

```ts
type LineChartSlot = (typeof LINE_CHART_SLOTS)[number]
```

---

## Link
The anchor voice of the Navigation family. Tailwind's preflight strips every
default from `<a>`, so an unstyled anchor carries no affordance at all; `Link` puts one back
in two voices: `inline` for running prose, which paints `--color-text-link` and underlines it —
two cues, and that token is the lever for restyling every link in a project without touching
the primary intent — and `standalone` for a handle in a `<nav>`, a filter row or a table
header, which carries no underline and rests at tertiary, stepping up to document ink on hover.

**Always an `<a>`, never polymorphic.** A single-box control does not swap its root element
(COMPONENT-API-CONVENTIONS.md § Polymorphic Elements), and `Link` is the member to reach for
where the whole component *is* the anchor. A link that should *look* like a button is still
the `LinkButton` wrapper recipe over `buttonVariants()` — that is a button look, not a link
look.

`href` is opaque to the library: `resolve()`, internal-vs-external and prefetch are the
consumer's routing decisions, exactly as for `BreadcrumbItem.href`. `target`, `rel`,
`onclick` and every other anchor attribute travel through `restProps`, so an external link is
`<Link href="…" target="_blank" rel="noopener noreferrer">` and needs no `external` prop.

Size is inherited, never chosen: a link takes the type scale of the text around it, so there
is no `size` axis. There is no `intent` either — a link is not a fill.

`active` marks the current page (`aria-current="page"`) and lifts the link to document ink at
`font-medium`; `disabled` renders it inert — `aria-disabled="true"`, `tabindex="-1"`,
`pointer-events-none` and a click handler that cancels the navigation, so an
assistive-technology activation and Enter on a focused link answer nothing either — while
keeping the `href` readable and copyable. Neither adds a keyboard trap: a disabled link leaves
the tab order rather than swallowing focus.

**Import:** `import { Link } from '@urbicon-ui/blocks';`

### Examples
```svelte
<p>
Read the <Link href="/docs/tokens">token reference</Link> before changing a palette.
</p>
```

```svelte
<script lang="ts">
import { Link } from '@urbicon-ui/blocks';
import { page } from '$app/state';

const tabs = [
{ label: 'Overview', href: '/project/1' },
{ label: 'Settings', href: '/project/1/settings' }
];
</script>

<nav aria-label="Project sections" class="flex gap-4">
{#each tabs as tab (tab.href)}
<Link variant="standalone" href={tab.href} active={page.url.pathname === tab.href}>
{tab.label}
</Link>
{/each}
</nav>
```

### Variants
- variant: inline, standalone (default: inline)
  - inline — A link inside running prose — link ink, underlined.
  - standalone — A handle in a nav strip, a filter row, a table header — no underline.
- active: true (default: false)
- disabled: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | The link text. Required — the anchor's accessible name is what it renders. |
| href | `string` | yes |  | The address the link points at. Opaque to the library — it is written to the `href` attribute unchanged, so `resolve()`, a base path and the internal-vs-external decision stay in app code. Required: a Link without an address is not a Link. |
| ...HTMLAnchorAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class' | 'href') |
| ...LinkVariants | `VariantProps` | no |  | Styling variants from LinkVariants |
| active | `boolean` | no | false | Mark this link as the one the current page is at: it renders `aria-current="page"`, lifts the link to document ink at `font-medium` and drops its hover state — you are already there. Written for the `standalone` voice, where a current handle in a strip is the point; on an `inline` link it also changes the weight mid-sentence, so where only the attribute is wanted pass `aria-current="page"` directly instead. `active` is the shorthand for the page case and wins where both are given, so the other `aria-current` values (`"step"` in a wizard trail, `"true"` for a non-page target) are reached by passing `aria-current` and leaving `active` unset. |
| class | `string` | no |  | Additional CSS class merged onto the root `<a>`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | Render the link inert: `aria-disabled="true"`, `tabindex="-1"`, `pointer-events-none` and a click handler that cancels the navigation — so a pointer, Enter on a focused link and an assistive-technology activation all do nothing, and a consumer's own `onclick` is not called either. Drawn at reduced opacity. The `href` stays on the element: a disabled link keeps its address readable and copyable, it just leaves the tab order and answers nothing. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Link: {...} }}>`. Prefer this over `class` overrides when a project wants one link look everywhere — presets keep the hover and dark-mode logic coherent and reusable. |
| slotClasses | `Partial<Record<LinkSlots, string>>` | no |  | Per-slot class overrides. Slots: base. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with slotClasses to rebuild from scratch. |
| variant | `'inline' | 'standalone'` | no | 'inline' | Link voice. `inline` sits in running prose, painted in `--color-text-link` and underlined; `standalone` is a handle in a `<nav>`, a filter row or a table header — no underline, and it takes its colour from the ink ramp rather than the link token. |

Inherited from:
- LinkVariants (external)
- Omit<HTMLAnchorAttributes, 'children' | 'class' | 'href'> (omit-pattern)

### Slots (slotClasses keys)
`base`

---

## LocaleSwitcher
Convenience wrapper around Select to switch UI locales.
Single-select only — locale is always exactly one value. Options, value,
form integration, multi-select, and null-option are all owned internally
and intentionally not forwarded to the underlying Select.

**Import:** `import { LocaleSwitcher } from '@urbicon-ui/blocks';`

### Examples
```svelte
<LocaleSwitcher />
```

```svelte
<LocaleSwitcher showFlag variant="filled" size="sm" />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| locales | `Locale[]` | no |  | Restrict the displayed locales. Defaults to all locales registered in i18n. |
| mint | `SelectSingleProps<string>['mint']` | no | 'none' | Micro-interaction preset forwarded to the inner Select trigger. Redeclared from SelectSingleProps so the inheritance is a documented contract rather than an accident of the Omit list. |
| onLocaleChange | `(locale: Locale) => void` | no |  | Called after the locale has been changed successfully. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ LocaleSwitcher: {...} }}>`. Resolved against the **`LocaleSwitcher`** key, not `Select`: a preset written for the locale picker would otherwise style every select under the provider. `defaults.Select` still applies — the resolved preset reaches Select as instance `slotClasses`, so it wins over the provider's select-wide defaults and loses to `slotClasses` / `class` written on this component. A preset's `overrides` rules are matched against what you wrote here plus Select's own variant defaults; an axis Select derives for itself (`tier`, `messageType`, `error`, `open`) can match the wrong state — #360. |
| selectionIndicator | `'checkmark' | 'none'` | no |  | Selection indicator rendered next to each option. - `'checkmark'` — trailing check icon (default) - `'none'` — no indicator (typical when using `customItem`) |
| showFlag | `boolean` | no | false | Show flag emoji alongside locale name. |

Inherited from:
- Omit<
    SelectSingleProps<string>,
    // Owned by LocaleSwitcher's internal options/value pipeline:
    | 'options'
    | 'groups'
    | 'value'
    | 'onValueChange'
    | 'multiple'
    | 'multiPlaceholder'
    | 'nullOption'
    | 'closeOnSelect'
    | 'name'
    | 'label'
    | 'helper'
    | 'error'
  > (omit-pattern)

### Types
```ts
type SelectValue = string | number | boolean
```

```ts
interface NullOptionConfig {
/** Label shown both in the listbox row and the trigger when `value` is `null`. */
  label: string;
  /** Disables selection of the null option (rare, but allowed for symmetry). */
  disabled?: boolean;
}
```

---

## LoginPage
Pre-built login page with email/password, optional passkey, and remember-me.
Sends POST to `apiPath` (default `/api/auth/login`). Pair with `createLoginHandler(authDeps)` on the server.

**Import:** `import { LoginPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<LoginPage {t} onSuccess={() => goto('/')} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/auth/login' | API endpoint for the login request. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| footer | `Snippet` | no |  | Content rendered below the form, above links (e.g. terms checkbox). |
| forgotPasswordUrl | `string` | no | '/auth/forgot-password' | URL for the forgot-password page link. |
| header | `Snippet` | no |  | Content rendered above the form (e.g. social login buttons, welcome text). |
| links | `Snippet` | no |  | Replaces the link area below the form. |
| mode | `'password' | 'passkey' | 'both'` | no | 'both' | Login mode. `'password'` shows only email/password, `'passkey'` shows only passkey button, `'both'` shows both with separator. |
| onSuccess | `() => void` | no |  | Called after successful login. |
| passkeyApiPath | `string` | no | undefined | Passkey API base path. Required when mode is `'passkey'` or `'both'`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ LoginPage: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| registerUrl | `string` | no | '/auth/register' | URL for the register page link. |
| rememberMe | `boolean` | no | false | Show a "Remember me" checkbox. When checked, sends `rememberMe: true` in the login request body. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| twoFactorApiPath | `string` | no | '/api/auth/2fa/verify' | API endpoint for the 2FA verify step. When the login response signals `twoFactorRequired`, the page switches to a code-entry step that POSTs here. Pair with `createTwoFactorHandlers().verify`. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
interface AuthPageSlotClasses {
/** Outermost wrapper element. */
  root?: string;
  /** Card container around the form. */
  card?: string;
  /** Page heading (h1). */
  title?: string;
  /** Form element wrapping all fields. */
  form?: string;
  /** Individual form field (Input). */
  field?: string;
  /** Submit button. */
  submit?: string;
  /** Error alert container. */
  error?: string;
  /** Success message container. */
  success?: string;
  /** Links area below the form (e.g. "Forgot password?"). */
  links?: string;
  /** Password requirements checklist (RegisterPage, ResetPasswordPage). */
  requirements?: string;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

---

## Menu
Action menu (`role="menu"`) triggered by a button, with nested
submenus, sections, icons, and separators. Items are verbs the user can
invoke — Edit, Delete, Share, Export — and dispatch an `onSelect` callback
when activated. An item given `checked` additionally *shows* a setting:
it renders as `role="menuitemradio"` with the supplied state announced and
marked. Menu still owns no selection state — the consumer computes `checked`
and updates it from `onSelect`. For committing a value to a form use
`Select` (or `Combobox` for searchable). Menu and Select stay deliberately
disjoint: Menu's `role="menu"`/`menuitem` semantics with arrow-key roving
and Action-family chrome versus Select's `role="listbox"` value commitment
with Form-family chrome.

**Import:** `import { Menu } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Menu placeholder="Actions" items={[
  { label: 'Edit', onSelect: () => edit() },
  { label: 'Duplicate', onSelect: () => duplicate() },
  { type: 'section', label: 'Danger' },
  { label: 'Delete', onSelect: () => confirmDelete() }
]} />
```

```svelte
<Menu placeholder="More">
  <MenuSection label="Edit">
    <MenuItem onSelect={() => rename()}>Rename</MenuItem>
    <MenuItem onSelect={() => duplicate()}>Duplicate</MenuItem>
  </MenuSection>
  <MenuDivider />
  <MenuItem onSelect={() => confirmDelete()}>Delete</MenuItem>
</Menu>
```

```svelte
<Menu placeholder="View" items={[
  {
    label: 'Sort by',
    detail: sortBy,
    children: [
      { label: 'Name', checked: sortBy === 'Name', onSelect: () => (sortBy = 'Name') },
      { label: 'Date', checked: sortBy === 'Date', onSelect: () => (sortBy = 'Date') }
    ]
  },
  { label: 'Refresh', onSelect: () => refresh() }
]} />
```

```svelte
<Menu items={actionItems}>
  {#snippet customTrigger(toggle, open)}
    <Button
      variant="ghost"
      aria-label="Actions"
      aria-haspopup="menu"
      aria-expanded={open}
      onclick={toggle}
    >
      <MoreHorizontalIcon />
    </Button>
  {/snippet}
</Menu>
```

### Variants
- chevronAnimation: fade, none, rotate, translate (default: rotate)
- disabled: true
- itemSize: lg, md, sm (default: md)
- open: true (default: false)
- placement: bottom, bottom-end, bottom-start, top, top-end, top-start (default: bottom-start)
- syncWidth: false, true (default: true)
- tier: commit, modify (default: commit)
- usePortal: false, true (default: true)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class' | 'placeholder') |
| ...MenuVariants | `VariantProps` | no |  | Styling variants from MenuVariants |
| chevronAnimation | `'rotate' | 'translate' | 'fade' | 'none'` | no |  | chevronAnimation property |
| children | `Snippet` | no |  | Declarative children mode — use `<MenuItem>` / `<MenuDivider>` / `<MenuSection>`. A `<MenuSection>` wraps the items it names, the same way a `{ type: 'section' }` entry owns the items that follow it. |
| class | `string` | no |  | class property. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| contextTrigger | `Snippet` | no |  | Turn the menu into a **context menu**: instead of a trigger button, the snippet you pass becomes a right-click target. A `contextmenu` (right-click or long-press) on it opens the menu at the cursor position — the native browser context menu is suppressed. Keyboard navigation, dismissal and item selection behave exactly as in the dropdown menu; on dismiss, focus returns to wherever it was. Mutually exclusive with `customTrigger`/the default trigger button (when set, no trigger button renders). |
| customFooter | `Snippet` | no |  | Optional custom footer rendered below the items list. |
| customHeader | `Snippet` | no |  | Optional custom header rendered above the items list. |
| customItem | `Snippet<[TItem]>` | no |  | Custom per-item content. **Render visible content only** — the outer `role="menuitem"` button is provided by Menu and handles the click / keyboard activation. Putting an interactive element (`<button>`, `<a>`) inside the snippet creates nested-interactive HTML and triggers the item's action twice via event bubbling.  Positional arg: `(item)`. To dispatch from outside the normal click (e.g. a "Recent" entry that needs to activate from a parent shortcut), call the item's own `onSelect` directly. |
| customTrigger | `Snippet<[() => void, boolean, () => void]>` | no |  | Replace the default trigger button (chevron + label) with a custom element. Positional args: `(toggle, open, dismiss)`.  - `toggle`: flips the open state — wire this to your custom trigger's   click handler so the menu can be opened from the consumer's element. - `open`: current open state — useful for `aria-expanded`. - `dismiss`: closes the menu without changing toggle history; rarely   needed but provided for symmetry.  The consumer's element should bind its `onclick` to `toggle` and set `aria-expanded={open}` + `aria-haspopup="menu"` for ARIA correctness. |
| getItemChecked | `(item: TItem) => boolean | undefined` | no |  | Optional checked-state resolver for items in array mode (`undefined` = plain action item). |
| getItemChildren | `(item: TItem) => TItem[] | undefined` | no |  | getItemChildren property |
| getItemClass | `(item: TItem) => string | undefined` | no |  | Optional per-item class resolver for items in array mode. |
| getItemDetail | `(item: TItem) => string | undefined` | no |  | Optional right-aligned detail-text resolver for items in array mode. |
| getItemDisabled | `(item: TItem) => boolean` | no |  | getItemDisabled property |
| getItemIcon | `(item: TItem) => unknown` | no |  | Optional icon resolver for items in array mode. |
| getItemId | `(item: TItem) => string` | no |  | getItemId property |
| getItemLabel | `(item: TItem) => string` | no |  | Optional mapping functions for custom item shapes. |
| getSectionLabel | `(item: MenuSectionHeader) => string` | no |  | Section label override. Accepts concrete section header type. |
| id | `string` | no |  | id property |
| intent | `ButtonVariants['intent']` | no | 'neutral' | Button intent applied to the default trigger button. |
| isDivider | `(item: MenuItemType) => boolean` | no |  | Divider detection override, symmetric to `isSection`. Supply it when your own item shape carries a `type: 'divider'` field of its own meaning — the built-in check is structural, and without this mapper such a row would render as a rule and lose its `onSelect`.  This mapper and `isSection` *replace* the built-in check rather than narrowing it, so the escape is all-or-nothing: `isDivider={() => false}` also switches off genuine `{ type: 'divider' }` entries, which render as plain rows again — express those in your own shape instead. |
| isSection | `(item: MenuItemType) => boolean` | no |  | Section detection override. Applies to full union, not just TItem. |
| items | `TItem[]` | no |  | Array of menu items. Each item's `onSelect` runs when activated. |
| loading | `boolean` | no | false | Whether the default trigger button is in loading state. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset forwarded to the inner default trigger Button and applied to each menu item row (per-item via context). Only applies while not disabled. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the menu opens or closes from user interaction (trigger click, item activation, Escape, Tab-out, outside click). Receives the new open state. Not called when the consumer writes `bind:open` directly. |
| placeholder | `string` | no |  | Placeholder text shown on the default trigger. Acts as the trigger's accessible name unless `aria-label` is supplied. Typical values: "Actions", "More", "Options". Ignored when `customTrigger` is provided. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Menu: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `ButtonVariants['size']` | no | 'md' | Button size applied to the default trigger button. |
| slotClasses | `Partial<Record<MenuSlots, string>>` | no |  | Per-slot class overrides merged with the variant styles. Slots: base | trigger | triggerText | chevron | content | header | section | group | divider | items | item | indicator | detail | submenu | footer. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no | false | Remove the default variant classes, the default trigger Button's included. Only user-supplied classes apply. |
| variant | `ButtonVariants['variant']` | no | 'outlined' | Button variant applied to the default trigger button. |
| disabled | `'true'` | no |  | Controls the disabled behavior and appearance of the Menu component. Available options: true. |
| itemSize | `'lg' | 'md' | 'sm'` | no | md | Controls the itemSize behavior and appearance of the Menu component. Available options: lg, md, sm. |
| open | `'true'` | no | false | Controls the open behavior and appearance of the Menu component. Available options: true. |
| placement | `'bottom' | 'bottom-end' | 'bottom-start' | 'top' | 'top-end' | 'top-start'` | no | bottom-start | Controls the positioning and alignment of the Menu relative to its container or trigger element. Available options: bottom, bottom-end, bottom-start, and 3 more. |
| syncWidth | `'false' | 'true'` | no | true | Controls the syncWidth behavior and appearance of the Menu component. Available options: false, true. |
| tier | `'commit' | 'modify'` | no | commit | Selects the semantic radius tier of the Menu — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |
| usePortal | `'false' | 'true'` | no | true | Controls the usePortal behavior and appearance of the Menu component. Available options: false, true. |

Inherited from:
- MenuVariants (external)
- Omit<MenuSpecificProps<TItem>, keyof MenuVariants> (omit-pattern)
- MenuCustomSlots (local-interface)
- AnimationProps (resolved-interface)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'placeholder'> (omit-pattern)

### Types
```ts
type MenuOption = string
```

```ts
interface MenuSectionHeader {
type: 'section';
  label: string;
  disabled?: true;
}
```

```ts
interface MenuDividerItem {
type: 'divider';
}
```

- `interface MenuObjectOption` — 10 members, definition omitted (65 lines; full definition: packages/blocks/src/lib/primitives/Menu/index.ts)

```ts
type MenuItemType = MenuOption | MenuObjectOption | MenuSectionHeader | MenuDividerItem
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `trigger`, `triggerText`, `chevron`, `content`, `header`, `section`, `divider`, `items`, `item`, `indicator`, `detail`, `group`, `submenu`, `footer`

---

## NoteList
Wraps a series of `Note` rows in the standard documentation card.
Row separators and the first/last row padding are handled by the component, so
adding or reordering a note never means fixing the spacing of its neighbours.

**Import:** `import { NoteList } from '@urbicon-ui/docs';`

### Examples
```svelte
<NoteList>
  <Note title="Built-in ARIA">The trigger carries `aria-expanded`.</Note>
  <Note title="Keyboard">Arrow keys move between items, Escape closes.</Note>
</NoteList>
```

### Variants
- variant: card, flush (default: card)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...NoteListVariantProps | `VariantProps` | no |  | Styling variants from NoteListVariantProps |
| children | `Snippet` | no |  | The `Note` rows. Anything else renders too, but loses the row padding the separators are calibrated against. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| slotClasses | `Partial<Record<NoteListSlots, string>>` | no |  | Per-slot class overrides for internal elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with `slotClasses` to rebuild from scratch. |
| variant | `'card' | 'flush'` | no | card | Controls the visual style and presentation of the NoteList. Determines the component's visual treatment. Available options: card, flush. |

Inherited from:
- NoteListVariantProps (external)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`root`, `list`

---

## NotificationBadge
An unread-count badge that renders nothing when the count is 0.
The visible text is the count, capped at `99+`; the accessible name is the
localized `notifications.badge.unread` string with that same text substituted
for `{n}`, so the badge's accessible name is "Unread notifications: 3"
instead of a bare number. Pass your own `aria-label` (or any other attribute — the rest spread
reaches the badge root) to override it.

The ARIA role follows the handler, because `Badge` derives it: with an
`onclick` the badge is a `button` and a tab stop; without one it is a
`status` — a polite live region that exists from the first unread on, so a
change between two non-zero counts happens inside a region that was already
there. The first unread is not such a change: at zero the badge renders
nothing, so the region arrives together with its text. The interactive look
follows the handler too — without one the badge is not pressable and does
not look it.

**Import:** `import { NotificationBadge } from '@urbicon-ui/auth';`

### Examples
```svelte
<NotificationBadge count={store.unreadCount} onclick={() => (open = !open)} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| count | `number` | yes |  | Number of unread notifications. Badge hidden when 0. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class' | 'onclick' | 'role') |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| onclick | `() => void` | no |  | Click handler (e.g. toggle notification center). Also what makes the badge a `button` and a tab stop. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ NotificationBadge: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| role | `BadgeProps['role']` | no |  | ARIA role, passed straight to `Badge` — its type, so the two cannot drift. Leave unset to take the derived one: `button` with an `onclick`, `status` (a polite live region) without. It narrows what the badge is announced as; it does not make it operable, so `role="button"` without an `onclick` is a button nothing can activate. |
| slotClasses | `Partial<Record<'root', string>>` | no |  | Per-slot class overrides. Slots: root. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children' | 'class' | 'onclick' | 'role'> (omit-pattern)

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`

---

## NotificationCenter
Menu-ready notification list with mark-as-read, delete, and empty state.
Renders each notification as a clickable card with timestamp. Feed it from `createNotificationStore`,
whose routes are served by the `createNotificationsHandlers` server factory.

**Import:** `import { NotificationCenter } from '@urbicon-ui/auth';`

### Examples
```svelte
<NotificationCenter {t} notifications={store.notifications}
  onMarkAsRead={(id) => store.markAsRead(id)}
  onMarkAllAsRead={() => store.markAllAsRead()}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| notifications | `import('../../../server/adapters/types.js').NotificationRecord[]` | yes |  | Notification records to display. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| item | `Snippet<[import('../../../server/adapters/types.js').NotificationRecord]>` | no |  | Custom notification item renderer. |
| onDelete | `(id: string) => void` | no |  | Called when a notification is deleted. |
| onMarkAllAsRead | `() => void` | no |  | Called when all notifications are marked as read. |
| onMarkAsRead | `(id: string) => void` | no |  | Called when a single notification is marked as read. |
| onNotificationClick | `(
    notification: import('../../../server/adapters/types.js').NotificationRecord
  ) => void` | no |  | Called when a notification is clicked (e.g. to navigate to a URL). SECURITY: `notification.url` is DB-/server-sourced and untrusted; before passing it to `goto()` / `window.location`, validate it is same-origin or relative (reject `javascript:` and absolute cross-origin URLs). Never navigate to a raw `notification.url`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ NotificationCenter: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| slotClasses | `Partial<Record<'root' | 'header' | 'list' | 'item' | 'empty', string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`, `header`, `list`, `item`, `empty`

---

## NotificationListener
Headless SSE listener for real-time notifications. Reads the stream off `fetch`
rather than `EventSource`, so it sees the HTTP response and decides by the server's machine
`code`, reported through `onRefused`: `connection_limit` (and any other 4xx) is final — the same
request would get the same answer; `rate_limited` waits out `Retry-After`; `not_authenticated`
is retried every 30s, since the session may come back; a 5xx and a dropped stream reconnect
with exponential backoff (1s doubling, or the server's `retry:`, capped at 60s), resuming from
the last `id:` the stream committed. A 2xx that is not `text/event-stream` (the login page a
redirect landed on) is final too. Connects to `apiPath` (default `/api/notifications/stream`).
Pair with `createStreamHandler(sse)` on the server; mount its `GET` on the stream route.

**Import:** `import { NotificationListener } from '@urbicon-ui/auth';`

### Examples
```svelte
<NotificationListener onNotification={(n) => store.add(n)} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/notifications/stream' | SSE stream endpoint. Read once when the component mounts; to switch endpoints (e.g. after a user change), unmount and remount the listener. |
| maxReconnectAttempts | `number` | no | 5 | Consecutive failed reconnects (a dropped stream, a 5xx) before the listener gives up; a connection that stayed open for 10s starts the count over. Rate limits and a missing session are not counted. Read once at mount. |
| onError | `(error: Error) => void` | no |  | Called when the stream drops or cannot be reached at all (network failure, server closed it) — a reconnect with backoff follows, up to `maxReconnectAttempts` in a row. |
| onNotification | `(
    notification: import('../../../server/adapters/types.js').NotificationRecord
  ) => void` | no |  | Called when a new notification arrives via SSE. |
| onReconnect | `(attempt: number) => void` | no |  | Called when a reconnection attempt starts. Receives current attempt number. |
| onRefused | `(code: string | undefined, status: number) => void` | no |  | Called when the server answers the stream request with a non-2xx status, or with a 2xx that is not `text/event-stream` (`code` is then `undefined`). `code` is the machine code from the JSON body; map it through `errorMessageFromCode` for the localized sentence. What follows depends on it: `rate_limited` waits out `Retry-After`, `not_authenticated` retries every 30s, a 5xx keeps the backoff; everything else — `connection_limit` (the per-user cap on concurrent streams, cleared only by closing a tab), 403, 404, a body without a code — is final. |

---

## NumberInput
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Generic numeric input with min/max/step bounds, stepper buttons,
and Arrow-key / mouse-wheel increment. Built on `Input`, so it inherits
labels, validation, sizes and variants. Values are plain numbers (not minor
units) — `CurrencyInput` is the domain-specific specialization for money.

The field accepts a leading `-`, a single decimal separator (`.` or `,`), and
clamps to `[min, max]` on blur; the stepper and Arrow keys clamp immediately.
Set `precision` to fix the number of decimal places.

**Import:** `import { NumberInput } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  let qty = $state(1);
</script>
<NumberInput label="Quantity" bind:value={qty} min={0} max={99} step={1} />
```

```svelte
<NumberInput label="Rate" bind:value={rate} min={0} max={1} step={0.05} precision={2} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| autoComplete | `string` | no |  | HTML autocomplete hint for browser autofill. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | disabled property |
| error | `string` | no |  | Error message below the input. When set, overrides `helper` and forces danger border styling regardless of `intent`. |
| helper | `string` | no |  | Helper text below the input — hidden when `error` is present. |
| hideStepper | `boolean` | no | false | Hide the up/down stepper buttons (Arrow keys + wheel still work). |
| label | `string` | no |  | Label text displayed above the input, auto-linked via `for`/`id`. |
| leftIcon | `Snippet` | no |  | Icon snippet rendered on the left side of the input field. |
| leftIconAriaLabel | `string` | no |  | Accessible label for the clickable left icon button. Required when `onLeftIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| max | `number` | no |  | Maximum allowed value. Clamped on step / Arrow / blur. |
| min | `number` | no |  | Minimum allowed value. Clamped on step / Arrow / blur. |
| mint | `InputProps['mint']` | no | 'none' | Micro-interaction preset forwarded to the inner Input. Redeclared from InputProps so the inheritance is a documented contract rather than an accident of the Omit list. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the input element. Only applies while not disabled. |
| name | `string` | no |  | Shared `name` for a hidden input for native form submission. |
| onLeftIconClick | `() => void` | no |  | When provided, the left icon becomes a clickable button. |
| onRightIconClick | `() => void` | no |  | When provided, the right icon becomes a clickable button. |
| onValueChange | `(value: number | null) => void` | no |  | Fires after the value changes (typing, stepper, Arrow, wheel, or clamp). |
| persistDebounceMs | `number` | no | 300 | Debounce interval (ms) for storage writes. |
| persistKey | `string` | no |  | Key for persisting the input value to storage. |
| persistNamespace | `string` | no |  | Namespace (e.g. user id) to scope the persist key. |
| persistStorage | `'localStorage' | 'sessionStorage'` | no | 'localStorage' | Storage backend for persistence. |
| persistVersion | `number` | no | 1 | Version stamp included in the storage key. |
| precision | `number` | no |  | Fixed number of decimal places for display and rounding. When unset, the value is shown as typed and the step's own decimals drive rounding. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ NumberInput: {...} }}>`. Resolved against the **`NumberInput`** key, not `Input`: a preset written for the number field would otherwise style every text field under the provider. `defaults.Input` still applies — the resolved preset reaches Input as instance `slotClasses`, so it wins over the provider's input-wide defaults and loses to `slotClasses` / `class` written on this component. A preset's `overrides` rules are matched against what you wrote here plus Input's own variant defaults; an axis Input derives or coerces for itself (`tier`, `messageType`, `error`, `hasRightIcon`, `iconPosition`) can match the wrong state — #360. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Input: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| readonly | `boolean` | no | false | readonly property |
| required | `boolean` | no | false | Adds a required asterisk to the label and sets the native `required` attribute. |
| rightIcon | `Snippet` | no |  | A custom right-side adornment. Overrides the stepper — pair with `hideStepper` or provide your own controls. |
| rightIcon | `Snippet` | no |  | Icon snippet rendered on the right side of the input field. |
| rightIconAriaLabel | `string` | no |  | Accessible label for the clickable right icon button. Required when `onRightIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| slotClasses | `Partial<Record<NumberInputSlots | keyof NonNullable<InputProps['slotClasses']>, string>>` | no |  | Per-slot class overrides. Carries NumberInput's own two slots — `stepper` (the button column) and `stepperButton` — on top of every `InputProps` slot. One record reaches both: the stepper is painted here and the rest travels on to the inner field. From `<BlocksProvider>`, everything under `NumberInput` reaches both halves; `defaults.Input` reaches the field only. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| slotClasses | `Partial<Record<InputSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | container | base (the `<input>` element) | label | requiredMark | message | iconContainer | iconButton | iconDecoration. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| step | `number` | no | 1 | Increment applied by the stepper buttons, Arrow keys, and wheel. |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |
| value | `number | null` | no |  | Current numeric value. `null` when the field is empty. Supports `bind:value`. |

Inherited from:
- Omit<
    InputProps,
    // NumberInput owns these internally and does not forward them: the numeric
    // handlers (input/focus/blur/keydown/wheel), the raw string `value`, the
    // fixed `type`/`inputmode`, and `children`. `clearable`/`onClear` are omitted
    // too — Input's clear button would replace the stepper and, worse, write only
    // Input's internal string value, drifting the numeric model out of sync.
    | 'value'
    | 'type'
    | 'inputmode'
    | 'oninput'
    | 'onfocus'
    | 'onblur'
    | 'onkeydown'
    | 'onwheel'
    | 'clearable'
    | 'onClear'
    | 'children'
  > (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

### Slots (slotClasses keys)
`stepper`, `stepperButton`

---

## Pagination
Navigation control for paged data sets.
Supports multiple layouts, intents, button variants, and configurable ellipsis behaviour.

**Import:** `import { Pagination } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Pagination
  currentPage={page}
  totalPages={20}
  onPageChange={(p) => page = p}
/>
```

### Variants
- size: lg, md, sm (default: md)
- layout: default, minimal, navigation, table (default: default)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| currentPage | `number` | yes |  | 1-based index of the currently active page. |
| totalPages | `number` | yes |  | Total number of pages in the data set. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class') |
| ...PaginationVariants | `VariantProps` | no |  | Styling variants from PaginationVariants |
| class | `string` | no |  | Additional CSS classes merged onto the root `<nav>` element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no |  | Disables all buttons and dims the component. |
| endItem | `number` | no |  | Override the calculated end item number for the info text. |
| firstIcon | `Snippet` | no |  | Custom icon rendered inside the "First" button. |
| firstLabel | `string` | no |  | Label for the "First" button. Falls back to i18n key `pagination.first`. |
| infoText | `string` | no |  | Override the auto-generated info text with a fully custom string. |
| intent | `'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral'` | no | 'primary' | Semantic color applied to every pagination button. |
| itemsPerPage | `number` | no |  | Items shown per page. Used by the table layout to compute "Showing X to Y of Z". |
| lastIcon | `Snippet` | no |  | Custom icon rendered inside the "Last" button. |
| lastLabel | `string` | no |  | Label for the "Last" button. Falls back to i18n key `pagination.last`. |
| loading | `boolean` | no |  | Shows a loading state with reduced opacity. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset forwarded to the inner buttons (page items, prev/next, first/last). |
| nextIcon | `Snippet` | no |  | Custom icon rendered inside the "Next" button. |
| nextLabel | `string` | no |  | Label for the "Next" button. Falls back to i18n key `pagination.next`. |
| onPageChange | `(page: number) => void` | no |  | Fires when the user selects a different page. Receives the 1-based page number. |
| pageLabel | `string` | no |  | Prefix for the info text (e.g. "Page"). Falls back to i18n key `pagination.page`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Pagination: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| previousIcon | `Snippet` | no |  | Custom icon rendered inside the "Previous" button. |
| previousLabel | `string` | no |  | Label for the "Previous" button. Falls back to i18n key `pagination.previous`. |
| renderItem | `Snippet<[PaginationItemContext]>` | no |  | Render each numbered page button yourself. Receives a `PaginationItemContext` with the page number, its active/disabled state, the forwarded style props (size, variant, intent, tier, mint) and a `select` callback. Only affects the numbered page buttons in the default layout — prev/next/first/last keep their own icon snippets, and the ellipsis is unaffected. |
| showFirstLast | `boolean` | no | true | Show "First" / "Last" boundary buttons when the current page is far from the edges. Deliberately redundancy-gated to the number window: the buttons render only beside a start/end ellipsis, so without `showNumbers` there is no number window, no ellipsis — and no First/Last buttons. That coupling is intentional (a compact prev/next-only bar stays compact), not a bug. Setting `showFirstLast` explicitly while `showNumbers` is `false` warns once per instance in dev. |
| showInfo | `boolean` | no |  | Show a text summary such as "Page 3 of 10" beneath the controls. |
| showNumbers | `boolean` | no |  | Show numbered page buttons. Set to false for a compact prev/next-only bar. |
| showPreviousNext | `boolean` | no |  | Show "Previous" / "Next" navigation buttons. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Button dimensions. Affects page numbers, prev/next, and first/last. |
| slotClasses | `Partial<Record<PaginationSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when unstyled) tv styles. Slots: base, info, controls, ellipsis. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| startItem | `number` | no |  | Override the calculated start item number for the info text. |
| tier | `InteractiveTier` | no |  | Semantic radius tier forwarded to pagination buttons. |
| totalItems | `number` | no |  | Total number of items across all pages. Used by the table layout info text. |
| unstyled | `boolean` | no |  | Strip all default variant classes, on the page buttons too, for a fully custom build. |
| variant | `'outlined' | 'filled' | 'ghost'` | no | 'ghost' | Visual weight of pagination buttons. The current page carries its own encoding regardless (a filled face on `outlined`, a subtle fill plus ring on `ghost`), so the quiet default keeps a nine-button page window from reading as a row of equally loud pills. |
| visiblePages | `number` | no |  | Maximum number of page buttons shown between the ellipsis indicators. |
| layout | `'default' | 'minimal' | 'navigation' | 'table'` | no | default | Controls the layout behavior and appearance of the Pagination component. Available options: default, minimal, navigation, table. |

Inherited from:
- Omit<PaginationVariants, 'disabled' | 'loading'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'class'> (omit-pattern)

### Types
```ts
interface PaginationPageItem {
label: string;
  value: number;
  href?: string;
  active?: boolean;
  disabled?: boolean;
}
```

```ts
interface PaginationItemContext {
/** The 1-based page number this item represents. */
  page: number;
  /** Whether this item is the currently active page. */
  active: boolean;
  /** Whether the item is inert (component `disabled` or `loading`). */
  disabled: boolean;
  /** Button size forwarded from the Pagination props. */
  size: 'sm' | 'md' | 'lg';
  /** Button variant forwarded from the Pagination props.
   * @summary How much weight the page buttons carry.
   */
  variant: 'outlined' | 'filled' | 'ghost';
  /** Semantic intent forwarded from the Pagination props. */
  intent: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
  /** Semantic radius tier forwarded from the Pagination props. */
  tier?: InteractiveTier;
  /** Micro-interaction preset forwarded from the Pagination props. */
  mint: MintProp;
  /** Navigate to this page. No-op when disabled, already active, or out of range. */
  select: () => void;
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `info`, `controls`, `ellipsis`

---

## PasskeyManager
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Self-service panel for managing passkeys (WebAuthn credentials). Register, list, rename and delete passkeys.
Renaming happens inline on the row: the name becomes a text field, Enter or Save commits, Escape or Cancel restores it, and focus returns to the row's rename button either way.
Communicates with `apiPath` (default `/api/auth/passkey`). Pair with `createPasskeyHandlers` — this panel uses its `registrationOptions`, `registrationVerify`, `list` (GET `${apiPath}/list`) and `item` (DELETE and PATCH on `${apiPath}/[credentialId]`) groups; the login flow additionally uses `authenticationOptions` and `authenticationVerify`.

**Import:** `import { PasskeyManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<PasskeyManager {t} apiPath="/api/auth/passkey" />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/auth/passkey' | API base path for passkey operations. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ PasskeyManager: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| slotClasses | `Partial<Record<'root' | 'title' | 'error' | 'success' | 'list' | 'item' | 'empty' | 'renameForm' | 'renameField', string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`, `title`, `error`, `success`, `list`, `item`, `empty`, `renameForm`, `renameField`

---

## PinInput
Segmented one-time-code / PIN entry — a row of single-character
cells with auto-advance, backspace-to-previous, paste-to-fill, and optional
masking. Purpose-built for the 2FA/OTP step: the first cell carries
`autocomplete="one-time-code"` on its own, so iOS offers an incoming SMS code
as a keyboard suggestion. The value is the concatenated string; `onComplete`
fires each time the row becomes complete.

**Import:** `import { PinInput } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  let code = $state('');
</script>
<PinInput bind:value={code} length={6} onComplete={(v) => verify(v)} />
```

```svelte
<PinInput length={8} type="alphanumeric" mask separator="-" groupSize={4} />
```

### Variants
- intent: danger, default, success, warning (default: default)
- variant: filled, ghost, outlined (default: outlined)
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- messageType: error, helper (default: helper)
- readonly: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class' | 'id' | 'aria-label') |
| ...PinInputVariants | `VariantProps` | no |  | Styling variants from PinInputVariants |
| aria-label | `string` | no |  | Accessible name for the cell group when no visible `label` is set. Each cell additionally announces its position ("Character 2 of 6"). |
| autoFocus | `boolean` | no | false | Focus the first empty cell on mount. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | Blocks input and dims the whole row. |
| error | `string` | no |  | Error message below the cells. When set it overrides `helper`, colours the cells danger, and sets `aria-invalid` on every cell. |
| groupSize | `number` | no | 3 | Cells per group when `separator` is set. |
| helper | `string` | no |  | Helper text below the cells — hidden when `error` is present. |
| id | `string` | no |  | Root id; the cells derive their ids and ARIA wiring from it. |
| label | `string` | no |  | Group label rendered above the cells and linked via `aria-labelledby`. |
| length | `number` | no | 6 | Number of cells. |
| mask | `boolean` | no | false | Render each filled cell as a masked dot (password style). For a standing PIN or passcode, not for a throwaway SMS code — masking one buys no secrecy and costs the user the ability to check what they typed. |
| name | `string` | no |  | Shared `name` for a hidden input, for native form submission. |
| onComplete | `(value: string) => void` | no |  | Fires each time the row becomes complete, with the full value — so correcting a rejected code fires it again. Not once per mount. |
| onValueChange | `(value: string) => void` | no |  | Fires after any change (typing, paste, backspace) with the full value. |
| placeholder | `string` | no | '' | Placeholder character shown in every empty cell. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ PinInput: {...} }}>`. |
| readonly | `boolean` | no | false | Shows the value but refuses edits; the cells stay focusable. |
| required | `boolean` | no | false | Marks the label with an asterisk and sets `aria-required` on the cells. It does not block a native submit — the value lives in component state, so validate it yourself before you act on it. |
| separator | `string` | no |  | Render a separator between groups of `groupSize` cells (e.g. `123-456`). A string is shown verbatim; omit for no separator. |
| slotClasses | `Partial<Record<PinInputSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: root (what `class` also targets) | label | requiredMark | group | cell | separator | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| type | `'numeric' | 'alphanumeric'` | no | 'numeric' | Allowed characters and keyboard hint. `numeric` accepts `0-9` and sets a numeric inputmode; `alphanumeric` also accepts `A-Z`/`a-z`. |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |
| uppercase | `boolean` | no | false | Uppercase alphanumeric input as it is entered — keeps a code like `ABCD` visually consistent regardless of caps lock. Ignored for `numeric`. |
| value | `string` | no |  | Current value — the concatenated cell characters. Supports `bind:value`. |
| intent | `'danger' | 'default' | 'success' | 'warning'` | no | default | Controls the color theme and semantic meaning of the PinInput. Affects the overall appearance and user perception. Available options: danger, default, success, warning. |
| variant | `'filled' | 'ghost' | 'outlined'` | no | outlined | Controls the visual style and presentation of the PinInput. Determines the component's visual treatment. Available options: filled, ghost, outlined. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the PinInput. Affects the component's physical footprint. Available options: lg, md, sm. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the PinInput component. Available options: error, helper. |
| tier | `'commit' | 'modify'` | no | modify | Selects the semantic radius tier of the PinInput — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

Inherited from:
- Omit<PinInputVariants, 'error'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'id' | 'aria-label'> (omit-pattern)

### Types
```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`root`, `label`, `requiredMark`, `group`, `cell`, `separator`, `message`

---

## Planner
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Date-indexed planning board — a week, month or custom-range grid
whose cells hold YOUR domain content (meals, shifts, bookings, content slots)
via a generic `cell` snippet. Buckets `items` by calendar day, then handles
navigation, ISO week numbers, keyboard a11y and a responsive column→stack
layout. For timed appointments, multi-day spans or recurrence use `Calendar`
instead.

**Import:** `import { Planner } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Planner view="week" items={entries} getDate={(e) => e.date}
sort={(a, b) => MEAL_ORDER[a.mealType] - MEAL_ORDER[b.mealType]}
bind:value={referenceDate} onNavigate={(_, range) => loadWeek(range.start)}>
{#snippet cell({ items, isoDate })}
{#each items as entry (entry.id)}
<MealCard {entry} />
{/each}
<Button variant="ghost" size="sm" onclick={() => openAdd(isoDate)}>Add meal</Button>
{/snippet}
</Planner>
```

### Variants
- variant: bordered, default, ghost (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| getDate | `(item: T) => Date | string` | yes |  | Map an item to its calendar day. Return a `Date`, or a local date string (`'2026-06-16'`) taken verbatim — never UTC-parsed, so a plain date never shifts across timezones. A date-*time* string is bucketed by its written date part too; if your value is a UTC instant whose local day matters (`'…T23:00:00Z'`), return `new Date(value)` so the local timezone applies. Required. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...PlannerVariants | `VariantProps` | no |  | Styling variants from PlannerVariants |
| animated | `boolean` | no | true | Slide-transition the grid on navigate (respects reduced-motion). |
| cell | `Snippet<[PlannerCellContext<T>]>` | no |  | Render a day's content — the core of the API. Receives bucketed `items: T[]`. Called for **every** day, including empty ones (`items: []`) — unless an `empty` snippet is given, which then handles empty days instead. Put an "add" affordance here to keep it available on empty days. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| dayHeader | `Snippet<[PlannerDayContext]>` | no |  | Customise each weekday/column header. |
| disabled | `boolean` | no | false | Disable navigation and selection. |
| disabledDates | `Date[]` | no |  | Specific dates that cannot be selected. |
| empty | `Snippet<[PlannerCellContext<T>]>` | no |  | Placeholder rendered **instead of** `cell` for days with no items. Omit it to let `cell` render empty days too. |
| fixedWeeks | `boolean` | no | false | Always render 6 week rows in `view="month"`, so the grid keeps its height across months of 4, 5 and 6 rows. Ignored in `week`/`range`. |
| header | `Snippet<[PlannerHeaderContext]>` | no |  | Replace the default toolbar (prev/next/today/title/week). |
| highlightToday | `boolean` | no | true | Visually mark today's cell. |
| highlightWeekend | `boolean` | no | false | Tint Saturday/Sunday cells. |
| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate for dates that cannot be selected, on top of `minDate`/`maxDate`. |
| items | `T[]` | no |  | The items to lay out. Each is bucketed onto a day via `getDate`. |
| locale | `string` | no | 'auto' | BCP 47 locale tag for date formatting — month names, weekday names and the header title. Defaults to `'auto'`, which follows the active `<I18nProvider>` locale, so an app that already declares its language does not have to repeat it here. SSR-safe: the locale comes from context, so the server and the client resolve the same tag (`Intl` with `undefined` would follow the runtime and disagree across hydration). Falls back to the base locale (`en`) when no provider is mounted. Pass an explicit tag (e.g. `'de-DE'`, `'ja-JP'`) to override. |
| maxDate | `Date` | no |  | Latest navigable/selectable date. |
| minDate | `Date` | no |  | Earliest navigable/selectable date. |
| onDateSelect | `(date: Date) => void` | no |  | Fires when a day cell is activated (click / Enter / Space). |
| onNavigate | `(date: Date, range: DateRange) => void` | no |  | Fires after navigation. Receives the new reference date and visible range — load data here. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Planner: {...} }}>`. |
| rangeEnd | `Date` | no |  | End of the window for `view="range"`. |
| rangeStart | `Date` | no |  | Start of the window for `view="range"`. |
| selectedDate | `Date` | no |  | The active highlighted day. Supports `bind:selectedDate`. |
| showWeekNumber | `boolean` | no |  | Renamed to `showWeekNumbers` for parity with `Calendar`, which has carried the plural since long before Planner existed. Still honoured, and warns in DEV. |
| showWeekNumbers | `boolean` | no | false | Show the ISO week-number column on the left. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Density of the grid and header. |
| slotClasses | `Partial<Record<PlannerSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: base | header | headerTitle | nav | navButton | grid | weekdayHeader | weekday | weekNumber | week | cell | cellHeader | cellWeekday | cellDate | cellItems | empty. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| sort | `(a: T, b: T) => number` | no |  | Comparator for items within a day cell (e.g. by meal type or start label). |
| swipeable | `boolean` | no | true | Enable horizontal swipe-to-navigate on touch. |
| unstyled | `boolean` | no | false | Remove all default tv() classes — only user-provided classes apply. Reaches the header's today-button tooltip. |
| value | `Date` | no | today | Reference date the view is anchored on. Supports `bind:value`. |
| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual treatment. |
| view | `PlannerView` | no | 'week' | Layout mode. |
| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week (0=Sun … 6=Sat). |

Inherited from:
- Omit<PlannerVariants, 'view' | keyof PlannerCellState> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type PlannerCellState = Pick<
  PlannerVariants,
  'dayState' | 'selected' | 'weekend' | 'outside'
>
```

```ts
interface DateRange {
start: Date;
  end: Date;
}
```

```ts
interface PlannerCellContext {
/** The cell's date (local midnight). */
  date: Date;
  /** `YYYY-MM-DD` local key for this date — the same key items were bucketed on. */
  isoDate: string;
  /** Items falling on this day, bucketed and sorted (the consumer's `T`). */
  items: T[];
  /** Whether this date is today. */
  isToday: boolean;
  /** Whether this date is the active selected day (`selectedDate`). */
  isSelected: boolean;
  /** Whether this date is a Saturday or Sunday. */
  isWeekend: boolean;
  /** Whether this date spills outside the focused month / requested range. */
  isOutsideRange: boolean;
  /**
   * Whether this date cannot be selected — outside `[minDate, maxDate]`, listed
   * in `disabledDates`, rejected by `isDateDisabled`, or the whole grid is
   * `disabled`. The scaffold already sets `aria-disabled` on the gridcell; read
   * this to grey out your own content or hide an "add" affordance.
   */
  isDisabled: boolean;
  /** ISO 8601 week number of this date. */
  weekNumber: number;
  /** Localized short weekday name (e.g. "Mo") — handy for stacked layouts. */
  weekday: string;
  /** Make this day the active selection (fires `onDateSelect`). */
  selectDate: () => void;
}
```

```ts
interface PlannerDayContext {
/** The concrete date in single-week (`week`) view; `undefined` in month/range
   * where a column spans many dates. */
  date?: Date;
  /** `YYYY-MM-DD` local key, present only when `date` is. */
  isoDate?: string;
  /** Localized short weekday name (e.g. "Mo"). */
  weekday: string;
  /** Whether the column's concrete date is today (always false in month/range). */
  isToday: boolean;
  /** Whether this is a weekend column. */
  isWeekend: boolean;
  /** ISO week number of the column's date, when it has one. */
  weekNumber?: number;
}
```

```ts
interface PlannerHeaderContext {
/** Localized title for the current view (e.g. "KW 25 · 15.–21. Juni"). */
  title: string;
  /** First visible date of the view. */
  rangeStart: Date;
  /** Last visible date of the view. */
  rangeEnd: Date;
  /** ISO week number of the reference date. */
  weekNumber: number;
  /** The active view. */
  view: PlannerView;
  /** Step the view by `delta` periods (− back, + forward). */
  navigate: (delta: number) => void;
  /** Jump to the period containing today. */
  goToToday: () => void;
  /** Jump to the period containing `date`. */
  goTo: (date: Date) => void;
  /** Whether back-navigation is within bounds. */
  canGoBack: boolean;
  /** Whether forward-navigation is within bounds. */
  canGoForward: boolean;
  /** Whether today is within `[minDate, maxDate]`; gate a custom Today control on it. */
  canGoToToday: boolean;
}
```

```ts
type PlannerView = 'week' | 'month' | 'range'
```

### Slots (slotClasses keys)
`base`, `grid`, `weekdayHeader`, `weekday`, `weekNumber`, `week`, `cell`, `cellHeader`, `cellWeekday`, `cellDate`, `cellItems`, `empty`

---

## PlaygroundConfigurator
Interactive playground configurator for component documentation.
Renders a live preview, control panel for props, and generated code block.

**Import:** `import { PlaygroundConfigurator } from '@urbicon-ui/docs';`

### Examples
```svelte
<PlaygroundConfigurator
  componentName="Button"
  controls={controls}
  values={values}
>
  {#snippet children(vals)}
    <Button {...vals}>Click me</Button>
  {/snippet}
</PlaygroundConfigurator>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet<[Record<string, any>]>` | yes |  | Render snippet receiving the current values map. The argument is typed loosely (`Record<string, any>`) so consumers can spread it onto child components without type-asserting each variant key — the trade-off is that direct property access inside the snippet is also `any`. Use the `values` prop type for typed access.  The `any` here is a pragmatic exception to the project-wide ban: it enables docs-page playgrounds (`<Component {...values} />`) to compile without forcing every consumer to mirror the full prop union locally. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...PlaygroundConfiguratorVariantProps | `VariantProps` | no |  | Styling variants from PlaygroundConfiguratorVariantProps |
| class | `string` | no |  | Extra CSS classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| codeGenerator | `(values: TValues) => string` | no |  | Custom code generator. Falls back to auto-generated Svelte tag syntax. |
| codeSetup | `CodeSetup` | no |  | Imports and data declarations the generated snippet needs to be a complete, copyable file.  Omit it for components whose props tell the whole story — `<Button variant="ghost">Get started</Button>` needs nothing above it. Supply it for components that are meaningless without data: a `Table` needs `columns` and `items`, an `A2UIView` a `payload`. `consts` takes the very objects the demo renders, so the snippet cannot fall out of step with the preview. |
| componentName | `string` | no | 'Component' | Component name used in the auto-generated code output. |
| controls | `ControlDefinition[]` | no |  | Control definitions that drive the props panel (dropdown, toggle, text, etc.).  Optional, because not every component has anything to turn: the auth family has API paths and callbacks, not variant axes. Left out, the props panel is not rendered at all and the configurator carries just the stage and the code panel — which is the part those components were missing. |
| defaultCodeExpanded | `boolean` | no |  | Forces the code panel open or closed regardless of the page-wide code switch. Leave it unset: the panel then follows `CodeVisibilityStore` on a docs page, and starts collapsed where there is none (the landing hero). |
| onValuesChange | `(values: TValues) => void` | no |  | Fires after any control value changes with the full values map. |
| propDocs | `Record<string, string>` | no |  | Hand-written prop descriptions (from JSDoc). Shown as tooltip behind an info icon. |
| shareKey | `string` | no |  | Identity this playground's share links are scoped to, emitted as `_pg`. A link only seeds the instance whose key it names, so a page with several playgrounds does not decode one link into all of them.  Defaults to `componentName`, which already separates instances documenting different components. Set it only to tell same-named instances on one page apart (`shareKey="Button-sizes"`); the value shows up in the URL, so make it readable. |
| showHeader | `boolean` | no | true | Show the title/subtitle header above the playground. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Controls the density of the playground layout – padding, grid columns, and text size. |
| slotClasses | `Partial<Record<PlaygroundConfiguratorSlotName, string>>` | no |  | Per-slot class overrides for internal elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| source | `string` | no |  | The playground's own source text, for demos whose content is **markup** rather than data — a Card's header and footer snippets, a SplitPane's two panes, the `<SegmentItem>`s inside a SegmentGroup. `codeSetup` cannot reach those (there is no data form they could take), so their snippets otherwise read `<Card />`: true and useless.  Pass it as a raw import, which costs nothing but the file's own text in the chunk that already holds the playground:  ```svelte import playgroundSource from './Playground.svelte?raw'; <PlaygroundConfigurator source={playgroundSource} …> ```  Name it `playgroundSource`, not `self`: `self` is `window.self`, so a missing import type-checks against the global and silently passes the Window object instead of failing.  Only the children are taken; the opening tag stays generated from the live control values, so default props keep out of the snippet. Markup that refers to names the snippet does not declare is dropped rather than printed broken — declare them in `codeSetup.consts` to show it. |
| subtitle | `string` | no |  | Descriptive text below the title. |
| title | `string` | no |  | Heading text above the playground panel. |
| unstyled | `boolean` | no | false | Strip all default tv() styles from internal slots. |
| values | `TValues` | no |  | Current control values. Supports `bind:values` for two-way binding. |
| variantKeys | `string[]` | no |  | Prop names originating from a tv() variant axis. Shown with a "V" indicator. |

Inherited from:
- Omit<PlaygroundConfiguratorVariantProps, 'size'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
type PlaygroundConfiguratorSlotName = | PlaygroundConfiguratorSlots
  | 'codeToolbar'
  | 'codeDisplay'
```

```ts
interface CodeSetup {
/** Import lines, in the order they should appear. */
  imports?: string[];
  /**
   * `const <name> = <value>` per entry, printed from the value itself. Use
   * `{ raw: '…' }` for anything without a faithful printed form (functions,
   * snippet references).
   */
  consts?: Record<string, unknown>;
  /**
   * `let <name> = $state(<value>)` per entry — what a `bind:` needs on the
   * other side. A `<Dialog bind:open />` snippet without the `let` is not code
   * anyone can run.
   */
  state?: Record<string, unknown>;
  /** Names passed to the component as the `{name}` shorthand, ahead of the control props. */
  bind?: string[];
  /**
   * Names passed as `bind:name`. Only for props the demo really binds two-way —
   * a `Progress` that reads a `$state` value still passes it one way, and
   * printing `bind:value` would document an API it does not have.
   */
  twoWay?: string[];
  /**
   * Controls that steer the demo but are not props of the component (a
   * scenario switch, a "show marks" toggle). They drive the preview and must
   * not show up in the snippet as an attribute that does not exist.
   */
  demoOnly?: string[];
}
```

### Slots (slotClasses keys)
`root`, `header`, `title`, `subtitle`, `container`, `preview`, `previewContent`, `controlsPanel`, `controlsHeader`, `controlsGrid`, `controlItem`, `controlLabel`, `controlControl`, `controlControlCompact`, `modifiedDot`, `variantBadge`, `colorInput`, `controlHint`, `actionsBar`, `helpToggle`, `helpToggleActive`, `codePanel`

---

## Popover
Floating panel anchored to a trigger element. Uses the native Popover API
for top-layer rendering, light dismiss, and Escape handling. The library's built-in
positioning engine provides automatic flip, shift, and optional width syncing.

**Import:** `import { Popover } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Popover placement="bottom-start">
  {#snippet trigger()}
    <Button>Open</Button>
  {/snippet}
  {#snippet children()}
    <div class="p-3">Popover content</div>
  {/snippet}
</Popover>
```

```svelte
<Popover placement="top" bind:open={showInfo}>
  {#snippet trigger()}
    <Button variant="ghost" size="sm">More info</Button>
  {/snippet}
  {#snippet children()}
    <div class="max-w-xs p-4">
      <h4 class="font-semibold">Details</h4>
      <p class="text-text-secondary text-sm">Additional context shown in a floating panel.</p>
    </div>
  {/snippet}
</Popover>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Popover body rendered inside the floating panel. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...PopoverVariants | `VariantProps` | no |  | Styling variants from PopoverVariants |
| autoTrigger | `boolean` | no |  | When true (default), the trigger wrapper handles click and keyboard to toggle the popover. Set to `false` to manage `open` yourself. |
| class | `string` | no |  | Extra classes merged onto the floating panel element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| closeOnClickOutside | `boolean` | no |  | Whether the popover closes on outside click / pointer interaction. Default `true`. Set to `false` to pin the popover open until the consumer explicitly toggles `open`. |
| closeOnEscape | `boolean` | no |  | Whether the popover closes on Escape key. Default `true`. Set to `false` for cases where Escape should be intercepted by an inner widget (e.g. an editable cell that wants to revert on Escape). |
| inline | `boolean` | no | false | Render in a way that is legal inside **phrasing content** — a paragraph or a heading. Set this when the trigger sits in flowing text, as a citation chip does inside a markdown paragraph.  A `<label>` is phrasing content too, but think twice there: after mount the panel is a DOM descendant of the label, so a click on non-interactive panel content forwards activation to the labelled control. Top-layer promotion changes where the panel *paints*, not where it sits in the tree.  Two things change. The trigger wrapper becomes a `<span>` instead of a `<div>`, and the panel is not rendered on the server at all — it appears after mount. Both are needed together: a `<div>` start tag closes an open `<p>` regardless of how deeply it is nested, so wrapping the trigger alone leaves the panel to break the paragraph instead.  Withholding the panel costs nothing the server render was providing: it is hidden and `inert` until opened, and opening requires the client anyway.  Without it, an SSR'd page with a popover in a paragraph emits invalid HTML. The parser repairs it by closing the `<p>` early, which makes the server DOM differ from the component tree — Svelte logs `node_invalid_placement_ssr` and then `hydration_mismatch`, and the layout visibly shifts on hydration.  **Cost:** the panel is absent from the prerendered HTML, so a non-rendering crawler never sees its content and the first paint has nothing to show if the popover is meant to open immediately. Leave it off for popovers in block context, where the default markup is already valid. |
| offsetDistance | `number` | no |  | Gap in px between the trigger edge and the popover. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the popover. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the popover closes — that is governed by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the popover. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the popover closes — that is governed by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the popover opens or closes from user interaction (click, escape, click-outside). Receives the new open state. |
| open | `boolean` | no |  | Controlled open state. Supports `bind:open`. |
| placement | `Placement` | no |  | Where the popover appears relative to the trigger. All standard `Placement` values (side plus optional `-start`/`-end` alignment) are supported. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Popover: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| shiftPadding | `number` | no |  | Minimum px padding from viewport edges when the popover shifts to stay visible. |
| slotClasses | `Partial<Record<'base', string>>` | no |  | Per-slot class overrides. Available slots: `base` (the floating panel). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| syncMinWidth | `boolean` | no |  | Match the popover's *minimum* width to the trigger width while still letting content grow the panel beyond it. Useful for menu-style overlays where items longer than the trigger should not get truncated. Ignored when `syncWidth` is true (hard width wins). |
| syncWidth | `boolean` | no |  | Match the popover width to the trigger width. Useful for select/autocomplete patterns where the floating panel should align with the input. |
| transitionDuration | `number` | no |  | Override the enter/exit fade duration in ms. Defaults to the shared token `--blocks-popover-duration` (150ms; collapses to 1ms under `prefers-reduced-motion`). |
| transitionEasing | `string` | no |  | Override the enter/exit easing as a CSS `<easing-function>` (e.g. `'linear'`, `'ease-out'`, `'cubic-bezier(0.4,0,0.2,1)'`). Defaults to the token `--blocks-popover-easing`. A CSS string, not a JS easing fn, because the popover motion is a pure CSS transition. |
| trigger | `Snippet` | no |  | Trigger element that anchors and toggles the popover. Receives click/keyboard handlers when `autoTrigger` is true. |
| triggerElement | `HTMLElement` | no |  | External trigger element ref. Use instead of the `trigger` snippet when the trigger lives outside the Popover tree. Supports `bind:triggerElement`. |
| unstyled | `boolean` | no |  | Strip all default tv() classes (including the enter/exit motion). Combine with `class` or `slotClasses` for full custom styling; the panel always carries `data-state="open" | "closed"`, so custom motion can rebuild on that hook (see `popoverMotion` in popover.variants.ts for the reference implementation). |
| usePortal | `boolean` | no | true | Render the floating panel into the browser's top layer via the native `popover` attribute, so it cannot be clipped by `overflow: auto` ancestors. Set to `false` when the popover is itself embedded inside another floating surface (Dialog, Drawer, another Popover) — nested top-layer rendering stacks unpredictably across browsers and stealing focus from the parent surface is usually unwanted. In-flow mode positions the panel absolutely relative to the trigger's offset parent. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Popover. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- PopoverVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

### Slots (slotClasses keys)
`base`

---

## Progress
Progress indicator for determinate and indeterminate loading states.
Supports linear bar and circular ring variants with semantic intents and animation.

**Import:** `import { Progress } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Progress value={65} label="Upload progress" showValue />
```

```svelte
<Progress value={80} shape="circular" intent="success" showValue />
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- size: lg, md, sm, xs (default: md)
- animated: true (default: false)
- indeterminate: true (default: false)
- striped: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...ProgressVariants | `VariantProps` | no |  | Styling variants from ProgressVariants |
| animated | `boolean` | no | false | Animate the striped pattern. Requires `striped` to be true. |
| circularSize | `number` | no | 80 | Diameter of the circular indicator in pixels. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| formatValue | `(value: number, max: number) => string` | no | (v, max) => `${Math.round((v/max) * 100)}%` | Format function for the displayed value. |
| label | `string` | no |  | Text label displayed above or inside the progress indicator. |
| max | `number` | no | 100 | Maximum value for the progress range. |
| min | `number` | no | 0 | Minimum value for the progress range. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Progress: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| shape | `'linear' | 'circular'` | no | 'linear' | Shape of the progress indicator. |
| showValue | `boolean` | no | false | Show the numeric value (percentage or absolute) next to the label. |
| slotClasses | `Partial<Record<ProgressSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (linear root — what `class` targets in linear shape) | header | label | valueText | track | fill | circularWrapper (circular root — what `class` targets in circular shape) | circularTrack | circularFill | circularLabel. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| striped | `boolean` | no | false | Display striped pattern on the fill. |
| strokeWidth | `number` | no | 6 | Stroke width of the circular indicator in pixels. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| value | `number` | no |  | Current progress value (0–100). Omit for indeterminate mode. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Progress. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Progress. Affects the component's physical footprint. Available options: lg, md, sm, xs. |
| indeterminate | `'true'` | no | false | Controls the indeterminate behavior and appearance of the Progress component. Available options: true. |

Inherited from:
- ProgressVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Slots (slotClasses keys)
`wrapper`, `header`, `label`, `valueText`, `track`, `fill`, `circularWrapper`, `circularTrack`, `circularFill`, `circularLabel`

---

## PromptInput
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
The chat composer: an auto-growing textarea in a single bordered
surface with a send button that flips to a stop button while a response is
streaming. `onSubmit({ text, attachments })` fires with trimmed text when there
is content (or at least one attachment); `onStop` fires from the stop button.
Attachment intake (paperclip picker, clipboard paste, drag-and-drop, chip strip)
reuses the shared `file-intake` core — the same accept/size/count validation and
preview-URL lifecycle as FileUpload — and is opt-in via `allowAttachments`.

**Import:** `import { PromptInput } from '@urbicon-ui/blocks';`

### Examples
```svelte
<PromptInput
  bind:value={draft}
  busy={isStreaming}
  onSubmit={({ text }) => send(text)}
  onStop={abort}
/>
```

```svelte
<PromptInput
bind:value={draft}
bind:attachments={files}
allowAttachments
accept="image/*"
maxFiles={4}
submitOn="mod-enter"
onSubmit={({ text, attachments }) => send(text, attachments)}
/>
```

### Variants
- size: md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| onSubmit | `(payload: { text: string; attachments: FileIntakeEntry[] }) => void` | yes |  | Fired on send with the trimmed text and the current attachments. Only fires when there is text or at least one attachment, and never while `busy` or `disabled`. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class' | 'onsubmit') |
| ...PromptInputVariants | `VariantProps` | no |  | Styling variants from PromptInputVariants |
| accept | `string | string[]` | no |  | Accepted MIME types / extensions (e.g. `'image/*'`, `['.pdf', 'image/png']`). |
| allowAttachments | `boolean` | no | false | Enable the attachment surface: paperclip picker, clipboard-image paste, drag-and-drop, and the chip strip above the textarea. |
| attachLabel | `string` | no | 'Attach file' | Accessible label for the attach button. |
| attachments | `FileIntakeEntry[]` | no |  | The accepted attachments (bindable). Populated by the picker / paste / drop when `allowAttachments` is set. On submit these are handed to `onSubmit` and — with `clearOnSubmit` — cleared from here **without** revoking their preview object-URLs, because ownership transfers to the consumer's message list.  Removing chips through the built-in UI revokes their preview URLs for you. Clearing or splicing this array **externally** (e.g. reassigning `bind:attachments`) bypasses that cleanup — such mutations must revoke the dropped entries' previews themselves via `revokeIntakePreviews` (exported from `$lib/utils/file-intake`) to avoid leaking object-URLs. |
| autofocus | `boolean` | no | false | Focus the textarea on mount. |
| busy | `boolean` | no | false | A response is in flight: the send button is replaced by a stop button and Enter no longer submits. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clearOnSubmit | `boolean` | no | true | Clear the text and attachments after a successful submit. Preview URLs of the submitted attachments are intentionally **not** revoked — see `attachments`. |
| disabled | `boolean` | no | false | Disables the whole composer (textarea + buttons). |
| hint | `Snippet` | no |  | Helper line rendered under the composer (e.g. "Enter to send"). |
| label | `string` | no | 'Message' | Accessible name for the textarea (rendered as `aria-label`). |
| leading | `Snippet` | no |  | Content in the leading (left) action zone, after the attach button. |
| maxFiles | `number` | no |  | Maximum number of attachments across the whole list. |
| maxFileSize | `number` | no |  | Maximum attachment size in bytes. |
| maxRows | `number` | no | 8 | Maximum visible rows before the textarea scrolls internally. |
| minRows | `number` | no | 1 | Minimum visible rows of the auto-growing textarea. |
| onAttachmentReject | `(rejections: FileIntakeRejection[]) => void` | no |  | Called with the rejected files when an add is refused (bad type, too large, over `maxFiles`, duplicate, or custom `validate`). The first rejection's message also surfaces inline; it clears on the next successful add. |
| onStop | `() => void` | no |  | Fired by the stop button (shown in place of send while `busy`). |
| onValueChange | `(value: string) => void` | no |  | Called whenever the text changes (including the clear after submit). |
| placeholder | `string` | no |  | Placeholder text for the textarea. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ PromptInput: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette. |
| preventDocumentDrop | `boolean` | no | true | Prevent browser navigation when a file is dropped outside the composer. Only takes effect while `allowAttachments` is set. |
| removeAttachmentLabel | `(name: string) => string` | no | (name) => `Remove ${name}` | Accessible label factory for a chip's remove button. |
| sendLabel | `string` | no | 'Send' | Accessible label for the send button. |
| slotClasses | `Partial<Record<PromptInputSlots, string>>` | no |  | Per-slot class overrides. Slots: root | attachmentsStrip | attachmentChip | attachmentThumb | attachmentName | attachmentSize | attachmentRemove | textarea | actions | leading | trailing | attachButton | sendButton | stopButton | error | hint. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| stopLabel | `string` | no | 'Stop' | Accessible label for the stop button. |
| submitOn | `'enter' | 'mod-enter'` | no | 'enter' | Which key gesture sends the message. - `enter` (default) — Enter sends, Shift+Enter inserts a newline. - `mod-enter` — Cmd/Ctrl+Enter sends, Enter inserts a newline.  Submission is always suppressed mid-IME-composition. |
| trailing | `Snippet` | no |  | Content in the trailing (right) action zone, before the send/stop button. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| validate | `(file: File) => FileIntakeEntry['errors'] | null` | no |  | Custom per-file validation. Return an errors array or `null`. |
| value | `string` | no |  | The composer's text (bindable). |
| size | `'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the PromptInput. Affects the component's physical footprint. Available options: md, sm. |

Inherited from:
- PromptInputVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'onsubmit'> (omit-pattern)

### Types
```ts
interface FileIntakeEntry {
/** Unique identifier for this file entry. */
  id: string;
  /** The native File object. */
  file: File;
  /** Object URL for image previews (auto-generated, auto-revoked). */
  preview?: string;
  /** Upload progress 0–100. Undefined when not tracking. */
  progress?: number;
  /** Current lifecycle status. */
  status: FileIntakeStatus;
  /** Validation or upload errors. */
  errors: FileIntakeError[];
}
```

```ts
interface FileIntakeRejection {
/** The rejected file. */
  file: File;
  /** Why it was rejected. */
  errors: FileIntakeError[];
}
```

```ts
type FileIntakeStatus = 'pending' | 'uploading' | 'complete' | 'error'
```

```ts
interface FileIntakeError {
/** Machine-readable error code. */
  code: FileIntakeErrorCode;
  /** Human-readable error message. */
  message: string;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type FileIntakeErrorCode = | 'FILE_INVALID_TYPE'
  | 'FILE_TOO_LARGE'
  | 'FILE_TOO_SMALL'
  | 'TOO_MANY_FILES'
  | 'FILE_EXISTS'
  | 'CUSTOM'
```

### Slots (slotClasses keys)
`root`, `attachmentsStrip`, `attachmentChip`, `attachmentThumb`, `attachmentName`, `attachmentSize`, `attachmentRemove`, `textarea`, `actions`, `leading`, `trailing`, `attachButton`, `sendButton`, `stopButton`, `error`, `hint`

---

## PushPermissionPrompt
A dismissible prompt that asks the user to enable push notifications,
then registers the VAPID subscription with the server.

**Import:** `import { PushPermissionPrompt } from '@urbicon-ui/auth';`

### Examples
```svelte
<PushPermissionPrompt {t} vapidPublicKey={PUBLIC_VAPID_KEY}
  onSubscribed={(sub) => console.log('Subscribed', sub)}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| vapidPublicKey | `string` | yes |  | VAPID public key for push subscription. |
| apiPath | `string` | no | '/api/notifications/push-subscription' | API endpoint for registering subscriptions. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| onDismissed | `() => void` | no |  | Called when the user dismisses the prompt. |
| onSubscribed | `(subscription: PushSubscription) => void` | no |  | Called after successful push subscription. |
| onUnavailable | `(reason: 'denied' | 'unsupported') => void` | no |  | Called when the prompt closes because push is not available: the user declined the browser permission (`'denied'`) or the browser has no push support (`'unsupported'`). Persist this to avoid remounting the prompt on every visit; without it, a denial is indistinguishable from never having shown the prompt. Operational failures do not close the prompt; they show the error state instead. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ PushPermissionPrompt: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| slotClasses | `Partial<Record<'root' | 'text' | 'error' | 'actions', string>>` | no |  | Per-slot class overrides. `error` styles the error Alert itself — present only while an error is shown — not the live region that always surrounds it (the same contract as every other component's `error` slot). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`, `text`, `error`, `actions`

---

## QRCode
Renders any text or URL as a scannable QR code. The output is a
self-contained SVG with no runtime dependency: the encoder (`encodeQr`,
exported alongside) covers numeric, alphanumeric and byte modes across all 40
versions and the four error-correction levels. Pass an `otpauth://` URI here
for 2FA enrolment instead of wiring an external QR library into
`TwoFactorManager`'s `qr` snippet.

**Import:** `import { QRCode } from '@urbicon-ui/blocks';`

### Examples
```svelte
<QRCode value="https://ui.urbicon.de" size={180} frame="card" />
```

```svelte
<QRCode value={otpauthUri} errorCorrection="H" size={200} frame="card" />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| value | `string` | yes |  | The data to encode — text, a URL, an `otpauth://` URI, etc. |
| ...QRCodeVariants | `VariantProps` | no |  | Styling variants from QRCodeVariants |
| aria-label | `string` | no |  | Accessible name announced for the code. Defaults to a localized "QR code". Avoid echoing sensitive payloads (e.g. a 2FA secret) into this label. |
| background | `string` | no | 'transparent' | Background fill — any CSS colour. |
| class | `string` | no |  | Extra classes merged onto the root wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| errorCorrection | `'L' | 'M' | 'Q' | 'H'` | no | 'M' | Error-correction level: higher levels survive more damage/occlusion at the cost of a denser (larger) code. L≈7%, M≈15%, Q≈25%, H≈30%. |
| foreground | `string` | no | 'currentColor' | Colour of the dark modules — any CSS colour. Defaults to `currentColor` so the code inherits the surrounding text colour. For reliable scanning keep a high-contrast dark-on-light pairing (see `frame="card"`). |
| id | `string` | no |  | Root id. |
| maxVersion | `number` | no |  | Upper bound on the QR version (1–40). Data that does not fit calls `onError` and renders the fallback instead of encoding. |
| minVersion | `number` | no |  | Lower bound on the QR version (1–40) to force a minimum size. |
| onError | `(error: Error) => void` | no |  | Called when the data cannot be encoded (e.g. too long for `maxVersion`). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ QRCode: {...} }}>`. |
| quietZone | `number` | no | 4 | Width of the mandatory light border, in modules. The spec requires ≥4. |
| size | `number` | no | 160 | Rendered edge length in pixels (the code is square). |
| slotClasses | `Partial<Record<QRCodeSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: root (what `class` also targets) | svg | fallback. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |

Inherited from:
- QRCodeVariants (external)

### Types
```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

---

## RadioGroup
Accessible radio group for single-option selection with semantic intents and form integration.
Uses native radio inputs for correct form behavior and ARIA semantics with keyboard navigation.

**Import:** `import { RadioGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<RadioGroup label="Plan" bind:value={plan}>
  <RadioItem value="free" label="Free" />
  <RadioItem value="pro" label="Pro" description="Best for teams" />
</RadioGroup>
```

### Variants
- disabled: true (default: false)
- error: true (default: false)
- orientation: horizontal, vertical (default: vertical)
- required: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | RadioItem children to render inside the group. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no |  | Disable all radio items in the group. |
| error | `string` | no |  | Error message below the group. Replaces `helper` and sets `aria-invalid`. |
| helper | `string` | no |  | Hint text below the group. Hidden when `error` is set. |
| id | `string` | no |  | Explicit `id` for the group element. Auto-generated if omitted. |
| intent | `RadioItemVariants['intent']` | no | 'primary' | Semantic color propagated to all child RadioItems. |
| label | `string` | no |  | Group label displayed above the radio items. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to each RadioItem (per-item via context). Only applies while the item is not disabled. |
| name | `string` | no |  | Shared `name` attribute for all radio inputs. Auto-generated if omitted. |
| onValueChange | `(value: string) => void` | no |  | Fired after the selected value changes. Receives the new value. |
| orientation | `'horizontal' | 'vertical'` | no | 'vertical' | Stack direction for the radio items. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ RadioGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no |  | Require a selection: marks the label with an asterisk, sets `aria-required` on the group, and puts the constraint on the radios themselves — so an empty group blocks the form's submit like a native required control. |
| size | `RadioItemVariants['size']` | no | 'md' | Visual size propagated to all child RadioItems. |
| slotClasses | `Partial<Record<RadioGroupSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: root (what `class` also targets) | group | label | requiredMark | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tier | `InteractiveTier` | no | 'commit' | Semantic radius tier propagated to every RadioItem. Default `commit` — radio indicators read as identity circles. Set to `modify` (or inherit via TierContext from a wrapping `<Toolbar tier="modify">`) for inline-toolbar contexts where a circle feels oversized. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. Only user-provided classes apply. |
| value | `string` | no |  | Currently selected value. Supports two-way binding via `bind:value`. |
| variant | `RadioItemVariants['variant']` | no | 'outlined' | Visual weight propagated to all child RadioItems. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
interface RadioGroupContext {
readonly name: string;
  readonly size: NonNullable<RadioItemVariants['size']>;
  readonly intent: NonNullable<RadioItemVariants['intent']>;
  readonly variant: NonNullable<RadioItemVariants['variant']>;
  readonly tier: InteractiveTier;
  readonly disabled: boolean;
  readonly error: boolean;
  readonly value: string | undefined;
  readonly mint: MintProp;
  /**
   * Passed to every radio input, which is what makes the group's `required`
   * real: HTML treats a radio group as required when any radio of the `name`
   * carries the attribute, so the browser blocks an empty submit itself.
   */
  readonly required: boolean;
  select: (value: string) => void;
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`root`, `group`, `label`, `requiredMark`, `message`

---

## ReasoningDisclosure
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Default renderer for `reasoning` parts in ChatMessage. Wraps a
model's thinking trace in a collapsed, muted disclosure: the header shows a
state label ("Thinking" while streaming, "Thought for Xs" once settled with a
duration, otherwise "Reasoning"), the body renders the reasoning text through
StreamingMarkdown in a damped tertiary tone, indented rather than boxed. Stays
collapsed by default — including while streaming — so a growing reasoning
trace never steals the answer's space; the caller drives the `streaming` flag
(the part carries no status). Renders in the same register as ToolCallCard's
default header: both report how an answer came about, and a reader should be
able to tell at a glance that they are the same kind of thing.

**Import:** `import { ReasoningDisclosure } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ReasoningDisclosure
  reasoning={{ type: 'reasoning', text: model.reasoning, durationMs: 2400 }}
  streaming={message.status === 'streaming'}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| reasoning | `ChatReasoningPart` | yes |  | The reasoning part to render (`{ type: 'reasoning'; text; durationMs? }`). Required. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class' | 'children') |
| class | `string` | no |  | Extra classes merged onto the root (the underlying Collapsible base). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| defaultOpen | `boolean` | no | false | Initial expanded state for uncontrolled usage. Reasoning stays collapsed by default, even while streaming. |
| formatDuration | `(seconds: number) => string` | no | (s) => `Thought for ${s}s` | Header label once settled with a `durationMs`, receiving whole seconds (`Math.round(durationMs / 1000)`). |
| onOpenChange | `(open: boolean) => void` | no |  | Fires once per trigger-driven open transition, after the state is applied. |
| open | `boolean` | no |  | Whether the disclosure is expanded. Supports `bind:open`. Passing `open` without `bind:` requires mirroring every `onOpenChange` back into your state. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ReasoningDisclosure: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette. |
| reasoningLabel | `string` | no | 'Reasoning' | Header label once settled without a `durationMs`. |
| slotClasses | `Partial<Record<ReasoningDisclosureSlots, string>>` | no |  | Per-slot class overrides. Slots: `trigger` (header button), `label` (state label), `chevron`, `content` (markdown wrapper). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| streaming | `boolean` | no | false | The reasoning trace is currently growing. Drives the "Thinking" label and its pulse; supplied by the caller (the part itself carries no status). |
| thinkingLabel | `string` | no | 'Thinking' | Header label while `streaming`. |
| unstyled | `boolean` | no |  | Strip the tv() classes of this component (trigger/label/chevron/content), of the Collapsible it renders and of the markdown body; the collapse mechanics stay. |
| urlPolicy | `MarkdownUrlPolicy` | no |  | URL policy passed through to the inner StreamingMarkdown for any links in the reasoning text (same strict default — untrusted model output). |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> (omit-pattern)

### Types
```ts
type ChatReasoningPart = Extract<ChatMessagePart, { type: 'reasoning' }>
```

```ts
interface MarkdownUrlPolicy {
/**
   * Allowed link protocols (with trailing colon). Relative URLs are always
   * allowed for links. @default ['http:', 'https:', 'mailto:', 'tel:']
   */
  allowedLinkProtocols?: string[];
  /**
   * Prefix allowlist for image sources, matched against the normalized
   * absolute URL. Empty (the default) blocks every external image; relative
   * sources are allowed. Prefer deep, specific prefixes — broad ones are
   * open-redirect bait. `data:` images are blocked unless a `data:` prefix
   * is listed explicitly.
   * @default []
   */
  allowedImagePrefixes?: string[];
  /** Observability hook — fires once per blocked URL occurrence. */
  onBlocked?: (kind: 'link' | 'image', url: string) => void;
}
```

```ts
type ChatMessagePart = | { type: 'text'; text: string }
  /** Model reasoning. Collapsed, tertiary presentation; `durationMs` feeds the "Thought for Xs" label. */
  | { type: 'reasoning'; text: string; durationMs?: number }
  /** A tool invocation with its lifecycle state. Rendered as a ToolCallCard by default; override via `partRenderers`. */
  | {
      type: 'tool-call';
      id: string;
      name: string;
      state: 'pending' | 'running' | 'complete' | 'error';
      input?: unknown;
      output?: unknown;
      errorMessage?: string;
    }
  /** A cited source. Same shape as CitationSource — also feeds StreamingMarkdown's `sources` for `[id]` markers. */
  | ({ type: 'source' } & CitationSource)
  /**
   * A file attached to the message. `url` is only ever rendered as a
   * policy-checked download link (never as an inline image/iframe) — LLM- or
   * server-supplied URLs are untrusted input.
   */
  | { type: 'attachment'; name: string; mimeType: string; size?: number; url?: string }
  /** Declarative A2UI payload (P4). Validated fail-loud by A2UIView; ignored by default renderers until then. */
  | { type: 'a2ui'; payload: unknown }
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
interface CitationSource {
/** Stable id — matches the `[id]` marker in the streamed markdown. */
  id: string;
  /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
  title: string;
  /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
  url?: string;
  /** Short excerpt shown under the title, clamped to ~3 lines. */
  snippet?: string;
}
```

### Slots (slotClasses keys)
`trigger`, `label`, `chevron`, `content`

---

## RegisterPage
Pre-built registration page with invitation-gated signup, password requirements checklist, and confirm field.
Sends POST to `apiPath` (default `/api/auth/register`). Pair with `createRegisterHandler(authDeps)` on the server.

**Import:** `import { RegisterPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<RegisterPage
  {t}
  token={page.url.searchParams.get('token') ?? ''}
  defaultEmail={page.url.searchParams.get('email') ?? ''}
  onSuccess={() => goto('/')}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| token | `string` | yes |  | The invitation token from the `?token=` query param. **Required to register**: possession of it is the entire proof of invitation, so without it the request is rejected before anything is looked up.  Read it in your route the same way as `defaultEmail`: `token={page.url.searchParams.get('token') ?? ''}`.  It is a credential: keep it out of logs and analytics, and do not put it in a page title or a shared screenshot.  Required rather than optional-with-a-default on purpose: a page rendered without it can only ever produce a 400, and an optional prop makes that mistake type-check. This way the compiler names every call site. |
| apiPath | `string` | no | '/api/auth/register' | API endpoint for the register request. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names, needed only when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| defaultEmail | `string` | no | '' | Pre-fills the email field. Pass the `?email=` query param from the invitation link (`createInvitationHandlers` builds `/auth/register?token=<secret>&email=<invitee>`) so an invited user lands on a ready-to-submit form instead of retyping. Following the same explicit-prop pattern as `ResetPasswordPage`/`VerifyEmailPage`'s `token`, read it from the page in your route (SSR-safe), e.g. `defaultEmail={page.url.searchParams.get('email') ?? ''}`.  Convenience only — the invitation names its own address, and registering with a different one is refused. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| footer | `Snippet` | no |  | Content rendered below the form, above links (e.g. terms checkbox). |
| header | `Snippet` | no |  | Content rendered above the form (e.g. social login buttons). |
| links | `Snippet` | no |  | Replaces the link area. |
| loginUrl | `string` | no | '/auth/login' | URL for the login page link. |
| onSuccess | `() => void` | no |  | Called after successful registration. |
| passwordPolicy | `PasswordPolicy` | no |  | The password policy to gate against, when you already have it server-side (`resolvePasswordPolicy(config.password)` in a `+page.server.ts` load). Supplying it skips the `policyPath` request — useful for SSR, and the only way to gate correctly when the endpoint is not mounted. |
| policyPath | `string | null` | no | '/api/auth/password-policy' | Endpoint serving `createPasswordPolicyHandler`, read once on mount so the checklist and the submit gate match what the server enforces. `null` disables the request and falls back to the package defaults (min 8, no character classes). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ RegisterPage: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| showRequirements | `boolean` | no | true | Show real-time password requirements checklist. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface PasswordPolicy {
/** Minimum length. @default 8 */
  minLength: number;
  /** Require at least one `A-Z`. @default false */
  requireUppercase: boolean;
  /** Require at least one `a-z`. @default false */
  requireLowercase: boolean;
  /** Require at least one `0-9`. @default false */
  requireDigit: boolean;
  /** Require at least one character outside `A-Za-z0-9`. @default false */
  requireSpecial: boolean;
}
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
interface AuthPageSlotClasses {
/** Outermost wrapper element. */
  root?: string;
  /** Card container around the form. */
  card?: string;
  /** Page heading (h1). */
  title?: string;
  /** Form element wrapping all fields. */
  form?: string;
  /** Individual form field (Input). */
  field?: string;
  /** Submit button. */
  submit?: string;
  /** Error alert container. */
  error?: string;
  /** Success message container. */
  success?: string;
  /** Links area below the form (e.g. "Forgot password?"). */
  links?: string;
  /** Password requirements checklist (RegisterPage, ResetPasswordPage). */
  requirements?: string;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

---

## ResetPasswordPage
Pre-built reset-password page with password confirmation.
Sends POST to `apiPath` (default `/api/auth/reset-password`). Pair with `createResetPasswordHandler(authDeps)` on the server.

**Import:** `import { ResetPasswordPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<script>
  import { page } from '$app/state';
</script>
<ResetPasswordPage {t} token={page.url.searchParams.get('token') ?? ''} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| token | `string` | yes |  | Reset token from URL query parameter. |
| apiPath | `string` | no | '/api/auth/reset-password' | API endpoint for the reset request. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| footer | `Snippet` | no |  | Content rendered below the form, above links. |
| header | `Snippet` | no |  | Content rendered between the heading and the form. |
| links | `Snippet` | no |  | Replaces the link area below the form. |
| loginUrl | `string` | no | '/auth/login' | URL for the login page link. |
| passwordPolicy | `PasswordPolicy` | no |  | The password policy to gate against, when you already have it server-side (`resolvePasswordPolicy(config.password)` in a `+page.server.ts` load). Supplying it skips the `policyPath` request. |
| policyPath | `string | null` | no | '/api/auth/password-policy' | Endpoint serving `createPasswordPolicyHandler`, read once on mount so the checklist and the submit gate match what the server enforces. `null` disables the request and falls back to the package defaults (min 8, no character classes). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ResetPasswordPage: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| showRequirements | `boolean` | no | true | Show the real-time password requirements checklist. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `requirements`, `submit`, `error`, `success`, `links`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface PasswordPolicy {
/** Minimum length. @default 8 */
  minLength: number;
  /** Require at least one `A-Z`. @default false */
  requireUppercase: boolean;
  /** Require at least one `a-z`. @default false */
  requireLowercase: boolean;
  /** Require at least one `0-9`. @default false */
  requireDigit: boolean;
  /** Require at least one character outside `A-Za-z0-9`. @default false */
  requireSpecial: boolean;
}
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
interface AuthPageSlotClasses {
/** Outermost wrapper element. */
  root?: string;
  /** Card container around the form. */
  card?: string;
  /** Page heading (h1). */
  title?: string;
  /** Form element wrapping all fields. */
  form?: string;
  /** Individual form field (Input). */
  field?: string;
  /** Submit button. */
  submit?: string;
  /** Error alert container. */
  error?: string;
  /** Success message container. */
  success?: string;
  /** Links area below the form (e.g. "Forgot password?"). */
  links?: string;
  /** Password requirements checklist (RegisterPage, ResetPasswordPage). */
  requirements?: string;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

---

## ResourceTimeline
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Resource timeline: every row is a resource (a room, a chair, a
vehicle, a person), every column a day of a navigable window, and each item
a bar spanning the days it occupies, stacked when two overlap in one lane.
The occupancy view neither `Calendar` (timed events on a date grid) nor
`Planner` (one item, one day bucket) expresses.

Three contracts decide whether your data lands where you expect:

- **`getRange` is inclusive.** `{ start, end }` are both days the bar covers.
A booking stored as check-in → check-out converts by subtracting a day:
the last *night* is `checkOut − 1`. Same convention as `CalendarEvent.end`.
- **Local date strings are taken verbatim** — `'2026-06-16'` is never
UTC-parsed, so a plain date never shifts a day west of Greenwich (the same
parser `Planner.getDate` uses). Pass a `Date` when you need an instant
converted to its local day.
- **The window is `value` + `view`.** `view="week"` snaps to the week
containing `value`; `view="days"` runs `days` columns **starting at**
`value`, so "the next 14 nights" needs no second anchor.

Two departures from `Calendar`/`Planner`, both forced by the sticky resource
column: **navigation does not slide-animate** (a `transform` ancestor breaks
`position: sticky`, so there is no `animated` prop), and **there is no
swipe-to-navigate** (the day track already claims the horizontal gesture, the
one that scrolls it). Arrow keys and the header arrows do the navigating;
`overflow-x` sits on the track, never on the root, so a wide window never
scrolls the page sideways.

Scale is honest rather than engineered: roughly 20 lanes × 30 days is
comfortable, and there is no virtualization in this version. Sort a longer
list into `groups` and page the window instead.

**Import:** `import { ResourceTimeline } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script lang="ts">
import { ResourceTimeline } from '@urbicon-ui/blocks';
// `isoToDate` first: `checkOut` is a local date string, and handing it
// straight to `addDays` would UTC-parse it and shift the bar a day.
import { addDays, isoToDate } from '@urbicon-ui/blocks/date';
</script>

<ResourceTimeline
view="days"
days={14}
resources={rooms}
items={bookings}
getResourceId={(b) => b.roomId}
getRange={(b) => ({ start: b.checkIn, end: addDays(isoToDate(b.checkOut), -1) })}
getLabel={(b) => b.guest}
onItemClick={(booking, room) => openBooking(booking, room)}
/>
```

```svelte
<ResourceTimeline
resources={chairs}
items={sessions}
categories={[{ id: 'cut', label: 'Cut', color: 'oklch(0.7 0.12 250)' }]}
getResourceId={(s) => s.chairId}
getCategoryId={(s) => s.serviceId}
getRange={(s) => ({ start: s.day, end: s.day })}
>
{#snippet span({ item, totalDays })}
<span class="truncate">{item.client} · {totalDays}d</span>
{/snippet}
</ResourceTimeline>
```

### Variants
- variant: bordered, default, ghost (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| getRange | `(item: T) => TimelineRange` | yes |  | The item's **inclusive** day range: both `start` and `end` are days the bar covers. A stay ending at check-out passes `checkOut − 1`. Return `Date`s, or local date strings (`'2026-06-16'`) which are read verbatim and never UTC-parsed. A range whose end precedes its start is rendered with the two swapped and warns in DEV. Required. |
| getResourceId | `(item: T) => string` | yes |  | Which lane an item belongs to. An id that is in no `resources` entry drops the item (DEV warns). Required. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...ResourceTimelineVariants | `VariantProps` | no |  | Styling variants from ResourceTimelineVariants |
| categories | `DateCategory[]` | no |  | Colour buckets for the bars, and the legend below the grid. |
| cell | `Snippet<[TimelineCellContext]>` | no |  | Render extra content inside every (resource, day) cell, e.g. an "add" affordance on free days. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| dayHeader | `Snippet<[TimelineDayContext]>` | no |  | Customise a day column's header. |
| days | `number` | no | 14 | Column count for `view="days"`. Ignored in `week`. |
| disabled | `boolean` | no | false | Disable navigation and cell activation. |
| empty | `Snippet` | no |  | Replace the "no resources" message shown when `resources` is empty. |
| getCategoryId | `(item: T) => string | undefined` | no |  | The item's category id, looked up in `categories`. Falls back to `resource.categoryId`. |
| getId | `(item: T) => string` | no |  | Stable key for an item, used as the `{#each}` key. Defaults to resource id + start day + index. |
| getLabel | `(item: T) => string` | no |  | The bar's text and accessible name. Without it a bar renders as a plain occupancy block. |
| groupLabel | `Snippet<[TimelineGroupContext]>` | no |  | Customise a group heading row. |
| groups | `TimelineGroup[]` | no |  | Heading rows above the lanes carrying the matching `groupId`. Supplying them re-orders the lanes to follow this list; a lane whose `groupId` names no group is appended without a heading rather than dropped. |
| header | `Snippet<[TimelineHeaderContext]>` | no |  | Replace the default toolbar (prev/title/today/next). |
| highlightToday | `boolean` | no | true | Tint today's column. Visual only — `aria-current="date"` is set on today's header and cells either way, so switching the highlight off never costs the semantic pointer. |
| highlightWeekend | `boolean` | no | false | Tint Saturday/Sunday columns. |
| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate for days that cannot be activated, on top of `minDate`/`maxDate`. |
| items | `T[]` | no |  | The items to lay out as bars. |
| legend | `Snippet<[TimelineLegendContext]>` | no |  | Replace the default category legend. |
| locale | `string` | no | 'auto' | BCP 47 locale tag for the weekday names and the header title. Defaults to `'auto'`, which follows the active `<I18nProvider>` locale, so an app that already declares its language does not repeat it here. SSR-safe: the locale comes from context, so server and client resolve the same tag. Pass an explicit tag (e.g. `'de-DE'`) to override. |
| maxDate | `Date` | no |  | Latest navigable date. The window clamps span-preserving, so it never collapses at the bound. |
| maxRowsPerLane | `number` | no |  | Bar rows to render per lane; anything past it becomes a `+n` chip at the lane's right edge. Unset renders every row. |
| minDate | `Date` | no |  | Earliest navigable date. The window clamps span-preserving, so it never collapses at the bound. |
| onCellClick | `(resource: TimelineResource, date: Date) => void` | no |  | Fires when a cell **no bar covers** is activated: the hook for an "add booking" affordance. Activating a day inside an existing stay fires `onItemClick` instead, from click or keyboard. |
| onItemClick | `(item: T, resource: TimelineResource) => void` | no |  | Fires when a bar is activated: a click on it, or Enter/Space on **any** cell it covers (the bar overhangs those cells, so the keyboard reaches what the pointer hits). Where several bars stack on one day, activating again steps through them, top row first, then wraps. |
| onNavigate | `(date: Date, range: DateRange) => void` | no |  | Fires after navigation with the new reference date and the visible window; load data here. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ResourceTimeline: {...} }}>`. |
| resourceLabel | `Snippet<[TimelineResourceContext]>` | no |  | Customise a lane's label in the resource column. |
| resources | `TimelineResource[]` | no |  | The lanes, top to bottom. An empty list renders the `empty` state. |
| showLegend | `boolean` | no | true | Render the category legend below the grid. Ignored without `categories`. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Density: lane width, day-column width and bar height. |
| slotClasses | `Partial<Record<ResourceTimelineSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: base | header | headerTitle | nav | navButton | track | dayHeaderRow | corner | dayHeader | dayHeaderWeekday | dayHeaderDate | body | groupRow | groupLabel | lane | laneHeader | laneLabel | laneDescription | dayCell | span | spanLabel | overflow | legend | legendItem | legendDot | legendLabel | empty. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| span | `Snippet<[TimelineSpanContext<T>]>` | no |  | Render a bar's content: receives the clipped geometry and the typed item. |
| stickyResourceColumn | `boolean` | no | true | Keep the resource column pinned while the day track scrolls sideways. Turn it off inside a shell that already provides its own horizontal scrolling. |
| unstyled | `boolean` | no | false | Remove all default tv() classes; only user-provided classes apply, and the header's today-button tooltip goes bare with them. Note that this also strips the layout's custom properties (`--rt-lane-w`, `--rt-day-w`, `--rt-bar-h` …), so an unstyled timeline has to re-declare them along with the look. |
| value | `Date` | no | today | Reference date the window is anchored on. Supports `bind:value`. |
| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style: `default`, `bordered` (a framed grid) or `ghost` (no grid lines, pill bars). |
| view | `ResourceTimelineView` | no | 'week' | `week` snaps to the week containing `value`; `days` starts at `value`. |
| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week for `view="week"` (0=Sun … 6=Sat). |

Inherited from:
- ResourceTimelineVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface DateCategory {
/** Stable id — what an item's category accessor returns. */
  id: string;
  /** Display label, shown in the legend. */
  label: string;
  /** CSS colour value for the dot, bar or border. */
  color: string;
}
```

```ts
interface DateRange {
start: Date;
  end: Date;
}
```

```ts
type ResourceTimelineView = 'week' | 'days'
```

```ts
interface TimelineCellContext {
/** The lane's resource. */
  resource: TimelineResource;
  /** The cell's date (local midnight). */
  date: Date;
  /** `YYYY-MM-DD` local key for this date. */
  isoDate: string;
  /** Whether this cell's day is today. */
  isToday: boolean;
  /** Whether this cell's day is a Saturday or Sunday. */
  isWeekend: boolean;
  /** Whether this cell cannot be activated (date bounds, predicate, `resource.disabled`, or the whole grid). */
  isDisabled: boolean;
  /** Whether any span covers this cell. */
  isOccupied: boolean;
}
```

```ts
interface TimelineDayContext {
/** The column's date (local midnight). */
  date: Date;
  /** `YYYY-MM-DD` local key for this date. */
  isoDate: string;
  /** 0-based column index inside the window. */
  index: number;
  /** Whether this column is today. */
  isToday: boolean;
  /** Whether this column is a Saturday or Sunday. */
  isWeekend: boolean;
  /** Whether the whole column is blocked by `minDate`/`maxDate`/`isDateDisabled`/`disabled`. */
  isDisabled: boolean;
  /** Localized short weekday name (e.g. "Mo"). */
  weekday: string;
  /** ISO 8601 week number of this date. */
  weekNumber: number;
}
```

```ts
interface TimelineGroup {
id: string;
  label: string;
}
```

```ts
interface TimelineGroupContext {
group: TimelineGroup;
  resources: TimelineResource[];
}
```

```ts
interface TimelineHeaderContext {
/** Localized title for the current window. */
  title: string;
  /** First day of the window. */
  rangeStart: Date;
  /** Last day of the window (inclusive). */
  rangeEnd: Date;
  /** ISO week number of the reference date. */
  weekNumber: number;
  /** The active window mode. */
  view: ResourceTimelineView;
  /** Step the window by `delta` (− back, + forward). */
  navigate: (delta: number) => void;
  /** Jump to the window containing today. */
  goToToday: () => void;
  /** Jump to the window containing `date`. */
  goTo: (date: Date) => void;
  /** Whether back-navigation is within bounds. */
  canGoBack: boolean;
  /** Whether forward-navigation is within bounds. */
  canGoForward: boolean;
  /** Whether today is within `[minDate, maxDate]`; gate a custom Today control on it. */
  canGoToToday: boolean;
}
```

```ts
interface TimelineLegendContext {
categories: DateCategory[];
}
```

```ts
interface TimelineRange {
start: Date | string;
  end: Date | string;
}
```

```ts
interface TimelineResource {
/** Stable identity; what `getResourceId` has to return. */
  id: string;
  /** Lane label, rendered in the sticky resource column. */
  label: string;
  /** Secondary line under the label (room type, floor, capacity). */
  description?: string;
  /** Id of the {@link TimelineGroup} this lane belongs to (a house, a department). */
  groupId?: string;
  /** Fallback category for every span in this lane; a span-level id wins. */
  categoryId?: string;
  /** Mark the whole lane unavailable — its cells report `aria-disabled` and do not activate. */
  disabled?: boolean;
  /** Free-form payload the consumer's snippets can read back. */
  meta?: Record<string, unknown>;
}
```

```ts
interface TimelineResourceContext {
resource: TimelineResource;
}
```

```ts
interface TimelineSpanContext {
/** The consumer's item, with its real `T` type (no cast through an event shape). */
  item: T;
  /** Stable key for this span (`getId`, else the resource id + start day). */
  id: string;
  /** The lane the span sits on. */
  resource: TimelineResource;
  /** The resolved category, if `categories` and a category id matched. */
  category?: DateCategory;
  /** First day of the span (local midnight), **unclipped** — may precede the window. */
  start: Date;
  /** Last day of the span (local midnight), inclusive and **unclipped**. */
  end: Date;
  /** 0-based column of the span's first **visible** day. */
  startCol: number;
  /** Number of visible columns — the span clipped to the window. */
  spanCols: number;
  /** `false` when the bar is cut off at the left window edge. */
  isStart: boolean;
  /** `false` when the bar is cut off at the right window edge. */
  isEnd: boolean;
  /** 0-based stack row inside the lane. */
  row: number;
  /** Total days of the unclipped span (≥ 1). */
  totalDays: number;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`base`, `track`, `dayHeaderRow`, `corner`, `dayHeader`, `dayHeaderWeekday`, `dayHeaderDate`, `body`, `groupRow`, `groupLabel`, `lane`, `laneHeader`, `laneLabel`, `laneDescription`, `dayCell`, `span`, `spanLabel`, `overflow`, `legend`, `legendItem`, `legendDot`, `legendLabel`, `empty`

---

## Sankey
Flow diagram (Sankey) for visualizing multi-stage data or value
pipelines. Nodes are split into layers; paths are rendered as cubic Bezier
curves with value-proportional width. The layout algorithm is embedded (no
d3-sankey dependency, ISC license attributed).

Hovering/focusing a node or path highlights the connected paths and
neighboring nodes. A ResizeObserver adapts the width responsively. An
sr-only table provides a screen-reader fallback with source/target/value.

**Import:** `import { Sankey } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Sankey
  nodes={[
    { id: 'gas',  label: 'Gas',     intent: 'primary' },
    { id: 'pot',  label: 'Pool',    intent: 'neutral' },
    { id: 'heat', label: 'Heating', intent: 'success' }
  ]}
  links={[
    { source: 'gas', target: 'pot',  value: 220609 },
    { source: 'pot', target: 'heat', value: 220609 }
  ]}
  formatValue={(v) => formatCurrency(v)}
  height={400}
/>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| links | `SankeyLink[]` | yes |  | Link list. |
| nodes | `SankeyNode[]` | yes |  | Node list. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...SankeyVariants | `VariantProps` | no |  | Styling variants from SankeyVariants |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| defaultOpacity | `number` | no | 0.45 | Default stroke opacity of paths without hover. |
| dimmedOpacity | `number` | no | 0.25 | Hover opacity of the non-focused paths. |
| formatPercent | `(percent: number) => string` | no |  | Format function for percentages (tooltip). |
| formatValue | `(value: number) => string` | no |  | Format function for values (tooltip + sr-only table). |
| height | `number | 'auto'` | no | 400 | Height of the diagram. Accepts a fixed pixel number or `'auto'`.  `'auto'` scales with the node count: roughly `nodes.length × (12 + nodePadding)`, clamped to `[280, 800]`. Useful when the number of nodes varies at runtime and a fixed pixel value would be too small or too large. |
| highlightedOpacity | `number` | no | 0.7 | Stroke opacity of the highlighted paths. |
| highlightOnHover | `boolean` | no | true | Hover highlight (paths + connected nodes). |
| intent | `SankeyIntent` | no | 'neutral' | Default intent for nodes without their own `intent`. |
| iterations | `number` | no | 6 | Number of relaxation iterations in the layout. |
| linkContent | `Snippet<[link: SankeyLaidOutLinkWithMeta]>` | no |  | Custom snippet for path rendering (instead of the default cubic Bezier). |
| nodeAlign | `'left' | 'right' | 'center' | 'justify'` | no | 'justify' | Where nodes go that the layering leaves short of the last layer.  Layers come from the **longest** path to a node, so this moves only two kinds: `right` and `justify` push sinks (no outgoing links) to the last layer, `center` puts fully isolated nodes (no links at all) in the middle, `left` moves nothing. On an evenly layered graph — every source-to-sink path the same length — all four values render identically.  Not d3-sankey's `nodeAlign`, which positions every node. |
| nodeContent | `Snippet<[node: SankeyLaidOutNodeWithMeta]>` | no |  | Custom snippet for node content (inside the SVG, instead of the label). |
| nodePadding | `number` | no | 16 | Vertical gap between nodes within a layer. |
| nodeWidth | `number` | no | 24 | Pixel width of a node. |
| onLinkClick | `(link: SankeyLaidOutLinkWithMeta) => void` | no |  | Click callback for a path. |
| onNodeClick | `(node: SankeyLaidOutNodeWithMeta) => void` | no |  | Click callback for a node. |
| preset | `string` | no |  | Preset name. |
| showValues | `boolean` | no | false | Persistently display values next to node labels (instead of only in the hover tooltip). Useful for print, PDF attachments, static screenshots, or tenant- and client-facing statements where hovering is not possible. Uses `formatValue` for formatting. |
| slotClasses | `Partial<Record<SankeySlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tooltip | `Snippet<[datum: SankeyLaidOutNodeWithMeta | SankeyLaidOutLinkWithMeta, kind: 'node' | 'link']>` | no |  | Custom tooltip content for node or path. |
| unstyled | `boolean` | no |  | Remove default classes. |
| width | `number` | no |  | Optional fixed width. Default: derived from the container via ResizeObserver. Set a value only if you need SSR-stable layouts and are willing to give up responsiveness. |

Inherited from:
- Omit<SankeyVariants, never> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type SankeyIntent = 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral'
```

```ts
interface SankeyNode {
/** Unique ID — referenced by `links.source`/`links.target`. */
  id: string;
  /** Display label rendered at the node. */
  label: string;
  /** Overrides the default intent from the component palette. */
  intent?: SankeyIntent;
  /** Arbitrary metadata for tooltip/snippets. */
  meta?: Record<string, unknown>;
}
```

```ts
interface SankeyLink {
/** ID of the source node (must exist in nodes). */
  source: string;
  /** ID of the target node. */
  target: string;
  /** Numeric value — determines the path width. */
  value: number;
  /** Overrides the default intent (default: intent of the source node). */
  intent?: SankeyIntent;
  /** Arbitrary metadata. */
  meta?: Record<string, unknown>;
}
```

```ts
type SankeyLaidOutNodeWithMeta = SankeyLaidOutNode & {
  meta?: Record<string, unknown>;
}
```

```ts
type SankeyLaidOutLinkWithMeta = SankeyLaidOutLink & {
  meta?: Record<string, unknown>;
}
```

```ts
interface SankeyLaidOutLink {
source: SankeyLaidOutNode;
  target: SankeyLaidOutNode;
  value: number;
  meta?: TLinkMeta;
  /** Y coordinate at the source node (midpoint of the link height). */
  y0: number;
  /** Y coordinate at the target node. */
  y1: number;
  /** Pixel width of the link (proportional to value). */
  width: number;
  /** Index (for stable ordering / iteration). */
  index: number;
}
```

```ts
interface SankeyLaidOutNode {
id: string;
  meta?: TNodeMeta;
  /** Layer index (0 = leftmost). */
  layer: number;
  /** Left pixel coordinate (X0). */
  x0: number;
  /** Right pixel coordinate (X1 = X0 + nodeWidth). */
  x1: number;
  /** Top pixel coordinate. */
  y0: number;
  /** Bottom pixel coordinate. */
  y1: number;
  /** Effective node value (max(Σ incoming, Σ outgoing)). */
  value: number;
  sourceLinks: SankeyLaidOutLink[];
  targetLinks: SankeyLaidOutLink[];
}
```

### Slots (slotClasses keys)
`wrapper`, `svg`, `node`, `nodeRect`, `nodeLabel`, `nodeValue`, `link`, `tooltip`, `tooltipLabel`, `tooltipDetail`

---

## Scroller
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Horizontal row of equal-rank items that becomes scrollable only
when it runs out of room — an overflow behaviour, not a navigation pattern.
On a wide viewport it is an ordinary row: no scrolling, no arrows, no dots,
and none of the accessibility duties a scroll container carries. Once it does
overflow it snaps to item boundaries, takes a tab stop (`role="group"` +
`label`, so the keyboard can scroll it at all — the bug in most media rows),
and can show jump buttons and dots. `align="center"` turns it into a centred
stage whose middle item lifts via `animation-timeline: view(inline)` — pure
CSS, and where that is unsupported the row is identical minus the lift. Use it
for feature cards, product rows, media strips and chip/filter bars. It never
auto-rotates. For one item at a time with paging semantics use Tab; for
page-number navigation use Pagination.

**Import:** `import { Scroller } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Scroller label="Main features" itemBasis="18rem">
  {#each features as feature (feature.id)}
    <FeatureCard {...feature} />
  {/each}
</Scroller>
```

```svelte
<!-- Centred stage: three visible, two peeking. Card width is chosen so the
     row always overflows — that is what gives it a middle to centre. -->
<Scroller
  label="Main features"
  itemBasis="22rem"
  align="center"
  emphasis="strong"
  indicator="dots"
>
  {#each features as feature (feature.id)}
    <FeatureCard {...feature} />
  {/each}
</Scroller>
```

### Variants
- align: center, start (default: start)
- gap: lg, md, sm, xl, xs (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | The row's items. Each direct child becomes one snap target — width, snap alignment and (with `emphasis`) the lift are applied for you. Required. |
| label | `string` | yes |  | Accessible name for the row, e.g. "Main features". Required: once the row overflows it becomes a focusable `role="group"`, and an unnamed group is a nameless box to a screen reader. It is deliberately not optional-with-a- fallback — a generic default name would be worse than none. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...ScrollerVariants | `VariantProps` | no |  | Styling variants from ScrollerVariants |
| align | `'start' | 'center'` | no | 'start' | Where an item comes to rest when the row snaps. `start` is the ordinary overflow row. `center` is a stage: the middle item is the subject, and the track is padded so the first and last item can reach the middle too.  `center` needs items narrow enough that roughly three are visible with two peeking. Make them much wider and the centring padding takes over the row — one card adrift in empty space, which reads as a layout bug rather than a stage. The component warns about that in DEV. |
| class | `string` | no |  | Extra classes merged onto the root container (the column holding the row and its control bar). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| controls | `'auto' | 'always' | 'none'` | no | 'auto' | Previous/next buttons. `auto` shows them only while the row overflows — on a viewport where everything fits there is nothing to navigate, and controls for a problem that does not exist are just clutter. `always` keeps them mounted (disabled at the ends); `none` omits them. |
| emphasis | `'none' | 'subtle' | 'strong'` | no | 'none' | Lift the item in the middle of the scrollport — a scale plus an elevation step, driven by scroll position via CSS. `subtle` is a light touch, `strong` is visible across a room; past roughly `strong` a row wobbles while scrolling and pulls attention away from reading, which is why this is a scale and not a free number. Retune per instance with `--blocks-scroller-emphasis-scale` / `-shadow`.  **Requires `align="center"`** and is a no-op otherwise (with a DEV warning): the lift marks the item that has arrived in the middle, and a start-aligned row has no middle. Neighbours are never dimmed or blurred — the point is to mark the middle, not to hide the rest. Respects `prefers-reduced-motion`, and where `animation-timeline` is unsupported it simply does nothing. |
| gap | `'xs' | 'sm' | 'md' | 'lg' | 'xl'` | no | 'md' | Space between items. |
| indicator | `'none' | 'dots'` | no | 'none' | Position indicator. `dots` renders one button per **resting place** — every dot jumps to its own destination and the current one carries `aria-current`. On a centred row that is one dot per item. On a `start`-aligned row the trailing items that share the end of the scroll range share one dot, labelled with their range ("Items 4–5 of 5"): a row has only as many distinct resting places as it can scroll to, and a dot per item would light up elsewhere than the press. Leave it off for long chip bars, where a dot per position is noise either way. |
| itemBasis | `string` | no | '16rem' | Width of each item, as any CSS length (`'18rem'`, `'clamp(14rem,60vw,22rem)'`). This is what decides when the row overflows, so it is a prop rather than a class: with `align="center"` the component needs it to compute the edge padding. Override per-item layout via `slotClasses.viewport` if you need responsive widths. |
| nextLabel | `string` | no | 'Next' (localised) | Accessible label for the next button. |
| onActiveChange | `(index: number) => void` | no |  | Fires when the item at the snap anchor changes, with its zero-based index. Intentionally coarse — there is no per-frame scroll-position callback, because the CSS-native carousel primitives this component is meant to be swapped for one day could not honour one. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Scroller: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| previousLabel | `string` | no | 'Previous' (localised) | Accessible label for the previous button. |
| slotClasses | `Partial<Record<ScrollerSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: root (the column — what `class` also targets) | viewport (the scroll container; also where per-item rules like width live, via `[&>*]:…`) | controls (the bar under the row) | control (a previous/next button) | indicator (the dot group) | dot. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| snap | `'proximity' | 'mandatory' | 'none'` | no | 'proximity' — or 'mandatory' when align="center" | Snap strictness. `proximity` snaps when you release nearby and otherwise leaves scrolling alone; `mandatory` always lands on an item — right when one item at a time is the unit, but it can skip past content sitting between two snap points. `none` scrolls freely.  The default follows `align`, because the two alignments mean different things: a `start` row is a list you sweep across (`proximity`), a `center` row is a stage whose middle has to land on something (`mandatory`). |
| unstyled | `boolean` | no |  | Remove all default tv() classes; combine with `slotClasses` to rebuild the look. Note that this also strips the layout rules that make the row scroll and snap. |

Inherited from:
- Omit<ScrollerVariants, 'emphasis' | 'snap' | 'scrollbar'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Slots (slotClasses keys)
`root`, `viewport`, `controls`, `control`, `indicator`, `dot`

---

## Section
Content section with title/subtitle, badges, and semantic footer.

**Import:** `import { Section } from '@urbicon-ui/docs';`

### Examples
```svelte
<Section id="usage" title="Usage" subtitle="Quick start">
  <p>Install and import the component.</p>
</Section>
```

### Variants
- intent: default, hero, primary, secondary (default: default)
- size: lg, md, sm, xl (default: lg)
- centered: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| id | `string` | yes |  | Section ID for navigation anchors |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'title') |
| ...SectionVariantProps | `VariantProps` | no |  | Styling variants from SectionVariantProps |
| badges | `Array<{
    text: string;
    variant?: 'soft' | 'filled';
    intent?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
  }>` | no |  | Badge configuration |
| children | `Snippet` | no |  | Main content snippet |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| footerSnippet | `Snippet` | no |  | Optional footer snippet (renders a semantic <footer>) |
| headingLevel | `1 | 2 | 3 | 4 | 5 | 6` | no | 2 | Heading level for the section title, clamped to 1..6 |
| marker | `string | boolean` | no |  | Editorial marker before the title — a quieter monospace stamp.  Pass it bare (`<Section marker …>`) and the page numbers the section for you: sections that ask for a marker are counted in render order within the enclosing `DocsLayout`, so inserting one renumbers the rest by itself. A section nested inside another never claims a number, which is what keeps a `<TypesReference>` inside a playground stage unnumbered while the same component at page level is numbered.  A string still wins, for the rare page that numbers by hand. Prefer the bare form: the hand-written literals were wrong on four pages (a duplicate `04`, two skipped numbers, one page starting at `02`) and nothing reported it. |
| meta | `string` | no |  | Optional right-aligned monospace meta information in the title row (e.g. `"20 props"`, `"6 recipes"`). Renders as an editorial counter next to the title with `font-meta`, so the information stays visually subordinate to the section title. |
| slotClasses | `Partial<Record<SectionSlots, string>>` | no |  | Per-slot class overrides for internal elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| subtitle | `string` | no |  | Subtitle text (property) |
| subtitleSnippet | `Snippet` | no |  | Custom subtitle snippet (overrides subtitle prop) |
| title | `string` | no |  | Title text. Renders as the section heading — this is deliberately **not** the native `title` tooltip attribute, which is why it is omitted from the inherited `HTMLAttributes`. |
| titleHidden | `boolean` | no | false | Keep the header in the screen-reader layer only — the section still gets a real heading and a working `aria-labelledby`, it just does not draw one.  For sections whose purpose is obvious from what they contain but that carry no heading in the design. The component playgrounds are the case this exists for: the specimen sits directly under the page `h1` and a "Playground" heading above it would be redundant to a sighted reader — while without one the table of contents offered a "Playground" entry leading into an unnamed region, and heading navigation skipped the largest interactive element on the page (measured on 57 pages, 2026-08).  Do not reach for it to quiet a section that simply has no title yet: a hidden heading and a missing heading look the same in the markup and only one of them is a decision. |
| titleSnippet | `Snippet` | no |  | Custom title snippet (overrides title prop) |
| unstyled | `boolean` | no |  | Strip all default styles; combine with `slotClasses` to rebuild from scratch. |
| intent | `'default' | 'hero' | 'primary' | 'secondary'` | no | default | Controls the color theme and semantic meaning of the Section. Affects the overall appearance and user perception. Available options: default, hero, primary, secondary. |
| size | `'lg' | 'md' | 'sm' | 'xl'` | no | lg | Controls the dimensions, padding, and text size of the Section. Affects the component's physical footprint. Available options: lg, md, sm, xl. |
| centered | `'false' | 'true'` | no | false | Controls the centered behavior and appearance of the Section component. Available options: false, true. |

Inherited from:
- SectionVariantProps (external)
- Omit<HTMLAttributes<HTMLElement>, 'children' | 'title'> (omit-pattern)

### Slots (slotClasses keys)
`root`, `header`, `headerRow`, `marker`, `title`, `meta`, `badges`, `subtitle`, `body`, `footer`

---

## SegmentGroup
Segment control with an animated sliding indicator for single selection; collapses to a vertical radio-style stack when its row can't fit the available width.
Compact mode/view switcher with smooth animation.

**Import:** `import { SegmentGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<SegmentGroup bind:value={view}>
  <SegmentItem value="list">List</SegmentItem>
  <SegmentItem value="grid">Grid</SegmentItem>
  <SegmentItem value="board">Board</SegmentItem>
</SegmentGroup>
```

### Variants
- variant: default, text (default: default)
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- fullWidth: true (default: false)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...SegmentGroupVariants | `VariantProps` | no |  | Styling variants from SegmentGroupVariants |
| ariaLabel | `string` | no |  | Accessible label for the segment group. |
| children | `Snippet` | no |  | Segment items to render. Must be SegmentItem components. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| collapseOnOverflow | `boolean` | no | true | When the segments can't fit their available width, collapse the horizontal track to a vertical radio-style stack (all options stay visible) instead of overflowing. Triggered by real measured overflow (ResizeObserver), not a viewport breakpoint, so it only engages when an instance genuinely doesn't fit — a 2-segment switcher that fits stays horizontal. Set `false` to keep the track horizontal (it still won't push the page wider than its parent). |
| disabled | `boolean` | no | false | Prevent interaction and dim the control. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to each segment item (per-item via context). Only applies while the item is not disabled. Accepts a preset name, an array of names, or configured mint objects. |
| onValueChange | `(value: string) => void` | no |  | Fires after the selected value changes. Receives the new value. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ SegmentGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<Exclude<SegmentGroupSlots, 'item'>, string>>` | no |  | Per-slot class overrides merged with tv() styles.  `item` is deliberately absent: the group renders only the track and the indicator, so an `item` entry here would type-check and then do nothing. It belongs on each `SegmentItem`, which owns that slot. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| value | `string` | no |  | Currently selected value. Supports `bind:value` for two-way binding. |
| variant | `'default' | 'text'` | no | default | Controls the visual style and presentation of the SegmentGroup. Determines the component's visual treatment. Available options: default, text. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the SegmentGroup. Affects the component's physical footprint. Available options: lg, md, sm. |
| fullWidth | `'true'` | no | false | Controls the fullWidth behavior and appearance of the SegmentGroup component. Available options: true. |
| tier | `'commit' | 'modify'` | no | commit | Selects the semantic radius tier of the SegmentGroup — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

Inherited from:
- SegmentGroupVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface RegisteredSegment {
element: HTMLElement;
  isDisabled: () => boolean;
}
```

```ts
interface SegmentGroupContext {
registerItem: (value: string, element: HTMLElement, isDisabled: () => boolean) => () => void;
  selectItem: (value: string) => void;
  isActive: (value: string) => boolean;
  isTabStop: (value: string) => boolean;
  readonly size: NonNullable<SegmentGroupVariants['size']>;
  readonly variant: NonNullable<SegmentGroupVariants['variant']>;
  readonly tier: InteractiveTier;
  readonly disabled: boolean;
  readonly unstyled: boolean;
  readonly mint: MintProp;
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `indicator`, `item`

---

## Select
Discriminated union over `multiple`. Consumers pick a single shape at the
call site and the value type narrows accordingly — `<Select multiple bind:value>`
binds to `T[]`, `<Select bind:value>` binds to `T | null`. See
`SelectSingleProps` / `SelectMultipleProps` for the per-mode details.

**Import:** `import { Select } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Select
  label="Country"
  options={[
    { label: 'Germany', value: 'de' },
    { label: 'France', value: 'fr' },
    { label: 'Spain', value: 'es' },
  ]}
  bind:value={country}
  placeholder="Choose a country"
/>
```

```svelte
<Select
  label="Tenant"
  options={tenants.map((t) => ({ label: t.name, value: t.id }))}
  bind:value={tenantId}
/>
```

```svelte
<Select
  label="Tags"
  options={tags}
  multiple
  selectionIndicator="checkbox"
  bind:value={selectedTags}
/>
```

```svelte
<Select {options} multiple bind:value bind:open>
  {#snippet customTrigger(selected, isOpen, clear)}
    <Button variant="ghost" size="sm">
      <ListFilterIcon />
      {#if selected.length > 0}
        <Badge size="xs">{selected.length}</Badge>
      {/if}
    </Button>
  {/snippet}
</Select>
```

```svelte
<Select
  label="Role"
  groups={[
    { label: 'Engineering', options: [
      { label: 'Frontend', value: 'fe' },
      { label: 'Backend', value: 'be' }
    ]},
    { label: 'Design', options: [
      { label: 'UX', value: 'ux' },
      { label: 'Visual', value: 'vis' }
    ]}
  ]}
  bind:value={role}
  required
  error={roleError}
/>
```

### Variants
- variant: bare, filled, ghost, outlined, underline (default: outlined)
- size: lg, md, sm, xl, xs (default: md)
- clearable: true (default: false)
- disabled: true (default: false)
- error: true (default: false)
- messageType: error, helper (default: helper)
- open: true (default: false)
- required: true (default: false)
- selected: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clearable | `boolean` | no | false | Show a clear button when a value is selected. |
| closeOnClickOutside | `boolean` | no |  | Whether the listbox closes on outside click. Default `true`. Set to `false` to pin the listbox open while the consumer manages dismissal explicitly. |
| closeOnEscape | `boolean` | no |  | Whether the listbox closes on Escape key. Default `true`. Set to `false` for inline contexts where Escape should be intercepted by an outer widget (e.g. a row editor that wants to revert on Escape). |
| closeOnSelect | `boolean` | no |  | Whether the listbox closes after a selection is made. Defaults to `true` in single-select and `false` in multi-select — the multi-select default lets users tick multiple options without re-opening, matching the established multi-select pattern. |
| customItem | `Snippet<[SelectOption<T>, boolean, () => void]>` | no |  | Replace the default per-option rendering. Receives the option, its selection state, and a `toggle` callback (call to select/deselect). The outer `<div role="option">` container is still owned by Select for ARIA correctness — the snippet renders the option's visible contents.  Positional args: `(option, isSelected, toggle)`. |
| customTrigger | `Snippet<[SelectOption<T>[], boolean, () => void]>` | no |  | Replace the entire trigger button (chevron, label, clear control) with a custom element. Receives the selected options, current open state, and a `clear` callback. Use this for icon-only triggers, badge-counter triggers, or any non-standard chrome — the Select still owns open/close + selection state via the returned callbacks.  Positional args: `(selected, open, clear)`. |
| customTriggerContent | `Snippet<[SelectOption<T>[]]>` | no |  | Replace only the trigger's text/label area (chevron and clear button stay intact). Receives the selected options. Useful for showing icons next to the label, badges with counts, or formatted multi-select summaries while keeping the standard outlined-Select chrome.  It receives the *selected* options, which is `[]` for a `null` value even where `nullOption` is set — the null option is a row, not a selection — so a custom trigger renders nothing exactly where the default one says "All strands"; render your own `nullOption` label for the empty case.  Positional args: `(selected)`. |
| disabled | `boolean` | no | false | disabled property |
| error | `string` | no |  | Error message below the select. Overrides `helper` and forces danger styling. |
| groups | `SelectGroup<T>[]` | no |  | Grouped options with section labels. Takes precedence over `options`. |
| helper | `string` | no |  | Helper text below the select. Hidden when `error` is set. |
| id | `string` | no |  | Explicit `id` for the component. Auto-generated if omitted.  The id lands on the component's wrapper, which is not a labelable element. The focusable trigger is derived from it as `` `${id}-trigger` `` — that is the id an external `<label for>` has to address, since a `for` pointing at the wrapper focuses nothing. |
| label | `string` | no |  | Label text displayed above the select, auto-linked via `id`. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the trigger — the default trigger button, or the wrapper around a `customTrigger`. Only applies while not disabled. |
| multiPlaceholder | `string | ((selected: SelectOption<T>[]) => string)` | no |  | Placeholder shown when one or more values are picked. Pass a string for a static label ("3 selected") or a function that receives the currently selected options and returns a custom string. When unset, the trigger lists the selected labels comma-separated. |
| multiple | `'false' | 'true'` | no |  | Single-select mode (the default). Omit or set to `false` explicitly. |
| name | `string` | no |  | Shared `name` for a hidden input for native form submission. |
| nullOption | `string | NullOptionConfig` | no |  | Render an explicit "no value" option as the first row of the listbox. Selecting it sets the bound value to `null`. When `value` is `null`, the trigger displays this label instead of the placeholder.  Pass a string to use it as the label, or a `NullOptionConfig` for more control. Ignored when `groups` is set — group structures own their option list. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the listbox. Use for analytics or side-effects on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the listbox. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the listbox opens or closes from user interaction (trigger click, keyboard, selection, Escape, Tab-out, outside click). Receives the new open state — use it e.g. to lazy-load options on first open. Not called when the consumer writes `bind:open` directly. |
| onValueChange | `(value: T | null) => void` | no |  | Fires after the selected value changes. Receives the new value or `null` on clear. |
| open | `boolean` | no | false | Controls whether the listbox is open. Supports `bind:open` for parents that need to coordinate open/close (e.g. attaching a custom trigger button outside the Select wrapper). |
| options | `SelectOption<T>[]` | no |  | Flat list of selectable options. |
| placeholder | `string` | no | 'Select...' | Text shown when no value is selected. Never shown in single mode alongside `nullOption`: `value` defaults to `null`, which is that option's own value, so the trigger names the null option from the start and the placeholder has no state left to describe. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Select: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no | false | Marks the field as mandatory: adds the asterisk to the label and sets `aria-required` on the trigger. When `name` is set (and the field is not disabled), an empty Select also blocks native form submission — the hidden form-bridge input is exempt from constraint validation, so an invisible required input participates in its place while nothing is selected. Focus then returns to the trigger, which means no native validation bubble; pass `error` to tell the reader what is wrong. |
| selectionIndicator | `'checkmark' | 'none'` | no |  | Selection indicator rendered next to each option. - `'checkmark'` — trailing check icon (default) - `'none'` — no indicator (typical when using `customItem`) |
| slotClasses | `Partial<Record<SelectSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | base | trigger | triggerText | placeholder | chevron | clear | listbox | option | optionLabel | optionHint | optionCheck | optionCheckbox | group | groupLabel | label | requiredMark | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| syncWidth | `boolean` | no | true | Whether the listbox matches the trigger's width. Set `false` for icon-only or compact triggers where the listbox should size to its content instead. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| usePortal | `boolean` | no | true | When true, the listbox is rendered into the browser top layer via the native `popover` API, so it cannot be clipped by `overflow: auto` ancestors. When false, the listbox stays in the regular DOM flow — useful inside other popovers/portals to avoid double-portaling. |
| value | `T[]` | no | [] | Currently selected values. Supports `bind:value`. |
| variant | `SelectVariants['variant']` | no | 'outlined' | Visual style. - `outlined` (default) — visible border, surface-base background - `filled` — surface-interactive fill, no border (compact toolbars) - `ghost` — transparent until hover/focus (dense menus, inline editors) - `underline` — bottom-line only, no border-box (editorial knob-strips,   docs playgrounds) - `bare` — no frame, no fill, no padding, no fixed height: an inline word   choice that keeps the listbox role. `size` keeps only the type step, and   focus is an outline in `--blocks-focus-ring-color` |
| size | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Select. Affects the component's physical footprint. Available options: lg, md, sm, and 2 more. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Select component. Available options: error, helper. |
| selected | `'true'` | no | false | Controls the selected behavior and appearance of the Select component. Available options: true. |
| tier | `'commit' | 'modify'` | no | modify | Selects the semantic radius tier of the Select — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

### Types
```ts
type SelectValue = string | number | boolean
```

```ts
interface SelectOption {
label: string;
  value: T;
  disabled?: boolean;
  /**
   * Trailing secondary text on the option row — a facet count ("24"), a unit,
   * a price. It is part of the option's text content, so the row's accessible
   * name reads "Noir 24" rather than dropping the number.
   *
   * A string, not a number: formatting and locale belong to the caller
   * (`String(count)`, or an `Intl.NumberFormat` result). Ignored while
   * `customItem` draws the row — that snippet owns the whole row.
   */
  hint?: string;
}
```

```ts
interface SelectGroup {
label: string;
  options: SelectOption<T>[];
}
```

```ts
interface NullOptionConfig {
/** Label shown both in the listbox row and the trigger when `value` is `null`. */
  label: string;
  /** Disables selection of the null option (rare, but allowed for symmetry). */
  disabled?: boolean;
}
```

```ts
type SelectProps = | SelectSingleProps<T>
  | SelectMultipleProps<T>
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`wrapper`, `base`, `trigger`, `triggerText`, `placeholder`, `chevron`, `clear`, `listbox`, `option`, `optionLabel`, `optionHint`, `optionCheck`, `optionCheckbox`, `group`, `groupLabel`, `label`, `requiredMark`, `message`

---

## Separator
Visual divider for separating content sections. Supports horizontal and
vertical orientations with proper ARIA semantics.

**Import:** `import { Separator } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Separator />
```

```svelte
<div class="flex items-center gap-4">
  <span>Item A</span>
  <Separator orientation="vertical" size="sm" />
  <span>Item B</span>
</div>
```

### Variants
- size: lg, md, sm (default: md)
- orientation: horizontal, vertical (default: horizontal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...SeparatorVariants | `VariantProps` | no |  | Styling variants from SeparatorVariants |
| class | `string` | no |  | Additional CSS class merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| decorative | `boolean` | no |  | When true, the separator is purely visual (role="none"); when false, it uses role="separator" with aria-orientation. |
| orientation | `'horizontal' | 'vertical'` | no |  | Horizontal renders a full-width line; vertical renders a full-height line (e.g. inside flex rows). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Separator: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `'sm' | 'md' | 'lg'` | no |  | Controls margin around the line — sm (0.5 rem), md (1 rem), lg (1.5 rem). |
| slotClasses | `Partial<Record<'base', string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with slotClasses to rebuild from scratch. |

Inherited from:
- SeparatorVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Slots (slotClasses keys)
`base`

---

## SessionManager
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Lists the user's active sessions (refresh-token families) with a
device label, last-active time and a "this device" badge, and lets them sign
out an individual session or all other devices. Requires refresh-token
rotation on the server (`config.refreshToken`); without it the list reports
itself unavailable. Pair with `createSessionsHandlers` — mount its `list`
(GET `apiPath`), `revoke` (POST `apiPath/revoke`) and `revokeOthers`
(POST `apiPath/revoke-others`) groups.

**Import:** `import { SessionManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<SessionManager apiPath="/api/auth/sessions" />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/auth/sessions' | API base path for the session endpoints. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ SessionManager: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| slotClasses | `Partial<Record<'root' | 'title' | 'error' | 'list' | 'item' | 'empty' | 'badge', string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`, `title`, `error`, `list`, `item`, `empty`, `badge`

---

## Sidebar
Sidebar primitive — fixed-position panel that is permanent on
desktop (≥1024px) and slides in as a backdropped overlay on mobile. Use
this directly for right-side detail panels or custom shells. For the
standard "permanent left rail + mobile hamburger" application chrome,
prefer the higher-level `<SidebarLayout>` component, which handles main
content offset and the mobile header for you.

The component exposes `--sidebar-width` and `--sidebar-effective-width`
(0px when collapsed) as CSS variables on its `<aside>` element. CSS
custom properties only inherit to descendants, so these variables are
available **inside** the sidebar's subtree but not on its siblings — that
is precisely why `<SidebarLayout>` exists for app-shell layouts.

**Import:** `import { Sidebar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
import { Sidebar, Button, CloseIcon, Badge } from '@urbicon-ui/blocks';
let detailOpen = $state(false);
</script>

<Button onclick={() => (detailOpen = true)}>Show details</Button>

<Sidebar bind:open={detailOpen} side="right" width="20rem">
{#snippet header()}
<div class="flex items-center justify-between py-3">
<span class="font-semibold">Item details</span>
<Button variant="ghost" size="xs" onclick={() => (detailOpen = false)}>
<CloseIcon class="h-4 w-4" />
</Button>
</div>
{/snippet}
<div class="space-y-3 p-4">
<dt class="text-text-tertiary text-xs">Status</dt>
<dd><Badge intent="success" size="sm">Active</Badge></dd>
</div>
</Sidebar>
```

```svelte
<Sidebar bind:open={sidebarOpen} mode="collapsible" width="16rem">
{#snippet header()}<span class="font-semibold">App</span>{/snippet}
<nav class="p-3"><!-- links --></nav>
</Sidebar>
```

### Variants
- mode: collapsible, responsive (default: responsive)
- side: left, right (default: left)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| children | `Snippet` | no |  | Main scrollable content of the sidebar. |
| class | `string` | no |  | Additional CSS classes applied to the sidebar panel. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| closeOnBackdropClick | `boolean` | no | true | Close the mobile overlay when clicking the backdrop. |
| closeOnEscape | `boolean` | no | true | Close the mobile overlay when pressing Escape. |
| footer | `Snippet` | no |  | Content rendered in the sidebar footer (below the scrollable area). |
| header | `Snippet` | no |  | Content rendered in the sidebar header (above the scrollable area). |
| mode | `SidebarVariants['mode']` | no | 'responsive' | Controls sidebar behavior across viewports. - `responsive` (default): permanently visible on desktop (≥1024px), slide-in overlay on mobile. - `collapsible`: toggleable via `open` at all viewports — width animation on desktop, overlay on mobile. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the open state changes (mobile overlay dismissed, or collapsible toggled). |
| open | `boolean` | no |  | Controls sidebar visibility. In `responsive` mode (default) this only affects the mobile overlay — on desktop the sidebar is always visible. In `collapsible` mode this controls visibility at all viewports. Supports bind:open.  While the panel is hidden it carries both `aria-hidden` and `inert`, so its children leave the accessibility tree AND the tab order together — they stay mounted, so one without the other would strand a keyboard user in an invisible region. `inert` also suppresses pointer events, applied the moment `open` flips rather than at the end of the transition. If focus was inside the panel, it returns to whatever held it when the panel opened. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Sidebar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| side | `SidebarVariants['side']` | no | 'left' | Which edge the sidebar attaches to. |
| slotClasses | `Partial<Record<SidebarSlots, string>>` | no |  | Per-slot class overrides merged with variant styles. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with slotClasses for custom appearance. |
| width | `string` | no | '16rem' | CSS width of the sidebar panel. Also exposed as `--sidebar-width` (constant) and `--sidebar-effective-width` (0px when collapsed) CSS variables on the `<aside>`. These inherit only inside the sidebar's own subtree — for the main content offset use `<SidebarLayout>`. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`backdrop`, `panel`, `header`, `content`, `footer`

---

## SidebarLayout
App-shell layout that wires a `<Sidebar>` to a main content
region and an optional mobile header. Use this whenever you want a
permanent sidebar on desktop with a hamburger overlay on mobile — it
resolves the CSS-variable scoping so the main content offset works without
boilerplate.

The component renders the sidebar internally; consumers configure it via
`sidebarHeader`, `sidebar`, and `sidebarFooter` snippets and bind `open`
for the mobile overlay (or for collapsible mode at all viewports).

For non-shell sidebars (right-side detail panels, drawers inside a page),
keep using the `<Sidebar>` primitive directly.

**Import:** `import { SidebarLayout } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
import { SidebarLayout, Button, MenuIcon } from '@urbicon-ui/blocks';
let sidebarOpen = $state(false);
</script>

<SidebarLayout bind:open={sidebarOpen} sidebarWidth="16rem">
{#snippet sidebarHeader()}
<a href="/" class="font-semibold">My App</a>
{/snippet}

{#snippet sidebar()}
<nav class="flex flex-col gap-1 p-3">
<a href="/dashboard">Dashboard</a>
<a href="/settings">Settings</a>
</nav>
{/snippet}

{#snippet mobileHeader({ openSidebar })}
<Button variant="ghost" size="sm" onclick={openSidebar} aria-label="Open menu">
<MenuIcon />
</Button>
<span class="font-semibold">My App</span>
{/snippet}

<h1>Page content</h1>
</SidebarLayout>
```

```svelte
<script>
import { SidebarLayout, Button, MenuIcon, createPersistentState } from '@urbicon-ui/blocks';

const railOpen = createPersistentState({ key: 'sidebar', defaultValue: true });
</script>

<SidebarLayout bind:open={railOpen.value} mode="collapsible" sidebarWidth="16rem">
{#snippet sidebarHeader()}<span class="font-semibold">App</span>{/snippet}
{#snippet sidebar()}<nav class="p-3"><!-- … --></nav>{/snippet}

{#snippet toggle(rail)}
<Button
variant="ghost"
size="sm"
{...rail.triggerProps}
onclick={rail.toggle}
aria-label={rail.open ? 'Collapse sidebar' : 'Expand sidebar'}
>
<MenuIcon />
</Button>
{/snippet}

<!-- main content -->
</SidebarLayout>
```

### Variants
- contentMaxWidth: 2xl, lg, md, none, sm, xl (default: xl)
- side: left, right (default: left)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| children | `Snippet` | no |  | Page content rendered inside the centered main column. |
| class | `string` | no |  | Additional CSS classes applied to the root wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| closeOnBackdropClick | `boolean` | no | true | Close the mobile sidebar overlay when clicking the backdrop. |
| closeOnEscape | `boolean` | no | true | Close the mobile sidebar overlay when pressing Escape. |
| contentMaxWidth | `SidebarLayoutVariants['contentMaxWidth']` | no | 'xl' | Maximum width of the centered content column. |
| mobileHeader | `Snippet<[MobileHeaderContext]>` | no |  | Mobile header bar, hidden on desktop in `responsive` mode. Receives a helper to open the sidebar so a hamburger button needs no extra wiring. If omitted, no mobile header is rendered — unless `toggle` is given, which needs the header bar as its mobile seam.  With `toggle`, the header already carries the sidebar control: leave your own hamburger out, or the bar shows two of them. |
| mode | `'responsive' | 'collapsible'` | no | 'responsive' | Sidebar mode. - `responsive` (default): permanent on desktop (≥1024px), slide-in overlay on mobile. - `collapsible`: toggleable at all viewports — width animation on desktop, overlay on mobile. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the sidebar open state changes. |
| open | `boolean` | no | false | Sidebar visibility. In `responsive` mode this only affects the mobile overlay. In `collapsible` mode it controls visibility at all viewports. Supports `bind:open`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ SidebarLayout: {...} }}>`. Use this to share a branded shell look across the app instead of repeating class overrides. |
| side | `SidebarLayoutVariants['side']` | no | 'left' | Which edge the sidebar attaches to. |
| sidebar | `Snippet` | no |  | Sidebar main content — typically a `<nav>`. |
| sidebarFooter | `Snippet` | no |  | Sidebar footer (below the scrollable nav). |
| sidebarHeader | `Snippet` | no |  | Sidebar header (above the scrollable nav). |
| sidebarWidth | `string` | no | '16rem' | Sidebar panel width. Single source of truth — the layout exposes it as `--sidebar-width` (constant) and `--sidebar-effective-width` (animates to `0` when collapsed) on the layout root, so the main content offset stays in sync automatically. |
| slotClasses | `Partial<Record<SidebarLayoutSlot, string>>` | no |  | Per-slot class overrides. A `sidebar`-prefixed key is forwarded to the embedded `<Sidebar>`'s slot of that name — `sidebarPanel` reaches its `panel`, `sidebarBackdrop` its `backdrop`, and so on. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| toggle | `Snippet<[SidebarToggleContext]>` | no |  | The control that opens and closes the sidebar, rendered by the layout at the seams it owns: the rail edge on desktop (`mode="collapsible"` only — a `responsive` sidebar is permanent there and `open` would toggle nothing) and the header bar on mobile. One snippet, both places, each render with its own `triggerId`.  The desktop grip floats over the content column, so while it renders the layout widens the content offset by `--sidebar-toggle-gutter`, which defaults to `3.5rem` — room for an icon button. A wider control needs a wider strip: set the property on the layout root, e.g. `class="[--sidebar-toggle-gutter:5rem]"`.  Persistence is deliberately not a prop: `createPersistentState` plus `bind:open` is the two-line version and keeps one storage story in the app. |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with `slotClasses` for a custom layout. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface MobileHeaderContext {
/** Open the sidebar (mobile overlay or collapsible panel). */
  openSidebar: () => void;
  /** Flip the sidebar open or closed. The `toggle` snippet is the wired-up version of this. */
  toggle: () => void;
  /** Current open state of the sidebar. */
  sidebarOpen: boolean;
}
```

```ts
interface SidebarToggleContext {
/** Whether the sidebar is currently open. */
  open: boolean;
  /** Flip it. */
  toggle: () => void;
  /** DOM id for this render of the trigger — already inside `triggerProps`. */
  triggerId: string;
  /** DOM id of the sidebar panel this trigger controls. */
  contentId: string;
  /** `id` / `aria-expanded` / `aria-controls` — spread these onto your button. */
  triggerProps: DisclosureTriggerProps;
}
```

```ts
type SidebarForwardKey = `sidebar${Capitalize<SidebarSlots>}`
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`root`, `mobileHeader`, `toggleRail`, `main`, `inner`

---

## Skeleton
Placeholder loading animation that mimics content layout.
Use to reduce perceived loading time and prevent layout shift.

**Import:** `import { Skeleton } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Skeleton variant="text" size="lg" />
<Skeleton variant="circular" size="md" />
<Skeleton variant="rectangular" width="100%" height="200px" />
```

```svelte
<div class="flex items-center gap-3">
  <Skeleton variant="circular" size="md" />
  <div class="flex flex-col gap-2 flex-1">
    <Skeleton variant="text" size="sm" />
    <Skeleton variant="text" size="xs" class="w-2/3" />
  </div>
</div>
```

### Variants
- variant: circular, rectangular, rounded, text (default: text)
- size: lg, md, sm, xl, xs (default: md)
- animation: none, pulse, wave (default: pulse)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...ElementAttributes | `HTMLAttributes` | no |  | All standard HTML element attributes |
| ...SkeletonVariants | `VariantProps` | no |  | Styling variants from SkeletonVariants |
| animation | `SkeletonVariants['animation']` | no |  | Animation style. `pulse` fades opacity, `wave` sweeps a shimmer gradient, `none` renders a static placeholder. All animations respect `prefers-reduced-motion`. |
| class | `string` | no |  | Extra classes merged onto the root element (or wrapper when `count > 1`). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| count | `number` | no |  | Number of skeleton lines to render. Wraps items in a flex-column container when > 1. |
| gap | `string` | no |  | Tailwind gap class between repeated lines (e.g. `"gap-4"`). Only applies when `count > 1`. Unset, the `wrapper` slot's own `gap-2` stands; set, it outranks a provider or preset `slotClasses.wrapper` in the gap bucket. |
| height | `string` | no |  | Custom height (CSS value, e.g. `"48px"`). Overrides the size preset height. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Skeleton: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `SkeletonVariants['size']` | no |  | Physical dimensions following the Standard size scale (xs–xl). Dimensions vary per variant — text heights range from h-3 (xs) to h-6 (xl), circular from 24 px to 64 px. |
| slotClasses | `Partial<Record<SkeletonSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) tv() output. Slots: base | wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. Combine with `slotClasses` for full control. |
| variant | `SkeletonVariants['variant']` | no |  | Shape preset. `text` is a slim bar, `circular` for avatars/icons, `rectangular` for images/cards, `rounded` like rectangular with softer corners. |
| width | `string` | no |  | Custom width (CSS value, e.g. `"200px"` or `"100%"`). Overrides the size preset width. |

Inherited from:
- SkeletonVariants (external)
- HTMLAttributes (html-attributes)

### Slots (slotClasses keys)
`base`, `wrapper`

---

## Slider
Slider for selecting a numeric value or range within min/max bounds.
Supports single and range modes, step snapping, tick marks, and labels.

Optional `validRange` and `recommendedRange` paint the track as a three-zone
gradient (red/yellow/green) and show a live status text that is also announced
via an ARIA live region. Both props are optional and additive — a slider
without `validRange`/`recommendedRange` behaves exactly as before.

**Import:** `import { Slider } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Slider label="Volume" bind:value={volume} />
```

```svelte
<Slider label="Price range" range bind:value={priceRange} min={0} max={500} step={10} showValue />
```

```svelte
<Slider
  label="Consumption share of heating costs"
  bind:value={share}
  min={0}
  max={100}
  step={5}
  validRange={[50, 100]}
  recommendedRange={[60, 80]}
  formatValue={(v) => `${v} %`}
/>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- variant: default, rail (default: default)
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- messageType: error, helper (default: helper)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...SliderVariants | `VariantProps` | no |  | Styling variants from SliderVariants |
| class | `string` | no |  | Extra classes merged onto the root wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | disabled property |
| error | `string` | no |  | Error message below the slider. Overrides `helper`. |
| formatValue | `(value: number | [number, number]) => string` | no |  | Format function for the displayed value. |
| helper | `string` | no |  | Helper text below the slider. Hidden when `error` is set. |
| label | `string` | no |  | Text label displayed above the slider. |
| marks | `SliderMark[]` | no |  | Tick marks along the track. |
| max | `number` | no | 100 | Maximum allowed value. |
| min | `number` | no | 0 | Minimum allowed value. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the slider's interactive area (the `base` slot — not the visual `track` slot). Only applies while not disabled. |
| name | `string` | no |  | Shared `name` for hidden inputs for form submission. |
| onValueChange | `(value: number | [number, number]) => void` | no |  | Fires after the value changes. Receives the new value. |
| outOfValidRangeIntent | `'danger' | 'warning'` | no | 'danger' | Intent applied outside the `validRange`. `'warning'` for softer limits (recommendation, not a violation), `'danger'` for hard limits. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Slider: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| range | `boolean` | no | false | Enable range mode with two thumbs. |
| rangeStatusText | `SliderRangeStatusText` | no |  | Custom status texts for the three zones. Defaults to the UIB i18n localization (`bt('slider.rangeStatus.*')`). |
| recommendedRange | `[number, number]` | no |  | Recommended value range (UX recommendation, softer than `validRange`). Values inside appear green, values outside yellow (warning). Typically `recommendedRange ⊂ validRange`, but this is not enforced. |
| showValue | `boolean` | no | false | Show the current value next to the label. |
| slotClasses | `Partial<Record<SliderSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | header | label | valueText | base (the interactive track container) | track | range | thumb | mark | boundaryTick | rangeStatus | rangeStatusIcon | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| step | `number` | no | 1 | Snap to increments of this value. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| validRange | `[number, number]` | no |  | Valid value range (e.g. a legal limit). Values outside it style track and thumb in the `outOfValidRangeIntent` color (default: `danger`). Status changes are announced via an ARIA live region. If the range lies outside `[min, max]`, a console warning is emitted — the visible `min`/`max` are NOT shifted automatically. |
| value | `number | [number, number]` | no |  | Current value. Number for single, [min, max] tuple for range. Supports `bind:value`. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Slider. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| variant | `'default' | 'rail'` | no | default | Controls the visual style and presentation of the Slider. Determines the component's visual treatment. Available options: default, rail. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Slider. Affects the component's physical footprint. Available options: lg, md, sm. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Slider component. Available options: error, helper. |

Inherited from:
- Omit<SliderVariants, 'error' | 'rangeStatus'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
interface SliderMark {
value: number;
  label?: string;
}
```

```ts
interface SliderRangeStatusText {
/** Value is within the recommended range. */
  insideRecommended?: string;
  /** Value is within the valid range but outside the recommended range. */
  insideValidOnly?: string;
  /** Value is outside the valid range. */
  outsideValid?: string;
}
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`wrapper`, `header`, `label`, `valueText`, `base`, `track`, `range`, `thumb`, `mark`, `boundaryTick`, `rangeStatus`, `rangeStatusIcon`, `message`

---

## Sparkline
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Tiny inline trend line — no axes, no labels — sized to flow in
table cells, cards, or running text. Zero-dependency SVG, optional area fill
and end-point dot. Fixed `width`/`height` by default, or set `fluid` to fill
the container width. Aria-hidden by default with an optional `ariaLabel`.

**Import:** `import { Sparkline } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Sparkline data={[3, 5, 4, 8, 6, 9]} area />
```

### Variants
- fluid: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `number[]` | yes |  | Sequence of values plotted left → right. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| area | `boolean` | no | false | Fill the area under the line. |
| ariaLabel | `string` | no |  | Accessible label; when omitted the sparkline is aria-hidden. |
| class | `string` | no |  | Extra classes merged onto the wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| color | `string` | no | 'var(--color-chart-1)' | Line + fill color. |
| fluid | `boolean` | no | false | Fill the container width instead of a fixed pixel size. Drops the svg's `width`/`height` attributes (they still set the `viewBox` aspect ratio) so it scales to its container; strokes stay crisp via `vector-effect="non-scaling-stroke"`. |
| height | `number` | no | 24 | Height in px. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| showEndPoint | `boolean` | no | false | Mark the last value with a single dot; style it via `slotClasses.endPoint`. |
| slotClasses | `SparklineSlotClasses` | no |  | Per-slot class overrides. `mark` is the trend line, `area` the band under it, `endPoint` the one dot at the last value — the charts' per-datum `point` has no counterpart here. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| strokeWidth | `number` | no | 1.5 | Stroke width in px. |
| unstyled | `boolean` | no |  | Remove all default classes. |
| width | `number` | no | 96 | Width in px. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
type SparklineSlotClasses = Partial<Record<SparklineSlots, string>>
```

### Slots (slotClasses keys)
`root`, `svg`, `mark`, `area`, `endPoint`

---

## Spinner
Animated loading indicator with multiple animation styles and semantic intents.

**Import:** `import { Spinner } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Spinner size="md" intent="primary" />
```

```svelte
<Spinner variant="bars" speed="fast" intent="success" />
```

### Variants
- intent: current, danger, neutral, primary, secondary, success, warning (default: primary)
  - current — Inherits the parent text colour via `currentColor` — for a spinner inside a coloured surface (filled Button, ConfirmDialog primary action, Toast action) that should pick up that surface's foreground instead of the intent palette.
- variant: bars, default, dots, pulse, ring (default: default)
- size: lg, md, sm, xl, xs (default: md)
- speed: fast, normal, slow (default: normal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...SpinnerVariants | `VariantProps` | no |  | Styling variants from SpinnerVariants |
| children | `Snippet` | no |  | Optional content rendered beside the spinner (e.g. loading text). |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| intent | `SpinnerVariants['intent']` | no |  | Semantic color applied via `text-*` token. |
| label | `string` | no |  | Accessible label announced by screen readers. Defaults to "Loading...". |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Spinner: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `SpinnerVariants['size']` | no |  | Physical dimensions from `xs` (16 px) to `xl` (40 px). |
| slotClasses | `Partial<Record<SpinnerSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) tv() output. Slots: base | svg | svgCircle | svgPath | dots | dot | pulse | pulseCenter | pulseRing | ring | ringElement | bars | bar | content | srOnly. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| speed | `SpinnerVariants['speed']` | no |  | Animation speed — controls `--spinner-speed` custom property. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. Combine with `slotClasses` for full control. |
| variant | `SpinnerVariants['variant']` | no |  | Animation style. `default` is an SVG arc, `dots` bounces three dots, `pulse` radiates a sonar ping, `ring` spins cascading borders, `bars` animates vertical equalizer bars. |
| visible | `boolean` | no |  | When false the spinner is removed from the DOM. |

Inherited from:
- SpinnerVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`base`, `svg`, `svgCircle`, `svgPath`, `dots`, `dot`, `pulse`, `pulseCenter`, `pulseRing`, `ring`, `ringElement`, `bars`, `bar`, `content`, `srOnly`

---

## SplitPane
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Resizable two-pane layout. A draggable divider (ARIA "window
splitter", role="separator") splits the container into a `start` and an `end`
pane; the first pane's share is controlled by `ratio` (0–1) and supports
`bind:ratio`. Resize by pointer drag or keyboard (Arrow / Home / End), with
optional collapse-to-zero. Panes clip their own overflow so their content
scrolls independently. For an application shell with a permanent nav rail
prefer SidebarLayout / Sidebar; reach for SplitPane when both regions are
primary content the user should be able to rebalance.

**Import:** `import { SplitPane } from '@urbicon-ui/blocks';`

### Examples
```svelte
<SplitPane bind:ratio={split} min="20%" max="80%">
  {#snippet start()}<nav class="p-4">…</nav>{/snippet}
  {#snippet end()}<main class="p-4">…</main>{/snippet}
</SplitPane>
```

```svelte
<SplitPane orientation="vertical" collapsible defaultRatio={0.3}>
  {#snippet start()}<section class="overflow-auto">Editor</section>{/snippet}
  {#snippet end()}<section class="overflow-auto">Preview</section>{/snippet}
</SplitPane>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| end | `Snippet` | yes |  | Second pane — fills the space the first pane leaves. Required. |
| start | `Snippet` | yes |  | First pane. In `horizontal` orientation it is the leading (left) pane; in `vertical` the top pane. Required. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...SplitPaneVariants | `VariantProps` | no |  | Styling variants from SplitPaneVariants |
| class | `string` | no |  | Extra classes merged onto the root container (the flex box). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| collapseThreshold | `number` | no | 48 | Pixel width/height of the first pane below which a drag snaps it collapsed. Only used when `collapsible`. |
| collapsible | `boolean` | no | false | Allow the first pane to collapse to zero: dragging below `collapseThreshold`, or pressing Enter on the divider, snaps it shut. |
| defaultRatio | `number` | no | 0.5 | Initial ratio for uncontrolled use; also the target of a double-click reset. |
| disabled | `boolean` | no | false | Disable resizing — the divider becomes inert (not focusable, no pointer/keyboard response). Panes stay visible. |
| handle | `Snippet` | no |  | Custom content rendered inside the divider (e.g. a grip icon). Replaces the default line; the divider stays the focusable separator. |
| handleLabel | `string` | no | 'Resize panes' | Accessible name for the divider (its `aria-label`). |
| max | `SplitPaneLimit` | no | '90%' | Upper bound for the first pane — px (`number`) or percentage string (`'90%'`). |
| min | `SplitPaneLimit` | no | '10%' | Lower bound for the first pane — px (`number`) or percentage string (`'20%'`). |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the divider (the `role="separator"` handle). Only applies while not disabled. |
| onCollapsedChange | `(collapsed: boolean) => void` | no |  | Fires when the first pane collapses (`true`) or re-expands (`false`) via drag or Enter. |
| onRatioChange | `(ratio: number) => void` | no |  | Fires after a drag/keyboard interaction changes the ratio. Receives the new ratio (`0`–`1`). Does not fire for consumer-driven `bind:ratio` writes. |
| orientation | `'horizontal' | 'vertical'` | no | 'horizontal' | Layout axis. `horizontal` places panes side by side (vertical divider); `vertical` stacks them (horizontal divider). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ SplitPane: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| ratio | `number` | no |  | First pane's share of the container, `0`–`1`. Supports `bind:ratio`. When omitted, starts at `defaultRatio` and is managed internally. |
| slotClasses | `Partial<Record<SplitPaneSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: root (the flex container — what `class` also targets) | startPane | endPane | handle (the draggable divider / separator). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv() classes; combine with `slotClasses` to rebuild the look. |

Inherited from:
- Omit<SplitPaneVariants, 'dragging' | 'orientation' | 'disabled'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type SplitPaneLimit = number | string
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`root`, `startPane`, `endPane`, `handle`

---

## Stepper
Multi-step progress indicator with horizontal/vertical layout,
clickable navigation, and per-step state overrides (error, warning).

**Import:** `import { Stepper } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Stepper activeStep={1}>
  <StepperStep label="Account" description="Create your account" />
  <StepperStep label="Profile" description="Set up your profile" />
  <StepperStep label="Review" description="Review and submit" />
</Stepper>
```

```svelte
<Stepper activeStep={0} orientation="vertical" clickable>
  <StepperStep label="Details" description="Enter your information">
    <p>Form content here...</p>
  </StepperStep>
  <StepperStep label="Confirm" description="Verify and submit" />
</Stepper>
```

### Variants
- variant: default, minimal, outlined (default: default)
- size: lg, md, sm (default: md)
- optionalNote: false, true
- orientation: horizontal, vertical (default: horizontal)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | StepperStep children. |
| ...HTMLAttributes<HTMLOListElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...StepperVariants | `VariantProps` | no |  | Styling variants from StepperVariants |
| activeStep | `number` | no | 0 | Current active step index (0-based). Supports bind:activeStep. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| clickable | `boolean` | no | false | Allow clicking step indicators to navigate between steps. |
| disabled | `boolean` | no | false | Disable all steps and prevent navigation. |
| linear | `boolean` | no | false | Restrict navigation to sequential order — only completed steps and the next step are clickable. |
| onStepChange | `(step: number) => void` | no |  | Fires when a step is activated via click. Passes the new step index. |
| orientation | `'horizontal' | 'vertical'` | no | 'horizontal' | Stack direction. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Stepper: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| responsive | `boolean | { breakpoint?: number }` | no | false | Container-responsive mode: when the Stepper's container is narrower than `breakpoint`, automatically switch to `orientation="vertical"` and `variant="minimal"` so the steps stay readable.  - `false` (default): never auto-switch. - `true`: switch below 640 px container width. - `{ breakpoint: 480 }`: switch below 480 px.  Uses `ResizeObserver` on the root element — works inside Drawers, Cards, or split layouts where viewport-based media queries miss the actual available width. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | size property |
| slotClasses | `Partial<Record<StepperSlots, string>>` | no |  | Per-slot class overrides. Slots: base | stepItem | step | indicatorColumn | indicator | labelGroup | label | description | separator | content. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tier | `InteractiveTier` | no | 'commit' | Semantic radius tier propagated to every StepperStep. Default `commit` — step indicators read as identity circles. Set to `modify` (or inherit via TierContext from a wrapping `<Toolbar tier="modify">`) to render a compact soft-rectangle stepper for inline wizards. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| variant | `'default' | 'outlined' | 'minimal'` | no | 'default' | Visual style of step indicators. |
| optionalNote | `'false' | 'true'` | no |  | Controls the optionalNote behavior and appearance of the Stepper component. Available options: false, true. |

Inherited from:
- Omit<StepperVariants, 'state' | 'clickable' | 'disabled' | 'separatorComplete'> (omit-pattern)
- Omit<HTMLAttributes<HTMLOListElement>, 'children'> (omit-pattern)

### Types
```ts
interface StepperContext {
readonly activeStep: number;
  readonly orientation: 'horizontal' | 'vertical';
  readonly variant: 'default' | 'outlined' | 'minimal';
  readonly size: 'sm' | 'md' | 'lg';
  readonly tier: InteractiveTier;
  readonly linear: boolean;
  readonly clickable: boolean;
  readonly disabled: boolean;
  /** SSR/first-paint index: the order steps initialise in. */
  registerStep: () => number;
  /** Client-side: register the step's `<li>` so its index can follow DOM order. */
  attachStep: (node: HTMLElement) => void;
  detachStep: (node: HTMLElement) => void;
  /** Index of the node in document order, or -1 while it is not attached. */
  stepIndexOf: (node: HTMLElement) => number;
  goToStep: (index: number) => void;
}
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

### Slots (slotClasses keys)
`base`, `stepItem`, `step`, `indicatorColumn`, `indicator`, `labelGroup`, `label`, `description`, `separator`, `content`

---

## StreamingMarkdown
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Streaming-safe markdown renderer for LLM output. Parses a growing
`content` string incrementally (settled blocks are never re-rendered) and renders
to a real component tree — never through `{@html}`, so raw HTML in the source
stays inert text. Links and images pass a strict-by-default URL policy
(external images blocked unless allowlisted). Citation markers like `[1]`
resolve to CitationChip when a matching entry exists in `sources`; code fences
render through CodeBlock. Per-node-type `renderers` snippets hook in syntax
highlighting, custom links, images, or citations without adding dependencies.

**Import:** `import { StreamingMarkdown } from '@urbicon-ui/blocks';`

### Examples
```svelte
<StreamingMarkdown content={message.text} streaming={message.status === 'streaming'} />
```

```svelte
<StreamingMarkdown
  content={answer}
  sources={[{ id: '1', title: 'Design tokens', url: 'https://ui.urbicon.de/tokens' }]}
  urlPolicy={{ allowedImagePrefixes: ['https://cdn.example.com/'] }}
/>
```

### Variants
- size: md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| content | `string` | yes |  | Markdown source. Append-only growth streams incrementally; any other change re-parses. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...StreamingMarkdownVariants | `VariantProps` | no |  | Styling variants from StreamingMarkdownVariants |
| autolink | `boolean` | no | false | Recognize bare `https://…` autolinks (GFM-style) |
| class | `string` | no |  | Custom CSS class. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| headingLevelStart | `1 | 2 | 3 | 4 | 5 | 6` | no | 1 | DOM heading level that markdown `#` maps to (deeper levels shift along, clamped at h6). Visual sizing keeps following the author's level. Set to 3 in a chat so message headings stay out of the page outline. |
| linkTarget | `'_blank' | '_self'` | no | '_blank' | Target for rendered links; `rel="noopener noreferrer"` is added for `_blank` |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ StreamingMarkdown: {...} }}>`. Prefer this over `class` overrides for reusable custom looks. |
| renderers | `MarkdownRenderers` | no |  | Per-node-type snippet overrides (code highlighting, router links, lightboxes, …) |
| size | `'sm' | 'md'` | no | 'md' | Type scale: `md` inherits the surrounding font size, `sm` is compact |
| slotClasses | `Partial<Record<StreamingMarkdownSlots, string>>` | no |  | Per-slot class overrides. Slots: base | paragraph | heading1–6 | inlineCode | link | linkBlocked | image | imageBlocked | listUnordered | listOrdered | listItem | taskItem | taskCheckbox | blockquote | codeBlock | tableWrapper | table | tableRow | tableHeadCell | tableCell | hr | cursor. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| sources | `CitationSource[]` | no |  | Citation sources. Ids activate `[id]` / `【id】` markers in the content, rendering them as CitationChip (1-based index follows array order). Markers without a matching id stay plain text. |
| streaming | `boolean` | no | false | Shows a pulsing cursor after the last block while the answer streams |
| tableRegionLabel | `string` | no | 'Table' | aria-label for the focusable scrollable region around tables |
| unstyled | `boolean` | no |  | Remove default styles |
| urlPolicy | `MarkdownUrlPolicy` | no |  | URL policy for links and images. Strict by default: links limited to http/https/mailto/tel + relative, every external image blocked. Keep the object referentially stable — a new reference re-parses the content. |

Inherited from:
- StreamingMarkdownVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
interface CitationSource {
/** Stable id — matches the `[id]` marker in the streamed markdown. */
  id: string;
  /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
  title: string;
  /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
  url?: string;
  /** Short excerpt shown under the title, clamped to ~3 lines. */
  snippet?: string;
}
```

```ts
interface MarkdownUrlPolicy {
/**
   * Allowed link protocols (with trailing colon). Relative URLs are always
   * allowed for links. @default ['http:', 'https:', 'mailto:', 'tel:']
   */
  allowedLinkProtocols?: string[];
  /**
   * Prefix allowlist for image sources, matched against the normalized
   * absolute URL. Empty (the default) blocks every external image; relative
   * sources are allowed. Prefer deep, specific prefixes — broad ones are
   * open-redirect bait. `data:` images are blocked unless a `data:` prefix
   * is listed explicitly.
   * @default []
   */
  allowedImagePrefixes?: string[];
  /** Observability hook — fires once per blocked URL occurrence. */
  onBlocked?: (kind: 'link' | 'image', url: string) => void;
}
```

```ts
interface MarkdownRenderers {
codeBlock?: Snippet<[{ code: string; lang?: string; open?: boolean }]>;
  /** `href` is already policy-checked: empty string when `blocked` is true. */
  link?: Snippet<[{ href: string; title?: string; children: InlineNode[]; blocked: boolean }]>;
  /** `src` is already policy-checked: empty string when `blocked` is true. */
  image?: Snippet<[{ src: string; alt: string; title?: string; blocked: boolean }]>;
  /** `source.url` is already policy-checked: stripped (undefined) when blocked. */
  citation?: Snippet<[{ id: string; source?: CitationSource; index?: number }]>;
}
```

```ts
type InlineNode = | { kind: 'text'; text: string }
  | { kind: 'strong'; children: InlineNode[] }
  | { kind: 'em'; children: InlineNode[] }
  | { kind: 'strike'; children: InlineNode[] }
  | { kind: 'code'; text: string }
  | {
      kind: 'link';
      /** Empty string when `blocked` is true — the original URL never reaches the DOM. */
      href: string;
      title?: string;
      children: InlineNode[];
      /** Set when the URL failed the `MarkdownUrlPolicy`; render as inert text. */
      blocked?: boolean;
    }
  | {
      kind: 'image';
      /** Empty string when `blocked` is true. */
      src: string;
      alt: string;
      title?: string;
      blocked?: boolean;
    }
  | {
      /** `[id]` / `【id】` citation marker; emitted only for ids in `MarkdownParseOptions.citationIds`. */
      kind: 'citation';
      id: string;
    }
  | { kind: 'break' }
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`base`, `paragraph`, `heading1`, `heading2`, `heading3`, `heading4`, `heading5`, `heading6`, `inlineCode`, `link`, `linkBlocked`, `image`, `imageBlocked`, `listUnordered`, `listOrdered`, `listItem`, `taskItem`, `taskCheckbox`, `blockquote`, `codeBlock`, `tableWrapper`, `table`, `tableRow`, `tableHeadCell`, `tableCell`, `hr`, `cursor`

---

## Tab
Tab container that manages tab switching and content display.
Supports horizontal/vertical orientation, visual variants, and keyboard navigation.

Tab props are a discriminated union on `orientation`. `fullWidth` is
only available on horizontal tabs — combining it with `orientation="vertical"`
fails type-check, since vertical triggers are already full-width by design.

**Import:** `import { Tab } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Tab bind:value={activeTab}>
  {#snippet tabs()}
    <TabItem value="overview">Overview</TabItem>
    <TabItem value="settings">Settings</TabItem>
    <TabItem value="billing">Billing</TabItem>
  {/snippet}
  {#snippet panels()}
    <TabPanel value="overview">Overview content</TabPanel>
    <TabPanel value="settings">Settings content</TabPanel>
    <TabPanel value="billing">Billing content</TabPanel>
  {/snippet}
</Tab>
```

```svelte
<Tab variant="line" size="sm" defaultValue="code">
  {#snippet tabs()}
    <TabItem value="code">Code</TabItem>
    <TabItem value="preview">Preview</TabItem>
  {/snippet}
  {#snippet panels()}
    <TabPanel value="code">Tab panel content</TabPanel>
    <TabPanel value="preview">Rendered output</TabPanel>
  {/snippet}
</Tab>
```

### Variants
- variant: enclosed, line, pills, solid (default: line)
- size: lg, md, sm (default: md)
- fullWidth: true (default: false)
- orientation: horizontal, vertical (default: horizontal)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| aria-label | `string` | no |  | Accessible name for the tab strip, applied to the inner `role="tablist"` element — not the root wrapper, whose role-less `<div>` forbids `aria-label`. Recommended whenever a page holds more than one tab strip; screen readers announce tablists only by this name. |
| aria-labelledby | `string` | no |  | Id of a visible element that labels the tab strip. Like `aria-label`, it is retargeted onto the inner `role="tablist"` element. Prefer this over `aria-label` when a visible heading already names the strip. |
| class | `string` | no |  | Additional CSS class merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| defaultValue | `string` | no |  | Default active tab for uncontrolled mode. Ignored when `value` is set. |
| disabled | `boolean` | no | false | Disables all tabs, preventing interaction and dimming the UI. |
| fullWidth | `boolean` | no | false | Stretch triggers to fill the available width. Only meaningful on horizontal tabs. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to each tab trigger (per-item via context). Only applies while the item is not disabled. |
| onValueChange | `(value: string) => void` | no |  | Fires when the active tab changes. Receives the new tab value string. |
| orientation | `'horizontal' | 'vertical'` | no | 'horizontal' | Tab strip axis. Determines whether triggers stack horizontally or vertically. |
| panels | `Snippet` | no |  | Snippet containing TabPanel components for the content area. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Tab: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<TabSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing when unstyled) tv() styles. Slots: base | list | trigger | icon | label | badge | panel | indicator. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tabs | `Snippet` | no |  | Snippet containing TabItem components for the tab strip. |
| tier | `InteractiveTier` | no | 'modify' | Semantic radius tier propagated to every TabItem. Default `modify` — tabs read as navigation tap surfaces. Set to `commit` (or inherit via TierContext from a wrapping `<Toolbar tier="commit">`) for full-pill tab strips in marketing/product-overview contexts. Only the `pills`, `solid`, and `enclosed` variants render a visible corner; `line` is radius-agnostic. |
| unstyled | `boolean` | no |  | Strip all default tv() styles from the container and children. |
| value | `string` | no |  | Controlled active tab value. Use with `bind:value` for two-way binding. When set, the component is controlled — you must handle `onValueChange` to update it. |
| variant | `'enclosed' | 'line' | 'pills' | 'solid'` | no | line | Controls the visual style and presentation of the Tab. Determines the component's visual treatment. Available options: enclosed, line, pills, solid. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Tab. Affects the component's physical footprint. Available options: lg, md, sm. |

### Types
```ts
interface RegisteredTab {
element: HTMLElement;
  isDisabled: () => boolean;
}
```

```ts
interface TabContext {
registerTab: (value: string, element: HTMLElement, isDisabled: () => boolean) => () => void;
  /**
   * Which tab holds the roving tab stop. Normally the active one — but a
   * disabled tab cannot hold focus, so the stop moves to the first enabled tab
   * rather than stranding there and dropping the tablist out of the tab order.
   */
  isTabStop: (value: string) => boolean;
  /**
   * Called by TabPanel while its element is actually in the DOM (rendering may
   * be deferred by `lazy`). TabItem emits `aria-controls` only for a value a
   * panel has claimed — consumers may render panel content themselves outside
   * `panels`, and an `aria-controls` pointing at a missing id is an axe
   * `aria-valid-attr-value` violation. Returns an unregister function.
   */
  registerPanel: (value: string) => () => void;
  hasPanel: (value: string) => boolean;
  selectTab: (value: string) => void;
  isActive: (value: string) => boolean;
  readonly variant: TabVariants['variant'];
  readonly orientation: TabVariants['orientation'];
  readonly size: TabVariants['size'];
  readonly tier: InteractiveTier;
  /**
   * Every axis TabItem styles itself with must travel through here — the
   * trigger is where `fullWidth` becomes `flex-1`, and a variants test on
   * `tabVariants({fullWidth:true})` stays green while the prop is missing
   * from the context (the gap this field closes).
   */
  readonly fullWidth: boolean;
  readonly disabled: boolean;
  readonly mint: MintProp;
}
```

```ts
type TabProps = TabPropsHorizontal | TabPropsVertical
```

```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`base`, `list`, `trigger`, `icon`, `label`, `badge`, `panel`, `indicator`

---

## Table
Advanced data table component with smart filtering, column factories, responsive design,
and extensible features for complex data visualization. Supports row selection, keyboard navigation,
virtual scrolling, column reorder, server-side data, live updates, and custom cell components.

**Import:** `import { Table } from '@urbicon-ui/table';`

### Examples
```svelte
<Table
items={data}
columns={columns}
viewDefaults={{ pageSize: 25 }}
enableSmartFilter={true}
/>
```

```svelte
{#snippet statusCell(item, value)}
<Badge intent={value === 'active' ? 'success' : 'danger'}>{value}</Badge>
{/snippet}

<Table items={data} columns={[
{ accessor: 'name', title: 'Name', sortable: true },
{ accessor: 'status', title: 'Status', cell: statusCell }
]} />
```

```svelte
<Table
items={data}
columns={columns}
selectionMode="multi"
onSelectionChange={(selected) => console.log(selected)}
/>
```

```svelte
<Table
columns={columns}
source={{
processing: 'server',
query: async (view, { signal }) => {
const res = await fetch(`/api/users?page=${view.page}`, { signal });
return await res.json();
}
}}
/>
```

```svelte
<Table items={tenThousandRows} columns={columns} virtualized virtualHeight="500px" />
```

```svelte
<script lang="ts">
import { Table, createTableView, bindViewToStorage } from '@urbicon-ui/table';

const view = createTableView({ defaults: { pageSize: 25 } });
bindViewToStorage(view, { key: 'expenses' });
</script>

<Table {items} {columns} {view} prefs={{ storage: 'expenses' }} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| activeRowId | `string | number | null` | no | null | The row that is currently being shown elsewhere — the master/detail pattern, where clicking a row renders that record beside or below the table.  Deliberately separate from selection: a selection is a set the user has marked for an action and brings a checkbox column with it, whereas a current row is a *view* state with no consequence beyond what is on screen. Marking one used to require `selectionMode`, which switched on that column as a side effect.  The matching row gets `aria-current="true"` and a `data-active` attribute (a hook for consumer CSS, e.g. emphasising a cell in that row), plus a quiet ground of its own. Ids are matched against `item.id`, with the row index as the same fallback the rest of the table uses. Pair it with `onRowClick` — this prop only reflects state, it never sets it. |
| ariaLabel | `string` | no | undefined | Accessible label for the table, announced by screen readers. |
| autoApplyOnNavigation | `boolean` | no | true | Automatically apply pending live updates when the user navigates (page change, sort, filter, search). Since the view is already changing, applying buffered changes at this point is non-disruptive. |
| body | `Snippet` | no | undefined | Custom body snippet |
| cardsBelow | `CardsBelowStep` | no | "48rem" | The width below which the table stops being a grid and becomes one card per row. Measured on the table's **own container** — not on the window — so a table in a narrow column switches while the window stays wide.  The right step depends on the columns, which is why it is a prop: a four-column index needs about 29rem and reads fine in a 32rem sidebar, while a twelve-column report is already cramped at 48rem. Add up the column `width`s and pick the next step above the sum.  Below the step the grid is not squeezed, it is replaced: the card list takes over, and the grid only ever renders at or above the width it was given. A grid wider than its container scrolls sideways. |
| cell | `Snippet<[item: T, value: unknown, column: Column<T>]>` | no | undefined | Global cell snippet that overrides rendering for ALL columns. For per-column customization, prefer `column.cell` instead. |
| class | `string` | no | undefined | Additional CSS class names for the table container. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| columns | `Column<T>[]` | no | [] | Column configuration array defining the table structure |
| emptyState | `Snippet` | no | undefined | Custom empty state snippet. Named after its `slotClasses.emptyState` slot (renamed from `empty` in v6.41 — `loading` is now the boolean state prop).  Must be table-row markup (`<tr><td colspan="99">…`) — it renders into the grid's `<tbody>`. **Grid only:** the card list below `TableProps.cardsBelow` renders `noDataText` instead, because row markup cannot live in a `<div>` (the parser drops the tags). Same contract as the two state snippets below. |
| enableColumnReorder | `boolean` | no | false | Enable drag-and-drop column reordering on desktop. Users can drag column headers to rearrange them. Also supports keyboard reorder via Shift+ArrowLeft/Right on focused headers. |
| enableColumnVisibility | `boolean` | no | true | Enable the column-visibility feature: the visibility menu in the smart filter bar and the "hide column" action in every header menu. Set `false` to remove both — this also reveals every currently-hidden column (including one restored from persistence), so no column is ever stranded hidden without a way back. For per-column control, set `hideable: false` on individual columns instead. |
| enableLiveUpdates | `boolean` | no | false | Enable live update support. When enabled, a `LiveUpdateBanner` is shown when pending inserts/updates/deletes are buffered. Get hold of `pushInsert`, `pushUpdate`, `pushDelete` for your WebSocket/SSE handler via `onReady` — or, from inside the table's own tree (a `toolbar` snippet, a custom cell), via `getTableContext()`. |
| enableSmartFilter | `boolean` | no | true | Enable smart filtering functionality |
| errorState | `Snippet` | no | undefined | Custom error state snippet. Named after its `slotClasses.errorState` slot (renamed from `error` in v6.41, alongside its two siblings).  Table-row markup, desktop only — mobile renders `errorText`. |
| errorText | `string` | no | i18n `error.loadingError` | Text displayed on error |
| expandedRowContent | `Snippet<[item: T]>` | no | undefined | Snippet to render expanded row content |
| fit | `'content' | 'viewport'` | no | "content" | Make the table its own scroll container so wide **and** long lists scroll *within* the table instead of pushing overflow onto the page.  - `'content'` (default): the table grows with its content; vertical overflow   scrolls the page. Pair with `sticky` for page-relative pinning. - `'viewport'`: the table is height-capped to the viewport and becomes a   self-contained scroll box. The column header (and group header when   grouping) pin to the top of the box and a total summary row to its bottom,   while the toolbar and pagination stay fixed outside the scrolling area —   only the rows scroll, in both axes. The   available height is measured automatically: the viewport, minus the space   reserved above the container by a pinned or clipping ancestor (zero in the   plain page flow, where the box can reach the top of the viewport). No magic   `max-height` is needed in the consumer.  Notes for `'viewport'`: - An assertion, not a measurement: it tells the table it owns the page   height, and it is honoured at every width. Set it only on a table that is   the page's primary content — inside a scrolling article the table caps   itself against the viewport all the same and gives you a second scroller. - Supersedes `sticky`: header/group pinning is intrinsic to the box, so the   `sticky` prop is ignored. `stickyOffset` still counts, as a floor under   the measured reservation: an app-shell bar that is an *ancestor* of the   table is measured, a `position: fixed` bar that is only a sibling is   not — declare its height and the cap leaves room for it. - Mutually exclusive with `virtualized`, which already has a bounded scroll   box of its own (`virtualHeight`) and pins the same two layers against it;   `fit` has no effect when `virtualized`, and a   DEV-build console warning names the combination — the refusal is otherwise   invisible, since `data-fit` publishes the resolved `"content"`. - The box reaches the bottom of the viewport, so it assumes nothing sits   *below* it. An ancestor with bottom padding (or a following sibling) is   pushed past `100dvh` and produces a second, page-level scrollbar next to   the table's own. The container reflects the resolved mode as   `data-fit="viewport"` (vs `"content"`, also when `virtualized`), so a   layout can drop that inset — at every width, exactly as the cap applies at   every width:   `main:has([data-fit='viewport']) { padding-block-end: 0 }`. |
| groupHeaderContent | `Snippet<[groupName: string, items: T[], isExpanded: boolean]>` | no | null | Custom content for group headers |
| groupOrder | `string[]` | no | [] | Custom order for group display |
| header | `Snippet` | no | undefined | Custom header snippet — the `<thead>` of the table, in place of the built-in one. In the virtualized layout the table sits in a scroll box of `virtualHeight` and the built-in head pins itself to the top edge of that box; a custom `<thead>` scrolls away with the rows unless it pins itself. The classes the built-in head uses there are `tableHeaderVariants({ sticky: 'box' }).header()` and `.row()` (exported from the package) — `sticky top-0 z-20 bg-surface-elevated` on the `<thead>`, plus an opaque ground and the underline on its `<tr>`. |
| initialSelectedIds | `Array<string | number>` | no | undefined | Initial selected row ids (if no persisted value exists). Seeds the uncontrolled selection once when the table is created. Ignored entirely when the controlled `selectedIds` prop is set — controlled always wins. A selection restored via `prefs.persistSelection` takes precedence. Later changes to this prop are ignored; users can still change or clear the selection. Rows are keyed by `item.id` (row-index fallback). Precedence when combined with `prefs.persistSelection` goes by *presence*, not emptiness: once storage holds a selection for this table — including the empty one written when the user deselected everything — it wins and the seed no longer applies. |
| items | `T[]` | no | [] | Array of data items to display in the table — the shorthand for `source={{ processing: 'client', items }}`, and the right prop whenever the rows are all you have to say. Reach for `source` once loading, error or a server total come into it.  Items with an `id` property get better key stability for animations. If no `id` is present, the array index is used as fallback key. |
| loadingState | `Snippet` | no | undefined | Custom loading state snippet, rendered while the `source` reports loading. Named after its `slotClasses.loadingState` slot.  Table-row markup, desktop only — mobile renders `loadingText`. |
| loadingText | `string` | no | i18n `data.loading` | Text displayed during loading state. The loading *state* itself comes from the `source` — `{ items, loading }` for data you fetch yourself, or the managed `{ query }` flow where the table drives it. |
| mobileCardDetails | `'collapsed' | 'expanded'` | no | "collapsed" | How much of a record a mobile card shows before it is opened. Below `TableProps.cardsBelow` of the table's **own container** — not of the window — the table renders one card per row instead of the grid. - `collapsed` (default): the card shows the first two card columns —   title and label-less subtitle — and opens the rest on tap. A record   costs roughly a third of the height, so a phone screen holds three   instead of one. - `expanded`: title on top, every other card column in the grid below it,   nothing hidden. The shape before v6.48.  Independent of `expandedRowContent`, which stays behind the chevron in both modes. |
| multiExpand | `boolean` | no | false | Allow multiple rows to be expanded simultaneously. When false (default), expanding a row collapses the previously expanded one. |
| noDataText | `string` | no | i18n `data.empty` | Text displayed when no data is available |
| onReady | `(context: TableContext) => void` | no |  | Called once with the table's context after the table is set up — the supported way to reach the imperative API from *outside* the table's tree (`getTableContext()` only resolves inside it).  The context is a live object typed as `TableContext` — since v8 a hand-written, deliberately narrow surface: `pushInsert`/`pushUpdate`/ `pushDelete` and `applyAllUpdates` for live feeds, the reactive `state`, the derived collections and the documented action methods. Hold on to it for the lifetime of the table; it is not re-created.  `state.items` and `state.columns` are reactive to *replacement*, not to writes reaching inside them: `state.items[0].name = 'x'` changes the row and re-renders nothing. Edit a row through `pushUpdate`, or assign a new array. |
| onRowClick | `(item: T) => void` | no | undefined | Callback fired when a row is clicked. Receives the clicked row's data item. |
| onSelectionChange | `(selectedItems: T[], selectedIds: Array<string | number>) => void` | no | undefined | Callback fired when the selection changes — and only then. Paging, sorting or a new page of server rows do not fire it.  The first argument is the selected rows, the second their ids. The two are **not** interchangeable: rows can only be handed over for the items the table currently holds, so under `processing: 'server'` the first argument carries the selected rows *of the loaded page* while the second carries the whole selection. The header checkbox states the same scope: in server mode it selects the loaded page and says so (mixed state, page-scoped label) — a selection here never silently claims rows the table has not seen.  With controlled `TableProps.selectedIds`, write the **ids** back — `(items, ids) => (selectedIds = ids)`. Mapping the rows instead (`items.map((item) => item.id)`) is correct in client mode and silently drops every row from another page in server mode. |
| pagination | `Snippet` | no | undefined | Custom pagination snippet |
| prefs | `TablePrefsConfig` | no | undefined | Preference channel (#152): column visibility, column order, summaries — and, opt-in, the selection. Preferences belong to the table, not the view: nobody wants to share a link that hides columns on the other end, so they live in web storage, never in the URL.  `storage` names the storage key (string shorthand or `{ key, kind?, debounceMs? }`); `defaults` are the initial preferences for a table nobody touched (applied at construction, SSR-visible); `persistSelection: true` opts the selection into storage.  Using the same key string here and in `bindViewToStorage` is a naming convention, not a link: the two channels stay independent, so persisting both the view and the preferences always takes both statements. |
| preset | `string` | no | undefined | Apply a named preset registered via `<BlocksProvider presets={{ Table: { … } }}>`. A preset's `slotClasses` use the same slot names as `TableProps.slotClasses` and sit between the provider's `defaults.Table` and this instance's own `slotClasses`. The resolved classes reach every subcomponent through the table style context, so a preset styles the frame, the header, the rows, the cells and the card list alike.  Prop-conditional `overrides` (in `defaults.Table` or in a preset) match `variant`, `size`, `cardsBelow`, `stickyToolbar` and `contained`. Those five, and no others: `tableContainerVariants` also carries `pinnedSummary`, which the table decides per render rather than per instance and does not publish here. The last two of the five are the resolved modes, not the props they derive from: `fit="viewport"` matches `{ contained: true }`, and a toolbar pinned to the page (`sticky`, `sticky="toolbar"` or `"both"`, unless the table resolves to `contained`) matches `{ stickyToolbar: true }`. A name no provider registers applies nothing and warns in development. |
| rowClickSelects | `boolean` | no | false | Whether clicking anywhere on a row body toggles that row's selection, in addition to the always-present checkbox.  On by default in `selectionMode="single"` (where a single click is the expected gesture and there is no marquee/range interaction to conflict with), as long as the row click means nothing else yet — neither `onRowClick` nor `expandedRowContent` is set. Set it explicitly to opt in for `multi` or for expandable rows, or to `false` to keep the checkbox as the only selection target.  A click that ends a text selection *inside the row* never selects, so cell content stays copyable. Applies to desktop rows (flat and grouped); mobile cards keep the checkbox as their only selection control, since a selectable card cannot be a button without nesting interactive elements.  Defaults to `true` only in `selectionMode="single"` without `onRowClick` and without `expandedRowContent` — a row click that already expands must not silently also select. |
| searchDebounceMs | `number` | no | undefined — the table's own mode-aware wait, which is not 0 | Debounce delay for search in milliseconds — the whole wait between a keystroke and the search taking effect, in either processing mode.  Left unset, the wait depends on the mode: 300 ms while the table filters client-side; in server mode the field writes through immediately and whoever fetches does the waiting — the managed source's own `debounceMs` (300 ms by default), or, where you fetch yourself, whatever delay you put in front of your fetch.  An explicit value is honoured in both modes and stays the *total* against a managed source (`source={{ processing: 'server', query }}`): the search field holds the write back for it, and the fetch that write triggers goes out at the end of that wait instead of adding `source.debounceMs` on top. `searchDebounceMs={300}` against a source debouncing 300 ms fetches at 300 ms, not at 600; `searchDebounceMs={0}` fetches at once. It covers the whole field, typing and clearing alike — Escape takes the same route as a backspace, so the two clear at the same moment. Search is the only change exempted: sort, filter, page and page size keep the source's debounce in full.  Two things this does not reach. **Coalescing moves with the delay:** at an explicit value the bar's timer is what collapses a burst of keystrokes, and the source's debounce no longer folds search requests together — with `searchDebounceMs={150}` against `debounceMs: 800`, every typing pause over 150 ms sends a request (each superseded one is aborted). Leave the prop unset to have the source's debounce do that job. **And the promise is the managed flow's:** where you fetch yourself (`{ processing: 'server', items, total }` plus `observeView`, or any hand-rolled effect), the table does not know about your delay and cannot subtract itself from it — an explicit value and your own debounce add up there, exactly as they always did. |
| searchPlaceholder | `string` | no | i18n `search.placeholder` | Placeholder text for search input |
| selectedIds | `Array<string | number>` | no | undefined | Controlled selected row ids. When set, `initialSelectedIds` is ignored and the table adopts this value: it seeds the selection at construction — the server HTML carries the selected rows — and every later prop value replaces the selection. An empty array is a valid value — nothing selected; `undefined` returns ownership to the table. User clicks still change the selection and fire `onSelectionChange` — write the new ids back into this prop, or the next change to it discards what the user clicked. Never written to storage (`prefs.persistSelection` has no effect), and a stored selection never overrides it — the prop is the source of truth. |
| selectionMode | `'none' | 'single' | 'multi'` | no | "none" | Row selection mode. - `'none'`: No selection (default) - `'single'`: Only one row can be selected at a time - `'multi'`: Multiple rows can be selected with checkboxes |
| size | `'sm' | 'md' | 'lg'` | no | "md" | Size variant for the table |
| slotClasses | `Partial<TableSlotClasses>` | no | {} | Per-slot class overrides merged with (or replacing, if `unstyled`) variant styles. Available slots: `container`, `toolbar`, `scrollArea`, `table`, `thead`, `tbody`, `headerRow`, `headerCell`, `row`, `cell`, `groupHeader`, `summaryRow`, `emptyState`, `loadingState`, `errorState`, `filterBar`, `mobileCard`.  The strongest layer of the `<BlocksProvider>` cascade: the provider's `defaults.Table.slotClasses`, then its matching `overrides`, then the active `preset`, then this prop. A later layer wins per Tailwind bucket, so a preset's `cell: 'p-2'` gives way to an instance `cell: 'p-4'`.  **Breaking change in v1.5:** the former `wrapper` slot has been replaced by `scrollArea`. The former hardcoded `overflow-hidden` on `wrapper` blocked `position: sticky`, see [docs/STICKY-PINNING.md](../../../../../docs/STICKY-PINNING.md). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| source | `TableSource<T>` | no | undefined | Where the rows come from, and **who processes them** — sorts, filters, searches and pages. Three shapes, and the invalid combinations of the old `mode`/`queryFn`/`loading`/`error`/`serverTotal` props are not expressible: - `{ processing: 'client', items, loading?, error? }` — the table does   that work in the browser; you fetched the rows, so `loading`/`error`   are yours to report - `{ processing: 'server', items, total, loading?, error? }` — your   backend does it; you fetch and hand in each page - `{ processing: 'server', query, debounceMs? }` — same, and the table   calls `query` when the view changes (first fetch immediate, later ones   debounced), manages loading/error and aborts superseded requests  `processing` is required on every variant: it decides whether the reader's sort headers reorder the page in front of them or ask your backend for a different one, which is too visible a difference to be inferred from a `total` that happened to be passed.  For rows and nothing else, reach for `items` — `source={{ processing: 'client', items }}` says the same thing. `source` wins when both are set. |
| sticky | `boolean | 'toolbar' | 'header' | 'both'` | no | false | Pin toolbar/header/group-header to the top of the scroll ancestor on scroll. - `false` (default): no pinning, layout matches v1.4.x - `true` / `'both'`: toolbar + thead + group-header all pin - `'toolbar'`: only the toolbar pins - `'header'`: only the thead (and group-header when grouping is active) pins  Pair with `stickyOffset` for app shells that have a fixed top bar.  For tables wider than the viewport, prefer `fit="viewport"` — it contains horizontal scroll inside the table instead of falling back to page-level horizontal scroll (a sticky pin host cannot also be a horizontal scroll ancestor). `fit="viewport"` supersedes `sticky` when set. |
| stickyOffset | `number` | no | 0 | Pixel offset for the topmost sticky layer (toolbar, or thead when no toolbar). Writes the CSS custom property `--blocks-table-sticky-top` on the container. Use this to push the pin below a fixed app shell top bar. With `fit="viewport"` the same figure is a floor under the space the box reserves above itself, for chrome the measurement cannot see (a fixed sibling bar). |
| toolbar | `Snippet` | no | undefined (renders default SmartFilterBar when enableSmartFilter) | Custom toolbar snippet. Replaces the default `SmartFilterBar`. Renders inside the sticky toolbar wrapper when `sticky` is enabled — so a custom toolbar inherits the pinning behavior without extra wiring.  Access the table context via `getTableContext()` to wire up custom filter UIs. |
| unstyled | `boolean` | no | false | Remove the default variant classes. Only user-provided `slotClasses` apply. `<BlocksProvider unstyled>` sets the same switch, so the table and the search field inside its toolbar lose their look in the same step. What stays either way is the desktop/card layout switch: structure, not look. |
| variant | `'flush' | 'surface' | 'framed'` | no | "flush" | Visual style of the table chrome (see the shipped VARIANT-CONTRACT.md § Table chrome): - `flush` (default): no outer frame, sits inline in the reading flow - `surface`: gentle `surface-quiet` tinted zone, no border - `framed`: bordered + rounded + shadowed standalone block  Applies to both layouts — on a narrow container the same frame wraps the mobile record list, whose records are separated by hairlines instead of each carrying a frame. |
| view | `TableView` | no | undefined | The view object — the six shareable axes (search, sort, page, pageSize, filters, groupBy) as one consumer-constructed reactive object, fully resolved against its `defaults`. The table reads and writes its fields directly (`view.page`, `view.sort`, …); decorate it with `bindViewToUrl` (from `@urbicon-ui/sveltekit-utils`) and/or `bindViewToStorage` to give the axes a home — the bindings are decorations over the object, not props of the table.  Leave unset for a table that owns its view (zero-config); use `viewDefaults` to adjust the defaults of that owned view. Passing both fails loud (also in prod — a miswired view corrupts state either way). Resolved once, at construction: a view is an identity, not a value — a later change of this prop is ignored.  The table's own interaction handlers reset the page on a new search, filter or grouping; a *direct field write* (`view.search = 'x'`) does not — write `view.page = 1` alongside, or go through the context's `setSearch`.  **Sharing one view across tables.** Several tables may mount the same view: they read and write the same six axes, and a table takes no claim of its own (a remounting `{#if}` child inherits the current state). A **virtualized** table renders any grouping the view carries as ungrouped — for itself only: the value stays on the view, and an un-virtualized sibling of the same view keeps rendering it grouped. One limit is worth knowing: a **managed source** (`{ query }`) on both tables fetches once *per table* per interaction — a shared view is not a shared cache; wire the fetch once yourself and hand both tables a manual `processing: 'server'` source if that matters. |
| viewDefaults | `TableViewDefaults` | no | undefined | Defaults for the view the table owns when no `view` prop is passed — the one-liner for the most common configuration: `viewDefaults={{ pageSize: 25 }}`. Mutually exclusive with `view` (a consumer-owned view carries its own defaults); passing both fails loud. Resolved once, at construction — a later change of this prop is ignored. |
| virtualHeight | `string` | no | "600px" | Height of the virtualized table's scroll box — the whole box, the column header and the summary row included: both are pinned inside it, so the rows get `virtualHeight` minus the two. Only used when `virtualized` is true. Accepts any CSS height value.  The summary pin is not this box's own trick: a total summary pins to the bottom edge of whichever scroll box the table owns, `virtualized` or `fit="viewport"`. While the list is too short to fill this box — a filter that matches a handful of rows — the summary sits under the last row instead: `position: sticky` cannot leave the `<table>`, and a short table does not reach the bottom of the box. |
| virtualized | `boolean` | no | false | Enable virtualization for large datasets. When enabled, only visible rows are rendered for performance with >1000 items. In client mode pagination is bypassed — the scrollable container holds all filtered/sorted rows. In server mode the pager stays: the container scrolls the loaded page, and paging remains the way to the rest of the result. Not compatible with grouping — and virtualization wins: the grouping affordances are suppressed, and a grouping arriving through the view (its defaults, a URL, storage) renders ungrouped (DEV warns). The value itself stays on the view and in the URL — an un-virtualized table reading the same view still groups, and a stored grouping applies again on the next load without `virtualized`. |

### Types
- `interface TableContext` — 48 members, definition omitted (224 lines; full definition: packages/table/src/lib/core/table/index.ts)

```ts
type Column = | DataColumnString<T>
  | DataColumnFunction<T>
  | SyntheticColumn<T>
```

```ts
type TableItem = Record<string, unknown>
```

```ts
interface TablePrefsConfig {
/**
   * Where to persist the preferences. A string is the shorthand for
   * `{ key }`; without this field the preferences stay volatile and only
   * `defaults` apply.
   */
  storage?:
    | string
    | {
        /** Unique identifier for this table — used as the storage-key suffix. */
        key: string;
        /** Storage type. @default 'localStorage' */
        kind?: 'localStorage' | 'sessionStorage';
        /** Write debounce in ms. @default 500 */
        debounceMs?: number;
      };
  /** Initial preferences for a table nobody has touched yet. */
  defaults?: {
    /** Column ids hidden initially. */
    hiddenColumns?: string[];
    /** Initial column order (resolved column ids). */
    columnOrder?: string[];
    /** Initial summary configurations. */
    summaries?: SummaryConfig[];
  };
  /**
   * Persist selected row ids across reloads. **Opt-in — default `false`**,
   * unlike every axis above (a restored selection surprises more often than
   * it helps). No effect when `selectedIds` is controlled: the prop is the
   * source of truth, so a controlled value is never written to storage.
   * Rows are keyed by `item.id`; without a stable `id` the selection falls
   * back to the row's position index, which restores onto *different* rows
   * after a reorder — enable this only for data with stable ids.
   */
  persistSelection?: boolean;
}
```

- `interface PageDescriptor` — 12 members, definition omitted (46 lines; full definition: packages/table/src/lib/stores/concerns/page-descriptor.ts)

- `interface TableState` — 25 members, definition omitted (152 lines; full definition: packages/table/src/lib/stores/concerns/types.ts)

```ts
interface LiveUpdateCounts {
inserts: number;
  updates: number;
  deletes: number;
  total: number;
}
```

```ts
interface SummaryConfig {
/** Column key to aggregate */
  column: string;
  /**
   * Aggregation type — derived from the one vocabulary in
   * `utils/summary-types.ts`, so the union and the rendered list of
   * types cannot drift apart (#251).
   */
  type: SummaryType;
  /** Optional custom formatter for the aggregated value */
  formatter?: (value: number) => string;
}
```

```ts
interface Filter {
/** Column ID the filter applies to (must match a column's resolved id) */
  column: string;
  /** Filter operator */
  operator: FilterOperator;
  /**
   * Filter value (string — `greaterThan`/`lessThan` compare it as a number
   * first, then as a date; see the interface docs)
   */
  value: string;
}
```

```ts
type FilterOperator = | 'contains'
  | 'equals'
  | 'startsWith'
  | 'endsWith'
  | 'greaterThan'
  | 'lessThan'
```

```ts
type CardsBelowStep = '24rem' | '28rem' | '32rem' | '36rem' | '42rem' | '48rem' | '56rem'
```

```ts
type TableSource = | ClientItemsSource<T>
  | ServerManualSource<T>
  | ServerManagedSource
```

```ts
class TableView {
  readonly defaults: TableViewSnapshot;
  constructor(defaults: TableViewDefaults = {});
  get search(): string;
  set search(value: string);
  get sort(): ViewSort | null;
  set sort(value: ViewSort | null);
  get page(): number;
  set page(value: number);
  get pageSize(): number;
  set pageSize(value: number);
  get filters(): Filter[];
  set filters(value: Filter[]);
  get groupBy(): string | null;
  set groupBy(value: string | null);
  applyExternal(partial: Partial<TableViewSnapshot>, origin: 'external'): void;
  originOf(axis: ViewAxis): { revision: number; origin: ViewOrigin | 'init' };
  snapshot(): TableViewSnapshot;
  claimAxes(kind: BindingKind, axes: readonly ViewAxis[]): void;
  releaseAxes(kind: BindingKind, axes: readonly ViewAxis[]): void;
  markInitApplied(axes: readonly ViewAxis[]): void;
  wasInitApplied(axis: ViewAxis): boolean;
  markStorageApplied(axes: readonly ViewAxis[]): void;
  wasStorageApplied(axis: ViewAxis): boolean;
}
```

```ts
type TableViewDefaults = Partial<TableViewSnapshot>
```

```ts
interface ViewSort {
/** Column ID to sort by (must match a column's resolved id). */
  column: string;
  /** Sort direction. */
  direction: 'asc' | 'desc';
}
```

- `interface TableSlotClasses` — 17 members, definition omitted (54 lines; full definition: packages/table/src/lib/core/table-style-context.ts)

- `interface DataColumnString` — 20 members, definition omitted (152 lines; full definition: packages/table/src/lib/types/tableTypes.ts)

- `interface DataColumnFunction` — 20 members, definition omitted (152 lines; full definition: packages/table/src/lib/types/tableTypes.ts)

- `interface SyntheticColumn` — 14 members, definition omitted (94 lines; full definition: packages/table/src/lib/types/tableTypes.ts)

```ts
type ProcessingMode = 'client' | 'server-manual' | 'server-managed'
```

```ts
type SummaryType = (typeof SUMMARY_TYPES)[number]['value']
```

```ts
interface ClientItemsSource {
processing: 'client';
  items: T[];
  loading?: boolean;
  error?: string | null;
  total?: never;
  query?: never;
}
```

```ts
interface ServerManualSource {
processing: 'server';
  items: T[];
  /** Total number of items matching the query — drives pagination. */
  total: number;
  loading?: boolean;
  error?: string | null;
  query?: never;
}
```

```ts
interface ServerManagedSource {
processing: 'server';
  /**
   * Called with the view itself — the same six axes the reader manipulates,
   * under the same names. Project it onto your backend's parameters inside
   * the function.
   */
  query: (q: TableViewSnapshot, options: { signal: AbortSignal }) => Promise<TablePage>;
  /** Debounce for refetches after the immediate first fetch. @default 300 */
  debounceMs?: number;
  items?: never;
  loading?: never;
  error?: never;
  total?: never;
}
```

```ts
interface TableViewSnapshot {
/** Full-text search term (`''` = no search). */
  search: string;
  /** Active sort, or `null` for unsorted — "unsorted" is a value, not a sentinel. */
  sort: ViewSort | null;
  /** Current page (1-based). */
  page: number;
  /** Number of items per page. */
  pageSize: number;
  /** Active column filters. */
  filters: Filter[];
  /** Column ID for grouping, or `null` for ungrouped. */
  groupBy: string | null;
}
```

```ts
type ViewAxis = (typeof VIEW_AXES)[number]
```

```ts
type ViewOrigin = 'user' | 'external'
```

```ts
type BindingKind = 'url' | 'storage'
```

```ts
type DataAccessor = [PrimitiveKeys<T>] extends [never] ? string : PrimitiveKeys<T>
```

```ts
interface TablePage {
/** Items for the current page/query */
  items: TableItem[];
  /** Total number of items matching the query — drives pagination. */
  total: number;
}
```

---

## TableOfContents
Sticky sidebar navigation that tracks scroll position and highlights the active section.
Hidden on mobile (DocsLayout provides a collapsible mobile alternative).

**Import:** `import { TableOfContents } from '@urbicon-ui/docs';`

### Examples
```svelte
<TableOfContents
  navigation={[
    { id: 'usage', title: 'Usage' },
    { id: 'api', title: 'API', children: [{ id: 'props', title: 'Props' }] }
  ]}
/>
```

### Variants
- position: left, right (default: right)
- width: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| navigation | `TocNavigationItem[]` | yes |  | Navigation items with optional nested children. |
| ...TableOfContentsVariantProps | `VariantProps` | no |  | Styling variants from TableOfContentsVariantProps |
| activeSection | `string` | no |  | Controlled active-section id. When provided (DocsLayout does this with its layout-wide scrollspy), the TOC renders the active marker from it and never starts its own scroll listener; leave undefined for standalone use, where the TOC tracks scroll itself (`trackScroll`). |
| class | `string` | no |  | Extra classes merged onto the root aside element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| related | `RelatedLink[]` | no |  | Optional Editorial `// RELATED` block rendered below the main nav. Each entry needs a pre-resolved `href` (the TOC does not call `resolve()`, mirroring the existing nav behaviour). When omitted, the related block does not render at all. |
| showCodeToggle | `boolean` | no | true | Render the Editorial `// CODE` block at the bottom of the TOC, hosting the global show-/hide-all-code toggle. Requires a host page that provided a `CodeVisibilityStore` via context — the block silently skips itself if no store is found, so callers outside of `DocsLayout` don't have to know about it. |
| slotClasses | `Partial<Record<TableOfContentsSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| title | `string` | no |  | Heading rendered above the nav links. Defaults to the localized "On this page". |
| trackScroll | `boolean` | no |  | Enable scroll-based active section tracking. |
| unstyled | `boolean` | no |  | Remove all default tv styles. |
| position | `'left' | 'right'` | no | right | Controls the position behavior and appearance of the TableOfContents component. Available options: left, right. |
| width | `'lg' | 'md' | 'sm'` | no | md | Controls the width behavior and appearance of the TableOfContents component. Available options: lg, md, sm. |

Inherited from:
- TableOfContentsVariantProps (external)

### Types
```ts
interface RelatedLink {
label: string;
  href: string;
}
```

```ts
interface TocNavigationItem {
id: string;
  title: string;
  href?: string;
  children?: Array<{ id: string; title: string; href?: string }>;
}
```

### Slots (slotClasses keys)
`aside`, `title`, `nav`, `link`, `linkActive`, `linkInactive`, `childLink`, `childLinkActive`, `childLinkInactive`, `relatedTitle`, `relatedNav`, `relatedLink`, `codeTitle`, `codeToggle`, `codeToggleLabel`

---

## Textarea
Multi-line text input with auto-resize, character counter, and validation states.
Shares the same variant/intent/size system as Input for visual consistency.

**Import:** `import { Textarea } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Textarea label="Description" placeholder="Tell us more..." bind:value={text} />
```

```svelte
<Textarea label="Bio" maxlength={280} showCounter autoResize />
```

### Variants
- intent: danger, default, success, warning (default: default)
- size: lg, md, sm, xl, xs (default: md)
- autoResize: true (default: false)
- disabled: true (default: false)
- messageType: error, helper (default: helper)
- readonly: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLTextareaAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'size' | 'class' | 'children') |
| ...TextareaVariants | `VariantProps` | no |  | Styling variants from TextareaVariants |
| autoResize | `boolean` | no | false | Automatically grow the textarea height to fit content. Disables manual resize handle. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| counterWarningThreshold | `number` | no | 0.9 | Character threshold (percentage of maxlength) at which the counter turns warning color. |
| disabled | `boolean` | no | false | disabled property |
| error | `string` | no |  | Error message below the textarea. Overrides `helper` and forces danger border styling. |
| helper | `string` | no |  | Helper text below the textarea. Hidden when `error` is set. |
| label | `string` | no |  | Label text displayed above the textarea, auto-linked via `for`/`id`. |
| maxRows | `number` | no |  | Maximum number of visible text rows when autoResize is enabled. |
| minRows | `number` | no | 3 | Minimum number of visible text rows. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the textarea element. Only applies while not disabled. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Textarea: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| readonly | `boolean` | no | false | readonly property |
| required | `boolean` | no | false | Adds a required asterisk to the label and sets the native `required` attribute. |
| showCounter | `boolean` | no |  | Show a live character counter. Requires `maxlength`; shows the current count against the limit (e.g. `42/280`). |
| slotClasses | `Partial<Record<TextareaSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | base (the `<textarea>` element) | label | requiredMark | footer | message | counter. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. Only user-provided classes apply. |
| variant | `TextareaVariants['variant']` | no | 'outlined' | Visual style. - `outlined` (default) — visible border, surface-base background - `filled` — surface-interactive fill, no border - `ghost` — transparent until hover/focus - `underline` — bottom-line only, no border-box (editorial style) - `bare` — no frame, no fill, no padding, no fixed height: the field reads as   the text it sits in. `size` keeps only the type step, and focus is an   outline in `--blocks-focus-ring-color` |
| intent | `'danger' | 'default' | 'success' | 'warning'` | no | default | Controls the color theme and semantic meaning of the Textarea. Affects the overall appearance and user perception. Available options: danger, default, success, warning. |
| size | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Textarea. Affects the component's physical footprint. Available options: lg, md, sm, and 2 more. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Textarea component. Available options: error, helper. |
| tier | `'commit' | 'modify'` | no | modify | Selects the semantic radius tier of the Textarea — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

Inherited from:
- Omit<TextareaVariants, 'error' | 'counterState' | 'variant'> (omit-pattern)
- Omit<HTMLTextareaAttributes, 'size' | 'class' | 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`wrapper`, `base`, `label`, `requiredMark`, `footer`, `message`, `counter`

---

## ThemeSwitcher
Cycles between light, dark, and system color schemes. Sets a
`light`/`dark` class on the `<html>` element for explicit choices and clears
it in system mode (so the CSS `light-dark()` function follows the OS natively).
Persists the choice to `localStorage` where that is usable, and never throws
where it is not: with storage switched off (a hardened browser profile, an
embedded webview) or a quota refusing the write, the button still switches the
theme and the choice simply does not survive a reload. So treat persistence as
best-effort — do not build a flow that depends on the stored key existing.

**Import:** `import { ThemeSwitcher } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ThemeSwitcher />
```

```svelte
<ThemeSwitcher size="lg" variant="outlined" strategy="toggle" />
```

### Variants
- variant: filled, ghost, outlined (default: ghost)
- size: lg, md, sm (default: md)
- disabled: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Additional CSS classes. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no |  | Disable the switcher. |
| onThemeChange | `(theme: Theme) => void` | no |  | Called after the theme changes. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ThemeSwitcher: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `ThemeSwitcherVariants['size']` | no | 'md' | Button size. |
| slotClasses | `Partial<Record<ThemeSwitcherSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| storageKey | `string | false` | no | 'urbicon-theme' | `localStorage` key holding the choice, or `false` to switch persistence off. A stored value is read once on mount; `'system'` is persisted as the ABSENCE of the key, so the OS keeps winning after a reload. Where storage is unusable nothing is written and nothing throws — the theme is back to `'system'` on the next load. |
| strategy | `'cycle' | 'toggle'` | no | 'cycle' | Interaction mode. - `'cycle'` — single button cycling light → dark → system (default) - `'toggle'` — single button toggling light ↔ dark (no system option) |
| theme | `Theme` | no | 'system' | Current theme. Supports `bind:theme`. |
| unstyled | `boolean` | no | false | Strip all default styles. |
| variant | `ThemeSwitcherVariants['variant']` | no | 'ghost' | Visual style of the button. |

### Types
```ts
type Theme = 'light' | 'dark' | 'system'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`button`, `icon`

---

## TimeInput
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Segmented time-of-day field — hour / minute (/ second) cells in a
single unified control, with per-segment Arrow-key stepping, digit auto-advance,
and 12- or 24-hour display. Fills the last form-family gap (Calendar, DatePicker
and DateRangePicker cover dates; this covers time). The value is always a
canonical 24-hour `HH:MM` (or `HH:MM:SS`) string regardless of display format,
and `null` when empty.

**Import:** `import { TimeInput } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  let time = $state('09:30');
</script>
<TimeInput label="Start" bind:value={time} />
```

```svelte
<TimeInput format="12h" withSeconds min="08:00" max="18:00" bind:value={time} />
```

### Variants
- intent: danger, default, success, warning (default: default)
- variant: filled, ghost, outlined (default: outlined)
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- fullWidth: true (default: false)
- messageType: error, helper (default: helper)
- readonly: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...TimeInputVariants | `VariantProps` | no |  | Styling variants from TimeInputVariants |
| aria-label | `string` | no |  | Accessible name for the field group when no visible `label` is set. |
| class | `string` | no |  | Extra classes merged onto the root wrapper. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | Blocks input and dims the whole field. |
| error | `string` | no |  | Error message below the field. When set it overrides `helper`, colours the field danger, and marks the segments `aria-invalid`. |
| format | `'12h' | '24h'` | no | '24h' | Display the hour as 12-hour with an AM/PM segment. The value stays 24-hour. |
| fullWidth | `boolean` | no | false | Stretch the field to the full width of its container. |
| helper | `string` | no |  | Helper text below the field — hidden when `error` is present. |
| icon | `Snippet` | no |  | A custom leading icon; replaces the default clock. |
| id | `string` | no |  | Root id; the segments derive their ids and ARIA wiring from it. |
| label | `string` | no |  | Label text displayed above the field, linked via `aria-labelledby`. |
| max | `string` | no |  | Latest allowed time, canonical 24-hour `HH:MM`(`:SS`). Values above it are clamped down on blur. |
| min | `string` | no |  | Earliest allowed time, canonical 24-hour `HH:MM`(`:SS`). Values below it are clamped up on blur. |
| name | `string` | no |  | Name for a hidden input carrying the canonical value, for native form submission. |
| onValueChange | `(value: string | null) => void` | no |  | Fires after any change with the canonical 24-hour value (or `null`). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ TimeInput: {...} }}>`. |
| readonly | `boolean` | no | false | Shows the time but refuses edits; the segments stay focusable. |
| required | `boolean` | no | false | Marks the label with an asterisk and sets `aria-required` on the segments. It does not block a native submit — the value lives in component state, so validate it yourself before you act on it. |
| showIcon | `boolean` | no | true | Show the leading clock icon. |
| slotClasses | `Partial<Record<TimeInputSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (what `class` also targets) | label | requiredMark | field | icon | segment | separator | meridiem | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |
| value | `string | null` | no |  | Current time as a canonical 24-hour `HH:MM` / `HH:MM:SS` string; `null` when empty. The stored format never changes with `format`. Supports `bind:value`. |
| withSeconds | `boolean` | no | false | Add a seconds segment. |
| intent | `'danger' | 'default' | 'success' | 'warning'` | no | default | Controls the color theme and semantic meaning of the TimeInput. Affects the overall appearance and user perception. Available options: danger, default, success, warning. |
| variant | `'filled' | 'ghost' | 'outlined'` | no | outlined | Controls the visual style and presentation of the TimeInput. Determines the component's visual treatment. Available options: filled, ghost, outlined. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the TimeInput. Affects the component's physical footprint. Available options: lg, md, sm. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the TimeInput component. Available options: error, helper. |
| tier | `'commit' | 'modify'` | no | modify | Selects the semantic radius tier of the TimeInput — the shape family it belongs to (`--radius-commit`/`-modify`/`-contain`/`-bridge`). Shape is retuned per family in your theme, so this picks the family rather than a pixel value. Available options: commit, modify. |

Inherited from:
- Omit<TimeInputVariants, 'error'> (omit-pattern)

### Types
```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`wrapper`, `label`, `requiredMark`, `field`, `icon`, `segment`, `separator`, `meridiem`, `message`

---

## Toast
Container that renders and manages toast notifications.
Place once in your root layout. Use the toaster store to trigger toasts from anywhere.

**Import:** `import { Toast } from '@urbicon-ui/blocks';`

### Examples
```svelte
<!-- +layout.svelte -->
<Toaster placement="bottom-right" />
```

```svelte
<script>
  import { toaster } from '@urbicon-ui/blocks';

  toaster.success('Saved!', { description: 'Changes applied.' });
  toaster.danger('Error', { description: 'Something went wrong.', duration: 8000 });
</script>
```

### Variants
- intent: danger, info, neutral, primary, success, warning (default: neutral)
- placement: bottom-center, bottom-left, bottom-right, top-center, top-left, top-right (default: bottom-right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the container element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| max | `number` | no | 5 | Maximum number of toasts visible at once. Oldest are hidden first. |
| placement | `ToastPlacement` | no | 'bottom-right' | Screen corner where toasts stack. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Toaster: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<ToasterSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| transitionDuration | `number` | no |  | Override the enter/exit fly animation duration in milliseconds for every toast in this toaster. Defaults to the overlay token `--blocks-overlay-enter-duration` (200ms). Set globally via the CSS custom property or per-instance via this prop. Respects `prefers-reduced-motion`. |
| transitionEasing | `(t: number) => number` | no |  | Override the enter/exit fly easing. Defaults to the overlay token easing (`quintOut`). |
| unstyled | `boolean` | no |  | Strip all default tv classes. Use with `slotClasses` for a fully custom look. |
| intent | `'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Toast. Affects the overall appearance and user perception. Available options: danger, info, neutral, and 3 more. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type ToastIntent = (typeof TOAST_INTENTS)[number]
```

```ts
interface ToastAction {
/** Button label. */
  label: string;
  /** Click handler. Receives the toast id so the handler can dismiss/update it. */
  onClick?: (id: string) => void;
  /** Dismiss the toast after the click. @default true */
  dismissOnClick?: boolean;
}
```

```ts
interface ToastData {
/** Unique identifier assigned automatically. Used for programmatic dismissal via `toaster.dismiss(id)`. */
  id: string;
  /** Semantic color of the toast. Affects border, icon, and progress bar color. @default 'neutral' */
  intent: ToastIntent;
  /** Bold heading line. Omit for a minimal notification. */
  title?: string;
  /** Secondary text below the title. */
  description?: string;
  /** Auto-dismiss delay in milliseconds. Set to `0` for persistent toasts that require manual dismissal. @default 5000 */
  duration: number;
  /** Show a close button so the user can dismiss manually. @default true */
  dismissible: boolean;
  /** Show an animated progress bar that counts down the remaining `duration`. @default true */
  showProgress: boolean;
  /** Primary action button (prominent). */
  action?: ToastAction;
  /** Secondary/cancel button (quiet). */
  cancel?: ToastAction;
  /** Render a spinner instead of the intent icon (used by `toaster.promise` while pending). @default false */
  loading?: boolean;
}
```

```ts
interface ToastPromiseOptions {
/** Shown while the promise is pending (spinner, persistent, not dismissible). */
  loading: string | ToastInput;
  /** Shown when the promise resolves. */
  success: string | ToastInput | ((value: T) => string | ToastInput);
  /** Shown when the promise rejects. */
  error: string | ToastInput | ((reason: unknown) => string | ToastInput);
}
```

```ts
type ToastInput = Partial<Omit<ToastData, 'id'>>
```

```ts
type ToastShorthandOpts = Omit<ToastInput, 'intent' | 'title'>
```

```ts
type ToastPlacement = | 'top-right'
  | 'top-left'
  | 'top-center'
  | 'bottom-right'
  | 'bottom-left'
  | 'bottom-center'
```

### Slots (slotClasses keys)
`container`, `toast`, `icon`, `content`, `title`, `description`, `actions`, `actionButton`, `cancelButton`, `dismissButton`, `progress`

---

## Toggle
Accessible switch control for boolean on/off states.
Built on a hidden native input with semantic intents and Mint micro-interactions.

**Import:** `import { Toggle } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Toggle label="Enable notifications" bind:checked />
```

```svelte
<Toggle
  intent="success"
  size="lg"
  withBorder
  onCheckedChange={(val) => console.log('toggled', val)}
/>
```

```svelte
<div class="space-y-2">
  <Toggle label="Email notifications" />
  <Toggle label="Push notifications" />
</div>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- variant: default, dot (default: default)
  - default — Classic switch pill — a track with an animated thumb.
  - dot — Small indicator dot left of the label — outline only when off, filled in the intent colour when on; monochrome, no pill background.
- size: lg, md, sm, xs (default: md)
- disabled: true (default: false)
- tier: commit, modify (default: commit)
- withBorder: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLInputAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'type' | 'size' | 'checked' | 'class' | 'children') |
| ...ToggleVariants | `VariantProps` | no |  | Styling variants from ToggleVariants |
| checked | `boolean` | no |  | Current on/off state. Supports two-way binding via `bind:checked`. |
| class | `string` | no |  | Extra classes merged onto the outermost wrapper element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no |  | Prevent interaction and dim the control. |
| error | `string` | no |  | Error message shown below the control. Replaces `helper`, flags the hidden input `aria-invalid`, and marks the unchecked track with the danger colour — e.g. for a consent toggle that must be switched on. |
| helper | `string` | no |  | Helper text shown below the control. Hidden when `error` is set. Useful for explaining side-effects of the toggle. |
| id | `string` | no |  | Explicit `id` to link `<label>` and `<input>`. Auto-generated if omitted. |
| label | `string` | no |  | Text label displayed to the right of the toggle track. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the track. Only applies while not disabled. |
| name | `string` | no |  | The `name` attribute of the underlying `<input>`. Used for form submission. |
| onCheckedChange | `(checked: boolean) => void` | no |  | Fired after the checked state changes. Receives the new `checked` value. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Toggle: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no |  | Mark the native input as required for form validation. |
| slotClasses | `Partial<Record<ToggleSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. Slots: wrapper (root — what `class` also targets) | control (the `<label>` wrapping the input) | track | thumb | label | message. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tier | `InteractiveTier` | no |  | Semantic radius tier. Default `commit` — a toggle declares status (on/off identity), and reads as a pill. Set to `modify` (usually via a wrapping `<Toolbar tier="modify">` propagating through TierContext) for inline-toolbar contexts where the Pill feels oversized — the track and thumb shrink to a soft-rectangle.  Inherited from TierContext when omitted; falls back to `commit` outside of any tier-aware container. |
| unstyled | `boolean` | no |  | Strip all default variant classes. Use with `slotClasses` for a fully custom look. The track exposes `data-state` for conditional styling. |
| value | `string` | no |  | The value submitted when checked. Defaults to `'on'`. |
| variant | `ToggleVariants['variant']` | no | 'default' | Visual style of the control. Reach for `dot` where the switch pill is visually too loud — dense settings rows, inline toolbars. |
| withBorder | `boolean` | no |  | Draw a subtle border around the track. Helps distinguish the control on busy backgrounds. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Toggle. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Toggle. Affects the component's physical footprint. Available options: lg, md, sm, xs. |

Inherited from:
- Omit<ToggleVariants, 'checked' | 'error'> (omit-pattern)
- Omit<HTMLInputAttributes, 'type' | 'size' | 'checked' | 'class' | 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`wrapper`, `control`, `track`, `thumb`, `label`, `message`

---

## ToolCallCard
**Stability:** experimental — shipped to be used and judged, but the API may change in any release without notice.
Collapsible disclosure for one agent tool-call part (`type: 'tool-call'`)
— a status indicator + monospaced tool name in the header, and the JSON input/output (or an
error message) in the expandable body. It is the default renderer ChatMessage reaches for on
`tool-call` parts (wire it in via `partRenderers`). By default it renders `plain`: one muted
line in the message flow, in the same register as ReasoningDisclosure, because a reader
following prose is not reading the machinery. Switch to `variant="card"` where the call is
the content — an agent trace, a tool-run log.
Opens itself when a call fails so the error is visible without a click; a manual toggle always
wins afterwards. Pass a `children` snippet to replace the default JSON body with a
domain-specific view of the same part.

**Import:** `import { ToolCallCard } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ToolCallCard toolCall={part} />
```

```svelte
<ToolCallCard toolCall={part} variant="card" />
```

```svelte
<ToolCallCard {toolCall}>
{#snippet children(call)}
<WeatherResult data={call.output} />
{/snippet}
</ToolCallCard>
```

### Variants
- variant: card, plain (default: plain)
- callState: complete, error, pending, running (default: pending)
- open: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| toolCall | `ChatToolCallPart` | yes |  | The tool-call part to render. Required. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class' | 'children') |
| children | `Snippet<[ChatToolCallPart]>` | no |  | Replace the default JSON input/output body with a custom rendering of the tool-call part. Receives the same `toolCall`. When provided, the built-in error line + input/output sections are not rendered. |
| class | `string` | no |  | Extra classes merged onto the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| completeLabel | `string` | no | 'Done' | Header status label for the `complete` state. |
| defaultOpen | `boolean` | no |  | Initial expanded state for uncontrolled usage. Defaults to `true` when the call is already in the `error` state, `false` otherwise. |
| errorLabel | `string` | no | 'Failed' | Header status label for the `error` state. |
| inputLabel | `string` | no | 'Input' | Caption in the input payload's header. |
| onOpenChange | `(open: boolean) => void` | no |  | Fired once per toggle, after the new open state is applied. |
| open | `boolean` | no |  | Whether the card is expanded. Supports `bind:open`. Left uncontrolled, the card starts collapsed for `pending` / `running` / `complete` and expanded for `error`. |
| outputLabel | `string` | no | 'Output' | Caption in the output payload's header. |
| pendingLabel | `string` | no | 'Pending' | Header status label for the `pending` state. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ToolCallCard: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette. |
| runningLabel | `string` | no | 'Running' | Header status label for the `running` state. |
| slotClasses | `Partial<Record<ToolCallCardSlots, string>>` | no |  | Per-slot class overrides. Slots: `trigger` (header button), `triggerLeft`, `triggerRight`, `spinner`, `toolName`, `statusText` (the plain header's status; `card` uses a Badge instead), `chevron`, `body`, `section`, `errorMessage`. The payloads render as `variant="plain"` CodeBlocks — style those through `<BlocksProvider presets={{ CodeBlock: {...} }}>`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| unstyled | `boolean` | no |  | Strip the component's default tv() classes, the underlying Collapsible's and the status Badge's. |
| variant | `'plain' | 'card'` | no | 'plain' | How prominent the header is. `plain` is one muted line in the message flow, with no outline, surface, or badge, as wide as its own text. `card` is a framed header (outline, radius, shadow, status badge, the container's full width) for surfaces where the tool call is the subject. |
| callState | `'complete' | 'error' | 'pending' | 'running'` | no | pending | Controls the callState behavior and appearance of the ToolCallCard component. Available options: complete, error, pending, running. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> (omit-pattern)

### Types
```ts
type ChatToolCallPart = Extract<ChatMessagePart, { type: 'tool-call' }>
```

```ts
type ChatMessagePart = | { type: 'text'; text: string }
  /** Model reasoning. Collapsed, tertiary presentation; `durationMs` feeds the "Thought for Xs" label. */
  | { type: 'reasoning'; text: string; durationMs?: number }
  /** A tool invocation with its lifecycle state. Rendered as a ToolCallCard by default; override via `partRenderers`. */
  | {
      type: 'tool-call';
      id: string;
      name: string;
      state: 'pending' | 'running' | 'complete' | 'error';
      input?: unknown;
      output?: unknown;
      errorMessage?: string;
    }
  /** A cited source. Same shape as CitationSource — also feeds StreamingMarkdown's `sources` for `[id]` markers. */
  | ({ type: 'source' } & CitationSource)
  /**
   * A file attached to the message. `url` is only ever rendered as a
   * policy-checked download link (never as an inline image/iframe) — LLM- or
   * server-supplied URLs are untrusted input.
   */
  | { type: 'attachment'; name: string; mimeType: string; size?: number; url?: string }
  /** Declarative A2UI payload (P4). Validated fail-loud by A2UIView; ignored by default renderers until then. */
  | { type: 'a2ui'; payload: unknown }
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
interface CitationSource {
/** Stable id — matches the `[id]` marker in the streamed markdown. */
  id: string;
  /** Human-readable source title, always shown in the popover (and as the chip label under `citationStyle="label"`). */
  title: string;
  /** Source URL. Rendered as an outbound link only when it passes the `urlPolicy`; a blocked or absent URL shows title/snippet with no link. */
  url?: string;
  /** Short excerpt shown under the title, clamped to ~3 lines. */
  snippet?: string;
}
```

### Slots (slotClasses keys)
`trigger`, `triggerLeft`, `triggerRight`, `spinner`, `toolName`, `statusText`, `chevron`, `body`, `section`, `errorMessage`

---

## Toolbar
Container for grouping related controls in a horizontal or vertical bar.
Renders with role="toolbar" and auto-sets aria-orientation.

**Import:** `import { Toolbar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Toolbar aria-label="Text formatting">
  <Button variant="ghost" size="sm">B</Button>
  <Button variant="ghost" size="sm">I</Button>
  <Separator orientation="vertical" size="sm" />
  <Button variant="ghost" size="sm">Left</Button>
  <Button variant="ghost" size="sm">Center</Button>
</Toolbar>
```

```svelte
<Toolbar aria-label="Actions" orientation="horizontal">
  <ButtonGroup connected size="sm" variant="ghost">
    <Button value="undo">Undo</Button>
    <Button value="redo">Redo</Button>
  </ButtonGroup>
  <Separator orientation="vertical" />
  <Button variant="ghost" size="sm" intent="danger">Delete</Button>
</Toolbar>
```

### Variants
- variant: elevated, ghost, outlined, quiet (default: quiet)
- gap: lg, md, sm, xl, xs (default: sm)
- orientation: horizontal, vertical (default: horizontal)
- padding: lg, md, sm, xl, xs (default: sm)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| aria-label | `string` | yes |  | Accessible label describing the toolbar's purpose (e.g. "Formatting toolbar"). Required. |
| children | `Snippet` | yes |  | Toolbar content — typically Buttons, Toggles, Separators, or ButtonGroups. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...ToolbarVariants | `VariantProps` | no |  | Styling variants from ToolbarVariants |
| class | `string` | no |  | Additional CSS class applied to the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Toolbar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<ToolbarSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing when `unstyled`) the default classes. Slots: base. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tier | `InteractiveTier` | no | 'modify' | Semantic radius tier propagated to tier-aware children (Buttons, Badges, Inputs, …). The Toolbar's own surface stays `r-structure` regardless of this prop.  Default `modify` — toolbars typically hold compact, icon-only actions where pill-shaped buttons read as tags. Set to `commit` for marketing or hero toolbars with full CTAs. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. Combine with `slotClasses` to restyle from scratch. |
| variant | `'elevated' | 'ghost' | 'outlined' | 'quiet'` | no | quiet | Controls the visual style and presentation of the Toolbar. Determines the component's visual treatment. Available options: elevated, ghost, outlined, quiet. |
| gap | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | sm | Controls the gap behavior and appearance of the Toolbar component. Available options: lg, md, sm, and 2 more. |
| orientation | `'horizontal' | 'vertical'` | no | horizontal | Controls the orientation behavior and appearance of the Toolbar component. Available options: horizontal, vertical. |
| padding | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | sm | Controls the padding behavior and appearance of the Toolbar component. Available options: lg, md, sm, and 2 more. |

Inherited from:
- ToolbarVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Types
```ts
type InteractiveTier = 'commit' | 'modify'
```

### Slots (slotClasses keys)
`base`

---

## Tooltip
Contextual overlay that displays brief, supplementary text on hover or focus.
Built on the library's own positioning engine for precise placement and accessibility support.
Renders as phrasing content — trigger, panel and arrow are all `<span>` — so it is valid inside a
paragraph, the position it is meant for. `Popover` needs its `inline` prop for that; `Tooltip`
needs no opt-in, because `label` is a string and cannot carry block content. Two caveats: the
trigger children are yours, and a `<div>` there closes the paragraph again; and the trigger
wrapper is `inline-flex`, so it is atomic — a multi-word trigger will not break across lines.

**Import:** `import { Tooltip } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Tooltip label="Save your changes">
  <Button>Save</Button>
</Tooltip>
```

```svelte
<Tooltip label="Copy to clipboard" placement="right" arrow showDelay={100}>
  <Button variant="ghost" size="sm" onclick={handleCopy}>Copy</Button>
</Tooltip>
```

```svelte
<script lang="ts">
let copied = $state(false);
async function copy() {
await navigator.clipboard.writeText(text);
copied = true;
setTimeout(() => (copied = false), 1500);
}
</script>

<Tooltip label="Copied!" bind:open={copied}>
<Button onclick={copy}>Copy</Button>
</Tooltip>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- size: lg, md, sm (default: md)
- open: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | The trigger element(s) that activate the tooltip. |
| label | `string` | yes |  | Text displayed inside the tooltip bubble. |
| ...HTMLAttributes<HTMLSpanElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...TooltipVariants | `VariantProps` | no |  | Styling variants from TooltipVariants |
| arrow | `boolean` | no | true | Whether to show a directional arrow pointing at the trigger. |
| class | `string` | no |  | Additional CSS class for the tooltip panel.  One class to avoid: anything that sets `display`. The panel is a `<span>` that CSS blockifies through its `position: fixed`, and an author-level `display` also beats the UA rule `[popover]:not(:popover-open) { display: none }` — the closed tooltip then keeps a laid-out box, invisible but present in the a11y tree and to find-in-page. The same applies to `slotClasses.base`, a `preset`, and `BlocksProvider` overrides. A unit test holds this component's own variants to the rule; nothing checks what you pass in. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no | false | Prevent the tooltip from appearing regardless of hover/focus. |
| hideDelay | `number` | no | 100 | Milliseconds before the tooltip disappears after leaving the trigger. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the tooltip opens or closes from user interaction (hover in/out, focus/blur, Escape). Receives the new open state. Not called when the consumer writes `bind:open` directly. |
| open | `boolean` | no | false | Controls tooltip visibility. Supports `bind:open` for programmatic display (e.g. a transient "Copied!" confirmation). Hover/focus keep driving the state in parallel — the delays apply only to those interaction paths, a `bind:open` write takes effect immediately. |
| placement | `Placement` | no | 'top' | Where the tooltip appears relative to the trigger. Auto-flips when clipped. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Tooltip: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| showDelay | `number` | no | 200 | Milliseconds before the tooltip appears after hover/focus. Prevents accidental activation. |
| slotClasses | `Partial<Record<TooltipSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when unstyled) tv styles. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| transitionDuration | `number` | no |  | Override the fade duration in milliseconds. Distinct from `showDelay` / `hideDelay`, which time *when* the tooltip appears — this is how fast the opacity fade itself runs. Defaults to the tooltip token `--blocks-tooltip-duration` (fast, 150ms). Respects `prefers-reduced-motion`. |
| transitionEasing | `string` | no |  | Override the fade easing as a CSS `<easing-function>` (e.g. `'linear'`, `'ease-out'`, `'cubic-bezier(0.4,0,0.2,1)'`). Defaults to the tooltip token `--blocks-tooltip-easing`. A CSS string, not a JS easing fn, because the tooltip fade is a pure CSS transition. |
| unstyled | `boolean` | no |  | Remove default tv classes; only consumer classes apply. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Tooltip. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Tooltip. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- TooltipVariants (external)
- Omit<HTMLAttributes<HTMLSpanElement>, 'children'> (omit-pattern)

### Types
```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

### Slots (slotClasses keys)
`base`, `arrow`

---

## TwoFactorManager
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
Self-service two-factor (TOTP) management: enrol with an
authenticator app, show one-time backup codes, and disable with a password
re-auth. Talks to `apiPath` (default `/api/auth/account/2fa`); pair with
`createTwoFactorHandlers` — this panel uses its `setup`, `enable` and
`disable` groups. The core stays zero-dependency, so QR
rendering is delegated to the `qr` snippet — without it the otpauth URI +
Base32 secret are shown for manual entry.

**Import:** `import { TwoFactorManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<TwoFactorManager {user} onEnabled={() => auth.checkStatus()}>
  {#snippet qr({ uri })}
    <QRCode value={uri} errorCorrection="H" />
  {/snippet}
</TwoFactorManager>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| user | `AuthUser | null` | yes |  | The current authenticated user: its `totpEnabled` seeds the initial state and its `email` labels the otpauth entry. While `null` nothing renders. Resolve `user` before mount, or remount with `{#key user?.id}…{/key}` to re-seed after an async load. |
| apiPath | `string` | no | '/api/auth/account/2fa' | API base path for the 2FA account endpoints. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| onDisabled | `() => void` | no |  | Called after 2FA was disabled. |
| onEnabled | `() => void` | no |  | Called after 2FA was successfully enabled (e.g. refresh your auth store). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ TwoFactorManager: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| qr | `Snippet<[{ uri: string; secret: string }]>` | no |  | QR-code renderer for the otpauth URI shown during setup. Receives the `otpauth://` `uri` and the Base32 `secret`. Optional: the package ships no QR encoder (zero-dep), so without this snippet only the URI and secret are shown for manual entry. |
| slotClasses | `Partial<Record<'root' | 'title' | 'section' | 'sectionTitle' | 'field' | 'submit' | 'error' | 'code' | 'backupCode', string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface AuthUser {
id: string;
  email: string;
  name: string;
  role: R;
  emailVerified: boolean;
  /**
   * Whether TOTP two-factor authentication is active on the account. A public
   * account-status flag in the same spirit as `emailVerified` — it drives the
   * `TwoFactorManager` UI and the login two-step, and never carries the secret
   * itself. `false` for every user until they finish 2FA setup, and for
   * consumers who don't wire 2FA at all (the adapter defaults a missing column
   * to `false`).
   */
  totpEnabled: boolean;
}
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

### Slots (slotClasses keys)
`root`, `title`, `section`, `sectionTitle`, `field`, `submit`, `error`, `code`, `backupCode`

---

## TypesReference
Displays expandable type definitions extracted from component source,
with inline code blocks, literal value badges, and cross-links to the API Reference.

**Import:** `import { TypesReference } from '@urbicon-ui/docs';`

### Examples
```svelte
<TypesReference
  types={componentData.types}
  title="Type Definitions"
  description="Local types used by this component."
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| types | `LocalTypeDef[]` | yes |  | Array of type definitions to display. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...TypesReferenceVariantProps | `VariantProps` | no |  | Styling variants from TypesReferenceVariantProps |
| class | `string` | no |  | Extra CSS classes merged onto the root section element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| description | `string` | no |  | Descriptive text below the title. |
| emptyState | `Snippet` | no |  | Optional snippet rendered below the table when no types match the filter. |
| id | `string` | no | 'types' | Anchor id of the rendered `<Section>`, and the stem its heading id is derived from (`{id}-title`). Keep the default on a component page: it is one half of the anchor pair `ApiReference` jumps to. A page rendering several instances gives each its own. |
| marker | `string | boolean` | no | true | Editorial marker before the heading. `true` (the default) claims the page's next section number — the same automatic numbering every other `<Section marker>` on the page uses, so inserting or removing a section renumbers this one too. A string numbers it by hand; `false` leaves it unstamped.  An instance rendered inside another section (a playground stage, a code example) never claims a number, whatever this says. |
| meta | `string` | no |  | Right-aligned counter in the section header, e.g. `"27 types"` — the same slot the API Reference section uses for its prop count. Unset by default; the toolbar above the table already states the count of what is visible. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Density of the expanded panel — code block, badges, footnotes. It does not reach the heading (that is `<Section intent="secondary">`, pinned so the types section reads as a sibling of the API Reference above it) nor the table rows (pinned to `sm`, so both reference tables on a page share one row rhythm). |
| slotClasses | `Partial<Record<TypesReferenceSlots, string>>` | no |  | Per-slot class overrides for internal elements. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. |
| title | `string` | no |  | Section heading text. There is no literal default to quote: it falls back to the localized `typesTitle` — "Types" in English, "Typen" in German. |
| unstyled | `boolean` | no | false | Strip all default tv() styles from internal slots. |

Inherited from:
- Omit<TypesReferenceVariantProps, 'size'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Types
```ts
interface TypeUsedByRef {
/** Component name owning the prop. */
  component: string;
  /** Prop name within the component. */
  propName: string;
  /** How the type is consumed. */
  source: 'direct' | 'inherited' | 'variant';
}
```

```ts
interface LocalTypeDef {
/** Type name (e.g. `ButtonProps`). */
  name: string;
  /** TypeScript construct kind. */
  type: 'interface' | 'type' | string;
  /** Raw type definition body. */
  definition: string;
  /** Human-readable documentation string. */
  documentation?: string;
  /** Classification for grouping. */
  category?: 'props' | 'variant' | 'helper' | string;
  /**
   * Where the definition lives relative to the component: `local` (its own
   * `index.ts` / variants file) or `imported` (elsewhere in the package,
   * pulled in through a type-only import).
   *
   * Was `'local' | 'external'`, which was wrong on both members: `external`
   * is a value docs-gen has never emitted, and `imported` — which it emits on
   * 575 of 967 entries — was missing. It went unnoticed because the generated
   * array was typed with a `[key: string]: unknown` index signature, under
   * which tsc never compared the two unions at all. Making the emitted type
   * precise is what brought the disagreement to the surface.
   */
  scope?: 'local' | 'imported';
  /** Props that reference this type. */
  usedByProps?: TypeUsedByRef[];
  /**
   * A `@see` value on the type declaration that the docs can navigate to —
   * an absolute URL, a route-relative path, or a bare `#fragment`.
   */
  seeAlso?: string;
  /**
   * `@see` values on the type declaration that name a sibling type or member
   * rather than a doc target (`CartesianDatum`). Rendered as literal text.
   */
  seeAlsoRefs?: string[];
}
```

### Slots (slotClasses keys)
`stack`, `expandedPanel`, `toolbar`, `filterLabel`, `codeBlock`, `documentation`, `documentationClamped`, `placeholder`, `literalValues`, `literalBadge`, `moreValues`, `usedBySection`, `usedByLink`, `seeAlsoSection`, `seeAlsoRef`, `seeAlsoLink`, `emptyText`, `highlightRing`

---

## VerifyEmailPage
Auto-verifying email confirmation page. Sends POST `{ token }` to `apiPath` (default `/api/auth/verify-email`) on mount.
Pair with `createVerifyEmailHandler(authDeps)` on the server.

**Import:** `import { VerifyEmailPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<script>
  import { page } from '$app/state';
</script>
<VerifyEmailPage {t} token={page.url.searchParams.get('token') ?? ''} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| token | `string` | yes |  | Verification token from URL query parameter. |
| apiPath | `string` | no | '/api/auth/verify-email' | API endpoint for the verify-email request. |
| class | `string` | no |  | Extra classes on the root element. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names. Only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| footer | `Snippet` | no |  | Content rendered below the form, above links. |
| header | `Snippet` | no |  | Content rendered between the heading and the form. |
| links | `Snippet` | no |  | Replaces the link area below the form. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ VerifyEmailPage: { … } }}>`. Resolves after the provider defaults and before this instance's own `slotClasses`, so a project-wide look lives in one place instead of being repeated at every usage site. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| t | `PartialAuthLocale` | no |  | Locale overrides, deep-merged over the bundle registered for the active locale — English unless `registerAuthLocale` ran for it. Pass any subset, from a single string to a whole tree. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Types
```ts
type PartialAuthLocale = DeepPartial<AuthLocale>
```

```ts
interface CsrfClientOptions {
cookieName?: string;
  headerName?: string;
  /**
   * Match the server's `csrf.useHostPrefix` — read the token from the
   * `__Host-`-prefixed cookie name. Leave `false` (default) unless the server
   * sets `useHostPrefix: true`.
   */
  useHostPrefix?: boolean;
}
```

```ts
interface AuthPageSlotClasses {
/** Outermost wrapper element. */
  root?: string;
  /** Card container around the form. */
  card?: string;
  /** Page heading (h1). */
  title?: string;
  /** Form element wrapping all fields. */
  form?: string;
  /** Individual form field (Input). */
  field?: string;
  /** Submit button. */
  submit?: string;
  /** Error alert container. */
  error?: string;
  /** Success message container. */
  success?: string;
  /** Links area below the form (e.g. "Forgot password?"). */
  links?: string;
  /** Password requirements checklist (RegisterPage, ResetPasswordPage). */
  requirements?: string;
}
```

```ts
type DeepPartial = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
```

- `interface AuthLocale` — 8 members, definition omitted (387 lines; full definition: packages/auth/src/lib/i18n/keys.ts)

---

## Design Token System

This is the COMPLETE list of available semantic tokens. Use ONLY these — do not invent token names.

### Surface Tokens (backgrounds)

```
bg-surface-base          /* L·1 — the page itself: content, cards and reading surfaces sit at this level */
bg-surface-quiet         /* L·0 — the ground beneath the page; the softest in-page tint, which alone signals "own zone" without border or shadow */
bg-surface-elevated      /* L·2 — lifted surfaces (Popover, Menu, Select dropdown), above the page with shadow and a z-index of their own */
bg-surface-overlay       /* L·3 — the highest surfaces (Dialog, Drawer, Sheet, Toast), full shadow plus backdrop dimming */
bg-surface-interactive   /* a resting FILL one step in from the page — a filled Input, a Slider track, the Tab list; its hover step is surface-interactive-hover */
bg-surface-interactive-hover /* the hover step for an element resting on surface-interactive — it continues the fill's own ladder, where surface-hover would be a no-op */
bg-surface-hover         /* the hover step for an element resting on a READING surface (base / quiet / elevated) — a menu item, a table row */
bg-surface-active        /* the pressed step for an element resting on a reading surface; the pair of surface-hover */
bg-surface-disabled      /* the fill of a disabled control */
bg-surface-selected      /* the ground of a selected item — the primary intent's tint, not a neutral step */
bg-surface-subtle        /* a RESTING tint only, never a hover step — it equals surface-elevated; prefer surface-quiet for a zone, surface-elevated for a lift */
bg-surface-inverted      /* the inverted ground (Tooltip) — near-black in light mode, near-white in dark; pairs with text-inverted */
```

### Text Tokens

```
text-text-primary        /* body copy — the top of the informative ramp (primary → secondary → tertiary); each rung clears AA 4.5:1 on every reading surface */
text-text-inverted       /* text on surface-inverted */
text-text-secondary      /* supporting text — the second rung of the informative ramp */
text-text-tertiary       /* muted text and metadata — the last rung that is still body-safe (AA on every reading surface); reach for it wherever quaternary tempts */
text-text-quaternary     /* MARK-ONLY — placeholders, dense-grid marks, disabled glyphs, decoration; never use it for body text (held only to the 3:1 UI floor) */
text-text-disabled       /* disabled text — the weakest rung, held to the 3:1 UI floor so a disabled field's label still says what the field is */
text-text-link           /* link ink on a reading surface — aliases the primary intent's -text role (its AA text step), never the base fill */
text-text-on-dark        /* the label on the avatar identity palette (one lightness per mode by construction); deliberately not aliased to text-on-fill */
text-text-on-fill        /* the label on ANY solid intent fill — white in light mode, near-black in dark mode; warning is the exception (text-on-warning) */
text-text-on-primary     /* the label on the primary fill specifically — defaults to text-on-fill; override it to repaint the primary fills alone */
text-text-on-warning     /* the label on the warning fill — a warm dark from the ramp's own 950 stop in BOTH modes, because the fill stays light amber in both */
text-text-on-surface     /* text on any surface — it tracks the page background, so never on an intent fill */
```

### Border Tokens

```
border-border-hairline   /* the quietest tier — structural dividers (row dividers, Card separators); translucent, so it blends onto any surface */
border-border-subtle     /* quiet container outlines (Popover) — one tier above hairline */
border-border-default    /* the standard border of controls and containers */
border-border-emphasis   /* an emphasised outline, one step stronger than default */
border-border-strong     /* the strongest outline the chassis offers */
```

### Intent Tokens (available for ALL intents: primary, secondary, neutral, success, warning, danger)

Each intent has 5 variants. Example with `success`:
```
bg-success               /* base intent color */
bg-success-hover         /* hover state */
bg-success-active        /* pressed state */
bg-success-subtle        /* soft background (e.g. success-50) */
bg-success-emphasis      /* strong/dark variant */
text-success-text        /* intent-colored text — the AA-clean text tier; never text-success (a fill tone) */
text-success-emphasis    /* near-ink text tier */
border-success           /* intent-colored border */
```

Same pattern for: `primary-*`, `secondary-*`, `neutral-*`, `warning-*`, `danger-*`

### Feedback Tokens (status messages)

```
bg-feedback-info            text-feedback-info            /* maps to primary */
bg-feedback-info-subtle                                   /* soft info background */
bg-feedback-success         text-feedback-success         /* maps to success */
bg-feedback-success-subtle                                /* soft success background */
bg-feedback-warning         text-feedback-warning         /* maps to warning */
bg-feedback-warning-subtle                                /* soft warning background */
bg-feedback-error           text-feedback-error           /* maps to danger */
bg-feedback-error-subtle                                  /* soft error background */
```

### DON'T invent token names — common mistakes:

```
/* WRONG — these don't exist */
text-status-danger       bg-status-warning       border-l-status-*
text-feedback-success-fg text-feedback-danger-fg

/* CORRECT equivalents */
text-danger-text         bg-warning              border-l-danger
text-feedback-success    text-feedback-error
```

### DON'T use primitive colors with dark: overrides:

```
/* WRONG */
bg-white dark:bg-neutral-900

/* CORRECT */
bg-surface-base
```

### Shadow Tokens

```
shadow-[var(--blocks-shadow-xs)]   /* minimal */
shadow-[var(--blocks-shadow-sm)]   /* buttons */
shadow-[var(--blocks-shadow-md)]   /* hover states */
shadow-[var(--blocks-shadow-lg)]   /* menus, popovers */
```

### Z-Index Tokens

```
z-[var(--z-dropdown)]  /* 1150 */
z-[var(--z-overlay)]   /* 1300 */
z-[var(--z-modal)]     /* 1400 */
z-[var(--z-popover)]   /* 1500 */
z-[var(--z-tooltip)]   /* 1800 */
```

### Duration Tokens

```
duration-[var(--blocks-duration-instant)]  /* 75ms */
duration-[var(--blocks-duration-fast)]     /* 150ms */
duration-[var(--blocks-duration-normal)]   /* 250ms */
duration-[var(--blocks-duration-slow)]     /* 350ms */
```

### Easing Tokens

```
var(--blocks-ease-confident)  /* standard transitions */
var(--blocks-ease-springy)    /* bouncy animations */
var(--blocks-ease-smooth)     /* gentle animations */
var(--blocks-ease-snappy)     /* quick, decisive */
```

### Border Radius — semantic tiers first

Shape is decided by component *family*, not per element, and the tiers rank **roles**: actions
softest, fields in between, containers tightest. A pill Button inside a hairline-edged Card is the
system working as intended. Retune a whole family at once through its token, and move the families
together so the ranking stays legible.

```
--radius-commit   9999px (pill)  Button, ButtonGroup, Badge, Toggle, SegmentGroup   rounded-commit
--radius-modify   4px            Input, Textarea, Select, Combobox, Tab, Menu item  rounded-modify
--radius-contain  2px            Card, Dialog, Drawer, Alert, Popover, Tooltip      rounded-contain
--radius-bridge   6px            small tinted content surfaces (see below)          rounded-bridge
```

```css
@theme {
  --radius-contain: var(--radius-md); /* friendlier containers, whole family at once */
}
```

`bridge` is the one sanctioned exception, and it is optical: radius scales with the area it
turns, so 2px on a 600px Card reads as a precise edge while the same 2px on a ~200px tile reads
as a plain rectangle. Small tinted surfaces are content, not architecture. Anything that
genuinely is a panel, dialog or container stays on `contain`.

### The raw radius scale

The physical steps the tiers are built from — for your own markup, not to overrule a tier.

```
rounded-xs    /* 0.125rem */    rounded-sm    /* 0.25rem */
rounded-md    /* 0.375rem */    rounded-lg    /* 0.5rem */
rounded-xl    /* 0.75rem */     rounded-2xl   /* 1rem */
rounded-3xl   /* 1.5rem */      rounded-4xl   /* 2rem */
```

---

## Design Quality

These guidelines help you create interfaces with genuine visual identity. They are framed as
"AVOID → INSTEAD" patterns because knowing what NOT to do is more effective than abstract principles.

### Vary Visual Weight

Don't give every element the same visual importance. Vary `variant`, `padding`, and grid span to reflect content hierarchy.

```
/* AVOID — uniform grid, all cards identical */
<div class="grid grid-cols-4 gap-4">
  <Card variant="elevated" padding="md">Metric A</Card>
  <Card variant="elevated" padding="md">Metric B</Card>
  <Card variant="elevated" padding="md">Metric C</Card>
  <Card variant="elevated" padding="md">Metric D</Card>
</div>

/* INSTEAD — weight reflects importance */
<div class="grid grid-cols-4 gap-4">
  <Card variant="elevated" padding="lg" class="col-span-2">Hero metric</Card>
  <Card variant="outlined" padding="md">Secondary</Card>
  <Card variant="outlined" padding="md">Secondary</Card>
</div>
```

### Color = Meaning, Not Decoration

Neutral surfaces should dominate (80–90%). Use `intent` and semantic color tokens ONLY for
their semantic meaning — status, severity, actions — never as visual flair.

```
/* AVOID — color without purpose */
<Card class="bg-primary-subtle">             <!-- why primary? -->
<Badge intent="primary">Active</Badge>       <!-- "Active" isn't a primary action -->

/* INSTEAD — color communicates state */
<Card variant="elevated">                    <!-- neutral default -->
<Badge intent="success" variant="soft">Healthy</Badge>   <!-- green = healthy -->
<Badge intent="danger" variant="filled">Critical</Badge>  <!-- red = critical -->
```

An intent says *how severe*, not *which kind*. Workflow stages, types, priorities and owners are
**categories** and carry no severity — mapping them onto intents makes the page shout about a
problem that does not exist:

```
/* AVOID — a stage painted as a severity */
<Badge purpose="status" intent="warning">Roasting</Badge>   <!-- nothing is wrong -->
<Badge purpose="status" intent="info">Normal priority</Badge>

/* INSTEAD — a category is a tag; the chart ramp when several must be told apart */
<Badge purpose="tag" intent="neutral">Roasting</Badge>
<span class="bg-chart-1 size-2 rounded-commit"></span>  <!-- series position, not meaning -->
```

### Spacing Signals Relationships

Don't use the same gap everywhere. Tight spacing groups related items; generous spacing
separates distinct sections. The two-tier rhythm (`gap-8`/`gap-10` between, `gap-4`/`gap-6`
within) is the **floor, not the ceiling**: let the rhythm follow the content, so a warning that
belongs to the metric above it sits closer than the next section does, and `padding` varies with
a card's density (`lg` for the one carrying the page, `md`/`sm` for the reference blocks).

```
/* AVOID — uniform spacing */
<div class="space-y-4">
  <section>...</section>    <!-- same gap between sections -->
  <section>...</section>
</div>

/* INSTEAD — spacing hierarchy */
<div class="space-y-10">                      <!-- generous between sections -->
  <section class="space-y-3">...</section>    <!-- tight within sections -->
  <section class="space-y-3">...</section>
</div>
```

### Commit to a Shape Language

Choose a shape philosophy and apply it **at the tier**, so a whole component family moves at
once (see "Border Radius — semantic tiers first" above for the tokens):

| Strategy | Tokens | Personality |
|----------|--------|-------------|
| Sharp | `--radius-contain: 0` · `--radius-modify: 0` · `--radius-commit: var(--radius-sm)` | Technical precision, data-dense |
| Soft *(default)* | library defaults: 2px containers, 4px fields, pill actions | Professional, precise |
| Round | `--radius-contain: var(--radius-xl)` · `--radius-modify: var(--radius-lg)` · `--radius-commit: 9999px` | Friendly, modern |

Move the families **together** so the ranking stays legible. The defect to avoid is not "inner
rounder than outer" — in this system it usually is, by design — but values with no stateable rule:
one family retuned while the others keep numbers that no longer relate to it.

```css
/* app-theme.css — one decision, every component of the family follows */
@theme {
  --radius-contain: var(--radius-xl);
  --radius-modify: var(--radius-lg);
}
```

**Do not** reach for `<Card class="rounded-2xl">`: that rounds one element out of its family
while Dialog, Alert and Popover stay behind, and it is the shape defect judges name most often.
For a project-wide treatment of one component use `BlocksProvider` `defaults`; for a surface
that is genuinely too small for the container radius, use the tier that exists for it
(`<Card tier="bridge">`).

### Data-Driven Styling

Let the data shape the presentation. Different states, severities, or categories should look
visually distinct — not just carry a different label.

```
/* AVOID — identical rows regardless of content */
{#each alerts as alert}
  <div class="py-3 border-b border-border-subtle">
    <Badge>{alert.severity}</Badge> {alert.message}
  </div>
{/each}

/* INSTEAD — severity drives visual weight */
{#each alerts as alert}
  {@const critical = alert.severity === 'critical'}
  <div class="border-b border-border-subtle {critical ? 'py-4 font-medium' : 'py-2.5'}">
    <Badge intent={severityIntent(alert.severity)}
           variant={critical ? 'filled' : 'soft'}>
      {alert.severity}
    </Badge>
    <span class={critical ? 'text-text-primary' : 'text-text-secondary'}>
      {alert.message}
    </span>
  </div>
{/each}
```

### Don't Copy, Compose

Recipes and examples show ONE possible interpretation. Use them for API understanding,
not as visual templates. Your implementation should:

- Vary Card `variant` across the page based on content importance (not all `elevated`)
- Use different density (padding, gap, text size) for different page sections
- Make one element per section clearly dominant — if everything is emphasized, nothing is
- Use `text-text-secondary` and `text-text-tertiary` generously to push supporting content back
- Choose your OWN spacing rhythm, radius strategy, and color distribution

---

## Customization

Four levels of customization, from simple color swaps to fully custom designs.
**Pick the lowest level that solves your problem** — lower levels preserve more of the
design system's behavior (dark mode, hover/active cascade, focus rings).

### Level 1: CSS Token Themes

Import a theme CSS file after base styles to override the color palette:
```css
@import '@urbicon-ui/blocks/style/index.css';
@import '@urbicon-ui/blocks/style/themes/ocean.css';
```

Built-in themes: `ocean.css`, `forest.css`, `sunset.css`, `rose.css`, `neutral.css`.

Create custom themes with a `@theme` block:
```css
@theme {
  --color-primary-50: oklch(0.95 0.03 YOUR_HUE);
  --color-primary-500: oklch(0.58 0.13 YOUR_HUE);
  --color-primary-900: oklch(0.26 0.06 YOUR_HUE);
  /* ... full 50–950 scale */
}
```

### Level 2: Presets – Named Project-Defined Styles

**Use this when the built-in `intent` palette doesn't fit.** Presets are named, reusable
`slotClasses` bundles you register once at the app root, then apply per component via
a `preset="…"` prop. They are the **preferred alternative** to ad-hoc `class="bg-…!"`
overrides at call sites.

Register once at the app root:
```svelte
<script>
  import { BlocksProvider } from '@urbicon-ui/blocks';
</script>

<BlocksProvider
  presets={{
    Button: {
      overlay: {
        slotClasses: {
          base: 'bg-black/20 hover:bg-black/30 active:bg-black/40 text-white border-transparent'
        }
      },
      brand: {
        slotClasses: {
          base: 'bg-[#FF5A1F] hover:bg-[#E04C15] active:bg-[#C53F0D] text-white border-transparent'
        }
      }
    },
    Card: {
      glass: {
        slotClasses: {
          base: 'bg-white/10 backdrop-blur-xl border-white/20'
        }
      }
    }
  }}
>
  <slot />
</BlocksProvider>
```

Then use across the project:
```svelte
<Button preset="overlay">Reinholen</Button>
<Button preset="brand">Jetzt kaufen</Button>
<Card preset="glass">Heads-up display</Card>
```

**Why presets over inline `class` overrides?**

```svelte
<!-- ❌ AVOID: Defeats hover/active cascade, leaks decisions into every call site,
     requires `!` to out-specify tv() defaults, inconsistent across the project. -->
<Button intent="primary" class="bg-black/20! hover:bg-black/30! active:bg-black/40!">
  Reinholen
</Button>

<!-- ✅ PREFER: Intent-less, cohesive cascade, reusable across the codebase. -->
<Button preset="overlay">Reinholen</Button>
```

When defining a preset, specify **all interactive states explicitly** (`hover:`, `active:`,
and `focus-visible:` where applicable). The preset's `slotClasses.base` is merged *after*
the `tv()` defaults, so conflicting Tailwind utilities are resolved by the built-in bucket
conflict resolver (last source wins) — no `!` needed.

An unknown preset name emits a dev-only console warning, so typos are discoverable.

### Level 3: BlocksProvider – Global Component Defaults

Use `defaults` (distinct from `presets`) to set **project-wide baseline styles** that
apply to *every* instance of a component — e.g. "all Buttons should be rounded-full in this app":

```svelte
<BlocksProvider
  defaults={{
    Button: { slotClasses: { base: 'rounded-full font-bold uppercase' } },
    Card: { slotClasses: { base: 'rounded-3xl shadow-2xl' } },
    Input: { slotClasses: { base: 'rounded-full' } }
  }}
>
  <slot />
</BlocksProvider>
```

`defaults` vs. `presets` vs. `overrides` — when to use which:
- **`defaults.slotClasses`**: blanket project style applied to every instance (no opt-in required)
- **`presets`**: named alternative look, opt-in via `preset="…"` prop at the call site
- **`defaults.overrides` / `presets[…].overrides`**: prop-conditional rules targeting only a specific
  variant/intent/state (e.g. only `variant="outlined"`) — what unconditional `slotClasses` cannot express

```svelte
<!-- Only outlined badges get a 1px border; the conflict resolver strips the variant's border-2. -->
<BlocksProvider defaults={{ Badge: { overrides: [{ variant: 'outlined', class: { base: 'border' } }] } }}>
  <slot />
</BlocksProvider>
```

Each `overrides` entry is a `compoundVariant`-shaped matcher (`string` = equals, `string[]` = one-of →
per-slot `class`); it matches active prop *values*, so it works regardless of whether the library
defines the conflicting class in a `variant` or a `compoundVariant`.

The library's own `tv()` variant styles sit below every rung a consumer writes, and `preset.*` in
the chain reads `presets[Component][name].*` — the entry the instance's `preset` prop selects.
Cascade (conflict-resolved per Tailwind bucket, later wins): `defaults.slotClasses → defaults.overrides[match] → preset.slotClasses → preset.overrides[match] → instance slotClasses → instance class`.

### Level 4: Global Unstyled Mode

Strip all default styles from every component, then apply your own:
```svelte
<BlocksProvider unstyled defaults={{
  Button: { slotClasses: { base: 'inline-flex items-center border-2 px-6 py-3 font-mono' } }
}}>
  <slot />
</BlocksProvider>
```

---

## Style Patterns

Urbicon UI components are designed to be radically reskinned. Do NOT default to the standard
look from examples — choose a visual style that fits the project's identity. Every component
supports `unstyled` (strips all defaults) and `slotClasses` (targeted sub-element overrides).

### Slot Reference

| Component | Slots |
|-----------|-------|
| Button | `base`, `content`, `spinner` |
| Card | `base`, `header`, `content`, `footer` |
| Input | `wrapper`, `container`, `base`, `label`, `message`, `iconContainer` |
| Badge | `base`, `content`, `removeButton`, `removeIcon` |
| Dialog | `base`, `overlay`, `header`, `body`, `footer` |
| Alert | `base`, `icon`, `content`, `title`, `description`, `actions` |
| Tooltip | `base`, `arrow` |

### Pattern: Glassmorphism

```svelte
<BlocksProvider defaults={{
  Card: {
    slotClasses: {
      base: 'bg-white/10 backdrop-blur-xl border border-white/20 shadow-2xl rounded-2xl'
    }
  },
  Button: {
    slotClasses: {
      base: 'bg-white/15 backdrop-blur-md border border-white/25 hover:bg-white/25 rounded-xl text-white shadow-lg'
    }
  },
  Input: {
    slotClasses: {
      base: 'bg-white/10 backdrop-blur-sm border-white/20 text-white placeholder:text-white/50 rounded-xl',
      label: 'text-white/80'
    }
  }
}}>
```

Combine with a gradient or image background on the page container.

### Pattern: Brutalist / Raw

```svelte
<BlocksProvider unstyled defaults={{
  Card: {
    slotClasses: {
      base: 'border-4 border-black bg-white p-0 shadow-[8px_8px_0_black]'
    }
  },
  Button: {
    slotClasses: {
      base: 'border-3 border-black bg-yellow-300 px-6 py-3 font-black uppercase tracking-widest hover:bg-black hover:text-yellow-300 active:translate-x-1 active:translate-y-1 active:shadow-none shadow-[4px_4px_0_black]'
    }
  },
  Input: {
    slotClasses: {
      base: 'border-3 border-black bg-white font-mono text-lg',
      label: 'font-black uppercase tracking-widest text-xs'
    }
  },
  Badge: {
    slotClasses: {
      base: 'border-2 border-black bg-lime-400 font-black uppercase text-black rotate-[-2deg]'
    }
  }
}}>
```

### Pattern: Terminal / Hacker

```svelte
<BlocksProvider unstyled defaults={{
  Card: {
    slotClasses: {
      base: 'border border-green-500/30 bg-black/90 font-mono text-green-400 rounded-none'
    }
  },
  Button: {
    slotClasses: {
      base: 'border border-green-500/50 bg-green-500/10 font-mono text-green-400 rounded-none hover:bg-green-500/20 hover:text-green-300 px-4 py-2 uppercase tracking-wider text-xs'
    }
  },
  Input: {
    slotClasses: {
      base: 'border border-green-500/30 bg-black font-mono text-green-400 rounded-none caret-green-400 placeholder:text-green-800',
      label: 'font-mono text-green-600 uppercase text-[10px] tracking-[0.2em]'
    }
  },
  Badge: {
    slotClasses: {
      base: 'border border-green-500/40 bg-green-500/10 font-mono text-green-400 text-[10px] uppercase rounded-none'
    }
  }
}}>
```

### Pattern: Soft / Organic

```svelte
<BlocksProvider defaults={{
  Card: {
    slotClasses: {
      base: 'rounded-[2rem] bg-amber-50 border-0 shadow-sm'
    }
  },
  Button: {
    slotClasses: {
      base: 'rounded-full bg-stone-800 text-amber-50 hover:bg-stone-700 px-8 font-light tracking-wide border-0 shadow-none'
    }
  },
  Input: {
    slotClasses: {
      base: 'rounded-2xl border-stone-200 bg-stone-50 font-light',
      label: 'font-light text-stone-500'
    }
  }
}}>
```

### Override Interaction Tokens

Change the feel of all components at once:
```css
:root {
  --blocks-ease-confident: cubic-bezier(0.22, 1, 0.36, 1);
  --blocks-duration-normal: 300ms;
  --blocks-mint-scale-intensity: 1.02; /* tone down the scale mint (1 disables it visually) */
  --blocks-focus-ring-width: 3px;
  --blocks-focus-ring-color: oklch(0.7 0.15 var(--primary-hue, 240));
}
```

### Per-Instance Override

For one-off customizations without changing the global style:
```svelte
<Card unstyled slotClasses={{ base: 'my-custom-card-class', header: 'my-header' }}>
  ...
</Card>

<Button class="rounded-full px-12 tracking-widest uppercase">
  Custom Button
</Button>
```

`class` merges with defaults; `unstyled` + `slotClasses` replaces them entirely.

---

## Callback Naming Convention

Native DOM events: lowercase (`onclick`, `onfocus`)
Custom state callbacks: `on` + PascalCase (`onCheckedChange`, `onValueChange`, `onPageChange`)

Always pass the NEW STATE VALUE, not the raw event:
```svelte
<Checkbox onCheckedChange={(checked) => ...} />
<Menu onValueChange={(value) => ...} />
<Pagination onPageChange={(page) => ...} />
```

---

## i18n Integration

```svelte
<script>
  import { T, LocaleSwitcher } from '@urbicon-ui/blocks';
</script>

<T key="blocks.button.loading" />
<LocaleSwitcher />
```

Supported locales: `en`, `de`. Components auto-translate their internal text.

---

## Common Patterns

### Form with validation
```svelte
<form onsubmit={handleSubmit}>
  <Input label="Email" type="email" bind:value={email} error={errors.email} required />
  <Input label="Password" type="password" bind:value={password} error={errors.password} required />
  <Checkbox label="Remember me" bind:checked={remember} />
  <Button intent="primary" type="submit" loading={submitting}>Sign In</Button>
</form>
```

### Confirmation dialog
```svelte
<Dialog bind:open={showConfirm} title="Delete Item?" intent="danger" size="sm">
  <p>This action cannot be undone.</p>
  {#snippet footer()}
    <Button variant="ghost" onclick={() => showConfirm = false}>Cancel</Button>
    <Button intent="danger" onclick={handleDelete} loading={deleting}>Delete</Button>
  {/snippet}
</Dialog>
```

### Data display card
```svelte
<Card variant="outlined" padding="lg">
  {#snippet header()}
    <div class="flex items-center justify-between">
      <h3 class="text-text-primary font-semibold">Revenue</h3>
      <Badge intent="success" variant="soft">+12%</Badge>
    </div>
  {/snippet}
  <p class="text-3xl font-bold text-text-primary">$48,200</p>
  <p class="text-text-tertiary text-sm">vs. $43,000 last month</p>
</Card>
```

### Navigation tabs
```svelte
<Tab
  tabs={[
    { label: 'Overview', value: 'overview' },
    { label: 'Analytics', value: 'analytics' },
    { label: 'Settings', value: 'settings', disabled: true }
  ]}
  bind:value={activeTab}
  variant="pills"
/>

{#if activeTab === 'overview'}
  <OverviewPanel />
{:else if activeTab === 'analytics'}
  <AnalyticsPanel />
{/if}
```

### Menu with custom items
```svelte
<Menu
  items={users}
  getItemLabel={(u) => u.name}
  getItemValue={(u) => u.id}
  placeholder="Assign to..."
  bind:value={assignee}
>
  {#snippet customItem(user, isSelected, toggle)}
    <div class="flex items-center gap-2 p-2" onclick={toggle}>
      <Avatar name={user.name} size="xs" />
      <span>{user.name}</span>
    </div>
  {/snippet}
</Menu>
```

### Loading skeleton
```svelte
{#if loading}
  <div class="flex items-center gap-3">
    <Skeleton variant="circular" size="md" />
    <div class="flex-1 flex flex-col gap-2">
      <Skeleton variant="text" size="sm" />
      <Skeleton variant="text" size="xs" class="w-2/3" />
    </div>
  </div>
{:else}
  <UserCard {user} />
{/if}
```

### Breadcrumb navigation
```svelte
<Breadcrumb items={[
  { label: 'Dashboard', href: '/dashboard' },
  { label: 'Settings', href: '/dashboard/settings' },
  { label: 'Profile' }
]} size="sm" />
```

---

## Auth Reference

The complete `@urbicon-ui/auth` reference — architecture, staged consumer setup,
federation (SSO), the adapter contract, the error contract, and the known
limitations & production-readiness checklist. Extracted at build time from the
package's canonical, tarball-shipped `docs/AUTH.md` (one source, all channels —
see docs/DOCS-SURFACES.md); the same document renders at
https://ui.urbicon.de/auth/guide.

Zero-dependency authentication, user management, and notification system for SvelteKit. Part of the Urbicon UI monorepo.

### Architecture

```
@urbicon-ui/auth
├── Server (import from '@urbicon-ui/auth/server')
│   ├── Core: JWT (HS256 default, ES256 opt-in + JWKS), PBKDF2 password hashing, CSRF, rate-limiting, security headers
│   ├── Handlers: login, logout, register, forgot-password, reset-password, verify-email, me
│   ├── Handle-Hook: createAuthHandle() — session hydration, route guard, CSRF, headers
│   ├── Passkeys: WebAuthn registration + authentication (CBOR, ECDSA P-256, RSA verification)
│   ├── Federation (SSO): createJWKSHandler (IdP side) + createFederatedAuthHandle (consumer side)
│   ├── Notifications: SSE manager, push service (RFC 8291/8292), event registry, dispatch
│   ├── Email: Transport interface + Lettermint adapter + console logger
│   └── Adapters: Repository interfaces + Prisma + in-memory adapters + conformance suite
│
├── Client (import from '@urbicon-ui/auth')
│   ├── Stores: createAuthStore(), createNotificationStore() — Svelte 5 Runes
│   ├── 14 UI Components: blocks-based, unstyled/slotClasses, snippet overrides
│   │   └── fetching components accept `fetcher` (DI for fetch — mocks in demos/tests,
│   │       custom retry/auth layers; default: global fetch)
│   └── Utils: service worker registration, push subscription
│
├── i18n (built in: EN — registerAuthLocale() adds any other)
│   └── EN + DE bundles ship ('@urbicon-ui/auth/i18n/en' | '/de'); any Locale is registrable
│
└── SW (import from '@urbicon-ui/auth/sw')
    └── handlePushEvent, handleNotificationClick
```

### Zero-Dependency Design

All crypto is implemented via Web Crypto API (`crypto.subtle`):

| Feature          | Implementation                                           | Standards               |
| ---------------- | -------------------------------------------------------- | ----------------------- |
| Password hashing | PBKDF2 (600k iterations, SHA-256)                        | —                       |
| JWT sessions     | HMAC-SHA256 (HS256, default; timing-safe comparison) or ECDSA P-256 (ES256, `createJWKSHandler` serves the JWKS) | RFC 7515, 7517, 7638    |
| Web Push         | ECDH + HKDF + AES-128-GCM                                | RFC 8291, 8292, 8188    |
| Passkeys         | CBOR decoder, ECDSA/RSA verification                     | WebAuthn Level 2, FIDO2 |
| Token hashing    | SHA-256                                                  | —                       |
| bcrypt migration | Dual-verify (detects `$2b$` prefix, re-hashes to PBKDF2) | —                       |

#### Runtime requirements

Zero **dependencies**, but the server runtime must provide a couple of platform
globals:

- **Web Crypto** — `globalThis.crypto` with `crypto.subtle` + `getRandomValues`
  backs every crypto path above. Global since Node 20, always present in Bun,
  Deno and edge runtimes.
- **Node `Buffer`** — password hashing (PBKDF2 hex encoding) and the TOTP secret
  cipher (base64) use `Buffer`. Password hashing is on the login/register path,
  so in practice this makes the package **Node ≥ 20 or Bun** (both ship `Buffer`
  globally); the Prisma adapter is Node/Bun-only regardless.

**Bottom line: target Node.js ≥ 20 or Bun.** Edge/Workers/Deno-deploy need a
Node-compatibility layer that polyfills `Buffer` (e.g. Cloudflare's
`nodejs_compat`); the Web Crypto paths themselves are edge-clean.

### Package Exports

| Export                                         | Condition           | Content                                                     |
| ---------------------------------------------- | ------------------- | ----------------------------------------------------------- |
| `@urbicon-ui/auth`                             | Client + types      | Stores, components, types                                   |
| `@urbicon-ui/auth/server`                      | Server only         | Handlers, auth core, adapters                               |
| `@urbicon-ui/auth/server/adapters/prisma`      | Server only         | Prisma adapter factory (`createPrismaRepos`)                |
| `@urbicon-ui/auth/server/adapters/in-memory`   | Server only         | In-memory adapter (`createInMemoryRepos`, per-repository factories on a `createInMemoryStore()`) — dev/test |
| `@urbicon-ui/auth/server/adapters/conformance-core` | Server (tests) | The suite without a runner import — pass your own `describe`/`it`/`expect` (bun:test as-is; jest needs `expect: (a) => expect(a)`) |
| `@urbicon-ui/auth/server/adapters/conformance` | Server only (tests) | Adapter conformance suite (`describeRepositoryConformance`) |
| `@urbicon-ui/auth/server/email/lettermint`     | Server only         | Lettermint email transport                                  |
| `@urbicon-ui/auth/server/email/console`        | Server only         | Console email transport (dev)                               |
| `@urbicon-ui/auth/sw`                          | Service Worker      | Push + notification click handlers                          |
| `@urbicon-ui/auth/i18n/en`                     | Universal           | English locale — the built-in bundle; import it for a parity test or as the base of a hand-built one |
| `@urbicon-ui/auth/i18n/de`                     | Universal           | German locale — reaches the components only after `registerAuthLocale('de', de)` ([Locales](#locales)) |

### UI Components

All components use `@urbicon-ui/blocks` primitives and support:

- **`t`** — locale overrides as `PartialAuthLocale`: any subset, deep-merged by
  `mergeAuthLocale` (both root-exported) over the bundle registered for the
  `<I18nProvider>` locale — English unless `registerAuthLocale` was called for that
  locale, see [Locales](#locales). Overriding one string never blanks the rest; a
  hand-rolled bundle missing newer keys resolves them from the base. `AuthLocale`
  itself is fully required — no per-key fallback literals in markup.
- **`unstyled`** — strips *every* default class, including inner wrappers and list-item
  internals; structural state that only styling used to carry is exposed as data
  attributes instead (`data-met` on RegisterPage requirement rows, `data-unread` on
  NotificationCenter items). Functionality never disappears with the flag. Set it on the
  prop or on `<BlocksProvider unstyled>` — a provider-wide flag reaches these components
  too. **Changed:** it used to strip only the blocks primitives inside them, leaving the
  auth components' own classes in place; a project relying on that half-stripped state
  now gets the whole thing.
- **`slotClasses`** — per-slot class overrides (e.g. `root`, `card`, `form`, `field`)
- **`preset`** — a named look registered on `<BlocksProvider presets={{ LoginPage: { … } }}>`,
  resolved after the provider's `defaults` and before this instance's `slotClasses`. Reach for it
  when the same override would otherwise be repeated at every usage site. `NotificationListener`
  is the one component without any of the three — it renders no markup.
- **Snippet overrides** — `header`/`footer`/`links` on all five pages, `item`
  (NotificationCenter), `qr` (TwoFactorManager)
- **Semantic design tokens** — `text-text-primary`, `bg-surface-quiet`, etc. The tokens
  come from the consumer's blocks stylesheet; this package's own
  `@urbicon-ui/auth/style/index.css` adds only the Tailwind `@source` for its components.
- The five pages share one internal skeleton (`_shared/AuthPageShell.svelte`: wrapper →
  Card → h1 → outcome regions); the regions themselves are
  `_shared/FormErrorAlert.svelte`, the one place a request outcome (error or success)
  becomes markup — every component reports into it, AccountSettings once per form.
  It renders two live regions, both always mounted: an assertive `role="alert"` for the
  error and a polite `role="status"` for the success and for pending content. Neither is
  a public export.

| Component            | Purpose                                     |
| -------------------- | ------------------------------------------- |
| LoginPage            | Login form with optional passkey button     |
| RegisterPage         | Registration form (invitation-gated)        |
| ForgotPasswordPage   | Password reset request                      |
| ResetPasswordPage    | Password reset with confirmation            |
| VerifyEmailPage      | Auto-verifying email confirmation           |
| InvitationManager    | Admin invitation management                 |
| PasskeyManager       | WebAuthn credential management              |
| AccountSettings      | Change name/email/password + delete account |
| SessionManager       | List active sessions + sign out devices     |
| TwoFactorManager     | Enrol/disable TOTP 2FA + show backup codes  |
| NotificationCenter   | Notification list with read/delete          |
| NotificationBadge    | Unread count badge                          |
| NotificationListener | Headless SSE listener                       |
| PushPermissionPrompt | Push notification opt-in                    |

#### Client stores

`createAuthStore` / `createNotificationStore` are the headless counterparts for
consumers building their own UI. They ride the same
infrastructure as the components: a `fetcher` config option (mock backends,
retry layers), the tolerant `postJson`/`getJson` request core, and the wire
contract instead of hardcoded English — a failed auth action returns
`{ success: false, error?, code? }` (server prose + machine code; localize via
`errorMessageFromCode(code, t, error)`), a request that never reached the
server synthesizes `code: 'network_error'`. The notification store records the
same shape on `lastError` (cleared by the next success), returns `false` from
failed operations instead of silently no-opping, and a failed `load` keeps the
existing list rather than blanking it into a fake empty inbox. `logout` clears
the local state unconditionally but still reports whether the server revoked
the session (threading the failure body's wire contract; what that call ends
server-side, and what it leaves alive, is [Logout](#logout)). `checkStatus`
distinguishes "signed out" from "could not ask": a 200 or the me-contract's
`401 { user: null }` resolves the user and reports success, while a transport
failure or non-contract error leaves the current user untouched and reports
the failure — a route guard can retry instead of bouncing a signed-in user
over a transient blip.

#### Password policy

`config.password` is the only definition of what a password must satisfy. The
server measures against it (`validatePasswordStrength`), and
`createPasswordPolicyHandler(deps)` publishes it so `<RegisterPage>`,
`<ResetPasswordPage>` and `<AccountSettings>` gate against the same rules
instead of a hand-kept copy in component props:

```ts
// src/routes/api/auth/password-policy/+server.ts
export const GET = createPasswordPolicyHandler(authDeps).GET;
```

The three components read it from `policyPath` (default
`/api/auth/password-policy`) on mount. Without the route they fall back to
`DEFAULT_PASSWORD_POLICY` — min 8, no character classes, i.e. what an
unconfigured server enforces — and warn in dev. When your route already loads
the policy, pass it in as `passwordPolicy` (`resolvePasswordPolicy(config.password)`
in a `+page.server.ts`) and no request is made.

**A refusal is localized even when the client gated on the wrong policy.** The
three handlers that take a new password answer a rule failure with the English
prose *and* the refusal in machine form:

```json
{ "error": "Password must be at least 12 characters", "code": "validation_error",
  "errors": ["Password must be at least 12 characters"],
  "rules": ["minLength"],
  "passwordPolicy": { "minLength": 12, "requireUppercase": false, … } }
```

`errorMessageFromCode` prefers the server prose for `validation_error` (it
names the field), so without `rules` a German user reads the English sentence
whenever the form measured against a different policy — the exact string this
work exists to remove. The shipped forms read `rules` first, render their own
labels for them, and **adopt** `passwordPolicy`, so the next attempt is gated on
the rules the checklist now shows instead of failing the same way again. A
consumer without i18n sees `error`/`errors` unchanged.

The **endpoint's** response is a five-field projection (`minLength`,
`requireUppercase`, `requireLowercase`, `requireDigit`, `requireSpecial`) and
nothing else — in particular never `pbkdf2Iterations`. It is unauthenticated on
purpose: registration and password reset are signed-out flows, and one failed
submit already spells the policy out ("Password must be at least 12
characters").

The checklist renders from the first paint rather than from the first
keystroke, and the password field points at it with `aria-describedby`: a
description added to an already-focused field is not reliably re-announced, and
there is deliberately no live region (it would fire on every keystroke). Set
`showRequirements={false}` to drop both — a refused password still names the
rules it missed, so the reason stays reachable.

#### Locales

**Only English is built in.** Every other locale is one import plus one
registration, so an English-only app never carries the German bundle:


```ts
// src/lib/locales.ts
import { registerAuthLocale } from '@urbicon-ui/auth';
import { de } from '@urbicon-ui/auth/i18n/de';

registerAuthLocale('de', de);
```

Import that module from **both** sides of the render:

```ts
// src/hooks.server.ts — the mail builders resolve `email.locale` while handling
// the first request, so the bundle has to be there before it arrives.
import '$lib/locales';

// src/routes/+layout.ts — evaluated in the browser as well as on the server, so
// the hydrating client resolves the same bundle the SSR HTML was rendered from.
import '$lib/locales';
```

Registering on one side only is the failure worth naming: German server HTML
hydrating into English text, or the reverse.

**App start is the recommendation, not a requirement.** The registry is
reactive, so a bundle registered later — after a locale switch, out of a lazily
loaded module — re-renders the auth components already on screen. What app start
buys is that the very first server render is already correct, which is what
removes the hydration mismatch above.

The registry is module-global and holds static, request-identical data, so one
registration at server start serves every concurrent request; the request-scoped
part (the locale that is active) stays in `<I18nProvider>`'s context, where
`useAuthLocale` reads it. `registerAuthLocale` takes any locale
`@urbicon-ui/i18n` supports (its `SUPPORTED_LOCALES`), not only the two that
ship a bundle — pass your own full `AuthLocale` for the rest.

It is write-strict, because a bundle that is wrong here is wrong for every
component at once: it throws on an unsupported locale, on a non-object bundle,
and on a bundle missing any key the built-in English one has. So registering
`en` **replaces** rather than merges — that is how you override the whole
surface at once instead of passing `t` at every usage site — and the override is
built from the shipped bundle:


```ts
import { mergeAuthLocale, registerAuthLocale } from '@urbicon-ui/auth';
import { en } from '@urbicon-ui/auth/i18n/en';

registerAuthLocale('en', mergeAuthLocale(en, { auth: { login: { title: 'Welcome back' } } }));
```

The same guard reaches a hand-built bundle at upgrade time: one that was complete
against an older `AuthLocale` throws as soon as a release adds a key — at module
evaluation, which for the `hooks.server.ts` import above is server boot. This is
the opposite of what the `t` prop does with a stale bundle (it fills the gaps from
the base), and deliberately so: a registered bundle is the base. Build yours with
`mergeAuthLocale(en, yours)` and it stays complete across upgrades.

A locale with no registered bundle resolves to English. The components do that
silently; `config.email.locale` naming one warns **once per locale** through
`config.logger`, because a locale configured for the mails is a stated intent
rather than a default — but it still sends, in English: a wiring slip must not
block a password-reset mail.

#### Breaking in 8.24.0

**A locale other than `en` now has to be registered.** The package used to
import both shipped bundles and choose between them at runtime, so every auth
component carried both languages; only `en` is statically imported now. Measured
with `bun run size --package auth`, `NotificationBadge` goes from 20.5 KB gz to
17.6 KB, and every other component that renders a string drops by the same
~2.9 KB gz.

**Affected:** apps rendering auth components under `<I18nProvider locale="de">`,
and apps sending the default transactional mails with `email.locale: 'de'`.
Nothing throws — both render and send **English** until the registration is
added, and the mail path warns once per locale through `config.logger`.


```ts
// src/lib/locales.ts — the three lines that bring German back
import { registerAuthLocale } from '@urbicon-ui/auth';
import { de } from '@urbicon-ui/auth/i18n/de';

registerAuthLocale('de', de);
```

Import that module from `src/hooks.server.ts` **and** from the root
`src/routes/+layout.ts` — [Locales](#locales) says why both. Nothing else moves:
`t`, `mergeAuthLocale`, `useAuthLocale`, `AuthLocale` and the
`@urbicon-ui/auth/i18n/*` subpaths are unchanged, and an English-only app needs
no edit at all.

#### Breaking in 8.21.0

**`AuthDeps.email` is optional.** The field went from `email: EmailTransport` to
`email?: EmailTransport`, so an app that mounts no mailing route no longer has to
invent a transport it never uses. Passing one is unchanged, and no factory that
worked before stops working: `createRegisterHandler`,
`createForgotPasswordHandler` and `createChangeEmailHandler` now say so at wiring
time when it is missing, which a bundle that carries a transport never reaches.

What breaks is the **reading** side, and only there: `deps.email` is now
`EmailTransport | undefined`, so a consumer's own handler that calls
`deps.email.send(…)` off the bundle stops compiling. Narrow it once, the way the
package's own handlers do —

```ts
import type { AuthDeps } from '@urbicon-ui/auth/server';

export function createOrderMailer(deps: AuthDeps) {
  const transport = deps.email;
  if (!transport) throw new Error('createOrderMailer: deps.email is required');
  return async (to: string) => transport.send({ to, subject: 'Ordered', html: '…' });
}
```

— or keep a reference to the transport you handed `createAuthDeps` and use that
instead of reading it back off the bundle.

**Every outcome now sits in exactly one live region, and successes are polite.**
`_shared/FormErrorAlert.svelte` — the single place a request outcome becomes
markup, reached by every page, every manager, and each of AccountSettings' four
forms — used to wrap blocks' `<Alert>` (which then rendered `role="alert"` at
every intent) in a `<div aria-live="polite">`. That is a live region inside a
live region: the same text carried two urgencies at once — `role="alert"` is
implicitly `aria-live="assertive"`, the wrapper was explicitly polite — with
nothing in ARIA saying which one wins. It also made every success as urgent as
every failure.

It now renders two sibling regions, both mounted from the first paint and empty
until something happens:

```html
<div>
  <div role="alert"><!-- the error, when there is one --></div>
  <div role="status"><!-- the success, or the pending content --></div>
</div>
```

The `<Alert>` inside carries no role of its own, so the message is announced
once, by the region that was already there when it arrived.

**What a consumer's test or selector has to do now.** A query for
`[aria-live="polite"]` matches nothing; the two regions are `[role="alert"]` and
`[role="status"]`. Neither is a presence test any more: both are in the DOM from
the first paint whether or not there is anything in them, `<AccountSettings>`
renders four of each (one pair per form), and `role="status"` is also what every
`Spinner` carries, so a loading manager has one more. So `getByRole('alert')` no
longer means "an error is shown" and `getByRole('status')` never did mean "a
success is shown".

Query the region and read its text, scoped to the form or panel you mean:

```ts
const region = (form: HTMLElement) => form.querySelector('[role="alert"]') as HTMLElement;
expect(region(profileForm).textContent).toContain('Current password is incorrect.');
expect(region(emailForm).textContent?.trim()).toBe(''); // the other forms stay quiet
```

A success reads the same way through `[role="status"]` — scoped, because an
unscoped one may find a spinner. A component's `error` / `success` slot classes
are unchanged: they still land on the inner `Alert`, never on the region, so
`region(form).firstElementChild` is the message element they style.

**`<VerifyEmailPage>`'s spinner** renders without its own `role="status"` for
the same reason — it sits inside the page's region.

**`<NotificationBadge>` has an accessible name and passes attributes through.**
Its accessible name used to be the bare "3", and its declared props accepted
nothing else. It now takes the localized `notifications.badge.unread` as its
`aria-label` (with the _shown_ text substituted, so past the cap the name says
`99+` too) and spreads the rest of its attributes onto the badge root, so your
own `aria-label`, `id` or `data-*` reach it. A test asserting that the badge's
accessible name is the number has to read the text content instead. Its ARIA
role is `Badge`'s to derive and did not change here: `button` with an `onclick`,
`status` without one — but the **interactive styling now follows the handler
too**: without an `onclick` the badge no longer renders `cursor-pointer` or the
hover/active scale and colour, because it is neither a button nor a tab stop. A
visual snapshot of a handler-less badge changes.

**Row actions name their row.** `<NotificationCenter>`'s delete button is now
"Delete — {title}" and `<SessionManager>`'s revoke "Sign out — {device}",
matching what `<PasskeyManager>` and `<InvitationManager>` already did. A query
for the exact name `'Delete'` or `'Sign out'` no longer matches; `/^Delete/`
does. Unread rows additionally carry a visually hidden "Unread" inside the row
button, so its accessible name begins with that word.

**The locale bundle grew three keys**, so a hand-written `AuthLocale` stops
compiling until it carries them — the intended signal:
`notifications.badge.unread` (`{n}` is the badge's own text),
`notifications.center.unread`, and `twoFactor.setupTitle` (the setup step gained
a heading, which is where focus now lands). Consumers passing a
`PartialAuthLocale` override are unaffected.

**Two components move focus where they did not before.**
`<PushPermissionPrompt>` hands focus on as it unmounts instead of dropping it on
`<body>`: back to whatever held it when the prompt appeared, else the next tab
stop after the card, else the one before it — skipping controls that are
disabled or not rendered, and mutating no element it does not own. On a page
with no other control it moves nothing. Your `onDismissed` / `onSubscribed` /
`onUnavailable` callback runs **first** on every closing path, so a callback
that places focus itself wins: the prompt only moves focus that is still on its
own buttons. `<TwoFactorManager>` moves focus to the heading of the step it just
opened (each step heading is now focusable, with the library's keyboard-only
focus ring). Both only move focus they still hold: a user who clicked elsewhere
while the request ran keeps their place, and a refused code changes no step, so
the caret stays in the field.

#### Breaking in 8.17.0

Passkeys can be **renamed**. `createPasskeyHandlers` gains `item.PATCH` on
`…/[credentialId]` and `<PasskeyManager>` grows an inline rename control on
each row, so `PasskeyRepository.rename` — required of every adapter since it was
declared, and reached by no shipped code path — now has one.

Mount the new verb beside the delete it shares a route with:

```ts
// …/[credentialId]/+server.ts
export const DELETE = passkey.item.DELETE;
export const PATCH = passkey.item.PATCH;
```

The endpoint takes `{ name }`, bounded by the same display-name rule as the
profile name (non-empty once trimmed, at most 256 characters, stored trimmed),
and answers `200 { passkey }` with the row in the shape `list` returns. A name
that is absent, blank or over the bound is `validation_error` (`400`); a
credentialId that is not the caller's — absent or someone else's, deliberately
one answer — is the new `passkey_not_found` (`404`). Ownership is decided in the
handler, so the refusal does not rest on the adapter's own scoping.

**Registration now holds a supplied name to the same rule.**
`registrationVerify` passed `name` straight to the adapter unchecked, so a label
registration accepted could be one the rename refuses — 100 KB of it, blank, or
not a string — and it came back in every `list` response afterwards. A request
that supplies such a name now answers `validation_error` (`400`) where it
answered `201`. Omitting `name` is unchanged and remains what `<PasskeyManager>`
sends: the adapter's `'Passkey'` default still applies.

Adapters need no edit. **The other break is the locale bundle:** `AuthLocale` is fully required, so a hand-written
one stops compiling until it carries the new keys — the intended signal, not a
regression. Added: `auth.errors.passkeyNotFound` and `passkeys.rename`,
`passkeys.renameLabel`, `passkeys.renameSave`, `passkeys.renameCancel`,
`passkeys.renamed`. Consumers passing a `PartialAuthLocale` override are
unaffected.

#### Breaking in 8.16.0

**The HTTP status is now a property of the error code.** One code answers under
exactly one status, everywhere it is sent, so `code` and status can no longer
disagree between two handlers. Where one name had been carrying two statuses
there are now two names, and both splits use the same rule: `401` means the
request was an attempt to authenticate and the credential it carried was
missing or refused; everything else about a request answers `400`, including a
wrong secret on a request that authenticates nobody.

- **Two-factor.** `invalid_code` keeps the sign-in step (`401`, unchanged).
  Enrolment answers the new `two_factor_setup_code_invalid` (`400`, unchanged)
  when the code typed against the staged secret does not match.
- **Passkeys.** `passkey_verification_failed` keeps the sign-in ceremony, and
  **its status changes from `400` to `401`** — the one wire change in this
  release. A sign-in ceremony that refuses the credential now answers the same
  status class as a refused password or second factor. Enrolment answers the
  new `passkey_registration_verification_failed` (`400`).
  `passkey_credential_deleted` **also moves from `400` to `401`**: the browser
  did present a credential and the server refused it, and "unknown" rather than
  "invalid" is the reason — which is what the `code` carries. Every way a
  passkey sign-in can be refused now answers `401`.

A client that switches on the code falls through to its `default` arm for the
two enrolment cases until it adds the new names; one that handles only the
sign-in codes is unaffected by the renames. A client that branches on the
**status** of a failed passkey sign-in must expect `401` where it saw `400`.

`AuthLocale` is fully required, so a **hand-written locale bundle stops
compiling** until it carries the new keys — the intended signal, not a
regression. Added: `auth.errors.twoFactorSetupCodeInvalid` and
`auth.errors.passkeyRegistrationVerificationFailed`. Consumers passing a
`PartialAuthLocale` override are unaffected.

#### Breaking in 8.7.0

`<RegisterPage>`'s `passwordMinLength` / `requireUppercase` / `requireLowercase`
/ `requireDigit` / `requireSpecial` props are gone — they were the second copy.
Their old defaults (min 8 **plus** upper, lower and digit) were also stricter
than an unconfigured server, so the checklist blocked passwords the server would
have taken. Configure `config.password` and mount the endpoint; the UI follows.

`requireSpecial` is new on the server side. The registration checklist has
offered that rule since v8 while `validatePasswordStrength` ignored it, so a UI
demanding a symbol refused nothing the server would have accepted; it is now
enforced, and off by default like the other character classes.

`AuthLocale` is fully required, so a **hand-written locale bundle stops
compiling** until it carries the new keys — that is the intended signal, not a
regression. Added: `auth.errors.csrfFailed`, `auth.errors.passkeyVerificationFailed`,
`auth.errors.connectionLimit`, and the `auth.passwordRequirements` subtree
(`label`, `met`, `notMet`, `failed`, `rules.*`). Moved: `auth.register.requirementsLabel`
and `auth.register.requirements.*` became `auth.passwordRequirements.label` and
`auth.passwordRequirements.rules.*` — they are read by the account panel and the
reset page too, so `register` was the wrong home for them. Consumers passing a
`PartialAuthLocale` override are unaffected unless they overrode those two.

### Consumer Integration — staged setup

The full copy-paste walkthrough lives in [packages/auth/README.md →
Getting Started](../README.md#getting-started), structured as three
stages that build on each other. This section is the architectural view: which building
blocks each stage swaps in, and the invariants that hold across all of them.

**Cross-cutting:** `createAuthHandle` is mandatory in every stage — it hydrates the
session (`locals.user`), guards routes, applies the response security headers, and
enforces CSRF. The handler factories alone do none of that.

**Mail transport:** `deps.email` is optional, like the feature-scoped repositories.
Three factories mail whenever they act at all — `createRegisterHandler`,
`createForgotPasswordHandler` and `createChangeEmailHandler`; the caller can neither
ask for nor opt out of the mail, and its failure never reaches them — and each throws
at wiring time without a transport, the way `createPasskeyHandlers` does without
`repos.passkey`. `createInvitationHandlers` does **not**: its mail hangs on the
per-request `sendEmail` flag and the copy-link flow needs no transport at all, so it
mounts either way and declines to mail per request — a `sendEmail: true` invite without a
transport still answers `201` with its `inviteUrl`, `emailSent: false`, and a logged
error that names the missing wiring instead of reporting a send failure. An app that
mounts only login/logout/me/refresh/sessions plus 2FA and passkeys needs no transport
at all. The cost of the optional field is on the reading side — `deps.email` is
`EmailTransport | undefined` for anyone who takes it off the bundle in a handler of
their own, and has to narrow before using it.

**Stylesheet:** every stage that mounts a component needs
`@import '@urbicon-ui/auth/style/index.css';` after the blocks import in the app's
Tailwind stylesheet (see [README → Installation](../README.md#installation)). The file
carries no tokens — only the `@source` directive that lets the consumer's Tailwind build
reach the classes inside this package. Without it the `sm:` layouts and the link colour
of the auth pages are missing from the compiled CSS.

`createAuthHandle` applies response security headers automatically:
`X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy`,
`Permissions-Policy` (always on) plus `Strict-Transport-Security` (only in a
[secure deployment](#secure-deployment)) and a `Content-Security-Policy` baseline
(`frame-ancestors 'none'`). Tune or disable the latter two via
`config.securityHeaders` — e.g. `{ csp: "default-src 'self'", hsts: false }`.
CSP is a hook: a full policy is app-specific, so supply your own once you know
which origins the app loads.

**Responses are uncacheable by default.** Everything the handlers answer is
scoped to one account — the `me` payload, freshly minted tokens, the session,
invitation, notification and passkey lists, 2FA material, WebAuthn challenges,
and the per-account outcome a bare `{ success: true }` reports — so every
response the package builds carries `Cache-Control: no-store`. It is a
property of the endpoint rather than of each call site: refusals take it from
`authError`, every other response from the wrapper around each handler bundle,
so a route cannot answer without it and no handler has to remember to add it.
That matters because SvelteKit's `json()` emits nothing but `content-type` and
`content-length`, and a `200` carrying no cache directive is heuristically
storable (RFC 9111 §4.2.2): a shared cache in front of the app, keyed by URL
and seeing no `Vary: Cookie`, would be free to serve one account's
notification rows, notification preferences or passkey inventory to the next
caller. The
notification SSE stream is `no-store` for the same reason — `no-cache`, the
conventional stream header, only forces revalidation and still lets a shared
cache keep the response.

**Three endpoints are public and say so**, each with
`Cache-Control: public, max-age=300`: `createJWKSHandler` (the published public
key set), `createPasswordPolicyHandler` (the policy the sign-up and reset forms
gate against) and `createPushKeyHandler` (the VAPID public key browsers need in
order to subscribe to Web Push). None of the three is scoped to a caller, and
all three accept the same bounded staleness — after a key rotation or a
tightened policy a warm client keeps using the previous value for up to five
minutes, which costs one refused push subscription or one rejected submit and
corrects itself on the next fetch.

Those three are the whole exception list **among the responses this package
builds**. The rule does not reach what SvelteKit generates from a `throw`: the
handle's `302` to the login page for a guarded route, or the `500` raised when
a consumer hook throws. Neither carries a directive. Neither status is in the
heuristically-cacheable set either, so nothing that motivated the rule reopens
there — but if you put a cache in front of the app, those two are the
responses this package has not spoken for.

#### Secure deployment

Whether the deployment runs over HTTPS is answered once, for every cookie the
package writes: it is secure **unless any of the three cookie configs a consumer
can declare it on — `jwt`, `csrf`, `refreshToken` — says `cookieSecure: false`**.
A deployment is one transport, so a single `false` settles the question for all
of them. Five decisions hang off that one answer: the `__Host-` prefix and the
`Secure` attribute of the 2FA and passkey-ceremony cookies, the
`csrf.useHostPrefix` warning, HSTS, and whether the wiring-time hardening
warnings (`rateLimit: null`, `lockout: null`, a weak `pbkdf2Iterations`) treat
the config as production. The signal is deliberately this wide: a `__Host-` +
`Secure` cookie is dropped by the browser over plain HTTP, and the flows that
lose it report a *challenge-store* failure (`no_2fa_challenge`, a missing
passkey ceremony handle) — the cookie's name is nowhere in that message, so a
narrower signal would cost the operator the whole debugging trail.

Each cookie is still *written* with its own `cookieSecure ?? true`, so the three
flags can disagree, and both directions bite: `csrf.cookieSecure: false` alone
switches HSTS and the production warnings off while the session cookie stays
`Secure`, so nobody can log in over HTTP; `jwt.cookieSecure: false` with
`csrf.doubleSubmit` and no `csrf.cookieSecure` writes a `Secure` CSRF cookie
over plain HTTP, the browser drops it, and every mutating request answers 403.
`createAuthDeps` therefore warns at wiring time whenever the configured slices
disagree (`[auth] cookieSecure disagrees between cookie configs: …`). Only
configured slices count — an absent `csrf` / `refreshToken` writes no cookie —
and `csrf.useHostPrefix: true` counts as `Secure`, because the prefix forces
it. Set `cookieSecure: false` on all of them for an HTTP dev deployment, or on
none of them for HTTPS. One pair is not a warning but a wiring-time error:
`cookieSameSite: 'none'` on a cookie that is not `Secure` — browsers reject it
outright, so the config is refused.

#### Stage 1 — Quickstart (dev)

In-memory adapter (`createInMemoryRepos`) + console email transport
(`createConsoleEmailTransport`) + `jwt.cookieSecure: false`. No database, no mail
server, wiped on restart — **dev only**. `createAuthDeps` still applies the secure
brute-force defaults (login rate-limit + lockout), so the dev flow isn't unprotected.
**Every key of `rateLimit` carries a default.** Configuring some keys is a merge,
never a replacement (`rateLimit: { register }` still leaves login protected), and
the default table is derived from the key set — a new endpoint key cannot ship
without one. There are two opt-outs: `rateLimit: null` disables limiting for every
handler, and a single key set to `null` disables just that one — `rateLimit: {
register: null }` is "deliberately unlimited registration" without giving up the
login brake. An *omitted* key is not an opt-out; it gets the default. The lockout
default applies only when you configured neither `rateLimit` nor `lockout`; opt out
of it with `null` too. The three sign-in limiters — `login`, `twoFactor`,
`passkeyAuth` — count attempts, and a success refunds the slot its request took:
behind a shared address they brake failures only, and twenty colleagues signing in
from one office spend nothing. A refund, not a reset — a success gives back exactly
what it cost, so an attacker with an account of his own cannot clear the address's
budget between guesses at other accounts. The re-auth keys (`changePassword`,
`changeEmail`, `deleteAccount`, `twoFactorDisable`) take the account password too
but count every request: they sit behind a session and are used once in a while,
never in a sign-in wave. One key is identified differently from all the others:
`passkeyRegister` counts per **authenticated user id**, not per address —
enrolment sits behind a session, so a per-user key cannot be dodged by rotating
addresses, and it does not brake an office enrolling from one NAT address.

| key                                                                     | window    | max | why this number                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------------- | --------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login`                                                                 | 15 min    | 5   | the one endpoint offering a human-chosen secret                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `changePassword` · `changeEmail` · `deleteAccount` · `twoFactorDisable` | 15 min    | 5   | re-auth endpoints accept the account password; a hijacked session must not get a better budget than the login form, and failed re-auths feed no lockout                                                                                                                                                                                                                                                                                                                                 |
| `twoFactor`                                                             | 15 min    | 10  | 10⁶ codes — a few typos, online brute force hopeless                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `register` · `forgotPassword` · `resetPassword` · `verifyEmail`         | 15 min    | 10  | 256-bit single-use tokens, so the budget brakes cost (mail sending, PBKDF2), not guessing; more generous than login because the key is the client IP and these are once-in-a-while actions behind shared/NAT addresses. These count every request, successes included: onboarding twenty people behind one office address takes two windows — the eleventh signup within fifteen minutes gets a `429` with `Retry-After`, tolerable for something done once                             |
| `passkeyAuth`                                                           | 15 min    | 30  | two calls per ceremony (options + verify share one bucket) = 15 failed or abandoned ceremonies, a completed one refunds both calls; it also bounds the challenge store, which prunes only at the 5-minute TTL — at **30** live entries per IP, not 15, because an abandoned ceremony spends one call and leaves its entry behind                                                                                                                                                        |
| `passkeyRegister`                                                       | **1 min** | 10  | the authenticated half of the same feature, keyed by **user id**. Enforced on `registrationVerify`, the call that creates the credential row. It caps the rate at which one account adds credentials — and with them the `excludeCredentials` / `allowCredentials` payloads later ceremonies carry. **No per-user credential cap stands beside it**, so this rate is the only bound on either: ten a minute is 600 rows an hour for an account that keeps at it. A brake, not a ceiling |
| `refresh`                                                               | **1 min** | 30  | the short window is the point: only the explicit refresh endpoint reads it (the handle hook rotates without it), a client needs it once per access-token lifetime, and every session behind one NAT address shares the counter — 30/min absorbs a many-tab burst and forgets it a minute later instead of locking the office out for fifteen                                                                                                                                            |

`resetPassword` is the one worth understanding before you loosen it: the handler
runs PBKDF2 **before** claiming the token, deliberately, so the claim→write window
stays closed — which means one unauthenticated request with any garbage token costs
a full password hash (~55 ms at the default work factor). Without a limiter, a few
dozen requests per second saturate the thread pool that login's own hashing shares.

Two endpoints that read one key share **one** counter (`verifyEmail` covers both
verify-email and verify-email-change; `passkeyAuth` covers options and verify). The
counters live for the process, keyed on the `jwt.secret` (a fingerprint of it — the
secret itself is never retained), the key and the configured limit: every bundle
built for one secret with the same `rateLimit` for a key reads the same counter and
the same in-memory store, so a `createAuthDeps` call per request cannot reset them,
and a bundle that configures a key differently — an opt-out included — counts on
its own under its own values; no bundle's limit depends on which was built first.
Under `vite dev` the counters survive a hot reload of your files — it re-executes
those, not the package module, whether Vite serves it from its SSR module graph or
from Node's module cache — so unchanged limits keep their counters across the
reload, and an edited `rateLimit` counts afresh under its new values on the next
bundle, without a restart.
Still **call `createAuthDeps` once**, at module scope, and pass `deps` around: every
call validates and resolves the config again, and a second call with a `jwt.secret`
this process has already built a bundle for is warned about on the logger — once
per secret, in production too. A limit with a persistent `RateLimitStore` is not
registered at all: its counters live in the store, shared across processes as well.

The wiring is four files: deps → `hooks.server.ts` (`createAuthHandle`) → one
`+server.ts` per handler (`createLoginHandler`, …) → a `<LoginPage>` route.

##### Testing handlers

The counters are per secret and per process, not per config object, so a test file
that builds real handlers from one literal secret spends one budget across its
tests: a `max: 1` test meets the counter a sibling already moved to 1, and a `429`
is spent before the test that expects it. Two ways out. Reset the counters before
each test — `resetRateLimiters()` starts every in-memory limiter over with a fresh
store, for every handler, whenever it was built — from a setup file or the top of
the test file:

```ts
import { resetRateLimiters } from '@urbicon-ui/auth/server';
import { beforeEach } from 'vitest';

beforeEach(() => resetRateLimiters());
```

Or hand each test its own `store` (`rateLimit: { login: { windowMs, max, store } }`):
a limit with a store is never registered, its counters are the store's, and a
`Map`-backed `RateLimitStore` per test isolates them without touching the registry.

#### Stage 2 — Production

Swap in `createPrismaRepos` + a real transport (`createLettermintTransport`) and turn on
the additive hardening layers: `csrf.doubleSubmit` (only when every mutation sends the token header — see the production checklist; incompatible with remote-function / no-JS-form mutations), `refreshToken` rotation (+ a `refresh`
route stub via `createRefreshHandler`), per-handler `rateLimit`, `lockout`, and HTTPS
(which auto-enables HSTS). The three single-use tokens the package mails out have their
own windows under `tokenTtl` — `emailVerification` (default `'24h'`), `passwordReset` and
`emailChange` (default `'1h'`) — in the `Ns | Nm | Nh | Nd` grammar every other duration
field uses; set them when a policy prescribes a different one. Each is resolved when the
handler is created, so a malformed value throws at wiring time rather than in a request,
and shortening one never shortens a link that is already in someone's inbox. `appUrl` must be the real public origin — outbound email links
are built from it, never from `request.url` (the Host header is attacker-controlled). Work
through the **[Production-Readiness Checklist](#production-readiness-checklist)** before going
live.

#### Stage 3 — Advanced

- **Custom persistence adapter** — see the [Adapter Authoring Guide](#adapter-authoring-guide); validate it against the exported conformance suite.
- **Post-login deep links** — the route guard preserves the originally requested path: an unauthenticated GET navigation redirects to `${loginPage}?redirectTo=<path+query>` (non-GET requests redirect without the param — a POST target must not be re-issued as a GET). The param is attacker-writable like any query string, so consume it **only** through the exported `sanitizeRedirect` (root and server export), which admits internal absolute paths and falls back on everything else (absolute/protocol-relative URLs, `/\` variants): `onSuccess={() => goto(sanitizeRedirect(page.url.searchParams.get('redirectTo'), '/dashboard'))}`.
- **JWT key rotation** — `jwt.keyId` + `jwt.previousSecrets` roll the signing secret without invalidating live sessions.
- **Passkeys (WebAuthn)** — mount the `createPasskeyHandlers(deps, webauthn)` route group (the four ceremony groups plus `list`/`item` for `<PasskeyManager>`'s list, rename and remove — `item` carries both `DELETE` and `PATCH` on `…/[credentialId]`; requires `deps.repos.passkey`, throws at wiring time without it) with a `webauthn: WebAuthnConfig` (persistent `challengeStore` at >1 instance; **user verification is enforced by default** — `requireUserVerification: false` opts out for authenticators that cannot do UV, and because passkey logins skip the TOTP gate, that opt-out alongside `config.twoFactor` makes a passkey login single-factor for a TOTP-enrolled user; `createPasskeyHandlers` warns at wiring time when it sees the pair) and add `<PasskeyManager>` + `<LoginPage mode="both">`.
- **Notifications & Web Push** — register domain events server-side, listen with `<NotificationListener>` + `<NotificationCenter>` client-side. **`notification.url` is untrusted at navigation time** — validate/allow-list it before `goto()`. The list/mark-read/read-all/delete routes that `createNotificationStore` calls are served by `createNotificationsHandlers(service)` — mount its `list`/`read`/`readAll`/`item` groups under the store's `apiPath` (default `/api/notifications`); every method derives `userId` from `locals.user` and goes through the ownership-scoped service methods (IDOR-safe by construction). **Endpoint takeover is key-gated**: `pushSubscription.create` upserts by endpoint, and reassigning the row to a *different* account requires the submitted keys to match the stored ones (compared constant-time on the decoded bytes) — the legitimate user-switch-in-the-same-browser case re-sends the browser's existing subscription (same endpoint *and* keys), while merely knowing the endpoint URL (say, from a log) is refused with `409` and no write (`'rejected'` outcome; all four outcomes — created/updated/reassigned/rejected — are conformance-tested). Endpoint URLs are still worth keeping out of logs (they are the push target), but takeover no longer rides on them alone. `recipients: 'online'` is presence-based, not account-based — it reaches the users with an open SSE stream in this process at send time, and nobody else (renamed from the misleading `'all'`; `send()` throws a migration error on the old value). The registry rejects duplicate keys and the legacy `'all'` value at registration time — note for dev-HMR setups: if you cache the registry on `globalThis` to survive hot reloads, module-scope `register()` calls re-run against the surviving instance and throw; cache the registrations together with the registry (or guard with `registry.get(key)`). A type declared with `recipients: 'admins'` requires a `resolveAdminRecipients` resolver on `createNotificationService` (e.g. `() => repo.findAdminUserIds()`) — the package has no role model of its own, so without it `send()` **throws** rather than silently delivering admin alerts to nobody. Push delivery failures are swallowed so one bad subscription can't break a send; pass `onPushResult` to observe them, and subscriptions the push service reports as gone (410/404) are pruned automatically. The preference/push-subscription endpoints are rate-limited per user by default (30/min PUT resp. 10/min POST; `rateLimit: null` opts out — the push-subscription `DELETE` carries none, see [the rule for authenticated writes](#rate-limiting-lockout--route-scope-deliberate-trade-offs)), `createPreferencesHandler` requires the registry and rejects unregistered `typeKey`s (bounding per-user preference rows to the registered types), and stored subscriptions are capped per user (`maxSubscriptionsPerUser`, default 10, `409` beyond — re-subscribes of a known endpoint always pass).
- **Invitations (admin)** — `createInvitationHandlers(deps, { authorize, roles })` is the server half of `<InvitationManager>`: mount `POST` + `GET` on `/api/invitations` and `DELETE` on `/api/invitations/[id]`. `authorize` is **required and fail-closed** (no open default) — registration's account-enumeration defense holds only while invitations stay admin-minted, so any authenticated user must not be able to mint one. `roles` allow-lists the assignable roles, so a crafted request can't escalate past what the UI offers. Every invitation carries a **one-time token** (SHA-256 in the database, raw value returned once) and an **expiry** (`invitationTtlMs`, default 7 days). The `201` returns `inviteUrl` — `${appUrl}/auth/register?token=…&email=…` — because that URL is the only way the invitation reaches anyone when no mail transport is configured, a case this package ships a console transport for. It is not in `GET`: the server keeps only the hash, so an admin who loses the link revokes the invitation and mints a new one. When the client sets `sendEmail`, the handler also mails that link — best-effort: a mail failure still returns `201` with `emailSent: false` (logged), since the invitation row is the durable effect. This group is the one mailing factory that does **not** require `deps.email` at wiring time (the copy-link deployment above is a complete configuration); a `sendEmail: true` request on a bundle without a transport gets the same `201 { emailSent: false }` plus a log line naming the missing wiring, kept distinct from the send-failure one so the two causes stay tellable apart. Override the mail via `inviteEmail`.
- **Pre-verified invited signups** — an invitation **that was emailed** proves mailbox ownership: the mail went to that address, it carried a secret, and the secret came back. A link the admin copied out of the panel proves nothing of the sort — it travelled whatever channel the admin chose — so `autoVerifyInvited` is honoured only for invitations with an `emailedAt`, and a copy-link signup gets the ordinary verification mail regardless of the setting. Pass `createRegisterHandler(deps, { autoVerifyInvited: true })` to create the account with `emailVerified: true` and skip the verification token **and** the verification mail entirely. Without it, the user — who is auto-logged-in on register — receives a "verify your email" mail *after* already being signed in, and `emailVerified` never flips. Defaults to `false` (backwards-compatible: token + mail issued as before, for consumers that genuinely gate on `emailVerified`). The flag is an option on the register handler's **second argument**, not something threaded through `createAuthHandle` — that hook only resolves the session and guards routes; every handler is mounted with its own `+server.ts`. Email *change* still verifies the new address independently (`createVerifyEmailChangeHandler`); there is no prior proof of ownership for it, so it is unaffected.
- **Session enrichment** — attach app-specific data (tenant/household id, plan, entitlements) to `locals.user` via `config.hooks.transformUser(user, event)`. It runs in the handle hook on every authenticated request with the sanitized `AuthUser` (never the password hash) and the request event; its return value becomes `locals.user` (type it through your `App.Locals`). `AuthUser` is intentionally fixed and the loaded row carries no custom columns, so load extras here keyed by `user.id` rather than adding a second `handle` that re-resolves the session. A throw fails the request — except on the transparent refresh-rotation path, where the rotation has already committed and its cookies would be lost with it; there the throw is caught and the request continues unauthenticated. Whatever you return lands on `locals.user` — keep secrets out of it if `locals.user` is serialized to the client. **Throw semantics across `config.hooks`:** `transformUser` and `onBeforeAccountDelete` are the only two gates, where a throw aborts; every other hook only reports, so a throw is caught and sent to `config.logger.error` and the handler's outcome stands. Each hook's JSDoc says which it is — read that before wiring one, and don't generalize from these two.
- **Account management (self-service)** — let a signed-in user manage their own account. Five server handlers (`createChangePasswordHandler`, `createChangeEmailHandler`, `createVerifyEmailChangeHandler`, `createUpdateProfileHandler`, `createDeleteAccountHandler`) plus the `<AccountSettings>` component (mount the first four under `/api/auth/account/*`; the verify-email-change route sits behind the link mailed to the new address). Invariants: every mutation except profile is **re-auth gated** (`verifyCurrentPassword`); `change-password` bumps `tokenVersion` + revokes all refresh families, then re-establishes the _current_ device (others log out — a voluntary change isn't a compromise, so the initiating device stays in, unlike `reset-password` which signs out everywhere); `change-email` verifies the **new** address (notice to the old one) and is account-enumeration safe (token+mail decoupled, always `success: true`, collision = no-op); `delete-account` is a hard delete (GDPR erasure) that fires `hooks.onBeforeAccountDelete` with the sanitized user **before** the row is removed (a throw aborts), with the Prisma adapter dropping sent invitations in the same `$transaction`. Config: `rateLimit.{changePassword,changeEmail,deleteAccount}`, hooks `onEmailChangeRequested` / `onEmailChangeFailed` / `onEmailChanged` / `onBeforeAccountDelete` (`onEmailChangeFailed` surfaces the decoupled token/mail failure, like `onPasswordResetFailed`).
- **Active-session listing** — let a user see and revoke their sessions. **Requires `config.refreshToken` rotation** — a "session" is a refresh-token family, so without rotation there is nothing server-side to list (the endpoint returns `available: false`). One route group — `createSessionsHandlers(deps)` with `list` (GET), `revoke` (POST) and `revokeOthers` (POST) — plus the `<SessionManager>` component. Each session row carries the user-agent (the component parses it to "Browser · OS" with a zero-dep heuristic) and a `createdAt`-based "last active"; the IP is listed only when the consumer opts in via `config.sessions.storeIp` (GDPR, default off). Revokes are **ownership-scoped** — `revokeFamilyForUser` returns 404 for a family that isn't the caller's, so a guessed family id can't sign out another user (IDOR). The session of the current request is flagged `current` (resolved from the request's refresh cookie). Login/register/passkey-verify tag their sessions with the device metadata via `resolveSessionMeta`, carried across rotation.
- **Two-factor authentication (TOTP)** — an opt-in authenticator-app second factor on top of the password. Set `config.twoFactor` (`encryptionKey` **required** — high-entropy, stable; it encrypts the secret at rest, and rotating it locks every enrolled user out until they get back in with a backup code — or, for users who enrolled one, a passkey, since passkey logins are not TOTP-gated — see the [key-rotation runbook](#key-rotation-runbook-twofactorencryptionkey)) and provide `repos.backupCode` (both shipped adapters include it). One route group — `createTwoFactorHandlers(deps)`: `setup`/`enable`/`disable` (authenticated, mount under `/api/auth/account/2fa/*`) plus `verify` (the **public** second login step, mount under `/api/auth/2fa/verify`); the `login` handler gates automatically on `user.totpEnabled`. UI: `<TwoFactorManager>` for enrol/disable + the two-step `<LoginPage>`. Invariants: the secret is **AES-256-GCM-encrypted at rest** and only ever returned (plaintext Base32 + otpauth URI) by `setup`; the login gate keys on `totpEnabled` **alone** so a missing `config.twoFactor` can never become a bypass (fail-closed) — it issues a signed, short-lived pending-2FA token (cookie `urbicon_2fa`, `__Host-`-prefixed unless a `cookieSecure: false` on the session, CSRF **or** refresh cookie declares the deployment non-HTTPS) instead of a session, leaving no session/refresh cookie and deferring `onLoginSuccess` to verify; verify accepts a TOTP **or** a single-use SHA-256 backup code, is **strictly rate-limited** (`createAuthDeps` injects a default), and consumes the pending cookie only on success (a wrong code keeps it for retry within the TTL); `disable` is **password re-auth gated** and clears the secret + every backup code; backup codes are cleared before re-issue at enable so a re-enrol leaves none doubly-redeemable. Passkey logins are **not** gated — a claim that rests entirely on user verification: `webauthn.requireUserVerification` defaults to `true`, so an accepted assertion carries possession *and* an asserted PIN/biometric (asserted, not attested — see [Known Limitations](#known-limitations--security-gaps)). Set it to `false` and a passkey is possession alone, which makes a passkey login a single-factor login for exactly the users who enrolled a second one (`createPasskeyHandlers` warns on that pairing). The TOTP core (`server/totp.ts`, RFC 6238/4226/4648) is exported for custom flows; the pending-token/cookie/backup-code plumbing (`server/two-factor.ts`) stays internal (consumed only by the login + 2FA handlers). Config knobs: `twoFactor.{issuer,algorithm,digits,period,window,pendingTokenTtl,backupCodeCount}`, `rateLimit.twoFactor`. `algorithm` defaults to **SHA-1** — the only one Google/Microsoft Authenticator reliably support; the secret's high entropy carries the security, not the hash, so SHA-256 stays opt-in. **Note:** the verify rate-limit is per-IP (like login) and TOTP codes are replayable within their window in v1 — both deliberate trade-offs (see [Known Limitations](#known-limitations--security-gaps)).
- **Federated identity / SSO** — one deployment becomes the identity provider (ES256 tokens + `createJWKSHandler`), sibling apps verify with `createFederatedAuthHandle` and decide access themselves. See [Federated Identity (SSO)](#federated-identity-sso).

```typescript
// Server: register a domain event (Stage 3 notifications)
import { createNotificationRegistry } from '@urbicon-ui/auth/server';
const registry = createNotificationRegistry();
registry.register({
  key: 'order_shipped',
  title: (data) => `Order ${data.orderId} shipped`,
  url: (data) => `/orders/${data.orderId}`, // untrusted at click time — validate before goto()
  recipients: async (data) => [data.userId as string] // data is Record<string, unknown>
});
```

#### Logout

`createLogoutHandler(deps)` revokes the refresh token the request's cookie carries
(when `refreshToken` rotation is configured) and clears both cookies. It requires no
valid session — a client whose access token has already expired still gets
`{ success: true }` with its cookies dropped — and a repo failure on the revoke is
logged, not propagated: the cookies are cleared in a `finally`, so a transient
database problem cannot leave a live refresh cookie behind.

**What it cannot end is the access token.** A session JWT is verified from its
signature rather than looked up, so a copy taken before the logout — a `curl`
session, a shared machine, a synced browser profile — keeps authenticating until
`jwt.expiresIn` elapses: 15 minutes under `refreshToken` rotation
(`refreshToken.accessTokenTtl`), 7 days without it. Nothing server-side refuses it,
because nothing server-side knows it exists. That is the stateless-JWT trade-off,
and the reason rotation shortens the access-token TTL in the first place.

Close the window at the price below:

```ts
// src/routes/api/auth/logout/+server.ts
import { createLogoutHandler } from '@urbicon-ui/auth/server';
import { authDeps } from '$lib/server/auth-setup';

export const { POST } = createLogoutHandler(authDeps, { invalidateAccessTokens: true });
```

The handler resolves the user from the session cookie and, **before** the revoke
and before the cookies are cleared, makes two writes: it bumps their
`tokenVersion`, so the generation check every request runs in `createAuthHandle`
(`user.tokenVersion === session.tokenVersion`) refuses every access token minted
before this logout, and — with rotation configured — revokes every refresh family
of that user (`revokeAllForUser`, the pairing `reset-password` uses), so nothing
can rotate back in. No valid session, no writes — the request still answers `200`
with the cookies cleared.

Neither write is propagated on failure, the same best-effort policy the revoke
follows: the cookies go either way. They report **separately**
(`[auth] logout: token-version bump failed`,
`[auth] logout: refresh-family revoke failed`), because the half-done state is
worth reading in a log — a bump without its family revoke leaves every other
device's access token dead but its refresh token alive, so that device rotates
back in on its next page navigation. `tokenVersion` is one counter per user, so an
adapter must increment it losslessly — the conformance check
`user.incrementTokenVersion loses no concurrent increments` is what proves yours
does.

**The price: both writes are per user, not per session.** Every session of the
account ends — every access token is refused by the generation check, and with
rotation configured every refresh token is revoked. Another device is signed out
until someone signs in again, and the refusals clear its cookies as they go: the
guard's `401` carries the clear for whichever cookie it was refused on, so a
still-valid access cookie goes on the first request and the revoked refresh
token on the next (a device whose access token had already expired loses both at
once). From there it sends no session cookie at all and the refusal costs no
repository write — across three polls `revokeFamily` runs exactly once, on the
one request that still presented the revoked token (`costs one family revoke,
not one per poll`, `logout.test.ts`). A page navigation redirects to the login
and clears the same cookies on the way. Hence the default `false`.

**A logout that arrives with no valid session invalidates nothing** — the option
included. Under rotation that case is rare: the hook rotates an expired access
cookie before the endpoint runs, so the handler reads the fresh session and both
writes land. Without rotation an expired access token resolves no user, and there
is nothing left to invalidate anyway — the copy someone took is that same expired
token.

Which to reach for:

- **`invalidateAccessTokens`** — logout must end every session of the account:
  single-user tools, shared devices, an admin panel someone signs out of before
  walking away.
- **`createSessionsHandlers(deps)` → `revoke` / `revokeOthers`** — sign a
  _specific_ device out, or every other one, and keep this session. A session is a
  refresh-token family, so this path needs `config.refreshToken`. It never touches
  `tokenVersion`, so a revoked device keeps authenticating with the access token it
  already holds until that one expires.
- **`createResetPasswordHandler`** — a compromise, not a logout: it bumps
  `tokenVersion` _and_ revokes every refresh family, so nothing survives anywhere.

In a federated deployment the option is **IdP-side only**. Consumers verify the
IdP's tokens against its published key and never learn of a `tokenVersion` bump, so
a token a consumer holds stays verifiable there until `exp` — see
[Limitations](#limitations-deliberate-v1-scope).

#### Machine callers

A cron runner posting with a secret header, an OAuth token endpoint, an API-key
route: callers that send no `Origin` header and hold no session cookie. The
`@urbicon-ui/sveltekit-utils` cron runner is one — it sends its secret header
and nothing else. Step 1 of `createAuthHandle` is an Origin gate on every
mutating request, so such a POST answers `403 csrf_failed` before the endpoint
runs. Turning the job into a GET is not the fix (it gives up the mutation guard
everywhere else), and neither is routing the endpoint around the hook. Declare
it:

```typescript
import { createAuthHandle } from '@urbicon-ui/auth/server';
import { authDeps } from '$lib/server/auth-setup';

export const handle = createAuthHandle({
  config: authDeps.config,
  repos: authDeps.repos,
  csrf: { exempt: ['/api/cron/', { path: '/oauth/token', exact: true }] }
});
```

`csrf.exempt` takes the `publicRoutes` vocabulary — a string is a pathname
prefix, `{ path, exact: true }` that pathname alone, matched against the
requested pathname (a `reroute` hook changes which route is resolved, not
this) — or a predicate over the event for callers a path does not identify:
`(event) => event.request.headers.has('x-cron-secret')`. Two entries are
refused at construction: a bare `'/'`, because nothing would be left on
(`exempt: () => true` is the deliberate spelling), and anything covering
`/api/auth/`, the package's own endpoints — for the reason below. An exempt
request is handled as **cookieless** by the hook, not merely as CSRF-skipped.
The argument that makes the exemption safe — nothing ambient rides along, so
there is nothing for a cross-site page to forge — holds only for a request
that carries no credential the browser sends on its own, so the hook reads no
cookie and writes none: no Origin gate, no session hydration, no refresh
rotation, no CSRF cookie, no route guard. `locals.user` is `null` even when a
valid session cookie is present — deliberately — and the response still gets
the security headers. That describes the hook, not the request: the cookie
still arrives, and a route that reads `event.cookies` itself keeps working
with the gate off — which is how every handler this package ships resolves
its user (`requireSessionUser`, from the session cookie, never from
`locals.user`). So **never exempt a cookie-authorised route**; exempt only
routes that authenticate every request without a cookie (bearer token, secret
header, PKCE). The list form is checked for `/api/auth/`; the predicate form
cannot be, and the rule is yours to keep there. Remote-function requests are
never exempt on either transport — their pathname is client-controlled — so
the remote guard's default-deny stands, and the predicate is not consulted for
them.

SvelteKit's own kernel CSRF gate is a separate, earlier gate that `csrf.exempt`
does not reach. It runs before any hook, in built apps only (never under
`vite dev`), on **form content types** — `application/x-www-form-urlencoded`,
`multipart/form-data`, `text/plain`, plus Kit's internal
`application/x-sveltekit-formdata` — and `403`s a cross-origin or Origin-less
form POST with "Cross-site POST form submissions are forbidden". A JSON **or
body-less** POST (MCP JSON-RPC, dynamic client registration, a cron job that
sends no body and no content type) passes it; an OAuth token endpoint does
not, because RFC 6749 §4.1.3 mandates
form encoding and real clients send no `Origin`. The gate cannot be switched off
per route from a hook, and its allow-list — `kit.csrf.trustedOrigins` — is
consulted only when an `Origin` header is present, so no list of origins admits
a header-less caller. The off-switch is `kit.csrf: { trustedOrigins: ['*'] }`
in `svelte.config.js`, resolved at **build** time (Kit derives
`csrf_check_origin = checkOrigin && !trustedOrigins.includes('*')` in
`write_server.js`; the runtime check never matches `'*'` against a header), and
since Kit 2.61 the only non-deprecated spelling (`checkOrigin` is deprecated in
its favour). Kit's strict same-origin check for remote-function requests is
independent of `kit.csrf.*` and stays on. Disabling the kernel gate is safe
exactly when **(1)** every cookie-authenticated mutating route flows through
`createAuthHandle` — including form actions such as an OAuth consent
`?/approve`, and "cookie-authenticated" means any ambient-session route, not
only this package's; *reaching* the hook is what counts, so a handle earlier in
a `sequence()` that answers without calling `resolve` (maintenance mode, a
webhook implemented as a handle, a redirect) leaves its routes uncovered — and
**(2)** `csrf.exempt` names only routes that authenticate themselves. Step 1 is
stricter than the kernel gate for everything that reaches it (every mutating
method, every content type, no allow-list), so the kernel check was redundant
there; if you relied on `trustedOrigins` as an allow-list for legitimate
cross-origin *browser* form posts, note that `validateCsrf` has no equivalent.
On a federated consumer the wildcard is off-limits without a `validateCsrf`
backstop of your own — see [Limitations](#limitations-deliberate-v1-scope).

#### Upgrade note — user verification is enforced by default

`webauthn.requireUserVerification` defaults to `true`. Registration and
assertion both reject an authenticator that does not set the UV bit, so
**credentials already enrolled on a UV-less authenticator stop working** on
upgrade: a security key with no PIN configured, or one driven in a mode that
only proves User Presence. Platform authenticators (Touch ID, Windows Hello,
Android) set the bit and are unaffected.

What it looks like when it bites: the assertion answers `400` with the bare
`passkey_verification_failed` code — the body names no cause (see
[Error Contract](#error-contract)) — and `hooks.onLoginFailed` fires with the
reason `invalid_assertion` and an empty email. The cause is only in
`config.logger`: `[auth] passkey assertion rejected: User verification required
but not performed`. In an audit sink the hook entry reads like an attack, not
like a config change — so if you upgrade and your passkey-failure rate jumps,
look for that log line before you look for an attacker. Enrolling a *new*
credential on the same authenticator fails the same way, logged as `[auth]
passkey registration verification failed: User verification required but not
performed`.

Two ways out: have the affected users set a PIN on the key (the outcome the
default is asking for), or set `requireUserVerification: false` — in which case
read the 2FA note on the passkey bullet above before you do, because with
`config.twoFactor` wired the opt-out makes a passkey login single-factor.

#### Key-rotation runbook (`twoFactor.encryptionKey`)

The 2FA secret is encrypted at rest with this key, and `decryptSecret` is
fail-closed. Changing the key therefore does not degrade — it **locks out every
user with `totpEnabled`**, and re-enrolment is not the way back: `setup` refuses
while 2FA is still on, so those users cannot mint a secret under the new key
either.

Two routes remain open. A **backup code** — the verify handler keeps that path
live because backup codes are hashed on their own rows and need no TOTP secret.
And a **passkey**, for users who enrolled one: passkey logins are not TOTP-gated
(see the passkey bullet above), so the rotated key never touches them. Either
route yields a session, and a session is all that `disable` → `setup` → `enable`
needs to re-enrol under the new key.

Both decryption failures are reported through `config.logger` at `error` level,
naming a user id — but not at the same rate. `verify` reports every attempt
(that endpoint is rate-limited by default); `enable` reports only the first
attempt **per user**, because it has no limiter ([the rule for authenticated
writes](#rate-limiting-lockout--route-scope-deliberate-trade-offs)) and one
authenticated caller could otherwise fill the sink. So the `enable` lines count
the users the rotation reached, not the attempts they made. Watch that sink: the
response is a `500 totp_secret_unreadable` built with `authError`, which
**returns** a Response rather than throwing `error()`, so SvelteKit's
`handleError` never fires and a Sentry integration hooked there sees nothing.

1. **Do not rotate on a schedule.** Unlike `jwt.previousSecrets`, this key has no
   overlap mechanism — one key is in force at a time.
2. **If you must** (key compromise): announce it, then rotate. Every TOTP user
   whose only other credential is the authenticator app needs a backup code at
   the next login; passkey holders sign in unaffected.
3. **After the rotation**, drive the affected users through
   `disable` → `setup` → `enable` (the `<TwoFactorManager>` flow) so their secret
   is re-encrypted under the new key and a fresh backup-code set is issued.
4. **A user out of backup codes and without a passkey** is locked out of their
   account; recovery is your own out-of-band identity proof plus an
   administrative `disableTotp`. Check for an enrolled passkey before running
   that ceremony — it is the cheaper route and the user can walk it alone.
5. **If the key was merely lost** (not compromised), restoring it from backup is
   the whole fix — nothing on the user rows changed.

### Federated Identity (SSO)

One deployment running this package becomes the **identity provider (IdP)**; any number of sibling apps become **consumers** that trust it. The token boundary is deliberately narrow:

> **Identity ≠ authorization.** The IdP's JWT proves *who* the caller is — nothing else. Each consumer app decides *whether* that identity gets in, and *as what*, in its own `resolveUser`. The IdP token's `role` and `tokenVersion` claims are IdP-application-internal and are structurally withheld from consumers (`FederatedIdentity` carries only `subject`, `email`, `issuedAt`, `expiresAt` — type **and** runtime). Forwarding the IdP's role would be exactly the identity/authorization confusion this design forbids: an "admin" at `auth.example.com` is not an admin of your billing app.

#### Architecture (prose diagram)

- **IdP** (`auth.example.com`): switches its session JWT to `jwt.algorithm: 'ES256'` (ECDSA P-256; HS256 stays the default for non-federated deployments) and publishes the **public** half of its signing key as an RFC 7517 JWKS via `createJWKSHandler` — served with `Cache-Control: public, max-age=300`. Login, logout, registration, refresh rotation, 2FA: all stay exclusively at the IdP. With `jwt.cookieDomain: '.example.com'` the session cookie is shared with every `*.example.com` sibling (the refresh and CSRF cookies deliberately stay host-scoped — consumers verify, they never rotate).
- **Consumer** (`app.example.com`): mounts `createFederatedAuthHandle` as its `hooks.server.ts` handle. Per request it verifies the shared cookie's ES256 signature against the IdP's JWKS (fetched lazily, cached ~5 min, cooldown-limited refresh on unknown `kid` — no fetch storms; fetch failures fail *closed* with one loud log line, never a 500), then calls `resolveUser(identity, event)`. The result is `locals.user` (same locals contract as `createAuthHandle`); `null` denies. Route guard: `publicRoutes` entries pass (a string prefix or `{ path, exact: true }`, read exactly as on the IdP handle), `/api/` gets a JSON 401, pages 302 to `loginUrl` (typically the IdP login; used verbatim — no `redirectTo`, since the IdP's `sanitizeRedirect` admits IdP-local paths only), and unauthenticated remote-function calls are default-denied on both transports (the same default-deny as the IdP handle). The consumer handle **never writes cookies** (the cookie is the IdP's — clearing it would log the user out of every sibling app), runs no CSRF gate of its own (keep SvelteKit's kernel CSRF gate on — the default; do **not** set `trustedOrigins: ['*']` on a federated consumer) and sets no security headers (your app's own policy).
- **Why ES256 only:** a federated consumer must verify *asymmetrically*. Verifying HS256 requires the signing secret — and a shared signing secret means every "consumer" can also **mint** tokens, i.e. there is no trust boundary left. The consumer pins `alg: ES256` (plus a mandatory `kid`) before touching any key material; the IdP side pins its configured algorithm the same way (no algorithm-confusion downgrade in either direction).
- **Purpose binding:** every JWT this package mints carries a `purpose` claim, and every verifier requires it *in the primitive* — not in each caller's claim-shape check. Session tokens (HS256 and ES256 alike) are stamped `purpose: 'session'` (exported as `SESSION_TOKEN_PURPOSE`); `verifySessionToken` **and** the consumer handle reject any token without exactly that value. The generic short-lived tokens (`createSignedToken`/`verifySignedToken` — e.g. the pending-2FA handle, `'2fa-pending'`) take a mandatory `purpose` parameter, stamped at mint and matched verbatim at verify (`purpose` is a reserved claim; a missing/empty purpose argument throws — API misuse, not a bad token). Result: two token kinds signed with the same `jwt.secret` can never be accepted for each other's purpose. **Version skew:** the claim crosses the app boundary, so upgrade the **IdP first** — a pre-purpose consumer ignores the extra claim, while an upgraded consumer rejects pre-purpose IdP tokens (fail-closed; the break heals as tokens re-mint via login/refresh after the IdP upgrade).
- **Verifier input cap:** `verifySessionToken`, `verifySignedToken` and the consumer handle reject input longer than `MAX_TOKEN_LENGTH` (8 KB — double the ~4 KB browser cookie ceiling, so a legitimate cookie-borne token can never hit it) *before any parsing*; on the consumer this also precedes any JWKS fetch. Belt-and-suspenders for verifiers applied to unbounded non-cookie input.

#### Setup — IdP side

1. **One-time key setup** (a script, **never** on boot — a fresh key per process would invalidate every live session and desynchronize consumers):
   ```typescript
   import { generateES256KeyPair } from '@urbicon-ui/auth/server';
   const { privateKey, publicKey, kid } = await generateES256KeyPair();
   // privateKey → secret manager (it contains the private scalar `d`);
   // kid is the RFC 7638 thumbprint, stamped into both JWKs.
   ```
2. Config: `jwt: { algorithm: 'ES256', signingKey: privateKey, secret, cookieDomain: '.example.com' }`. `jwt.secret` stays required — package-internal short-lived tokens (pending-2FA handle etc.) deliberately remain HMAC. Misconfiguration (ES256 without a usable key, malformed `previousPublicKeys`) throws at wiring time in `createAuthDeps`/`createAuthHandle`.
3. Mount the JWKS route, e.g. `src/routes/.well-known/jwks.json/+server.ts`:
   ```typescript
   import { createJWKSHandler } from '@urbicon-ui/auth/server';
   export const { GET } = createJWKSHandler({ jwt: config.jwt });
   ```
   Exempt the route from the IdP's own guard if it falls outside your public prefixes — `publicRoutes` replaces the defaults rather than adding to them, so that reads `publicRoutes: [...DEFAULT_PUBLIC_ROUTES, '/.well-known/']`. Only public JWK members can reach the response (allow-list projection; a `d` in the config is warned about and never served).

#### Setup — consumer side

```typescript
// hooks.server.ts of app.example.com
import { createFederatedAuthHandle } from '@urbicon-ui/auth/server';
import { createPrismaFederatedAccountRepository } from '@urbicon-ui/auth/server/adapters/prisma';
import { prisma } from './prisma';

const federated = createPrismaFederatedAccountRepository(prisma); // throws if the model is missing

export const handle = createFederatedAuthHandle({
  jwksUrl: 'https://auth.example.com/.well-known/jwks.json', // https enforced (http: localhost only)
  cookieName: 'session', // must match the IdP's jwt.cookieName
  loginUrl: 'https://auth.example.com/auth/login',
  publicRoutes: [{ path: '/', exact: true }, '/pricing'], // exact: that pathname; a string: a prefix
  resolveUser: async (identity) => {
    // THE authorization decision of this app — identity.subject is the stable key.
    const link = await federated.findByFederatedId('https://auth.example.com', identity.subject);
    if (!link) return null; // unknown identity → no access (fail-closed)
    return prisma.user.findUnique({ where: { id: link.userId } }); // roles are THIS app's columns
  }
});
```

The `FederatedAccount` link table (`findByFederatedId` / `linkFederatedAccount` / `unlinkFederatedAccount`, unique on `(issuer, subject)`) ships as an optional repo section in both adapters — see the [Prisma Schema](#prisma-schema); the `issuer` string is *your* stable label for the IdP (canonically its origin — the token carries no `iss` claim, the trust anchor is the one `jwksUrl` you configured). Linking is idempotent for the same user and **refuses** re-linking a pair to a different user (account-takeover primitive); the explicit path is `unlinkFederatedAccount(userId, { issuer, subject })` — **owner-scoped** (one conditional delete; returns `true` iff a link owned by `userId` was removed), so the unlink→re-link two-step cannot take over a foreign identity either. Onboarding flows (invite-based, email-match against `identity.email`, admin-approved) are the consumer's own policy in `resolveUser`. Consumers without a database can resolve users without any repo — `resolveUser` is just a function.

#### Key-rotation runbook (`previousPublicKeys`)

1. Generate the next pair: `const next = await generateES256KeyPair()`.
2. On the IdP, deploy in ONE step: `signingKey: next.privateKey`, and move the **public** JWK of the retiring key into `jwt.previousPublicKeys` (it already carries its `kid`; for a hand-built entry derive it with `computeJwkThumbprint`). The JWKS now serves both keys; old sessions keep verifying, new tokens carry the new `kid`.
3. Consumers converge automatically: an unknown `kid` triggers a (cooldown-limited) JWKS refresh, so the new key propagates within about a minute — no consumer deploy.
4. After the old sessions have expired (`jwt.expiresIn`, default 7d), remove the retired entry from `previousPublicKeys`. Removal is the kill switch: tokens signed by a removed key fail verification everywhere.

#### Limitations (deliberate v1 scope)

- **Revocation blindness:** consumers cannot see the IdP's `tokenVersion` bumps ("log out everywhere"), so an IdP-revoked session stays verifiable at consumers until `exp`. Bound the window with short-lived IdP access tokens (`refreshToken` rotation keeps UX intact) and/or the consumer-side `maxTokenAge` option; emergency global kill = rotate the signing key *without* keeping the old public key.
- **Same trust domain:** cookie-based federation needs a shared parent domain (`cookieDomain`). Cross-domain SSO (redirect-based token handoff, OIDC) is out of scope — as is acting as an OAuth/OIDC provider for third parties (see the auth package non-goals).
- **Logout is IdP-global:** the consumer never clears the shared cookie; "sign out of one app only" does not exist in this model (deny via `resolveUser` instead).
- **Sibling subdomains are full trust peers:** the shared-domain session cookie is readable and settable by every host under `cookieDomain`. A compromised sibling (`evil.example.com`) can (a) **replay** the bearer JWT it receives to any other sibling until `exp`, and (b) **set** a `.example.com` session cookie to pin a victim onto an attacker-chosen — but validly signed — session (cookie-tossing / session fixation). Put only apps you trust as peers under one `cookieDomain`, and give each sibling's CSRF cookie a `__Host-` prefix so it can't be tossed across subdomains.
- **The consumer handle runs no CSRF gate:** unlike `createAuthHandle`, `createFederatedAuthHandle` does not check request origin. SvelteKit's kernel CSRF gate covers form-encoded cross-site POSTs but **not** JSON ones (see [Known Limitations](#known-limitations--security-gaps)), so a cookie-authenticated JSON mutating endpoint on a consumer must enforce its own CSRF defense. The `trustedOrigins: ['*']` resolution from Known Limitations is **off-limits on a federated consumer** unless you build the backstop yourself: there is no `validateCsrf` behind this handle, so `['*']` would leave every cookie-authenticated form mutation of the app unprotected. A federated consumer that must expose its own header-less cross-origin endpoint (own OAuth token endpoint, webhook) first gates its cookie-authenticated mutations by calling the exported `validateCsrf(event.request, event.url)` in its own hook (sequenced before `createFederatedAuthHandle`), exempting its machine routes there. What that hook cannot give is the cookieless handling `createAuthHandle` gives `csrf.exempt`: `createFederatedAuthHandle` hydrates `locals.user` on every request and has no exemption seam, so an exempted route is CSRF-skipped but stays fully session-hydrated — it must therefore not be cookie-authorised (bearer token, secret header, PKCE only), and it still has to be listed in `publicRoutes`, or the federated guard answers 401 before the route runs. What the kernel gate still does to such a route and when its off-switch is safe: [Machine callers](#machine-callers). Only then disable the kernel gate.

### Prisma Schema

The reference schema ships in the package, at `node_modules/@urbicon-ui/auth/prisma/auth-schema.prisma` (`packages/auth/prisma/auth-schema.prisma` in this repo). Ten models: User, Invitation, PushSubscription, Notification, NotificationType, NotificationPreference, Passkey, RefreshToken (rotation; required once `config.refreshToken` is set), TwoFactorBackupCode, FederatedAccount (consumer-side federation link, optional). The User model carries the 2FA columns `totpSecret` (AES-256-GCM-encrypted), `totpEnabled`, `totpConfirmedAt`. The reference schema puts `onDelete: Cascade` on all eight dependent models, `Invitation.invitedBy` included. The delete-account handler **still** removes sent invitations by hand inside its `$transaction`, so an adapter over a schema without that cascade behaves identically; the conformance suite pins both — the hand-written half directly, the rest through `user.delete erases the dependents of every declared repository`.

**A model your client does not have drops its feature to `undefined`.** That is the design — `createPrismaRepos` wires what exists — but the absences differ in how visible they are. `passkey` makes `createPasskeyHandlers` throw at wiring; `refreshToken` makes both wiring entry points throw whenever `config.refreshToken` is set; `twoFactorBackupCode` makes the 2FA handlers answer `feature_unavailable` 400; `notification` is a type error, because the notification service requires that repo. The two that nothing else surfaces are **`pushSubscription`** (web-push delivery is skipped for every notification — the DB row and the SSE event still happen) and **`notificationPreference`** (per-user channel preferences are ignored and notifications go out on every channel the type declares). Every absent model is reported once per Prisma client at factory time. The report defaults to `console` — the same sink `config.logger ?? console` resolves to — so pass `createPrismaRepos(prisma, { logger })` when the app configures its own `config.logger`, to keep the wiring diagnostics with the rest of the auth logs. Note the dedup key is the client, not the logger: whichever call comes first wins, so wire the logger on the first one.

#### Upgrading an existing database

The `Invitation` model gained three columns: `tokenHash` (`@unique`, NOT NULL),
`expiresAt` (NOT NULL) and `emailedAt`. Two of them have no default, and that is
deliberate — an invitation minted under the old rules is redeemable by anyone who
knows the address, which is the hole this closes.

**Every unused invitation becomes invalid. The admins re-invite** — which no
longer needs a mail transport, since the panel now hands back a copyable link.

Adding two NOT NULL columns to a table that already has rows does not work in one
statement, and a constant backfill collides with the unique index. Add them
nullable, fill per row, then tighten — the shape below runs on PostgreSQL as
written and translates directly to other engines:

```sql
-- 1. Unused invitations are the ones that must not survive: under the old rules
--    they are redeemable by anyone who knows the address.
DELETE FROM "Invitation" WHERE "usedAt" IS NULL;

-- 2. Add nullable, so existing (already-redeemed) rows are accepted.
ALTER TABLE "Invitation"
  ADD COLUMN "tokenHash" TEXT,
  ADD COLUMN "expiresAt" TIMESTAMP(3),
  ADD COLUMN "emailedAt" TIMESTAMP(3);

-- 3. Backfill the surviving history. The values are inert — these invitations
--    are spent — but `tokenHash` is UNIQUE, so a constant will not do. Anything
--    per-row and unguessable works; the id is both.
UPDATE "Invitation"
   SET "tokenHash" = 'migrated:' || "id",
       "expiresAt" = "createdAt"
 WHERE "tokenHash" IS NULL;

-- 4. Now the constraints hold.
ALTER TABLE "Invitation"
  ALTER COLUMN "tokenHash" SET NOT NULL,
  ALTER COLUMN "expiresAt" SET NOT NULL;
CREATE UNIQUE INDEX "Invitation_tokenHash_key" ON "Invitation"("tokenHash");
```

Redeemed rows are kept because the admin panel lists them (they render as
`Registered`); their backfilled `expiresAt` sits in the past and their
`tokenHash` matches no real token, so neither is redeemable.

### Adapter Authoring Guide

Persistence is behind a repository interface (`Repositories` in `packages/auth/src/lib/server/adapters/types.ts`). The auth core never talks to a database directly — it talks to `repos.user`, `repos.refreshToken`, etc. This section is the contract for writing your own adapter.

#### What we ship, and the strategy

| Adapter               | Import                                                                           | Use                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Prisma**            | `@urbicon-ui/auth/server/adapters/prisma` (`createPrismaRepos`)                  | Production reference. Copy the models from the shipped `prisma/auth-schema.prisma`.                           |
| **In-memory**         | `@urbicon-ui/auth/server/adapters/in-memory` (`createInMemoryRepos`)             | Dev/test only — heap Maps, single-process, wiped on restart. The five-minute quickstart and the test fixture. `createInMemoryRepos()` is a fresh `createInMemoryStore()` with every repository built on it; take a piece of it — say the refresh-token repository beside a user store of your own — by building that factory on a store handle (`createInMemoryRefreshTokenRepository(createInMemoryStore())`). Repositories on one store share its rows, and `user.delete` erases a user's dependents from every table of that store. The store carries the role type — `createInMemoryStore<'ADMIN' \| 'USER'>()` — and every factory infers it from the handle; a role-typed factory on an untyped store is a type error. |
| **Conformance suite** | `@urbicon-ui/auth/server/adapters/conformance` (`describeRepositoryConformance`) | Not an adapter — the executable contract every adapter validates itself against. Wired to vitest; under another runner import `…/conformance-core` and pass `{ runner: { describe, it, expect } }`. |

We deliberately **do not** ship one official adapter per ORM (Drizzle, Kysely, …). Each interface change would then have to be maintained × N adapters. Instead the interface **is** the contract and the conformance suite makes a third-party adapter _provably_ safe rather than hopefully-safe. A Drizzle worked example is below; ship it in your own app, validate it with the suite.

#### The contract: what every adapter MUST guarantee

The interface JSDoc (`types.ts`) is authoritative; these are the invariants that are easy to get wrong. **Getting any of these wrong is a security bug**, not a style nit — a non-atomic token claim double-spends a single-use reset link; an unscoped delete lets one user silence another's security notifications.

| Operation                                                                                | Guarantee                                                                                                                                                                                                                                                                                                                           | Why                                                                                          |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `refreshToken.revoke(id)`                                                                | Compare-and-set: flip `revokedAt` null→now **only if still live**; return `true` iff this call won (`count === 1`).                                                                                                                                                                                                                 | Rotation race-safety — two concurrent rotations must yield exactly one live successor.       |
| `refreshToken.revokeFamilyForUser(userId, family)`                                       | Revoke the family in one write **scoped to `userId`** (`UPDATE … WHERE family = ? AND userId = ?`); return `true` iff a row the caller owns was revoked, else `false` (→ 404/no-op). Never revoke by `family` alone.                                                                                                                | IDOR — a guessed family id must not let one user sign another user out of their session.     |
| `refreshToken.listActiveByUser(userId)`                                                  | Return only live rows: `revokedAt` null **and** unexpired.                                                                                                                                                                                                                                                                       | The rotation's race tolerance reads it: a spent token presented inside the ten-second grace window passes as the loser of a concurrent rotation only while its family still has a live token here — after `revokeFamily` / `revokeAllForUser` it is refused. A revoked row reported live would keep a "sign out everywhere" open for ten seconds. |
| `user.consumeResetToken` / `consumeVerificationToken`                                    | Single conditional write that clears the token; return the user only on the winning claim, else `null`. Purge an expired token's hash. **A `null` stored expiry reads as _no deadline_** in both shipped adapters — write the expiry the setter handed you, or that token stays claimable forever.                                                                                                                                                                                              | One reset/verify link → one use; no double-spend under concurrency.                          |
| `user.consumeEmailChangeToken`                                                           | Single conditional write that swaps `email`←`pendingEmail` and sets `emailVerified`, clearing the pending fields — only if the token matches, is unexpired, **and** the target address is still free. A collision with another account is a **failed claim** (`null`), never a duplicate email. Purge an expired token's artifacts. | One email-change link → one use; respects `email` uniqueness under concurrency.              |
| `invitation.findByTokenHash(hash)`                                                       | Look up by SHA-256 of the token. Returns used and expired rows too — the handler tells the three cases apart. | This is the registration gate; knowing an address is not.                                    |
| `invitation.markEmailed(id, at)`                                                          | Record that the invite mail went out. No-op for a missing id.                                                | `emailedAt` is what allows `autoVerifyInvited` to skip verification.                          |
| `invitation.markUsedIfUnused(id)`                                                        | CAS: flip `usedAt` null→now; `true` iff this call won.                                                                                                                                                                                                                                                                              | One invitation → one registration.                                                           |
| `backupCode.consumeIfUnused(userId, hash)`                                               | Single conditional write scoped to `userId` that flips an unused code to used; `true` iff this call won. Never `SELECT` then `UPDATE`.                                                                                                                                                                                              | One backup code → one redemption; no cross-user redemption (IDOR).                           |
| `user.incrementTokenVersion`                                                             | Atomic `increment`, never read-modify-write.                                                                                                                                                                                                                                                                                        | Parallel "log out everywhere" must not lose an increment.                                    |
| `user.recordFailedLogin(id, lock?)`                                                      | Atomic `increment`; read the new count from the write. The threshold and the lock instant arrive **as values** (`lock.maxAttempts`, `lock.lockedUntil`, resolved by the login handler): compare against the one, store the other verbatim — never a threshold or duration of your own; `lockedUntil` is stored at least to the second, and the suite tolerates rounding under one second. Set the lock with a write **guarded** on the DB-side count (`failedLoginAttempts >= lock.maxAttempts`), not the value just read. Stamp the attempt's time, and hand it back as `lastFailedAt` from `getFailedLoginAttempts`. A store that cannot keep that column returns `null` there — never a stand-in timestamp. | Lockout must not under-count under credential stuffing, nor set the lock from a stale count. Time arithmetic lives in one place: an adapter with numbers of its own silently overrides the configured policy (the suite hands in values the defaults cannot reproduce). `lastFailedAt` is what dates the count: `null` costs the decay (counters then only fall on a successful sign-in, the pre-decay behaviour), a stand-in would date an old count as current and hand out a fresh set of attempts. |
| `user.resetFailedLoginsIfStale(id, cutoff)`                                              | The clear of `resetFailedLogins`, **guarded in the store**: one conditional write, `UPDATE … WHERE id = ? AND lastFailedLogin <= ?`. A row without a `lastFailedAt` matches nothing. | The login handler decays a count it read as stale, and that write can land after other requests counted failures and set a lock; each of those re-dates the row past the cutoff. Applied unguarded, the decay becomes a way to wipe a live lockout. |
| `passkey.updateCounter(id, n)`                                                           | CAS: bump only if stored `< n`; `false` if nothing advanced. `n === 0` → counterless, touch `lastUsedAt` only.                                                                                                                                                                                                                      | Cloned-authenticator detection.                                                              |
| `notification.markAsRead`/`delete`, `pushSubscription.delete`, `passkey.delete`/`rename` | Scope every mutation to the owner `userId`. A non-owner call must not mutate (no-op **or** throw both fine).                                                                                                                                                                                                                        | IDOR — knowing an id/endpoint must not let an attacker touch another user's row.             |
| `pushSubscription.create`                                                                | Upsert-by-`endpoint`: a row with the same endpoint is updated in place. Reassigning it to a *different* user is **key-gated**: only when the submitted keys equal the stored ones (constant-time on the decoded bytes) — otherwise return `'rejected'` without writing. Never fail on the unique endpoint.                          | Re-enabling push re-sends the browser's *existing* subscription (the duplicate POST is the normal case); key possession is what separates the legitimate user switch from an endpoint-URL takeover. |
| `user.delete`                                                                            | Hard-delete plus dependents: rely on `onDelete: Cascade` for passkeys/tokens/notifications/subscriptions/preferences/backup-codes/federated-links, and delete the invitations the user **sent** by hand as well (portable for a schema whose `invitedBy` FK has no cascade), ideally in one transaction. Conformance pins every dependent whose repository you declare — removed, not merely revoked.                                                 | GDPR erasure must not leave orphans; the sent-invitations half is the part every adapter writes itself. |

The CAS/claim operations are why the interface returns `Promise<boolean>` (or the claimed entity) rather than `void`: the business logic in the core (`rotateRefreshToken`, the register/reset/verify handlers) reads that return value to detect a lost race. Implement each as a **single conditional statement** (`UPDATE … WHERE <still-claimable> RETURNING …`), never `SELECT` then `UPDATE` across an `await` — that gap is the race.

##### Ids: opaque strings, and a miss is never an error

The package never generates or parses an id. It stores what your adapter returned and hands it back verbatim, so any id scheme works — `uuid`, cuid2, ULID, or an integer key rendered as a string. The shipped schema writes `String @id @default(uuid())`, which Prisma maps to `text`; **you may map ids to a native type instead** (`String @id @default(uuid()) @db.Uuid`), and you do not need to change the interface for it, because `id: string` describes the wire value, not the column.

One limit on the shipped Prisma adapter specifically: it passes ids through as the strings the interface gives it, so the column has to be string-shaped (`text`, `uuid`, `citext`). A numeric key needs an adapter that converts at the boundary — the interface still fits (render the number as a string), the shipped adapter does not do the conversion for you.

What a native id type does change is what happens to a value that does not fit it. Ids arrive from outside — a URL segment, a request body — and a `uuid` or `bigint` column rejects an unparsable value with SQLSTATE 22P02 rather than simply matching nothing, on **reads** as much as on writes:

```sql
SELECT … WHERE id = 'not-an-id'   -- text: 0 rows · uuid: ERROR 22P02
```

So the contract has two rules about misses, and both are pinned by the conformance suite:

1. **An id your store cannot represent behaves exactly like an id that is absent** — return `null`, return `false`, no-op. Never throw. Catch that one error on that one argument and turn it into the miss; every other database error must keep propagating. The shipped Prisma adapter does this for you (`idSafeClient` in `adapters/prisma.ts`).
2. **A scoped mutation that matches no row is a no-op, not a throw.** "Not yours" and "not there" are the same answer. In Prisma terms: `updateMany`/`deleteMany`, whose zero-match result is a count, not the `P2025` that `update`/`delete` raise.

Both exist because a miss is a normal answer, and only a throw is not. What the route does with it varies — the session revoke answers `404` (it gets a boolean back), while the notification, passkey and invitation delete routes are deliberately idempotent and answer `200` whether or not a row matched — but an adapter that throws turns every one of them into a `500`, so a malformed id becomes a way to fail those endpoints on demand.

The passkey **rename** route also answers `404` (`passkey_not_found`) for a row that is absent or is not the caller's. What separates it from the deletes above is not that it refuses — the session revoke refuses too — but where its answer comes from: the revoke is handed a boolean by its repository, while `rename` returns `void`, so this route reads the row itself before writing rather than inferring the outcome from a call that cannot report one. A `200` on a rename that did not happen would leave the panel showing a name the store does not hold; a delete's no-op has no such reading, because dropping the row is what the client does either way. The repository's own owner scope is still required: it is the second gate, and the only one a consumer route calling `rename` directly has.

Three further cross-cutting conventions round the contract off. **Owner-first parameters:** every owner-scoped mutation takes `(userId, id, …)` — `markAsRead(userId, id)`, `passkey.delete(userId, credentialId)`, `pushSubscription.delete(userId, endpoint)`, `backupCode.consumeIfUnused(userId, codeHash)`. With two plain strings a swapped call still compiles, so the single fixed order is what keeps a swap greppable. **Pre-normalized emails:** every email reaching a repository (lookups and create data) was already trimmed + lowercased by the package's validation — match and store verbatim, never re-normalize. **Feature tiers:** `UserRepository` is sectioned by feature (core · email verification · password reset · email change · TOTP); an adapter for an app that will never mount a feature may stub that section with throwing methods, since nothing calls a section whose feature is not wired — the shipped adapters implement everything (see the section comments in `adapters/types.ts`).

#### Structural boundary — the `XLike` pattern

`createPrismaRepos<AppRole>(prisma)` accepts the consumer's generated client through a structural interface (`PrismaLike`). Every method returns `Promise<PrismaRow>` where `PrismaRow = any` — a single, intentional `biome-ignore lint/suspicious/noExplicitAny` at the module boundary.

`PrismaLike` lists what the adapter actually calls, so it moves when the adapter does. It now asks for `deleteMany` on `notification` and `passkey`, and no longer asks for the single-row `delete` on `notification`, `passkey` and `invitation`, nor `update` on `notification` and `passkey` — those scoped writes moved to the `…Many` operations (see the id contract above). A generated client satisfies both versions; only a hand-written stand-in needs the two new methods. It buys wider version coverage in exchange: the old calls needed Prisma's extended `WhereUniqueInput` (`update({ where: { credentialId, userId } })`, GA in 5.0), while `updateMany`/`deleteMany` take an ordinary filter.

The reason is concrete: every consumer generates its **own** row shapes from its **own** schema (extra columns, RLS-only fields, soft-delete flags). Typing `PrismaLike.user.findUnique` against our internal `User`/`Passkey` shapes would either reject the consumer's wider rows or force a per-method generic. Both leak the adapter's internal type model into the consumer signature.

Inside the adapter, each method casts the returned row to the **internal** shape via a named `mapX(row)` seam — that's where a missing column surfaces as a TypeScript error, not as a silent `any` at the call site:

```ts
// XLike — permissive at the boundary
type PrismaRow = any;
interface PrismaLike {
  user: { findUnique(args: unknown): Promise<PrismaRow> /* … */ };
  passkey: { findMany(args: unknown): Promise<PrismaRow> /* … */ };
}

// Adapter method — strict at the seam
async function listPasskeys(userId: string): Promise<Passkey[]> {
  const rows = await prisma.passkey.findMany({ where: { userId } });
  return (rows as PrismaPasskeyRow[]).map(mapPasskey); // ← typed conversion
}
```

The `mapX` seams (`mapUser`, `mapPasskey`, `mapRefreshToken`, `mapInvitation`, `mapNotification`, `mapPushSubscription`, `mapNotificationPreference`) live next to each other at the bottom of `prisma.ts`. `mapInvitation` doubles as a security projection: invitation results feed the admin HTTP response directly, so the seam is what keeps `invitedById` (and consumer extra columns) out of the wire format — the conformance suite asserts the exact field set. A new adapter follows the same shape: a structural `XLike` interface with `unknown` args + one permissive return type, narrow casts inside each method, named `mapX(row)` helpers so the conversion is testable. Don't expose generated row types to the consumer — that's what made the original adapter sprout 32 `Promise<unknown>` errors cross-package.

#### Validate it: the conformance suite

Whatever you build, prove it upholds the contract by running the shared suite from a `*.test.ts`. The entry below registers vitest for you; under any other runner import `…/adapters/conformance-core` instead and pass `{ runner: { describe, it, expect } }` — that module imports no runner of its own:

```ts
import { describeRepositoryConformance } from '@urbicon-ui/auth/server/adapters/conformance';
import { createMyAdapter } from './my-adapter';
import { freshTestDatabase } from './test-db';

describeRepositoryConformance('my-adapter', {
  role: 'USER',
  // All seven optional repos, `false` for the ones you do not implement — an
  // omitted key reads as "not implemented" and drops its checks silently.
  capabilities: {
    refreshToken: true,
    passkey: true,
    notification: true,
    pushSubscription: true,
    notificationPreference: true,
    backupCode: true, // set to false if you do not implement this
    federatedAccount: true // set to false if you do not implement this
  },
  // MUST hand back a fresh, isolated repo set per check (wipe schema / new tx).
  setup: () => createMyAdapter(freshTestDatabase())
});
```

The suite drives each atomic claim under `Promise.all` concurrency, asserts exactly one winner, and checks every ownership scope. It is exactly what the shipped Prisma and in-memory adapters run against in CI — including a negative control proving a non-atomic adapter is _rejected_, so the checks have teeth.

Read the suite title: it states how many checks ran out of how many, and names every repository you left undeclared. A check whose repository is undeclared is reported as skipped, so a short capability list is a green run that asserted less than you think — including `backupCode.consumeIfUnused`, whose single-use-under-concurrency guarantee is in the table above. `summarizeConformanceRun(harness)` returns the same numbers if you want to gate on them yourself.

#### Worked example — a Drizzle adapter

The same `XLike` + `mapX` + single-statement-CAS pattern in Drizzle. The trick on every claim is `UPDATE … WHERE <still-claimable> RETURNING …` and treating "0 rows returned" as "lost the race" — Drizzle's `.returning()` gives the row count for free.

```ts
import { and, desc, eq, gt, isNull, lt, lte, ne, or, sql } from 'drizzle-orm';
import type {
  FullAuthUser,
  RefreshTokenRecord,
  RefreshTokenRepository,
  UserRepository /* … */
} from '@urbicon-ui/auth/server';

// The `mapX` seam. The row shape gets its own type and the seam takes it as a
// parameter — that is the half that does the work. Against `row: any` a
// renamed column (`row.token_hash`) type-checks silently; against
// `RefreshTokenRow` it is a `TS2551` right at the seam. The shipped Prisma
// adapter types every seam this way; `any` belongs at the db boundary, not here.
interface RefreshTokenRow {
  id: string;
  userId: string;
  tokenHash: string;
  family: string;
  expiresAt: Date;
  revokedAt?: Date | null;
  replacedById?: string | null;
  createdAt: Date;
  userAgent?: string | null;
  ip?: string | null;
}

const mapRefreshToken = (row: RefreshTokenRow): RefreshTokenRecord => ({
  id: row.id,
  userId: row.userId,
  tokenHash: row.tokenHash,
  family: row.family,
  expiresAt: row.expiresAt,
  revokedAt: row.revokedAt ?? null,
  replacedById: row.replacedById ?? null,
  createdAt: row.createdAt,
  userAgent: row.userAgent ?? null,
  ip: row.ip ?? null
});
// Same seam against `FullAuthUser`, in your own file — declared here so this
// excerpt type-checks standalone.
declare function mapUser(row: any): FullAuthUser;

// `DrizzleLike` is the structural boundary — pass any drizzle db + your tables.
// All nine `RefreshTokenRepository` methods are here, and the annotated return
// type is what keeps them here: leave one out and the factory is a `TS2741`
// naming it. Annotate, never assert — see the note on the user factory below.
export function createDrizzleRefreshTokenRepository(db: any, t: any): RefreshTokenRepository {
  return {
    async create(data) {
      const [row] = await db.insert(t.refreshToken).values(data).returning();
      return mapRefreshToken(row);
    },
    async findByHash(tokenHash) {
      const [row] = await db
        .select()
        .from(t.refreshToken)
        .where(eq(t.refreshToken.tokenHash, tokenHash))
        .limit(1);
      return row ? mapRefreshToken(row) : null;
    },
    async revoke(id, replacedById) {
      // CAS: revoke only while still live; RETURNING gives the win/lose count.
      const won = await db
        .update(t.refreshToken)
        .set({ revokedAt: new Date(), replacedById: replacedById ?? null })
        .where(and(eq(t.refreshToken.id, id), isNull(t.refreshToken.revokedAt)))
        .returning({ id: t.refreshToken.id });
      return won.length === 1;
    },
    async revokeFamily(family) {
      await db
        .update(t.refreshToken)
        .set({ revokedAt: new Date() })
        .where(and(eq(t.refreshToken.family, family), isNull(t.refreshToken.revokedAt)));
    },
    async revokeAllForUser(userId) {
      await db
        .update(t.refreshToken)
        .set({ revokedAt: new Date() })
        .where(and(eq(t.refreshToken.userId, userId), isNull(t.refreshToken.revokedAt)));
    },
    async deleteExpired() {
      const gone = await db
        .delete(t.refreshToken)
        .where(lt(t.refreshToken.expiresAt, new Date()))
        .returning({ id: t.refreshToken.id });
      return gone.length;
    },
    async listActiveByUser(userId) {
      // Live sessions for the session list: non-revoked AND unexpired, newest
      // first. Rotation keeps one live token per family, so one row = one
      // session.
      const rows = await db
        .select()
        .from(t.refreshToken)
        .where(
          and(
            eq(t.refreshToken.userId, userId),
            isNull(t.refreshToken.revokedAt),
            gt(t.refreshToken.expiresAt, new Date())
          )
        )
        .orderBy(desc(t.refreshToken.createdAt));
      return rows.map(mapRefreshToken);
    },
    async revokeFamilyForUser(userId, family) {
      // revokeFamily plus the mandatory owner guard. Without the userId
      // predicate a guessed family id signs another user out (IDOR) — this is
      // the method the session-revoke route calls, and its boolean is what
      // becomes the 404.
      const revoked = await db
        .update(t.refreshToken)
        .set({ revokedAt: new Date() })
        .where(
          and(
            eq(t.refreshToken.userId, userId),
            eq(t.refreshToken.family, family),
            isNull(t.refreshToken.revokedAt)
          )
        )
        .returning({ id: t.refreshToken.id });
      return revoked.length > 0;
    },
    async revokeOtherFamiliesForUser(userId, keepFamily) {
      // "Sign out all other sessions": everything of this user except the
      // caller's own family, in one write.
      await db
        .update(t.refreshToken)
        .set({ revokedAt: new Date() })
        .where(
          and(
            eq(t.refreshToken.userId, userId),
            ne(t.refreshToken.family, keepFamily),
            isNull(t.refreshToken.revokedAt)
          )
        );
    }
  };
}

export function createDrizzleUserRepository(db: any, t: any): UserRepository {
  return {
    // … findById/findByEmail/create/setPasswordResetToken etc. as plain reads/writes …
    async consumeResetToken(tokenHash) {
      const now = new Date();
      // Single conditional claim: clear the token only if it still matches and
      // is unexpired; RETURNING tells us if *this* call won.
      const [claimed] = await db
        .update(t.user)
        .set({ passwordResetToken: null, passwordResetTokenExpires: null })
        .where(
          and(
            eq(t.user.passwordResetToken, tokenHash),
            or(isNull(t.user.passwordResetTokenExpires), gt(t.user.passwordResetTokenExpires, now))
          )
        )
        .returning();
      if (claimed) return mapUser(claimed);
      // Lost the race or expired → purge any expired artifact, return null.
      await db
        .update(t.user)
        .set({ passwordResetToken: null, passwordResetTokenExpires: null })
        .where(
          and(eq(t.user.passwordResetToken, tokenHash), lte(t.user.passwordResetTokenExpires, now))
        );
      return null;
    },
    async incrementTokenVersion(id) {
      // Atomic increment — never read-modify-write.
      await db
        .update(t.user)
        .set({ tokenVersion: sql`${t.user.tokenVersion} + 1` })
        .where(eq(t.user.id, id));
    }
    // … recordFailedLogin (sql increment), consumeVerificationToken (same CAS shape) …

    // The assertion is what lets this excerpt stop at 2 of the 21 methods, and
    // it switches off exactly the check the refresh-token factory above gets
    // from its return type — without the `as`: `TS2740`, 19 missing. Do not
    // carry it into your own file: `createAuthHandle` calls `user.findById` on
    // every authenticated request, so a method you never wrote fails per
    // request rather than at startup. Annotate the return type instead and let
    // the compiler enumerate what is left to write.
  } as UserRepository;
}

// invitation.markUsedIfUnused and passkey.updateCounter follow the identical
// "UPDATE … WHERE <claimable> RETURNING {id}; return rows.length === 1" shape.
```

Wire the per-repo factories into one `Repositories` object (mirroring `createPrismaRepos`), point `describeRepositoryConformance` at it, and you have a _proven_ adapter. `drizzle-orm` stays a `peerDependency`/optional in your app — never a runtime dependency of this package.

### Tests

Unit tests (Vitest, next to the modules they cover) + the E2E flow (`e2e/auth.spec.ts`). Run with:

```bash
cd packages/auth && bunx --bun vitest run   # unit
bun run test:e2e                            # Playwright (from the repo root)
```

**Covered:** crypto primitives (JWT, HMAC, PBKDF2, CBOR, WebAuthn parsing, TOTP/HOTP against RFC 6238/4226 vectors, AES-256-GCM secret encrypt/decrypt), CSRF, rate-limiter, session cookies, validation, notification registry/SSE/push, login handler (incl. 2FA gate), account-management and session-listing handlers, 2FA flow (setup/enable/disable/verify, backup-code single-use, pending-2FA token), E2E core flow (register → protected → logout → refresh rotation → reuse detection). **Adapter conformance** (`adapters/conformance.ts`): the atomic claim/scope guarantees run against the in-memory adapter **and** the Prisma adapter (via a faithful in-memory `PrismaLike` fake) — this is the first real test coverage for `adapters/prisma.ts` — plus a negative control that demonstrably fails a non-atomic adapter. The release history (v0.8.1 – v0.11.0) covers every hardening-1.0 milestone — details in the changelog.

**Still open:** end-to-end attestation/assertion with a real authenticator; conformance against a _real_ database engine (the Prisma path is currently covered via the `PrismaLike` fake, not against a running Postgres).

### Error Contract

Every handler (and the `createAuthHandle` gates) answers errors with one JSON shape: `{ error: string, code: AuthErrorCode, … }` — `error` is human-readable English prose, `code` the stable machine value from the append-only `AUTH_ERROR_CODES` set (never repurposed, only extended). **The status is a property of the code**: one code answers under exactly one HTTP status, everywhere it is sent, so `code` and status can never disagree between two handlers. The 400/401 boundary is one rule: **401 means the request was an attempt to authenticate and the credential it carried was missing or refused**, and everything else about a request answers 400 — a payload the server cannot read, a request that does not match the server's state, and a wrong secret on a request that authenticates nobody. Being signed in is not itself the test. What counts as *the credential it carried* is worth stating, because two server-issued cookies answer differently: a refresh token **is** the credential — the request offers it and asks for a session in exchange — so `missing_refresh_token` and `invalid_refresh_token` are both 401, while the pending-2FA cookie is only a handle naming which challenge is open (the credential is the code in the body), so `no_2fa_challenge` and `two_factor_challenge_expired` are 400 on the same *unauthenticated* endpoint. One seam follows from that: a signature check cannot be told from an expiry check here, so a forged pending cookie answers 400 where a forged refresh token answers 401 — both refused, different class. Where one name would have had to straddle that boundary there are two names: `invalid_code` (2FA sign-in, 401) beside `two_factor_setup_code_invalid` (2FA enrolment, 400), and `passkey_verification_failed` (passkey sign-in, 401) beside `passkey_registration_verification_failed` (passkey enrolment, 400). Statuses outside that pair follow their own HTTP meaning and the rule does not reach them — 403 when an authenticated caller is refused the action, a failed re-auth gate (`current_password_incorrect`) included. Validation failures additionally carry the full field list as `errors`, and the first field message replaces the generic prose. Rate limits answer `429 rate_limited` with a `Retry-After` header, while the per-user cap on concurrent SSE streams answers `429 connection_limit` — a separate code because backoff never clears a connection cap, so a client that treats the two alike retries forever. `<NotificationListener>` reads the stream off `fetch`, so it sees the code: it reports the refusal through `onRefused(code, status)` and does not reconnect on a 4xx (anything reading the log or metrics by `code` tells the two apart the same way). The CSRF gate answers `403 csrf_failed`; the SSE-stream refusals are JSON as of v6.17.0. The push-subscription writes distinguish `push_endpoint_conflict` (endpoint owned by another account — permanent) from `push_subscription_limit` (per-user device cap). The one deliberate exception: `createMeHandler` answers `401 { user: null }` — that is the session-status contract of the client store, not an error report. Every refusal also carries `Cache-Control: no-store`, set by `authError` itself rather than passed at the call site, so a `404 session_not_found` — a status a cache may hold on its own — cannot be replayed to anyone else; `Retry-After` on a `429` rides alongside it.

Localized clients map `code` via `errorMessageFromCode(code, t, error)` (exported from the package root): known code → locale bundle, unknown code or missing translation → the server prose, neither → `undefined` for the caller's own fallback. `validation_error` deliberately prefers the field-level server prose. The pre-built components do this everywhere via their shared `errorTextFromBody` helper. One code is client-synthesized rather than served: `network_error` (the request never reached the server — offline, DNS, CORS), produced by the stores and mapped to `auth.errors.networkError` like any other code.

**The code→locale-key table is bound to the union.** `AUTH_ERROR_MESSAGE_KEYS` (`i18n/error-keys.ts`) is `satisfies Record<AuthErrorCode | 'network_error', …>`, so a new server code that nobody keys is a compile error rather than an English sentence on a localized page; `null` marks the two push codes, whose copy `<PushPermissionPrompt>` owns (`notifications.push.errorConflict` / `errorLimit`). The English `error` prose is **read out of the `en` bundle through that same table** — there is one English text per code, not one for i18n consumers and another for the rest.

**Passkey ceremonies answer uniformly, with one exception.** The failure paths return the bare `passkey_verification_failed` with no prose override: none of those causes is actionable by the end user, and one of them — the sign-counter regression — is a possible-cloned-authenticator signal that must not be readable in a page. The exception is a passkey the server does not hold — deleted from another device while the browser keeps offering it: that answers `passkey_credential_deleted` (401, like every other refused sign-in credential), because a retry presents the same passkey again and the sentence has to name the way out (sign in another way, then set it up again). Every outcome, those two included, is told apart server-side: `config.hooks.onLoginFailed(email, reason)` receives a distinct reason per outcome (`challenge_missing`, `unknown_credential`, `user_handle_mismatch`, `credential_deleted`, `counter_regression`, `user_not_found`, `invalid_assertion`), and `config.logger` receives the WebAuthn detail on the paths a reason cannot carry.

### Known Limitations & Security Gaps

The auth core is **stable** — all initial hardening items are closed; the self-service surfaces added in v5.x (account management, session listing, TOTP 2FA) are initially marked **`beta`**. The complete fix history lives in the monorepo changelog; relevant versions per area are referenced in the feature-matrix tables of the [package README](../README.md).

#### 🛡️ Defense-in-Depth (planned)

- **Monitoring recommendations** — for production deployments, track latency/error rate on the auth handlers; no package code needed, only a doc reference in the consumer app.

#### Account Enumeration & Timing

The package deliberately avoids revealing whether an account exists, via either response content **or** timing:

- **Login** — an unknown email goes through the same PBKDF2 verify as a wrong password (against a discarded dummy hash with the configured work factor) before returning `401`. There is no measurable "user does not exist" shortcut.
- **Forgot password** — always responds with `{ success: true }`; the token write + email send run decoupled from the response (fire-and-forget), so the response time doesn't reveal whether the account exists. Since a failure then no longer surfaces as an HTTP status, it is reported via `config.hooks.onPasswordResetFailed` (+ `config.logger.error`) — hook it into your own error tracker so a broken mail transport doesn't silently lock users out of recovery. **Serverless/edge note:** runtimes that freeze the worker after the response is sent can cut off the downstream work (and its logging/the hook) — use a queue-backed email transport there so delivery stays reliable.
- **Register** — gated on **possession of the invitation token**, and on nothing else. Without a valid token every email returns the same `403 "invitation required"`, registered or not. The more precise `403`/`409` messages are visible only to someone holding a valid unused token, which is admin-minted and not guessable — not a usable enumeration vector, and the clear messages help the legitimately invited person. The token also names its invitee: registering with a different address is refused, so a leaked link cannot be redeemed onto an attacker-chosen account.
- **WebAuthn auth options** — an unknown email returns the same `200` options response (empty `allowCredentials`) as a known one; discoverable/usernameless login works without any email at all.

#### Rate-Limiting, Lockout & Route Scope (deliberate trade-offs)

- **Lockout DoS** — the login rate-limit is **per-IP**, the lockout is **account-based**. An attacker with many IPs (IPv6 rotation, proxy pool) can thereby deliberately lock out someone else's account without tripping their own IP rate-limit. This is the classic lockout trade-off (brute-force protection vs. DoS). If you don't want that, set `lockout: null` (then the per-IP rate-limit alone protects) — but the default deliberately leaves the lockout on, because brute-force protection is the more important risk for most apps. For visibility, consider adding your own monitoring on `lockedUntil` writes.
- **The login limiter brakes failures, not cost** — a correct password refunds the slot its request took, so successful sign-ins from one address are not limited at all, and each of them costs a PBKDF2 run (~38 ms at the default work factor) plus a session establish. An attacker needs one account of their own for that, no one else's password; credential stuffing with a high hit rate reads the same way, every valid pair being a free session. Deliberately not capped here: a per-IP counter has never stopped a distributed cost attack, and one account hammering from one address is what an edge rate-limit (reverse proxy, WAF) is for — so a second per-IP counter that successes do not refund would be surface without protection. If the cost matters to you, brake at the edge; do not lower `password.pbkdf2Iterations` for it.
- **At the defaults the limiter answers before the lockout does** — both thresholds are five, and the per-IP limiter runs at the top of the handler, before the account is looked up. Six wrong passwords from one address are answered `401 ×5, 429`: the fifth failure did set `lockedUntil`, but that address never sees the `423`. The same six attempts from six addresses are answered `401 ×5, 423`. The two brakes therefore divide the work by *who* is attacking: the limiter is per IP and stops a single source, the lockout is per account and stops the distributed attempt the limiter cannot see — which is also why it is the DoS-prone one of the pair. (Both sequences are pinned against the real handler and the in-memory adapter in `login.test.ts`.)
- **Failed attempts decay, and that sets the sustained guess rate** — an attempt stops counting once it is `lockout.decayMinutes` old (default 60), so typos on separate occasions never add up to a lock. The window is also the attacker's budget: every further failure re-dates the count, so waiting it out buys `maxAttempts` guesses per window — **5 per hour at the defaults**, against the ~4.3 per hour a stuck-at-threshold counter allows (one guess per `durationMinutes`, each re-locking the account). Shortening it multiplies that rate — 15 minutes would allow 20 per hour — and buys a user nothing an hour of quiet does not. (All three numbers are simulated against the real handler on a 12-hour clock in `login.test.ts`, not derived on paper.) `decayMinutes: 0` is **refused when the login handler is created**: a zero window resets the counter before every increment, so it would read as "no decay" and act as "no lockout" — run without a lockout via `lockout: null` instead. The decay needs `lastFailedAt` from `getFailedLoginAttempts`: an adapter that returns `null` there gets no decay, never a lost lockout. Its reset is `resetFailedLoginsIfStale`, guarded in the store on that same timestamp: a reset that lands after other requests have counted failures and set a lock matches nothing, so it cannot end that lock — the conformance suite fails an adapter that applies it unguarded.
- **The lockout bounds what follows a burst, not the burst** — the counter is read, then written, once per request, so requests that arrive together all pass the lock check before any of them has been counted: a simultaneous burst reaches the password check in full, with or without the decay window (pinned at twelve in `login.test.ts`, measured unchanged at fifty). That is what the per-IP `rateLimit.login` is for; the lockout limits the *next* attempts.
- **2FA verify rate-limit is per-IP, not per-account** — the public `/2fa/verify` endpoint is limited per-IP like login (`rateLimit.twoFactor`, strict default), not per-account — consistent with the package philosophy (account-level limits are themselves DoS-prone and opt-in). A distributed-IP attack would additionally need the victim's password (to set the pending-2FA cookie); with a ±1 window (10⁶ codes) + ~5-min TTL this remains practically hopeless. A per-account limiter is a deliberate later option.
- **The UV bit is self-asserted, not attested** — `attestation: 'none'` is hard-wired in the generated registration options, so the relying party never receives an authenticator certificate. `requireUserVerification` therefore verifies that the *credential itself signed* a UV flag, not that a genuine authenticator model performed a genuine PIN or biometric check; software or a modified authenticator can set the bit. It still moves the practical threat model — a stolen hardware key that demands its PIN is no longer a one-tap login — which is why passkey logins skip the TOTP gate only under enforced UV. Read the guarantee as "the credential claims user verification", not as a proof of it. Attestation-based authenticator allow-listing is out of v1 scope.
- **TOTP replay within the same time window** — v1 relies solely on the strict verify rate-limit. A stored `lastUsedStep` that prevents re-redeeming the same code within its validity (±1 period) is noted as a later hardening.
- **`publicRoutes` replaces the defaults, and a string entry is a prefix** — passing the option drops the built-in list rather than adding to it. That list is exported as `DEFAULT_PUBLIC_ROUTES` (read it there; it is not transcribed here), and `'/api/auth/'` is in it — so an override that omits it guards the app's own sign-in: an unauthenticated `POST /api/auth/login` gets `401 not_authenticated` instead of a session. Spread the constant to extend — `publicRoutes: [...DEFAULT_PUBLIC_ROUTES, '/pricing']` — and replace wholesale only for a handle scoped to routes that mount no auth endpoints of their own. A string matches with `startsWith`: `'/api/auth/'` makes **all** subroutes below it public, `'/pricing'` also publishes `/pricing-admin` and `/pricing/internal`, and `'/'` makes the **entire app** public — the obvious spelling of "my landing page is public" turns the guard off completely, and the handle warns about it at construction. One pathname alone is the object form, `{ path: '/', exact: true }`: the landing page, and nothing under it. A list held in a variable first (`const routes = [...]; createAuthHandle({ publicRoutes: routes })`) needs `as const` or the annotation `PublicRoute[]` — TypeScript otherwise widens `exact: true` to `boolean` and the assignment is a type error; an inline list needs nothing. The same two forms apply to `createFederatedAuthHandle`. Keep the list narrow, and don't place protectable app routes below a public prefix.
- **Remote functions are guarded by `event.isRemoteRequest` (+ a `/remote` POST check), not `publicRoutes`.** For SvelteKit Remote Functions (`kit.experimental.remoteFunctions`) the pathname the guard sees is **client-controlled**, via either of two transports: **(1)** the `/_app/remote/…` calls (`query` / `command` / JS-enhanced `form`) — SvelteKit overwrites `event.url.pathname` from the `x-sveltekit-pathname` header *before* the `handle` hook runs; a plain `query` is even a **GET** (payload in `?payload=`), so the kernel's non-`GET` cross-site block doesn't catch it either; and **(2)** the no-JS `<form action="?/remote=…">` fallback — dispatched through the page pipeline from the `/remote` search param, decoupled from the pathname, with `event.isRemoteRequest` left **`false`**. Either way a spoofed (or genuinely) public route such as `/auth/login` would let an unauthenticated remote call run without a session and leak every reachable row. `createAuthHandle` **default-denies** (`401`) both: keyed on the unspoofable `event.isRemoteRequest`, and — for the fallback — a `POST` carrying a truthy `/remote` action param (mirroring SvelteKit's own dispatch gate; a normal action named `remote` serializes to an empty `?/remote` and is correctly left to the path guard). Set `allowUnauthenticatedRemote: true` **only** if you deliberately expose public remote functions — you then own their authorization (check `event.locals.user` inside each). **Defense-in-depth:** even with the guard active, prefer an explicit `event.locals.user` (+ per-user ownership) check inside each remote function rather than relying on the handle alone — the guard is a backstop, not a substitute for per-function authorization.
- **SvelteKit's built-in `csrf.checkOrigin` is a separate gate that runs _before_ this package's check.** SvelteKit's request kernel performs its own Origin-CSRF check *before* the `handle` hook runs (`@sveltejs/kit` → `src/runtime/server/respond.js`), so `csrf.exempt` cannot reach it: a cross-origin, form-encoded `POST` — an OAuth 2.1 token endpoint, a third-party webhook — is answered `403 "Cross-site POST form submissions are forbidden"` before your hook (and therefore this package's `validateCsrf`) ever runs. It fires on form content types only, cannot be disabled per route from a hook, admits no header-less caller through `trustedOrigins`, and is **skipped under `vite dev`, never in a build** (guaranteed by the package's `@sveltejs/kit ^2.70.1` peer range — older Kits compiled the gate out of non-production-`NODE_ENV` builds, [sveltejs/kit#16313](https://github.com/sveltejs/kit/pull/16313)), so the 403 typically first surfaces *after deploy*, never in local development. Which callers it stops, the build-time off-switch (`kit.csrf: { trustedOrigins: ['*'] }`) and the two conditions under which disabling it is safe: [Machine callers](#machine-callers). The exemption from *this* package's gate is `csrf.exempt` on `createAuthHandle` — never a route mounted around the hook.
- **SSE presence is process-local** — `createSSEManager` registers connections in this process only; there is no cross-instance seam. On multi-instance/serverless deployments, `isOnline` false-negatives make `send()` skip the live SSE event for users connected to another instance and fall back to push (delivery still happens, via the heavier channel, provided a push subscription exists), and `recipients: 'online'` broadcasts only reach the users connected to the instance running `send()`. Treat the notification system as single-instance until a shared presence backend exists — the same class of assumption as the in-memory rate-limit store.
- **In-memory adapter grows unbounded** — `createInMemoryRepos` doesn't clean up notifications/push subscriptions and doesn't call `deleteExpired` for refresh tokens automatically. `user.delete` is not one of these: every repository built on one `createInMemoryStore()` shares its tables, and the delete removes a user's dependent rows from all of them, the same end state the Prisma adapter gets from `onDelete: Cascade` — both are pinned by the conformance suite. This is fine for the declared dev/test scope; for long-lived processes use a persistent adapter.
- **What an authenticated write is limited for, and what it is deliberately not limited for** — the package's limiters guard three things: **state growth** (a write that can create or reassign rows), **secret verification** (a write that checks a secret the session does not itself hold — the current password on a hijacked session, a refresh token, a pending-2FA code — and is therefore a guessing target) and **third-party cost** (a write that sends a mail or a push). Three they deliberately leave alone: a write that only changes or removes rows the caller already owns, which is bounded by what the caller owns; a read; and anything behind the consumer's **`authorize` gate**, which outranks the three guarded clauses — a write may create rows and send mail and still carry no limit here, because behind a gate this package does not define, who may do it and how often is the consumer's policy. The request rate of an authenticated caller is not this package's brake — that is the edge's, the same line the login limiter already draws above ("brakes failures, not cost"). A list of the limits that exist is therefore not a list of what is covered, so the table below is both halves at once. The unauthenticated per-IP flows — login, register, the token flows, `/2fa/verify`, passkey authentication — are not in it; their keys and numbers are the table under [Stage 1 — Quickstart (dev)](#stage-1--quickstart-dev).

| Authenticated write                                                                                                                                                                                                       | Limit                                    | Key     | Clause                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `createChangePasswordHandler` `POST`                                                                                                                                                                                      | `rateLimit.changePassword`, 5 / 15 min   | IP      | secret verification                                                                                                                                                                                                      |
| `createChangeEmailHandler` `POST`                                                                                                                                                                                         | `rateLimit.changeEmail`, 5 / 15 min      | IP      | secret verification, third-party cost                                                                                                                                                                                    |
| `createDeleteAccountHandler` `POST`                                                                                                                                                                                       | `rateLimit.deleteAccount`, 5 / 15 min    | IP      | secret verification                                                                                                                                                                                                      |
| `createTwoFactorHandlers` `disable`                                                                                                                                                                                       | `rateLimit.twoFactorDisable`, 5 / 15 min | IP      | secret verification                                                                                                                                                                                                      |
| `createRefreshHandler` `POST`                                                                                                                                                                                             | `rateLimit.refresh`, 30 / min            | IP      | secret verification                                                                                                                                                                                                      |
| `createPasskeyHandlers` `registrationVerify`                                                                                                                                                                              | `rateLimit.passkeyRegister`, 10 / min    | user id | state growth (the call that creates the credential row)                                                                                                                                                                  |
| `createPreferencesHandler` `PUT`                                                                                                                                                                                          | its own `rateLimit` option, 30 / min     | user id | state growth                                                                                                                                                                                                             |
| `createPushSubscriptionHandler` `POST`                                                                                                                                                                                    | its own `rateLimit` option, 10 / min     | user id | state growth                                                                                                                                                                                                             |
| `createPasskeyHandlers` `registrationOptions`                                                                                                                                                                             | none                                     | —       | overwrites the caller's own challenge entry (keyed by user id)                                                                                                                                                           |
| `createPushSubscriptionHandler` `DELETE`                                                                                                                                                                                  | none                                     | —       | removes a row the caller owns                                                                                                                                                                                            |
| `createNotificationsHandlers` `read` / `readAll` / `item.DELETE`                                                                                                                                                          | none                                     | —       | changes or removes rows the caller owns                                                                                                                                                                                  |
| `createPreferencesHandler` `GET`, `createNotificationsHandlers` `list`, `createSessionsHandlers` `list`, `createPasskeyHandlers` `list`, `createMeHandler`, `createInvitationHandlers` `GET`, `createStreamHandler` `GET` | none                                     | —       | reads                                                                                                                                                                                                                    |
| `createUpdateProfileHandler` `POST`                                                                                                                                                                                       | none                                     | —       | changes the caller's own row                                                                                                                                                                                             |
| `createSessionsHandlers` `revoke` / `revokeOthers`                                                                                                                                                                        | none                                     | —       | revokes the caller's own sessions                                                                                                                                                                                        |
| `createLogoutHandler` `POST`                                                                                                                                                                                              | none                                     | —       | ends the caller's own session                                                                                                                                                                                            |
| `createPasskeyHandlers` `item.PATCH` / `item.DELETE`                                                                                                                                                                      | none                                     | —       | changes or removes a row the caller owns                                                                                                                                                                                 |
| `createTwoFactorHandlers` `setup`                                                                                                                                                                                         | none                                     | —       | changes the secret on the caller's own row                                                                                                                                                                               |
| `createTwoFactorHandlers` `enable`                                                                                                                                                                                        | none                                     | —       | checks a code against a secret the same session was just handed by `setup` — nothing to guess (what its absent limiter costs an operator is in the [key-rotation runbook](#key-rotation-runbook-twofactorencryptionkey)) |
| `createInvitationHandlers` `POST`                                                                                                                                                                                         | none                                     | —       | behind the consumer's `authorize` gate (who may mint, and how many, is decided where the gate is)                                                                                                                        |
| `createInvitationHandlers` `DELETE`                                                                                                                                                                                       | none                                     | —       | behind the consumer's `authorize` gate (who may revoke is decided where the gate is)                                                                                                                                     |

What `rateLimit.passkeyRegister` bounds, and why no per-user credential cap stands beside it, is stated once beside the number itself: `RATE_LIMIT_DEFAULTS.passkeyRegister` in `server/security-defaults.ts`.

#### Production-Readiness Checklist

Before production use outside of controlled environments:

**Package setup (one-time):**

- [ ] Persistent-storage adapter for challenges, refresh tokens, and rate-limits configured (at >1 instance). Interfaces/adapters since v0.8.5 – v0.11.0.
- [ ] CSRF double-submit decided (`config.csrf = { doubleSubmit: true }`, since v0.8.4). Enable it **only when every cookie-authenticated mutation sends the `x-csrf-token` header** — i.e. all mutations go through this package's client stores/components or `csrfFetch`. SvelteKit **Remote Functions** (`command` / `form`) and native no-JS form posts send no such header (the remote transport is Kit-internal — you cannot attach one), so with those in play `doubleSubmit: true` would 403 every such mutation: keep it `false` and rely on Layer 1 — the Origin gate holds for a same-origin deployment on the default `SameSite=Lax` cookies, provided nothing in front of the app rewrites or injects the `Origin` header; remote-function mutations additionally sit behind Kit's own non-configurable strict same-origin remote gate. Layer 2's real added value is exactly that residue: an Origin-normalizing proxy/gateway combined with `cookieSameSite: 'none'` lets a cross-site request *satisfy* the Origin check, while the token cookie stays unreadable to the attacker — if that is your deployment, don't drop Layer 2; restructure the mutating surface so it can send the header. Optionally also `useHostPrefix: true` (HTTPS-only) against subdomain cookie injection — then also set `useHostPrefix: true` in the `csrf` config of the client stores/components.
- [ ] Refresh-token rotation enabled (`config.refreshToken = { … }`, since v0.11.0) — non-breaking, recommended in production.

**Deployment:**

- [ ] HTTPS enforced (cookies are already `secure: true`; HSTS is then set automatically by `createAuthHandle`).
- [ ] CSP adapted to the app (`config.securityHeaders.csp`) — the default `frame-ancestors 'none'` blocks only framing; a complete policy is app-specific.
- [ ] Monitoring for auth-handler latency and error rate active.
- [ ] Incident runbook for a compromised JWT secret prepared (`keyId` + `previousSecrets` allows uninterrupted rotation).
- [ ] Incident runbook for `twoFactor.encryptionKey` prepared — it has **no** overlap mechanism, so a rotation locks out every TOTP user *and* blocks their re-enrolment; a backup code — or a passkey, which is not TOTP-gated — is the way back in (see the [key-rotation runbook](#key-rotation-runbook-twofactorencryptionkey)). Keep the key backed up separately from the database, and alert on the `2fa-enable` / `2fa-verify` decryption errors in `config.logger` — they never reach `handleError`.
- [ ] **Machine callers declared** — every cron, OAuth-token or API-key route that posts without an `Origin` header is listed in `csrf: { exempt }` on `createAuthHandle` and authenticates each request itself (it sees `locals.user === null` by design). For the form-encoded ones (an OAuth 2.1 token endpoint, a webhook): `kit.csrf: { trustedOrigins: ['*'] }` set in `svelte.config.js` — the build-time off-switch for SvelteKit's kernel gate, which a *specific* origin list cannot open for a header-less caller — and confirmed every cookie-authenticated mutating route still flows through the auth handle ([Machine callers](#machine-callers)). The kernel CSRF check never runs under `vite dev`, so this won't show up before a deployed build.
- [ ] If you run **`createFederatedAuthHandle`** (SSO consumer): the kernel CSRF gate stays **on** — the `trustedOrigins: ['*']` resolution above is off-limits there (no `validateCsrf` backstop behind the federated handle) unless you gate cookie-authenticated mutations yourself via the exported `validateCsrf` in your own hook (see [Federated Identity](#federated-identity-sso)).
- [ ] If you use **SvelteKit Remote Functions** (`kit.experimental.remoteFunctions`): confirmed each remote function checks `event.locals.user` (and per-user ownership) itself — the handle default-denies unauthenticated remote requests, but per-function checks are defense-in-depth. Only set `allowUnauthenticatedRemote: true` for deliberately public remote functions (see [Known Limitations](#known-limitations--security-gaps)).

**Your own tests:**

- [ ] E2E passkey flow against a real authenticator (registration + authentication) — the shipped tests cover the session core flow, the WebAuthn crypto at the parser level, and the auth-ceremony plumbing at the handler level: the challenge is bound to an opaque per-ceremony handle (HttpOnly cookie between `authentication-options` and `authentication-verify`), enabling both **discoverable/usernameless** _and_ email-first login. An end-to-end signature check against real hardware remains on the consumer side. **Your own client:** the cookie from the `authentication-options` response must be sent along with the `authentication-verify` request — `fetch`/`csrfFetch` do that same-origin automatically; the shipped `LoginPage` is already correct.

### Consumer Migration

Lifting an existing SvelteKit app onto `@urbicon-ui/auth` roughly follows the staged setup progression from [README → Getting Started](../README.md#getting-started) (Quickstart → Production → Advanced). The detailed migration order and app-specific steps (e.g. schema diffs, role mapping, replacing existing stores) belong in the respective consumer repo — not in this package.