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