@krizaka/ui 2.8.0 → 2.10.0

package/registry/mascot-quote.json

@@ -8,7 +8,7 @@
   "category": "blocks",
   "platforms": "web",
   "whenToUse": [
-    "To state the rule a feature stands for (the falcon watches, the owl reads, the duck builds, the flamingo answers or gets paid, the pigeon delivers, the lovebird introduces).",
+    "To state the rule a feature stands for (the falcon watches, the owl reads, the duck builds, the flamingo answers or gets paid, the pigeon delivers, the lovebird introduces, the crane listens).",
     "A promise that deserves its own moment in a section (`callout`)."
   ],
   "whenNotToUse": [
@@ -48,7 +48,7 @@
         "props": [
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
             "description": "The bird that speaks — the one whose idea it is.",
             "required": true
@@ -118,15 +118,15 @@
     },
     {
       "path": "mascot-quote/mascot-quote.tsx",
-      "content": "// Client (the bird has an id per instance). A rule, a promise or a decision told by a bird (blocks.css): the sentence in\n// a speech bubble — an opening quote mark, the hue around it — and under its tail the bird and who speaks. One bird per\n// idea (Mascot's rule): the falcon watches, the owl reads, the duck builds, the flamingo answers or gets paid, the\n// pigeon delivers, the lovebird introduces.\nimport type * as React from \"react\";\n\nimport { cn } from \"../cn\";\nimport { type MascotBird, type MascotMood } from \"../mascots/geometry\";\nimport { Mascot } from \"../mascots/mascot\";\n\nexport type MascotQuoteProps = Omit<React.HTMLAttributes<HTMLElement>, \"children\"> & {\n  /** The bird that speaks — the one whose idea it is. */\n  bird: MascotBird;\n  /**\n   * Its mood.\n   * @default \"thinking\"\n   */\n  mood?: MascotMood;\n  /** Who speaks, under the bubble: `The falcon's rule`. */\n  label: React.ReactNode;\n  /** The sentence: the rule, the promise. */\n  children: React.ReactNode;\n  /**\n   * `inline` inside a card (small, the bird answers the pointer); `callout` alone in a section (larger, the bird alive).\n   * @default \"inline\"\n   */\n  variant?: \"inline\" | \"callout\";\n  /** The bird's idle loop (it pauses off screen and stops under reduced motion). Defaults to `true` for a callout. */\n  animated?: boolean;\n};\n\n/** A sentence told by a bird: a speech bubble, the bird under its tail, who speaks. The bird is decorative. */\nexport function MascotQuote({ bird, mood = \"thinking\", label, children, variant = \"inline\", animated, className, ...props }: MascotQuoteProps) {\n  const callout = variant === \"callout\";\n  return (\n    <figure className={cn(\"kz-quote\", className)} data-variant={callout ? \"callout\" : undefined} {...props}>\n      <blockquote>\n        <p>{children}</p>\n      </blockquote>\n      <figcaption>\n        <Mascot bird={bird} mood={mood} size={callout ? 72 : 44} animated={animated ?? callout} className=\"kz-quote-bird\" aria-hidden />\n        <span>{label}</span>\n      </figcaption>\n    </figure>\n  );\n}\n"
+      "content": "// Client (the bird has an id per instance). A rule, a promise or a decision told by a bird (blocks.css): the sentence in\n// a speech bubble — an opening quote mark, the hue around it — and under its tail the bird and who speaks. One bird per\n// idea (Mascot's rule): the falcon watches, the owl reads, the duck builds, the flamingo answers or gets paid, the\n// pigeon delivers, the lovebird introduces, the crane listens.\nimport type * as React from \"react\";\n\nimport { cn } from \"../cn\";\nimport { type MascotBird, type MascotMood } from \"../mascots/geometry\";\nimport { Mascot } from \"../mascots/mascot\";\n\nexport type MascotQuoteProps = Omit<React.HTMLAttributes<HTMLElement>, \"children\"> & {\n  /** The bird that speaks — the one whose idea it is. */\n  bird: MascotBird;\n  /**\n   * Its mood.\n   * @default \"thinking\"\n   */\n  mood?: MascotMood;\n  /** Who speaks, under the bubble: `The falcon's rule`. */\n  label: React.ReactNode;\n  /** The sentence: the rule, the promise. */\n  children: React.ReactNode;\n  /**\n   * `inline` inside a card (small, the bird answers the pointer); `callout` alone in a section (larger, the bird alive).\n   * @default \"inline\"\n   */\n  variant?: \"inline\" | \"callout\";\n  /** The bird's idle loop (it pauses off screen and stops under reduced motion). Defaults to `true` for a callout. */\n  animated?: boolean;\n};\n\n/** A sentence told by a bird: a speech bubble, the bird under its tail, who speaks. The bird is decorative. */\nexport function MascotQuote({ bird, mood = \"thinking\", label, children, variant = \"inline\", animated, className, ...props }: MascotQuoteProps) {\n  const callout = variant === \"callout\";\n  return (\n    <figure className={cn(\"kz-quote\", className)} data-variant={callout ? \"callout\" : undefined} {...props}>\n      <blockquote>\n        <p>{children}</p>\n      </blockquote>\n      <figcaption>\n        <Mascot bird={bird} mood={mood} size={callout ? 72 : 44} animated={animated ?? callout} className=\"kz-quote-bird\" aria-hidden />\n        <span>{label}</span>\n      </figcaption>\n    </figure>\n  );\n}\n"
     },
     {
       "path": "mascot-quote/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Mascot quote\",\n  summary:\n    \"A rule, a promise or a decision told by a bird: the sentence in a speech bubble, the bird under its tail and who speaks — `inline` in a card, `callout` alone in a section.\",\n  status: \"beta\",\n  category: \"blocks\",\n  platforms: \"web\",\n  whenToUse: [\n    \"To state the rule a feature stands for (the falcon watches, the owl reads, the duck builds, the flamingo answers or gets paid, the pigeon delivers, the lovebird introduces).\",\n    \"A promise that deserves its own moment in a section (`callout`).\",\n  ],\n  whenNotToUse: [\n    { when: \"For a bird that only decorates: a bird carries a promise, or it is not there.\", use: \"mascots\" },\n    { when: \"For a status or a warning the reader must act on.\", use: \"alert\" },\n  ],\n  bestPractices: [\n    \"One bird per idea, the same bird for the same idea everywhere.\",\n    \"One sentence, said as a rule: short, in the present tense.\",\n    \"The label says who speaks (`The falcon's rule`): words as props.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"A `figure` with a `blockquote` and its `figcaption`: read as a quote and who says it.\",\n      \"The bird is decorative (`aria-hidden`); its idle loop pauses off screen and stops under `prefers-reduced-motion`.\",\n    ],\n  },\n  related: [\"mascots\", \"argument-card\", \"alert\"],\n  web: {\n    imports: [\"MascotQuote\"],\n    examples: [\n      { name: \"inline\", title: \"Inline\", description: \"The falcon's rule, small, beside a paragraph or inside a card.\" },\n      { name: \"callout\", title: \"Callout\", description: \"The owl's promise, alone in a section, the bird alive.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Mascot quote\",\n  summary:\n    \"A rule, a promise or a decision told by a bird: the sentence in a speech bubble, the bird under its tail and who speaks — `inline` in a card, `callout` alone in a section.\",\n  status: \"beta\",\n  category: \"blocks\",\n  platforms: \"web\",\n  whenToUse: [\n    \"To state the rule a feature stands for (the falcon watches, the owl reads, the duck builds, the flamingo answers or gets paid, the pigeon delivers, the lovebird introduces, the crane listens).\",\n    \"A promise that deserves its own moment in a section (`callout`).\",\n  ],\n  whenNotToUse: [\n    { when: \"For a bird that only decorates: a bird carries a promise, or it is not there.\", use: \"mascots\" },\n    { when: \"For a status or a warning the reader must act on.\", use: \"alert\" },\n  ],\n  bestPractices: [\n    \"One bird per idea, the same bird for the same idea everywhere.\",\n    \"One sentence, said as a rule: short, in the present tense.\",\n    \"The label says who speaks (`The falcon's rule`): words as props.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"A `figure` with a `blockquote` and its `figcaption`: read as a quote and who says it.\",\n      \"The bird is decorative (`aria-hidden`); its idle loop pauses off screen and stops under `prefers-reduced-motion`.\",\n    ],\n  },\n  related: [\"mascots\", \"argument-card\", \"alert\"],\n  web: {\n    imports: [\"MascotQuote\"],\n    examples: [\n      { name: \"inline\", title: \"Inline\", description: \"The falcon's rule, small, beside a paragraph or inside a card.\" },\n      { name: \"callout\", title: \"Callout\", description: \"The owl's promise, alone in a section, the bird alive.\" },\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 krizaka.com renders as\n// /docs/ui/<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  | \"action-bar\"\n  | \"alert\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"link-card\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\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 */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layout\" | \"foundations\";\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 */\nexport interface Example {\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/** 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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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 krizaka.com renders as\n// /docs/ui/<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  | \"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  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\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  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\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/**\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 */\nexport interface Example {\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   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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": [],
@@ -145,7 +145,7 @@
       "props": [
         {
           "name": "bird",
-          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
           "default": null,
           "description": "The bird that speaks — the one whose idea it is.",
           "required": true

package/registry/mascot-state.json

@@ -33,7 +33,7 @@
     }
   ],
   "bestPractices": [
-    "Choose the bird by the job, not by the mood: the owl reads (documents, search), the falcon watches (security, verification), the duck builds (code, uploads), the flamingo answers and gets paid (support, payments), the pigeon delivers (messages, notifications), the lovebird introduces (matches, introductions).",
+    "Choose the bird by the job, not by the mood: the owl reads (documents, search), the falcon watches (security, verification), the duck builds (code, uploads), the flamingo answers and gets paid (support, payments), the pigeon delivers (messages, notifications), the lovebird introduces (matches, introductions), the crane listens (a quiet moment, taking one's time).",
     "One bird per screen: a moment, never decoration in working content.",
     "The title says what happened in a few words, the description what comes next; one action — the way out.",
     "`titleAs=\"h1\"` when the state is the whole page (a 404), so the page keeps a heading."
@@ -83,9 +83,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
             "required": false
           },
           {
@@ -159,9 +159,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
             "required": false
           },
           {
@@ -235,9 +235,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": "owl",
-            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
             "required": false
           },
           {
@@ -318,9 +318,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
             "required": false
           },
           {
@@ -394,9 +394,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
             "required": false
           },
           {
@@ -523,9 +523,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": "owl",
-            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions), `crane` (listening).",
             "required": false
           },
           {
@@ -592,9 +592,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions), `crane` (listening).",
             "required": false
           },
           {
@@ -654,9 +654,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions), `crane` (listening).",
             "required": false
           },
           {
@@ -716,9 +716,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions), `crane` (listening).",
             "required": false
           },
           {
@@ -778,9 +778,9 @@
           },
           {
             "name": "bird",
-            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
             "default": null,
-            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions), `crane` (listening).",
             "required": false
           },
           {
@@ -836,15 +836,15 @@
     },
     {
       "path": "mascot-state/mascot-state.tsx",
-      "content": "// The moments a product speaks to a person — nothing yet, a long wait, done, it failed, welcome — told by a bird of\n// the flock beside the words. Every word is a prop; the bird never carries the message alone.\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport type { MascotBird, MascotMood, MascotTone } from \"../mascots/geometry\";\nimport { Mascot } from \"../mascots/mascot\";\n\n// Staged: the bird arrives, then the words, then the action — once, and not at all under reduced motion.\nconst CSS = `\n@keyframes kzms-in { from { opacity: 0; transform: translateY(6px); } }\n@media (prefers-reduced-motion: no-preference) {\n  [data-kzms-staged] > [data-kzms-part] { animation: kzms-in .42s cubic-bezier(.2,.8,.2,1) both; }\n  [data-kzms-staged] > [data-kzms-part=\"words\"] { animation-delay: .12s; }\n  [data-kzms-staged] > [data-kzms-part=\"action\"] { animation-delay: .24s; }\n}\n`;\n\nexport const mascotState = tv({\n  slots: {\n    root: \"flex items-center gap-4 text-fg\",\n    bird: \"shrink-0\",\n    words: \"flex flex-col gap-1.5\",\n    title: \"text-base font-semibold text-fg\",\n    description: \"max-w-sm text-sm text-fg-secondary\",\n    action: \"flex flex-wrap items-center gap-2\",\n  },\n  variants: {\n    layout: {\n      stacked: { root: \"flex-col justify-center px-6 py-10 text-center\", words: \"items-center\", action: \"justify-center\" },\n      inline: { root: \"flex-row text-left\", action: \"mt-1\" },\n    },\n    framed: { true: { root: \"rounded-xl border border-dashed border-border-default bg-surface-1\" }, false: {} },\n  },\n  compoundVariants: [{ layout: \"inline\", framed: true, class: { root: \"p-4\" } }],\n  defaultVariants: { layout: \"stacked\", framed: false },\n});\n\nconst SIZE = { sm: 64, md: 96, lg: 128 } as const;\n\nexport type MascotStateProps = Omit<React.ComponentProps<\"div\">, \"title\"> & {\n  /**\n   * The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n   * (code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.\n   */\n  bird?: MascotBird;\n  /** The moment: `empty` (nothing yet), `thinking` (a long task runs), `success` (done), `error` (it failed), `welcome`. */\n  mood?: MascotMood;\n  /** What happened, in a few words (\"No videos yet\", \"Payment received\"). */\n  title: React.ReactNode;\n  /** Why, or what comes next. */\n  description?: React.ReactNode;\n  /** What to do next: a Button, a link. One, at most two. */\n  action?: React.ReactNode;\n  /** The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px. */\n  size?: keyof typeof SIZE;\n  /** `stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form. */\n  layout?: \"stacked\" | \"inline\";\n  /** A dashed frame on the raised surface, for an empty list or panel. */\n  framed?: boolean;\n  /** `brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story. */\n  tone?: MascotTone;\n  /** The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`. */\n  animated?: boolean;\n  /** The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page. */\n  titleAs?: \"p\" | \"h1\" | \"h2\" | \"h3\";\n};\n\n/**\n * A moment told by a bird of the flock: an empty list, a long wait, a success, an error, a welcome. Announced to\n * assistive technology — `role=\"alert\"` for an error, `role=\"status\"` otherwise (`aria-busy` while thinking).\n */\nexport function MascotState({\n  bird = \"owl\",\n  mood = \"empty\",\n  title,\n  description,\n  action,\n  size = \"md\",\n  layout,\n  framed,\n  tone,\n  animated = true,\n  titleAs: Title = \"p\",\n  className,\n  ...props\n}: MascotStateProps) {\n  const s = mascotState({ layout, framed });\n  return (\n    <div\n      role={mood === \"error\" ? \"alert\" : \"status\"}\n      aria-busy={mood === \"thinking\" ? true : undefined}\n      data-mood={mood}\n      data-kzms-staged={animated ? \"\" : undefined}\n      className={s.root({ className })}\n      {...props}\n    >\n      {animated && <style>{CSS}</style>}\n      <span data-kzms-part=\"bird\" className={s.bird()}>\n        <Mascot bird={bird} mood={mood} tone={tone} size={SIZE[size]} animated={animated} />\n      </span>\n      <div data-kzms-part=\"words\" className={s.words()}>\n        <Title className={s.title()}>{title}</Title>\n        {description && <p className={s.description()}>{description}</p>}\n        {layout === \"inline\" && action && <div className={s.action()}>{action}</div>}\n      </div>\n      {layout !== \"inline\" && action && (\n        <div data-kzms-part=\"action\" className={s.action()}>\n          {action}\n        </div>\n      )}\n    </div>\n  );\n}\n\ntype PresetProps = Omit<MascotStateProps, \"mood\">;\n\n/** It failed: what went wrong and what to do (`role=\"alert\"`). `MascotState` with `mood=\"error\"`. */\nexport function ErrorState(props: PresetProps) {\n  return <MascotState mood=\"error\" {...props} />;\n}\n\n/** It is done: a payment, a verification, a delivery, a sent message. `MascotState` with `mood=\"success\"`. */\nexport function SuccessState(props: PresetProps) {\n  return <MascotState mood=\"success\" {...props} />;\n}\n\n/** A long task runs (`aria-busy`): what runs, beside the bird. `MascotState` with `mood=\"thinking\"`. */\nexport function LoadingState(props: PresetProps) {\n  return <MascotState mood=\"thinking\" {...props} />;\n}\n\n/** A first screen, an onboarding step. `MascotState` with `mood=\"welcome\"`. */\nexport function WelcomeState(props: PresetProps) {\n  return <MascotState mood=\"welcome\" {...props} />;\n}\n"
+      "content": "// The moments a product speaks to a person — nothing yet, a long wait, done, it failed, welcome — told by a bird of\n// the flock beside the words. Every word is a prop; the bird never carries the message alone.\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport type { MascotBird, MascotMood, MascotTone } from \"../mascots/geometry\";\nimport { Mascot } from \"../mascots/mascot\";\n\n// Staged: the bird arrives, then the words, then the action — once, and not at all under reduced motion.\nconst CSS = `\n@keyframes kzms-in { from { opacity: 0; transform: translateY(6px); } }\n@media (prefers-reduced-motion: no-preference) {\n  [data-kzms-staged] > [data-kzms-part] { animation: kzms-in .42s cubic-bezier(.2,.8,.2,1) both; }\n  [data-kzms-staged] > [data-kzms-part=\"words\"] { animation-delay: .12s; }\n  [data-kzms-staged] > [data-kzms-part=\"action\"] { animation-delay: .24s; }\n}\n`;\n\nexport const mascotState = tv({\n  slots: {\n    root: \"flex items-center gap-4 text-fg\",\n    bird: \"shrink-0\",\n    words: \"flex flex-col gap-1.5\",\n    title: \"text-base font-semibold text-fg\",\n    description: \"max-w-sm text-sm text-fg-secondary\",\n    action: \"flex flex-wrap items-center gap-2\",\n  },\n  variants: {\n    layout: {\n      stacked: { root: \"flex-col justify-center px-6 py-10 text-center\", words: \"items-center\", action: \"justify-center\" },\n      inline: { root: \"flex-row text-left\", action: \"mt-1\" },\n    },\n    framed: { true: { root: \"rounded-xl border border-dashed border-border-default bg-surface-1\" }, false: {} },\n  },\n  compoundVariants: [{ layout: \"inline\", framed: true, class: { root: \"p-4\" } }],\n  defaultVariants: { layout: \"stacked\", framed: false },\n});\n\nconst SIZE = { sm: 64, md: 96, lg: 128 } as const;\n\nexport type MascotStateProps = Omit<React.ComponentProps<\"div\">, \"title\"> & {\n  /**\n   * The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n   * (code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.\n   */\n  bird?: MascotBird;\n  /** The moment: `empty` (nothing yet), `thinking` (a long task runs), `success` (done), `error` (it failed), `welcome`. */\n  mood?: MascotMood;\n  /** What happened, in a few words (\"No videos yet\", \"Payment received\"). */\n  title: React.ReactNode;\n  /** Why, or what comes next. */\n  description?: React.ReactNode;\n  /** What to do next: a Button, a link. One, at most two. */\n  action?: React.ReactNode;\n  /** The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px. */\n  size?: keyof typeof SIZE;\n  /** `stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form. */\n  layout?: \"stacked\" | \"inline\";\n  /** A dashed frame on the raised surface, for an empty list or panel. */\n  framed?: boolean;\n  /** `brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story. */\n  tone?: MascotTone;\n  /** The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`. */\n  animated?: boolean;\n  /** The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page. */\n  titleAs?: \"p\" | \"h1\" | \"h2\" | \"h3\";\n};\n\n/**\n * A moment told by a bird of the flock: an empty list, a long wait, a success, an error, a welcome. Announced to\n * assistive technology — `role=\"alert\"` for an error, `role=\"status\"` otherwise (`aria-busy` while thinking).\n */\nexport function MascotState({\n  bird = \"owl\",\n  mood = \"empty\",\n  title,\n  description,\n  action,\n  size = \"md\",\n  layout,\n  framed,\n  tone,\n  animated = true,\n  titleAs: Title = \"p\",\n  className,\n  ...props\n}: MascotStateProps) {\n  const s = mascotState({ layout, framed });\n  return (\n    <div\n      role={mood === \"error\" ? \"alert\" : \"status\"}\n      aria-busy={mood === \"thinking\" ? true : undefined}\n      data-mood={mood}\n      data-kzms-staged={animated ? \"\" : undefined}\n      className={s.root({ className })}\n      {...props}\n    >\n      {animated && <style>{CSS}</style>}\n      <span data-kzms-part=\"bird\" className={s.bird()}>\n        <Mascot bird={bird} mood={mood} tone={tone} size={SIZE[size]} animated={animated} />\n      </span>\n      <div data-kzms-part=\"words\" className={s.words()}>\n        <Title className={s.title()}>{title}</Title>\n        {description && <p className={s.description()}>{description}</p>}\n        {layout === \"inline\" && action && <div className={s.action()}>{action}</div>}\n      </div>\n      {layout !== \"inline\" && action && (\n        <div data-kzms-part=\"action\" className={s.action()}>\n          {action}\n        </div>\n      )}\n    </div>\n  );\n}\n\ntype PresetProps = Omit<MascotStateProps, \"mood\">;\n\n/** It failed: what went wrong and what to do (`role=\"alert\"`). `MascotState` with `mood=\"error\"`. */\nexport function ErrorState(props: PresetProps) {\n  return <MascotState mood=\"error\" {...props} />;\n}\n\n/** It is done: a payment, a verification, a delivery, a sent message. `MascotState` with `mood=\"success\"`. */\nexport function SuccessState(props: PresetProps) {\n  return <MascotState mood=\"success\" {...props} />;\n}\n\n/** A long task runs (`aria-busy`): what runs, beside the bird. `MascotState` with `mood=\"thinking\"`. */\nexport function LoadingState(props: PresetProps) {\n  return <MascotState mood=\"thinking\" {...props} />;\n}\n\n/** A first screen, an onboarding step. `MascotState` with `mood=\"welcome\"`. */\nexport function WelcomeState(props: PresetProps) {\n  return <MascotState mood=\"welcome\" {...props} />;\n}\n"
     },
     {
       "path": "mascot-state/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Mascot state\",\n  summary:\n    \"A moment told by a bird of the flock: nothing yet, a long wait, done, it failed, welcome — the bird of the job beside the words and the next action.\",\n  status: \"beta\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\n    \"An empty list or search the person reaches for the first time (`mood=\\\"empty\\\"`, `framed`).\",\n    \"A page or a panel that failed: a 404, a lost connection, a refused payment (`ErrorState`).\",\n    \"The end of something that matters: a payment received, an identity verified, a message sent (`SuccessState`).\",\n    \"A task of several seconds or more, with what runs in words (`LoadingState`).\",\n    \"The first screen of an onboarding (`WelcomeState`).\",\n  ],\n  whenNotToUse: [\n    { when: \"A short wait of a second or two, or a list that is loading.\", use: \"skeleton\" },\n    { when: \"An error inside a form or a card, next to what it concerns.\", use: \"alert\" },\n    { when: \"A result that needs no moment: a saved setting, a copied link.\", use: \"toast\" },\n    { when: \"A plain empty list in a dense screen (a table, a sidebar).\", use: \"empty-state\" },\n  ],\n  bestPractices: [\n    \"Choose the bird by the job, not by the mood: the owl reads (documents, search), the falcon watches (security, verification), the duck builds (code, uploads), the flamingo answers and gets paid (support, payments), the pigeon delivers (messages, notifications), the lovebird introduces (matches, introductions).\",\n    \"One bird per screen: a moment, never decoration in working content.\",\n    \"The title says what happened in a few words, the description what comes next; one action — the way out.\",\n    \"`titleAs=\\\"h1\\\"` when the state is the whole page (a 404), so the page keeps a heading.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"`role=\\\"alert\\\"` for an error, `role=\\\"status\\\"` otherwise: announced when it appears; `aria-busy` while thinking.\",\n      \"The bird is decorative: the title and the description carry the meaning.\",\n      \"The staged arrival (bird, words, action) and the bird's gesture stop under `prefers-reduced-motion` and with `animated={false}`.\",\n    ],\n  },\n  related: [\"mascots\", \"empty-state\", \"alert\", \"progress\"],\n  web: {\n    imports: [\"MascotState\", \"ErrorState\", \"SuccessState\", \"LoadingState\", \"WelcomeState\"],\n    examples: [\n      { name: \"empty\", title: \"Nothing yet\", description: \"A framed empty list: the pigeon has no message to deliver yet.\" },\n      { name: \"error\", title: \"It failed\", description: \"A page that does not exist: the owl did not find it, with the way back.\" },\n      { name: \"success\", title: \"Done\", description: \"A payment received: the flamingo answers, the next step beside it.\" },\n      { name: \"loading\", title: \"A long task\", description: \"The duck builds while the job runs, in a card (`layout=\\\"inline\\\"`).\" },\n      { name: \"welcome\", title: \"Welcome\", description: \"An onboarding's first screen: the falcon keeps the account safe.\" },\n    ],\n  },\n  native: {\n    imports: [\"MascotState\", \"ErrorState\", \"SuccessState\", \"LoadingState\", \"WelcomeState\"],\n    differences: [\"`title` and `description` are strings; the action is a native `Button`.\", \"No `framed` and no `titleAs`: style with `style`.\", \"Only the idle bob and a fade-in: the web gestures (wave, dots, hop) stay on the web.\"],\n    examples: [{ name: \"default\", title: \"Default\", description: \"A payment received (flamingo) and a verification that failed (falcon).\" }],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Mascot state\",\n  summary:\n    \"A moment told by a bird of the flock: nothing yet, a long wait, done, it failed, welcome — the bird of the job beside the words and the next action.\",\n  status: \"beta\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\n    \"An empty list or search the person reaches for the first time (`mood=\\\"empty\\\"`, `framed`).\",\n    \"A page or a panel that failed: a 404, a lost connection, a refused payment (`ErrorState`).\",\n    \"The end of something that matters: a payment received, an identity verified, a message sent (`SuccessState`).\",\n    \"A task of several seconds or more, with what runs in words (`LoadingState`).\",\n    \"The first screen of an onboarding (`WelcomeState`).\",\n  ],\n  whenNotToUse: [\n    { when: \"A short wait of a second or two, or a list that is loading.\", use: \"skeleton\" },\n    { when: \"An error inside a form or a card, next to what it concerns.\", use: \"alert\" },\n    { when: \"A result that needs no moment: a saved setting, a copied link.\", use: \"toast\" },\n    { when: \"A plain empty list in a dense screen (a table, a sidebar).\", use: \"empty-state\" },\n  ],\n  bestPractices: [\n    \"Choose the bird by the job, not by the mood: the owl reads (documents, search), the falcon watches (security, verification), the duck builds (code, uploads), the flamingo answers and gets paid (support, payments), the pigeon delivers (messages, notifications), the lovebird introduces (matches, introductions), the crane listens (a quiet moment, taking one's time).\",\n    \"One bird per screen: a moment, never decoration in working content.\",\n    \"The title says what happened in a few words, the description what comes next; one action — the way out.\",\n    \"`titleAs=\\\"h1\\\"` when the state is the whole page (a 404), so the page keeps a heading.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"`role=\\\"alert\\\"` for an error, `role=\\\"status\\\"` otherwise: announced when it appears; `aria-busy` while thinking.\",\n      \"The bird is decorative: the title and the description carry the meaning.\",\n      \"The staged arrival (bird, words, action) and the bird's gesture stop under `prefers-reduced-motion` and with `animated={false}`.\",\n    ],\n  },\n  related: [\"mascots\", \"empty-state\", \"alert\", \"progress\"],\n  web: {\n    imports: [\"MascotState\", \"ErrorState\", \"SuccessState\", \"LoadingState\", \"WelcomeState\"],\n    examples: [\n      { name: \"empty\", title: \"Nothing yet\", description: \"A framed empty list: the pigeon has no message to deliver yet.\" },\n      { name: \"error\", title: \"It failed\", description: \"A page that does not exist: the owl did not find it, with the way back.\" },\n      { name: \"success\", title: \"Done\", description: \"A payment received: the flamingo answers, the next step beside it.\" },\n      { name: \"loading\", title: \"A long task\", description: \"The duck builds while the job runs, in a card (`layout=\\\"inline\\\"`).\" },\n      { name: \"welcome\", title: \"Welcome\", description: \"An onboarding's first screen: the falcon keeps the account safe.\" },\n    ],\n  },\n  native: {\n    imports: [\"MascotState\", \"ErrorState\", \"SuccessState\", \"LoadingState\", \"WelcomeState\"],\n    differences: [\"`title` and `description` are strings; the action is a native `Button`.\", \"No `framed` and no `titleAs`: style with `style`.\", \"Only the idle bob and a fade-in: the web gestures (wave, dots, hop) stay on the web.\"],\n    examples: [{ name: \"default\", title: \"Default\", description: \"A payment received (flamingo) and a verification that failed (falcon).\" }],\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 krizaka.com renders as\n// /docs/ui/<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  | \"action-bar\"\n  | \"alert\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"link-card\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\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 */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layout\" | \"foundations\";\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 */\nexport interface Example {\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/** 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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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 krizaka.com renders as\n// /docs/ui/<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  | \"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  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\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  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"gallery-page\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"radio-group\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\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/**\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 */\nexport interface Example {\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   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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": [
@@ -885,9 +885,9 @@
         },
         {
           "name": "bird",
-          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
           "default": null,
-          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
           "required": false
         },
         {
@@ -961,9 +961,9 @@
         },
         {
           "name": "bird",
-          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
           "default": null,
-          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
           "required": false
         },
         {
@@ -1037,9 +1037,9 @@
         },
         {
           "name": "bird",
-          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
           "default": "owl",
-          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
           "required": false
         },
         {
@@ -1120,9 +1120,9 @@
         },
         {
           "name": "bird",
-          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
           "default": null,
-          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
           "required": false
         },
         {
@@ -1196,9 +1196,9 @@
         },
         {
           "name": "bird",
-          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\" | \"crane\"",
           "default": null,
-          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions), `crane` (listening). One bird per idea.",
           "required": false
         },
         {