footprint-story 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.0 — a story written as data
+
+- **storyboard** (`footprint-story/storyboard`, a fourth door, pure, loaded only when imported): a story written as plain
+  data on a named shape, for a film and a deck to draw the same way. `storyShapes` lists the shapes with a worked outline,
+  `storyboardProblems` names every mistake at once, and `readStoryboard` gives frozen scenes, each usable as a scene of a
+  film's storyboard as it is. Two shapes: `told-twice` and `what-we-found`. Given a conversation, a claim must cite the
+  messages it rests on, and its numbers must be in them. What a model writes must use plain digits: a disguised number is
+  refused. Nothing here draws.
+- The architecture test now checks four doors.
+
 ## 0.3.0 — footprint-narration is now footprint-story, and the motion words join it
 
 **Renamed.** The package is `footprint-story` from this version: what a film (footprint-storyreel) and a deck

package/README.md

@@ -1,5 +1,9 @@
 # footprint-story
 
+For developers building narration and animation tools, or integrating the shared rules used by StoryDeck and StoryReel.
+
+[Install and import paths](#install-and-import-paths) · [Text mapping](#one-text-as-shown-and-as-spoken) · [Captions](#captions) · [Motion](#how-things-move-motion) · [Guarantees and limits](#what-is-guaranteed)
+
 **What a film and a deck share.** [StoryDeck](https://github.com/footprintjs/storydeck) (slide decks that narrate
 themselves) and [footprint-storyreel](https://github.com/footprintjs/storyreel) (drawn films) tell stories the same
 way: a voice says the words, captions show them, and things move on screen. Each used to keep its own copy of those
@@ -16,22 +20,49 @@ files, YouTube chapters, and — for Node — a voice port with a clip cache key
 picture may sit still are words both tools use, so they are named here once. Nothing here draws: StoryReel paints
 them on a canvas, StoryDeck plays them in a page.
 
+## Install and import paths
+
 ```sh
 npm install footprint-story
 ```
 
-Three doors, nothing else. A door loads only when you import it, so a page that only captions never loads motion:
+Four doors, nothing else. A door loads only when you import it, so a page that only captions never loads motion:
 
 | door | what | runs |
 |---|---|---|
 | `footprint-story` | the shown↔spoken map, sentences, captions, chapters | anywhere — browser or Node; no dependencies |
 | `footprint-story/voice` | the voice port, the clip cache, its two adapters: the Chatterbox kit and your own recorded takes | **Node only** (files, child processes) |
 | `footprint-story/motion` | eases and springs, moves, transitions as data, pace | anywhere — browser or Node; no dependencies |
+| `footprint-story/storyboard` | a story written as data on a named shape, read and checked for both tools to draw | anywhere — browser or Node; no dependencies |
 
 What may join: only what both tools use, and only the shared words and maths — each tool keeps its own drawing. A
 new topic gets its own door; a door becomes a package of its own only if it ever needs a dependency or a release
 pace of its own.
 
+## A story written as data
+
+An agent telling a story should not have to write a deck's HTML or a film's recipe. It fills in a **shape**, and every
+mistake is named at once, so it fixes them in one pass. Whoever draws the board treats its words as text, never as code.
+
+```js
+import { storyShapes, storyboardProblems, readStoryboard } from 'footprint-story/storyboard';
+
+storyShapes();                   // [{ name, about, fills }]: the shapes, and a worked outline of each
+storyboardProblems(fromAgent);   // [{ at: 'items[1].turn.callout', message: 'must say both names, …' }]
+const board = readStoryboard(fromAgent, { conversation: [{ id: 'm7', text: 'it waited 41 minutes' }] });
+board.scenes[1];                 // { id, part, look, title, narration, beat }
+```
+
+| shape | what it tells |
+|---|---|
+| `told-twice` | a cast of people and everyday things acts a system out, each turns into the real thing where it stood, then the same story runs again for real |
+| `what-we-found` | what was checked, what was found, what is still not known (which must be written, even empty), and what happens next |
+
+Given a conversation, a `what-we-found` claim must name the messages it rests on, and every number in it must be in one of
+them; anything that cites none, such as its title, must use numbers from somewhere in the conversation. That catches a
+wrong number. It does not catch a claim that is wrong in words, a number spelled out, or a sign (`-41` reads as 41). `verified` is true only when claims
+really were checked: `told-twice` makes none, and with no conversation nothing is checked.
+
 ## One text, as shown and as spoken
 
 A **slot** says one exact place by hand; the **rules** say everything else. Use either or both.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "footprint-story",
-  "version": "0.3.0",
-  "description": "What a film and a deck share: what a voice says and what a caption shows (shown-vs-spoken text, sentences and word times, caption cues and files, YouTube chapters); a voice port and a clip cache behind /voice; how things move behind /motion (eases, springs, moves, transitions as data, pace).",
+  "version": "0.4.0",
+  "description": "Shared JavaScript narration, shown/spoken text, captions and motion primitives for StoryDeck and StoryReel, with a separate Node voice-cache entry.",
   "type": "module",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -27,6 +27,7 @@
     "easing",
     "spring",
     "transitions",
+    "storyboard",
     "storyreel",
     "storydeck",
     "footprintjs"
@@ -49,6 +50,10 @@
       "types": "./motion.d.ts",
       "default": "./motion.js"
     },
+    "./storyboard": {
+      "types": "./storyboard.d.ts",
+      "default": "./storyboard.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -58,6 +63,8 @@
     "voice.d.ts",
     "motion.js",
     "motion.d.ts",
+    "storyboard.js",
+    "storyboard.d.ts",
     "src",
     "plugin",
     "README.md",
@@ -65,7 +72,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test --experimental-test-coverage --test-coverage-include=src/** --test-coverage-include=index.js --test-coverage-include=voice.js --test-coverage-include=motion.js --test-coverage-lines=95 --test-coverage-branches=85 --test-coverage-functions=90 test/*.test.js"
+    "test": "node --test --experimental-test-coverage --test-coverage-include=src/** --test-coverage-include=index.js --test-coverage-include=voice.js --test-coverage-include=motion.js --test-coverage-include=storyboard.js --test-coverage-lines=95 --test-coverage-branches=85 --test-coverage-functions=90 test/*.test.js"
   },
   "devDependencies": {
     "fast-check": "^4.10.2"

package/plugin/skills/footprint-story/SKILL.md

@@ -7,13 +7,14 @@ description: What a film and a deck share (footprint-story, formerly footprint-n
 
 A voice drops or garbles digits and a forced aligner knows only letters, so a narration is **said in words and
 shown as written**. Everything here rests on one map from the shown text to the spoken text. And a move, a change of
-picture and a pace are named here once, so a film and a deck move alike. Three doors:
+picture and a pace are named here once, so a film and a deck move alike. Four doors:
 
 | You need | Import | Runs |
 |---|---|---|
 | the shown↔spoken map, sentences, captions, chapters | `footprint-story` | anywhere (browser or Node), no dependencies |
 | a voice clip cache, the voice port, the Chatterbox kit adapter | `footprint-story/voice` | **Node only** |
 | eases, springs, moves, transitions as data, pace | `footprint-story/motion` | anywhere, no dependencies; nothing draws |
+| a story as data on a named shape, read and checked | `footprint-story/storyboard` | anywhere, no dependencies; nothing draws |
 
 Never import `footprint-story/voice` into browser code. This package was `footprint-narration` until 0.3.0: replace
 the name in imports and `package.json`; the two old doors export exactly what they did.

package/src/storyboard/README.md

@@ -0,0 +1,27 @@
+# storyboard/ — a story written as data, on a named shape
+
+**Why:** a model that writes a deck's HTML or a film's recipe by hand spends many tokens, can drift between tools, and can
+put a conversation's planted text into a page as code. Filling in a shape costs little, names every mistake at once,
+and its text is only ever text. Each tool draws the same board its own way.
+
+| file | holds |
+|---|---|
+| `read.js` | the door's rule: read a board, name every problem at once, give scenes |
+| `toldTwice.js` | `told-twice`: a cast acts a system out, turns into it, and the story runs again for real |
+| `whatWeFound.js` | `what-we-found`: what was checked, what was found, what is not known, what is next |
+| `conversation.js` | a conversation as sources, and the rule that a claim's numbers are in the messages it cites |
+| `fields.js` | reading data while keeping every problem |
+| `words.js` | the limits on each kind of text, and a part's labels |
+
+```js
+import { readStoryboard } from 'footprint-story/storyboard';
+
+const board = readStoryboard(fromAnAgent, { conversation: [{ id: 'm7', text: 'it waited 41 minutes' }] });
+board.scenes[1];   // { id, part, look, title, narration, beat }: title and narration are a film's scene as they are
+```
+
+The number rule covers every word a `what-we-found` says or shows: a claim against the messages it cites, and anything that
+cites none against the whole conversation. What a model writes must use plain digits: a disguised number (hidden characters,
+superscripts, odd separators, direction controls) is refused rather than read. It does not catch a claim that
+is wrong in words, a number spelled out, or a sign (`-41` reads as 41). `verified` is true only when a shape's claims really were checked: `told-twice`
+makes none, and with no conversation given nothing is checked.

package/src/storyboard/conversation.js

@@ -0,0 +1,88 @@
+/**
+ * A conversation, as the sources of a storyboard: messages in order, each with an id a claim can cite. This shape is the
+ * library's own: an app maps its history onto it. Whoever writes the storyboard may get things wrong, so a claim says which
+ * messages it rests on, and every number in it must be in one of them.
+ */
+const MOST_MESSAGES = 5000;
+
+const THOUSANDS = /^\d{1,3}(?:[,   ]\d{3})+(?:\.\d+)?$/;
+const GROUPING = /[,   ]/g;
+const FULLWIDTH = /[０-９]/g;
+/** Digits of any kind, kept with whatever joins them into one number, so a source's '10²' or '1 250' is not also a 10 or a 250. */
+const NUMBER = /[\p{Nd}\p{No}]+(?:[.,，．   ․﹐﹒][\p{Nd}\p{No}]+)*/gu;
+const BIDI = /[؜‎‏‪-‮⁦-⁩]/;
+/**
+ * Two digits with something between them that a reader cannot read as what it is: anything but a visible letter or printable
+ * ASCII. One class, with nothing that can match in two ways, so its cost stays linear; invisible letters are marked first.
+ */
+const ODDLY_JOINED = /\p{Nd}[^\p{L}\p{Nd}\x20-\x7E]+\p{Nd}/u;
+const INVISIBLE = /\p{Default_Ignorable_Code_Point}/gu;
+/** A control character other than a tab or a line break. */
+const CONTROL = /[^\P{Cc}\t\n\r]/u;
+const plainWidth = (text) => String(text).replace(FULLWIDTH, (d) => String.fromCharCode(d.charCodeAt(0) - 0xFF10 + 48));
+const digitCount = (text) => (text.match(/\p{Nd}/gu) ?? []).length;
+
+/**
+ * Every number in a text: digits in any script, fullwidth ones read as plain, hidden characters ignored. Grouping goes only
+ * when it is real thousands ('1,250.5' → '1250.5', and with a thin space too); anything else stays as written, so '3,5' is
+ * not 35 and '10²' is not 10.
+ */
+export function numbersIn(text) {
+  const seen = plainWidth(text).replace(/[\p{Cf}\p{Default_Ignorable_Code_Point}]/gu, '');
+  return [...new Set((seen.match(NUMBER) ?? []).map((n) => (THOUSANDS.test(n) ? n.replace(GROUPING, '') : n)))];
+}
+
+/**
+ * Whether words write a number in a form that may not show what it reads as: a compatibility digit (10², ½, ①, ㏳), digits
+ * joined by anything odd, or direction controls that reorder what is shown. What a model writes must use plain digits, so
+ * these are refused rather than read: the rule allows one form instead of chasing each disguise.
+ */
+function disguisesNumber(text) {
+  const plain = plainWidth(text);
+  if (/\p{No}/u.test(plain) || digitCount(plain.normalize('NFKC')) !== digitCount(plain)) return true;
+  return digitCount(plain) > 0 && (BIDI.test(plain) || CONTROL.test(plain) || ODDLY_JOINED.test(plain.replace(INVISIBLE, '​')));
+}
+const DISGUISED = 'writes a number in a form that cannot be checked: use plain digits, with no hidden or special characters near them';
+
+/**
+ * [{id, who?, text}] read and checked: a Map of id → text. Throws, naming the place, on anything it cannot use, as what
+ * is passed here comes from the app, not from whoever writes the storyboard.
+ */
+export function readConversation(messages) {
+  if (!Array.isArray(messages)) throw new TypeError('a conversation is a list of messages: [{id, text}]');
+  if (messages.length > MOST_MESSAGES) throw new RangeError(`a conversation of ${messages.length} messages is too long: ${MOST_MESSAGES} is the most`);
+  const out = new Map();
+  messages.forEach((m, i) => {
+    if (m === null || typeof m !== 'object' || typeof m.id !== 'string' || !m.id.trim()) throw new TypeError(`message ${i}: id must be text with something in it`);
+    if (typeof m.text !== 'string') throw new TypeError(`message ${i} ("${m.id}"): text must be text`);
+    if (out.has(m.id)) throw new TypeError(`message ${i}: two messages have the id "${m.id}"`);
+    out.set(m.id, m.text);
+  });
+  return out;
+}
+
+/**
+ * Checks one claim against the messages it cites, keeping any problem on `fields`: every message it cites is there, and
+ * every number it says is in one of them. `claim`: the words it says. With no conversation there is nothing to check
+ * against, and a board says so (`verified: false`).
+ */
+export function checkClaim(fields, conversation, at, claim, cited) {
+  if (!conversation) return;
+  if (!cited.length) { fields.say(`${at}.sources`, 'must name the messages this rests on'); return; }
+  const missing = cited.filter((id) => !conversation.has(id));
+  for (const id of missing) fields.say(`${at}.sources`, `names "${id}", which the conversation does not have`);
+  if (missing.length) return;
+  if (disguisesNumber(claim)) { fields.say(at, DISGUISED); return; }
+  const said = new Set(cited.flatMap((id) => numbersIn(conversation.get(id))));
+  for (const n of numbersIn(claim)) {
+    if (!said.has(n)) fields.say(at, `says ${n}, which none of its sources (${cited.join(', ')}) says: fix the number, cite the message that says it, or move it to what you are not sure about`);
+  }
+}
+
+/** Words that cite no message (a title, what is said at the end, what happens next): any number in them must be somewhere in the conversation. */
+export function checkAnywhere(fields, conversation, at, text) {
+  if (!conversation) return;
+  if (disguisesNumber(text)) { fields.say(at, DISGUISED); return; }
+  const said = new Set([...conversation.values()].flatMap((message) => numbersIn(message)));
+  for (const n of numbersIn(text)) if (!said.has(n)) fields.say(at, `says ${n}, which the conversation never says: fix the number, or take it out`);
+}

package/src/storyboard/fields.js

@@ -0,0 +1,54 @@
+/**
+ * Fields: reading plain data a person or a model wrote, keeping every problem instead of stopping at the first, so one
+ * answer can name everything to fix. Reads own properties only. A key it does not know is a problem, naming the keys
+ * there are, so a misspelt name is never silently ignored.
+ */
+const MOST_NAME = 40;   // of an unknown key, as a problem repeats it: what comes back to a model is short
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const join = (at, key) => (typeof key === 'number' ? `${at}[${key}]` : at ? `${at}.${key}` : key);
+
+/** A reader with its own list of problems, each {at, message}: `at` is the place in the data, as it is written. */
+export function fieldReader() {
+  const problems = [];
+  const say = (at, message) => { problems.push({ at, message }); return null; };
+  return {
+    problems,
+    say,
+    /** A copy of `value` holding only its own `keys`, each read once, so nothing inherited counts; null when it is not an object. */
+    object(value, at, keys) {
+      if (!isObject(value)) return say(at, `must be an object with ${keys.join(', ')}`);
+      const own = Object.create(null);
+      for (const key of Object.keys(value)) {
+        if (keys.includes(key)) own[key] = value[key];
+        else say(join(at, key.length > MOST_NAME ? `${key.slice(0, MOST_NAME)}…` : key), `is not a field here (the fields are ${keys.join(', ')})`);
+      }
+      return own;
+    },
+    /** A field's text, trimmed; null when it is missing and may be, or wrong. Never longer than `most`. */
+    text(parent, key, at, { most, optional = false } = {}) {
+      const place = join(at, key), v = parent && Object.hasOwn(parent, key) ? parent[key] : undefined;
+      if (v === undefined) return optional ? null : say(place, 'is missing');
+      if (typeof v !== 'string' || !v.trim()) return say(place, 'must be text with something in it');
+      if (v.trim().length > most) return say(place, `is ${v.trim().length} characters, and ${most} is the most it may be: shorten it`);
+      return v.trim();
+    },
+    /** A field's list, between `least` and `most` long; empty when it is wrong (the problem is kept). */
+    list(parent, key, at, { least = 0, most, optional = false } = {}) {
+      const place = join(at, key), v = parent && Object.hasOwn(parent, key) ? parent[key] : undefined;
+      if (v === undefined) { if (!optional) say(place, 'is missing'); return []; }
+      if (!Array.isArray(v)) { say(place, 'must be a list'); return []; }
+      if (v.length < least) say(place, `has ${v.length}, and it needs at least ${least}`);
+      if (v.length > most) { say(place, `has ${v.length}, and ${most} is the most it may have`); return v.slice(0, most); }
+      return v;
+    },
+  };
+}
+
+/** A deep copy's freeze: what a reader hands out is never edited by whoever draws it. */
+export function deepFreeze(value) {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const v of Object.values(value)) deepFreeze(v);
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/storyboard/read.js

@@ -0,0 +1,60 @@
+/**
+ * The door's one rule: a storyboard is plain data on a named shape, and reading it gives scenes both tools can draw. It
+ * names every problem at once, so whoever wrote it fixes them in one pass. No text here is trusted: whoever draws a scene
+ * escapes it as text.
+ */
+import { fieldReader, deepFreeze } from './fields.js';
+import { MOST } from './words.js';
+import { readConversation } from './conversation.js';
+import { toldTwice } from './toldTwice.js';
+import { whatWeFound } from './whatWeFound.js';
+
+const SHAPES = Object.freeze({ [toldTwice.name]: toldTwice, [whatWeFound.name]: whatWeFound });
+const MOST_PROBLEMS = 40;
+const SHARED = ['shape', 'title', 'subtitle', 'lang'];
+const OWN = { 'told-twice': ['analogy', 'intro', 'items', 'flow', 'together', 'remember', 'closing', 'labels'], 'what-we-found': ['intro', 'checked', 'found', 'unsure', 'next', 'closing', 'labels'] };
+
+/** The shapes there are, for whoever is about to write one: [{name, about, fills}]. `fills` is a worked outline of its fields. */
+export const storyShapes = () => Object.values(SHAPES).map(({ name, about, fills }) => ({ name, about, fills }));
+
+
+/** No more problems than whoever wrote this can use in one pass: what comes back to a model stays short. */
+const shortList = (problems) => (problems.length > MOST_PROBLEMS ? [...problems.slice(0, MOST_PROBLEMS), { at: '', message: `and ${problems.length - MOST_PROBLEMS} more: fix these first` }] : problems);
+
+/** What reading finds: {board, problems}. `board` only when there are no problems. */
+function readAll(raw, { conversation } = {}) {
+  const f = fieldReader();
+  let parsed = raw;
+  if (typeof raw === 'string') {
+    try { parsed = JSON.parse(raw); } catch (e) { return { board: null, problems: [{ at: 'storyboard', message: `is not valid JSON: ${e.message}` }] }; }
+  }
+  const known = Object.keys(SHAPES), name = parsed !== null && typeof parsed === 'object' && Object.hasOwn(parsed, 'shape') ? parsed.shape : undefined;
+  if (typeof name !== 'string' || !Object.hasOwn(SHAPES, name)) return { board: null, problems: [{ at: 'shape', message: `must be one of ${known.join(', ')}` }] };
+  const sources = conversation ? readConversation(conversation) : null;   // the app's own input: a mistake here is the app's, and throws
+  try {
+    const input = f.object(parsed, '', [...SHARED, ...OWN[name]]);
+    if (!input) return { board: null, problems: f.problems };
+    const base = { title: f.text(input, 'title', '', { most: MOST.title }), subtitle: f.text(input, 'subtitle', '', { most: MOST.subtitle, optional: true }), lang: f.text(input, 'lang', '', { most: 20, optional: true }) };
+    const drawn = SHAPES[name].read(f, input, base, sources);
+    if (f.problems.length) return { board: null, problems: shortList(f.problems) };
+    // verified only where a shape's claims really were checked: told-twice tells a system's story, and makes none to check
+    return { board: deepFreeze({ shape: name, ...base, verified: Boolean(sources && SHAPES[name].checksClaims), ...drawn }), problems: [] };
+  } catch {   // not plain data (a getter that throws, a proxy): what it is given to read never stops the reader
+    return { board: null, problems: shortList([...f.problems, { at: 'storyboard', message: 'could not be read: it must be plain data' }]) };
+  }
+}
+
+/** Every problem in a storyboard, [{at, message}]; [] when it can be drawn. Never throws on what it is given to read. `conversation`: the messages its claims cite, [{id, text}]. */
+export const storyboardProblems = (input, options) => readAll(input, options).problems;
+
+/**
+ * A storyboard read: frozen {shape, title, subtitle, lang, verified, labels, scenes, …}. Each scene is {id, part, look, title,
+ * narration, beat}: `title` and `narration` make it a scene of a film's storyboard as they are, and `beat` says what happens.
+ * Throws when it cannot be drawn, its `problems` listing all of them. `verified`: whether its claims were checked against a conversation.
+ */
+export function readStoryboard(input, options) {
+  const { board, problems } = readAll(input, options);
+  if (board) return board;
+  const list = problems.map((p) => `${p.at ? `${p.at} ` : ''}${p.message}`);
+  throw Object.assign(new TypeError(`this storyboard has ${list.length} problem${list.length === 1 ? '' : 's'}:\n- ${list.join('\n- ')}`), { problems });
+}

package/src/storyboard/toldTwice.js

@@ -0,0 +1,89 @@
+/**
+ * told-twice: one picture, told twice. A cast of people and everyday things acts a system out, each turns into the real
+ * thing where it stood, then the same story runs again for real. Written once, so the two tellings cannot drift: every
+ * real moment is the same moment as a story one, by construction.
+ */
+import { MOST, isSafeId, readLabels, saysName } from './words.js';
+import { deepFreeze } from './fields.js';
+
+const LABELS = Object.freeze({ story: 'The story', turn: 'The turn', real: 'The real thing', remember: 'To remember' });
+const WHO = { name: 20, line: 36 };   // what fits a piece in a row of five
+
+function readWho(f, value, at) {
+  const who = f.object(value, at, ['name', 'line', 'icon']);
+  if (!who) return { name: null, line: null, icon: null };
+  return { name: f.text(who, 'name', at, { most: WHO.name }), line: f.text(who, 'line', at, { most: WHO.line }), icon: f.text(who, 'icon', at, { most: MOST.icon, optional: true }) };
+}
+
+function readTold(f, value, at) {
+  const told = f.object(value, at, ['headline', 'notes']);
+  return told ? { title: f.text(told, 'headline', at, { most: MOST.headline }), narration: f.text(told, 'notes', at, { most: MOST.notes }) } : { title: null, narration: null };
+}
+
+function readItem(f, value, i, seen) {
+  const at = `items[${i}]`, item = f.object(value, at, ['id', 'cast', 'real', 'turn']);
+  if (!item) return null;
+  const safe = isSafeId(item.id);
+  if (!safe) f.say(`${at}.id`, 'must be lower case letters, digits and dashes');
+  else if (seen.has(item.id)) f.say(`${at}.id`, `is "${item.id}" again: each item has an id of its own`);
+  else seen.add(item.id);
+  const cast = readWho(f, item.cast, `${at}.cast`), real = readWho(f, item.real, `${at}.real`);
+  const turn = f.object(item.turn, `${at}.turn`, ['headline', 'callout', 'notes']);
+  const callout = turn ? f.text(turn, 'callout', `${at}.turn`, { most: MOST.callout }) : null;
+  for (const who of [cast, real]) {
+    if (callout && who.name && !saysName(callout, who.name)) f.say(`${at}.turn.callout`, `must say both names, so the reader can tie them together, and it does not say "${who.name}"`);
+  }
+  return { id: safe ? item.id : null, cast, real, callout, title: turn ? f.text(turn, 'headline', `${at}.turn`, { most: MOST.headline }) : null, narration: turn ? f.text(turn, 'notes', `${at}.turn`, { most: MOST.notes }) : null };
+}
+
+/** A moment of the flow: its path along the row of items, what is called on each hop, and its words in each telling. */
+function readMoment(f, value, i, order) {
+  const at = `flow[${i}]`, moment = f.object(value, at, ['path', 'calls', 'story', 'real']);
+  if (!moment) return null;
+  const path = [...f.list(moment, 'path', at, { least: 1, most: 8 })], calls = f.list(moment, 'calls', at, { most: 7, optional: true });
+  path.forEach((id, k) => {
+    if (!order.includes(id)) f.say(`${at}.path[${k}]`, `is not an item (they are ${order.join(', ')})`);
+    else if (k && id === path[k - 1]) f.say(`${at}.path[${k}]`, `goes from "${id}" to itself`);
+    else if (k && order.includes(path[k - 1]) && Math.abs(order.indexOf(id) - order.indexOf(path[k - 1])) !== 1) f.say(`${at}.path[${k}]`, `goes from "${path[k - 1]}" to "${id}", which do not stand next to each other: items stand in one row, in the order written`);
+  });
+  if (calls.length && path.length && calls.length !== path.length - 1) f.say(`${at}.calls`, `has ${calls.length}, and this path has ${path.length - 1} hop${path.length === 2 ? '' : 's'}: one call per hop`);
+  const called = calls.map((_, k) => f.text(calls, k, `${at}.calls`, { most: MOST.call }));
+  return { path, calls: called, story: readTold(f, moment.story, `${at}.story`), real: readTold(f, moment.real, `${at}.real`) };
+}
+
+export const toldTwice = Object.freeze({
+  name: 'told-twice',
+  about: 'A cast of people and everyday things acts a system out, each turns into the real thing where it stood, then the same story runs again for real. For explaining a system to people who do not work on it.',
+  fills: deepFreeze({
+    shape: 'told-twice', title: 'One picture, told twice', subtitle: '(optional)', analogy: 'a café stands in for a web service', intro: 'what is said on the title',
+    items: [{ id: 'customer', cast: { name: 'Customer', line: 'wants a coffee', icon: 'person-asking' }, real: { name: 'Browser', line: 'asks for a page', icon: 'window' },
+      turn: { headline: 'The customer turns into the browser', callout: 'The customer is the browser: it asks, then waits', notes: 'what is said' } }, '… 2 or more, in the row they stand in'],
+    flow: [{ path: ['customer', 'cashier'], calls: ['GET /order'], story: { headline: 'They tell the cashier', notes: 'what is said' }, real: { headline: 'It sends a request to the API', notes: 'what is said' } }, '… every item acts'],
+    together: { headline: '(optional) a last turn showing them all', notes: 'what is said' }, remember: ['2 to 4 things to remember'], closing: 'what is said at the end',
+    labels: { story: 'The café', turn: '…', real: '…', remember: '…' },
+  }),
+
+  read(f, input, base) {
+    const seen = new Set(), items = f.list(input, 'items', '', { least: 2, most: 8 }).map((v, i) => readItem(f, v, i, seen)).filter(Boolean);
+    const order = items.map((it) => it.id).filter(Boolean), flow = f.list(input, 'flow', '', { least: 1, most: 20 }).map((v, i) => readMoment(f, v, i, order)).filter(Boolean);
+    const acting = new Set(flow.flatMap((m) => m.path));
+    for (const id of order) if (!acting.has(id)) f.say('flow', `never reaches "${id}": every item acts in the story before it turns`);
+    const analogy = f.text(input, 'analogy', '', { most: MOST.analogy }), labels = readLabels(f, input, base.lang, LABELS);
+    const together = input.together === undefined ? null : readTold(f, input.together, 'together');
+    const points = f.list(input, 'remember', '', { least: 2, most: 4 }).map((_, i, all) => f.text(all, i, 'remember', { most: MOST.point }));
+    const intro = f.text(input, 'intro', '', { most: MOST.notes }), closing = f.text(input, 'closing', '', { most: MOST.notes });
+    const path = (m, look, k) => ({ id: `${look === 'cast' ? 'story' : 'real'}-${k + 1}`, part: look === 'cast' ? 'story' : 'real', look, ...(look === 'cast' ? m.story : m.real), beat: { kind: 'path', path: m.path, calls: look === 'cast' ? [] : m.calls } });
+    return {
+      analogy, labels,
+      items: items.map(({ id, cast, real }) => ({ id, cast, real })),
+      scenes: [
+        { id: 'title', part: 'title', look: 'cast', title: base.title, narration: intro, beat: { kind: 'title', subtitle: base.subtitle } },
+        ...flow.map((m, k) => path(m, 'cast', k)),
+        ...items.map((it) => ({ id: `turn-${it.id}`, part: 'turn', look: 'cast', title: it.title, narration: it.narration, beat: { kind: 'turn', item: it.id, callout: it.callout } })),
+        ...(together ? [{ id: 'together', part: 'turn', look: 'cast', ...together, beat: { kind: 'together' } }] : []),
+        ...flow.map((m, k) => path(m, 'real', k)),
+        { id: 'remember', part: 'remember', look: 'real', title: labels.remember, narration: closing, beat: { kind: 'points', points } },
+      ],
+    };
+  },
+});

package/src/storyboard/whatWeFound.js

@@ -0,0 +1,64 @@
+/**
+ * what-we-found: what a piece of work or a conversation came to, in the order a reader asks: what was looked at, what was
+ * found, what is still not known, what happens next. A claim names the messages it rests on, and "not sure" has a part of
+ * its own, and must be written even when it is empty, so a story cannot sound surer than the work was.
+ */
+import { MOST, readLabels } from './words.js';
+import { deepFreeze } from './fields.js';
+import { checkAnywhere, checkClaim } from './conversation.js';
+
+const LABELS = Object.freeze({ checked: 'What we checked', found: 'What we found', unsure: 'What we are not sure about', next: 'What happens next' });
+
+function readSources(f, value, at) {
+  return f.list(value, 'sources', at, { most: 12, optional: true }).map((_, i, all) => f.text(all, i, `${at}.sources`, { most: MOST.source })).filter(Boolean);
+}
+
+export const whatWeFound = Object.freeze({
+  name: 'what-we-found',
+  checksClaims: true,
+  about: 'What a piece of work or a conversation came to: what was checked, what was found, what is still not known, what happens next. Claims name their sources, and a number must be in a source.',
+  fills: deepFreeze({
+    shape: 'what-we-found', title: 'Why the nightly job slowed down', subtitle: '(optional)', intro: 'what is said on the title',
+    checked: [{ what: 'Disk space', found: '40% full, so not the cause', notes: '(optional) what is said', sources: ['m3'] }],
+    found: [{ headline: 'The job waits on a lock', line: 'It waited 41 minutes on 3 nights', notes: 'what is said', sources: ['m7', 'm9'] }],
+    unsure: [{ what: 'Whether Tuesday had the same cause', why: 'there are no logs from that night', notes: '(optional) what is said' }, '… or [] when nothing is, which you must say'],
+    next: ['1 to 4 things that happen next'], closing: 'what is said at the end',
+    labels: { checked: '…', found: '…', unsure: '…', next: '…' },
+  }),
+
+  read(f, input, base, conversation) {
+    const labels = readLabels(f, input, base.lang, LABELS);
+    const checked = f.list(input, 'checked', '', { least: 1, most: 6 }).map((v, i) => {
+      const at = `checked[${i}]`, c = f.object(v, at, ['what', 'found', 'notes', 'sources']);
+      if (!c) return null;
+      const what = f.text(c, 'what', at, { most: MOST.line }), found = f.text(c, 'found', at, { most: MOST.headline }), notes = f.text(c, 'notes', at, { most: MOST.notes, optional: true }), sources = readSources(f, c, at);
+      checkClaim(f, conversation, at, [what, found, notes].filter(Boolean).join(' '), sources);
+      return { id: `checked-${i + 1}`, part: 'checked', look: null, title: found, narration: notes ?? (what && found ? `${what}: ${found}` : null), beat: { kind: 'card', group: 'checked', tone: null, name: what, line: found, sources } };
+    });
+    const found = f.list(input, 'found', '', { least: 1, most: 3 }).map((v, i) => {
+      const at = `found[${i}]`, c = f.object(v, at, ['headline', 'line', 'notes', 'sources']);
+      if (!c) return null;
+      const title = f.text(c, 'headline', at, { most: MOST.headline }), line = f.text(c, 'line', at, { most: MOST.line }), notes = f.text(c, 'notes', at, { most: MOST.notes }), sources = readSources(f, c, at);
+      checkClaim(f, conversation, at, [title, line, notes].filter(Boolean).join(' '), sources);
+      return { id: `found-${i + 1}`, part: 'found', look: null, title, narration: notes, beat: { kind: 'card', group: 'found', tone: 'ok', name: line, line: null, sources } };
+    });
+    const unsure = f.list(input, 'unsure', '', { most: 3 }).map((v, i) => {
+      const at = `unsure[${i}]`, c = f.object(v, at, ['what', 'why', 'notes']);
+      if (!c) return null;
+      const what = f.text(c, 'what', at, { most: MOST.headline }), why = f.text(c, 'why', at, { most: MOST.line }), notes = f.text(c, 'notes', at, { most: MOST.notes, optional: true });
+      checkAnywhere(f, conversation, at, [what, why, notes].filter(Boolean).join(' '));
+      return { id: `unsure-${i + 1}`, part: 'unsure', look: null, title: what, narration: notes ?? (what && why ? `${what}: ${why}` : null), beat: { kind: 'card', group: 'unsure', tone: 'warn', name: why, line: null, sources: [] } };
+    });
+    const points = f.list(input, 'next', '', { least: 1, most: 4 }).map((_, i, all) => f.text(all, i, 'next', { most: MOST.point }));
+    const intro = f.text(input, 'intro', '', { most: MOST.notes }), closing = f.text(input, 'closing', '', { most: MOST.notes });
+    for (const [at, text] of [['title', base.title], ['subtitle', base.subtitle], ['intro', intro], ['closing', closing], ...points.map((p, i) => [`next[${i}]`, p]), ...Object.entries(labels).map(([key, word]) => [`labels.${key}`, word])]) if (text) checkAnywhere(f, conversation, at, text);
+    return {
+      labels,
+      scenes: [
+        { id: 'title', part: 'title', look: null, title: base.title, narration: intro, beat: { kind: 'title', subtitle: base.subtitle } },
+        ...[...checked, ...found, ...unsure].filter(Boolean),
+        { id: 'next', part: 'next', look: null, title: labels.next, narration: closing, beat: { kind: 'points', points } },
+      ],
+    };
+  },
+});

package/src/storyboard/words.js

@@ -0,0 +1,29 @@
+/** The words a shape keeps as limits, and the labels of its parts. */
+
+/** The most characters each kind of text may be, so what a model writes fits what a film or a deck can show. */
+export const MOST = Object.freeze({ title: 90, subtitle: 120, headline: 120, notes: 1000, name: 40, line: 70, callout: 140, call: 24, point: 90, analogy: 58, label: 40, icon: 40, id: 40, source: 80 });
+
+const SAFE_ID = /^[a-z0-9][a-z0-9-]*$/;
+/** An item's id: lower case letters, digits and dashes, so a tool can name a piece or a scene by it. */
+export const isSafeId = (id) => typeof id === 'string' && SAFE_ID.test(id) && id.length <= MOST.id;
+
+/** A part's labels: each one given, else the shape's English default. Another language gives its own: English words on a slide of another language would be wrong. */
+export function readLabels(fields, input, lang, defaults) {
+  const given = input.labels === undefined ? {} : fields.object(input.labels, 'labels', Object.keys(defaults)) ?? {};
+  const english = !lang || /^en([-_]|$)/i.test(lang);
+  return Object.fromEntries(Object.entries(defaults).map(([key, word]) => {
+    const own = fields.text(given, key, 'labels', { most: MOST.label, optional: true });
+    if (!own && !english && !fields.problems.some((p) => p.at === `labels.${key}`)) fields.say(`labels.${key}`, `is needed: this story is in "${lang}", and the label is "${word}" in English`);
+    return [key, own ?? word];
+  }));
+}
+
+/** The scripts written without spaces between words, where a name runs straight on into the next word. */
+const UNSPACED = /[\p{scx=Han}\p{scx=Hira}\p{scx=Kana}\p{scx=Thai}\p{scx=Lao}\p{scx=Khmr}\p{scx=Mymr}]/u;
+
+/** Whether a text says a name: as a whole word, in any case, so "API" is not found in "rapid"; in a script with no spaces, anywhere. */
+export function saysName(text, name) {
+  const letters = [...name], escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const before = UNSPACED.test(letters[0]) ? '' : '(?<![\\p{L}\\p{N}])', after = UNSPACED.test(letters.at(-1)) ? '' : '(?![\\p{L}\\p{N}])';
+  return new RegExp(`${before}${escaped}${after}`, 'iu').test(text);
+}

package/storyboard.d.ts

@@ -0,0 +1,57 @@
+/**
+ * footprint-story/storyboard — a story written as plain data on a named shape, for a film and a deck to draw the same way.
+ * Pure: runs anywhere, imports nothing. Nothing here draws.
+ */
+
+/** The shapes a storyboard may take. */
+export type StoryShapeName = 'told-twice' | 'what-we-found';
+/** A shape, for whoever is about to write one: what it is for, and a worked outline of its fields. */
+export interface StoryShape { readonly name: StoryShapeName; readonly about: string; readonly fills: object }
+/** One thing to fix: `at` is the place in the data, as it is written. */
+export interface StoryboardProblem { readonly at: string; readonly message: string }
+/** A message a claim can cite. An app maps its history onto this. */
+export interface StoryMessage { readonly id: string; readonly who?: string; readonly text: string }
+export interface StoryboardOptions {
+  /** The messages the storyboard's claims rest on: every message cited must be here, and every number in a claim in one it cites. */
+  readonly conversation?: readonly StoryMessage[];
+}
+/** What a scene does. */
+export type StoryBeat =
+  | { readonly kind: 'title'; readonly subtitle: string | null }
+  /** Along the row of items, in order; on a told-twice story's real telling, what is called on each hop. */
+  | { readonly kind: 'path'; readonly path: readonly string[]; readonly calls: readonly string[] }
+  /** An item turns into the real thing where it stood, and the callout says both names. */
+  | { readonly kind: 'turn'; readonly item: string; readonly callout: string }
+  | { readonly kind: 'together' }
+  | { readonly kind: 'points'; readonly points: readonly string[] }
+  /** One card comes in beside the others of its group. */
+  | { readonly kind: 'card'; readonly group: string; readonly tone: 'ok' | 'warn' | null; readonly name: string; readonly line: string | null; readonly sources: readonly string[] };
+/** One moment. `title` and `narration` make it a scene of a film's storyboard as they are. */
+export interface StoryScene { readonly id: string; readonly part: string; readonly look: 'cast' | 'real' | null; readonly title: string; readonly narration: string; readonly beat: StoryBeat }
+/** Someone or something in a told-twice row. */
+export interface StoryWho { readonly name: string; readonly line: string; readonly icon: string | null }
+/** A storyboard read: checked and frozen. */
+export interface Storyboard {
+  readonly shape: StoryShapeName;
+  readonly title: string;
+  readonly subtitle: string | null;
+  readonly lang: string | null;
+  /** Whether its claims really were checked against a conversation: never for told-twice, which makes none. */
+  readonly verified: boolean;
+  /** Each part's label, by part. */
+  readonly labels: Readonly<Record<string, string>>;
+  readonly scenes: readonly StoryScene[];
+  /** told-twice: the row, in order. */
+  readonly items?: readonly { readonly id: string; readonly cast: StoryWho; readonly real: StoryWho }[];
+  /** told-twice: says what stands in for what. */
+  readonly analogy?: string;
+}
+
+/** The shapes there are. */
+export function storyShapes(): readonly StoryShape[];
+/** Every problem in a storyboard (data or JSON text); empty when it can be drawn. Never throws on what it is given to read. */
+export function storyboardProblems(input: unknown, options?: StoryboardOptions): readonly StoryboardProblem[];
+/** A storyboard read. Throws when it cannot be drawn, its `problems` listing all of them. */
+export function readStoryboard(input: unknown, options?: StoryboardOptions): Storyboard;
+/** Every number in a text, with any thousands commas taken out: '1,250.5' → '1250.5'. */
+export function numbersIn(text: string): readonly string[];

package/storyboard.js

@@ -0,0 +1,10 @@
+// footprint-story/storyboard — a story written as plain data on a named shape, for a film and a deck to draw the same way.
+// Pure: runs anywhere (browser or Node), imports nothing, and loads only when imported. Nothing here draws: StoryDeck makes
+// its pieces and clicks from a board, StoryReel its scenes and recipe.
+//
+//   storyShapes()                                → [{ name, about, fills }]: the shapes there are, and a worked outline of each
+//   storyboardProblems(input, { conversation })  → [{ at, message }]: everything to fix, all at once
+//   readStoryboard(input, { conversation })      → the board: checked and frozen, with its scenes
+
+export { storyShapes, storyboardProblems, readStoryboard } from './src/storyboard/read.js';
+export { numbersIn } from './src/storyboard/conversation.js';