@krizaka/ui 3.22.0 → 3.24.0

package/registry/app-header.json

@@ -0,0 +1,202 @@
+{
+  "name": "app-header",
+  "type": "primitive",
+  "title": "App header",
+  "summary": "The top bar that sits next to a `RailNav`: the product's name as text, optional status chips, and the actions. The mark is the rail's; on a phone, where the rail is a bottom tab bar, the header shows it too, so one mark is visible at every width.",
+  "description": "The top bar that sits next to a `RailNav`: the product's name as text, optional status chips, and the actions. The mark is the rail's; on a phone, where the rail is a bottom tab bar, the header shows it too, so one mark is visible at every width.",
+  "status": "beta",
+  "deprecated": null,
+  "category": "navigation",
+  "platforms": "web",
+  "parity": {
+    "web": {
+      "state": "yes"
+    },
+    "native": {
+      "state": "n/a",
+      "reason": "A native screen has its own header.",
+      "use": "header"
+    },
+    "desktop": {
+      "state": "yes"
+    }
+  },
+  "whenToUse": [
+    "Beside a `RailNav`, as the bar of every signed-in screen: name, status, theme, notifications, account."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "The bar of a site, with its menus and its call to action.",
+      "use": "nav-bar"
+    },
+    {
+      "when": "A screen's title and its actions inside an AppShell.",
+      "use": "app-shell"
+    },
+    {
+      "when": "A page's title block.",
+      "use": "page-header"
+    }
+  ],
+  "bestPractices": [
+    "Pass the name as text and the mark as `mark`: never put a mark in the header that the rail already carries on a desktop (`mark` is hidden from `md` up for that reason).",
+    "Chips say a state, not a place: « Local · Sovereign », « Dev », a version.",
+    "Keep the actions to what changes the session (theme, notifications, account menu): the sections are in the rail.",
+    "Make the name a link home with `homeLink` (your router's link) or `href`."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "A `header` landmark; the name is plain text (the page's `h1` is the screen's, below).",
+      "The mark is decorative beside the name: give the home link its name through the visible text."
+    ]
+  },
+  "related": [
+    "rail-nav",
+    "app-shell",
+    "nav-bar",
+    "badge",
+    "page-header"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/app-header",
+    "import": "import { AppHeader } from \"@krizaka/ui/app-header\";",
+    "props": [
+      {
+        "component": "AppHeader",
+        "description": "The app's top bar: the name next to the rail, the mark on a phone, chips, actions.",
+        "props": [
+          {
+            "name": "name",
+            "type": "string",
+            "default": null,
+            "description": "The product's name, as text (`Orazaka`): the only brand element on a desktop.",
+            "required": true
+          },
+          {
+            "name": "actions",
+            "type": "ReactNode",
+            "default": null,
+            "description": "On the right: theme, notifications, the account menu.",
+            "required": false
+          },
+          {
+            "name": "chips",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Status chips beside the name (`Badge`): « Local · Sovereign », « Dev », a version.",
+            "required": false
+          },
+          {
+            "name": "homeLink",
+            "type": "ReactElement<{ className?: string; children?: ReactNode; }, string | JSXElementConstructor<any>>",
+            "default": null,
+            "description": "Your router's link element for the home link; it receives the name and the mark as children.",
+            "required": false
+          },
+          {
+            "name": "href",
+            "type": "string",
+            "default": null,
+            "description": "Makes the name (and the mark) a link home: pass your router's link as `homeLink` or give a `href`.",
+            "required": false
+          },
+          {
+            "name": "mark",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The product's mark (`<ProductLogo id=\"orazaka\" size={22} />`): shown below `md` only, where the rail (which carries it) is a bottom bar.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "basic",
+        "title": "Name, chip and actions",
+        "description": "Orazaka's bar: the name, a « Local · Sovereign » chip, and the theme and account on the right; the mark joins the name below `md`.",
+        "path": "examples/app-header/basic.tsx",
+        "module": "@krizaka/ui/registry/examples/app-header/basic",
+        "code": "import { ProductLogo } from \"@krizaka/ui\";\nimport { AppHeader } from \"@krizaka/ui/app-header\";\nimport { Badge } from \"@krizaka/ui/badge\";\nimport { Button } from \"@krizaka/ui/button\";\n\n// The name is text; the mark shows below `md` only (a desktop's rail carries it). Chips say a state.\nexport default function AppHeaderBasic() {\n  return (\n    <AppHeader\n      name=\"Orazaka\"\n      mark={<ProductLogo id=\"orazaka\" size={22} animated={false} />}\n      href=\"#home\"\n      chips={<Badge tone=\"success\" dot>Local · Sovereign</Badge>}\n      actions={<Button size=\"sm\" variant=\"secondary\">Account</Button>}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "app-header/app-header.tsx",
+      "content": "// Server-safe: no hook, no context. The top bar that sits next to a `RailNav`: the product's NAME as text (the mark is the\n// rail's), then optional chips, then the actions. Where the rail is a bottom tab bar (a phone) it has no room for the mark,\n// so the header shows it there and only there: exactly one brand mark is visible at every width.\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nexport const appHeader = tv({\n  slots: {\n    root: \"sticky top-0 z-30 flex h-14 w-full shrink-0 items-center gap-3 border-b border-border-subtle bg-surface-1/90 px-4 backdrop-blur-xl md:bg-surface-1 md:pl-3 md:pr-5 md:backdrop-blur-none\",\n    // The rail's mark is 56 px tall and so is this bar: the word shares the mark's line, right after the rail.\n    brand: \"flex min-w-0 items-center gap-2 font-display text-sm font-bold tracking-tight text-fg no-underline\",\n    mark: \"inline-flex shrink-0 md:hidden\",\n    name: \"truncate\",\n    chips: \"flex shrink-0 items-center gap-2\",\n    actions: \"ml-auto flex shrink-0 items-center gap-2\",\n  },\n});\nconst s = appHeader();\n\nexport type AppHeaderProps = Omit<React.ComponentProps<\"header\">, \"children\"> & {\n  /** The product's name, as text (`Orazaka`): the only brand element on a desktop. */\n  name: string;\n  /** The product's mark (`<ProductLogo id=\"orazaka\" size={22} />`): shown below `md` only, where the rail (which carries it) is a bottom bar. */\n  mark?: React.ReactNode;\n  /** Makes the name (and the mark) a link home: pass your router's link as `homeLink` or give a `href`. */\n  href?: string;\n  /** Your router's link element for the home link; it receives the name and the mark as children. */\n  homeLink?: React.ReactElement<{ className?: string; children?: React.ReactNode }>;\n  /** Status chips beside the name (`Badge`): « Local · Sovereign », « Dev », a version. */\n  chips?: React.ReactNode;\n  /** On the right: theme, notifications, the account menu. */\n  actions?: React.ReactNode;\n};\n\n/** The app's top bar: the name next to the rail, the mark on a phone, chips, actions. */\nexport function AppHeader({ name, mark, href, homeLink, chips, actions, className, ...props }: AppHeaderProps) {\n  const brand = (\n    <>\n      {mark && <span data-brand-mark className={s.mark()}>{mark}</span>}\n      <span className={s.name()}>{name}</span>\n    </>\n  );\n  return (\n    <header className={s.root({ className })} {...props}>\n      {homeLink ? (\n        React.cloneElement(homeLink, { className: s.brand() }, brand)\n      ) : href ? (\n        <a href={href} className={s.brand()}>{brand}</a>\n      ) : (\n        <div className={s.brand()}>{brand}</div>\n      )}\n      {chips && <div className={s.chips()}>{chips}</div>}\n      {actions && <div className={s.actions()}>{actions}</div>}\n    </header>\n  );\n}\n"
+    },
+    {
+      "path": "app-header/index.ts",
+      "content": "/** @krizaka/ui/app-header — `AppHeader` (`name`, `mark`, `chips`, `actions`), `appHeader`: the top bar beside a `RailNav`. Server-safe. */\nexport { AppHeader, appHeader, type AppHeaderProps } from \"./app-header\";\n"
+    },
+    {
+      "path": "app-header/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"App header\",\n  summary: \"The top bar that sits next to a `RailNav`: the product's name as text, optional status chips, and the actions. The mark is the rail's; on a phone, where the rail is a bottom tab bar, the header shows it too, so one mark is visible at every width.\",\n  status: \"beta\",\n  category: \"navigation\",\n  platforms: \"web\",\n  parity: { native: { status: \"n/a\", reason: \"A native screen has its own header.\", use: \"header\" }, desktop: \"web\" },\n  whenToUse: [\n    \"Beside a `RailNav`, as the bar of every signed-in screen: name, status, theme, notifications, account.\",\n  ],\n  whenNotToUse: [\n    { when: \"The bar of a site, with its menus and its call to action.\", use: \"nav-bar\" },\n    { when: \"A screen's title and its actions inside an AppShell.\", use: \"app-shell\" },\n    { when: \"A page's title block.\", use: \"page-header\" },\n  ],\n  bestPractices: [\n    \"Pass the name as text and the mark as `mark`: never put a mark in the header that the rail already carries on a desktop (`mark` is hidden from `md` up for that reason).\",\n    \"Chips say a state, not a place: « Local · Sovereign », « Dev », a version.\",\n    \"Keep the actions to what changes the session (theme, notifications, account menu): the sections are in the rail.\",\n    \"Make the name a link home with `homeLink` (your router's link) or `href`.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"A `header` landmark; the name is plain text (the page's `h1` is the screen's, below).\",\n      \"The mark is decorative beside the name: give the home link its name through the visible text.\",\n    ],\n  },\n  related: [\"rail-nav\", \"app-shell\", \"nav-bar\", \"badge\", \"page-header\"],\n  web: {\n    imports: [\"AppHeader\"],\n    examples: [\n      { name: \"basic\", title: \"Name, chip and actions\", description: \"Orazaka's bar: the name, a « Local · Sovereign » chip, and the theme and account on the right; the mark joins the name below `md`.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "meta.ts",
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"action-sheet\"\n  | \"activity-feed\"\n  | \"alert\"\n  | \"app-header\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"captcha\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"comparison-table\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"docs-nav\"\n  | \"document-viewer\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"force-update-screen\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"genui\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"maintenance-screen\"\n  | \"map\"\n  | \"markdown\"\n  | \"meta-row\"\n  | \"waveform\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-grid\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"rail-nav\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"splash-handoff\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"update-prompt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n *   component that answers there, when one does.\n */\nexport type Absence =\n  | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n  | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n  readonly web?: Absence;\n  readonly native?: Absence;\n  readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: string;\n    });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n  readonly parity: Parity;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+    }
+  ],
+  "dependencies": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [],
+  "demo": {
+    "path": "examples/app-header/basic.tsx",
+    "content": "import { ProductLogo } from \"@krizaka/ui\";\nimport { AppHeader } from \"@krizaka/ui/app-header\";\nimport { Badge } from \"@krizaka/ui/badge\";\nimport { Button } from \"@krizaka/ui/button\";\n\n// The name is text; the mark shows below `md` only (a desktop's rail carries it). Chips say a state.\nexport default function AppHeaderBasic() {\n  return (\n    <AppHeader\n      name=\"Orazaka\"\n      mark={<ProductLogo id=\"orazaka\" size={22} animated={false} />}\n      href=\"#home\"\n      chips={<Badge tone=\"success\" dot>Local · Sovereign</Badge>}\n      actions={<Button size=\"sm\" variant=\"secondary\">Account</Button>}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "AppHeader",
+      "description": "The app's top bar: the name next to the rail, the mark on a phone, chips, actions.",
+      "props": [
+        {
+          "name": "name",
+          "type": "string",
+          "default": null,
+          "description": "The product's name, as text (`Orazaka`): the only brand element on a desktop.",
+          "required": true
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "default": null,
+          "description": "On the right: theme, notifications, the account menu.",
+          "required": false
+        },
+        {
+          "name": "chips",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Status chips beside the name (`Badge`): « Local · Sovereign », « Dev », a version.",
+          "required": false
+        },
+        {
+          "name": "homeLink",
+          "type": "ReactElement<{ className?: string; children?: ReactNode; }, string | JSXElementConstructor<any>>",
+          "default": null,
+          "description": "Your router's link element for the home link; it receives the name and the mark as children.",
+          "required": false
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "default": null,
+          "description": "Makes the name (and the mark) a link home: pass your router's link as `homeLink` or give a `href`.",
+          "required": false
+        },
+        {
+          "name": "mark",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The product's mark (`<ProductLogo id=\"orazaka\" size={22} />`): shown below `md` only, where the rail (which carries it) is a bottom bar.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/app-shell.json

@@ -18,7 +18,7 @@
       "use": "tab-bar"
     },
     "desktop": {
-      "state": "yes"
+      "state": "desktop"
     }
   },
   "whenToUse": [
@@ -40,7 +40,8 @@
     "Persist the collapse with `collapsed` + `onCollapsedChange`; put the account in the sidebar's `footer`.",
     "Render your router's links with `AppShell.Item asChild`.",
     "Give the sections a `shortcut` (`g p`: G then P): it clicks the item, so a router link navigates, and the keys show on hover and focus.",
-    "Put `AppShell.Search` in the header and open your `CommandDialog` from its `onOpen`: ⌘K (Ctrl+K) opens it from anywhere."
+    "Put `AppShell.Search` in the header and open your `CommandDialog` from its `onOpen`: ⌘K (Ctrl+K) opens it from anywhere.",
+    "In a desktop app (the Orazaka Mac app, Tauri 2) pass `desktop`: the header and the sidebar's top become the title bar that moves the window, there is no drawer, the density is the desktop's; build the native menu bar from the same shortcuts with `acceleratorOf` (`mod+k` → `CmdOrCtrl+K`)."
   ],
   "accessibility": {
     "keyboard": [
@@ -71,7 +72,8 @@
       "On a phone the drawer is a modal dialog (Radix): focus trapped inside, Escape and the overlay close it, the focus returns to the button.",
       "The header's title is the screen's `h1`; nested layouts use `headingAs=\"h2\"`.",
       "A combination is announced with `aria-keyshortcuts` (`Control+K`, `Meta+K` on a Mac); a sequence is not a chord, so it is only shown on its keys, never named to assistive technology.",
-      "The platform's keys are known after the first client render (⌘ on a Mac, Ctrl elsewhere): the server and the first render agree."
+      "The platform's keys are known after the first client render (⌘ on a Mac, Ctrl elsewhere): the server and the first render agree.",
+      "With `desktop`, the drag regions are the header, its title and the sidebar's top only — never a control — so every button, link and field keeps its focus and its click; the chrome is not selectable, the content is."
     ]
   },
   "related": [
@@ -87,7 +89,7 @@
   ],
   "web": {
     "entry": "@krizaka/ui/app-shell",
-    "import": "import { AppShell, useShortcuts, formatShortcut } from \"@krizaka/ui/app-shell\";",
+    "import": "import { AppShell, useShortcuts, formatShortcut, acceleratorOf } from \"@krizaka/ui/app-shell\";",
     "props": [
       {
         "component": "AppShellRoot",
@@ -114,6 +116,13 @@
             "description": "The sidebar starts collapsed to its icons (desktop).",
             "required": false
           },
+          {
+            "name": "desktop",
+            "type": "boolean",
+            "default": "false",
+            "description": "The shell is a desktop app's window (the Orazaka Mac app, Tauri 2 — ADR-002): no drawer, the sidebar's top clears the\nwindow's traffic lights (`--kz-titlebar-inset`, 28 px; the window's height is `--kz-window-height`, the viewport by default), the header and that top move the window\n(`data-tauri-drag-region`), a denser layout, the chrome not selectable. In a browser it is a fixed-height shell.",
+            "required": false
+          },
           {
             "name": "onCollapsedChange",
             "type": "((collapsed: boolean) => void)",
@@ -344,6 +353,14 @@
         "path": "examples/app-shell/basic.tsx",
         "module": "@krizaka/ui/registry/examples/app-shell/basic",
         "code": "import { ProductLogo } from \"@krizaka/ui\";\nimport { AppShell } from \"@krizaka/ui/app-shell\";\nimport { Button } from \"@krizaka/ui/button\";\n\nconst dot = <svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" aria-hidden><circle cx=\"12\" cy=\"12\" r=\"7\" /></svg>;\n\n// The shell alone: the sidebar (it collapses to its icons on a desktop, opens as a drawer on a phone), the header, the\n// content. Your router's links go in `AppShell.Item asChild`.\nexport default function AppShellBasic() {\n  return (\n    <AppShell.Root className=\"min-h-[32rem]\">\n      <AppShell.Sidebar\n        label=\"Studio\"\n        brand={<><ProductLogo id=\"orochia\" size={24} animated={false} /> Studio</>}\n        collapseLabels={[\"Collapse\", \"Expand\"]}\n        closeLabel=\"Close the menu\"\n      >\n        <AppShell.Item href=\"#home\" icon={dot} label=\"Home\" current />\n        <AppShell.Item href=\"#videos\" icon={dot} label=\"Videos\" badge={3} />\n        <AppShell.Group>Money</AppShell.Group>\n        <AppShell.Item href=\"#earnings\" icon={dot} label=\"Earnings\" />\n      </AppShell.Sidebar>\n      <AppShell.Body>\n        <AppShell.Header title=\"Home\" menuLabel=\"Open the menu\" actions={<Button size=\"sm\" variant=\"primary\" shape=\"cut\">Upload</Button>} />\n        <AppShell.Main>\n          <p className=\"text-sm text-fg-secondary\">The screen's content.</p>\n        </AppShell.Main>\n      </AppShell.Body>\n    </AppShell.Root>\n  );\n}\n"
+      },
+      {
+        "name": "desktop",
+        "title": "Desktop window",
+        "description": "The Orazaka Mac app's window (`desktop`): the title bar moves the window and clears the traffic lights, no drawer, the desktop's density, ⌘1–⌘3 to the sections.",
+        "path": "examples/app-shell/desktop.tsx",
+        "module": "@krizaka/ui/registry/examples/app-shell/desktop",
+        "code": "import { ProductLogo } from \"@krizaka/ui\";\nimport { AppShell } from \"@krizaka/ui/app-shell\";\nimport { Badge } from \"@krizaka/ui/badge\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { Progress } from \"@krizaka/ui/progress\";\n\nconst dot = <svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" aria-hidden><circle cx=\"12\" cy=\"12\" r=\"7\" /></svg>;\n\n// The Mac app's window (Tauri 2, ADR-002): `desktop` — the title bar moves the window and clears the traffic lights, no\n// drawer, desktop density. The menu bar answers the same keys (`acceleratorOf(\"mod+1\")` → `CmdOrCtrl+1`).\nexport default function AppShellDesktop() {\n  return (\n    <AppShell.Root desktop style={{ [\"--kz-window-height\" as string]: \"34rem\" }}>\n      <AppShell.Sidebar label=\"Orazaka\" brand={<><ProductLogo id=\"orazaka\" size={22} animated={false} /> Orazaka</>} collapseLabels={[\"Collapse\", \"Expand\"]} closeLabel=\"Close\">\n        <AppShell.Item href=\"#workspace\" icon={dot} label=\"Workspace\" shortcut=\"mod+1\" />\n        <AppShell.Item href=\"#models\" icon={dot} label=\"Models\" shortcut=\"mod+2\" current />\n        <AppShell.Item href=\"#jobs\" icon={dot} label=\"Jobs\" shortcut=\"mod+3\" badge={2} />\n        <AppShell.Group>Machine</AppShell.Group>\n        <AppShell.Item href=\"#backups\" icon={dot} label=\"Backups\" />\n        <AppShell.Item href=\"#logs\" icon={dot} label=\"Logs\" />\n      </AppShell.Sidebar>\n      <AppShell.Body>\n        <AppShell.Header title=\"Models\" menuLabel=\"Open the menu\" actions={<Button size=\"sm\" variant=\"primary\" shape=\"cut\">Add a model</Button>} />\n        <AppShell.Main className=\"space-y-4\">\n          <div className=\"flex items-center justify-between gap-3 rounded-lg border border-border-subtle bg-surface-1 p-4\">\n            <div className=\"min-w-0 flex-1 space-y-2\">\n              <p className=\"text-sm font-semibold\">qwen2.5 7B · chat</p>\n              <Progress value={64} label=\"Downloading qwen2.5 7B\" />\n            </div>\n            <Badge tone=\"accent\">3.1 of 4.8 GB</Badge>\n          </div>\n          <p className=\"text-[13px] text-fg-secondary\">Models run on this Mac (Metal). Nothing leaves your network.</p>\n        </AppShell.Main>\n      </AppShell.Body>\n    </AppShell.Root>\n  );\n}\n"
       }
     ]
   },
@@ -351,19 +368,19 @@
   "files": [
     {
       "path": "app-shell/app-shell.tsx",
-      "content": "// Client (the collapse, the drawer, the shortcuts). The shell of an application screen, read from the products' consoles\n// (Orochia admin and studio, Orazaka web-admin and web-client): a sidebar of sections that collapses to its icons on a\n// desktop, a header with the screen's title, a search that opens the app's command palette and its actions, the content —\n// and below `md` the sidebar becomes a drawer opened from the header (Radix Dialog: focus trap, Escape, focus return).\n// Keyboard: ⌘/Ctrl+B folds the sidebar, ⌘/Ctrl+K opens the search, `g` then a letter goes to a section (`shortcut` of an\n// item). Words arrive as props; links through `asChild`.\nimport { SkipLink } from \"@krizaka/ui/skip-link\";\nimport { Dialog as DialogPrimitive, Slot } from \"radix-ui\";\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { cn } from \"../cn\";\nimport { ChevronGlyph, CloseGlyph, SearchGlyph } from \"../glyphs\";\nimport { Kbd } from \"../kbd\";\nimport { ariaKeyShortcuts, formatShortcut, useApple, useShortcuts } from \"./shortcuts\";\n\nexport const appShell = tv({\n  slots: {\n    root: \"flex min-h-dvh w-full bg-surface-0 text-fg\",\n    sidebar:\n      \"sticky top-0 hidden h-dvh shrink-0 flex-col border-r border-border-subtle bg-surface-1 transition-[width] duration-300 motion-reduce:transition-none md:flex \" +\n      \"w-64 data-collapsed:w-[4.25rem]\",\n    drawer:\n      \"kz-dialog fixed inset-y-0 left-0 z-50 flex w-[min(20rem,88vw)] flex-col border-r border-border-default bg-surface-1 pl-[env(safe-area-inset-left)] shadow-lg focus:outline-hidden\",\n    overlay: \"kz-overlay fixed inset-0 z-50 bg-overlay backdrop-blur-xs\",\n    brand: \"flex h-14 shrink-0 items-center gap-2.5 px-4 font-display text-[15px] font-bold tracking-tight [[data-collapsed]_&]:justify-center [[data-collapsed]_&]:px-0\",\n    nav: \"flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto px-2 py-2\",\n    group: \"mt-3 mb-1 px-3 font-mono text-[10.5px] font-semibold uppercase tracking-[0.14em] text-fg-secondary [[data-collapsed]_&]:sr-only\",\n    item:\n      \"group/item relative flex h-10 items-center gap-3 rounded-lg px-3 text-sm font-medium text-fg-secondary no-underline transition-colors \" +\n      \"hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring \" +\n      \"aria-[current=page]:bg-accent-soft aria-[current=page]:text-fg \" +\n      \"aria-[current=page]:before:absolute aria-[current=page]:before:inset-y-2 aria-[current=page]:before:-left-2 aria-[current=page]:before:w-1 aria-[current=page]:before:rounded-full aria-[current=page]:before:bg-accent \" +\n      \"[[data-collapsed]_&]:justify-center [[data-collapsed]_&]:px-0 [&>svg]:h-[18px] [&>svg]:w-[18px] [&>svg]:shrink-0\",\n    itemLabel: \"min-w-0 flex-1 truncate [[data-collapsed]_&]:sr-only\",\n    itemHint: \"ml-auto hidden items-center gap-0.5 text-fg-secondary group-hover/item:flex group-focus-visible/item:flex [[data-collapsed]_&]:!hidden\",\n    itemBadge:\n      \"ml-auto inline-flex min-w-5 items-center justify-center rounded-full bg-accent px-1.5 text-[11px] font-bold text-on-accent \" +\n      \"[[data-collapsed]_&]:absolute [[data-collapsed]_&]:right-1.5 [[data-collapsed]_&]:top-1 [[data-collapsed]_&]:min-w-4 [[data-collapsed]_&]:px-1 [[data-collapsed]_&]:text-[10px]\",\n    footer: \"shrink-0 border-t border-border-subtle p-2\",\n    collapse:\n      \"hidden h-9 w-full items-center gap-2 rounded-lg px-3 text-xs font-medium text-fg-secondary hover:bg-surface-2 hover:text-fg md:flex \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring [[data-collapsed]_&]:justify-center [[data-collapsed]_&]:px-0\",\n    body: \"flex min-w-0 flex-1 flex-col\",\n    header:\n      \"sticky top-0 z-30 flex h-14 shrink-0 items-center gap-3 border-b border-border-subtle bg-surface-0/85 px-4 backdrop-blur-xl md:px-6\",\n    menuButton:\n      \"inline-flex h-9 w-9 items-center justify-center rounded-lg border border-border-subtle bg-surface-1 text-fg md:hidden \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring\",\n    title: \"min-w-0 flex-1 truncate font-display text-base font-bold tracking-tight\",\n    search:\n      \"inline-flex h-9 min-w-9 items-center justify-center gap-2 rounded-lg border border-border-subtle bg-surface-1 px-2.5 text-sm text-fg-secondary transition-colors \" +\n      \"hover:border-border-default hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring md:w-56 md:justify-start [&>svg]:h-4 [&>svg]:w-4 [&>svg]:shrink-0\",\n    searchLabel: \"sr-only md:not-sr-only md:flex-1 md:truncate md:text-left\",\n    searchKeys: \"hidden items-center gap-0.5 md:flex\",\n    actions: \"ml-auto flex shrink-0 items-center gap-2\",\n    main: \"min-w-0 flex-1 px-4 py-6 md:px-6 md:py-8\",\n  },\n});\nconst s = appShell();\n\ninterface ShellState {\n  collapsed: boolean;\n  setCollapsed: (value: boolean) => void;\n  open: boolean;\n  setOpen: (value: boolean) => void;\n  inDrawer: boolean;\n}\nconst ShellContext = React.createContext<ShellState | null>(null);\nconst useShell = () => {\n  const ctx = React.useContext(ShellContext);\n  if (!ctx) throw new Error(\"AppShell parts must be inside <AppShell.Root>\");\n  return ctx;\n};\n\nexport type AppShellRootProps = React.ComponentProps<\"div\"> & {\n  /** The sidebar starts collapsed to its icons (desktop). */\n  defaultCollapsed?: boolean;\n  /** Controlled collapse (desktop): pair with `onCollapsedChange` to persist the choice. */\n  collapsed?: boolean;\n  /** Called when the sidebar collapses or expands. */\n  onCollapsedChange?: (collapsed: boolean) => void;\n  /** The words of the \"skip to content\" link (`Skip to content`), the first tab stop; it lands on `AppShell.Main`. Without it, no link. */\n  skipLabel?: string;\n  /**\n   * The shortcut that folds and unfolds the sidebar (a combination: `mod+b` is ⌘B on a Mac, Ctrl+B elsewhere), or `false`\n   * for none.\n   * @default \"mod+b\"\n   */\n  collapseShortcut?: string | false;\n};\n\n/** The shell: holds the collapse (desktop) and the drawer (phone) state. Children: Sidebar, then Body. */\nexport function AppShellRoot({ defaultCollapsed = false, collapsed: controlled, onCollapsedChange, skipLabel, collapseShortcut = \"mod+b\", className, children, ...props }: AppShellRootProps) {\n  const [own, setOwn] = React.useState(defaultCollapsed);\n  const [open, setOpen] = React.useState(false);\n  const collapsed = controlled ?? own;\n  const setCollapsed = React.useCallback(\n    (value: boolean) => {\n      if (controlled === undefined) setOwn(value);\n      onCollapsedChange?.(value);\n    },\n    [controlled, onCollapsedChange],\n  );\n  const value = React.useMemo(() => ({ collapsed, setCollapsed, open, setOpen, inDrawer: false }), [collapsed, setCollapsed, open]);\n  useShortcuts(collapseShortcut ? { [collapseShortcut]: () => setCollapsed(!collapsed) } : {});\n  return (\n    <ShellContext.Provider value={value}>\n      <div className={s.root({ className })} {...props}>\n        {skipLabel && <SkipLink href=\"#content\">{skipLabel}</SkipLink>}\n        {children}\n      </div>\n    </ShellContext.Provider>\n  );\n}\n\nexport type AppShellSidebarProps = Omit<React.ComponentProps<\"nav\">, \"children\"> & {\n  /** The navigation's accessible name (`Studio`, `Administration`). */\n  label: string;\n  /** The brand at the top: the product's mark and name (a link home through `asChild` of your router, or plain). */\n  brand?: React.ReactNode;\n  /** The sections: `AppShell.Group` and `AppShell.Item`. */\n  children: React.ReactNode;\n  /** At the bottom, above the collapse button: the account, a plan, the version. */\n  footer?: React.ReactNode;\n  /** The collapse button's words, `[collapse, expand]` (desktop only). Without it the sidebar cannot collapse. */\n  collapseLabels?: readonly [string, string];\n  /** The drawer's close button words (phone). */\n  closeLabel: string;\n};\n\nfunction SidebarContent({ brand, children, footer, collapseLabels, closeLabel }: Pick<AppShellSidebarProps, \"brand\" | \"children\" | \"footer\" | \"collapseLabels\" | \"closeLabel\">) {\n  const { collapsed, setCollapsed, inDrawer } = useShell();\n  return (\n    <>\n      <div className={s.brand()}>\n        {brand}\n        {inDrawer && (\n          <DialogPrimitive.Close className={cn(s.menuButton(), \"ml-auto flex\")} aria-label={closeLabel}>\n            <CloseGlyph className=\"h-4 w-4\" />\n          </DialogPrimitive.Close>\n        )}\n      </div>\n      <div className={s.nav()}>{children}</div>\n      {(footer || (collapseLabels && !inDrawer)) && (\n        <div className={s.footer()}>\n          {footer}\n          {collapseLabels && !inDrawer && (\n            <button type=\"button\" className={s.collapse()} aria-expanded={!collapsed} onClick={() => setCollapsed(!collapsed)}>\n              <ChevronGlyph direction={collapsed ? \"right\" : \"left\"} className=\"h-4 w-4\" />\n              <span className={collapsed ? \"sr-only\" : undefined}>{collapsed ? collapseLabels[1] : collapseLabels[0]}</span>\n            </button>\n          )}\n        </div>\n      )}\n    </>\n  );\n}\n\n/** The sidebar: on a desktop a column that collapses to its icons; on a phone the same content in a drawer. */\nexport function AppShellSidebar({ label, brand, children, footer, collapseLabels, closeLabel, className, ...props }: AppShellSidebarProps) {\n  const shell = useShell();\n  const content = { brand, children, footer, collapseLabels, closeLabel };\n  return (\n    <>\n      <nav aria-label={label} data-collapsed={shell.collapsed ? \"\" : undefined} className={s.sidebar({ className })} {...props}>\n        <SidebarContent {...content} />\n      </nav>\n      <DialogPrimitive.Root open={shell.open} onOpenChange={shell.setOpen}>\n        <DialogPrimitive.Portal>\n          <DialogPrimitive.Overlay className={s.overlay()} />\n          <DialogPrimitive.Content className={s.drawer()} aria-describedby={undefined}>\n            <DialogPrimitive.Title className=\"sr-only\">{label}</DialogPrimitive.Title>\n            <ShellContext.Provider value={{ ...shell, collapsed: false, inDrawer: true }}>\n              <nav aria-label={label} className=\"flex min-h-0 flex-1 flex-col\" onClick={(e) => (e.target as Element).closest(\"a\") && shell.setOpen(false)}>\n                <SidebarContent {...content} />\n              </nav>\n            </ShellContext.Provider>\n          </DialogPrimitive.Content>\n        </DialogPrimitive.Portal>\n      </DialogPrimitive.Root>\n    </>\n  );\n}\n\nexport type AppShellGroupProps = React.ComponentProps<\"p\"> & {\n  /** The group's name, above its items (hidden when the sidebar is collapsed). */\n  children: React.ReactNode;\n};\n\n/** A heading between groups of items. */\nexport function AppShellGroup({ className, ...props }: AppShellGroupProps) {\n  return <p className={s.group({ className })} {...props} />;\n}\n\nexport type AppShellItemProps = Omit<React.ComponentProps<\"a\">, \"children\"> & {\n  /** The item's icon (a signature icon): it stays when the sidebar collapses. */\n  icon?: React.ReactNode;\n  /** Its words: the accessible name, hidden visually when collapsed (the icon carries a tooltip through `title`). */\n  label: string;\n  /** The screen it opens is the current one: `aria-current=\"page\"`. */\n  current?: boolean;\n  /** A count beside it (unread, pending): a number or a few characters. */\n  badge?: React.ReactNode;\n  /**\n   * A keyboard shortcut that goes to it: a sequence (`g d`: G then D) or a combination (`mod+1`). It clicks the item, so a\n   * router link navigates. The keys are shown on hover and focus when the sidebar is open.\n   */\n  shortcut?: string;\n  /** Renders your link (Next's `Link`) with the item's look: pass it as the only child. */\n  asChild?: boolean;\n  /** Your link element when `asChild`. */\n  children?: React.ReactElement;\n};\n\n/** A destination of the sidebar: icon, words, a count. */\nexport function AppShellItem({ icon, label, current, badge, shortcut, asChild, children, className, ...props }: AppShellItemProps) {\n  const { collapsed, inDrawer } = useShell();\n  const element = React.useRef<HTMLAnchorElement>(null);\n  const apple = useApple();\n  // Only the sidebar's own items listen: the drawer holds a copy of them, open or not.\n  useShortcuts(shortcut && !inDrawer ? { [shortcut]: () => element.current?.click() } : {});\n  const Comp = asChild ? Slot.Root : \"a\";\n  const inner = (\n    <>\n      {icon}\n      <span className={s.itemLabel()}>{label}</span>\n      {badge != null && <span className={s.itemBadge()}>{badge}</span>}\n      {shortcut && !inDrawer ? (\n        <span className={s.itemHint()} aria-hidden>\n          {formatShortcut(shortcut, apple).map((key) => (\n            <Kbd key={key} size=\"sm\">\n              {key}\n            </Kbd>\n          ))}\n        </span>\n      ) : null}\n    </>\n  );\n  return (\n    <Comp ref={element} aria-current={current ? \"page\" : undefined} aria-keyshortcuts={shortcut ? ariaKeyShortcuts(shortcut, apple) : undefined} title={collapsed ? label : undefined} className={s.item({ className })} {...props}>\n      {asChild && children ? React.cloneElement(children, undefined, inner) : inner}\n    </Comp>\n  );\n}\n\n/** The column right of the sidebar: Header, then Main. */\nexport function AppShellBody({ className, ...props }: React.ComponentProps<\"div\">) {\n  return <div className={s.body({ className })} {...props} />;\n}\n\nexport type AppShellHeaderProps = Omit<React.ComponentProps<\"header\">, \"title\"> & {\n  /** The screen's title (an `h1`). */\n  title?: React.ReactNode;\n  /** The button that opens the drawer on a phone: its words. */\n  menuLabel: string;\n  /** The screen's actions, on the right. */\n  actions?: React.ReactNode;\n};\n\n/** The top of the screen: the drawer's button (phone), the title, the actions. Sticky. */\nexport function AppShellHeader({ title, menuLabel, actions, className, children, ...props }: AppShellHeaderProps) {\n  const { open, setOpen } = useShell();\n  return (\n    <header className={s.header({ className })} {...props}>\n      <button type=\"button\" className={s.menuButton()} aria-label={menuLabel} aria-expanded={open} aria-haspopup=\"dialog\" onClick={() => setOpen(true)}>\n        <svg viewBox=\"0 0 24 24\" className=\"h-4 w-4\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" aria-hidden>\n          <path d=\"M4 7h16M4 12h16M4 17h10\" />\n        </svg>\n      </button>\n      {title && <h1 className={s.title()}>{title}</h1>}\n      {children}\n      {actions && <div className={s.actions()}>{actions}</div>}\n    </header>\n  );\n}\n\nexport type AppShellSearchProps = Omit<React.ComponentProps<\"button\">, \"children\" | \"onClick\"> & {\n  /** The words (\"Search\", \"Search creators\"): the accessible name, shown beside the keys on a desktop. */\n  label: string;\n  /** Called when the button is pressed or the shortcut is typed: open your command palette (`CommandDialog`) here. */\n  onOpen: () => void;\n  /**\n   * The shortcut that opens it (a combination); shown on its keys.\n   * @default \"mod+k\"\n   */\n  shortcut?: string;\n};\n\n/** The header's search: a button that looks like a field (a magnifier, its words, ⌘K) and opens the app's command palette. */\nexport function AppShellSearch({ label, onOpen, shortcut = \"mod+k\", className, ...props }: AppShellSearchProps) {\n  const apple = useApple();\n  useShortcuts({ [shortcut]: () => onOpen() });\n  return (\n    <button type=\"button\" className={s.search({ className })} aria-keyshortcuts={ariaKeyShortcuts(shortcut, apple)} onClick={onOpen} {...props}>\n      <SearchGlyph />\n      <span className={s.searchLabel()}>{label}</span>\n      <span className={s.searchKeys()} aria-hidden>\n        {formatShortcut(shortcut, apple).map((key) => (\n          <Kbd key={key} size=\"sm\">\n            {key}\n          </Kbd>\n        ))}\n      </span>\n    </button>\n  );\n}\n\n/** The screen's content. */\nexport function AppShellMain({ className, ...props }: React.ComponentProps<\"main\">) {\n  return <main id=\"content\" tabIndex={-1} className={s.main({ className })} {...props} />;\n}\n\nexport const AppShell = {\n  Root: AppShellRoot,\n  Sidebar: AppShellSidebar,\n  Group: AppShellGroup,\n  Item: AppShellItem,\n  Body: AppShellBody,\n  Header: AppShellHeader,\n  Search: AppShellSearch,\n  Main: AppShellMain,\n};\n"
+      "content": "// Client (the collapse, the drawer, the shortcuts). The shell of an application screen, read from the products' consoles\n// (Orochia admin and studio, Orazaka web-admin and web-client): a sidebar of sections that collapses to its icons on a\n// desktop, a header with the screen's title, a search that opens the app's command palette and its actions, the content —\n// and below `md` the sidebar becomes a drawer opened from the header (Radix Dialog: focus trap, Escape, focus return).\n// Keyboard: ⌘/Ctrl+B folds the sidebar, ⌘/Ctrl+K opens the search, `g` then a letter goes to a section (`shortcut` of an\n// item). Words arrive as props; links through `asChild`.\n// `desktop` (ADR-002): the shell is the window of a desktop app (the Orazaka Mac app, Tauri 2): the sidebar is always\n// there (a window has a minimum width, no drawer), its top clears the traffic lights, the header and the sidebar's top are\n// the title bar (`data-tauri-drag-region`: dragging them moves the window), the density is the desktop's (32 px rows,\n// 13 px text, a 48 px header), the chrome is not selectable, and the content scrolls under a fixed header.\nimport { SkipLink } from \"@krizaka/ui/skip-link\";\nimport { Dialog as DialogPrimitive, Slot } from \"radix-ui\";\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { cn } from \"../cn\";\nimport { ChevronGlyph, CloseGlyph, SearchGlyph } from \"../glyphs\";\nimport { Kbd } from \"../kbd\";\nimport { ariaKeyShortcuts, formatShortcut, useApple, useShortcuts } from \"./shortcuts\";\n\nexport const appShell = tv({\n  slots: {\n    root: \"flex min-h-dvh w-full bg-surface-0 text-fg data-desktop:h-[var(--kz-window-height,100dvh)] data-desktop:overflow-hidden\",\n    sidebar:\n      \"sticky top-0 hidden h-dvh shrink-0 flex-col border-r border-border-subtle bg-surface-1 transition-[width] duration-300 motion-reduce:transition-none md:flex \" +\n      \"w-64 data-collapsed:w-[4.25rem] \" +\n      \"[[data-desktop]_&]:static [[data-desktop]_&]:flex [[data-desktop]_&]:h-auto [[data-desktop]_&]:w-60 [[data-desktop]_&]:select-none [[data-desktop]_&]:data-collapsed:w-[4.75rem]\",\n    titlebar: \"h-[var(--kz-titlebar-inset,1.75rem)] shrink-0\",\n    drawer:\n      \"kz-dialog fixed inset-y-0 left-0 z-50 flex w-[min(20rem,88vw)] flex-col border-r border-border-default bg-surface-1 pl-[env(safe-area-inset-left)] shadow-lg focus:outline-hidden\",\n    overlay: \"kz-overlay fixed inset-0 z-50 bg-overlay backdrop-blur-xs\",\n    brand: \"flex h-14 shrink-0 items-center gap-2.5 px-4 font-display text-[15px] font-bold tracking-tight [[data-collapsed]_&]:justify-center [[data-collapsed]_&]:px-0 [[data-desktop]_&]:h-11\",\n    nav: \"flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto px-2 py-2\",\n    group: \"mt-3 mb-1 px-3 font-mono text-[10.5px] font-semibold uppercase tracking-[0.14em] text-fg-secondary [[data-collapsed]_&]:sr-only\",\n    item:\n      \"group/item relative flex h-10 items-center gap-3 rounded-lg px-3 text-sm font-medium text-fg-secondary no-underline transition-colors \" +\n      \"hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring \" +\n      \"aria-[current=page]:bg-accent-soft aria-[current=page]:text-fg \" +\n      \"aria-[current=page]:before:absolute aria-[current=page]:before:inset-y-2 aria-[current=page]:before:-left-2 aria-[current=page]:before:w-1 aria-[current=page]:before:rounded-full aria-[current=page]:before:bg-accent \" +\n      \"[[data-collapsed]_&]:justify-center [[data-collapsed]_&]:px-0 [&>svg]:h-[18px] [&>svg]:w-[18px] [&>svg]:shrink-0 \" +\n      \"[[data-desktop]_&]:h-8 [[data-desktop]_&]:cursor-default [[data-desktop]_&]:rounded-md [[data-desktop]_&]:text-[13px] [[data-desktop]_&_svg]:h-4 [[data-desktop]_&_svg]:w-4\",\n    itemLabel: \"min-w-0 flex-1 truncate [[data-collapsed]_&]:sr-only\",\n    itemHint: \"ml-auto hidden items-center gap-0.5 text-fg-secondary group-hover/item:flex group-focus-visible/item:flex [[data-collapsed]_&]:!hidden\",\n    itemBadge:\n      \"ml-auto inline-flex min-w-5 items-center justify-center rounded-full bg-accent px-1.5 text-[11px] font-bold text-on-accent \" +\n      \"[[data-collapsed]_&]:absolute [[data-collapsed]_&]:right-1.5 [[data-collapsed]_&]:top-1 [[data-collapsed]_&]:min-w-4 [[data-collapsed]_&]:px-1 [[data-collapsed]_&]:text-[10px]\",\n    footer: \"shrink-0 border-t border-border-subtle p-2\",\n    collapse:\n      \"hidden h-9 w-full items-center gap-2 rounded-lg px-3 text-xs font-medium text-fg-secondary hover:bg-surface-2 hover:text-fg md:flex \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring [[data-collapsed]_&]:justify-center [[data-collapsed]_&]:px-0\",\n    body: \"flex min-w-0 flex-1 flex-col [[data-desktop]_&]:min-h-0 [[data-desktop]_&]:overflow-y-auto\",\n    header:\n      \"sticky top-0 z-30 flex h-14 shrink-0 items-center gap-3 border-b border-border-subtle bg-surface-0/85 px-4 backdrop-blur-xl md:px-6 \" +\n      \"[[data-desktop]_&]:h-12 [[data-desktop]_&]:select-none [[data-desktop]_&]:px-5\",\n    menuButton:\n      \"inline-flex h-9 w-9 items-center justify-center rounded-lg border border-border-subtle bg-surface-1 text-fg md:hidden [[data-desktop]_&]:hidden \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring\",\n    title: \"min-w-0 flex-1 truncate font-display text-base font-bold tracking-tight [[data-desktop]_&]:text-[15px]\",\n    search:\n      \"inline-flex h-9 min-w-9 items-center justify-center gap-2 rounded-lg border border-border-subtle bg-surface-1 px-2.5 text-sm text-fg-secondary transition-colors \" +\n      \"hover:border-border-default hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring md:w-56 md:justify-start [&>svg]:h-4 [&>svg]:w-4 [&>svg]:shrink-0\",\n    searchLabel: \"sr-only md:not-sr-only md:flex-1 md:truncate md:text-left\",\n    searchKeys: \"hidden items-center gap-0.5 md:flex\",\n    actions: \"ml-auto flex shrink-0 items-center gap-2\",\n    main: \"min-w-0 flex-1 px-4 py-6 md:px-6 md:py-8 [[data-desktop]_&]:px-6 [[data-desktop]_&]:py-6\",\n  },\n});\nconst s = appShell();\n\ninterface ShellState {\n  collapsed: boolean;\n  setCollapsed: (value: boolean) => void;\n  open: boolean;\n  setOpen: (value: boolean) => void;\n  inDrawer: boolean;\n  desktop: boolean;\n}\nconst ShellContext = React.createContext<ShellState | null>(null);\nconst useShell = () => {\n  const ctx = React.useContext(ShellContext);\n  if (!ctx) throw new Error(\"AppShell parts must be inside <AppShell.Root>\");\n  return ctx;\n};\n\nexport type AppShellRootProps = React.ComponentProps<\"div\"> & {\n  /** The sidebar starts collapsed to its icons (desktop). */\n  defaultCollapsed?: boolean;\n  /** Controlled collapse (desktop): pair with `onCollapsedChange` to persist the choice. */\n  collapsed?: boolean;\n  /** Called when the sidebar collapses or expands. */\n  onCollapsedChange?: (collapsed: boolean) => void;\n  /** The words of the \"skip to content\" link (`Skip to content`), the first tab stop; it lands on `AppShell.Main`. Without it, no link. */\n  skipLabel?: string;\n  /**\n   * The shortcut that folds and unfolds the sidebar (a combination: `mod+b` is ⌘B on a Mac, Ctrl+B elsewhere), or `false`\n   * for none.\n   * @default \"mod+b\"\n   */\n  collapseShortcut?: string | false;\n  /**\n   * The shell is a desktop app's window (the Orazaka Mac app, Tauri 2 — ADR-002): no drawer, the sidebar's top clears the\n   * window's traffic lights (`--kz-titlebar-inset`, 28 px; the window's height is `--kz-window-height`, the viewport by default), the header and that top move the window\n   * (`data-tauri-drag-region`), a denser layout, the chrome not selectable. In a browser it is a fixed-height shell.\n   */\n  desktop?: boolean;\n};\n\n/** The shell: holds the collapse (desktop) and the drawer (phone) state. Children: Sidebar, then Body. */\nexport function AppShellRoot({ defaultCollapsed = false, collapsed: controlled, onCollapsedChange, skipLabel, collapseShortcut = \"mod+b\", desktop = false, className, children, ...props }: AppShellRootProps) {\n  const [own, setOwn] = React.useState(defaultCollapsed);\n  const [open, setOpen] = React.useState(false);\n  const collapsed = controlled ?? own;\n  const setCollapsed = React.useCallback(\n    (value: boolean) => {\n      if (controlled === undefined) setOwn(value);\n      onCollapsedChange?.(value);\n    },\n    [controlled, onCollapsedChange],\n  );\n  const value = React.useMemo(() => ({ collapsed, setCollapsed, open, setOpen, inDrawer: false, desktop }), [collapsed, setCollapsed, open, desktop]);\n  useShortcuts(collapseShortcut ? { [collapseShortcut]: () => setCollapsed(!collapsed) } : {});\n  return (\n    <ShellContext.Provider value={value}>\n      <div data-desktop={desktop ? \"\" : undefined} className={s.root({ className })} {...props}>\n        {skipLabel && <SkipLink href=\"#content\">{skipLabel}</SkipLink>}\n        {children}\n      </div>\n    </ShellContext.Provider>\n  );\n}\n\nexport type AppShellSidebarProps = Omit<React.ComponentProps<\"nav\">, \"children\"> & {\n  /** The navigation's accessible name (`Studio`, `Administration`). */\n  label: string;\n  /** The brand at the top: the product's mark and name (a link home through `asChild` of your router, or plain). */\n  brand?: React.ReactNode;\n  /** The sections: `AppShell.Group` and `AppShell.Item`. */\n  children: React.ReactNode;\n  /** At the bottom, above the collapse button: the account, a plan, the version. */\n  footer?: React.ReactNode;\n  /** The collapse button's words, `[collapse, expand]` (desktop only). Without it the sidebar cannot collapse. */\n  collapseLabels?: readonly [string, string];\n  /** The drawer's close button words (phone). */\n  closeLabel: string;\n};\n\nfunction SidebarContent({ brand, children, footer, collapseLabels, closeLabel }: Pick<AppShellSidebarProps, \"brand\" | \"children\" | \"footer\" | \"collapseLabels\" | \"closeLabel\">) {\n  const { collapsed, setCollapsed, inDrawer, desktop } = useShell();\n  const drag = desktop ? { \"data-tauri-drag-region\": \"\" } : {};\n  return (\n    <>\n      {desktop && <div aria-hidden className={s.titlebar()} {...drag} />}\n      <div className={s.brand()} {...drag}>\n        {brand}\n        {inDrawer && (\n          <DialogPrimitive.Close className={cn(s.menuButton(), \"ml-auto flex\")} aria-label={closeLabel}>\n            <CloseGlyph className=\"h-4 w-4\" />\n          </DialogPrimitive.Close>\n        )}\n      </div>\n      <div className={s.nav()}>{children}</div>\n      {(footer || (collapseLabels && !inDrawer)) && (\n        <div className={s.footer()}>\n          {footer}\n          {collapseLabels && !inDrawer && (\n            <button type=\"button\" className={s.collapse()} aria-expanded={!collapsed} onClick={() => setCollapsed(!collapsed)}>\n              <ChevronGlyph direction={collapsed ? \"right\" : \"left\"} className=\"h-4 w-4\" />\n              <span className={collapsed ? \"sr-only\" : undefined}>{collapsed ? collapseLabels[1] : collapseLabels[0]}</span>\n            </button>\n          )}\n        </div>\n      )}\n    </>\n  );\n}\n\n/** The sidebar: on a desktop a column that collapses to its icons; on a phone the same content in a drawer. */\nexport function AppShellSidebar({ label, brand, children, footer, collapseLabels, closeLabel, className, ...props }: AppShellSidebarProps) {\n  const shell = useShell();\n  const content = { brand, children, footer, collapseLabels, closeLabel };\n  return (\n    <>\n      <nav aria-label={label} data-collapsed={shell.collapsed ? \"\" : undefined} className={s.sidebar({ className })} {...props}>\n        <SidebarContent {...content} />\n      </nav>\n      {!shell.desktop && (\n      <DialogPrimitive.Root open={shell.open} onOpenChange={shell.setOpen}>\n        <DialogPrimitive.Portal>\n          <DialogPrimitive.Overlay className={s.overlay()} />\n          <DialogPrimitive.Content className={s.drawer()} aria-describedby={undefined}>\n            <DialogPrimitive.Title className=\"sr-only\">{label}</DialogPrimitive.Title>\n            <ShellContext.Provider value={{ ...shell, collapsed: false, inDrawer: true }}>\n              <nav aria-label={label} className=\"flex min-h-0 flex-1 flex-col\" onClick={(e) => (e.target as Element).closest(\"a\") && shell.setOpen(false)}>\n                <SidebarContent {...content} />\n              </nav>\n            </ShellContext.Provider>\n          </DialogPrimitive.Content>\n        </DialogPrimitive.Portal>\n      </DialogPrimitive.Root>\n      )}\n    </>\n  );\n}\n\nexport type AppShellGroupProps = React.ComponentProps<\"p\"> & {\n  /** The group's name, above its items (hidden when the sidebar is collapsed). */\n  children: React.ReactNode;\n};\n\n/** A heading between groups of items. */\nexport function AppShellGroup({ className, ...props }: AppShellGroupProps) {\n  return <p className={s.group({ className })} {...props} />;\n}\n\nexport type AppShellItemProps = Omit<React.ComponentProps<\"a\">, \"children\"> & {\n  /** The item's icon (a signature icon): it stays when the sidebar collapses. */\n  icon?: React.ReactNode;\n  /** Its words: the accessible name, hidden visually when collapsed (the icon carries a tooltip through `title`). */\n  label: string;\n  /** The screen it opens is the current one: `aria-current=\"page\"`. */\n  current?: boolean;\n  /** A count beside it (unread, pending): a number or a few characters. */\n  badge?: React.ReactNode;\n  /**\n   * A keyboard shortcut that goes to it: a sequence (`g d`: G then D) or a combination (`mod+1`). It clicks the item, so a\n   * router link navigates. The keys are shown on hover and focus when the sidebar is open.\n   */\n  shortcut?: string;\n  /** Renders your link (Next's `Link`) with the item's look: pass it as the only child. */\n  asChild?: boolean;\n  /** Your link element when `asChild`. */\n  children?: React.ReactElement;\n};\n\n/** A destination of the sidebar: icon, words, a count. */\nexport function AppShellItem({ icon, label, current, badge, shortcut, asChild, children, className, ...props }: AppShellItemProps) {\n  const { collapsed, inDrawer } = useShell();\n  const element = React.useRef<HTMLAnchorElement>(null);\n  const apple = useApple();\n  // Only the sidebar's own items listen: the drawer holds a copy of them, open or not.\n  useShortcuts(shortcut && !inDrawer ? { [shortcut]: () => element.current?.click() } : {});\n  const Comp = asChild ? Slot.Root : \"a\";\n  const inner = (\n    <>\n      {icon}\n      <span className={s.itemLabel()}>{label}</span>\n      {badge != null && <span className={s.itemBadge()}>{badge}</span>}\n      {shortcut && !inDrawer ? (\n        <span className={s.itemHint()} aria-hidden>\n          {formatShortcut(shortcut, apple).map((key) => (\n            <Kbd key={key} size=\"sm\">\n              {key}\n            </Kbd>\n          ))}\n        </span>\n      ) : null}\n    </>\n  );\n  return (\n    <Comp ref={element} aria-current={current ? \"page\" : undefined} aria-keyshortcuts={shortcut ? ariaKeyShortcuts(shortcut, apple) : undefined} title={collapsed ? label : undefined} className={s.item({ className })} {...props}>\n      {asChild && children ? React.cloneElement(children, undefined, inner) : inner}\n    </Comp>\n  );\n}\n\n/** The column right of the sidebar: Header, then Main. */\nexport function AppShellBody({ className, ...props }: React.ComponentProps<\"div\">) {\n  return <div className={s.body({ className })} {...props} />;\n}\n\nexport type AppShellHeaderProps = Omit<React.ComponentProps<\"header\">, \"title\"> & {\n  /** The screen's title (an `h1`). */\n  title?: React.ReactNode;\n  /** The button that opens the drawer on a phone: its words. */\n  menuLabel: string;\n  /** The screen's actions, on the right. */\n  actions?: React.ReactNode;\n};\n\n/** The top of the screen: the drawer's button (phone), the title, the actions. Sticky. */\nexport function AppShellHeader({ title, menuLabel, actions, className, children, ...props }: AppShellHeaderProps) {\n  const { open, setOpen, desktop } = useShell();\n  const drag = desktop ? { \"data-tauri-drag-region\": \"\" } : {};\n  return (\n    <header className={s.header({ className })} {...drag} {...props}>\n      <button type=\"button\" className={s.menuButton()} aria-label={menuLabel} aria-expanded={open} aria-haspopup=\"dialog\" onClick={() => setOpen(true)}>\n        <svg viewBox=\"0 0 24 24\" className=\"h-4 w-4\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" aria-hidden>\n          <path d=\"M4 7h16M4 12h16M4 17h10\" />\n        </svg>\n      </button>\n      {title && (\n        <h1 className={s.title()} {...drag}>\n          {title}\n        </h1>\n      )}\n      {children}\n      {actions && <div className={s.actions()}>{actions}</div>}\n    </header>\n  );\n}\n\nexport type AppShellSearchProps = Omit<React.ComponentProps<\"button\">, \"children\" | \"onClick\"> & {\n  /** The words (\"Search\", \"Search creators\"): the accessible name, shown beside the keys on a desktop. */\n  label: string;\n  /** Called when the button is pressed or the shortcut is typed: open your command palette (`CommandDialog`) here. */\n  onOpen: () => void;\n  /**\n   * The shortcut that opens it (a combination); shown on its keys.\n   * @default \"mod+k\"\n   */\n  shortcut?: string;\n};\n\n/** The header's search: a button that looks like a field (a magnifier, its words, ⌘K) and opens the app's command palette. */\nexport function AppShellSearch({ label, onOpen, shortcut = \"mod+k\", className, ...props }: AppShellSearchProps) {\n  const apple = useApple();\n  useShortcuts({ [shortcut]: () => onOpen() });\n  return (\n    <button type=\"button\" className={s.search({ className })} aria-keyshortcuts={ariaKeyShortcuts(shortcut, apple)} onClick={onOpen} {...props}>\n      <SearchGlyph />\n      <span className={s.searchLabel()}>{label}</span>\n      <span className={s.searchKeys()} aria-hidden>\n        {formatShortcut(shortcut, apple).map((key) => (\n          <Kbd key={key} size=\"sm\">\n            {key}\n          </Kbd>\n        ))}\n      </span>\n    </button>\n  );\n}\n\n/** The screen's content. */\nexport function AppShellMain({ className, ...props }: React.ComponentProps<\"main\">) {\n  return <main id=\"content\" tabIndex={-1} className={s.main({ className })} {...props} />;\n}\n\nexport const AppShell = {\n  Root: AppShellRoot,\n  Sidebar: AppShellSidebar,\n  Group: AppShellGroup,\n  Item: AppShellItem,\n  Body: AppShellBody,\n  Header: AppShellHeader,\n  Search: AppShellSearch,\n  Main: AppShellMain,\n};\n"
     },
     {
       "path": "app-shell/index.ts",
-      "content": "/** @krizaka/ui/app-shell — `AppShell.Root/Sidebar/Group/Item/Body/Header/Search/Main`: an application screen (sidebar that collapses, header with a search for the command palette, drawer on a phone, keyboard shortcuts), and `useShortcuts`. Client. */\nexport {\n  AppShell,\n  appShell,\n  AppShellBody,\n  AppShellGroup,\n  type AppShellGroupProps,\n  AppShellHeader,\n  type AppShellHeaderProps,\n  AppShellItem,\n  type AppShellItemProps,\n  AppShellMain,\n  AppShellRoot,\n  type AppShellRootProps,\n  AppShellSearch,\n  type AppShellSearchProps,\n  AppShellSidebar,\n  type AppShellSidebarProps,\n} from \"./app-shell\";\nexport { ariaKeyShortcuts, formatShortcut, matchesCombo, parseCombo, type ShortcutMap, useApple, useShortcuts } from \"./shortcuts\";\n"
+      "content": "/** @krizaka/ui/app-shell — `AppShell.Root/Sidebar/Group/Item/Body/Header/Search/Main`: an application screen (sidebar that collapses, header with a search for the command palette, drawer on a phone, keyboard shortcuts), and `useShortcuts`. Client. */\nexport {\n  AppShell,\n  appShell,\n  AppShellBody,\n  AppShellGroup,\n  type AppShellGroupProps,\n  AppShellHeader,\n  type AppShellHeaderProps,\n  AppShellItem,\n  type AppShellItemProps,\n  AppShellMain,\n  AppShellRoot,\n  type AppShellRootProps,\n  AppShellSearch,\n  type AppShellSearchProps,\n  AppShellSidebar,\n  type AppShellSidebarProps,\n} from \"./app-shell\";\nexport { acceleratorOf, ariaKeyShortcuts, formatShortcut, matchesCombo, parseCombo, type ShortcutMap, useApple, useShortcuts } from \"./shortcuts\";\n"
     },
     {
       "path": "app-shell/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"App shell\",\n  summary: \"The shell of an application screen: a sidebar of sections that collapses to its icons on a desktop and opens as a drawer on a phone, a sticky header with the screen's title, a search that opens the command palette and its actions, the content — and the keyboard shortcuts a console lives by (⌘B, ⌘K, `g` then a letter).\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  parity: { native: { status: \"n/a\", reason: \"On a phone the app shell is a tab bar, a header and a screen.\", use: \"tab-bar\" }, desktop: \"web\" },\n  whenToUse: [\"Every signed-in screen of a product: a studio, a console, an administration.\", \"When the app has more than four destinations — fewer fit a NavBar.\"],\n  whenNotToUse: [\n    { when: \"For a public page of a site.\", use: \"marketing-layout\" },\n    { when: \"For a mobile app's tabs: React Native has its own tab bar.\" },\n  ],\n  bestPractices: [\"Five to nine items, grouped by what the user does (`AppShell.Group`), the current one marked with `current`.\", \"Give every item an icon: it is all that remains when the sidebar collapses (its words become a tooltip).\", \"Persist the collapse with `collapsed` + `onCollapsedChange`; put the account in the sidebar's `footer`.\", \"Render your router's links with `AppShell.Item asChild`.\", \"Give the sections a `shortcut` (`g p`: G then P): it clicks the item, so a router link navigates, and the keys show on hover and focus.\", \"Put `AppShell.Search` in the header and open your `CommandDialog` from its `onOpen`: ⌘K (Ctrl+K) opens it from anywhere.\"],\n  accessibility: {\n    keyboard: [\n      { keys: \"Tab\", action: \"Moves through the sidebar's items, the collapse button and the header's actions.\" },\n      { keys: \"Esc\", action: \"Closes the drawer on a phone and returns the focus to the menu button.\" },\n      { keys: \"⌘B / Ctrl+B\", action: \"Folds and unfolds the sidebar (`collapseShortcut`, off with `false`).\" },\n      { keys: \"⌘K / Ctrl+K\", action: \"Opens the command palette from `AppShell.Search`, in a text field too.\" },\n      { keys: \"G then a letter\", action: \"Goes to the section whose `shortcut` it is; plain keys never fire while typing in a field.\" },\n    ],\n    notes: [\"`skipLabel` on `AppShell.Root` adds the skip link (WCAG 2.4.1): the first tab stop, landing on `AppShell.Main`.\", \"The sidebar is a `nav` named by `label`; the current item carries `aria-current=\\\"page\\\"`.\", \"On a phone the drawer is a modal dialog (Radix): focus trapped inside, Escape and the overlay close it, the focus returns to the button.\", \"The header's title is the screen's `h1`; nested layouts use `headingAs=\\\"h2\\\"`.\", \"A combination is announced with `aria-keyshortcuts` (`Control+K`, `Meta+K` on a Mac); a sequence is not a chord, so it is only shown on its keys, never named to assistive technology.\", \"The platform's keys are known after the first client render (⌘ on a Mac, Ctrl elsewhere): the server and the first render agree.\"],\n  },\n  related: [\"dashboard-layout\", \"nav-bar\", \"dialog\", \"skip-link\", \"command\", \"page-header\", \"action-bar\", \"data-table\", \"form\"],\n  web: {\n    imports: [\"AppShell\", \"useShortcuts\", \"formatShortcut\"],\n    examples: [\n      { name: \"console\", title: \"Console\", description: \"A finance console: sections with `g` shortcuts, ⌘K that opens the palette, a server-side table that refreshes when a form creates a row.\", template: true, purpose: \"operate\", why: \"An operator works all day from the keyboard: jumps between sections, finds a row, creates one and sees the table update.\" },\n      { name: \"orochia-studio\", title: \"Orochia studio\", description: \"Elena's home in the creator studio: the shell around this week's figures, the payout, the auction and the sales.\", template: true, purpose: \"operate\", why: \"A creator moves between the sections of an app and reads this week's figures at home.\" },\n      { name: \"admin-console\", title: \"Administration console\", description: \"A review queue in a console: sections, counts and a sortable table with bulk actions (cards on a phone).\", template: true, purpose: \"operate\", why: \"An administrator works a queue: scans it, sorts it and acts on many rows at once.\" },\n      { name: \"basic\", title: \"The shell alone\", description: \"Sidebar with a group and a count, header with an action, the content.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"App shell\",\n  summary: \"The shell of an application screen: a sidebar of sections that collapses to its icons on a desktop and opens as a drawer on a phone, a sticky header with the screen's title, a search that opens the command palette and its actions, the content — and the keyboard shortcuts a console lives by (⌘B, ⌘K, `g` then a letter).\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  parity: { native: { status: \"n/a\", reason: \"On a phone the app shell is a tab bar, a header and a screen.\", use: \"tab-bar\" }, desktop: \"desktop\" },\n  whenToUse: [\"Every signed-in screen of a product: a studio, a console, an administration.\", \"When the app has more than four destinations — fewer fit a NavBar.\"],\n  whenNotToUse: [\n    { when: \"For a public page of a site.\", use: \"marketing-layout\" },\n    { when: \"For a mobile app's tabs: React Native has its own tab bar.\" },\n  ],\n  bestPractices: [\"Five to nine items, grouped by what the user does (`AppShell.Group`), the current one marked with `current`.\", \"Give every item an icon: it is all that remains when the sidebar collapses (its words become a tooltip).\", \"Persist the collapse with `collapsed` + `onCollapsedChange`; put the account in the sidebar's `footer`.\", \"Render your router's links with `AppShell.Item asChild`.\", \"Give the sections a `shortcut` (`g p`: G then P): it clicks the item, so a router link navigates, and the keys show on hover and focus.\", \"Put `AppShell.Search` in the header and open your `CommandDialog` from its `onOpen`: ⌘K (Ctrl+K) opens it from anywhere.\", \"In a desktop app (the Orazaka Mac app, Tauri 2) pass `desktop`: the header and the sidebar's top become the title bar that moves the window, there is no drawer, the density is the desktop's; build the native menu bar from the same shortcuts with `acceleratorOf` (`mod+k` → `CmdOrCtrl+K`).\"],\n  accessibility: {\n    keyboard: [\n      { keys: \"Tab\", action: \"Moves through the sidebar's items, the collapse button and the header's actions.\" },\n      { keys: \"Esc\", action: \"Closes the drawer on a phone and returns the focus to the menu button.\" },\n      { keys: \"⌘B / Ctrl+B\", action: \"Folds and unfolds the sidebar (`collapseShortcut`, off with `false`).\" },\n      { keys: \"⌘K / Ctrl+K\", action: \"Opens the command palette from `AppShell.Search`, in a text field too.\" },\n      { keys: \"G then a letter\", action: \"Goes to the section whose `shortcut` it is; plain keys never fire while typing in a field.\" },\n    ],\n    notes: [\"`skipLabel` on `AppShell.Root` adds the skip link (WCAG 2.4.1): the first tab stop, landing on `AppShell.Main`.\", \"The sidebar is a `nav` named by `label`; the current item carries `aria-current=\\\"page\\\"`.\", \"On a phone the drawer is a modal dialog (Radix): focus trapped inside, Escape and the overlay close it, the focus returns to the button.\", \"The header's title is the screen's `h1`; nested layouts use `headingAs=\\\"h2\\\"`.\", \"A combination is announced with `aria-keyshortcuts` (`Control+K`, `Meta+K` on a Mac); a sequence is not a chord, so it is only shown on its keys, never named to assistive technology.\", \"The platform's keys are known after the first client render (⌘ on a Mac, Ctrl elsewhere): the server and the first render agree.\", \"With `desktop`, the drag regions are the header, its title and the sidebar's top only — never a control — so every button, link and field keeps its focus and its click; the chrome is not selectable, the content is.\"],\n  },\n  related: [\"dashboard-layout\", \"nav-bar\", \"dialog\", \"skip-link\", \"command\", \"page-header\", \"action-bar\", \"data-table\", \"form\"],\n  web: {\n    imports: [\"AppShell\", \"useShortcuts\", \"formatShortcut\", \"acceleratorOf\"],\n    examples: [\n      { name: \"console\", title: \"Console\", description: \"A finance console: sections with `g` shortcuts, ⌘K that opens the palette, a server-side table that refreshes when a form creates a row.\", template: true, purpose: \"operate\", why: \"An operator works all day from the keyboard: jumps between sections, finds a row, creates one and sees the table update.\" },\n      { name: \"orochia-studio\", title: \"Orochia studio\", description: \"Elena's home in the creator studio: the shell around this week's figures, the payout, the auction and the sales.\", template: true, purpose: \"operate\", why: \"A creator moves between the sections of an app and reads this week's figures at home.\" },\n      { name: \"admin-console\", title: \"Administration console\", description: \"A review queue in a console: sections, counts and a sortable table with bulk actions (cards on a phone).\", template: true, purpose: \"operate\", why: \"An administrator works a queue: scans it, sorts it and acts on many rows at once.\" },\n      { name: \"basic\", title: \"The shell alone\", description: \"Sidebar with a group and a count, header with an action, the content.\" },\n      { name: \"desktop\", title: \"Desktop window\", description: \"The Orazaka Mac app's window (`desktop`): the title bar moves the window and clears the traffic lights, no drawer, the desktop's density, ⌘1–⌘3 to the sections.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "app-shell/shortcuts.ts",
-      "content": "// Keyboard shortcuts for an application: a combination (`mod+k`, `shift+/`, `alt+arrowup`) or a sequence (`g d`: press G,\n// then D). `mod` is ⌘ on Apple devices and Ctrl elsewhere. Plain keys and sequences stay out of text fields; a combination\n// with `mod` works in an input (not in a rich-text editor, where ⌘B is bold). Nothing is decided here about the words.\nimport * as React from \"react\";\n\nimport { useLatest } from \"../media\";\n\nexport type ShortcutMap = Readonly<Record<string, ((event: KeyboardEvent) => void) | undefined>>;\n\nconst isApple = () => typeof navigator !== \"undefined\" && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);\n\nconst ALIASES: Record<string, string> = { esc: \"escape\", return: \"enter\", space: \" \", spacebar: \" \", up: \"arrowup\", down: \"arrowdown\", left: \"arrowleft\", right: \"arrowright\", del: \"delete\", plus: \"+\" };\ntype Modifier = \"mod\" | \"ctrl\" | \"alt\" | \"shift\" | \"meta\";\n\ntype Combo = { key: string; mod: boolean; ctrl: boolean; alt: boolean; shift: boolean; meta: boolean };\n\n/** `\"mod+shift+k\"` → its parts. A lone `+` key is written `plus`. */\nexport function parseCombo(combo: string): Combo {\n  const parts = combo.toLowerCase().split(\"+\").filter(Boolean);\n  const key = ALIASES[parts.at(-1) ?? \"\"] ?? parts.at(-1) ?? \"\";\n  const has = (name: Modifier) => parts.slice(0, -1).includes(name);\n  return { key, mod: has(\"mod\"), ctrl: has(\"ctrl\"), alt: has(\"alt\"), shift: has(\"shift\"), meta: has(\"meta\") };\n}\n\n/** Whether a key event is this combination: its modifiers exactly (`mod` is ⌘ or Ctrl by platform), then its key. */\nexport function matchesCombo(event: Pick<KeyboardEvent, \"key\" | \"metaKey\" | \"ctrlKey\" | \"altKey\" | \"shiftKey\">, combo: string, apple = isApple()): boolean {\n  const want = parseCombo(combo);\n  const meta = want.meta || (want.mod && apple);\n  const ctrl = want.ctrl || (want.mod && !apple);\n  if (event.metaKey !== meta || event.ctrlKey !== ctrl || event.altKey !== want.alt) return false;\n  // Shift is only checked when the binding names it: `?` and `/` need it on most layouts.\n  if (want.shift && !event.shiftKey) return false;\n  return event.key.toLowerCase() === want.key;\n}\n\n/** The keys of a shortcut to show on a keycap: `[\"⌘\", \"K\"]` on a Mac, `[\"Ctrl\", \"K\"]` elsewhere; a sequence `g d` is `[\"G\", \"D\"]`. */\nexport function formatShortcut(shortcut: string, apple = isApple()): string[] {\n  if (shortcut.includes(\" \")) return shortcut.split(/\\s+/).map((key) => key.toUpperCase());\n  const parts = shortcut.split(\"+\").filter(Boolean);\n  const key = parts.at(-1) ?? \"\";\n  const names: Record<string, [string, string]> = { mod: [\"⌘\", \"Ctrl\"], meta: [\"⌘\", \"Win\"], ctrl: [\"⌃\", \"Ctrl\"], alt: [\"⌥\", \"Alt\"], shift: [\"⇧\", \"Shift\"] };\n  const shown = parts.slice(0, -1).map((part) => names[part.toLowerCase()]?.[apple ? 0 : 1] ?? part);\n  const glyph: Record<string, string> = { escape: \"Esc\", enter: \"↵\", arrowup: \"↑\", arrowdown: \"↓\", arrowleft: \"←\", arrowright: \"→\", \" \": \"Space\" };\n  const last = glyph[ALIASES[key.toLowerCase()] ?? key.toLowerCase()] ?? key.toUpperCase();\n  return [...shown, last];\n}\n\nconst noop = () => () => undefined;\n\n/** Whether the person is on an Apple device — `false` on the server and in the first client render (no mismatch), then right. */\nexport function useApple(): boolean {\n  return React.useSyncExternalStore(noop, isApple, () => false);\n}\n\n/** The `aria-keyshortcuts` of a combination (`Control+K`, `Meta+K` on a Mac); a sequence has none (it is not a chord). */\nexport function ariaKeyShortcuts(shortcut: string, apple = isApple()): string | undefined {\n  if (shortcut.includes(\" \")) return undefined;\n  const parts = shortcut.split(\"+\").filter(Boolean);\n  const names: Record<string, string> = { mod: apple ? \"Meta\" : \"Control\", meta: \"Meta\", ctrl: \"Control\", alt: \"Alt\", shift: \"Shift\" };\n  const key = parts.at(-1) ?? \"\";\n  return [...parts.slice(0, -1).map((part) => names[part.toLowerCase()] ?? part), key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1)].join(\"+\");\n}\n\n/** Whether a key press happens in something you type in. */\nfunction isEditable(target: EventTarget | null): { field: boolean; rich: boolean } {\n  const element = target instanceof HTMLElement ? target : null;\n  if (!element) return { field: false, rich: false };\n  const rich = element.isContentEditable;\n  return { field: rich || /^(input|textarea|select)$/i.test(element.tagName), rich };\n}\n\n/**\n * Binds shortcuts for as long as the component lives (`enabled` turns them off). Each key is a combination or a sequence,\n * each value runs when it is pressed; the handler may change on every render. A shortcut that fires is `preventDefault`ed.\n * A sequence waits `timeout` ms for its next key.\n */\nexport function useShortcuts(map: ShortcutMap, { enabled = true, timeout = 900 }: { enabled?: boolean; timeout?: number } = {}) {\n  const latest = useLatest(map);\n  const names = Object.keys(map).sort().join(\"\\n\");\n  React.useEffect(() => {\n    if (!enabled) return;\n    const bindings = names.split(\"\\n\").filter(Boolean);\n    let buffer: { key: string; at: number }[] = [];\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.defaultPrevented || event.isComposing || event.repeat || !event.key) return;\n      const editing = isEditable(event.target);\n      const chord = event.metaKey || event.ctrlKey || event.altKey;\n      const now = Date.now();\n      buffer = [...buffer.filter((entry) => now - entry.at <= timeout), { key: event.key.toLowerCase(), at: now }].slice(-4);\n      for (const binding of bindings) {\n        const handler = latest.current[binding];\n        if (!handler) continue;\n        const keys = binding.toLowerCase().split(/\\s+/).map((key) => ALIASES[key] ?? key);\n        const fired =\n          keys.length > 1\n            ? !chord && !editing.field && buffer.length >= keys.length && keys.every((key, i) => buffer[buffer.length - keys.length + i]?.key === key)\n            : matchesCombo(event, binding) && (chord ? !editing.rich : !editing.field);\n        if (!fired) continue;\n        event.preventDefault();\n        buffer = [];\n        handler(event);\n        return;\n      }\n    };\n    document.addEventListener(\"keydown\", onKeyDown);\n    return () => document.removeEventListener(\"keydown\", onKeyDown);\n  }, [enabled, names, latest, timeout]);\n}\n"
+      "content": "// Keyboard shortcuts for an application: a combination (`mod+k`, `shift+/`, `alt+arrowup`) or a sequence (`g d`: press G,\n// then D). `mod` is ⌘ on Apple devices and Ctrl elsewhere. Plain keys and sequences stay out of text fields; a combination\n// with `mod` works in an input (not in a rich-text editor, where ⌘B is bold). Nothing is decided here about the words.\nimport * as React from \"react\";\n\nimport { useLatest } from \"../media\";\n\nexport type ShortcutMap = Readonly<Record<string, ((event: KeyboardEvent) => void) | undefined>>;\n\nconst isApple = () => typeof navigator !== \"undefined\" && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);\n\nconst ALIASES: Record<string, string> = { esc: \"escape\", return: \"enter\", space: \" \", spacebar: \" \", up: \"arrowup\", down: \"arrowdown\", left: \"arrowleft\", right: \"arrowright\", del: \"delete\", plus: \"+\" };\ntype Modifier = \"mod\" | \"ctrl\" | \"alt\" | \"shift\" | \"meta\";\n\ntype Combo = { key: string; mod: boolean; ctrl: boolean; alt: boolean; shift: boolean; meta: boolean };\n\n/** `\"mod+shift+k\"` → its parts. A lone `+` key is written `plus`. */\nexport function parseCombo(combo: string): Combo {\n  const parts = combo.toLowerCase().split(\"+\").filter(Boolean);\n  const key = ALIASES[parts.at(-1) ?? \"\"] ?? parts.at(-1) ?? \"\";\n  const has = (name: Modifier) => parts.slice(0, -1).includes(name);\n  return { key, mod: has(\"mod\"), ctrl: has(\"ctrl\"), alt: has(\"alt\"), shift: has(\"shift\"), meta: has(\"meta\") };\n}\n\n/** Whether a key event is this combination: its modifiers exactly (`mod` is ⌘ or Ctrl by platform), then its key. */\nexport function matchesCombo(event: Pick<KeyboardEvent, \"key\" | \"metaKey\" | \"ctrlKey\" | \"altKey\" | \"shiftKey\">, combo: string, apple = isApple()): boolean {\n  const want = parseCombo(combo);\n  const meta = want.meta || (want.mod && apple);\n  const ctrl = want.ctrl || (want.mod && !apple);\n  if (event.metaKey !== meta || event.ctrlKey !== ctrl || event.altKey !== want.alt) return false;\n  // Shift is only checked when the binding names it: `?` and `/` need it on most layouts.\n  if (want.shift && !event.shiftKey) return false;\n  return event.key.toLowerCase() === want.key;\n}\n\n/** The keys of a shortcut to show on a keycap: `[\"⌘\", \"K\"]` on a Mac, `[\"Ctrl\", \"K\"]` elsewhere; a sequence `g d` is `[\"G\", \"D\"]`. */\nexport function formatShortcut(shortcut: string, apple = isApple()): string[] {\n  if (shortcut.includes(\" \")) return shortcut.split(/\\s+/).map((key) => key.toUpperCase());\n  const parts = shortcut.split(\"+\").filter(Boolean);\n  const key = parts.at(-1) ?? \"\";\n  const names: Record<string, [string, string]> = { mod: [\"⌘\", \"Ctrl\"], meta: [\"⌘\", \"Win\"], ctrl: [\"⌃\", \"Ctrl\"], alt: [\"⌥\", \"Alt\"], shift: [\"⇧\", \"Shift\"] };\n  const shown = parts.slice(0, -1).map((part) => names[part.toLowerCase()]?.[apple ? 0 : 1] ?? part);\n  const glyph: Record<string, string> = { escape: \"Esc\", enter: \"↵\", arrowup: \"↑\", arrowdown: \"↓\", arrowleft: \"←\", arrowright: \"→\", \" \": \"Space\" };\n  const last = glyph[ALIASES[key.toLowerCase()] ?? key.toLowerCase()] ?? key.toUpperCase();\n  return [...shown, last];\n}\n\n/**\n * The accelerator of a combination for a desktop app's native menu bar (Tauri's `MenuItem`, Electron's — ADR-002):\n * `mod+k` → `CmdOrCtrl+K`, `shift+mod+/` → `Shift+CmdOrCtrl+/`. The menu and the shell then answer the same keys, and the\n * menu shows them. A sequence (`g d`) has none: a menu item takes one chord.\n */\nexport function acceleratorOf(shortcut: string): string | undefined {\n  if (shortcut.trim().includes(\" \")) return undefined;\n  const parts = shortcut.split(\"+\").filter(Boolean);\n  const names: Record<string, string> = { mod: \"CmdOrCtrl\", meta: \"Super\", ctrl: \"Ctrl\", alt: \"Alt\", shift: \"Shift\" };\n  const raw = (parts.at(-1) ?? \"\").toLowerCase();\n  const key = ALIASES[raw] ?? raw;\n  const keys: Record<string, string> = { escape: \"Escape\", enter: \"Enter\", \" \": \"Space\", arrowup: \"Up\", arrowdown: \"Down\", arrowleft: \"Left\", arrowright: \"Right\", delete: \"Delete\", backspace: \"Backspace\", tab: \"Tab\", \"+\": \"Plus\" };\n  const last = keys[key] ?? (key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1));\n  return [...parts.slice(0, -1).map((part) => names[part.toLowerCase()] ?? part), last].join(\"+\");\n}\n\nconst noop = () => () => undefined;\n\n/** Whether the person is on an Apple device — `false` on the server and in the first client render (no mismatch), then right. */\nexport function useApple(): boolean {\n  return React.useSyncExternalStore(noop, isApple, () => false);\n}\n\n/** The `aria-keyshortcuts` of a combination (`Control+K`, `Meta+K` on a Mac); a sequence has none (it is not a chord). */\nexport function ariaKeyShortcuts(shortcut: string, apple = isApple()): string | undefined {\n  if (shortcut.includes(\" \")) return undefined;\n  const parts = shortcut.split(\"+\").filter(Boolean);\n  const names: Record<string, string> = { mod: apple ? \"Meta\" : \"Control\", meta: \"Meta\", ctrl: \"Control\", alt: \"Alt\", shift: \"Shift\" };\n  const key = parts.at(-1) ?? \"\";\n  return [...parts.slice(0, -1).map((part) => names[part.toLowerCase()] ?? part), key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1)].join(\"+\");\n}\n\n/** Whether a key press happens in something you type in. */\nfunction isEditable(target: EventTarget | null): { field: boolean; rich: boolean } {\n  const element = target instanceof HTMLElement ? target : null;\n  if (!element) return { field: false, rich: false };\n  const rich = element.isContentEditable;\n  return { field: rich || /^(input|textarea|select)$/i.test(element.tagName), rich };\n}\n\n/**\n * Binds shortcuts for as long as the component lives (`enabled` turns them off). Each key is a combination or a sequence,\n * each value runs when it is pressed; the handler may change on every render. A shortcut that fires is `preventDefault`ed.\n * A sequence waits `timeout` ms for its next key.\n */\nexport function useShortcuts(map: ShortcutMap, { enabled = true, timeout = 900 }: { enabled?: boolean; timeout?: number } = {}) {\n  const latest = useLatest(map);\n  const names = Object.keys(map).sort().join(\"\\n\");\n  React.useEffect(() => {\n    if (!enabled) return;\n    const bindings = names.split(\"\\n\").filter(Boolean);\n    let buffer: { key: string; at: number }[] = [];\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.defaultPrevented || event.isComposing || event.repeat || !event.key) return;\n      const editing = isEditable(event.target);\n      const chord = event.metaKey || event.ctrlKey || event.altKey;\n      const now = Date.now();\n      buffer = [...buffer.filter((entry) => now - entry.at <= timeout), { key: event.key.toLowerCase(), at: now }].slice(-4);\n      for (const binding of bindings) {\n        const handler = latest.current[binding];\n        if (!handler) continue;\n        const keys = binding.toLowerCase().split(/\\s+/).map((key) => ALIASES[key] ?? key);\n        const fired =\n          keys.length > 1\n            ? !chord && !editing.field && buffer.length >= keys.length && keys.every((key, i) => buffer[buffer.length - keys.length + i]?.key === key)\n            : matchesCombo(event, binding) && (chord ? !editing.rich : !editing.field);\n        if (!fired) continue;\n        event.preventDefault();\n        buffer = [];\n        handler(event);\n        return;\n      }\n    };\n    document.addEventListener(\"keydown\", onKeyDown);\n    return () => document.removeEventListener(\"keydown\", onKeyDown);\n  }, [enabled, names, latest, timeout]);\n}\n"
     },
     {
       "path": "glyphs.tsx",
@@ -375,7 +392,7 @@
     },
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"action-sheet\"\n  | \"activity-feed\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"comparison-table\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"document-viewer\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"force-update-screen\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"genui\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"maintenance-screen\"\n  | \"map\"\n  | \"markdown\"\n  | \"meta-row\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-grid\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"splash-handoff\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"update-prompt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n *   component that answers there, when one does.\n */\nexport type Absence =\n  | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n  | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n  readonly web?: Absence;\n  readonly native?: Absence;\n  readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: string;\n    });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n  readonly parity: Parity;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"action-sheet\"\n  | \"activity-feed\"\n  | \"alert\"\n  | \"app-header\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"captcha\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"comparison-table\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"docs-nav\"\n  | \"document-viewer\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"force-update-screen\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"genui\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"maintenance-screen\"\n  | \"map\"\n  | \"markdown\"\n  | \"meta-row\"\n  | \"waveform\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-grid\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"rail-nav\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"splash-handoff\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"update-prompt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n *   component that answers there, when one does.\n */\nexport type Absence =\n  | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n  | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n  readonly web?: Absence;\n  readonly native?: Absence;\n  readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: string;\n    });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n  readonly parity: Parity;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     }
   ],
   "dependencies": [
@@ -417,6 +434,13 @@
           "description": "The sidebar starts collapsed to its icons (desktop).",
           "required": false
         },
+        {
+          "name": "desktop",
+          "type": "boolean",
+          "default": "false",
+          "description": "The shell is a desktop app's window (the Orazaka Mac app, Tauri 2 — ADR-002): no drawer, the sidebar's top clears the\nwindow's traffic lights (`--kz-titlebar-inset`, 28 px; the window's height is `--kz-window-height`, the viewport by default), the header and that top move the window\n(`data-tauri-drag-region`), a denser layout, the chrome not selectable. In a browser it is a fixed-height shell.",
+          "required": false
+        },
         {
           "name": "onCollapsedChange",
           "type": "((collapsed: boolean) => void)",