{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "explainer-spec",
  "type": "registry:lib",
  "title": "Explainer Spec",
  "description": "The plain-data description of an explainer film (scenes of a title, a chart, a map, a 3D model, a then-and-now comparison, a quote or a caption, each with a length, a transition, captions, a narration cue and a provenance label) and a validator that lists every fault in words.",
  "categories": [
    "lib"
  ],
  "dependencies": [],
  "registryDependencies": [
    "@rivier-ui/theme"
  ],
  "files": [
    {
      "path": "registry/lib/explainer-spec.ts",
      "type": "registry:lib",
      "target": "lib/explainer-spec.ts",
      "content": "/**\n * @name explainer-spec\n * @category lib\n * @description The plain-data description of an explainer film (scenes of a title, a chart, a map, a 3D model, a then-and-now comparison, a quote or a caption, each with a length, a transition, captions, a narration cue and a provenance label) and a validator that lists every fault in words.\n * @when An assistant or a project writes a film as JSON and hands it to motion/explainer. Run validateExplainer first and show its faults: each says where the fault is and how to mend it. For a film drawn by hand from React, use film-stage directly.\n * @example\n * const spec: ExplainerSpec = {\n *   title: \"How the river rose\",\n *   lang: \"en\",\n *   scenes: [\n *     { id: \"intro\", kind: \"title\", duration: 4, title: \"How the river rose\", subtitle: \"Spring 2026\" },\n *     {\n *       id: \"levels\", kind: \"chart\", duration: 8, chart: \"line-chart\",\n *       props: { label: \"Water level by day\", data: [{ day: 1, level: 2.1 }, { day: 2, level: 2.9 }], x: \"day\", series: [{ key: \"level\", label: \"Level (m)\" }] },\n *       captions: [{ start: 0.5, end: 4, text: \"The level rose for four days.\" }],\n *       provenance: { kind: \"measured\", note: \"Gauge readings\" },\n *     },\n *   ],\n * };\n * const faults = validateExplainer(spec); // [] when it is sound\n */\n\n/** What a scene shows, by how it was made. Each is said in words on the scene, never left to guess. */\nexport type ExplainerProvenanceKind = \"measured\" | \"reconstructed\" | \"generated\" | \"invented\";\n\nexport const EXPLAINER_PROVENANCE_KINDS: readonly ExplainerProvenanceKind[] = [\"measured\", \"reconstructed\", \"generated\", \"invented\"];\n\nexport type ExplainerProvenance = {\n  kind: ExplainerProvenanceKind;\n  /** A few words more: \"Gauge readings, hourly\", \"Drawn from the 1890 survey\". */\n  note?: string;\n  /** Where it came from, one line each. Shown in the label's popover. */\n  sources?: readonly string[];\n};\n\n/** A line of captions, in seconds from the start of its scene. */\nexport type ExplainerCaption = { start: number; end: number; text: string };\n\n/** A sound for the scene: a narrated line, in seconds from the start of the scene. */\nexport type ExplainerNarration = {\n  src: string;\n  /** When it starts within the scene. Default 0. */\n  start?: number;\n  /** How long it plays. Default: to its end. */\n  duration?: number;\n  /** 0 to 1. Default 1. */\n  volume?: number;\n};\n\nexport type ExplainerTransition = \"cut\" | \"crossfade\";\n\n/** What every scene has. */\nexport type ExplainerSceneBase = {\n  /** Unique within the film: letters, digits and dashes. */\n  id: string;\n  /** Its length in seconds, above 0. */\n  duration: number;\n  /** Its name in the scene strip and the time bar. Default: the scene's title or kind. */\n  label?: string;\n  /** How it arrives. Default: the film's `transition`. */\n  transition?: ExplainerTransition;\n  captions?: readonly ExplainerCaption[];\n  narration?: ExplainerNarration;\n  /** How what it shows was made. Charts, maps, models and comparisons should always say. */\n  provenance?: ExplainerProvenance;\n};\n\n/** The charts a chart scene can draw, by their registry names. */\nexport const EXPLAINER_CHARTS = [\n  \"line-chart\",\n  \"area-chart\",\n  \"bar-chart\",\n  \"donut-chart\",\n  \"heatmap\",\n  \"scatter-chart\",\n  \"histogram\",\n  \"box-plot\",\n  \"fan-chart\",\n  \"small-multiples\",\n  \"treemap\",\n  \"sunburst\",\n  \"circle-pack\",\n  \"sankey-chart\",\n  \"network-graph\",\n  \"calendar-heatmap\",\n  \"gantt-chart\",\n  \"density-chart\",\n  \"radar-chart\",\n  \"waterfall-chart\",\n  \"funnel-chart\",\n  \"bullet-chart\",\n  \"candlestick-chart\",\n  \"chord-diagram\",\n  \"parallel-coordinates\",\n  \"dot-plot\",\n  \"stream-chart\",\n  \"slope-chart\",\n] as const;\nexport type ExplainerChart = (typeof EXPLAINER_CHARTS)[number];\n\n/** The props each chart cannot do without, beyond `label`. */\nconst CHART_NEEDS: Record<ExplainerChart, readonly string[]> = {\n  \"line-chart\": [\"data\", \"x\", \"series\"],\n  \"area-chart\": [\"data\", \"x\", \"series\"],\n  \"bar-chart\": [\"data\", \"x\", \"series\"],\n  \"donut-chart\": [\"data\"],\n  heatmap: [\"data\", \"x\", \"y\", \"value\"],\n  \"scatter-chart\": [\"data\", \"x\", \"y\"],\n  histogram: [\"data\", \"value\"],\n  \"box-plot\": [\"data\", \"group\", \"value\"],\n  \"fan-chart\": [\"data\", \"x\", \"median\", \"intervals\"],\n  \"small-multiples\": [\"data\", \"facet\", \"x\", \"y\"],\n  treemap: [\"data\"],\n  sunburst: [\"data\"],\n  \"circle-pack\": [\"data\"],\n  \"sankey-chart\": [\"nodes\", \"links\"],\n  \"network-graph\": [\"nodes\", \"links\"],\n  \"calendar-heatmap\": [\"data\", \"day\", \"value\"],\n  \"gantt-chart\": [\"tasks\"],\n  \"density-chart\": [\"data\", \"x\", \"y\"],\n  \"radar-chart\": [\"data\", \"axis\", \"series\"],\n  \"waterfall-chart\": [\"data\", \"x\", \"value\"],\n  \"funnel-chart\": [\"data\", \"x\", \"value\"],\n  \"bullet-chart\": [\"items\"],\n  \"candlestick-chart\": [\"data\", \"x\"],\n  \"chord-diagram\": [\"names\", \"matrix\"],\n  \"parallel-coordinates\": [\"data\", \"dimensions\"],\n  \"dot-plot\": [\"data\", \"y\", \"series\"],\n  \"stream-chart\": [\"data\", \"x\", \"series\"],\n  \"slope-chart\": [\"data\", \"name\", \"from\", \"to\", \"fromLabel\", \"toLabel\"],\n};\n\n/** A map's view, as geo-map's: `k` the zoom (1 fitted), `x` and `y` a shift in pixels. */\nexport type ExplainerMapView = { k: number; x: number; y: number };\n\n/** A GeoJSON FeatureCollection, as plain data. */\nexport type ExplainerGeoJson = { type: \"FeatureCollection\"; features: readonly { type: \"Feature\"; id?: string | number; properties?: Record<string, unknown> | null; geometry: unknown }[] };\n\nexport type ExplainerMapLayer =\n  | {\n      type: \"choropleth\";\n      /** The layer's name: \"Rainfall by district\". */\n      label: string;\n      /** The feature property holding each region's number, and the one holding its name. */\n      valueProperty: string;\n      nameProperty: string;\n      /** Class edges, low to high. Left out, one hue from low to high. */\n      thresholds?: readonly number[];\n      valueLabel?: string;\n    }\n  | { type: \"markers\"; label: string; points: readonly { id: string; name: string; lon: number; lat: number; value?: number; group?: string }[]; variant?: \"point\" | \"bubble\"; valueLabel?: string }\n  | {\n      type: \"routes\";\n      label: string;\n      routes: readonly { id: string; name: string; from: [number, number]; to: [number, number]; value?: number }[];\n      variant?: \"great-circle\" | \"arc\";\n      valueLabel?: string;\n    }\n  | { type: \"hexbin\"; label: string; points: readonly { lon: number; lat: number; weight?: number }[]; valueLabel?: string };\n\nexport const EXPLAINER_PROJECTIONS = [\"equal-earth\", \"natural-earth\", \"mercator\", \"equirectangular\", \"orthographic\", \"conic-equal-area\", \"azimuthal-equal-area\", \"transverse-mercator\"] as const;\n\nexport type ExplainerPicture = { src: string; alt: string };\n\nexport type ExplainerScene = ExplainerSceneBase &\n  (\n    | { kind: \"title\"; title: string; subtitle?: string }\n    | { kind: \"chart\"; chart: ExplainerChart; props: Record<string, unknown>; title?: string }\n    | {\n        kind: \"map\";\n        geojson: ExplainerGeoJson;\n        projection?: (typeof EXPLAINER_PROJECTIONS)[number];\n        /** Turns the globe before projecting: [longitude, latitude]. */\n        rotate?: [number, number];\n        layers?: readonly ExplainerMapLayer[];\n        /** The view at the start and at the end: the map moves between them over the scene. */\n        camera?: { from?: ExplainerMapView; to?: ExplainerMapView };\n        /** The map's name for screen readers. */\n        label: string;\n        title?: string;\n      }\n    | {\n        kind: \"model\";\n        /** A glTF, GLB or Gaussian splat file. */\n        src: string;\n        alt: string;\n        poster?: string;\n        /** How far the model turns over the scene, in degrees. Default 60. */\n        turn?: number;\n        title?: string;\n      }\n    | {\n        kind: \"compare\";\n        before: ExplainerPicture & { label: string };\n        after: ExplainerPicture & { label: string };\n        /** The divider's position at the start and the end of the scene, 0 to 100. Default [100, 0]. */\n        sweep?: [number, number];\n        /** What is compared, for screen readers. */\n        label: string;\n      }\n    | { kind: \"quote\"; text: string; attribution?: string }\n    | { kind: \"caption\"; text: string; picture?: ExplainerPicture }\n  );\n\nexport type ExplainerKind = ExplainerScene[\"kind\"];\nexport const EXPLAINER_KINDS: readonly ExplainerKind[] = [\"title\", \"chart\", \"map\", \"model\", \"compare\", \"quote\", \"caption\"];\n\n/** A sound under the whole film, from its start. */\nexport type ExplainerBed = { src: string; volume?: number };\n\nexport type ExplainerSpec = {\n  /** The film's name: the stage is named by it. */\n  title: string;\n  /** The language of the captions and words (BCP 47): \"en\", \"nb\", \"ar\". Default \"en\". */\n  lang?: string;\n  /** Width / height of the frame. Default 16 / 9. */\n  aspect?: number;\n  /** How scenes arrive unless they say otherwise. Default \"crossfade\". */\n  transition?: ExplainerTransition;\n  scenes: readonly ExplainerScene[];\n  bed?: ExplainerBed;\n};\n\n/** One fault: where it is (a path into the spec) and what is wrong, in words that say how to mend it. */\nexport type ExplainerFault = { path: string; message: string };\n\nconst isRecord = (value: unknown): value is Record<string, unknown> => typeof value === \"object\" && value !== null && !Array.isArray(value);\nconst isText = (value: unknown): value is string => typeof value === \"string\" && value.trim().length > 0;\nconst isNumber = (value: unknown): value is number => typeof value === \"number\" && Number.isFinite(value);\nconst list = (items: readonly string[]): string => items.map((item) => `\"${item}\"`).join(\", \");\n\n/** The longest scene the validator accepts, in seconds: a longer one is nearly always a unit mistake (milliseconds). */\nexport const EXPLAINER_MAX_SCENE = 600;\n\n/**\n * Checks a spec, which may have come from anywhere (JSON written by an assistant), and returns every fault\n * found, in order. An empty list means the explainer component can play it. Unknown keys are allowed.\n */\nexport function validateExplainer(input: unknown): ExplainerFault[] {\n  const faults: ExplainerFault[] = [];\n  const fault = (path: string, message: string): void => {\n    faults.push({ path, message });\n  };\n  if (!isRecord(input)) {\n    fault(\"\", \"The spec must be an object with a title and a list of scenes.\");\n    return faults;\n  }\n  if (!isText(input[\"title\"])) fault(\"title\", \"Give the film a title: a string of words, used as its name.\");\n  if (input[\"lang\"] !== undefined && (!isText(input[\"lang\"]) || !/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(input[\"lang\"])))\n    fault(\"lang\", 'lang must be a language tag such as \"en\", \"nb\" or \"pt-BR\".');\n  if (input[\"aspect\"] !== undefined && (!isNumber(input[\"aspect\"]) || input[\"aspect\"] <= 0.2 || input[\"aspect\"] > 5))\n    fault(\"aspect\", \"aspect must be width divided by height, a number such as 1.78 (16 / 9) or 1 (square).\");\n  if (input[\"transition\"] !== undefined && input[\"transition\"] !== \"cut\" && input[\"transition\"] !== \"crossfade\") fault(\"transition\", 'transition must be \"cut\" or \"crossfade\".');\n  const bed = input[\"bed\"];\n  if (bed !== undefined && (!isRecord(bed) || !isText(bed[\"src\"]))) fault(\"bed\", \"bed must be an object with src, the address of a sound file.\");\n  const scenes = input[\"scenes\"];\n  if (!Array.isArray(scenes) || scenes.length === 0) {\n    fault(\"scenes\", \"scenes must be a list with at least one scene.\");\n    return faults;\n  }\n  const seen = new Set<string>();\n  scenes.forEach((scene: unknown, index) => {\n    const at = `scenes[${index}]`;\n    const name = `Scene ${index + 1}`;\n    if (!isRecord(scene)) {\n      fault(at, `${name} must be an object.`);\n      return;\n    }\n    const id = scene[\"id\"];\n    const named = isText(id) ? `${name} (\"${id}\")` : name;\n    if (!isText(id) || !/^[a-zA-Z0-9][\\w-]*$/.test(id)) fault(`${at}.id`, `${name} needs an id: letters, digits and dashes, such as \"intro\".`);\n    else if (seen.has(id)) fault(`${at}.id`, `${named} has the same id as an earlier scene; ids must be unique.`);\n    else seen.add(id);\n    const duration = scene[\"duration\"];\n    const length = isNumber(duration) ? duration : 0;\n    if (!isNumber(duration) || duration <= 0) fault(`${at}.duration`, `${named} needs a duration: a number of seconds above 0.`);\n    else if (duration > EXPLAINER_MAX_SCENE) fault(`${at}.duration`, `${named} lasts ${duration} seconds. Durations are in seconds, not milliseconds; keep a scene under ${EXPLAINER_MAX_SCENE}.`);\n    if (scene[\"transition\"] !== undefined && scene[\"transition\"] !== \"cut\" && scene[\"transition\"] !== \"crossfade\") fault(`${at}.transition`, `${named}: transition must be \"cut\" or \"crossfade\".`);\n    if (scene[\"label\"] !== undefined && !isText(scene[\"label\"])) fault(`${at}.label`, `${named}: label must be a few words.`);\n\n    const captions = scene[\"captions\"];\n    if (captions !== undefined) {\n      if (!Array.isArray(captions)) fault(`${at}.captions`, `${named}: captions must be a list of { start, end, text }.`);\n      else\n        captions.forEach((cue: unknown, c) => {\n          const cueAt = `${at}.captions[${c}]`;\n          if (!isRecord(cue) || !isText(cue[\"text\"]) || !isNumber(cue[\"start\"]) || !isNumber(cue[\"end\"])) {\n            fault(cueAt, `${named}, caption ${c + 1}: give start and end in seconds and the text.`);\n            return;\n          }\n          if (cue[\"start\"] < 0 || cue[\"end\"] <= cue[\"start\"]) fault(cueAt, `${named}, caption ${c + 1}: end must come after start, and start must not be below 0.`);\n          else if (length > 0 && cue[\"start\"] >= length)\n            fault(cueAt, `${named}, caption ${c + 1} starts at ${cue[\"start\"]} s, after the scene ends at ${length} s. Caption times are counted from the start of their scene.`);\n        });\n    }\n    const narration = scene[\"narration\"];\n    if (narration !== undefined) {\n      if (!isRecord(narration) || !isText(narration[\"src\"])) fault(`${at}.narration`, `${named}: narration needs src, the address of the sound file.`);\n      else {\n        const start = narration[\"start\"];\n        if (start !== undefined && (!isNumber(start) || start < 0 || (length > 0 && start >= length)))\n          fault(`${at}.narration.start`, `${named}: narration start must be a number of seconds within the scene (0 to ${length}).`);\n        const volume = narration[\"volume\"];\n        if (volume !== undefined && (!isNumber(volume) || volume < 0 || volume > 1)) fault(`${at}.narration.volume`, `${named}: narration volume must be between 0 and 1.`);\n      }\n    }\n    const provenance = scene[\"provenance\"];\n    const kind = scene[\"kind\"];\n    if (provenance !== undefined) {\n      if (!isRecord(provenance) || !EXPLAINER_PROVENANCE_KINDS.includes(provenance[\"kind\"] as ExplainerProvenanceKind))\n        fault(`${at}.provenance`, `${named}: provenance.kind must be one of ${list(EXPLAINER_PROVENANCE_KINDS)}.`);\n      else if (provenance[\"sources\"] !== undefined && (!Array.isArray(provenance[\"sources\"]) || !provenance[\"sources\"].every(isText)))\n        fault(`${at}.provenance.sources`, `${named}: sources must be a list of lines of text.`);\n    } else if (kind === \"chart\" || kind === \"map\" || kind === \"model\" || kind === \"compare\") {\n      fault(`${at}.provenance`, `${named} shows a ${kind} but does not say how it was made: add provenance with kind ${list(EXPLAINER_PROVENANCE_KINDS)}.`);\n    }\n\n    switch (kind) {\n      case \"title\":\n        if (!isText(scene[\"title\"])) fault(`${at}.title`, `${named} is a title scene: give it a title.`);\n        break;\n      case \"quote\":\n        if (!isText(scene[\"text\"])) fault(`${at}.text`, `${named} is a quote: give the words as text.`);\n        break;\n      case \"caption\": {\n        if (!isText(scene[\"text\"])) fault(`${at}.text`, `${named} is a caption: give the words as text.`);\n        const picture = scene[\"picture\"];\n        if (picture !== undefined && (!isRecord(picture) || !isText(picture[\"src\"]) || typeof picture[\"alt\"] !== \"string\"))\n          fault(`${at}.picture`, `${named}: picture needs src and alt (alt may be \"\" for a picture that only decorates).`);\n        break;\n      }\n      case \"chart\": {\n        const chart = scene[\"chart\"];\n        if (!EXPLAINER_CHARTS.includes(chart as ExplainerChart)) {\n          fault(`${at}.chart`, `${named}: chart must be one of ${list(EXPLAINER_CHARTS)}.`);\n          break;\n        }\n        const props = scene[\"props\"];\n        if (!isRecord(props)) {\n          fault(`${at}.props`, `${named}: props must be an object with the chart's data and keys.`);\n          break;\n        }\n        if (!isText(props[\"label\"]) && !isText(props[\"title\"]) && !isText(scene[\"title\"])) fault(`${at}.props.label`, `${named}: give the chart a label, what it shows in words, for screen readers.`);\n        for (const need of CHART_NEEDS[chart as ExplainerChart]) {\n          if (props[need] === undefined || props[need] === null) fault(`${at}.props.${need}`, `${named}: a ${String(chart)} needs ${need}.`);\n        }\n        if (props[\"data\"] !== undefined && chart !== \"treemap\" && chart !== \"sunburst\" && chart !== \"circle-pack\" && !Array.isArray(props[\"data\"]))\n          fault(`${at}.props.data`, `${named}: data must be a list of rows.`);\n        break;\n      }\n      case \"map\": {\n        if (!isText(scene[\"label\"])) fault(`${at}.label`, `${named} is a map: give it a label, what it shows, for screen readers.`);\n        const geojson = scene[\"geojson\"];\n        if (!isRecord(geojson) || geojson[\"type\"] !== \"FeatureCollection\" || !Array.isArray(geojson[\"features\"]))\n          fault(`${at}.geojson`, `${named}: geojson must be a GeoJSON FeatureCollection with a features list.`);\n        if (scene[\"projection\"] !== undefined && !EXPLAINER_PROJECTIONS.includes(scene[\"projection\"] as (typeof EXPLAINER_PROJECTIONS)[number]))\n          fault(`${at}.projection`, `${named}: projection must be one of ${list(EXPLAINER_PROJECTIONS)}.`);\n        const camera = scene[\"camera\"];\n        if (camera !== undefined) {\n          const views = isRecord(camera) ? [camera[\"from\"], camera[\"to\"]] : [null];\n          if (!views.every((view) => view === undefined || (isRecord(view) && isNumber(view[\"k\"]) && view[\"k\"] >= 1 && isNumber(view[\"x\"]) && isNumber(view[\"y\"]))))\n            fault(`${at}.camera`, `${named}: camera.from and camera.to must be views { k, x, y } with k (the zoom) 1 or more.`);\n        }\n        const layers = scene[\"layers\"];\n        if (layers !== undefined && !Array.isArray(layers)) fault(`${at}.layers`, `${named}: layers must be a list.`);\n        else\n          (layers ?? []).forEach((layer: unknown, l: number) => {\n            const layerAt = `${at}.layers[${l}]`;\n            if (!isRecord(layer) || ![\"choropleth\", \"markers\", \"routes\", \"hexbin\"].includes(String(layer[\"type\"]))) {\n              fault(layerAt, `${named}, layer ${l + 1}: type must be \"choropleth\", \"markers\", \"routes\" or \"hexbin\".`);\n              return;\n            }\n            if (!isText(layer[\"label\"])) fault(`${layerAt}.label`, `${named}, layer ${l + 1}: give it a label for screen readers.`);\n            if (layer[\"type\"] === \"choropleth\" && (!isText(layer[\"valueProperty\"]) || !isText(layer[\"nameProperty\"])))\n              fault(layerAt, `${named}, layer ${l + 1}: a choropleth needs valueProperty and nameProperty, the feature properties holding each region's number and name.`);\n            if ((layer[\"type\"] === \"markers\" || layer[\"type\"] === \"hexbin\") && !Array.isArray(layer[\"points\"]))\n              fault(`${layerAt}.points`, `${named}, layer ${l + 1}: points must be a list of { lon, lat }.`);\n            if (layer[\"type\"] === \"routes\" && !Array.isArray(layer[\"routes\"])) fault(`${layerAt}.routes`, `${named}, layer ${l + 1}: routes must be a list of { id, name, from, to }.`);\n          });\n        break;\n      }\n      case \"model\":\n        if (!isText(scene[\"src\"])) fault(`${at}.src`, `${named} is a model: give src, the address of a .glb, .gltf or splat file.`);\n        if (!isText(scene[\"alt\"])) fault(`${at}.alt`, `${named}: give alt, what the model shows in words.`);\n        if (scene[\"turn\"] !== undefined && !isNumber(scene[\"turn\"])) fault(`${at}.turn`, `${named}: turn must be a number of degrees.`);\n        break;\n      case \"compare\": {\n        if (!isText(scene[\"label\"])) fault(`${at}.label`, `${named} is a comparison: give it a label, what is compared.`);\n        for (const side of [\"before\", \"after\"] as const) {\n          const picture = scene[side];\n          if (!isRecord(picture) || !isText(picture[\"src\"]) || !isText(picture[\"alt\"]) || !isText(picture[\"label\"]))\n            fault(`${at}.${side}`, `${named}: ${side} needs src, alt (what it shows) and label (its name, such as a year).`);\n        }\n        const sweep = scene[\"sweep\"];\n        if (sweep !== undefined && (!Array.isArray(sweep) || sweep.length !== 2 || !sweep.every((value) => isNumber(value) && value >= 0 && value <= 100)))\n          fault(`${at}.sweep`, `${named}: sweep must be two numbers from 0 to 100, the divider at the start and at the end.`);\n        break;\n      }\n      default:\n        fault(`${at}.kind`, `${named}: kind must be one of ${list(EXPLAINER_KINDS)}.`);\n    }\n  });\n  return faults;\n}\n\n/** Where each scene starts and ends in the film, in seconds, and the film's length. */\nexport function explainerTimeline(spec: Pick<ExplainerSpec, \"scenes\">): { scenes: { id: string; start: number; end: number }[]; duration: number } {\n  let at = 0;\n  const scenes = spec.scenes.map((scene) => {\n    const start = at;\n    at += Math.max(0, scene.duration);\n    return { id: scene.id, start, end: at };\n  });\n  return { scenes, duration: at };\n}\n\n/** Every scene's captions on the film's clock: what captions and a transcript take. */\nexport function explainerCues(spec: Pick<ExplainerSpec, \"scenes\">): { start: number; end: number; text: string }[] {\n  const { scenes } = explainerTimeline(spec);\n  return spec.scenes.flatMap((scene, index) => {\n    const start = scenes[index]?.start ?? 0;\n    return (scene.captions ?? []).map((cue) => ({ start: start + cue.start, end: start + Math.min(cue.end, scene.duration), text: cue.text }));\n  });\n}\n"
    }
  ],
  "meta": {
    "category": "lib",
    "when": "An assistant or a project writes a film as JSON and hands it to motion/explainer. Run validateExplainer first and show its faults: each says where the fault is and how to mend it. For a film drawn by hand from React, use film-stage directly.",
    "example": "const spec: ExplainerSpec = {\n  title: \"How the river rose\",\n  lang: \"en\",\n  scenes: [\n    { id: \"intro\", kind: \"title\", duration: 4, title: \"How the river rose\", subtitle: \"Spring 2026\" },\n    {\n      id: \"levels\", kind: \"chart\", duration: 8, chart: \"line-chart\",\n      props: { label: \"Water level by day\", data: [{ day: 1, level: 2.1 }, { day: 2, level: 2.9 }], x: \"day\", series: [{ key: \"level\", label: \"Level (m)\" }] },\n      captions: [{ start: 0.5, end: 4, text: \"The level rose for four days.\" }],\n      provenance: { kind: \"measured\", note: \"Gauge readings\" },\n    },\n  ],\n};\nconst faults = validateExplainer(spec); // [] when it is sound",
    "client": false
  }
}
