@krizaka/ui 3.4.0 → 3.6.0

package/registry/map.json

@@ -5,6 +5,7 @@
   "summary": "Maps that cost nothing per view — MapLibre (open source) over Protomaps tiles on the Krizaka CDN, painted from the tokens in dark or light and in the product's accent — with markers, clusters, the person's position, a radius and a location picker.",
   "description": "Maps that cost nothing per view — MapLibre (open source) over Protomaps tiles on the Krizaka CDN, painted from the tokens in dark or light and in the product's accent — with markers, clusters, the person's position, a radius and a location picker.",
   "status": "beta",
+  "deprecated": null,
   "category": "data-display",
   "platforms": "both",
   "whenToUse": [
@@ -901,7 +902,7 @@
     },
     {
       "path": "map/map.tsx",
-      "content": "// Client. A map of the Krizaka family on MapLibre GL JS (open source) over Protomaps tiles on our CDN — no API key, no\n// metered service. MapLibre and PMTiles are optional peers, loaded when a map is shown (a dynamic import: a page without\n// a map never pays for them). The style comes from the tokens (`mapStyle`), in the page's scheme, and follows it.\n//\n// What every map does: the canvas is decorative for assistive technologies — the map is a region named by `label`, its\n// places a list read in order (the text alternative, `MapPlaces`), each marker a button when it does something; the\n// attribution of OpenStreetMap (ODbL) and Protomaps is always shown; under reduced motion the camera jumps, never flies;\n// without WebGL (or while the engine loads) `fallback` stands in its place.\n/// <reference types=\"geojson\" />\nimport * as React from \"react\";\nimport { createPortal } from \"react-dom\";\n\nimport { usePrefersReducedMotion } from \"../media\";\nimport { tv } from \"../tv\";\nimport { MAP_ATTRIBUTION, setMapAssetsBase } from \"./assets\";\nimport { circlePolygon, type LngLat } from \"./geo\";\nimport { type MapBrand, mapPalette, type MapRegion, mapStyle } from \"./style\";\n\ntype MapLibre = typeof import(\"maplibre-gl\");\ntype MapInstance = import(\"maplibre-gl\").Map;\n\nexport const map = tv({\n  slots: {\n    root: \"relative isolate overflow-hidden rounded-2xl border border-border-default bg-surface-2 shadow-raised\",\n    canvas: \"absolute inset-0 [&_.maplibregl-canvas]:outline-hidden\",\n    fallback: \"absolute inset-0\",\n    controls: \"absolute right-3 top-3 z-10 flex flex-col overflow-hidden rounded-xl border border-border-default bg-surface-1 shadow-floating\",\n    control:\n      \"inline-flex h-10 w-10 items-center justify-center text-lg font-semibold text-fg-secondary transition-colors hover:bg-surface-3 hover:text-fg \" +\n      \"focus-visible:outline-hidden focus-visible:focus-ring-inset disabled:opacity-40 [&+&]:border-t [&+&]:border-border-subtle\",\n    attribution:\n      \"absolute bottom-1.5 right-1.5 z-10 rounded-md bg-surface-1/85 px-1.5 py-0.5 text-[10px] text-fg-secondary backdrop-blur-sm [&_a]:underline-offset-2 hover:[&_a]:underline\",\n    places: \"sr-only\",\n    marker:\n      \"group relative flex -translate-y-1/2 cursor-pointer items-center justify-center rounded-full border-2 border-on-accent bg-accent shadow-floating outline-hidden \" +\n      \"transition-transform hover:scale-110 focus-visible:focus-ring motion-reduce:transition-none motion-reduce:hover:scale-100 data-[selected]:scale-125\",\n    markerLabel:\n      \"pointer-events-none absolute bottom-full mb-2 whitespace-nowrap rounded-lg border border-border-default bg-surface-1 px-2 py-1 text-xs font-semibold text-fg shadow-floating\",\n  },\n});\n\ntype Registry = { add: (id: string, text: string) => void; remove: (id: string) => void };\ntype Ctx = { map: MapInstance | null; lib: MapLibre | null; ready: boolean; reduce: boolean; places: Registry };\nconst MapContext = React.createContext<Ctx | null>(null);\n\n/** The map a child is drawn on (`Marker`, `RadiusCircle`, `Cluster`…): the MapLibre instance once it is ready. */\nexport function useMap(): Ctx {\n  const ctx = React.useContext(MapContext);\n  if (!ctx) throw new Error(\"useMap: inside a <Map> only\");\n  return ctx;\n}\n\n/** The scheme of the page (`html.light`), followed as it changes. */\nfunction usePageScheme(): \"dark\" | \"light\" {\n  const read = () => (typeof document !== \"undefined\" && document.documentElement.classList.contains(\"light\") ? \"light\" : \"dark\");\n  const [scheme, setScheme] = React.useState<\"dark\" | \"light\">(read);\n  React.useEffect(() => {\n    const observer = new MutationObserver(() => setScheme(read()));\n    observer.observe(document.documentElement, { attributes: true, attributeFilter: [\"class\"] });\n    return () => observer.disconnect();\n  }, []);\n  return scheme;\n}\n\nlet protocolAdded = false;\nlet workerUrl: string | null = null;\n\n/**\n * Where MapLibre's worker comes from. A bundler (Next.js, Vite) renames MapLibre's module and leaves its worker behind:\n * by default the worker of the very version the app installed is imported from jsDelivr (free, open source, no key)\n * through a module worker of the page's own origin. An app with a strict CSP serves it itself —\n * `configureMaps({ workerUrl: \"/maplibre-gl-worker.mjs\" })` (with `maplibre-gl-shared.mjs` beside it), once, before a map.\n * `assetsBase` reads the tiles and glyphs through a same-origin proxy of the CDN (`setMapAssetsBase`).\n */\nexport function configureMaps(options: { workerUrl?: string; assetsBase?: string }) {\n  if (options.workerUrl) workerUrl = options.workerUrl;\n  if (options.assetsBase) setMapAssetsBase(options.assetsBase);\n}\n\n/** MapLibre, its worker and the PMTiles protocol, loaded once for the page. */\nasync function loadEngine(): Promise<MapLibre> {\n  const [lib, pmtiles] = await Promise.all([import(\"maplibre-gl\"), import(\"pmtiles\")]);\n  const ml = ((lib as unknown as { default?: MapLibre }).default ?? lib) as MapLibre;\n  if (!protocolAdded) {\n    protocolAdded = true;\n    const remote = `https://cdn.jsdelivr.net/npm/maplibre-gl@${ml.getVersion()}/dist/maplibre-gl-worker.mjs`;\n    ml.setWorkerUrl(workerUrl ?? URL.createObjectURL(new Blob([`import ${JSON.stringify(remote)};`], { type: \"text/javascript\" })));\n    ml.addProtocol(\"pmtiles\", new pmtiles.Protocol().tile);\n  }\n  return ml;\n}\n\nconst hasWebGL = () => {\n  try {\n    const canvas = document.createElement(\"canvas\");\n    return Boolean(canvas.getContext(\"webgl2\") ?? canvas.getContext(\"webgl\"));\n  } catch {\n    return false;\n  }\n};\n\nexport type MapLabels = {\n  /** The zoom-in button (\"Zoom in\"). */\n  zoomIn: string;\n  /** The zoom-out button (\"Zoom out\"). */\n  zoomOut: string;\n  /** Before the list of places read in place of the map (\"Places on the map\"). */\n  places: string;\n};\n\nexport const mapLabels: MapLabels = { zoomIn: \"Zoom in\", zoomOut: \"Zoom out\", places: \"Places on the map\" };\n\nexport type MapProps = {\n  /** The map's accessible name (\"Pick-up points near you\"), passed translated. */\n  label: string;\n  /** Where the map looks at first: longitude, latitude. */\n  center: LngLat;\n  /** The zoom at first (0 the world, 12 a city, 16 a street). Default 12. */\n  zoom?: number;\n  /** The camera follows `center` and `zoom` when they change (flies, or jumps under reduced motion). */\n  controlled?: boolean;\n  /** The scheme. Default: the page's (`html.light`), followed. */\n  scheme?: \"dark\" | \"light\";\n  /** The product whose accent the map carries. Default `krizaka`. */\n  brand?: MapBrand;\n  /** The language of the labels (`fr`, `en`). Default `en`. */\n  lang?: string;\n  /** The detailed region (PMTiles) drawn from zoom 6.5. Default: our Montréal–Québec extract (to zoom 14). */\n  region?: MapRegion | null;\n  /** The world's low zooms (PMTiles). Default: our world extract (to zoom 6). */\n  world?: MapRegion | null;\n  /** The zoom buttons (default) — the keyboard also zooms with + and − on the focused map. */\n  controls?: boolean;\n  /** Moves with the hand (default); `false` makes a still picture of a place. */\n  interactive?: boolean;\n  /** Shown in place of the map while its engine loads, and for good without WebGL: a `StaticMap`, a picture. */\n  fallback?: React.ReactNode;\n  /** Called when the camera rests: its centre and zoom. */\n  onMoveEnd?: (view: { center: LngLat; zoom: number }) => void;\n  /** Called with the position pressed on the map (not on a marker). */\n  onPress?: (position: LngLat) => void;\n  /** Markers, circles, clusters, the user's position — and anything drawn over the map. */\n  children?: React.ReactNode;\n  /** The words, passed translated; English by default. */\n  labels?: Partial<MapLabels>;\n  /** Classes merged on the root (its height: `h-80`, `aspect-video`). */\n  className?: string;\n};\n\n/** A map: MapLibre over our Protomaps tiles, styled from the tokens, with its places as a list for screen readers. */\nexport function Map({\n  label,\n  center,\n  zoom = 12,\n  controlled,\n  scheme: schemeProp,\n  brand,\n  lang,\n  region,\n  world,\n  controls = true,\n  interactive = true,\n  fallback,\n  onMoveEnd,\n  onPress,\n  children,\n  labels: given,\n  className,\n}: MapProps) {\n  const labels = { ...mapLabels, ...given };\n  const s = map();\n  const pageScheme = usePageScheme();\n  const scheme = schemeProp ?? pageScheme;\n  const reduce = usePrefersReducedMotion();\n  const host = React.useRef<HTMLDivElement>(null);\n  const [instance, setInstance] = React.useState<MapInstance | null>(null);\n  const [lib, setLib] = React.useState<MapLibre | null>(null);\n  const [ready, setReady] = React.useState(false);\n  const [failed, setFailed] = React.useState(false);\n  const [places, setPlaces] = React.useState<Record<string, string>>({});\n  const registry = React.useMemo<Registry>(\n    () => ({\n      add: (id, text) => setPlaces((p) => (p[id] === text ? p : { ...p, [id]: text })),\n      remove: (id) =>\n        setPlaces((p) => {\n          const { [id]: _gone, ...rest } = p;\n          return rest;\n        }),\n    }),\n    [],\n  );\n  const latest = React.useRef({ onMoveEnd, onPress });\n  React.useEffect(() => {\n    latest.current = { onMoveEnd, onPress };\n  });\n  const styleOf = React.useCallback((sc: \"dark\" | \"light\") => mapStyle({ scheme: sc, brand, lang, ...(region !== undefined ? { region } : {}), ...(world !== undefined ? { world } : {}) }), [brand, lang, region, world]);\n\n  // The engine and the map, once (the style follows the scheme below).\n  React.useEffect(() => {\n    if (!host.current) return;\n    let alive = true;\n    let created: MapInstance | null = null;\n    (hasWebGL() ? loadEngine() : Promise.reject(new Error(\"no WebGL\")))\n      .then((ml) => {\n        if (!alive || !host.current) return;\n        created = new ml.Map({\n          container: host.current,\n          style: styleOf(scheme) as never,\n          center: [...center] as [number, number],\n          zoom,\n          interactive,\n          attributionControl: false,\n          fadeDuration: reduce ? 0 : 300,\n          cooperativeGestures: false,\n        });\n        created.getCanvas().setAttribute(\"aria-hidden\", \"true\");\n        created.getCanvas().setAttribute(\"tabindex\", \"-1\");\n        created.on(\"load\", () => alive && setReady(true));\n        // The basemap cannot be read (offline, a blocked request): the fallback comes back rather than an empty map.\n        created.on(\"error\", (e) => {\n          const source = (e as { sourceId?: string }).sourceId;\n          if (alive && (source === \"world\" || source === \"region\")) setFailed(true);\n        });\n        created.on(\"moveend\", () => {\n          const c = created!.getCenter();\n          latest.current.onMoveEnd?.({ center: [c.lng, c.lat], zoom: created!.getZoom() });\n        });\n        created.on(\"click\", (e) => {\n          if ((e.originalEvent.target as Element | null)?.closest?.(\"[data-kz-marker]\")) return;\n          latest.current.onPress?.([e.lngLat.lng, e.lngLat.lat]);\n        });\n        setLib(ml);\n        setInstance(created);\n      })\n      .catch(() => alive && setFailed(true));\n    return () => {\n      alive = false;\n      created?.remove();\n    };\n    // Created once: the props that change afterwards are followed by the effects below.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  // The scheme (and the brand, the language) change the style, not the map.\n  const first = React.useRef(true);\n  React.useEffect(() => {\n    if (!instance) return;\n    if (first.current) {\n      first.current = false;\n      return;\n    }\n    instance.setStyle(styleOf(scheme) as never);\n  }, [instance, scheme, styleOf]);\n\n  // A controlled camera: it flies (or jumps) to the new view.\n  React.useEffect(() => {\n    if (!instance || !controlled) return;\n    const view = { center: [...center] as [number, number], zoom };\n    if (reduce) instance.jumpTo(view);\n    else instance.flyTo({ ...view, speed: 1.4 });\n  }, [instance, controlled, center[0], center[1], zoom, reduce]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  const zoomBy = (by: number) => instance && (reduce ? instance.setZoom(instance.getZoom() + by) : instance.zoomTo(instance.getZoom() + by, { duration: 250 }));\n  const ctx = React.useMemo<Ctx>(() => ({ map: instance, lib, ready, reduce, places: registry }), [instance, lib, ready, reduce, registry]);\n  const listed = Object.entries(places);\n  return (\n    <MapContext.Provider value={ctx}>\n      <section\n        aria-label={label}\n        className={s.root({ className })}\n        data-ready={ready ? \"\" : undefined}\n        tabIndex={interactive ? 0 : undefined}\n        onKeyDown={(e) => {\n          if (e.target !== e.currentTarget || !instance) return;\n          if (e.key === \"+\" || e.key === \"=\") zoomBy(1);\n          else if (e.key === \"-\") zoomBy(-1);\n          else if (e.key.startsWith(\"Arrow\")) {\n            e.preventDefault();\n            const step = 80;\n            const by: Record<string, [number, number]> = { ArrowUp: [0, -step], ArrowDown: [0, step], ArrowLeft: [-step, 0], ArrowRight: [step, 0] };\n            instance.panBy(by[e.key]!, { duration: reduce ? 0 : 200 });\n          }\n        }}\n      >\n        {!ready || failed ? <div className={s.fallback()}>{fallback}</div> : null}\n        <div ref={host} className={s.canvas()} style={{ position: \"absolute\", inset: 0, visibility: failed ? \"hidden\" : undefined }} />\n        {controls && interactive && !failed ? (\n          <div className={s.controls()}>\n            <button type=\"button\" className={s.control()} aria-label={labels.zoomIn} disabled={!instance} onClick={() => zoomBy(1)}>\n              +\n            </button>\n            <button type=\"button\" className={s.control()} aria-label={labels.zoomOut} disabled={!instance} onClick={() => zoomBy(-1)}>\n              −\n            </button>\n          </div>\n        ) : null}\n        <p className={s.attribution()}>\n          <a href={MAP_ATTRIBUTION.protomapsUrl} target=\"_blank\" rel=\"noreferrer\">\n            {MAP_ATTRIBUTION.protomaps}\n          </a>\n          {\" · \"}\n          <a href={MAP_ATTRIBUTION.osmUrl} target=\"_blank\" rel=\"noreferrer\">\n            {MAP_ATTRIBUTION.osm}\n          </a>\n        </p>\n        {listed.length ? (\n          <div className={s.places()}>\n            <p>{labels.places}</p>\n            <ul>\n              {listed.map(([id, text]) => (\n                <li key={id}>{text}</li>\n              ))}\n            </ul>\n          </div>\n        ) : null}\n        {children}\n      </section>\n    </MapContext.Provider>\n  );\n}\n\nexport type MarkerProps = {\n  /** Where it stands. */\n  position: LngLat;\n  /** Its words: the place's name, read in the list of places and as the button's name (\"Café Olimpico, 350 m\"). */\n  label: string;\n  /** Pressing it (details in a panel, a sheet): the marker becomes a button. */\n  onPress?: () => void;\n  /** The chosen one: larger, its label shown above it. */\n  selected?: boolean;\n  /** Its size in pixels. Default 18. */\n  size?: number;\n  /** What it draws instead of the accent dot (an avatar, an icon). */\n  children?: React.ReactNode;\n};\n\n/** A place on the map: an accent dot (or your content) that is a button when it does something. */\nexport function Marker({ position, label, onPress, selected, size = 18, children }: MarkerProps) {\n  const { map: m, lib, places } = useMap();\n  const s = map();\n  const id = React.useId();\n  const [el] = React.useState(() => (typeof document === \"undefined\" ? null : document.createElement(\"div\")));\n  React.useEffect(() => {\n    places.add(id, label);\n    return () => places.remove(id);\n  }, [id, label, places]);\n  React.useEffect(() => {\n    if (!m || !lib || !el) return;\n    el.setAttribute(\"data-kz-marker\", \"\");\n    const marker = new lib.Marker({ element: el, anchor: \"center\" }).setLngLat([...position] as [number, number]).addTo(m);\n    return () => void marker.remove();\n  }, [m, lib, el, position[0], position[1]]); // eslint-disable-line react-hooks/exhaustive-deps\n  if (!el) return null;\n  const Tag = onPress ? \"button\" : \"span\";\n  return createPortal(\n    <Tag\n      type={onPress ? \"button\" : undefined}\n      aria-label={onPress ? label : undefined}\n      aria-hidden={onPress ? undefined : true}\n      aria-pressed={onPress && selected !== undefined ? selected : undefined}\n      data-selected={selected ? \"\" : undefined}\n      className={s.marker()}\n      style={children ? undefined : { width: size, height: size }}\n      onClick={onPress}\n    >\n      {children}\n      {selected ? <span className={s.markerLabel()}>{label}</span> : null}\n    </Tag>,\n    el,\n  );\n}\n\nexport type UserPositionProps = {\n  /** Where the person is. */\n  position: LngLat;\n  /** Its words (\"You are here\"), read in the list of places. */\n  label: string;\n  /** The accuracy in metres: a soft disc around the dot. */\n  accuracy?: number;\n};\n\n/** The person's position: a dot that pulses (still under reduced motion), its accuracy as a soft disc. */\nexport function UserPosition({ position, label, accuracy }: UserPositionProps) {\n  const { map: m, lib, places } = useMap();\n  const id = React.useId();\n  React.useEffect(() => {\n    places.add(id, label);\n    return () => places.remove(id);\n  }, [id, label, places]);\n  React.useEffect(() => {\n    if (!m || !lib) return;\n    const el = document.createElement(\"div\");\n    el.className = \"kz-map-user\";\n    el.setAttribute(\"aria-hidden\", \"true\");\n    const marker = new lib.Marker({ element: el, anchor: \"center\" }).setLngLat([...position] as [number, number]).addTo(m);\n    return () => void marker.remove();\n  }, [m, lib, position[0], position[1]]); // eslint-disable-line react-hooks/exhaustive-deps\n  return accuracy ? <RadiusCircle center={position} radius={accuracy} tone=\"soft\" /> : null;\n}\n\n/** Adds a GeoJSON source and its layers while the map has a style (again after a change of scheme). */\nfunction useGeoLayer(id: string, data: GeoJSON.GeoJSON, layers: (palette: ReturnType<typeof mapPalette>) => object[], source: object = {}) {\n  const { map: m, ready } = useMap();\n  const dataRef = React.useRef(data);\n  React.useEffect(() => {\n    dataRef.current = data;\n    const src = m?.getSource(id) as { setData?: (d: GeoJSON.GeoJSON) => void } | undefined;\n    src?.setData?.(data);\n  }, [m, id, data]);\n  React.useEffect(() => {\n    if (!m || !ready) return;\n    const add = () => {\n      if (m.getSource(id)) return;\n      const scheme = document.documentElement.classList.contains(\"light\") ? \"light\" : \"dark\";\n      m.addSource(id, { type: \"geojson\", data: dataRef.current, ...source } as never);\n      for (const layer of layers(mapPalette(scheme))) m.addLayer(layer as never);\n    };\n    add();\n    m.on(\"styledata\", add);\n    return () => {\n      m.off(\"styledata\", add);\n      if (!m.getStyle()) return;\n      for (const layer of m.getStyle().layers.filter((l) => \"source\" in l && l.source === id)) m.removeLayer(layer.id);\n      if (m.getSource(id)) m.removeSource(id);\n    };\n  }, [m, ready, id]); // eslint-disable-line react-hooks/exhaustive-deps\n}\n\nexport type RadiusCircleProps = {\n  /** Its centre. */\n  center: LngLat;\n  /** Its radius in metres. */\n  radius: number;\n  /** `accent` (a zone that matters: a delivery area, a search radius) or `soft` (an accuracy). */\n  tone?: \"accent\" | \"soft\";\n};\n\n/** A circle on the ground: a delivery zone, a search radius — filled with the accent, its edge drawn. */\nexport function RadiusCircle({ center, radius, tone = \"accent\" }: RadiusCircleProps) {\n  const id = `kz-circle-${React.useId().replace(/[^a-zA-Z0-9]/g, \"\")}`;\n  const data = React.useMemo(() => circlePolygon(center, radius), [center[0], center[1], radius]); // eslint-disable-line react-hooks/exhaustive-deps\n  useGeoLayer(id, data, (c) => [\n    { id: `${id}-fill`, type: \"fill\", source: id, paint: { \"fill-color\": c.accent, \"fill-opacity\": tone === \"soft\" ? 0.1 : 0.14 } },\n    { id: `${id}-line`, type: \"line\", source: id, paint: { \"line-color\": c.accent, \"line-width\": tone === \"soft\" ? 1 : 2, \"line-opacity\": tone === \"soft\" ? 0.4 : 0.9, ...(tone === \"accent\" ? { \"line-dasharray\": [2, 1.5] } : {}) } },\n  ]);\n  return null;\n}\n\nexport type ClusterPoint = { id: string; position: LngLat; label: string };\n\nexport type ClusterProps = {\n  /** The points: many of them (creators, pick-up points, events). */\n  points: readonly ClusterPoint[];\n  /** Pressing a single point. A group zooms in to open itself. */\n  onPointPress?: (point: ClusterPoint) => void;\n  /** The radius, in pixels, within which points group. Default 48. */\n  radius?: number;\n};\n\n/** Many points grouped while they are close: a disc with the count, opened by zooming in; each point is listed for screen readers. */\nexport function Cluster({ points, onPointPress, radius = 48 }: ClusterProps) {\n  const { map: m, ready, reduce, places } = useMap();\n  const id = `kz-cluster-${React.useId().replace(/[^a-zA-Z0-9]/g, \"\")}`;\n  const data = React.useMemo<GeoJSON.FeatureCollection>(\n    () => ({ type: \"FeatureCollection\", features: points.map((p) => ({ type: \"Feature\", properties: { id: p.id, label: p.label }, geometry: { type: \"Point\", coordinates: [...p.position] } })) }),\n    [points],\n  );\n  React.useEffect(() => {\n    for (const p of points) places.add(`${id}-${p.id}`, p.label);\n    return () => points.forEach((p) => places.remove(`${id}-${p.id}`));\n  }, [points, places, id]);\n  useGeoLayer(\n    id,\n    data,\n    (c) => [\n      { id: `${id}-groups`, type: \"circle\", source: id, filter: [\"has\", \"point_count\"], paint: { \"circle-color\": c.accent, \"circle-opacity\": 0.92, \"circle-radius\": [\"step\", [\"get\", \"point_count\"], 16, 10, 20, 50, 26], \"circle-stroke-width\": 3, \"circle-stroke-color\": c.halo } },\n      { id: `${id}-count`, type: \"symbol\", source: id, filter: [\"has\", \"point_count\"], layout: { \"text-field\": [\"get\", \"point_count_abbreviated\"], \"text-font\": [\"Noto Sans Medium\"], \"text-size\": 13 }, paint: { \"text-color\": c.onAccent } },\n      { id: `${id}-points`, type: \"circle\", source: id, filter: [\"!\", [\"has\", \"point_count\"]], paint: { \"circle-color\": c.accent, \"circle-radius\": 7, \"circle-stroke-width\": 2.5, \"circle-stroke-color\": c.halo } },\n    ],\n    { cluster: true, clusterRadius: radius, clusterMaxZoom: 15 },\n  );\n  React.useEffect(() => {\n    if (!m || !ready) return;\n    const openGroup = async (e: { features?: { properties: Record<string, unknown>; geometry: GeoJSON.Geometry }[] }) => {\n      const f = e.features?.[0];\n      if (!f) return;\n      const src = m.getSource(id) as unknown as { getClusterExpansionZoom: (id: number) => Promise<number> };\n      const z = await src.getClusterExpansionZoom(f.properties.cluster_id as number);\n      const center = (f.geometry as GeoJSON.Point).coordinates as [number, number];\n      if (reduce) m.jumpTo({ center, zoom: z });\n      else m.easeTo({ center, zoom: z });\n    };\n    const pressPoint = (e: { features?: { properties: Record<string, unknown> }[] }) => {\n      const pid = e.features?.[0]?.properties.id;\n      const point = points.find((p) => p.id === pid);\n      if (point) onPointPress?.(point);\n    };\n    m.on(\"click\", `${id}-groups`, openGroup as never);\n    m.on(\"click\", `${id}-points`, pressPoint as never);\n    return () => {\n      m.off(\"click\", `${id}-groups`, openGroup as never);\n      m.off(\"click\", `${id}-points`, pressPoint as never);\n    };\n  }, [m, ready, id, points, onPointPress, reduce]);\n  return null;\n}\n"
+      "content": "// Client. A map of the Krizaka family on MapLibre GL JS (open source) over Protomaps tiles on our CDN — no API key, no\n// metered service. MapLibre and PMTiles are optional peers, loaded when a map is shown (a dynamic import: a page without\n// a map never pays for them). The style comes from the tokens (`mapStyle`), in the page's scheme, and follows it.\n//\n// What every map does: the canvas is decorative for assistive technologies — the map is a region named by `label`, its\n// places a list read in order (the text alternative, `MapPlaces`), each marker a button when it does something; the\n// attribution of OpenStreetMap (ODbL) and Protomaps is always shown; under reduced motion the camera jumps, never flies;\n// without WebGL (or while the engine loads) `fallback` stands in its place.\n/// <reference types=\"geojson\" />\nimport * as React from \"react\";\nimport { createPortal } from \"react-dom\";\n\nimport { usePrefersReducedMotion } from \"../media\";\nimport { tv } from \"../tv\";\nimport { MAP_ATTRIBUTION, setMapAssetsBase } from \"./assets\";\nimport { circlePolygon, type LngLat } from \"./geo\";\nimport { type MapBrand, mapPalette, type MapRegion, mapStyle } from \"./style\";\n\ntype MapLibre = typeof import(\"maplibre-gl\");\ntype MapInstance = import(\"maplibre-gl\").Map;\n\nexport const map = tv({\n  slots: {\n    root: \"relative isolate overflow-hidden rounded-2xl border border-border-default bg-surface-2 shadow-raised\",\n    canvas: \"absolute inset-0 [&_.maplibregl-canvas]:outline-hidden\",\n    fallback: \"absolute inset-0\",\n    controls: \"absolute right-3 top-3 z-10 flex flex-col overflow-hidden rounded-xl border border-border-default bg-surface-1 shadow-floating\",\n    control:\n      \"inline-flex h-10 w-10 items-center justify-center text-lg font-semibold text-fg-secondary transition-colors hover:bg-surface-3 hover:text-fg \" +\n      \"focus-visible:outline-hidden focus-visible:focus-ring-inset disabled:opacity-40 [&+&]:border-t [&+&]:border-border-subtle\",\n    attribution:\n      \"absolute bottom-1.5 right-1.5 z-10 rounded-md bg-surface-1/85 px-1.5 py-0.5 text-[10px] text-fg-secondary backdrop-blur-sm [&_a]:underline-offset-2 hover:[&_a]:underline\",\n    places: \"sr-only\",\n    marker:\n      \"group relative flex -translate-y-1/2 cursor-pointer items-center justify-center rounded-full border-2 border-on-accent bg-accent shadow-floating outline-hidden \" +\n      \"transition-transform hover:scale-110 focus-visible:focus-ring motion-reduce:transition-none motion-reduce:hover:scale-100 data-[selected]:scale-125\",\n    markerLabel:\n      \"pointer-events-none absolute bottom-full mb-2 whitespace-nowrap rounded-lg border border-border-default bg-surface-1 px-2 py-1 text-xs font-semibold text-fg shadow-floating\",\n  },\n});\n\ntype Registry = { add: (id: string, text: string) => void; remove: (id: string) => void };\ntype Ctx = { map: MapInstance | null; lib: MapLibre | null; ready: boolean; reduce: boolean; places: Registry };\nconst MapContext = React.createContext<Ctx | null>(null);\n\n/** The map a child is drawn on (`Marker`, `RadiusCircle`, `Cluster`…): the MapLibre instance once it is ready. */\nexport function useMap(): Ctx {\n  const ctx = React.useContext(MapContext);\n  if (!ctx) throw new Error(\"useMap: inside a <Map> only\");\n  return ctx;\n}\n\n/** The scheme of the page (`html.light`), followed as it changes. */\nfunction usePageScheme(): \"dark\" | \"light\" {\n  const read = () => (typeof document !== \"undefined\" && document.documentElement.classList.contains(\"light\") ? \"light\" : \"dark\");\n  const [scheme, setScheme] = React.useState<\"dark\" | \"light\">(read);\n  React.useEffect(() => {\n    const observer = new MutationObserver(() => setScheme(read()));\n    observer.observe(document.documentElement, { attributes: true, attributeFilter: [\"class\"] });\n    return () => observer.disconnect();\n  }, []);\n  return scheme;\n}\n\nlet protocolAdded = false;\nlet workerUrl: string | null = null;\n\n/**\n * Where MapLibre's worker comes from. A bundler (Next.js, Vite) renames MapLibre's module and leaves its worker behind:\n * by default the worker of the very version the app installed is imported from jsDelivr (free, open source, no key)\n * through a module worker of the page's own origin. An app with a strict CSP serves it itself —\n * `configureMaps({ workerUrl: \"/maplibre-gl-worker.mjs\" })` (with `maplibre-gl-shared.mjs` beside it), once, before a map.\n * `assetsBase` reads the tiles and glyphs through a same-origin proxy of the CDN (`setMapAssetsBase`).\n */\nexport function configureMaps(options: { workerUrl?: string; assetsBase?: string }) {\n  if (options.workerUrl) workerUrl = options.workerUrl;\n  if (options.assetsBase) setMapAssetsBase(options.assetsBase);\n}\n\n/** MapLibre, its worker and the PMTiles protocol, loaded once for the page. */\nasync function loadEngine(): Promise<MapLibre> {\n  const [lib, pmtiles] = await Promise.all([import(\"maplibre-gl\"), import(\"pmtiles\")]);\n  const ml = ((lib as unknown as { default?: MapLibre }).default ?? lib) as MapLibre;\n  if (!protocolAdded) {\n    protocolAdded = true;\n    const remote = `https://cdn.jsdelivr.net/npm/maplibre-gl@${ml.getVersion()}/dist/maplibre-gl-worker.mjs`;\n    ml.setWorkerUrl(workerUrl ?? URL.createObjectURL(new Blob([`import ${JSON.stringify(remote)};`], { type: \"text/javascript\" })));\n    ml.addProtocol(\"pmtiles\", new pmtiles.Protocol().tile);\n  }\n  return ml;\n}\n\nconst hasWebGL = () => {\n  try {\n    const canvas = document.createElement(\"canvas\");\n    return Boolean(canvas.getContext(\"webgl2\") ?? canvas.getContext(\"webgl\"));\n  } catch {\n    return false;\n  }\n};\n\nexport type MapLabels = {\n  /** The zoom-in button (\"Zoom in\"). */\n  zoomIn: string;\n  /** The zoom-out button (\"Zoom out\"). */\n  zoomOut: string;\n  /** Before the list of places read in place of the map (\"Places on the map\"). */\n  places: string;\n};\n\nexport const mapLabels: MapLabels = { zoomIn: \"Zoom in\", zoomOut: \"Zoom out\", places: \"Places on the map\" };\n\nexport type MapProps = {\n  /** The map's accessible name (\"Pick-up points near you\"), passed translated. */\n  label: string;\n  /** Where the map looks at first: longitude, latitude. */\n  center: LngLat;\n  /** The zoom at first (0 the world, 12 a city, 16 a street). Default 12. */\n  zoom?: number;\n  /** The camera follows `center` and `zoom` when they change (flies, or jumps under reduced motion). */\n  controlled?: boolean;\n  /** The scheme. Default: the page's (`html.light`), followed. */\n  scheme?: \"dark\" | \"light\";\n  /** The product whose accent the map carries. Default `krizaka`. */\n  brand?: MapBrand;\n  /** The language of the labels (`fr`, `en`). Default `en`. */\n  lang?: string;\n  /** The detailed region (PMTiles) drawn from zoom 6.5. Default: our Montréal–Québec extract (to zoom 14). */\n  region?: MapRegion | null;\n  /** The world's low zooms (PMTiles). Default: our world extract (to zoom 6). */\n  world?: MapRegion | null;\n  /** The zoom buttons (default) — the keyboard also zooms with + and − on the focused map. */\n  controls?: boolean;\n  /** Moves with the hand (default); `false` makes a still picture of a place. */\n  interactive?: boolean;\n  /** Shown in place of the map while its engine loads, and for good without WebGL: a `StaticMap`, a picture. */\n  fallback?: React.ReactNode;\n  /** Called when the camera rests: its centre and zoom. */\n  onMoveEnd?: (view: { center: LngLat; zoom: number }) => void;\n  /** Called with the position pressed on the map (not on a marker). */\n  onPress?: (position: LngLat) => void;\n  /** Markers, circles, clusters, the user's position — and anything drawn over the map. */\n  children?: React.ReactNode;\n  /** The words, passed translated; English by default. */\n  labels?: Partial<MapLabels>;\n  /** Classes merged on the root (its height: `h-80`, `aspect-video`). */\n  className?: string;\n};\n\n/** A map: MapLibre over our Protomaps tiles, styled from the tokens, with its places as a list for screen readers. */\nexport function Map({\n  label,\n  center,\n  zoom = 12,\n  controlled,\n  scheme: schemeProp,\n  brand,\n  lang,\n  region,\n  world,\n  controls = true,\n  interactive = true,\n  fallback,\n  onMoveEnd,\n  onPress,\n  children,\n  labels: given,\n  className,\n}: MapProps) {\n  const labels = { ...mapLabels, ...given };\n  const s = map();\n  const pageScheme = usePageScheme();\n  const scheme = schemeProp ?? pageScheme;\n  const reduce = usePrefersReducedMotion();\n  const host = React.useRef<HTMLDivElement>(null);\n  const [instance, setInstance] = React.useState<MapInstance | null>(null);\n  const [lib, setLib] = React.useState<MapLibre | null>(null);\n  const [ready, setReady] = React.useState(false);\n  const [failed, setFailed] = React.useState(false);\n  const [places, setPlaces] = React.useState<Record<string, string>>({});\n  const registry = React.useMemo<Registry>(\n    () => ({\n      add: (id, text) => setPlaces((p) => (p[id] === text ? p : { ...p, [id]: text })),\n      remove: (id) =>\n        setPlaces((p) => {\n          const { [id]: _gone, ...rest } = p;\n          return rest;\n        }),\n    }),\n    [],\n  );\n  const latest = React.useRef({ onMoveEnd, onPress });\n  React.useEffect(() => {\n    latest.current = { onMoveEnd, onPress };\n  });\n  const styleOf = React.useCallback((sc: \"dark\" | \"light\") => mapStyle({ scheme: sc, brand, lang, ...(region !== undefined ? { region } : {}), ...(world !== undefined ? { world } : {}) }), [brand, lang, region, world]);\n\n  // The engine and the map, once (the style follows the scheme below).\n  React.useEffect(() => {\n    if (!host.current) return;\n    let alive = true;\n    let created: MapInstance | null = null;\n    (hasWebGL() ? loadEngine() : Promise.reject(new Error(\"no WebGL\")))\n      .then((ml) => {\n        if (!alive || !host.current) return;\n        created = new ml.Map({\n          container: host.current,\n          style: styleOf(scheme) as never,\n          center: [...center] as [number, number],\n          zoom,\n          interactive,\n          attributionControl: false,\n          fadeDuration: reduce ? 0 : 300,\n          cooperativeGestures: false,\n        });\n        created.getCanvas().setAttribute(\"aria-hidden\", \"true\");\n        created.getCanvas().setAttribute(\"tabindex\", \"-1\");\n        created.on(\"load\", () => alive && setReady(true));\n        // The basemap cannot be read (offline, a blocked request): the fallback comes back rather than an empty map.\n        created.on(\"error\", (e) => {\n          const source = (e as { sourceId?: string }).sourceId;\n          if (alive && (source === \"world\" || source === \"region\")) setFailed(true);\n        });\n        created.on(\"moveend\", () => {\n          const c = created!.getCenter();\n          latest.current.onMoveEnd?.({ center: [c.lng, c.lat], zoom: created!.getZoom() });\n        });\n        created.on(\"click\", (e) => {\n          if ((e.originalEvent.target as Element | null)?.closest?.(\"[data-kz-marker]\")) return;\n          latest.current.onPress?.([e.lngLat.lng, e.lngLat.lat]);\n        });\n        setLib(ml);\n        setInstance(created);\n      })\n      .catch(() => alive && setFailed(true));\n    return () => {\n      alive = false;\n      created?.remove();\n    };\n    // Created once: the props that change afterwards are followed by the effects below.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  // The scheme (and the brand, the language) change the style, not the map.\n  const first = React.useRef(true);\n  React.useEffect(() => {\n    if (!instance) return;\n    if (first.current) {\n      first.current = false;\n      return;\n    }\n    instance.setStyle(styleOf(scheme) as never);\n  }, [instance, scheme, styleOf]);\n\n  // A controlled camera: it flies (or jumps) to the new view.\n  React.useEffect(() => {\n    if (!instance || !controlled) return;\n    const view = { center: [...center] as [number, number], zoom };\n    if (reduce) instance.jumpTo(view);\n    else instance.flyTo({ ...view, speed: 1.4 });\n  }, [instance, controlled, center[0], center[1], zoom, reduce]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  const zoomBy = (by: number) => instance && (reduce ? instance.setZoom(instance.getZoom() + by) : instance.zoomTo(instance.getZoom() + by, { duration: 250 }));\n  const ctx = React.useMemo<Ctx>(() => ({ map: instance, lib, ready, reduce, places: registry }), [instance, lib, ready, reduce, registry]);\n  const listed = Object.entries(places);\n  return (\n    <MapContext.Provider value={ctx}>\n      <section\n        aria-label={label}\n        className={s.root({ className })}\n        data-ready={ready ? \"\" : undefined}\n        tabIndex={interactive ? 0 : undefined}\n        onKeyDown={(e) => {\n          if (e.target !== e.currentTarget || !instance) return;\n          if (e.key === \"+\" || e.key === \"=\") zoomBy(1);\n          else if (e.key === \"-\") zoomBy(-1);\n          else if (e.key.startsWith(\"Arrow\")) {\n            e.preventDefault();\n            const step = 80;\n            const by: Record<string, [number, number]> = { ArrowUp: [0, -step], ArrowDown: [0, step], ArrowLeft: [-step, 0], ArrowRight: [step, 0] };\n            instance.panBy(by[e.key]!, { duration: reduce ? 0 : 200 });\n          }\n        }}\n      >\n        {!ready || failed ? <div className={s.fallback()}>{fallback}</div> : null}\n        <div ref={host} className={s.canvas()} style={{ position: \"absolute\", inset: 0, visibility: failed ? \"hidden\" : undefined }} />\n        {controls && interactive && !failed ? (\n          <div className={s.controls()}>\n            <button type=\"button\" className={s.control()} aria-label={labels.zoomIn} disabled={!instance} onClick={() => zoomBy(1)}>\n              +\n            </button>\n            <button type=\"button\" className={s.control()} aria-label={labels.zoomOut} disabled={!instance} onClick={() => zoomBy(-1)}>\n              −\n            </button>\n          </div>\n        ) : null}\n        <p className={s.attribution()}>\n          <a href={MAP_ATTRIBUTION.protomapsUrl} target=\"_blank\" rel=\"noreferrer\">\n            {MAP_ATTRIBUTION.protomaps}\n          </a>\n          {\" · \"}\n          <a href={MAP_ATTRIBUTION.osmUrl} target=\"_blank\" rel=\"noreferrer\">\n            {MAP_ATTRIBUTION.osm}\n          </a>\n        </p>\n        {listed.length ? (\n          <div className={s.places()}>\n            <p>{labels.places}</p>\n            <ul>\n              {listed.map(([id, text]) => (\n                <li key={id}>{text}</li>\n              ))}\n            </ul>\n          </div>\n        ) : null}\n        {children}\n      </section>\n    </MapContext.Provider>\n  );\n}\n\nexport type MarkerProps = {\n  /** Where it stands. */\n  position: LngLat;\n  /** Its words: the place's name, read in the list of places and as the button's name (\"Café Olimpico, 350 m\"). */\n  label: string;\n  /** Pressing it (details in a panel, a sheet): the marker becomes a button. */\n  onPress?: () => void;\n  /** The chosen one: larger, its label shown above it. */\n  selected?: boolean;\n  /** Its size in pixels. Default 18. */\n  size?: number;\n  /** What it draws instead of the accent dot (an avatar, an icon). */\n  children?: React.ReactNode;\n};\n\nconst noSubscription = () => () => undefined;\n\n/** A place on the map: an accent dot (or your content) that is a button when it does something. */\nexport function Marker({ position, label, onPress, selected, size = 18, children }: MarkerProps) {\n  const { map: m, lib, places } = useMap();\n  const s = map();\n  const id = React.useId();\n  // The marker's host element exists only in a browser: the server and the hydration pass render nothing for it, then the\n  // client swaps in the element — `useSyncExternalStore`'s server snapshot, so hydration never sees a difference.\n  const host = React.useRef<HTMLElement | null>(null);\n  const el = React.useSyncExternalStore(\n    noSubscription,\n    () => (host.current ??= document.createElement(\"div\")),\n    () => null,\n  );\n  React.useEffect(() => {\n    places.add(id, label);\n    return () => places.remove(id);\n  }, [id, label, places]);\n  React.useEffect(() => {\n    if (!m || !lib || !el) return;\n    el.setAttribute(\"data-kz-marker\", \"\");\n    const marker = new lib.Marker({ element: el, anchor: \"center\" }).setLngLat([...position] as [number, number]).addTo(m);\n    return () => void marker.remove();\n  }, [m, lib, el, position[0], position[1]]); // eslint-disable-line react-hooks/exhaustive-deps\n  if (!el) return null;\n  const Tag = onPress ? \"button\" : \"span\";\n  return createPortal(\n    <Tag\n      type={onPress ? \"button\" : undefined}\n      aria-label={onPress ? label : undefined}\n      aria-hidden={onPress ? undefined : true}\n      aria-pressed={onPress && selected !== undefined ? selected : undefined}\n      data-selected={selected ? \"\" : undefined}\n      className={s.marker()}\n      style={children ? undefined : { width: size, height: size }}\n      onClick={onPress}\n    >\n      {children}\n      {selected ? <span className={s.markerLabel()}>{label}</span> : null}\n    </Tag>,\n    el,\n  );\n}\n\nexport type UserPositionProps = {\n  /** Where the person is. */\n  position: LngLat;\n  /** Its words (\"You are here\"), read in the list of places. */\n  label: string;\n  /** The accuracy in metres: a soft disc around the dot. */\n  accuracy?: number;\n};\n\n/** The person's position: a dot that pulses (still under reduced motion), its accuracy as a soft disc. */\nexport function UserPosition({ position, label, accuracy }: UserPositionProps) {\n  const { map: m, lib, places } = useMap();\n  const id = React.useId();\n  React.useEffect(() => {\n    places.add(id, label);\n    return () => places.remove(id);\n  }, [id, label, places]);\n  React.useEffect(() => {\n    if (!m || !lib) return;\n    const el = document.createElement(\"div\");\n    el.className = \"kz-map-user\";\n    el.setAttribute(\"aria-hidden\", \"true\");\n    const marker = new lib.Marker({ element: el, anchor: \"center\" }).setLngLat([...position] as [number, number]).addTo(m);\n    return () => void marker.remove();\n  }, [m, lib, position[0], position[1]]); // eslint-disable-line react-hooks/exhaustive-deps\n  return accuracy ? <RadiusCircle center={position} radius={accuracy} tone=\"soft\" /> : null;\n}\n\n/** Adds a GeoJSON source and its layers while the map has a style (again after a change of scheme). */\nfunction useGeoLayer(id: string, data: GeoJSON.GeoJSON, layers: (palette: ReturnType<typeof mapPalette>) => object[], source: object = {}) {\n  const { map: m, ready } = useMap();\n  const dataRef = React.useRef(data);\n  React.useEffect(() => {\n    dataRef.current = data;\n    const src = m?.getSource(id) as { setData?: (d: GeoJSON.GeoJSON) => void } | undefined;\n    src?.setData?.(data);\n  }, [m, id, data]);\n  React.useEffect(() => {\n    if (!m || !ready) return;\n    const add = () => {\n      if (m.getSource(id)) return;\n      const scheme = document.documentElement.classList.contains(\"light\") ? \"light\" : \"dark\";\n      m.addSource(id, { type: \"geojson\", data: dataRef.current, ...source } as never);\n      for (const layer of layers(mapPalette(scheme))) m.addLayer(layer as never);\n    };\n    add();\n    m.on(\"styledata\", add);\n    return () => {\n      m.off(\"styledata\", add);\n      if (!m.getStyle()) return;\n      for (const layer of m.getStyle().layers.filter((l) => \"source\" in l && l.source === id)) m.removeLayer(layer.id);\n      if (m.getSource(id)) m.removeSource(id);\n    };\n  }, [m, ready, id]); // eslint-disable-line react-hooks/exhaustive-deps\n}\n\nexport type RadiusCircleProps = {\n  /** Its centre. */\n  center: LngLat;\n  /** Its radius in metres. */\n  radius: number;\n  /** `accent` (a zone that matters: a delivery area, a search radius) or `soft` (an accuracy). */\n  tone?: \"accent\" | \"soft\";\n};\n\n/** A circle on the ground: a delivery zone, a search radius — filled with the accent, its edge drawn. */\nexport function RadiusCircle({ center, radius, tone = \"accent\" }: RadiusCircleProps) {\n  const id = `kz-circle-${React.useId().replace(/[^a-zA-Z0-9]/g, \"\")}`;\n  const data = React.useMemo(() => circlePolygon(center, radius), [center[0], center[1], radius]); // eslint-disable-line react-hooks/exhaustive-deps\n  useGeoLayer(id, data, (c) => [\n    { id: `${id}-fill`, type: \"fill\", source: id, paint: { \"fill-color\": c.accent, \"fill-opacity\": tone === \"soft\" ? 0.1 : 0.14 } },\n    { id: `${id}-line`, type: \"line\", source: id, paint: { \"line-color\": c.accent, \"line-width\": tone === \"soft\" ? 1 : 2, \"line-opacity\": tone === \"soft\" ? 0.4 : 0.9, ...(tone === \"accent\" ? { \"line-dasharray\": [2, 1.5] } : {}) } },\n  ]);\n  return null;\n}\n\nexport type ClusterPoint = { id: string; position: LngLat; label: string };\n\nexport type ClusterProps = {\n  /** The points: many of them (creators, pick-up points, events). */\n  points: readonly ClusterPoint[];\n  /** Pressing a single point. A group zooms in to open itself. */\n  onPointPress?: (point: ClusterPoint) => void;\n  /** The radius, in pixels, within which points group. Default 48. */\n  radius?: number;\n};\n\n/** Many points grouped while they are close: a disc with the count, opened by zooming in; each point is listed for screen readers. */\nexport function Cluster({ points, onPointPress, radius = 48 }: ClusterProps) {\n  const { map: m, ready, reduce, places } = useMap();\n  const id = `kz-cluster-${React.useId().replace(/[^a-zA-Z0-9]/g, \"\")}`;\n  const data = React.useMemo<GeoJSON.FeatureCollection>(\n    () => ({ type: \"FeatureCollection\", features: points.map((p) => ({ type: \"Feature\", properties: { id: p.id, label: p.label }, geometry: { type: \"Point\", coordinates: [...p.position] } })) }),\n    [points],\n  );\n  React.useEffect(() => {\n    for (const p of points) places.add(`${id}-${p.id}`, p.label);\n    return () => points.forEach((p) => places.remove(`${id}-${p.id}`));\n  }, [points, places, id]);\n  useGeoLayer(\n    id,\n    data,\n    (c) => [\n      { id: `${id}-groups`, type: \"circle\", source: id, filter: [\"has\", \"point_count\"], paint: { \"circle-color\": c.accent, \"circle-opacity\": 0.92, \"circle-radius\": [\"step\", [\"get\", \"point_count\"], 16, 10, 20, 50, 26], \"circle-stroke-width\": 3, \"circle-stroke-color\": c.halo } },\n      { id: `${id}-count`, type: \"symbol\", source: id, filter: [\"has\", \"point_count\"], layout: { \"text-field\": [\"get\", \"point_count_abbreviated\"], \"text-font\": [\"Noto Sans Medium\"], \"text-size\": 13 }, paint: { \"text-color\": c.onAccent } },\n      { id: `${id}-points`, type: \"circle\", source: id, filter: [\"!\", [\"has\", \"point_count\"]], paint: { \"circle-color\": c.accent, \"circle-radius\": 7, \"circle-stroke-width\": 2.5, \"circle-stroke-color\": c.halo } },\n    ],\n    { cluster: true, clusterRadius: radius, clusterMaxZoom: 15 },\n  );\n  React.useEffect(() => {\n    if (!m || !ready) return;\n    const openGroup = async (e: { features?: { properties: Record<string, unknown>; geometry: GeoJSON.Geometry }[] }) => {\n      const f = e.features?.[0];\n      if (!f) return;\n      const src = m.getSource(id) as unknown as { getClusterExpansionZoom: (id: number) => Promise<number> };\n      const z = await src.getClusterExpansionZoom(f.properties.cluster_id as number);\n      const center = (f.geometry as GeoJSON.Point).coordinates as [number, number];\n      if (reduce) m.jumpTo({ center, zoom: z });\n      else m.easeTo({ center, zoom: z });\n    };\n    const pressPoint = (e: { features?: { properties: Record<string, unknown> }[] }) => {\n      const pid = e.features?.[0]?.properties.id;\n      const point = points.find((p) => p.id === pid);\n      if (point) onPointPress?.(point);\n    };\n    m.on(\"click\", `${id}-groups`, openGroup as never);\n    m.on(\"click\", `${id}-points`, pressPoint as never);\n    return () => {\n      m.off(\"click\", `${id}-groups`, openGroup as never);\n      m.off(\"click\", `${id}-points`, pressPoint as never);\n    };\n  }, [m, ready, id, points, onPointPress, reduce]);\n  return null;\n}\n"
     },
     {
       "path": "map/meta.ts",
@@ -921,7 +922,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 krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\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  | \"verified-badge\"\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 * `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 krizaka.com/docs/ui/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  /** 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"
     },
     {
       "path": "tv.ts",
@@ -929,7 +930,7 @@
     }
   ],
   "dependencies": [
-    "@krizaka/tokens@^3.4.0",
+    "@krizaka/tokens@^3.6.0",
     "@protomaps/basemaps@5.7.2",
     "tailwind-variants@^3.3.1"
   ],

