@krizaka/ui 3.41.1 → 3.43.0

package/registry/flock.json

@@ -2,8 +2,8 @@
   "name": "flock",
   "type": "primitive",
   "title": "Flock",
-  "summary": "The Krizaka birds standing on a stage, alive: each at ease in character, two neighbours glancing at each other, the pigeon carrying its parcel across, a bird looking up when you come near or tap it.",
-  "description": "The Krizaka birds standing on a stage, alive: each at ease in character, two neighbours glancing at each other, the pigeon carrying its parcel across, a bird looking up when you come near or tap it.",
+  "summary": "The Krizaka birds standing on a stage, alive: each at ease in character, two neighbours glancing at each other, the pigeon carrying its parcel across, a bird looking up when you come near or tap it — and, with `scenes`, a short scene for each bird.",
+  "description": "The Krizaka birds standing on a stage, alive: each at ease in character, two neighbours glancing at each other, the pigeon carrying its parcel across, a bird looking up when you come near or tap it — and, with `scenes`, a short scene for each bird.",
   "status": "beta",
   "deprecated": null,
   "category": "blocks",
@@ -44,13 +44,15 @@
     "Give the stage the ratio of its backdrop (`ratio`) and the birds' places in percent: they keep their positions at any width.",
     "Keep each bird to its job: the falcon watches, the owl reads, the duck builds, the flamingo answers, the pigeon delivers.",
     "Make it the page's own: `active` is the bird of the product the reader is on (it looks up and jumps), `greet` has every bird jump once as the flock comes into view, `tempo` makes the moments more frequent.",
+    "`scenes` gives each bird a short scene true to its promise (the owl reads a book, the flamingo and the lovebird talk, the crane bows, the beaver taps a log, the magpie takes a shiny point, the duck builds, the falcon scans) and has the pigeon hand its parcel over, which the receiver opens in its own way. One at a time, at random, with long pauses now and then: leave `tempo` near 1 to 1.7.",
     "Turn a moment off with `glance={false}`, `courier={false}` or `react={false}` on a page that already moves."
   ],
   "accessibility": {
     "keyboard": [],
     "notes": [
       "Decorative (`aria-hidden`): it never carries information; put the words beside it.",
-      "Under `prefers-reduced-motion` the birds are still: no idle motion, no glance, no delivery, no reaction.",
+      "Under `prefers-reduced-motion` the birds are still: no idle motion, no glance, no delivery, no scene, no reaction.",
+      "It waits for the page to settle (`html[data-motion=\"settling\"]`) and pauses off screen (the stage is a `data-motion-scope`).",
       "The moments pause while the flock is off screen and while the tab is hidden; there is no frame loop."
     ]
   },
@@ -124,6 +126,13 @@
             "description": "A bird looks up when the pointer comes near, and jumps a little when tapped. Default `true`.",
             "required": false
           },
+          {
+            "name": "scenes",
+            "type": "boolean",
+            "default": "false",
+            "description": "Scenes, true to each bird's promise: the owl reads a book, the flamingo and the lovebird talk with a speech mark, the\ncrane steps and bows, the beaver taps a log, the magpie takes a shiny point, the duck builds, the falcon scans — and the\npigeon hands its parcel over, which the receiver opens in its own way. One at a time, at random. Default `false`.",
+            "required": false
+          },
           {
             "name": "tempo",
             "type": "number",
@@ -150,6 +159,14 @@
         "module": "@krizaka/ui/registry/examples/flock/ridge",
         "code": "import { Flock } from \"@krizaka/ui/flock\";\n\n// The five of the story on a ridge: the falcon watches, the owl reads, the duck builds, the flamingo answers and the\n// pigeon delivers. Places are percents of the stage, so they hold at any width.\nexport default function FlockRidge() {\n  return (\n    <Flock\n      className=\"max-w-3xl\"\n      ratio={16 / 6}\n      birds={[\n        { bird: \"falcon\", x: 20, y: 96, size: 13 },\n        { bird: \"owl\", x: 35, y: 96, size: 13 },\n        { bird: \"duck\", x: 50, y: 96, size: 13 },\n        { bird: \"flamingo\", x: 65, y: 96, size: 13 },\n        { bird: \"pigeon\", x: 80, y: 96, size: 13 },\n      ]}\n    />\n  );\n}\n"
       },
