@toa.io/extensions.configuration 1.0.0-alpha.272 → 1.0.0-alpha.274

package/ui/.agents/skills/antcn/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: antcn
+description: Ready-to-install Svelte components and utils. You MUST use these components to compose your UI unless you have a very good reason to write your own.
+---
+
+# antcn — Svelte component registry
+
+Svelte components and utilities at `https://cn.ants.dev`.
+
+## Install
+
+```sh
+npx shadcn-svelte add -y -o https://cn.ants.dev/r/<name>.json
+```
+
+If the project has no `components.json`, run `npx shadcn-svelte init` first.
+
+## Catalog
+
+**Before building any Svelte component or utility, scan this catalog.** If something here fits — even loosely — install it and adapt it to the project instead of writing your own. These are the building blocks; reuse beats rebuild.
+
+One line per item below. **Before installing, read its full reference at `references/<name>.md`** (bundled next to this skill — a plain local file read, no network): props/API, dependencies, and post-install wiring to use it correctly in one pass. The one-liner is for recognizing a match; the reference is the documentation you act on. The CLI merges CSS but not layouts, so the reference also lists the manual steps it can't do for you (e.g. `onNavigate(navigate)` in the root layout, peer npm packages).
+
+Each one-liner describes **what the item lets you do** and **when to reach for it**.
+
+`tools` and the shared global CSS usually arrive **transitively** via another component's `registryDependencies` (e.g. `hold` pulls `tools`) — install them standalone only when you want the utility set or theme tokens on their own.
+
+The catalog has two tracks: **Components** (presentational UI blocks, inline English, no backend) and **Solutions** (vertical app-domain slices that ship service logic, UI, and their own i18n, installed under your `@/<name>`).
+
+## Components
+
+- **shell** — mobile-first app shell with bottom navigation, section tabs, nested-route back behavior, and slots for headers and toolbars. Reach for it when building a PWA-style layout with fixed nav and contextual actions.
+- **stack** — collapsible card stack with expand/collapse animation and an optional toolbar. Reach for it when several cards should peek behind the first and fan out on tap.
+- **scrollable** — horizontal snap scroller with scroll-to-index, bleed-to-viewport, and infinite loop. Reach for carousels, pickers, and edge-to-edge horizontal lists.
+- **panel** — tappable list row with left/right/icon slots and swipe-reveal trailing actions. Reach for contact lists, settings rows, or anywhere a row needs inline actions.
+- **fullscreen** — tap-to-expand overlay with morph animation, optional toolbar, and programmatic show/hide. Reach for it when a thumbnail or card should open into an immersive fullscreen layer.
+- **dismissable** — swipe-to-dismiss wrapper with optional slide-out animation and programmatic dismiss/remove. Reach for notification stacks, banners, or flick-away cards.
+- **dropdown** — action menu with anchor positioning, morph animation, and nested layers. Reach for toolbar overflow, contextual actions, or multi-step pickers.
+- **input-form** — inline text field that auto-saves on blur or Enter when the value changed. Reach for editable display names and other single-field edits without a save button.
+- **hold** — hold-to-confirm button for dangerous actions: fires only after a brief hold, with countdown feedback. Reach for it instead of a confirmation dialog when inline confirmation is enough.
+- **clipboard** — copy-to-clipboard button with loading and success states; supports async text. Reach for copying IDs, invite links, or other strings without a separate input.
+- **share** — share button with clipboard fallback when native share is unavailable. Reach for invite links and other share payloads on mobile-first flows.
+- **selector** — card-style single- or multi-choice picker with radio or checkbox indicators. Reach for plan pickers, settings toggles, or tappable option lists.
+- **taptap** — multi-tap gate that fires only after N consecutive taps within a gap. Reach for accidental-tap protection on destructive or rare actions.
+- **shake** — brief horizontal shake on a bound wrapper. Reach for obvious validation failures on small forms where error copy adds little value.
+- **tools** — shared helpers for dates, currency, media queries, view transitions, navigation glue, and common browser utilities. Reach for the same helper set antcn components rely on.
+- **globals** — shared theme tokens and Tailwind globals for constructive color, standalone/tim variants, and morph transitions. Reach for consistent styling across antcn components.
+
+<!--
+  Fixed catalog order: tools, globals, hold, shell. Append one line per newly registered item as `**<name>** — <capabilities>. Reach for <use case>.` Capabilities only — what the consumer can do with it, not how it's built. Avoid: internal structure (sub-components, exports, file layout), dependencies (shadcn, sibling items, npm/libs), function/store/type names, props, install commands, transitively-pulled notes. Those live in references/<name>.md (auto-generated from the item README by the reference-bundler).
+-->
+
+## Solutions
+
+Vertical app-domain slices (auth, notifications, realtime, …) that ship service logic, UI, and their own i18n. Install the same way; the whole `svc/` + `ui/` + `ui/intl/` tree lands under your `@/<name>`:
+
+```sh
+npx shadcn-svelte add -y -o https://cn.ants.dev/r/<name>.json
+```
+
+Solutions that ship i18n read a **host svintl mount** at `$lib/intl` — the consumer owns it (the CLI can't scaffold it). Set it up once: run `npx intl hola`, then have its `index.ts` export a persisted `selected` writable plus `locale`, `locales`, `dictionaries`, and the `Grammar` type. Each Solution uses a subset, and its bundled `ui/intl/` copy derives from this host.
+
+Then reconcile the Solution's dictionary to your locale set:
+
+```sh
+npx intl import <name> src/@/<name>/ui/intl
+```
+
+Each Solution's reference (`references/<name>.md`) lists the `$config` fields it needs and any consumer wiring (e.g. interfaces to extend). Sibling Solutions arrive automatically via `local:` dependencies.
+
+### Grammatical form (cross-cutting i18n)
+
+Some languages word a message by the subject's grammatical gender (`{name} added` vs Russian `добавил`/`добавила`). This is a translation concern that spans the svintl host, the account, and your UI — owned by no single Solution. Enable it once with `npx intl genders he she none` (the listed tokens become a generated `Grammar` union in `$lib/intl`; the last is the neutral/fallback). Gender-varying dictionary entries then become functions taking the gender as their **last** argument — `(name, gender) => …`, or just `(gender) => …` when the phrase has no other placeholders. The subject's gender is stored per account as `grammar?: Grammar | null` (antcn's `iam` carries it on `Echo`); pass _that account's_ value into the dictionary function — the subject's gender, not the viewer's. Full mechanics, consumption modes, and examples: `references/grammatical-form.md`.
+
+<!--
+  Append one line per registered Solution as `**<name>** — <capabilities>. Reach for <use case>.` Same rule as Components — consumer-facing capabilities, not internal structure, dependencies, API names, or wiring. Details live in references/<name>.md.
+-->
+
+- **net** — shared API client and query helpers for declaring backend resources. Reach for any feature or Solution that talks to your API.
+- **passkeys** — register, list, and revoke passkeys for the signed-in account. Reach for passwordless login or a passkey manager screen.
+- **iam** — complete sign-in and account management: password, OTP, passkeys, Google/Apple OIDC, session sync, expiry refresh, and credential management including cross-device QR transfer. Reach for a full authentication surface.
+- **locale** — let users pick their language via a horizontal scroller of native names or a compact settings dropdown. Reach for in-app locale switching.
+- **hints** — track per-user onboarding hints: show once, snooze, or dismiss permanently. Reach for first-run tips, permission prompts, and one-shot nudges.
+- **realtime** — live server-pushed events with auto-reconnect tied to sign-in, a debug dashboard, and server-clock sync. Reach for UI that must react to backend push in real time.
+- **transmission** — push notification permission, subscription, per-domain toggles, and ready-made permission/scopes UI. Reach for web or mobile push with user-configurable topics.
+- **analytics** — GA4/GTM event tracking and a cookie-consent banner. Reach for analytics or ads conversion measurement with GDPR-style consent.
+- **bridge** — talk to a native app from the WebView: detect platform, drive native purchases, and receive native push. Reach for hybrid app integration.
+- **fragments** — single-use URL hash tokens for deep links and payment redirects that won't re-fire on reload. Reach for one-time return URLs.
+- **geo** — look up the visitor's consent zone to decide whether a cookie banner is required. Reach for privacy-jurisdiction gating before loading trackers.
+- **payments** — subscription paywall with tier selection, benefits, and checkout via App Store, Google Play, or Stripe. Reach for selling subscriptions in-app.
+- **system** — user-controlled PWA updates surfaced as a version card that tracks the running build, shows live download progress, and offers a one-tap install once an update is ready, plus a browsable localized changelog history the app version derives from, an app-wide escape from insecure in-app webviews out to the system browser, and CI that auto-generates translated release notes and publishes tagged releases on merge. Reach for the PWA update, release-notes, and webview-escape layer of an installed app.

package/ui/.agents/skills/antcn/references/analytics.md

@@ -0,0 +1,78 @@
+# analytics
+
+Consent-first GA4 + Google Tag Manager analytics. A typed `track()` dual-dispatches to a GA4 property (via a `gtag` shim) and/or a GTM container; a Consent Mode v2 cookie banner collects consent before any non-essential storage, shown only to visitors inside a prior-consent jurisdiction (resolved through `geo`) and auto-granting elsewhere. Events are an open interface each domain owns and augments.
+
+## Environment
+
+Configured through `VITE_*` env vars (read at build via `import.meta.env`, so no custom `envPrefix` is needed). Set whichever delivery you use — at least one `id` must be present or the whole stack no-ops:
+
+| Var                | Example        | Notes                                                                 |
+| ------------------ | -------------- | --------------------------------------------------------------------- |
+| `VITE_GA_ID`       | `G-XXXXXXXXXX` | GA4 Measurement ID. When set, events go to GA4 via `gtag` (takes priority). |
+| `VITE_GTM_ID`      | `GTM-XXXXXXX`  | GTM container ID. Used for `track()` only when `VITE_GA_ID` is unset; otherwise the container still sees gtag's push as a Custom Event. |
+| `VITE_GTM_AUTH`    | `abc123…`      | Optional — GTM Environment snippet auth param. Empty for the Live environment. |
+| `VITE_GTM_PREVIEW` | `env-3`        | Optional — GTM Environment snippet preview param. Empty for Live.     |
+
+## Notes
+
+- **Bootstrap with `rc()`.** Run it once on app start (see Usage). It emits the `consent default` + `platform` user-property commands, resolves the consent zone, then either auto-grants (out of zone), re-applies a stored choice, or opens the banner. It no-ops when neither id is set.
+- **Page-view title.** Pass `<Analytics title={…}>` the resolved page title so the `page_view` event isn't subject to the SPA `document.title` race.
+- **Re-opening consent.** `<Manage>` is an optional "Cookie settings" button (place it in a footer or settings row); it renders only inside a prior-consent zone once a choice has been made.
+- **Banner copy.** Ships its own svintl mount in the registry's four locales with neutral copy. After install, reconcile it to your locale set: `npx intl import analytics src/@/analytics/ui/intl`. The body links to `/privacy/` — point it at your policy via the mount.
+- **Native iOS shell.** `settle('ios_shell')` resolves to `denied` (App Store privacy expectations); adjust the platform branch in `rc.ts` if your wrapper differs.
+
+## Usage
+
+Bootstrap once on app start — resolves the consent zone and opens the banner when consent is required:
+
+```ts
+import { rc } from '@/analytics/rc'
+
+onMount(rc)
+```
+
+Mount the loaders and banner near the app root. `<Analytics>` injects the gtag.js / gtm.js loaders and fires a `page_view` on every SPA navigation; `<Consent>` renders the banner while consent is pending:
+
+```svelte
+<script lang="ts">
+  import { Analytics, Consent } from '@/analytics/ui'
+  import { page } from '$app/state'
+</script>
+
+<svelte:head>
+  <Analytics title={page.data.title ?? document.title} />
+</svelte:head>
+
+<Consent />
+```
+
+Declare your domain's events by augmenting the open `Events` interface — keeping event names and parameter types owned by the domain that fires them (dependency direction domain → analytics). `@/analytics` itself owns only `page_view` and `purchase`:
+
+```ts
+// src/@/your-domain/svc/events.ts
+declare module '@/analytics' {
+  interface Events {
+    sign_up: { method: 'passkey' | 'password' | 'google' | 'apple' }
+  }
+}
+```
+
+Then fire it, type-checked, from anywhere:
+
+```ts
+import { track } from '@/analytics'
+
+track('sign_up', { method: 'passkey' })
+```
+
+## Props
+
+### `<Analytics>`
+
+| Prop    | Type     | Default | Notes                                                                        |
+| ------- | -------- | ------- | ---------------------------------------------------------------------------- |
+| `title` | `string` | —       | Resolved page title sent with each `page_view` (avoids the SPA title race).  |
+
+### `<Consent>` / `<Manage>`
+
+No props — both read the consent stores directly. `<Consent>` shows the banner while consent is pending; `<Manage>` renders only inside a prior-consent zone once a choice has been made.

package/ui/.agents/skills/antcn/references/bridge.md

@@ -0,0 +1,41 @@
+# bridge
+
+## Notes
+
+You build the native side. It is reachable through two contracts the CLI cannot wire for you:
+
+- **The message channel.** Your native host receives requests on `window.webkit.messageHandlers.bridge` and must post each reply/event back as a `window` `'bridge'` `CustomEvent` (a `Detail`). `available()` is `true` only inside such a host; in a plain browser `platform`/`version` are `null` and `semver()` is `false`, so gate any request on `available()` (a request fired with no host never gets a reply).
+- **The detection markers** — change these to match your wrapper:
+  - **Android package id** (`svc/bridge.ts`) — detected by `document.referrer.startsWith('android-app://com.example.twa')`. Replace the placeholder `com.example.twa` with your Trusted Web Activity package id.
+  - **`PWAShell` UA marker** (`svc/bridge.ts`) — iOS is detected by a `PWAShell` token in `navigator.userAgent`, with the version parsed from `PWAShell/<version>`. Have your iOS WebView host append the same marker (`… PWAShell/1.2.3`), or change both regexes to your own.
+
+## Usage
+
+```ts
+import { bridge } from '@/bridge'
+
+if (bridge.platform === 'ios' && bridge.semver('>=1.2.0')) {
+  if (await bridge.purchases.available()) {
+    const products = await bridge.purchases.products(['premium_yearly'])
+    // …drive a purchase, then bridge.purchases.finish(transactionID)
+  }
+}
+
+bridge.transmission.onNotificationClick((n) => {
+  if (n.action) location.assign(n.action)
+})
+```
+
+## API
+
+| Symbol                          | Description                                                                                  |
+| ------------------------------- | -------------------------------------------------------------------------------------------- |
+| `bridge.platform`               | `'ios' \| 'android' \| null` — native host detected from UA / referrer; `null` in a browser. |
+| `bridge.version`                | Native host version string parsed from the `PWAShell/<version>` UA marker, else `null`.      |
+| `bridge.semver(pattern)`        | `true` when `version` satisfies the semver `pattern`; `false` when there is no native host.   |
+| `bridge.available()`            | `true` when the native message handler is reachable in the current environment.              |
+| `bridge.purchases`              | StoreKit operations: `available()`, `products(ids)`, `purchase(id, token)`, `restore()`, `manage()`, `finish(txId)`. |
+| `bridge.transmission`           | Push channel: `address()`, `permission()`, `request()`, `delete()`, `onNotification(cb)`, `onNotificationClick(cb)`. |
+| `on(key, cb)` / `send(label, args?)` | Low-level transport: subscribe to a reply id / event label, or fire-and-forget a message. |
+
+Every `purchases`/`transmission` request resolves to its typed result **or** an `Error` (a native-side failure) — narrow with `instanceof Error` before use.

package/ui/.agents/skills/antcn/references/clipboard.md

@@ -0,0 +1,23 @@
+# Clipboard
+
+Copies `text` (string or async retriever) to the system clipboard. Shows a checkmark for 2s after success. Disabled when `navigator.clipboard` is unavailable (non-secure context).
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Clipboard } from '$com/clipboard'
+</script>
+
+<Clipboard text="https://example.com/join/abc" label="Copy link" variant="outline" />
+```
+
+## Props
+
+| Prop     | Type                         | Default | Notes                                              |
+| -------- | ---------------------------- | ------- | -------------------------------------------------- |
+| `text`   | `string \| () => Promise<string>` | —       | Value to copy. Retriever may return `null` to skip. |
+| `label`  | `string`                     | —       | Button label. Omit for icon-only.                  |
+| `oncopy` | `() => void`                 | —       | Fires after a successful copy.                     |
+
+All other props pass through to the underlying `Button`.

package/ui/.agents/skills/antcn/references/dismissable.md

@@ -0,0 +1,75 @@
+# Dismissable
+
+Horizontal swipe-to-dismiss wrapper with optional slide-out animation. Swiping far enough triggers `ondismiss` immediately; calling `dismiss()` on a bound instance plays the slide-out first, then `ondismiss`. `remove()` animates out without calling `ondismiss`.
+
+Set `dismissable={false}` to disable the swipe sentinel — use when dismissal is programmatic only.
+
+## Usage
+
+### Swipe to dismiss
+
+```svelte
+<script lang="ts">
+  import { Dismissable } from '$com/dismissable'
+
+  let visible = $state(true)
+
+  async function ondismiss() {
+    visible = false
+  }
+</script>
+
+{#if visible}
+  <Dismissable {ondismiss}>
+    <div class="rounded-lg border bg-muted px-4 py-3">Swipe left to dismiss</div>
+  </Dismissable>
+{/if}
+```
+
+### Clear all
+
+Bind each row, call `remove()` on every ref with a short stagger (`delay` from `$lib/tools`), then drop them from state — `remove()` skips per-row `ondismiss`.
+
+```svelte
+<script lang="ts">
+  import { Dismissable } from '$com/dismissable'
+  import { delay } from '$lib/tools'
+
+  type Ref = { remove: () => Promise<void> | void }
+
+  let items = $state(['One', 'Two', 'Three'])
+  const refs = $state<Array<Ref | undefined>>([])
+
+  async function clearAll() {
+    const removed = refs.map((ref, i) => delay(() => ref?.remove(), i * 50))
+
+    await Promise.all(removed)
+    items = []
+  }
+</script>
+
+<button onclick={clearAll}>Clear all</button>
+
+{#each items as item, i (item)}
+  <Dismissable bind:this={refs[i]} ondismiss={() => (items = items.filter((x) => x !== item))}>
+    <div class="rounded-lg border bg-muted px-4 py-3">{item}</div>
+  </Dismissable>
+{/each}
+```
+
+## Props
+
+| Prop          | Type                              | Default | Notes                                                                 |
+| ------------- | --------------------------------- | ------- | --------------------------------------------------------------------- |
+| `children`    | `Snippet`                         | —       | Content inside the swipe track.                                       |
+| `ondismiss`   | `() => Promise<void> \| void`     | —       | Swipe-to-sentinel fires immediately; `dismiss()` fires after animation. |
+| `dismissable` | `boolean`                         | `true`  | When `false`, hides the swipe sentinel and disables swipe dismissal.  |
+
+## Instance methods
+
+Bind with `bind:this` to call programmatic dismissal:
+
+| Method     | Notes                                                          |
+| ---------- | -------------------------------------------------------------- |
+| `dismiss()` | Slide-out animation, then `ondismiss`.                        |
+| `remove()`  | Slide-out animation only — no `ondismiss`.                    |

package/ui/.agents/skills/antcn/references/dropdown.md

@@ -0,0 +1,153 @@
+# Dropdown
+
+Composable action menu with CSS anchor positioning, view-transition morph on open/close, and optional nested layers. Import as a namespace (`import * as Dropdown from '$com/dropdown'`).
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+  import { Ellipsis } from '@lucide/svelte'
+  import * as Dropdown from '$com/dropdown'
+
+  let menu: Dropdown.Root | undefined
+</script>
+
+<Dropdown.Root bind:this={menu}>
+  <Dropdown.Trigger variant="outline" size="icon">
+    <Ellipsis />
+  </Dropdown.Trigger>
+  <Dropdown.Content>
+    <Dropdown.Group direction="col">
+      <Dropdown.Item onclick={() => menu?.close()}>Edit</Dropdown.Item>
+      <Dropdown.Item>More…</Dropdown.Item>
+    </Dropdown.Group>
+  </Dropdown.Content>
+</Dropdown.Root>
+```
+
+### Nested layers
+
+Initially layers with `name` are hidden. Items with `layer` push a named layer. `Back` pops the current layer.
+
+```svelte
+<script lang="ts">
+  import { Ellipsis } from '@lucide/svelte'
+  import * as Dropdown from '$com/dropdown'
+
+  let menu: Dropdown.Root | undefined
+</script>
+
+<Dropdown.Root bind:this={menu}>
+  <Dropdown.Trigger variant="outline" size="icon">
+    <Ellipsis />
+  </Dropdown.Trigger>
+  <Dropdown.Content>
+    <Dropdown.Layer>
+      <Dropdown.Group direction="col">
+        <Dropdown.Item onclick={() => menu?.close()}>Edit</Dropdown.Item>
+        <Dropdown.Item layer="more">More…</Dropdown.Item>
+      </Dropdown.Group>
+    </Dropdown.Layer>
+    <Dropdown.Layer name="more">
+      <Dropdown.Group direction="col">
+        <Dropdown.Back />
+        <Dropdown.Item onclick={() => menu?.close()}>Archive</Dropdown.Item>
+      </Dropdown.Group>
+    </Dropdown.Layer>
+  </Dropdown.Content>
+</Dropdown.Root>
+```
+
+### Actions
+
+Typical use case for Dropdown is navigation actions.
+Wrap it with `<Actions>` from `shell` component, pass `active` store to control mute of the main navigation.
+
+```svelte
+<script lang="ts">
+  import { writable } from 'svelte/store'
+  import { Actions } from '$com/shell'
+  import * as Dropdown from '$com/dropdown'
+
+  const active = writable(false)
+</script>
+
+<Actions active={active}>
+  <Dropdown.Root bind:this={menu} onopen={(open) => active.set(open)}>
+    <Dropdown.Trigger variant="outline" size="icon">
+      <Ellipsis />
+    </Dropdown.Trigger>
+    <Dropdown.Content>
+      <Dropdown.Group direction="col">
+        <Dropdown.Item onclick={() => menu?.close()}>Edit</Dropdown.Item>
+        <Dropdown.Item>More…</Dropdown.Item>
+      </Dropdown.Group>
+    </Dropdown.Content>
+  </Dropdown.Root>
+</Actions>
+```
+
+## Props
+
+### Root
+
+| Prop       | Type                      | Default | Notes                                      |
+| ---------- | ------------------------- | ------- | ------------------------------------------ |
+| `children` | `Snippet`                 | —       | `Trigger` and `Content` slots.             |
+| `onopen`   | `(open: boolean) => void` | —       | Fires when open state changes.             |
+
+**Methods** (via `bind:this`): `open()`, `close()`.
+
+### Trigger
+
+Extends shadcn `Button` props (`variant`, `size`, `class`, …).
+
+| Prop       | Type      | Default | Notes                                |
+| ---------- | --------- | ------- | ------------------------------------ |
+| `children` | `Snippet` | —       | Trigger label or icon.               |
+| `id`       | `string`  | —       | Passed to the underlying `Button`.   |
+
+### Content
+
+| Prop       | Type                                                                 | Default         | Notes                                                                 |
+| ---------- | -------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------- |
+| `children` | `Snippet`                                                            | —               | `Layer`, `Group`, `Item`, `Separator` slots.                          |
+| `class`    | `ClassValue`                                                         | —               | Panel wrapper classes.                                                |
+| `position` | `'start-top' \| 'start-bottom' \| 'end-top' \| 'end-bottom'`         | `'end-bottom'`  | Corner where menu aligns with the trigger; menu grows outward from it. |
+
+### Layer
+
+| Prop       | Type      | Default | Notes                                                                 |
+| ---------- | --------- | ------- | --------------------------------------------------------------------- |
+| `name`     | `string`  | `''`    | Layer id. Default layer uses `''`; push targets use a non-empty name. |
+| `children` | `Snippet` | —       | Shown when this layer is active.                                      |
+
+### Group
+
+| Prop        | Type               | Default | Notes                                      |
+| ----------- | ------------------ | ------- | ------------------------------------------ |
+| `children`  | `Snippet`          | —       | `Item` or custom content.                  |
+| `direction` | `'col' \| 'row'`   | `'col'` | Layout for items; affects `itemVariants`.  |
+| `class`     | `ClassValue`       | —       | Wrapper classes.                           |
+
+### Item
+
+Extends shadcn `Button` props. Export `itemVariants` for custom buttons in a row group.
+
+| Prop       | Type      | Default   | Notes                                                         |
+| ---------- | --------- | --------- | ------------------------------------------------------------- |
+| `children` | `Snippet` | —         | Row content (icon + label).                                   |
+| `layer`    | `string`  | —         | When set, click pushes this layer instead of calling `onclick`. |
+| `variant`  | `string`  | `'ghost'` | Button variant.                                               |
+
+### Back
+
+Same props as `Item` except `onclick` / `layer` (handled internally). Optional label snippet after the back arrow.
+
+### Separator
+
+| Prop       | Type      | Default | Notes                              |
+| ---------- | --------- | ------- | ---------------------------------- |
+| `children` | `Snippet` | —       | Optional centered label between rules. |

package/ui/.agents/skills/antcn/references/fragments.md

@@ -0,0 +1,29 @@
+# fragments
+
+## Notes
+
+- **Mount `<Fragments />` once** in your root `+layout.svelte`. It runs on the first (landing) navigation only and drives the consume-on-read cleanup; without it, read values are never stripped from the hash.
+- `fragment(name)` returns the value present in the landing URL's hash, or `null` when absent. The hash is snapshotted once at module load, so reads are stable across the session even as the bar is rewritten; the actual URL is cleaned on the next navigation.
+- SSR-safe: on the server the hash is empty, so `fragment()` returns `null` and `<Fragments />` is inert until hydration.
+
+## Usage
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { Fragments } from '@/fragments/ui'
+</script>
+
+<Fragments />
+{@render children()}
+```
+
+```ts
+// anywhere a one-shot hash value is expected, e.g. a returning redirect
+import { fragment } from '@/fragments'
+
+const session = fragment('stripe')
+if (session) {
+  // …resume the flow for this session id; the hash is cleaned on next navigation
+}
+```

package/ui/.agents/skills/antcn/references/fullscreen.md

@@ -0,0 +1,157 @@
+# Fullscreen
+
+Tap-to-expand overlay portaled to `body`. Wraps open/close in `transit()` for view transitions. Default mode: `children` is the trigger and the fullscreen body. Use `content` when the trigger and the overlay body should differ.
+
+## Usage
+
+### Zoom a thumbnail
+
+Same markup in the trigger and in fullscreen — good for photo zoom. Put `view-transition-name` on the image; add `fullscreen-content` for correct morph stacking.
+
+```svelte
+<script lang="ts">
+  import { Fullscreen } from '$com/fullscreen'
+
+  const id = 'photo-1'
+  let zoomed = $state<string | null>(null)
+</script>
+
+<Fullscreen class="h-[300px]" fragile onshow={() => (zoomed = id)} x={false}>
+  <img
+    src="/photo.jpg"
+    alt=""
+    class="h-full object-contain fullscreen-content"
+    style={`${zoomed === id ? 'view-transition-name: photo;' : ''} view-transition-class: transition-spring transition-morph;`} />
+</Fullscreen>
+```
+
+Set the transition name only while open (`onshow` + conditional style) when several Fullscreens sit in a list — otherwise every thumbnail joins the same morph.
+
+### Button → content
+
+When a button (or file input, share target, …) opens different fullscreen UI, split trigger and body: `controlled`, `content`, and `bind:this` → `show()` / `hide()`.
+
+Morph from the button into `content` with `takeoff` + `styles` (same transition name on both sides):
+
+```svelte
+<script lang="ts">
+  import { Button } from '$ui/button'
+  import { styles, takeoff } from '$lib/tools'
+  import { Fullscreen } from '$com/fullscreen'
+
+  const morph = 'transition-spring transition-morph fullscreen-content'
+
+  let fullscreen = $state<Fullscreen | null>(null)
+  const contentStyle = styles('upload', morph)
+
+  function open() {
+    takeoff('upload-button', 'upload', morph)
+    fullscreen?.show()
+  }
+</script>
+
+<Fullscreen bind:this={fullscreen} controlled>
+  <Button id="upload-button" onclick={open}>Upload</Button>
+  {#snippet content()}
+    <div class="max-w-md p-4 fullscreen-content" style={$contentStyle}>
+      <!-- progress, preview, … -->
+    </div>
+  {/snippet}
+</Fullscreen>
+```
+
+No visible trigger? Pass an empty `<div></div>` as `children` and call `show()` from `onMount` (share-target flow).
+
+### Overlay toolbar
+
+Actions above the content — delete, share, etc. Disable the default ✕ (`x={false}`) when the overlay dismisses.
+
+```svelte
+<script lang="ts">
+  import { Hold } from '$com/hold'
+  import { Fullscreen } from '$com/fullscreen'
+
+  let fullscreen = $state<Fullscreen | null>(null)
+</script>
+
+<Fullscreen bind:this={fullscreen} fragile x={false}>
+  <img src="/photo.jpg" alt="" class="fullscreen-content" style="view-transition-name: photo; …" />
+  {#snippet overlay()}
+    <div class="flex justify-end p-4 tim:pt-[env(safe-area-inset-top)]">
+      <Hold label="hold to delete" variant="outline" size="icon" onclick={() => fullscreen?.hide()}>
+        <!-- icon -->
+      </Hold>
+    </div>
+  {/snippet}
+</Fullscreen>
+```
+
+### Store-driven open
+
+When `open` comes from a store or parent, still wrap the flip in `transit()` — `show()` / `hide()` do that; raw `open = true` skips the animation.
+
+```svelte
+<script lang="ts">
+  import { transit } from '$lib/tools'
+  import { Fullscreen } from '$com/fullscreen'
+
+  let open = $state(false)
+
+  async function present() {
+    await transit(() => (open = true))
+  }
+</script>
+
+<Fullscreen bind:open>
+  <div></div>
+  {#snippet content()}
+    <!-- paywall, modal flow, … -->
+  {/snippet}
+</Fullscreen>
+```
+
+Optional: `takeoff(sourceId, name, classes)` before `transit` when morphing from another element on the page (CTA button → paywall card).
+
+## Props
+
+| Prop         | Type           | Default | Notes                                                                 |
+| ------------ | -------------- | ------- | --------------------------------------------------------------------- |
+| `children`   | `Snippet`      | —       | Trigger markup; also fullscreen body when `content` is omitted.       |
+| `content`    | `Snippet`      | —       | Fullscreen-only body; trigger stays on the page.                      |
+| `overlay`    | `Snippet`      | —       | Toolbar/actions above content; rendered inside `Overlay`.             |
+| `open`       | `boolean`      | `false` | Bindable. Mutate inside `transit()` unless using `show()` / `hide()`. |
+| `onshow`     | `() => void`   | —       | Fires when `show()` starts.                                           |
+| `onhide`     | `() => void`   | —       | Fires after the close transition finishes.                            |
+| `class`      | `ClassValue`   | —       | Classes on the trigger button (ignored when `controlled`).            |
+| `fragile`    | `boolean`      | `false` | Close on backdrop pointer down.                                       |
+| `controlled` | `boolean`      | `false` | No built-in trigger; call `show()` / `hide()` yourself.               |
+| `x`          | `boolean`      | `true`  | Top-trailing close button.                                            |
+
+`bind:this` exposes `show()` and `hide()`. `Overlay` accepts `children` and optional `class`.
+
+## Notes
+
+### Opening and closing
+
+- Prefer `show()` / `hide()` or `await transit(() => (open = …))`. Assigning `open` directly bypasses the view transition.
+- In `controlled` mode, Escape and backdrop tap (`fragile`) do nothing — close with `hide()`, `transit(() => (open = false))`, or a control in `overlay`.
+- Pair `controlled` + `bind:open` when async work should finish only while open: `if (open) callback?.(id)`.
+
+### `children` vs `content`
+
+| Setup | Trigger | Fullscreen body | Typical use |
+| ----- | ------- | --------------- | ----------- |
+| `children` only | wrapped in a button | same `children` | Thumbnail zoom |
+| `controlled` + `content` | `children` stays in place | `content` snippet | Button → upload progress, paywall |
+
+### View transitions
+
+- Shared name on source and target: inline `view-transition-name` on the thumbnail, or `takeoff(id, name, classes)` + `styles(name, classes)` on `content`.
+- Add `view-transition-class: transition-spring transition-morph` and class `fullscreen-content` on the morphing element — matches built-in z-index (`::view-transition-group(.fullscreen-content)`).
+- Content above the default stack? Add a scoped rule, e.g. `::view-transition-group(paywall) { z-index: 4; }`.
+- List of items: unique name per row; set it only for the open item (see thumbnail example above).
+
+### Overlay
+
+- Set `x={false}` when `overlay` owns dismiss/delete.
+- The built-in trigger hides `[data-slot=fullscreen-overlay]` descendants so overlay chrome does not appear in the thumbnail.