package/registry/marketing-layout.json

@@ -5,6 +5,7 @@
   "summary": "A site's page: the link that skips to the content, the floating bar, the page made of a PageHero and Sections in one frame, the footer.",
   "description": "A site's page: the link that skips to the content, the floating bar, the page made of a PageHero and Sections in one frame, the footer.",
   "status": "beta",
+  "deprecated": null,
   "category": "layouts",
   "platforms": "web",
   "whenToUse": [
@@ -81,6 +82,8 @@
         "title": "A product page",
         "description": "Orazaka's page: hero with facts, reasons, decisions, the owl's promise, the closing call.",
         "template": true,
+        "purpose": "convince",
+        "why": "A visitor decides whether a product is for them: the promise first, the proof and the call after.",
         "path": "examples/marketing-layout/product-page.tsx",
         "module": "@krizaka/ui/registry/examples/marketing-layout/product-page",
         "code": "import { ProductLogo } from \"@krizaka/ui\";\nimport { ActionBar } from \"@krizaka/ui/action-bar\";\nimport { ArgumentCard } from \"@krizaka/ui/argument-card\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { CardGrid } from \"@krizaka/ui/card-grid\";\nimport { CtaPanel } from \"@krizaka/ui/cta-panel\";\nimport { DecisionList } from \"@krizaka/ui/decision-list\";\nimport { MarketingLayout } from \"@krizaka/ui/marketing-layout\";\nimport { MascotQuote } from \"@krizaka/ui/mascot-quote\";\nimport { Mascot } from \"@krizaka/ui/mascots\";\nimport { NavBar } from \"@krizaka/ui/nav-bar\";\nimport { Facts, Section } from \"@krizaka/ui/page\";\nimport { PageHero } from \"@krizaka/ui/page-hero\";\n\nconst WHY = [\n  { id: \"local\", title: \"Local inference\", hook: \"Elsewhere, every prompt crosses the ocean.\", bird: \"falcon\" as const },\n  { id: \"paid\", title: \"Paid once\", hook: \"Elsewhere, you pay per token, forever.\", bird: \"flamingo\" as const },\n  { id: \"asked\", title: \"Agents that ask\", hook: \"Elsewhere, an agent acts first and apologises later.\", bird: \"pigeon\" as const },\n];\nconst DECISIONS = [\n  { id: \"local\", chose: \"Local models by default.\", refused: \"A hosted API as the default path.\", because: \"A prompt that never leaves cannot leak.\", cost: \"You need a GPU, or patience on a CPU.\" },\n  { id: \"telemetry\", chose: \"Zero telemetry.\", refused: \"Anonymous usage statistics.\", because: \"Anonymous rarely stays anonymous.\", cost: \"You tell us what breaks.\" },\n];\nconst labels = { chose: \"We chose\", refused: \"We refused\", because: \"Because\", cost: \"What it costs you\" };\n\n// TEMPLATE — a product page (Orazaka): the hero with its facts and its main action (cut, shimmer), the reasons as compact\n// argument cards (the bird in the corner), the decisions with their cost, the owl's promise, the closing call. On a\n// phone the hero's bird goes above the title, the cards stack, the decisions' three parts stack under the choice.\nexport default function MarketingLayoutProductPage() {\n  return (\n    <div className=\"brand-orazaka\">\n      <MarketingLayout\n        skipLabel=\"Skip to content\"\n        header={\n          <NavBar.Root label=\"Main\" compactAfter={false} className=\"max-w-(--kz-page-max,72rem)\">\n            <NavBar.Brand href=\"#home\"><ProductLogo id=\"orazaka\" size={22} animated={false} /> Orazaka</NavBar.Brand>\n            <NavBar.Items>\n              <NavBar.Link href=\"#why\" active>Why</NavBar.Link>\n              <NavBar.Link href=\"#decisions\">Decisions</NavBar.Link>\n            </NavBar.Items>\n          </NavBar.Root>\n        }\n      >\n        <PageHero\n          eyebrow=\"Sovereign AI · open source\"\n          title=\"The AI that never leaves home\"\n          lead=\"Chat, image, voice and video on your own server — one governed pipeline, nothing sent anywhere.\"\n          aside={<Mascot bird=\"owl\" mood=\"welcome\" size={112} />}\n        >\n          <Facts items={[{ label: \"Apache-2.0\", tone: \"ok\" }, { label: \"Law 25 · GDPR\" }]} />\n          <Button variant=\"primary\" size=\"lg\" shape=\"cut\" shimmer>Install in three commands</Button>\n        </PageHero>\n        <Section id=\"why\" eyebrow=\"Why\" title=\"Three traps it removes\">\n          <CardGrid min={260} fit=\"fit\" reveal={false}>\n            {WHY.map((w) => (\n              <ArgumentCard\n                key={w.id}\n                id={`why-${w.id}`}\n                title={w.title}\n                mark={<Mascot bird={w.bird} size={40} animated={false} />}\n                hook={{ label: \"The trap\", text: w.hook }}\n                more={{ href: `#${w.id}`, label: \"Details\" }}\n              />\n            ))}\n          </CardGrid>\n        </Section>\n        <Section id=\"decisions\" eyebrow=\"Decisions\" title=\"What we chose, and what it costs you\" divider>\n          <DecisionList decisions={DECISIONS} labels={labels} reveal={false} />\n          <div className=\"mt-8\">\n            <MascotQuote variant=\"callout\" bird=\"owl\" label=\"The owl's promise\">\n              Every personal record stays in Québec, and you can read who touched it.\n            </MascotQuote>\n          </div>\n        </Section>\n        <Section spacing=\"sm\" aria-labelledby=\"product-cta\">\n          <CtaPanel id=\"product-cta\" title=\"Ready to run it at home?\" body=\"Three commands, then your first private answer.\">\n            <ActionBar primaryFirst size=\"lg\" label=\"Get started\" actions={[{ href: \"#install\", label: \"Install\" }, { href: \"#contact\", label: \"Talk to us\" }]} />\n          </CtaPanel>\n        </Section>\n      </MarketingLayout>\n    </div>\n  );\n}\n"
@@ -90,6 +93,8 @@
         "title": "Pricing and credits",
         "description": "Plans side by side, what a credit buys, the credits left.",
         "template": true,
+        "purpose": "convince",
+        "why": "A buyer compares plans and sees what a credit buys before deciding to commit.",
         "path": "examples/marketing-layout/pricing.tsx",
         "module": "@krizaka/ui/registry/examples/marketing-layout/pricing",
         "code": "import { Badge } from \"@krizaka/ui/badge\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { GlowCard } from \"@krizaka/ui/glow-card\";\nimport { Meter } from \"@krizaka/ui/meter\";\nimport { Section } from \"@krizaka/ui/page\";\nimport { PageHero } from \"@krizaka/ui/page-hero\";\n\nconst PLANS = [\n  { id: \"community\", name: \"Community\", price: \"Free\", unit: \"self-hosted\", points: [\"Every feature\", \"Your hardware\", \"Community support\"] },\n  { id: \"workspace\", name: \"Workspace\", price: \"€29\", unit: \"per month · 12,000 credits\", points: [\"Packs & Studios\", \"Shared workspaces\", \"Email support\"], featured: true },\n  { id: \"sovereign\", name: \"Sovereign\", price: \"Custom\", unit: \"on your servers\", points: [\"Installation with you\", \"Law 25 review\", \"A named engineer\"] },\n];\n\n// TEMPLATE — pricing and credits: the plans side by side (the featured one lit by its turning ring), what a credit buys,\n// and the credits left for a signed-in visitor. On a phone the plans stack, the featured one first in the reading order\n// it already has; every action is the cut button, the featured one primary.\nexport default function MarketingLayoutPricing() {\n  return (\n    <div className=\"w-full\">\n      <PageHero eyebrow=\"Pricing\" title=\"Pay once for what was done\" lead=\"Credits buy answers, images and minutes of video — never a seat you do not use.\" align=\"center\" backdrop=\"plain\" />\n      <Section aria-label=\"Plans\" spacing=\"sm\">\n        <ul className=\"grid gap-4 md:grid-cols-3\">\n          {PLANS.map((p) => (\n            <li key={p.id} className=\"flex\">\n              <GlowCard alive={p.featured} className=\"flex w-full flex-col gap-4\">\n                <div className=\"flex items-center justify-between gap-2\">\n                  <h2 className=\"font-display text-lg font-bold text-fg\">{p.name}</h2>\n                  {p.featured && <Badge tone=\"accent\">Most chosen</Badge>}\n                </div>\n                <p>\n                  <span className=\"font-display text-4xl font-extrabold text-fg\">{p.price}</span>\n                  <span className=\"mt-1 block text-sm text-fg-secondary\">{p.unit}</span>\n                </p>\n                <ul className=\"flex flex-col gap-2 text-sm text-fg-secondary\">\n                  {p.points.map((x) => (\n                    <li key={x}>— {x}</li>\n                  ))}\n                </ul>\n                <Button variant={p.featured ? \"primary\" : \"secondary\"} shape=\"cut\" className=\"mt-auto w-full\">\n                  Choose {p.name}\n                </Button>\n              </GlowCard>\n            </li>\n          ))}\n        </ul>\n      </Section>\n      <Section id=\"credits\" title=\"Your credits\" headingSize=\"sm\" spacing=\"sm\" divider>\n        <div className=\"max-w-md\">\n          <Meter label=\"Credits this month\" value={3800} max={12000} valueText=\"3,800 of 12,000 used\" thresholds={{ low: 0.7, high: 0.9 }} showLabel />\n          <p className=\"mt-3 text-sm text-fg-secondary\">One credit ≈ one chat answer · 4 credits an image · 30 a minute of video.</p>\n        </div>\n      </Section>\n    </div>\n  );\n}\n"
@@ -99,6 +104,8 @@
         "title": "A documentation hub",
         "description": "Groups of compact link cards under the hero.",
         "template": true,
+        "purpose": "explain",
+        "why": "A newcomer finds the right documentation from one page of grouped entry points.",
         "path": "examples/marketing-layout/docs-hub.tsx",
         "module": "@krizaka/ui/registry/examples/marketing-layout/docs-hub",
         "code": "import { ProductLogo } from \"@krizaka/ui\";\nimport { CardGrid } from \"@krizaka/ui/card-grid\";\nimport { LinkCard } from \"@krizaka/ui/link-card\";\nimport { Section } from \"@krizaka/ui/page\";\nimport { PageHero } from \"@krizaka/ui/page-hero\";\n\nconst GROUPS = [\n  {\n    id: \"start\",\n    title: \"Start here\",\n    cards: [\n      { id: \"cli\", logo: \"orazaka\", title: \"The CLI\", text: \"npx orazaka install, start, dev — then every command.\" },\n      { id: \"packs\", logo: \"orazaka\", title: \"Packs & Studios\", text: \"The business offers Orazaka installs without code.\" },\n      { id: \"admin\", logo: \"orochia\", title: \"Orochia admin console\", text: \"Verification, moderation, payouts — behind four gates.\" },\n    ],\n  },\n  {\n    id: \"platform\",\n    title: \"Platform\",\n    cards: [\n      { id: \"ui\", logo: \"krizaka\", title: \"Krizaka UI\", text: \"Tokens, a Tailwind preset and the components — live.\" },\n      { id: \"java\", logo: \"krizaka\", title: \"Krizaka Java\", text: \"Parent, BOM, starters, messaging, Problem Details.\" },\n    ],\n  },\n] as const;\n\n// TEMPLATE — a documentation hub (krizaka.com/docs): the hero, then one section per group, each a grid of compact link\n// cards — the whole card one link, the product's mark, one sentence, the way in. One column on a phone.\nexport default function MarketingLayoutDocsHub() {\n  return (\n    <div className=\"w-full\">\n      <PageHero eyebrow=\"Documentation\" title=\"Build with Krizaka\" lead=\"The building blocks the products are made of, documented from their source.\" backdrop=\"plain\" />\n      {GROUPS.map((g) => (\n        <Section key={g.id} id={`hub-${g.id}`} title={g.title} headingSize=\"sm\" spacing=\"sm\">\n          <CardGrid min={260} reveal={false}>\n            {g.cards.map((c) => (\n              <LinkCard key={c.id} href={`#${c.id}`} icon={<ProductLogo id={c.logo} size={24} animated={false} />} title={c.title} description={c.text} cta=\"Open\" />\n            ))}\n          </CardGrid>\n        </Section>\n      ))}\n    </div>\n  );\n}\n"
@@ -121,21 +128,23 @@
     },
     {
       "path": "marketing-layout/marketing-layout.tsx",
-      "content": "// Server-safe. The page of a site (krizaka.com, a product's public pages): a link to skip to the content, the site's\n// bar, the page — its PageHero and Sections (@krizaka/ui/page) — and the footer. The bar floats over the hero\n// (`--kz-hero-top` clears it); everything shares the page frame (`--kz-page-max`, `--kz-page-gutter`).\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nexport const marketingLayout = tv({\n  slots: {\n    root: \"flex min-h-dvh w-full flex-col bg-surface-0 text-fg\",\n    skip:\n      \"sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-[60] focus:rounded-lg focus:bg-surface-1 focus:px-4 focus:py-2 \" +\n      \"focus:text-sm focus:font-semibold focus:text-fg focus:shadow-lg focus:outline-hidden focus:ring-2 focus:ring-ring\",\n    header: \"fixed inset-x-0 top-3 z-50 px-(--kz-page-gutter,16px) pointer-events-none *:pointer-events-auto\",\n    main: \"flex-1 outline-hidden\",\n  },\n});\nconst s = marketingLayout();\n\nexport type MarketingLayoutProps = React.ComponentProps<\"div\"> & {\n  /** The site's bar (a floating NavBar of @krizaka/ui/nav-bar). */\n  header: React.ReactNode;\n  /** The site's footer. */\n  footer?: React.ReactNode;\n  /** The words of the link that skips to the content (`Skip to content`). */\n  skipLabel: string;\n  /** The page: a PageHero, then Sections. */\n  children: React.ReactNode;\n};\n\n/** A site's page: skip link, floating bar, the page, the footer. */\nexport function MarketingLayout({ header, footer, skipLabel, className, children, ...props }: MarketingLayoutProps) {\n  return (\n    <div className={s.root({ className })} {...props}>\n      <a href=\"#content\" className={s.skip()}>\n        {skipLabel}\n      </a>\n      <div className={s.header()}>{header}</div>\n      <main id=\"content\" tabIndex={-1} className={s.main()}>\n        {children}\n      </main>\n      {footer}\n    </div>\n  );\n}\n"
+      "content": "// Server-safe. The page of a site (krizaka.com, a product's public pages): a link to skip to the content, the site's\n// bar, the page — its PageHero and Sections (@krizaka/ui/page) — and the footer. The bar floats over the hero\n// (`--kz-hero-top` clears it); everything shares the page frame (`--kz-page-max`, `--kz-page-gutter`).\nimport { SkipLink } from \"@krizaka/ui/skip-link\";\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nexport const marketingLayout = tv({\n  slots: {\n    root: \"flex min-h-dvh w-full flex-col bg-surface-0 text-fg\",\n    header: \"fixed inset-x-0 top-3 z-50 px-(--kz-page-gutter,16px) pointer-events-none *:pointer-events-auto\",\n    main: \"flex-1 outline-hidden\",\n  },\n});\nconst s = marketingLayout();\n\nexport type MarketingLayoutProps = React.ComponentProps<\"div\"> & {\n  /** The site's bar (a floating NavBar of @krizaka/ui/nav-bar). */\n  header: React.ReactNode;\n  /** The site's footer. */\n  footer?: React.ReactNode;\n  /** The words of the link that skips to the content (`Skip to content`). */\n  skipLabel: string;\n  /** The page: a PageHero, then Sections. */\n  children: React.ReactNode;\n};\n\n/** A site's page: skip link, floating bar, the page, the footer. */\nexport function MarketingLayout({ header, footer, skipLabel, className, children, ...props }: MarketingLayoutProps) {\n  return (\n    <div className={s.root({ className })} {...props}>\n      <SkipLink>{skipLabel}</SkipLink>\n      <div className={s.header()}>{header}</div>\n      <main id=\"content\" tabIndex={-1} className={s.main()}>\n        {children}\n      </main>\n      {footer}\n    </div>\n  );\n}\n"
     },
     {
       "path": "marketing-layout/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Marketing layout\",\n  summary: \"A site's page: the link that skips to the content, the floating bar, the page made of a PageHero and Sections in one frame, the footer.\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  whenToUse: [\"Every public page of a Krizaka site: a product, pricing, a hub, a story.\", \"A product's public landing.\"],\n  whenNotToUse: [\n    { when: \"For a signed-in screen.\", use: \"app-shell\" },\n    { when: \"For a documentation page with a sidebar.\", use: \"docs-layout\" },\n  ],\n  bestPractices: [\"One PageHero per page, then Sections; the main action of the page is the only one with `shimmer`.\", \"Give the bar the frame's width (`--kz-page-max`): its edges are the content's.\", \"Templates show complete pages: copy one, keep its order.\"],\n  accessibility: {\n    keyboard: [\n      { keys: \"Tab\", action: \"The first stop is the skip link, which jumps to the page's content.\" }\n    ],\n    notes: [\"`main#content` receives the focus from the skip link.\", \"The bar floats over the hero: `--kz-hero-top` keeps the title clear of it.\"],\n  },\n  related: [\"page-hero\", \"page\", \"nav-bar\"],\n  web: {\n    imports: [\"MarketingLayout\"],\n    examples: [\n      { name: \"product-page\", title: \"A product page\", description: \"Orazaka's page: hero with facts, reasons, decisions, the owl's promise, the closing call.\", template: true },\n      { name: \"pricing\", title: \"Pricing and credits\", description: \"Plans side by side, what a credit buys, the credits left.\", template: true },\n      { name: \"docs-hub\", title: \"A documentation hub\", description: \"Groups of compact link cards under the hero.\", template: true },\n      { name: \"basic\", title: \"The layout alone\", description: \"Skip link, bar, hero, a section and a footer.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Marketing layout\",\n  summary: \"A site's page: the link that skips to the content, the floating bar, the page made of a PageHero and Sections in one frame, the footer.\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  whenToUse: [\"Every public page of a Krizaka site: a product, pricing, a hub, a story.\", \"A product's public landing.\"],\n  whenNotToUse: [\n    { when: \"For a signed-in screen.\", use: \"app-shell\" },\n    { when: \"For a documentation page with a sidebar.\", use: \"docs-layout\" },\n  ],\n  bestPractices: [\"One PageHero per page, then Sections; the main action of the page is the only one with `shimmer`.\", \"Give the bar the frame's width (`--kz-page-max`): its edges are the content's.\", \"Templates show complete pages: copy one, keep its order.\"],\n  accessibility: {\n    keyboard: [\n      { keys: \"Tab\", action: \"The first stop is the skip link, which jumps to the page's content.\" }\n    ],\n    notes: [\"`main#content` receives the focus from the skip link.\", \"The bar floats over the hero: `--kz-hero-top` keeps the title clear of it.\"],\n  },\n  related: [\"page-hero\", \"page\", \"nav-bar\"],\n  web: {\n    imports: [\"MarketingLayout\"],\n    examples: [\n      { name: \"product-page\", title: \"A product page\", description: \"Orazaka's page: hero with facts, reasons, decisions, the owl's promise, the closing call.\", template: true, purpose: \"convince\", why: \"A visitor decides whether a product is for them: the promise first, the proof and the call after.\" },\n      { name: \"pricing\", title: \"Pricing and credits\", description: \"Plans side by side, what a credit buys, the credits left.\", template: true, purpose: \"convince\", why: \"A buyer compares plans and sees what a credit buys before deciding to commit.\" },\n      { name: \"docs-hub\", title: \"A documentation hub\", description: \"Groups of compact link cards under the hero.\", template: true, purpose: \"explain\", why: \"A newcomer finds the right documentation from one page of grouped entry points.\" },\n      { name: \"basic\", title: \"The layout alone\", description: \"Skip link, bar, hero, a section and a footer.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\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  | \"verified-badge\"\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 * `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 krizaka.com/docs/ui/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  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     }
   ],
   "dependencies": [
     "tailwind-variants@^3.3.1"
   ],