+      {
+        "name": "scenes",
+        "title": "The scenes",
+        "description": "The owl reads, the flamingo and the lovebird talk, the crane bows, the beaver taps a log, the magpie takes a shiny point, and the pigeon hands its parcel over.",
+        "path": "examples/flock/scenes.tsx",
+        "module": "@krizaka/ui/registry/examples/flock/scenes",
+        "code": "import { Flock } from \"@krizaka/ui/flock\";\n\n// The scenes: each bird does what it promises, one thing at a time and never twice the same. The owl reads a book, the\n// flamingo speaks and its neighbour answers, the crane steps out and bows, the beaver taps a log, the magpie takes a\n// shiny point — and the pigeon hands its parcel over, which the receiver opens in its own way.\nexport default function FlockScenes() {\n  return (\n    <Flock\n      className=\"max-w-4xl\"\n      ratio={16 / 5}\n      scenes\n      tempo={1.4}\n      birds={[\n        { bird: \"pigeon\", x: 10, y: 96, size: 11 },\n        { bird: \"owl\", x: 24, y: 96, size: 11 },\n        { bird: \"lovebird\", x: 38, y: 96, size: 11 },\n        { bird: \"flamingo\", x: 52, y: 96, size: 13 },\n        { bird: \"crane\", x: 66, y: 96, size: 11 },\n        { bird: \"magpie\", x: 79, y: 96, size: 11 },\n        { bird: \"beaver\", x: 92, y: 96, size: 11 },\n      ]}\n    />\n  );\n}\n"
+      },
       {
         "name": "pair",
         "title": "Two birds",
@@ -164,7 +181,7 @@
   "files": [
     {
       "path": "flock/flock.tsx",
-      "content": "\"use client\";\n\n// The flock, alive: birds standing on a stage, each at ease in character (Mascot `life`), and the moments between\n// them — two birds glance at each other, the pigeon carries its parcel across, a bird looks up when you come near or tap\n// it. Transform and opacity only: CSS for each bird's own life, a timer for the moments (no frame loop), and nothing at\n// all when the flock is off screen, the tab is hidden or the person asked for less motion.\nimport * as React from \"react\";\n\nimport { cn } from \"../cn\";\nimport type { MascotBird, MascotLook } from \"../mascots\";\nimport { Mascot } from \"../mascots\";\n\nexport interface FlockBird {\n  /** Which bird. */\n  bird: MascotBird;\n  /** Where its feet are, across the stage: 0 to 100 (% of the stage's width). */\n  x: number;\n  /** Where its feet are, down the stage: 0 to 100 (% of the stage's height). */\n  y: number;\n  /** How wide it is: % of the stage's width. */\n  size: number;\n}\n\nexport interface FlockMoments {\n  /** Two neighbours look at each other now and then. Default `true`. */\n  glance?: boolean;\n  /** The pigeon, when the flock has one, carries its parcel across to another bird and comes back. Default `true`. */\n  courier?: boolean;\n  /** A bird looks up when the pointer comes near, and jumps a little when tapped. Default `true`. */\n  react?: boolean;\n}\n\nexport type FlockProps = Omit<React.ComponentProps<\"div\">, \"children\"> &\n  FlockMoments & {\n    /** The birds on the stage. */\n    birds: readonly FlockBird[];\n    /** The stage's shape, width over height (default 16 / 9). It keeps its ratio at any width, so the birds keep their places. */\n    ratio?: number;\n    /** The birds' colours: the host's accent (`brand`, default) or the Krizaka story's (`own`). */\n    tone?: \"brand\" | \"own\";\n    /** The source of chance (default `Math.random`): give it a fixed one in a test. */\n    random?: () => number;\n    /** How lively the moments are: 1 is calm (default), 2 doubles how often neighbours glance and the pigeon delivers. */\n    tempo?: number;\n    /** A bird the page points at (a product the reader is on): it looks up and jumps once each time it changes. */\n    active?: MascotBird | null;\n    /** The birds greet the reader once as the flock first comes into view: each jumps in turn, left to right. */\n    greet?: boolean;\n  };\n\n// @fixed: the rhythm of the moments — how long a glance lasts, how often one happens, how long a delivery takes. A\n// choreography's pace, not a business parameter.\nconst GLANCE_HOLD_MS = [1500, 2400] as const;\nconst GLANCE_EVERY_MS = [4200, 9000] as const;\nconst COURIER_FIRST_MS = 9000;\nconst COURIER_EVERY_MS = [26000, 38000] as const;\nconst FLIGHT_MS = 2600;\nconst HAND_OVER_MS = 1300;\nconst LOOK_BACK_MS = 1600;\n\nconst between = (random: () => number, [lo, hi]: readonly [number, number], tempo = 1) => (lo + random() * (hi - lo)) / tempo;\nconst GREET_STEP_MS = 110;\nconst POKE_MS = 700;\n\n/** `true` while the page may move: no reduced-motion request, the tab visible. */\nfunction useMayMove(): boolean {\n  const [may, setMay] = React.useState(false);\n  React.useEffect(() => {\n    const query = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n    const update = () => setMay(!query.matches && document.visibilityState !== \"hidden\");\n    update();\n    query.addEventListener(\"change\", update);\n    document.addEventListener(\"visibilitychange\", update);\n    return () => {\n      query.removeEventListener(\"change\", update);\n      document.removeEventListener(\"visibilitychange\", update);\n    };\n  }, []);\n  return may;\n}\n\n/** `true` while the element is on screen. */\nfunction useOnScreen(ref: React.RefObject<Element | null>): boolean {\n  const [on, setOn] = React.useState(false);\n  React.useEffect(() => {\n    const el = ref.current;\n    if (!el || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(([entry]) => setOn(Boolean(entry?.isIntersecting)), { threshold: 0.1 });\n    observer.observe(el);\n    return () => observer.disconnect();\n  }, [ref]);\n  return on;\n}\n\n/**\n * The flock on its stage, alive. Decorative (`aria-hidden`): put the words beside it. Each bird idles in character; every\n * few seconds two neighbours glance at each other; every half minute the pigeon carries its parcel to another bird and\n * returns; a bird looks up when you come near. All of it pauses off screen and in a hidden tab, and the flock is still\n * under `prefers-reduced-motion`.\n */\nexport function Flock({ birds, ratio = 16 / 9, tone = \"brand\", glance = true, courier = true, react = true, random = Math.random, tempo = 1, active = null, greet = false, className, style, ...props }: FlockProps) {\n  const stage = React.useRef<HTMLDivElement>(null);\n  const bodies = React.useRef<(HTMLDivElement | null)[]>([]);\n  const may = useMayMove();\n  const onScreen = useOnScreen(stage);\n  const running = may && onScreen;\n  const [looks, setLooks] = React.useState<Record<number, MascotLook>>({});\n  const [flying, setFlying] = React.useState<{ index: number; bank: number } | null>(null);\n  const [poked, setPoked] = React.useState<Record<number, boolean>>({});\n\n  // Left to right: a bird's neighbours are the birds beside it on the stage.\n  const order = React.useMemo(() => birds.map((_, i) => i).sort((a, b) => birds[a]!.x - birds[b]!.x), [birds]);\n  const look = (index: number, to: MascotLook) => setLooks((l) => (l[index] === to ? l : { ...l, [index]: to }));\n  const rest = (...indexes: number[]) => setLooks((l) => Object.fromEntries(Object.entries(l).filter(([k]) => !indexes.includes(Number(k)))));\n\n  // Glances: two neighbours turn towards each other, hold, and look away.\n  React.useEffect(() => {\n    if (!running || !glance || order.length < 2) return;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let back: ReturnType<typeof setTimeout> | undefined;\n    const next = () => {\n      timer = setTimeout(() => {\n        const at = Math.floor(random() * (order.length - 1));\n        const [a, b] = [order[at]!, order[at + 1]!];\n        look(a, \"right\");\n        look(b, \"left\");\n        back = setTimeout(() => {\n          rest(a, b);\n          next();\n        }, between(random, GLANCE_HOLD_MS));\n      }, between(random, GLANCE_EVERY_MS, tempo));\n    };\n    next();\n    return () => {\n      clearTimeout(timer);\n      clearTimeout(back);\n    };\n  }, [running, glance, order, random, tempo]);\n\n  // The delivery: the pigeon takes its parcel across to the farthest bird, hands it over, and flies back.\n  React.useEffect(() => {\n    const pigeon = birds.findIndex((b) => b.bird === \"pigeon\");\n    if (!running || !courier || pigeon < 0 || birds.length < 2) return;\n    let alive = true;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let animation: Animation | undefined;\n    const wait = (ms: number) => new Promise<void>((resolve) => (timer = setTimeout(resolve, ms)));\n    const trip = async () => {\n      const el = bodies.current[pigeon];\n      const box = stage.current?.getBoundingClientRect();\n      if (!el || !box || typeof el.animate !== \"function\") return;\n      // The farthest bird from the pigeon, so the parcel crosses the whole stage.\n      const from = birds[pigeon]!;\n      const target = birds.reduce((far, b, i) => (i !== pigeon && Math.abs(b.x - from.x) > Math.abs(birds[far]!.x - from.x) ? i : far), pigeon === 0 ? 1 : 0);\n      const to = birds[target]!;\n      const side = to.x > from.x ? 1 : -1;\n      // It lands beside the receiver, not on it.\n      const dx = ((to.x - from.x) / 100) * box.width - side * (to.size / 100) * box.width * 0.55;\n      const lift = (from.size / 100) * box.width * 0.35;\n      const fly = async (fromX: number, toX: number) => {\n        setFlying({ index: pigeon, bank: Math.sign(toX - fromX) });\n        animation = el.animate(\n          [\n            { transform: `translate(${fromX}px, 0)`, easing: \"ease-out\" },\n            { transform: `translate(${(fromX + toX) / 2}px, ${-lift}px)`, easing: \"ease-in\", offset: 0.5 },\n            { transform: `translate(${toX}px, 0)` },\n          ],\n          { duration: FLIGHT_MS, fill: \"forwards\" },\n        );\n        await animation.finished.catch(() => undefined);\n        setFlying(null);\n      };\n      look(target, side > 0 ? \"left\" : \"right\");\n      await fly(0, dx);\n      if (!alive) return;\n      // The hand-over: the receiver looks at the pigeon, the pigeon hops on the doorstep.\n      setPoked((p) => ({ ...p, [pigeon]: true }));\n      await wait(HAND_OVER_MS);\n      if (!alive) return;\n      setPoked((p) => ({ ...p, [pigeon]: false }));\n      look(target, \"up\");\n      await fly(dx, 0);\n      animation?.cancel();\n      rest(target);\n    };\n    const schedule = (ms: number) => {\n      timer = setTimeout(async () => {\n        await trip();\n        if (alive) schedule(between(random, COURIER_EVERY_MS, tempo));\n      }, ms);\n    };\n    schedule(COURIER_FIRST_MS / tempo);\n    return () => {\n      alive = false;\n      clearTimeout(timer);\n      animation?.cancel();\n      setFlying(null);\n    };\n  }, [running, courier, birds, random, tempo]);\n\n  // The greeting: the first time the flock is on screen, each bird jumps in turn.\n  const greeted = React.useRef(false);\n  React.useEffect(() => {\n    if (!running || !greet || greeted.current) return;\n    greeted.current = true;\n    const timers: ReturnType<typeof setTimeout>[] = [];\n    order.forEach((index, n) => {\n      timers.push(setTimeout(() => setPoked((p) => ({ ...p, [index]: true })), n * GREET_STEP_MS));\n      timers.push(setTimeout(() => setPoked((p) => ({ ...p, [index]: false })), n * GREET_STEP_MS + POKE_MS));\n    });\n    return () => timers.forEach(clearTimeout);\n  }, [running, greet, order]);\n\n  // The bird the page points at looks up and jumps.\n  React.useEffect(() => {\n    const index = active ? birds.findIndex((b) => b.bird === active) : -1;\n    if (!running || index < 0) return;\n    const start = setTimeout(() => {\n      look(index, \"up\");\n      setPoked((p) => ({ ...p, [index]: true }));\n    }, 0);\n    const t = setTimeout(() => setPoked((p) => ({ ...p, [index]: false })), POKE_MS);\n    return () => {\n      clearTimeout(start);\n      clearTimeout(t);\n      setPoked((p) => ({ ...p, [index]: false }));\n      rest(index);\n    };\n  }, [active, running, birds]);\n\n  // A bird looks up when you come near, and jumps when you tap it.\n  const hover = (index: number, event: React.PointerEvent) => {\n    if (!running || !react || event.pointerType !== \"mouse\") return;\n    look(index, \"up\");\n  };\n  const leave = (index: number) => {\n    if (!react) return;\n    rest(index);\n  };\n  const tap = (index: number) => {\n    if (!running || !react) return;\n    look(index, \"up\");\n    setPoked((p) => ({ ...p, [index]: true }));\n    setTimeout(() => {\n      setPoked((p) => ({ ...p, [index]: false }));\n      rest(index);\n    }, LOOK_BACK_MS);\n  };\n\n  return (\n    <div\n      ref={stage}\n      aria-hidden\n      data-flock=\"\"\n      data-running={running ? \"\" : undefined}\n      className={cn(\"relative w-full\", className)}\n      style={{ aspectRatio: String(ratio), containerType: \"inline-size\", ...style }}\n      {...props}\n    >\n      {birds.map((b, i) => (\n        <div\n          key={`${b.bird}-${i}`}\n          ref={(el) => {\n            bodies.current[i] = el;\n          }}\n          data-flock-bird={b.bird}\n          className=\"absolute touch-manipulation\"\n          style={{ left: `${b.x - b.size / 2}%`, width: `${b.size}%`, top: `calc(${b.y}% - ${b.size * 0.9}cqw)`, aspectRatio: \"1\", pointerEvents: react ? \"auto\" : \"none\" }}\n          onPointerEnter={(event) => hover(i, event)}\n          onPointerLeave={() => leave(i)}\n          onPointerDown={() => tap(i)}\n        >\n          <Mascot\n            bird={b.bird}\n            tone={tone}\n            life\n            look={looks[i]}\n            flying={flying?.index === i}\n            bank={flying?.index === i ? flying.bank : 0}\n            poked={poked[i]}\n            size={120}\n            style={{ width: \"100%\", height: \"100%\", display: \"block\", overflow: \"visible\" }}\n          />\n        </div>\n      ))}\n    </div>\n  );\n}\n"
+      "content": "\"use client\";\n\n// The flock, alive: birds standing on a stage, each at ease in character (Mascot `life`), and the moments between\n// them — two birds glance at each other, the pigeon carries its parcel across, a bird looks up when you come near or tap\n// it. Transform and opacity only: CSS for each bird's own life, a timer for the moments (no frame loop), and nothing at\n// all when the flock is off screen, the tab is hidden or the person asked for less motion.\nimport * as React from \"react\";\n\nimport { cn } from \"../cn\";\nimport type { MascotBird, MascotLook } from \"../mascots\";\nimport { Mascot } from \"../mascots\";\nimport { BEATS, neighbourOf, Prop, receive, type Shown, type Stage } from \"./scenes\";\n\nexport interface FlockBird {\n  /** Which bird. */\n  bird: MascotBird;\n  /** Where its feet are, across the stage: 0 to 100 (% of the stage's width). */\n  x: number;\n  /** Where its feet are, down the stage: 0 to 100 (% of the stage's height). */\n  y: number;\n  /** How wide it is: % of the stage's width. */\n  size: number;\n}\n\nexport interface FlockMoments {\n  /** Two neighbours look at each other now and then. Default `true`. */\n  glance?: boolean;\n  /** The pigeon, when the flock has one, carries its parcel across to another bird and comes back. Default `true`. */\n  courier?: boolean;\n  /** A bird looks up when the pointer comes near, and jumps a little when tapped. Default `true`. */\n  react?: boolean;\n  /**\n   * Scenes, true to each bird's promise: the owl reads a book, the flamingo and the lovebird talk with a speech mark, the\n   * crane steps and bows, the beaver taps a log, the magpie takes a shiny point, the duck builds, the falcon scans — and the\n   * pigeon hands its parcel over, which the receiver opens in its own way. One at a time, at random. Default `false`.\n   */\n  scenes?: boolean;\n}\n\nexport type FlockProps = Omit<React.ComponentProps<\"div\">, \"children\"> &\n  FlockMoments & {\n    /** The birds on the stage. */\n    birds: readonly FlockBird[];\n    /** The stage's shape, width over height (default 16 / 9). It keeps its ratio at any width, so the birds keep their places. */\n    ratio?: number;\n    /** The birds' colours: the host's accent (`brand`, default) or the Krizaka story's (`own`). */\n    tone?: \"brand\" | \"own\";\n    /** The source of chance (default `Math.random`): give it a fixed one in a test. */\n    random?: () => number;\n    /** How lively the moments are: 1 is calm (default), 2 doubles how often neighbours glance and the pigeon delivers. */\n    tempo?: number;\n    /** A bird the page points at (a product the reader is on): it looks up and jumps once each time it changes. */\n    active?: MascotBird | null;\n    /** The birds greet the reader once as the flock first comes into view: each jumps in turn, left to right. */\n    greet?: boolean;\n  };\n\n// @fixed: the rhythm of the moments — how long a glance lasts, how often one happens, how long a delivery takes. A\n// choreography's pace, not a business parameter.\nconst GLANCE_HOLD_MS = [1500, 2400] as const;\nconst GLANCE_EVERY_MS = [4200, 9000] as const;\nconst COURIER_FIRST_MS = 9000;\nconst COURIER_EVERY_MS = [26000, 38000] as const;\nconst FLIGHT_MS = 2600;\nconst HAND_OVER_MS = 1300;\nconst LOOK_BACK_MS = 1600;\n\nconst between = (random: () => number, [lo, hi]: readonly [number, number], tempo = 1) => (lo + random() * (hi - lo)) / tempo;\n// @fixed: the scenes' pace — the wait between two beats, and the rarer long pause.\nconst SCENE_EVERY_MS = [2600, 5200] as const;\nconst SCENE_PAUSE_MS = [8000, 12000] as const;\nconst GREET_STEP_MS = 110;\nconst POKE_MS = 700;\n\n/** `true` while the page may move: no reduced-motion request, the tab visible. */\nfunction useMayMove(): boolean {\n  const [may, setMay] = React.useState(false);\n  React.useEffect(() => {\n    const query = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n    // The page settles first: `html[data-motion=\"settling\"]` (MotionObserver) holds every loop until it is `ready`.\n    const settled = () => document.documentElement.getAttribute(\"data-motion\") !== \"settling\";\n    const update = () => setMay(!query.matches && document.visibilityState !== \"hidden\" && settled());\n    update();\n    query.addEventListener(\"change\", update);\n    document.addEventListener(\"visibilitychange\", update);\n    const watch = typeof MutationObserver === \"undefined\" ? null : new MutationObserver(update);\n    watch?.observe(document.documentElement, { attributes: true, attributeFilter: [\"data-motion\"] });\n    return () => {\n      query.removeEventListener(\"change\", update);\n      document.removeEventListener(\"visibilitychange\", update);\n      watch?.disconnect();\n    };\n  }, []);\n  return may;\n}\n\n/** `true` while the element is on screen. */\nfunction useOnScreen(ref: React.RefObject<Element | null>): boolean {\n  const [on, setOn] = React.useState(false);\n  React.useEffect(() => {\n    const el = ref.current;\n    if (!el || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(([entry]) => setOn(Boolean(entry?.isIntersecting)), { threshold: 0.1 });\n    observer.observe(el);\n    return () => observer.disconnect();\n  }, [ref]);\n  return on;\n}\n\n/**\n * The flock on its stage, alive. Decorative (`aria-hidden`): put the words beside it. Each bird idles in character; every\n * few seconds two neighbours glance at each other; every half minute the pigeon carries its parcel to another bird and\n * returns; a bird looks up when you come near. All of it pauses off screen and in a hidden tab, and the flock is still\n * under `prefers-reduced-motion`.\n */\nexport function Flock({ birds, ratio = 16 / 9, tone = \"brand\", glance = true, courier = true, react = true, scenes = false, random = Math.random, tempo = 1, active = null, greet = false, className, style, ...props }: FlockProps) {\n  const stage = React.useRef<HTMLDivElement>(null);\n  const bodies = React.useRef<(HTMLDivElement | null)[]>([]);\n  const may = useMayMove();\n  const onScreen = useOnScreen(stage);\n  const running = may && onScreen;\n  const [looks, setLooks] = React.useState<Record<number, MascotLook>>({});\n  const [flying, setFlying] = React.useState<{ index: number; bank: number } | null>(null);\n  const [poked, setPoked] = React.useState<Record<number, boolean>>({});\n  const [shown, setShown] = React.useState<Shown[]>([]);\n  const [empty, setEmpty] = React.useState<Record<number, boolean>>({});\n  // Birds a scene holds (a glance or a trip leaves them alone), and the scene or the trip in progress.\n  const held = React.useRef(new Set<number>());\n  const busy = React.useRef<\"scene\" | \"trip\" | null>(null);\n  const ids = React.useRef(0);\n\n  // Left to right: a bird's neighbours are the birds beside it on the stage.\n  const order = React.useMemo(() => birds.map((_, i) => i).sort((a, b) => birds[a]!.x - birds[b]!.x), [birds]);\n  const look = React.useCallback((index: number, to: MascotLook) => setLooks((l) => (l[index] === to ? l : { ...l, [index]: to })), []);\n  const rest = React.useCallback((...indexes: number[]) => setLooks((l) => Object.fromEntries(Object.entries(l).filter(([k]) => !indexes.includes(Number(k))))), []);\n\n  // What a scene can do, bound to one run of an effect: every timer and animation it starts ends with the run.\n  const stageFor = React.useCallback((run: { timers: Set<ReturnType<typeof setTimeout>>; anims: Set<Animation> }): Stage => {\n    const later = (fn: () => void, ms: number) => {\n      const t = setTimeout(() => {\n        run.timers.delete(t);\n        fn();\n      }, ms);\n      run.timers.add(t);\n    };\n    const poke = (index: number, ms = POKE_MS) => {\n      setPoked((p) => ({ ...p, [index]: true }));\n      later(() => setPoked((p) => ({ ...p, [index]: false })), ms);\n    };\n    const show = (index: number, kind: Shown[\"kind\"], ms: number, side?: 1 | -1, mark?: string) => {\n      const item: Shown = { id: ++ids.current, at: index, kind, ms, side, mark };\n      setShown((all) => [...all, item]);\n      later(() => setShown((all) => all.filter((x) => x.id !== item.id)), ms);\n    };\n    return {\n      birds,\n      order,\n      random,\n      look,\n      rest,\n      poke,\n      show,\n      say: (index, mark, ms) => show(index, \"say\", ms, undefined, mark),\n      wait: (ms) => new Promise<void>((resolve) => later(resolve, ms)),\n      move: async (index, keyframes, ms) => {\n        const el = bodies.current[index];\n        if (!el || typeof el.animate !== \"function\") return;\n        const animation = el.animate(keyframes, { duration: ms });\n        run.anims.add(animation);\n        await animation.finished.catch(() => undefined);\n        run.anims.delete(animation);\n      },\n    };\n  }, [birds, order, random, look, rest]);\n\n  // Glances: two neighbours turn towards each other, hold, and look away.\n  React.useEffect(() => {\n    if (!running || !glance || order.length < 2) return;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let back: ReturnType<typeof setTimeout> | undefined;\n    const next = () => {\n      timer = setTimeout(() => {\n        const at = Math.floor(random() * (order.length - 1));\n        const [a, b] = [order[at]!, order[at + 1]!];\n        if (held.current.has(a) || held.current.has(b)) return next();\n        look(a, \"right\");\n        look(b, \"left\");\n        back = setTimeout(() => {\n          rest(a, b);\n          next();\n        }, between(random, GLANCE_HOLD_MS));\n      }, between(random, GLANCE_EVERY_MS, tempo));\n    };\n    next();\n    return () => {\n      clearTimeout(timer);\n      clearTimeout(back);\n    };\n  }, [running, glance, order, random, tempo, look, rest]);\n\n  // The delivery: the pigeon takes its parcel across to the farthest bird, hands it over, and flies back.\n  React.useEffect(() => {\n    const pigeon = birds.findIndex((b) => b.bird === \"pigeon\");\n    if (!running || !courier || pigeon < 0 || birds.length < 2) return;\n    let alive = true;\n    const heldNow = held.current;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let animation: Animation | undefined;\n    const run = { timers: new Set<ReturnType<typeof setTimeout>>(), anims: new Set<Animation>() };\n    // The farthest bird from the pigeon, so the parcel crosses the whole stage.\n    const from = birds[pigeon]!;\n    const target = birds.reduce((far, b, i) => (i !== pigeon && Math.abs(b.x - from.x) > Math.abs(birds[far]!.x - from.x) ? i : far), pigeon === 0 ? 1 : 0);\n    const wait = (ms: number) => new Promise<void>((resolve) => (timer = setTimeout(resolve, ms)));\n    const trip = async () => {\n      // With scenes, the trip waits for the beat in progress and holds the stage while it lasts.\n      while (alive && scenes && busy.current === \"scene\") await wait(400);\n      if (!alive) return;\n      busy.current = \"trip\";\n      const el = bodies.current[pigeon];\n      const box = stage.current?.getBoundingClientRect();\n      if (!el || !box || typeof el.animate !== \"function\") return;\n      const to = birds[target]!;\n      const side = to.x > from.x ? 1 : -1;\n      // It lands beside the receiver, not on it.\n      const dx = ((to.x - from.x) / 100) * box.width - side * (to.size / 100) * box.width * 0.55;\n      const lift = (from.size / 100) * box.width * 0.35;\n      const fly = async (fromX: number, toX: number) => {\n        setFlying({ index: pigeon, bank: Math.sign(toX - fromX) });\n        animation = el.animate(\n          [\n            { transform: `translate(${fromX}px, 0)`, easing: \"ease-out\" },\n            { transform: `translate(${(fromX + toX) / 2}px, ${-lift}px)`, easing: \"ease-in\", offset: 0.5 },\n            { transform: `translate(${toX}px, 0)` },\n          ],\n          { duration: FLIGHT_MS, fill: \"forwards\" },\n        );\n        await animation.finished.catch(() => undefined);\n        setFlying(null);\n      };\n      look(target, side > 0 ? \"left\" : \"right\");\n      held.current.add(target);\n      await fly(0, dx);\n      if (!alive) return;\n      // The hand-over: the receiver looks at the pigeon, the pigeon hops on the doorstep.\n      setPoked((p) => ({ ...p, [pigeon]: true }));\n      if (scenes) {\n        // …and the parcel changes hands: the receiver takes it and reacts in character, the pigeon flies back light.\n        setEmpty((e) => ({ ...e, [pigeon]: true }));\n        const reaction = receive(stageFor(run), target, pigeon);\n        await wait(HAND_OVER_MS);\n        if (!alive) return;\n        setPoked((p) => ({ ...p, [pigeon]: false }));\n        await reaction;\n      } else {\n        await wait(HAND_OVER_MS);\n        if (!alive) return;\n        setPoked((p) => ({ ...p, [pigeon]: false }));\n      }\n      if (!alive) return;\n      look(target, \"up\");\n      await fly(dx, 0);\n      animation?.cancel();\n      setEmpty((e) => ({ ...e, [pigeon]: false }));\n      rest(target);\n    };\n    const schedule = (ms: number) => {\n      timer = setTimeout(async () => {\n        await trip();\n        busy.current = null;\n        held.current.delete(target);\n        if (alive) schedule(between(random, COURIER_EVERY_MS, tempo));\n      }, ms);\n    };\n    schedule(COURIER_FIRST_MS / tempo);\n    return () => {\n      alive = false;\n      clearTimeout(timer);\n      animation?.cancel();\n      run.timers.forEach(clearTimeout);\n      run.anims.forEach((a) => a.cancel());\n      if (scenes) {\n        setShown([]);\n        setEmpty({});\n        heldNow.clear();\n        busy.current = null;\n      }\n      setFlying(null);\n    };\n  }, [running, courier, birds, random, tempo, scenes, stageFor, look, rest]);\n\n  // The scenes: one beat at a time, picked at random from what the flock holds — never the same bird twice in a row, never\n  // at a regular beat (short waits, now and then a long pause) — so the minute is never the same twice.\n  React.useEffect(() => {\n    if (!running || !scenes || birds.length < 1) return;\n    let alive = true;\n    const heldNow = held.current;\n    const run = { timers: new Set<ReturnType<typeof setTimeout>>(), anims: new Set<Animation>() };\n    const st = stageFor(run);\n    const beats = BEATS.flatMap((beat) => birds.flatMap((b, i) => (b.bird === beat.bird ? [{ beat, index: i }] : [])));\n    if (!beats.length) return;\n    let last = -1;\n    const next = async () => {\n      const long = random() < 0.2;\n      await st.wait(between(random, long ? SCENE_PAUSE_MS : SCENE_EVERY_MS, tempo));\n      while (alive && busy.current === \"trip\") await st.wait(600);\n      if (!alive) return;\n      const pool = beats.filter((x) => x.index !== last);\n      const pick = (pool.length ? pool : beats)[Math.floor(random() * (pool.length ? pool.length : beats.length))]!;\n      last = pick.index;\n      busy.current = \"scene\";\n      // The scene's birds are held, so no glance cuts across it.\n      const near = neighbourOf(st, pick.index);\n      held.current.add(pick.index);\n      if (near !== null) held.current.add(near);\n      await pick.beat.run(st, pick.index);\n      held.current.delete(pick.index);\n      if (near !== null) held.current.delete(near);\n      if (busy.current === \"scene\") busy.current = null;\n      if (alive) void next();\n    };\n    void next();\n    return () => {\n      alive = false;\n      run.timers.forEach(clearTimeout);\n      run.anims.forEach((a) => a.cancel());\n      setShown([]);\n      heldNow.clear();\n      busy.current = null;\n    };\n  }, [running, scenes, birds, random, tempo, stageFor]);\n\n  // The greeting: the first time the flock is on screen, each bird jumps in turn.\n  const greeted = React.useRef(false);\n  React.useEffect(() => {\n    if (!running || !greet || greeted.current) return;\n    greeted.current = true;\n    const timers: ReturnType<typeof setTimeout>[] = [];\n    order.forEach((index, n) => {\n      timers.push(setTimeout(() => setPoked((p) => ({ ...p, [index]: true })), n * GREET_STEP_MS));\n      timers.push(setTimeout(() => setPoked((p) => ({ ...p, [index]: false })), n * GREET_STEP_MS + POKE_MS));\n    });\n    return () => timers.forEach(clearTimeout);\n  }, [running, greet, order]);\n\n  // The bird the page points at looks up and jumps.\n  React.useEffect(() => {\n    const index = active ? birds.findIndex((b) => b.bird === active) : -1;\n    if (!running || index < 0) return;\n    const start = setTimeout(() => {\n      look(index, \"up\");\n      setPoked((p) => ({ ...p, [index]: true }));\n    }, 0);\n    const t = setTimeout(() => setPoked((p) => ({ ...p, [index]: false })), POKE_MS);\n    return () => {\n      clearTimeout(start);\n      clearTimeout(t);\n      setPoked((p) => ({ ...p, [index]: false }));\n      rest(index);\n    };\n  }, [active, running, birds, look, rest]);\n\n  // A bird looks up when you come near, and jumps when you tap it.\n  const hover = (index: number, event: React.PointerEvent) => {\n    if (!running || !react || event.pointerType !== \"mouse\") return;\n    look(index, \"up\");\n  };\n  const leave = (index: number) => {\n    if (!react) return;\n    rest(index);\n  };\n  const tap = (index: number) => {\n    if (!running || !react) return;\n    look(index, \"up\");\n    setPoked((p) => ({ ...p, [index]: true }));\n    setTimeout(() => {\n      setPoked((p) => ({ ...p, [index]: false }));\n      rest(index);\n    }, LOOK_BACK_MS);\n  };\n\n  return (\n    <div\n      ref={stage}\n      aria-hidden\n      data-flock=\"\"\n      data-running={running ? \"\" : undefined}\n      data-motion-scope=\"\"\n      className={cn(\"relative w-full\", className)}\n      style={{ aspectRatio: String(ratio), containerType: \"inline-size\", ...style }}\n      {...props}\n    >\n      {birds.map((b, i) => (\n        <div\n          key={`${b.bird}-${i}`}\n          ref={(el) => {\n            bodies.current[i] = el;\n          }}\n          data-flock-bird={b.bird}\n          className=\"absolute touch-manipulation\"\n          style={{ left: `${b.x - b.size / 2}%`, width: `${b.size}%`, top: `calc(${b.y}% - ${b.size * 0.9}cqw)`, aspectRatio: \"1\", pointerEvents: react ? \"auto\" : \"none\" }}\n          onPointerEnter={(event) => hover(i, event)}\n          onPointerLeave={() => leave(i)}\n          onPointerDown={() => tap(i)}\n        >\n          <Mascot\n            bird={b.bird}\n            tone={tone}\n            life\n            look={looks[i]}\n            flying={flying?.index === i}\n            bank={flying?.index === i ? flying.bank : 0}\n            poked={poked[i]}\n            carrying={!empty[i]}\n            size={120}\n            style={{ width: \"100%\", height: \"100%\", display: \"block\", overflow: \"visible\" }}\n          />\n          {shown\n            .filter((x) => x.at === i)\n            .map((x) => (\n              <Prop key={x.id} shown={x} size={b.size} />\n            ))}\n        </div>\n      ))}\n    </div>\n  );\n}\n"
     },
     {
       "path": "flock/index.ts",
@@ -172,11 +189,15 @@
     },
     {
       "path": "flock/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Flock\",\n  summary:\n    \"The Krizaka birds standing on a stage, alive: each at ease in character, two neighbours glancing at each other, the pigeon carrying its parcel across, a bird looking up when you come near or tap it.\",\n  status: \"beta\",\n  category: \"blocks\",\n  platforms: \"web\",\n  parity: {\n    native: { status: \"n/a\", reason: \"A decorative stage for a public page's first screen; an app screen speaks with MascotState.\", use: \"mascot-state\" },\n    desktop: \"web\",\n  },\n  whenToUse: [\n    \"On a company's home, where the flock is the scene: five birds on a ridge, under the words.\",\n    \"On an about or story page, where the birds are the subject and a still drawing would feel dead.\",\n  ],\n  whenNotToUse: [\n    { when: \"A bird that answers a state (a wait, an error, an empty list).\", use: \"mascot-state\" },\n    { when: \"One bird at ease inside a card or beside a rule.\", use: \"mascots\" },\n    { when: \"The flock as a still plate with its promises.\", use: \"bird-plate\" },\n  ],\n  bestPractices: [\n    \"One flock per page, under the words and never behind them: the birds are the scene, not the message.\",\n    \"Give the stage the ratio of its backdrop (`ratio`) and the birds' places in percent: they keep their positions at any width.\",\n    \"Keep each bird to its job: the falcon watches, the owl reads, the duck builds, the flamingo answers, the pigeon delivers.\",\n    \"Make it the page's own: `active` is the bird of the product the reader is on (it looks up and jumps), `greet` has every bird jump once as the flock comes into view, `tempo` makes the moments more frequent.\",\n    \"Turn a moment off with `glance={false}`, `courier={false}` or `react={false}` on a page that already moves.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"Decorative (`aria-hidden`): it never carries information; put the words beside it.\",\n      \"Under `prefers-reduced-motion` the birds are still: no idle motion, no glance, no delivery, no reaction.\",\n      \"The moments pause while the flock is off screen and while the tab is hidden; there is no frame loop.\",\n    ],\n  },\n  related: [\"mascots\", \"mascot-state\", \"bird-plate\", \"landscape\"],\n  web: {\n    imports: [\"Flock\"],\n    examples: [\n      { name: \"ridge\", title: \"The flock on its ridge\", description: \"Five birds across a stage, each at ease; neighbours glance, the pigeon delivers.\" },\n      { name: \"pair\", title: \"Two birds\", description: \"The owl and the duck: they look at each other now and then.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Flock\",\n  summary:\n    \"The Krizaka birds standing on a stage, alive: each at ease in character, two neighbours glancing at each other, the pigeon carrying its parcel across, a bird looking up when you come near or tap it — and, with `scenes`, a short scene for each bird.\",\n  status: \"beta\",\n  category: \"blocks\",\n  platforms: \"web\",\n  parity: {\n    native: { status: \"n/a\", reason: \"A decorative stage for a public page's first screen; an app screen speaks with MascotState.\", use: \"mascot-state\" },\n    desktop: \"web\",\n  },\n  whenToUse: [\n    \"On a company's home, where the flock is the scene: five birds on a ridge, under the words.\",\n    \"On an about or story page, where the birds are the subject and a still drawing would feel dead.\",\n  ],\n  whenNotToUse: [\n    { when: \"A bird that answers a state (a wait, an error, an empty list).\", use: \"mascot-state\" },\n    { when: \"One bird at ease inside a card or beside a rule.\", use: \"mascots\" },\n    { when: \"The flock as a still plate with its promises.\", use: \"bird-plate\" },\n  ],\n  bestPractices: [\n    \"One flock per page, under the words and never behind them: the birds are the scene, not the message.\",\n    \"Give the stage the ratio of its backdrop (`ratio`) and the birds' places in percent: they keep their positions at any width.\",\n    \"Keep each bird to its job: the falcon watches, the owl reads, the duck builds, the flamingo answers, the pigeon delivers.\",\n    \"Make it the page's own: `active` is the bird of the product the reader is on (it looks up and jumps), `greet` has every bird jump once as the flock comes into view, `tempo` makes the moments more frequent.\",\n    \"`scenes` gives each bird a short scene true to its promise (the owl reads a book, the flamingo and the lovebird talk, the crane bows, the beaver taps a log, the magpie takes a shiny point, the duck builds, the falcon scans) and has the pigeon hand its parcel over, which the receiver opens in its own way. One at a time, at random, with long pauses now and then: leave `tempo` near 1 to 1.7.\",\n    \"Turn a moment off with `glance={false}`, `courier={false}` or `react={false}` on a page that already moves.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"Decorative (`aria-hidden`): it never carries information; put the words beside it.\",\n      \"Under `prefers-reduced-motion` the birds are still: no idle motion, no glance, no delivery, no scene, no reaction.\",\n      \"It waits for the page to settle (`html[data-motion=\\\"settling\\\"]`) and pauses off screen (the stage is a `data-motion-scope`).\",\n      \"The moments pause while the flock is off screen and while the tab is hidden; there is no frame loop.\",\n    ],\n  },\n  related: [\"mascots\", \"mascot-state\", \"bird-plate\", \"landscape\"],\n  web: {\n    imports: [\"Flock\"],\n    examples: [\n      { name: \"ridge\", title: \"The flock on its ridge\", description: \"Five birds across a stage, each at ease; neighbours glance, the pigeon delivers.\" },\n      { name: \"scenes\", title: \"The scenes\", description: \"The owl reads, the flamingo and the lovebird talk, the crane bows, the beaver taps a log, the magpie takes a shiny point, and the pigeon hands its parcel over.\" },\n      { name: \"pair\", title: \"Two birds\", description: \"The owl and the duck: they look at each other now and then.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "flock/scenes.tsx",
+      "content": "\"use client\";\n\n// The flock's scenes: what a bird does between the idle motions, each one true to the promise it carries — the owl reads\n// (a book, a leaf turned), the flamingo and the lovebird answer (a speech mark, a reply), the crane steps and bows, the\n// beaver carries a log and taps it, the magpie spots a shiny point and takes it, the duck builds, the falcon scans — and the\n// pigeon's parcel changes hands: the receiver reacts in its own way. A director picks one beat at a time from what the\n// flock holds, with chance in the waits and in the choice, so it never loops the same minute twice. Transform and opacity\n// only (Web Animations on a few small elements, timers between beats); nothing runs off screen or under reduced motion.\nimport * as React from \"react\";\n\nimport type { MascotBird, MascotLook } from \"../mascots\";\nimport { PARCEL } from \"../mascots/geometry\";\n\nexport type PropKind = \"say\" | \"book\" | \"log\" | \"glint\" | \"gift\";\n\n/** A small thing a bird shows for a while: a speech mark, a book, a log, a shiny point, a parcel. */\nexport interface Shown {\n  id: number;\n  /** Index of the bird it belongs to. */\n  at: number;\n  kind: PropKind;\n  /** How long it stays (ms). */\n  ms: number;\n  /** The mark of a speech bubble. */\n  mark?: string;\n  /** Which side it comes from (1: right, -1: left). */\n  side?: 1 | -1;\n}\n\n/** What a beat can do on the stage (built by `Flock`; every wait ends when the flock stops). */\nexport interface Stage {\n  birds: readonly { bird: MascotBird; x: number; y: number; size: number }[];\n  /** Indexes left to right. */\n  order: readonly number[];\n  random: () => number;\n  look: (index: number, to: MascotLook) => void;\n  rest: (...indexes: number[]) => void;\n  poke: (index: number, ms?: number) => void;\n  say: (index: number, mark: string, ms: number) => void;\n  show: (index: number, kind: PropKind, ms: number, side?: 1 | -1) => void;\n  /** Move a bird's body for a while (transform only). */\n  move: (index: number, keyframes: Keyframe[], ms: number) => Promise<void>;\n  wait: (ms: number) => Promise<void>;\n}\n\nconst side = (s: Stage, i: number, j: number): 1 | -1 => (s.birds[j]!.x >= s.birds[i]!.x ? 1 : -1);\nconst towards = (s: Stage, i: number, j: number): MascotLook => (side(s, i, j) > 0 ? \"right\" : \"left\");\n/** Where a bird is among its neighbours, left to right: the one beside it (the nearer one when there are two). */\nexport function neighbourOf(s: Stage, i: number): number | null {\n  const at = s.order.indexOf(i);\n  const near = [s.order[at - 1], s.order[at + 1]].filter((n): n is number => n !== undefined);\n  if (!near.length) return null;\n  return near.reduce((a, b) => (Math.abs(s.birds[a]!.x - s.birds[i]!.x) <= Math.abs(s.birds[b]!.x - s.birds[i]!.x) ? a : b));\n}\n\n// @fixed: the choreography's pace — how long each beat lasts. A rhythm to the eye, not a business parameter.\nconst BOOK_MS = 4800;\nconst LOG_MS = 3800;\nconst GLINT_MS = 3400;\nconst SAY_MS = 1500;\n\n/** The owl reads: it looks down at its book, a leaf turns, and it turns another. A neighbour glances over. */\nasync function read(s: Stage, i: number) {\n  const j = neighbourOf(s, i);\n  s.look(i, \"left\");\n  s.show(i, \"book\", BOOK_MS);\n  await s.wait(BOOK_MS * 0.45);\n  if (j !== null && s.random() < 0.5) {\n    s.look(j, towards(s, j, i));\n    await s.wait(1100);\n    s.rest(j);\n  }\n  await s.wait(BOOK_MS * 0.5);\n  s.rest(i);\n}\n\n/** The flamingo or the lovebird speaks; its neighbour listens, then answers, and they both light up. */\nasync function chat(s: Stage, i: number) {\n  const j = neighbourOf(s, i);\n  s.look(i, j === null ? \"up\" : towards(s, i, j));\n  s.say(i, \"…\", SAY_MS);\n  await s.wait(SAY_MS * 0.6);\n  if (j === null) {\n    await s.wait(SAY_MS * 0.6);\n    s.rest(i);\n    return;\n  }\n  s.look(j, towards(s, j, i));\n  await s.wait(SAY_MS * 0.7);\n  s.say(j, s.random() < 0.5 ? \"!\" : \"?\", SAY_MS);\n  s.poke(j);\n  await s.wait(SAY_MS * 0.5);\n  s.poke(i);\n  await s.wait(SAY_MS * 0.7);\n  s.rest(i, j);\n}\n\n/** The crane steps out of the line, bows to its neighbour, and steps back. */\nasync function bow(s: Stage, i: number) {\n  const j = neighbourOf(s, i);\n  const dir = j === null ? 1 : side(s, i, j);\n  const step = `${(s.birds[i]!.size * 0.14 * dir).toFixed(2)}cqw`;\n  const lean = `rotate(${dir * 11}deg)`;\n  const at = (x: string, r: string) => `translateX(${x}) ${r}`;\n  const run = s.move(\n    i,\n    [\n      { transform: at(\"0cqw\", \"rotate(0deg)\"), easing: \"ease-in-out\" },\n      { transform: at(step, \"rotate(0deg)\"), offset: 0.22, easing: \"ease-in-out\" },\n      { transform: at(step, lean), offset: 0.42, easing: \"ease-in-out\" },\n      { transform: at(step, lean), offset: 0.6, easing: \"ease-in-out\" },\n      { transform: at(step, \"rotate(0deg)\"), offset: 0.74, easing: \"ease-in-out\" },\n      { transform: at(\"0cqw\", \"rotate(0deg)\") },\n    ],\n    3800,\n  );\n  if (j !== null) {\n    await s.wait(1700);\n    s.look(j, towards(s, j, i));\n    await s.wait(1200);\n    s.poke(j);\n    await s.wait(500);\n    s.rest(j);\n  }\n  await run;\n}\n\n/** The beaver brings a log, taps it into place three times, and takes it away. */\nasync function tap(s: Stage, i: number) {\n  s.show(i, \"log\", LOG_MS, s.birds[i]!.x > 50 ? 1 : -1);\n  await s.wait(LOG_MS * 0.3);\n  for (let n = 0; n < 3; n++) {\n    s.poke(i, 420);\n    await s.wait(520);\n  }\n  await s.wait(LOG_MS * 0.3);\n}\n\n/** The magpie sees something shiny on the ground, looks, hops, and takes it. */\nasync function shine(s: Stage, i: number) {\n  const dir: 1 | -1 = s.birds[i]!.x > 50 ? -1 : 1;\n  const to: MascotLook = dir > 0 ? \"right\" : \"left\";\n  s.show(i, \"glint\", GLINT_MS, dir);\n  await s.wait(GLINT_MS * 0.28);\n  s.look(i, to);\n  await s.wait(GLINT_MS * 0.3);\n  s.poke(i);\n  await s.wait(GLINT_MS * 0.25);\n  s.look(i, \"up\");\n  await s.wait(GLINT_MS * 0.2);\n  s.rest(i);\n}\n\n/** The duck builds: quick nods in a burst, like typing a block into place. */\nasync function build(s: Stage, i: number) {\n  for (let n = 0; n < 4; n++) {\n    s.poke(i, 300);\n    await s.wait(380);\n  }\n}\n\n/** The falcon watches: a slow scan, left then right, and a look up. */\nasync function scan(s: Stage, i: number) {\n  for (const to of [\"left\", \"up\", \"right\"] as const) {\n    s.look(i, to);\n    await s.wait(1100);\n  }\n  s.rest(i);\n}\n\n/** The pigeon's parcel has just been handed over: the receiver reacts in its own way (about 2 s). */\nexport async function receive(s: Stage, i: number, from: number) {\n  const bird = s.birds[i]!.bird;\n  s.look(i, towards(s, i, from));\n  s.show(i, \"gift\", 2400);\n  await s.wait(350);\n  if (bird === \"crane\") await bow(s, i);\n  else if (bird === \"magpie\") {\n    s.poke(i);\n    await s.wait(700);\n    s.show(i, \"glint\", GLINT_MS * 0.6, side(s, i, from));\n    await s.wait(1200);\n  } else if (bird === \"beaver\" || bird === \"duck\") {\n    s.poke(i, 420);\n    await s.wait(520);\n    s.poke(i, 420);\n    await s.wait(900);\n  } else if (bird === \"owl\") {\n    s.say(i, \"?\", SAY_MS);\n    await s.wait(900);\n    s.poke(i);\n    await s.wait(700);\n  } else {\n    s.say(i, \"!\", SAY_MS);\n    s.poke(i);\n    await s.wait(1500);\n  }\n}\n\nexport interface Beat {\n  id: string;\n  bird: MascotBird;\n  run: (s: Stage, index: number) => Promise<void>;\n}\n\n/** What each bird of the flock can do on its own (the pigeon's trip is the flock's courier). */\nexport const BEATS: readonly Beat[] = [\n  { id: \"read\", bird: \"owl\", run: read },\n  { id: \"chat\", bird: \"flamingo\", run: chat },\n  { id: \"chat\", bird: \"lovebird\", run: chat },\n  { id: \"bow\", bird: \"crane\", run: bow },\n  { id: \"tap\", bird: \"beaver\", run: tap },\n  { id: \"shine\", bird: \"magpie\", run: shine },\n  { id: \"build\", bird: \"duck\", run: build },\n  { id: \"scan\", bird: \"falcon\", run: scan },\n];\n\n// ─── The small things a bird shows ───────────────────────────────────────────────────────────────\n\nconst PAPER = \"var(--kz-surface-1)\";\nconst INK = \"var(--kz-text-primary)\";\nconst LINE = \"var(--kz-border-strong, currentColor)\";\n\n/** One thing, in its own frame: it comes in, stays for `ms`, and goes (opacity and transform only). */\nfunction lifeFrames(from: string, to: string): Keyframe[] {\n  return [\n    { opacity: 0, transform: from, offset: 0 },\n    { opacity: 1, transform: \"none\", offset: 0.14 },\n    { opacity: 1, transform: \"none\", offset: 0.84 },\n    { opacity: 0, transform: to, offset: 1 },\n  ];\n}\n\nconst LEAF: Keyframe[] = [\n  { transform: \"scaleX(1)\", offset: 0 },\n  { transform: \"scaleX(1)\", offset: 0.25 },\n  { transform: \"scaleX(-1)\", offset: 0.38 },\n  { transform: \"scaleX(1)\", offset: 0.39 },\n  { transform: \"scaleX(1)\", offset: 0.62 },\n  { transform: \"scaleX(-1)\", offset: 0.75 },\n  { transform: \"scaleX(-1)\", offset: 1 },\n];\n\nexport function Prop({ shown, size }: { shown: Shown; size: number }) {\n  const ref = React.useRef<HTMLDivElement>(null);\n  const leaf = React.useRef<HTMLDivElement>(null);\n  const dir = shown.side ?? 1;\n  React.useEffect(() => {\n    const el = ref.current;\n    if (!el || typeof el.animate !== \"function\") return;\n    const from: Record<PropKind, [string, string]> = {\n      say: [\"translateY(30%) scale(.5)\", \"translateY(-12%) scale(.9)\"],\n      book: [\"translateY(40%) scale(.8)\", \"translateY(20%) scale(.9)\"],\n      log: [`translateX(${190 * dir}%)`, `translateX(${190 * dir}%)`],\n      glint: [\"scale(.2) rotate(-60deg)\", `translate(${-90 * dir}%, -170%) scale(.2) rotate(60deg)`],\n      gift: [\"translateY(40%) scale(.3)\", \"translateY(-30%) scale(1.4)\"],\n    };\n    const [a, b] = from[shown.kind];\n    const animations = [el.animate(lifeFrames(a, b), { duration: shown.ms, fill: \"both\", easing: \"ease-out\" })];\n    if (shown.kind === \"book\" && leaf.current) animations.push(leaf.current.animate(LEAF, { duration: shown.ms, fill: \"both\", easing: \"ease-in-out\" }));\n    if (shown.kind === \"glint\") animations.push(el.firstElementChild!.animate([{ transform: \"scale(1)\" }, { transform: \"scale(1.35)\" }, { transform: \"scale(1)\" }], { duration: 700, iterations: Math.ceil(shown.ms / 700), easing: \"ease-in-out\" }));\n    return () => animations.forEach((x) => x.cancel());\n  }, [shown, dir]);\n\n  const unit = (n: number) => `calc(${size}cqw * ${n})`;\n  const base: React.CSSProperties = { position: \"absolute\", pointerEvents: \"none\", opacity: 0 };\n\n  if (shown.kind === \"say\")\n    return (\n      <div ref={ref} data-flock-prop=\"say\" style={{ ...base, left: \"58%\", top: \"-6%\", width: unit(0.34), height: unit(0.24), transformOrigin: \"20% 100%\" }}>\n        <span\n          style={{ position: \"absolute\", inset: 0, display: \"grid\", placeItems: \"center\", background: PAPER, border: `1.5px solid ${LINE}`, borderRadius: \"999px\", color: INK, font: `600 ${unit(0.17)}/1 var(--font-mono, ui-monospace, monospace)` }}\n        >\n          {shown.mark ?? \"…\"}\n        </span>\n        <span style={{ position: \"absolute\", left: \"14%\", bottom: \"-12%\", width: unit(0.07), height: unit(0.07), background: PAPER, borderRight: `1.5px solid ${LINE}`, borderBottom: `1.5px solid ${LINE}`, transform: \"rotate(45deg)\" }} />\n      </div>\n    );\n\n  if (shown.kind === \"book\")\n    return (\n      <div ref={ref} data-flock-prop=\"book\" style={{ ...base, left: \"17%\", bottom: \"-2%\", width: \"66%\", height: unit(0.2), transformOrigin: \"50% 100%\" }}>\n        {[0, 1].map((n) => (\n          <span key={n} style={{ position: \"absolute\", top: 0, bottom: 0, [n ? \"right\" : \"left\"]: 0, width: \"50%\", background: `repeating-linear-gradient(${PAPER} 0 18%, ${LINE} 18% 24%)`, border: `1.5px solid ${LINE}`, borderRadius: n ? \"0 3px 3px 0\" : \"3px 0 0 3px\" }} />\n        ))}\n        <div ref={leaf} style={{ position: \"absolute\", top: 0, bottom: 0, left: \"50%\", width: \"50%\", transformOrigin: \"0 50%\", background: PAPER, border: `1.5px solid ${LINE}`, borderRadius: \"0 3px 3px 0\" }} />\n      </div>\n    );\n\n  if (shown.kind === \"log\")\n    return (\n      <div ref={ref} data-flock-prop=\"log\" style={{ ...base, left: \"22%\", bottom: \"-3%\", width: \"56%\", height: unit(0.17), background: PARCEL[2], borderRadius: \"999px\", boxShadow: `inset -${unit(0.04)} 0 0 ${PARCEL[1]}` }}>\n        <span style={{ position: \"absolute\", left: 0, top: 0, bottom: 0, aspectRatio: \"1\", borderRadius: \"50%\", background: `radial-gradient(${PARCEL[0]} 0 25%, ${PARCEL[1]} 26% 55%, ${PARCEL[2]} 56%)`, border: `1px solid ${PARCEL[2]}` }} />\n      </div>\n    );\n\n  if (shown.kind === \"glint\")\n    return (\n      <div ref={ref} data-flock-prop=\"glint\" style={{ ...base, [dir > 0 ? \"left\" : \"right\"]: \"94%\", bottom: \"2%\", width: unit(0.2), height: unit(0.2) }}>\n        <span style={{ position: \"absolute\", inset: 0, background: PARCEL[0], clipPath: \"polygon(50% 0, 62% 38%, 100% 50%, 62% 62%, 50% 100%, 38% 62%, 0 50%, 38% 38%)\" }} />\n      </div>\n    );\n\n  return (\n    <div ref={ref} data-flock-prop=\"gift\" style={{ ...base, left: \"58%\", top: \"2%\", width: unit(0.26), height: unit(0.22), background: PARCEL[0], border: `1.5px solid ${PARCEL[2]}`, borderRadius: 2 }}>\n      <span style={{ position: \"absolute\", left: \"44%\", top: 0, bottom: 0, width: \"12%\", background: PARCEL[2] }} />\n      <span style={{ position: \"absolute\", top: \"42%\", left: 0, right: 0, height: \"16%\", background: PARCEL[2] }} />\n    </div>\n  );\n}\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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"elephant\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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": [],
@@ -249,6 +270,13 @@
           "description": "A bird looks up when the pointer comes near, and jumps a little when tapped. Default `true`.",
           "required": false
         },
+        {
+          "name": "scenes",
+          "type": "boolean",
+          "default": "false",
+          "description": "Scenes, true to each bird's promise: the owl reads a book, the flamingo and the lovebird talk with a speech mark, the\ncrane steps and bows, the beaver taps a log, the magpie takes a shiny point, the duck builds, the falcon scans — and the\npigeon hands its parcel over, which the receiver opens in its own way. One at a time, at random. Default `false`.",
+          "required": false
+        },
         {
           "name": "tempo",
           "type": "number",

package/registry/footnote.json

@@ -144,7 +144,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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"elephant\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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": [],

package/registry/force-update-screen.json

@@ -243,7 +243,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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"elephant\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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": [

package/registry/form.json

@@ -2097,7 +2097,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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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  | \"anatomy-plate\"\n  | \"bird-plate\"\n  | \"flock\"\n  | \"elephant\"\n  | \"footnote\"\n  | \"page-index\"\n  | \"specimen-tag\"\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  | \"chip-row\"\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  | \"cover-hero\"\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  | \"engine-flow\"\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  | \"language-switch\"\n  | \"media-gallery\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"opening-hours\"\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  | \"service-card\"\n  | \"settings-layout\"\n  | \"account-menu\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot-picker\"\n  | \"slot\"\n  | \"spinner\"\n  | \"sticky-action\"\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": [