-  "registryDependencies": [],
+  "registryDependencies": [
+    "skip-link"
+  ],
   "demo": {
     "path": "examples/marketing-layout/product-page.tsx",
     "content": "import { ProductLogo } from \"@krizaka/ui\";\nimport { ActionBar } from \"@krizaka/ui/action-bar\";\nimport { ArgumentCard } from \"@krizaka/ui/argument-card\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { CardGrid } from \"@krizaka/ui/card-grid\";\nimport { CtaPanel } from \"@krizaka/ui/cta-panel\";\nimport { DecisionList } from \"@krizaka/ui/decision-list\";\nimport { MarketingLayout } from \"@krizaka/ui/marketing-layout\";\nimport { MascotQuote } from \"@krizaka/ui/mascot-quote\";\nimport { Mascot } from \"@krizaka/ui/mascots\";\nimport { NavBar } from \"@krizaka/ui/nav-bar\";\nimport { Facts, Section } from \"@krizaka/ui/page\";\nimport { PageHero } from \"@krizaka/ui/page-hero\";\n\nconst WHY = [\n  { id: \"local\", title: \"Local inference\", hook: \"Elsewhere, every prompt crosses the ocean.\", bird: \"falcon\" as const },\n  { id: \"paid\", title: \"Paid once\", hook: \"Elsewhere, you pay per token, forever.\", bird: \"flamingo\" as const },\n  { id: \"asked\", title: \"Agents that ask\", hook: \"Elsewhere, an agent acts first and apologises later.\", bird: \"pigeon\" as const },\n];\nconst DECISIONS = [\n  { id: \"local\", chose: \"Local models by default.\", refused: \"A hosted API as the default path.\", because: \"A prompt that never leaves cannot leak.\", cost: \"You need a GPU, or patience on a CPU.\" },\n  { id: \"telemetry\", chose: \"Zero telemetry.\", refused: \"Anonymous usage statistics.\", because: \"Anonymous rarely stays anonymous.\", cost: \"You tell us what breaks.\" },\n];\nconst labels = { chose: \"We chose\", refused: \"We refused\", because: \"Because\", cost: \"What it costs you\" };\n\n// TEMPLATE — a product page (Orazaka): the hero with its facts and its main action (cut, shimmer), the reasons as compact\n// argument cards (the bird in the corner), the decisions with their cost, the owl's promise, the closing call. On a\n// phone the hero's bird goes above the title, the cards stack, the decisions' three parts stack under the choice.\nexport default function MarketingLayoutProductPage() {\n  return (\n    <div className=\"brand-orazaka\">\n      <MarketingLayout\n        skipLabel=\"Skip to content\"\n        header={\n          <NavBar.Root label=\"Main\" compactAfter={false} className=\"max-w-(--kz-page-max,72rem)\">\n            <NavBar.Brand href=\"#home\"><ProductLogo id=\"orazaka\" size={22} animated={false} /> Orazaka</NavBar.Brand>\n            <NavBar.Items>\n              <NavBar.Link href=\"#why\" active>Why</NavBar.Link>\n              <NavBar.Link href=\"#decisions\">Decisions</NavBar.Link>\n            </NavBar.Items>\n          </NavBar.Root>\n        }\n      >\n        <PageHero\n          eyebrow=\"Sovereign AI · open source\"\n          title=\"The AI that never leaves home\"\n          lead=\"Chat, image, voice and video on your own server — one governed pipeline, nothing sent anywhere.\"\n          aside={<Mascot bird=\"owl\" mood=\"welcome\" size={112} />}\n        >\n          <Facts items={[{ label: \"Apache-2.0\", tone: \"ok\" }, { label: \"Law 25 · GDPR\" }]} />\n          <Button variant=\"primary\" size=\"lg\" shape=\"cut\" shimmer>Install in three commands</Button>\n        </PageHero>\n        <Section id=\"why\" eyebrow=\"Why\" title=\"Three traps it removes\">\n          <CardGrid min={260} fit=\"fit\" reveal={false}>\n            {WHY.map((w) => (\n              <ArgumentCard\n                key={w.id}\n                id={`why-${w.id}`}\n                title={w.title}\n                mark={<Mascot bird={w.bird} size={40} animated={false} />}\n                hook={{ label: \"The trap\", text: w.hook }}\n                more={{ href: `#${w.id}`, label: \"Details\" }}\n              />\n            ))}\n          </CardGrid>\n        </Section>\n        <Section id=\"decisions\" eyebrow=\"Decisions\" title=\"What we chose, and what it costs you\" divider>\n          <DecisionList decisions={DECISIONS} labels={labels} reveal={false} />\n          <div className=\"mt-8\">\n            <MascotQuote variant=\"callout\" bird=\"owl\" label=\"The owl's promise\">\n              Every personal record stays in Québec, and you can read who touched it.\n            </MascotQuote>\n          </div>\n        </Section>\n        <Section spacing=\"sm\" aria-labelledby=\"product-cta\">\n          <CtaPanel id=\"product-cta\" title=\"Ready to run it at home?\" body=\"Three commands, then your first private answer.\">\n            <ActionBar primaryFirst size=\"lg\" label=\"Get started\" actions={[{ href: \"#install\", label: \"Install\" }, { href: \"#contact\", label: \"Talk to us\" }]} />\n          </CtaPanel>\n        </Section>\n      </MarketingLayout>\n    </div>\n  );\n}\n"

package/registry/marquee.json

@@ -5,6 +5,7 @@
   "summary": "A band of items that slides forever — at a speed in pixels per second, paused by the pointer, the focus or its own pause button, read once by assistive technology, and a still row you scroll under reduced motion.",
   "description": "A band of items that slides forever — at a speed in pixels per second, paused by the pointer, the focus or its own pause button, read once by assistive technology, and a still row you scroll under reduced motion.",
   "status": "beta",
+  "deprecated": null,
   "category": "data-display",
   "platforms": "web",
   "whenToUse": [
@@ -147,7 +148,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 krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\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  | \"verified-badge\"\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 * `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 krizaka.com/docs/ui/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  /** 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/mascot-quote.json

@@ -5,6 +5,7 @@
   "summary": "A rule, a promise or a decision told by a bird: the sentence in a speech bubble, the bird under its tail and who speaks — `inline` in a card, `callout` alone in a section.",
   "description": "A rule, a promise or a decision told by a bird: the sentence in a speech bubble, the bird under its tail and who speaks — `inline` in a card, `callout` alone in a section.",
   "status": "beta",
+  "deprecated": null,
   "category": "blocks",
   "platforms": "web",
   "whenToUse": [
@@ -126,7 +127,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 krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\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  | \"verified-badge\"\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 * `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 krizaka.com/docs/ui/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  /** 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/mascot-state.json

@@ -5,6 +5,7 @@
   "summary": "A moment told by a bird of the flock: nothing yet, a long wait, done, it failed, welcome — the bird of the job beside the words and the next action.",
   "description": "A moment told by a bird of the flock: nothing yet, a long wait, done, it failed, welcome — the bird of the job beside the words and the next action.",
   "status": "beta",
+  "deprecated": null,
   "category": "feedback",
   "platforms": "both",
   "whenToUse": [
@@ -844,7 +845,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 krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"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  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"stepper\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\nexport interface Example {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n  /**\n   * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its phone\n   * version thought out), copied as a starting point — at most 160 lines, listed on krizaka.com/docs/ui/templates.\n   */\n  readonly template?: boolean;\n}\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which krizaka.com renders as\n// /docs/ui/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"activity-feed\"\n  | \"action-sheet\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"form\"\n  | \"gallery-page\"\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  | \"map\"\n  | \"longform-page\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"split-view\"\n  | \"splash-handoff\"\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  | \"verified-badge\"\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 * `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 krizaka.com/docs/ui/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  /** 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": [