From ed76a9c8dfce50e932a0141618a163fad338041d Mon Sep 17 00:00:00 2001
From: nichinichisou <nichinichisou0609@outlook.com>
Date: Wed, 14 Oct 2026 19:16:13 +0800
Subject: [PATCH 1/3] feat(story-author): report fixes for script problems, and
 pace each line

A script's problems now say how to fix them, not only what is wrong, and
the renderer reports how long each line takes.

Every problem whose fix is known carries it as JSON Patch operations on
the script document: an unknown key is renamed to the nearest key of the
format (when the object does not hold that key already), an unknown name
is replaced by the nearest one the site has, a repeated beat id takes the
first free suffix, and two characters on one position put the later one
on the nearest free position. `--fix <file>` on `check` and `render`
writes the script with those fixes applied (later beats first, so the
beats a fix adds do not move the ones after it) and checks the written
script again, reporting which fixes went in and where the fixed script
stands.

A line that overflows the talk window is measured in the browser, laid
out again with TextMeshPro's word wrapping (the breaks the game's text
engine takes, CJK line breaking rules included), and comes with a fix
that breaks the text where the game breaks it and, where the window holds
fewer lines, spreads it over beats of the same speaker after it.

`render` frames also carry the line's pacing in story seconds: the
characters the typewriter types, the time until its text is fully shown,
and the hold auto mode adds from the base story's talk timings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/story-author.md               |  64 ++++++++--
 scripts/lib/story-author/page.js   |  51 +++++++-
 scripts/lib/story-author/script.js | 193 ++++++++++++++++++++++++++---
 scripts/story-author.mjs           |  61 ++++++---
 tests/unit/story-author.test.mjs   | 133 +++++++++++++++++++-
 5 files changed, 452 insertions(+), 50 deletions(-)

diff --git a/docs/story-author.md b/docs/story-author.md
index e9d464a..01b375a 100644
--- a/docs/story-author.md
+++ b/docs/story-author.md
@@ -33,6 +33,7 @@ node scripts/story-author.mjs new stories/10002.json $S > story.json   # 4. a st
 node scripts/story-author.mjs check story.json $S                  # 5. errors and warnings with JSON pointers
 node scripts/story-author.mjs render story.json $S --out shots     # 6. one picture per line, and a contact sheet
 #    look at shots/sheet.png (and shots/line-*.png), fix, repeat 5-6
+#    (--fix <file> on check and render writes the script with the fixes the tool knows applied)
 node scripts/story-author.mjs build story.json $S --name my-story  # 7. into the site
 node scripts/story-author.mjs serve $S                             # 8. URLs to watch it in examples/story
 ```
@@ -98,15 +99,16 @@ stage, three lines). Redirect it to a file and edit it.
 
 ### check
 
-`check <script>`: the script's errors and warnings. A script without errors also reports its number of lines and
-scenes and the CSS font family its text is drawn with.
+`check <script> [--fix <file>]`: the script's errors and warnings. A script without errors also reports its number of
+lines and scenes and the CSS font family its text is drawn with.
 
 ```json
 {
   "ok": false, "language": "zh-Hans",
   "errors": [{ "path": "/beats/2/motion", "code": "unknownMotion",
                "message": "motion \"mtn_nodd01\" does not exist in adv_live2d_…; did you mean \"mtn_nod01\"?",
-               "expected": ["mtn_angry01", "…"], "suggestion": "mtn_nod01" }],
+               "expected": ["mtn_angry01", "…"], "suggestion": "mtn_nod01",
+               "fix": [{ "op": "replace", "path": "/beats/2/motion", "value": "mtn_nod01" }] }],
   "warnings": [{ "path": "/beats/0/say", "code": "speakerOffStage", "message": "tomori speaks from off stage" }]
 }
 ```
@@ -115,23 +117,51 @@ Every problem has `path`, a JSON pointer to the value in the script, `code` and
 comes with `expected` (the names that do, or `expectedCount` when there are more than 40) and, when one is close,
 `suggestion`.
 
+### Fixes
+
+A problem whose fix is known has `fix`: [JSON Patch](https://www.rfc-editor.org/rfc/rfc6902) operations on the script
+document (`replace`, `add`, and `move` within one object to rename a key, which keeps the key's place). The fixes:
+
+| Code | Fix |
+|---|---|
+| `unknownKey` | The key renamed to the nearest key of the format, when the object does not have that key already. |
+| `unknownLanguage`, `unknownFont`, `unknownPosition`, `unknownCamera`, `unknownModel`, `unknownStage`, `unknownMusic`, `unknownMotion`, `unknownExpression` | The nearest name (`suggestion`) written in. |
+| `unknownCast` | The nearest cast id written in; in `positions`, the key renamed, when the beat does not place that cast member already. |
+| `duplicateId` | The id with the first free `_<n>` after it (`promise_2`). |
+| `positionTaken` | The free position nearest the taken one (`suggestion`), the left one of two as near. |
+| `textTooWide`, `textTooTall` | `render`: the text broken where the game's text engine wraps it in the talk window, and, where the window holds fewer lines, spread over beats after it (the same speaker, or narration), as evenly as fits. `suggestion` holds the texts. A line with both warnings has the fix on the first. |
+
+`--fix <file>` on `check` and `render` writes the script with every fix applied to `<file>` (it may be the script
+itself; the fixes of later beats go in first, so the beats a fix adds do not move the others) and checks it again:
+
+```json
+"fixed": { "file": "story.fixed.json", "applied": [{ "path": "/beats/2/motion", "code": "unknownMotion" }],
+           "failed": [], "ok": true, "errors": 0, "warnings": 1 }
+```
+
+`applied` and `failed` (with `message`) list the problems whose fixes went in or could not; `ok`, `errors` and
+`warnings` are how the written script checks (`render` does not render it again). A problem without `fix` needs the
+author: it has no near name, or its fix is a choice of story (who stands where, who speaks).
+
 ### render
 
-`render <script> --out <dir> [--from <line>] [--to <line>] [--width <px>] [--settle <frames>] [--columns <n>]`: plays
-the script in the story player (manual advance, no sound) and saves a picture of each line from `--from` to `--to`
-(line numbers from 0; default every line) once its text is fully shown and `--settle` more frames have passed
-(default 8, at 30 frames per second): `line-<n>.png` at `--width` × width × 6 / 13 pixels (default 1300 × 600), and
-`sheet.png` (`sheet-<n>.png` for more than 12 lines) with every line, its speaker and its text. Earlier pictures of a
-render in `--out` are replaced. A start line after 0 is reached the way the game's shortcut reaches it: the rows before
-it run without being shown.
+`render <script> --out <dir> [--from <line>] [--to <line>] [--width <px>] [--settle <frames>] [--columns <n>]
+[--fix <file>]`: plays the script in the story player (manual advance, no sound) and saves a picture of each line from
+`--from` to `--to` (line numbers from 0; default every line) once its text is fully shown and `--settle` more frames
+have passed (default 8, at 30 frames per second): `line-<n>.png` at `--width` × width × 6 / 13 pixels (default 1300 ×
+600), and `sheet.png` (`sheet-<n>.png` for more than 12 lines) with every line, its speaker and its text. Earlier
+pictures of a render in `--out` are replaced. A start line after 0 is reached the way the game's shortcut reaches it:
+the rows before it run without being shown.
 
 ```json
 {
   "ok": true, "out": "shots", "sheets": ["shots/sheet.png"],
   "frames": [{ "line": 0, "path": "/beats/1", "speaker": "soyo", "text": "…", "image": "shots/line-000.png",
                "talk": { "lines": 1, "fontSize": 36, "width": 431.2, "widthLimit": 1200, "height": 41.6,
-                         "heightLimit": 200, "overflow": false } }],
-  "warnings": [{ "path": "/beats/7", "code": "textTooWide", "message": "line 4 runs past the talk window …" }],
+                         "heightLimit": 200, "overflow": false },
+               "timing": { "characters": 11, "typing": 1.1, "autoHold": 1.6 } }],
+  "warnings": [{ "path": "/beats/7", "code": "textTooWide", "message": "line 4 runs past the talk window …",
+                 "suggestion": ["……", "……"], "fix": [{ "op": "replace", "path": "/beats/7/text", "value": "……" }] }],
   "seconds": 7.7
 }
 ```
@@ -139,7 +169,13 @@ it run without being shown.
 `talk` is the layout of the line's text in the talk window, in the window's units: the number of text lines, the
 point size, the widest line and the height of the text against the room the window has. The talk window does not
 wrap text: a line wider than the window runs past its edge (warning `textTooWide`; break it with `\n`), and more text
-lines than fit run below it (`textTooTall`; split it into two lines of the script).
+lines than fit run below it (`textTooTall`; split it into two lines of the script). Both come with a fix (see
+[Fixes](#fixes)) when breaking the text at the game's word wrap makes it fit.
+
+`timing` is the line's pacing in seconds of story time: `characters`, the characters the typewriter types; `typing`,
+from the line's start until its text is fully shown (the game's ADV frame rate, 30 frames per second); `autoHold`, how
+long auto mode then keeps the line before the next one (`_waitTalkTextUnitTime` per character, at least
+`_minTalkDisplayTime`, from the base story's player settings). A line takes `typing` + `autoHold` in auto mode.
 
 ### build
 
@@ -233,6 +269,8 @@ breaks the line. Keep each text line within the talk window's width; `render` re
 | warning `unusedCast` | A cast member never appears or speaks. |
 | warning `textTooWide`, `textTooTall` | `render`: a line does not fit the talk window. |
 
+Codes with a known fix are listed under [Fixes](#fixes).
+
 ## What the story is made of
 
 The tool compiles a script into the story player's data ([story-data-format.md](story-data-format.md)): an
diff --git a/scripts/lib/story-author/page.js b/scripts/lib/story-author/page.js
index a13df42..e1612e6 100644
--- a/scripts/lib/story-author/page.js
+++ b/scripts/lib/story-author/page.js
@@ -1,11 +1,14 @@
 // The story author's page code: runs in the headless browser (chrome.js) on the author's server (server.js) and
 // posts the pictures it draws to /out/<name>.png. run(job) does one job and returns its report:
 //   story    plays a composed story manifest with StorySession, stepping 1/30 s at a time, and takes a picture of
-//            each line once its text is fully shown (then taps to the next line); contact sheets of the pictures
+//            each line once its text is fully shown (then taps to the next line); contact sheets of the pictures.
+//            Each frame says how long the line took to show and how long the player would have held it in auto mode
+//            (autoSeconds), and a line whose text overflows its talk window comes with the wrap the fix is built from
 //   model    a model (ModelSession) with each expression, and in each motion, on contact sheets
 //   stages   the background pictures of a base story's stages on a contact sheet
 // Progress goes to console.log (the author prints it on stderr).
 import { AssetStore } from "../../../src/data/assets.js";
+import { TMP_WRAP } from "../../../src/engine/uitext.js";
 import { ModelSession } from "../../../src/live2d/session.js";
 import { loadStoryStore } from "../../../src/story/assets.js";
 import { NEXT_STEP } from "../../../src/story/player-core.js";
@@ -92,6 +95,39 @@ const talkLayout = (s) => {
            overflow: width > widthLimit + 0.01 || height > heightLimit + 0.01 };
 };
 
+// Where word wrapping breaks the talk text, for the fix of a line that does not fit: the talk text laid out again with
+// TextMeshPro's word wrapping (its rules, the font's CJK line breaking rules included: the breaks the game's text
+// engine takes), then with its own wrapping mode again. -> {lines: the text of each line (the characters laid out,
+// the line feed that ends it included), asc, desc: the ascender and descender of each line} of a text that fits the
+// window's width once broken, else null (a single word stays wider than the window).
+const wrapLayout = (s) => {
+  const talk = s.ui && s.ui.talk, node = talk && talk.p.talkText;
+  if (!node || !node.text) return null;
+  const t = node.text, r = node.rect, mg = t.margin, limit = Math.max(0, r.w - mg.x - mg.z), mode = t.wrapping;
+  try {
+    t.setWrapping(TMP_WRAP.Normal);
+    t.generate();
+    const info = t.lines.filter(Boolean);
+    if (!info.length || info.some((l) => (l.maxAdvance || 0) > limit + 0.01)) return null;
+    const lines = info.map((l, i) => t.chars.slice(l.first, i + 1 < info.length ? info[i + 1].first : t.chars.length)
+      .filter(Boolean).map((c) => String.fromCodePoint(c.u)).join(""));
+    return { lines, asc: info.map((l) => l.ascender), desc: info.map((l) => l.descender) };
+  } catch (e) {
+    console.log(`no wrap layout: ${e.message}`);
+    return null;
+  } finally {
+    t.setWrapping(mode);
+    t.generate();
+  }
+};
+
+// The seconds the player holds a typed line of `length` characters in auto mode, without voices
+// (AdvTextCommandHelper.WaitAutoPlayText): _waitTalkTextUnitTime per character, at least _minTalkDisplayTime, at the
+// playback speed rate `speed`.
+const autoHold = (P, length, speed) => Math.max(P._waitTalkTextUnitTime * length, P._minTalkDisplayTime) / speed;
+
+const round2 = (v) => Math.round(v * 100) / 100;
+
 // job: {manifest, lang, family, sample, width, height, quality, from, to, settle, maxSeconds, columns, cellWidth,
 // lines: [{line, title, detail}] (the labels of the contact sheet)}
 const story = async (job) => {
@@ -107,20 +143,29 @@ const story = async (job) => {
                                                     sound: false, voice: false, seed: 1, quality: job.quality,
                                                     width: job.width, height: job.height });
   console.log(`loaded in ${((performance.now() - t0) / 1000).toFixed(1)} s`);
+  // the characters the typewriter of the current line types (the talk view's setTalk -> {totalLength})
+  let length = 0;
+  const setTalk = s.ui.setTalk.bind(s.ui);
+  s.ui.setTalk = (text) => { const t = setTalk(text); length = t.totalLength; return t; };
+  const P = s.ctx.settings.player;
   const frames = [], thumbs = [];
   const cellW = job.cellWidth, cellH = Math.round(cellW * job.height / job.width);
   const limit = Math.round(job.maxSeconds * 30);
-  let shown = job.from - 1, idle = 0;
+  let shown = job.from - 1, idle = 0, current = -1, started = 0;
   try {
     while (!s.ended && shown < job.to) {
       await s.step({ draw: false });
       const line = s.line;
+      if (line !== current) { current = line; started = s.time; }
       if (line > shown && !s.ui.isTyping && s.core.nextStep === NEXT_STEP.AllowNext) {
+        const timing = { characters: length, typing: round2(s.time - started),
+                         autoHold: round2(autoHold(P, length, s.core.speedRate())) };
         for (let i = 0; i < job.settle; i++) await s.step({ draw: false });
         s.render();
         const file = `line-${String(line).padStart(3, "0")}.png`;
         await post(file, await pngOf(canvas));
-        frames.push({ line, file, time: Math.round(s.time * 100) / 100, talk: talkLayout(s) });
+        const talk = talkLayout(s), wrap = talk && talk.overflow ? wrapLayout(s) : null;
+        frames.push({ line, file, time: round2(s.time), talk, timing, ...(wrap ? { wrap } : {}) });
         thumbs.push({ line, image: await createImageBitmap(canvas, { resizeWidth: cellW, resizeHeight: cellH, resizeQuality: "high" }) });
         console.log(`line ${line}`);
         shown = line;
diff --git a/scripts/lib/story-author/script.js b/scripts/lib/story-author/script.js
index 0990a29..ef4ce03 100644
--- a/scripts/lib/story-author/script.js
+++ b/scripts/lib/story-author/script.js
@@ -10,8 +10,10 @@
 //   {"narrate": <text>}                                                 a line without a speaker
 // parseScript checks the document's shape; checkScript checks its names against the site (stages, music, models,
 // motions, expressions) and the staging (positions, speakers on stage). Every problem names the JSON pointer of the
-// value, and an unknown name comes with the names that exist and the nearest one. compileScript turns a script without
-// errors into the episode's command rows (episode.json) and the story index (story.json).
+// value, an unknown name comes with the names that exist and the nearest one, and a problem with a known fix carries it
+// as JSON Patch operations (applyFixes applies them; layoutFix makes the fix of a line that overflows the talk
+// window). compileScript turns a script without errors into the episode's command rows (episode.json) and the story
+// index (story.json).
 
 import { ADV_COMMAND } from "../../../src/story/interfaces.js";
 import { STORY_LANGUAGES } from "../../../src/story/params.js";
@@ -22,6 +24,12 @@ export const SCRIPT_FORMAT = "ournotes.story-script/1";
 export const POSITIONS = Object.freeze({ "far-left": 1, left: 3, center: 5, right: 7, "far-right": 9 });
 // the side a slot's motions face: the game's motions come in _L, _C and _R variants
 const SIDE = { 1: "L", 3: "L", 5: "C", 7: "R", 9: "R" };
+
+// The name of the position nearest `slot` that `occupied` (a set of position values) does not hold, or null when every
+// position is taken. -> "far-left" | "left" | "center" | "right" | "far-right"
+export const freeSlot = (slot, occupied) =>
+  Object.keys(POSITIONS).sort((a, b) => Math.abs(POSITIONS[a] - slot) - Math.abs(POSITIONS[b] - slot) || POSITIONS[a] - POSITIONS[b])
+    .find((k) => !occupied.has(POSITIONS[k])) || null;
 // focus data: the camera distance
 export const CAMERAS = Object.freeze({ near: 1, middle: 2, far: 3 });
 export const FONT_PRESETS = Object.freeze(["sans", "serif", "rounded"]);
@@ -92,14 +100,20 @@ export const nearest = (name, names) => {
 
 const EXPECTED_MAX = 40;
 export const byName = (a, b) => String(a).localeCompare(String(b), "en", { numeric: true });
-// an error about a name that is not one of `names` (`where`: what holds them, if not the script): the names (up to
-// EXPECTED_MAX) and the nearest one
-const unknown = (path, code, what, name, names, where = "") => {
+
+// the JSON Patch operation that renames the object key at `path` to `key`
+const renameOp = (path, key) => ({ op: "move", from: path, path: `${path.slice(0, path.lastIndexOf("/"))}/${tok(key)}` });
+
+// An error about a name that is not one of `names` (`where`: what holds them, if not the script): the names (up to
+// EXPECTED_MAX) and the nearest one, with the fix that writes it in: `fix` "replace" (the name is the value at
+// `path`), "rename" (the name is the key at `path`) or null (no fix).
+const unknown = (path, code, what, name, names, where = "", fix = "replace") => {
   const list = [...names], near = nearest(name, list);
   return { path, code, message: `${what} ${JSON.stringify(name)} does not exist${where ? ` in ${where}` : ""}` +
            (list.length ? (near ? `; did you mean ${JSON.stringify(near)}?` : "") : ` (${where || "it"} has none)`),
            ...(list.length <= EXPECTED_MAX ? { expected: list } : { expectedCount: list.length }),
-           ...(near ? { suggestion: near } : {}) };
+           ...(near ? { suggestion: near } : {}),
+           ...(near && fix ? { fix: [fix === "rename" ? renameOp(path, near) : { op: "replace", path, value: near }] } : {}) };
 };
 
 // ------------------------------------------------------------------------------------------------ text
@@ -117,6 +131,130 @@ export const plainText = (s) => str(s).replace(/\r\n?/g, "\n").replace(/</g, LT_
 export const cueLabel = (cue) => str(cue).replace(/^sound_bgm_(adv_)?/i, "").split("_").filter(Boolean)
   .map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
 
+// ------------------------------------------------------------------------------------------------ layout fixes
+
+// The word joiner plainText writes after a "\": it is in the text the talk window lays out, not in the script's.
+const JOINER = String.fromCharCode(0x2060);
+
+// The lines a text wraps into, as the script writes them: `shown` are the lines of plainText(text) the talk window
+// lays out with word wrapping (page.js), each with the line feed that ends it, if any. Apart from the word joiners,
+// plainText writes one character for each character of the text, so the two line up character for character. ->
+// the lines without the line feeds and the spaces at their ends, or null when `shown` is not the text.
+export const wrapText = (text, shown) => {
+  const src = [...str(text).replace(/\r\n?/g, "\n")];
+  const lines = (shown || []).map((l) => [...l].filter((c) => c !== JOINER));
+  const flat = lines.flat();
+  if (!lines.length || flat.length !== src.length || flat.join("") !== [...plainText(src.join(""))].filter((c) => c !== JOINER).join(""))
+    return null;
+  const out = [];
+  let at = 0, wrapped = false;
+  for (const l of lines) {
+    let line = src.slice(at, at + l.length).join("");
+    at += l.length;
+    if (wrapped) line = line.replace(/^[ \t]+/, "");                   // the space a wrapped line starts after
+    wrapped = !line.endsWith("\n");
+    out.push(line.replace(/[ \t]*\n?$/, ""));
+  }
+  return out;
+};
+
+// The lines (with the ascender and descender of each: their top and bottom in the text) cut into runs that each fit
+// `heightLimit`, as even as the longest run that fits allows: [[from, to), ...], or null when a line alone does not
+// fit.
+export const lineGroups = (asc, desc, heightLimit) => {
+  const fits = (a, b) => asc[a] - desc[b - 1] <= heightLimit + 0.01;
+  const n = asc.length;
+  let most = 0;
+  while (most < n && fits(0, most + 1)) most++;
+  if (!most) return null;
+  const count = Math.ceil(n / most), size = Math.ceil(n / count), even = [];
+  for (let a = 0; a < n; a += size) even.push([a, Math.min(n, a + size)]);
+  if (even.every(([a, b]) => fits(a, b))) return even;
+  const greedy = [];
+  for (let a = 0; a < n;) {
+    let b = a + 1;
+    if (!fits(a, b)) return null;
+    while (b < n && fits(a, b + 1)) b++;
+    greedy.push([a, b]);
+    a = b;
+  }
+  return greedy;
+};
+
+// The fix of a line whose text does not fit the talk window: its text broken where TextMeshPro wraps it and, where
+// the window holds fewer lines, spread over beats of the same speaker after it. `beat`: the beat as the script writes
+// it (say or narrate) at `index`; `wrap`: {lines, asc, desc} of its text laid out with word wrapping (page.js: null
+// when a line stays wider than the window); `heightLimit`: the room the window has. -> {texts, fix}, or null when the
+// text as written already fits or breaking it does not help (a single line taller than the window).
+export const layoutFix = ({ beat, index, wrap, heightLimit }) => {
+  const key = "say" in beat ? "text" : "narrate", text = beat[key];
+  if (!wrap) return null;
+  const lines = wrapText(text, wrap.lines), groups = lines && lineGroups(wrap.asc, wrap.desc, heightLimit);
+  if (!groups) return null;
+  const texts = groups.map(([a, b]) => lines.slice(a, b).join("\n"));
+  const fix = [];
+  if (texts[0] !== text) fix.push({ op: "replace", path: `/beats/${index}/${key}`, value: texts[0] });
+  texts.slice(1).forEach((t, i) => fix.push({ op: "add", path: `/beats/${index + 1 + i}`,
+                                               value: key === "text" ? { say: beat.say, text: t } : { narrate: t } }));
+  return fix.length ? { texts, fix } : null;
+};
+
+// ------------------------------------------------------------------------------------------------ applying fixes
+
+// The JSON Patch operations of the fixes (RFC 6902): replace, add, and move of an object key to another key of the
+// same object (a rename, which keeps the key's place). -> null, or why `op` cannot be applied to `doc`.
+const applyOp = (doc, op) => {
+  const tokens = (p) => str(p).split("/").slice(1).map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~"));
+  const parentOf = (ts) => {
+    let o = doc;
+    for (const t of ts.slice(0, -1)) o = o && typeof o === "object" ? o[t] : undefined;
+    return o && typeof o === "object" ? o : null;
+  };
+  const ts = tokens(op.path), key = ts[ts.length - 1], parent = parentOf(ts);
+  if (!parent) return `${op.path} does not exist`;
+  const index = Array.isArray(parent) && /^\d+$/.test(key) ? Number(key) : -1;
+  if (op.op === "replace") {
+    if (Array.isArray(parent) ? index < 0 || index >= parent.length : !(key in parent)) return `${op.path} does not exist`;
+    parent[Array.isArray(parent) ? index : key] = op.value;
+    return null;
+  }
+  if (op.op === "add") {
+    if (!Array.isArray(parent)) { parent[key] = op.value; return null; }
+    if (index < 0 || index > parent.length) return `${op.path} is not a place in the array`;
+    parent.splice(index, 0, op.value);
+    return null;
+  }
+  if (op.op === "move") {
+    const from = tokens(op.from);
+    if (Array.isArray(parent) || parentOf(from) !== parent) return "a move other than renaming a key is not supported";
+    const old = from[from.length - 1];
+    if (!(old in parent)) return `${op.from} does not exist`;
+    if (key !== old && key in parent) return `${op.path} exists already`;
+    const entries = Object.entries(parent).map(([k, v]) => [k === old ? key : k, v]);
+    for (const k of Object.keys(parent)) delete parent[k];
+    for (const [k, v] of entries) parent[k] = v;
+    return null;
+  }
+  return `operation ${JSON.stringify(op.op)} is not supported`;
+};
+
+// the beat a JSON pointer is in (-1: none)
+const beatOf = (path) => Number((/^\/beats\/(\d+)/.exec(str(path)) || [])[1] ?? -1);
+
+// The script document with the fixes of `problems` applied, later beats first (the fix of a line that does not fit
+// adds beats after it, which moves the beats after those). -> {script, applied: [{path, code}], failed: [{path, code,
+// message}]}
+export const applyFixes = (doc, problems) => {
+  const script = JSON.parse(JSON.stringify(doc)), applied = [], failed = [];
+  const fixes = (problems || []).filter((p) => Array.isArray(p.fix) && p.fix.length).sort((a, b) => beatOf(b.path) - beatOf(a.path));
+  for (const p of fixes) {
+    let why = null;
+    for (const op of p.fix) if ((why = applyOp(script, op))) break;
+    (why ? failed : applied).push({ path: p.path, code: p.code, ...(why ? { message: why } : {}) });
+  }
+  return { script, applied, failed };
+};
+
 // ------------------------------------------------------------------------------------------------ the base story
 
 // The music of a base story: the sound rows of its episode whose cue sheet is a BGM sheet the story has the sound
@@ -241,9 +379,9 @@ export const parseScript = (doc) => {
   const keys = (o, allowed, path) => {
     for (const k of Object.keys(o)) {
       if (allowed.includes(k)) continue;
-      const near = nearest(k, allowed);
-      err(`${path}/${tok(k)}`, "unknownKey", `unknown key ${JSON.stringify(k)}` + (near ? `; did you mean ${JSON.stringify(near)}?` : ""),
-          { expected: allowed, ...(near ? { suggestion: near } : {}) });
+      const near = nearest(k, allowed), kp = `${path}/${tok(k)}`;
+      err(kp, "unknownKey", `unknown key ${JSON.stringify(k)}` + (near ? `; did you mean ${JSON.stringify(near)}?` : ""),
+          { expected: allowed, ...(near ? { suggestion: near } : {}), ...(near && !(near in o) ? { fix: [renameOp(kp, near)] } : {}) });
     }
   };
   const text = (o, k, path, { required = false, empty = false } = {}) => {
@@ -305,12 +443,21 @@ export const parseScript = (doc) => {
         motion = text(p, "motion", `${pp}/motion`);
         expression = text(p, "expression", `${pp}/expression`);
       } else { err(pp, "type", "a position is a name or {at, motion, expression}", { expected: Object.keys(POSITIONS) }); continue; }
-      if (at !== undefined) out.push({ cast: id, slot: at, motion: motion || "", expression: expression || "", path: pp });
+      if (at !== undefined) out.push({ cast: id, slot: at, motion: motion || "", expression: expression || "", path: pp,
+                                       atPath: typeof p === "string" ? pp : `${pp}/at` });
     }
     return out;
   };
 
   const ids = new Set();
+  // every beat id of the document, for the fix of a duplicate one (an id no beat has)
+  const allIds = new Set(Array.isArray(doc.beats) ? doc.beats.filter((b) => isObj(b) && typeof b.id === "string").map((b) => b.id) : []);
+  const freeId = (id) => {
+    let n = 2;
+    while (allIds.has(`${id}_${n}`)) n++;
+    allIds.add(`${id}_${n}`);
+    return `${id}_${n}`;
+  };
   if (!("beats" in doc)) err("/beats", "missing", "beats is required (an array)");
   else if (!Array.isArray(doc.beats)) err("/beats", "type", "beats must be an array");
   else if (!doc.beats.length) err("/beats", "empty", "beats is empty");
@@ -323,8 +470,11 @@ export const parseScript = (doc) => {
     const beat = { kind, index, path, id: undefined };
     if ("id" in b) {
       const id = text(b, "id", `${path}/id`);
-      if (id && ids.has(id)) err(`${path}/id`, "duplicateId", `beat id ${JSON.stringify(id)} is used by an earlier beat`);
-      else if (id) { ids.add(id); beat.id = id; }
+      if (id && ids.has(id)) {
+        const next = freeId(id);
+        err(`${path}/id`, "duplicateId", `beat id ${JSON.stringify(id)} is used by an earlier beat`,
+            { suggestion: next, fix: [{ op: "replace", path: `${path}/id`, value: next }] });
+      } else if (id) { ids.add(id); beat.id = id; }
     }
     if (kind === "scene" || kind === "positions") {
       if (kind === "scene") {
@@ -388,12 +538,23 @@ export const checkScript = (script, site) => {
     }
     if (b.positions) {
       const slots = new Map();
+      // the slots of the beat and the ones given to fixes of characters on a taken slot
+      const occupied = new Set(b.positions.map((p) => p.slot));
       for (const p of b.positions) {
-        if (!cast.has(p.cast)) { errors.push(unknown(p.path, "unknownCast", "cast member", p.cast, cast.keys())); continue; }
+        if (!cast.has(p.cast)) {
+          const near = nearest(p.cast, cast.keys());
+          errors.push(unknown(p.path, "unknownCast", "cast member", p.cast, cast.keys(), "",
+                              near && !b.positions.some((q) => q.cast === near) ? "rename" : null));
+          continue;
+        }
         used.add(p.cast);
-        if (slots.has(p.slot))
-          errors.push({ path: p.path, code: "positionTaken", message: `${p.cast} and ${slots.get(p.slot)} stand at the same position` });
-        slots.set(p.slot, p.cast);
+        if (slots.has(p.slot)) {
+          const free = freeSlot(p.slot, occupied);
+          if (free) occupied.add(POSITIONS[free]);
+          errors.push({ path: p.path, code: "positionTaken", message: `${p.cast} and ${slots.get(p.slot)} stand at the same position` +
+                        (free ? `; ${JSON.stringify(free)} is free` : ""),
+                        ...(free ? { suggestion: free, fix: [{ op: "replace", path: p.atPath, value: free }] } : {}) });
+        } else slots.set(p.slot, p.cast);
         checkAction(p.cast, p.motion, p.expression, p.path);
       }
       on = new Set(b.positions.map((p) => p.cast));
diff --git a/scripts/story-author.mjs b/scripts/story-author.mjs
index 1213400..11564a4 100644
--- a/scripts/story-author.mjs
+++ b/scripts/story-author.mjs
@@ -12,11 +12,13 @@
 //     model   <id> [--out <dir>]                        a model's motions and expressions; --out: <id>-expressions.png
 //                                                       and <id>-motions.png, the model showing each
 //     new     <manifest> [--lang <l>]                   a starter script on that base story (the script itself)
-//     check   <script>                                  the script's errors and warnings, each with its JSON pointer
-//     render  <script> --out <dir> [--from <line>] [--to <line>] [--width <px>] [--settle <frames>]
+//     check   <script> [--fix <file>]                   the script's errors and warnings, each with its JSON pointer
+//                                                       and, where one is known, its fix (JSON Patch operations)
+//     render  <script> --out <dir> [--from <line>] [--to <line>] [--width <px>] [--settle <frames>] [--fix <file>]
 //                                                       plays the script in the story player and saves a picture of
 //                                                       each line once its text is shown (line-<n>.png) and contact
-//                                                       sheets of them (sheet.png)
+//                                                       sheets of them (sheet.png); a line that overflows the talk
+//                                                       window comes with a fix that breaks or splits it
 //     build   <script> --name <name>                    writes the story into the site: custom-stories/<name>.json
 //                                                       and its assets under assets/
 //     serve   [--port <n>]                              serves the package and the site on 127.0.0.1 to watch the
@@ -26,12 +28,13 @@
 //   --gpu              draw with the GPU (default: SwiftShader, the same pictures on every machine)
 //   --core <url|file>  Live2D Cubism Core (default: Live2D's distribution)
 //   --timeout <s>      give up a picture job after this long (default 600)
+//   --fix <file>       check, render: write the script with every fix applied to <file> (it may be the script)
 // Exit status: 0 done, 1 the script has errors or the job failed (the JSON says why: {"ok": false, ...}), 2 usage.
 import fs from "node:fs";
 import path from "node:path";
 import { Browser, findBrowser } from "./lib/story-author/chrome.js";
 import {
-  FONT_PRESETS, SCRIPT_FORMAT, checkScript, compileScript, fontFamily, motionStems,
+  FONT_PRESETS, SCRIPT_FORMAT, applyFixes, checkScript, compileScript, fontFamily, layoutFix, motionStems,
   parseScript, scriptTexts,
 } from "./lib/story-author/script.js";
 import { CUBISM_CORE_URL, startServer } from "./lib/story-author/server.js";
@@ -40,7 +43,7 @@ import { Site, SiteError } from "./lib/story-author/site.js";
 class UsageError extends Error {}
 
 const VALUE_OPTIONS = new Set(["site", "lang", "out", "from", "to", "width", "settle", "name", "search", "limit", "chrome",
-                               "core", "timeout", "port", "columns"]);
+                               "core", "timeout", "port", "columns", "fix"]);
 const FLAG_OPTIONS = new Set(["gpu", "help"]);
 
 const parseArgs = (argv) => {
@@ -127,12 +130,13 @@ const readScript = (file) => {
   }
 };
 
-// a script checked against its site: {ok, script, language, errors, warnings, base, models, actions}
+// a script checked against its site: {ok, doc, script, language, errors, warnings, base, models, actions} (doc: the
+// document as read)
 const loadScript = async (site, file) => {
   const doc = readScript(file);
   if (doc.parseError) return { ok: false, errors: [doc.parseError], warnings: [] };
   const { script, errors } = parseScript(doc);
-  if (!script) return { ok: false, errors, warnings: [] };
+  if (!script) return { ok: false, doc, errors, warnings: [] };
   let base = null;
   if (script.base) {
     try {
@@ -143,16 +147,29 @@ const loadScript = async (site, file) => {
       errors.push({ path: "/base", code: "unknownBase", message: e.message });
     }
   }
-  if (!base) return { ok: false, script, errors, warnings: [] };
+  if (!base) return { ok: false, doc, script, errors, warnings: [] };
   const models = site.models().map((m) => m.id), keys = Object.fromEntries(site.models().map((m) => [m.id, m.key]));
   const actions = {};
   for (const c of script.cast) if (models.includes(c.model) && !actions[c.model]) actions[c.model] = (await site.model(c.model)).actions;
   const checked = checkScript(script, { base, models, actions });
   const all = [...errors, ...checked.errors];
-  return { ok: all.length === 0, script, language: checked.language, errors: all, warnings: checked.warnings, base,
+  return { ok: all.length === 0, doc, script, language: checked.language, errors: all, warnings: checked.warnings, base,
            models: keys, actions };
 };
 
+// --fix <file>: the script document with the fixes of `problems` applied, written to <file> and checked again ->
+// {file, applied, failed, ok, errors, warnings}: the fixes applied and the ones that failed, and how the written
+// script checks (its error and warning counts)
+const writeFixed = async (site, opts, doc, problems) => {
+  if (!doc) throw new UsageError("--fix: the script is not JSON, so it cannot be fixed");
+  const { script, applied, failed } = applyFixes(doc, problems);
+  const file = path.resolve(opts.fix);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${pretty(script)}\n`);
+  const c = await loadScript(site, file);
+  return { file, applied, failed, ok: c.ok, errors: c.errors.length, warnings: c.warnings.length };
+};
+
 const compileChecked = (c) => compileScript(c.script, { base: c.base, models: c.models, actions: c.actions }, c.language);
 
 const familyOf = (c) => fontFamily(c.script.font, c.language);
@@ -248,12 +265,13 @@ const commands = {
   },
 
   async check({ args, opts }) {
-    const c = await loadScript(openSite(opts), args[0]);
+    const site = openSite(opts), c = await loadScript(site, args[0]);
     const res = { ok: c.ok, language: c.language, errors: c.errors, warnings: c.warnings };
     if (c.ok) {
       const k = compileChecked(c);
       Object.assign(res, { lines: k.lines.length, scenes: k.scenes, font: familyOf(c) });
     }
+    if (opts.fix) res.fixed = await writeFixed(site, opts, c.doc, [...c.errors, ...c.warnings]);
     return res;
   },
 
@@ -282,16 +300,27 @@ const commands = {
     const warnings = [...c.warnings];
     const frames = r.frames.map((f) => {
       const l = byLine.get(f.line), t = f.talk;
+      // a line that overflows has one fix (its text broken where the game wraps it, and spread over beats after it
+      // where the window holds fewer lines), on its first warning
+      let fix = f.wrap ? layoutFix({ beat: c.doc.beats[l.beat], index: l.beat, wrap: f.wrap, heightLimit: t.heightLimit }) : null;
+      const how = fix ? (fix.texts.length > 1 ? `; the fix spreads it over ${fix.texts.length} lines of the script`
+                                               : "; the fix breaks it where the game wraps it") : "";
+      const warn = (w) => {
+        if (fix) { Object.assign(w, { suggestion: fix.texts, fix: fix.fix }); fix = null; }
+        warnings.push(w);
+      };
       if (t && t.width > t.widthLimit + 0.01)
-        warnings.push({ path: l.path, code: "textTooWide", message: `line ${f.line} runs past the talk window ` +
-                        `(${t.width} > ${t.widthLimit}): break it with "\\n" or shorten it` });
+        warn({ path: l.path, code: "textTooWide", message: `line ${f.line} runs past the talk window ` +
+               `(${t.width} > ${t.widthLimit}): break it with "\\n" or shorten it${how}` });
       if (t && t.height > t.heightLimit + 0.01)
-        warnings.push({ path: l.path, code: "textTooTall", message: `line ${f.line} has ${t.lines} lines, taller than the ` +
-                        `talk window (${t.height} > ${t.heightLimit}): split it into two lines of the script` });
+        warn({ path: l.path, code: "textTooTall", message: `line ${f.line} has ${t.lines} lines, taller than the ` +
+               `talk window (${t.height} > ${t.heightLimit}): split it into two lines of the script${how}` });
       return { line: f.line, path: l.path, ...(l.id ? { id: l.id } : {}), speaker: l.speaker, text: l.text,
-               image: path.join(out, f.file), talk: f.talk };
+               image: path.join(out, f.file), talk: f.talk, timing: f.timing };
     });
-    return { ok: true, out, sheets: r.sheets.map((f) => path.join(out, f)), frames, warnings, seconds: r.seconds };
+    const res = { ok: true, out, sheets: r.sheets.map((f) => path.join(out, f)), frames, warnings, seconds: r.seconds };
+    if (opts.fix) res.fixed = await writeFixed(site, opts, c.doc, warnings);
+    return res;
   },
 
   async build({ args, opts }) {
diff --git a/tests/unit/story-author.test.mjs b/tests/unit/story-author.test.mjs
index fb9766d..ae1046f 100644
--- a/tests/unit/story-author.test.mjs
+++ b/tests/unit/story-author.test.mjs
@@ -8,8 +8,9 @@ import path from "node:path";
 import { test } from "node:test";
 import { pathToFileURL } from "node:url";
 import {
-  SCRIPT_FORMAT, checkScript, compileScript, cueLabel, fontFamily, modelActions, musicChoices, nearest, parseScript,
-  plainText, resolveMotion, stageBackground, stageChoices, withBrowserFonts,
+  SCRIPT_FORMAT, applyFixes, checkScript, compileScript, cueLabel, fontFamily, freeSlot, layoutFix, lineGroups,
+  modelActions, musicChoices, nearest, parseScript, plainText, resolveMotion, stageBackground, stageChoices, wrapText,
+  withBrowserFonts,
 } from "../../scripts/lib/story-author/script.js";
 import { Site } from "../../scripts/lib/story-author/site.js";
 import { fileFetch, nodeDecode } from "../../scripts/lib/headless.mjs";
@@ -227,6 +228,118 @@ test("a second scene fades out, clears the stage and fades in; a positions beat
   assert.equal(c.scenes, 2);
 });
 
+test("a script's problem names the fix that writes it in", () => {
+  const { errors } = parseScript({
+    format: SCRIPT_FORMAT, base: "b", cast: { a: { model: "m_a", name: "Ann" } },
+    beats: [{ scene: "garden", positions: { a: "middle" } }, { id: "x", say: "a", txt: "hi" }, { id: "x", narrate: "no" },
+            { narrate: "x", postions: {} }],
+  });
+  const by = Object.fromEntries(errors.map((e) => [e.path, e]));
+  assert.deepEqual(by["/beats/1/txt"].fix, [{ op: "move", from: "/beats/1/txt", path: "/beats/1/text" }]);  // rename
+  assert.equal(by["/beats/0/positions/a"].suggestion, undefined);    // "middle" is no near name for a position
+  const camera = parseScript({ format: SCRIPT_FORMAT, base: "b", cast: {},
+    beats: [{ scene: "garden", camera: "midle" }] }).errors.find((e) => e.code === "unknownCamera");
+  assert.deepEqual(camera.fix, [{ op: "replace", path: "/beats/0/camera", value: "middle" }]);
+  assert.deepEqual(by["/beats/2/id"].fix, [{ op: "replace", path: "/beats/2/id", value: "x_2" }]);         // free id
+  assert.equal(by["/beats/3/postions"].suggestion, undefined);       // no near name in this beat's keys
+  assert.equal(by["/beats/3/postions"].fix, undefined);              // and so no fix
+  assert.deepEqual(by["/beats/3/postions"].expected, ["id", "narrate"]);
+  assert.equal(parseScript({ format: SCRIPT_FORMAT, zzz: 1 }).errors[0].fix, undefined);
+  // a key whose near name is taken is left alone: renaming onto it would lose a value
+  const taken = parseScript({ format: SCRIPT_FORMAT, base: "b", cast: {},
+    beats: [{ scene: "garden", positions: { a: "left" }, psotions: {} }] }).errors.find((e) => e.code === "unknownKey");
+  assert.equal(taken.suggestion, "positions");
+  assert.equal(taken.fix, undefined);
+  assert.equal(freeSlot(5, new Set([5])), "left");                   // the nearest free position, ties to the left
+  assert.equal(freeSlot(5, new Set([5, 3])), "right");
+  assert.equal(freeSlot(3, new Set([1, 3, 5, 7, 9])), null);
+});
+
+test("where the game wraps a line, and how its lines are cut into the window and spread over beats", () => {
+  assert.deepEqual(wrapText("He said hello there.", ["He said hello ", "there."]), ["He said hello", "there."]);
+  // the word joiner the talk window has after a "\", and a line feed of the text
+  assert.deepEqual(wrapText("x\\\ny z", [`x\\${WJ}\n`, "y z"]), ["x\\", "y z"]);
+  assert.deepEqual(wrapText("one two", ["one ", "two", ""]), ["one", "two", ""]);
+  assert.equal(wrapText("one two", ["one ", "three"]), null);        // not this text
+  assert.equal(wrapText("one two", []), null);
+  assert.equal(wrapText("ab", ["a"]), null);
+
+  // four lines of 60 px, 30 px apart: two lines stack 90 px, three 120, four 150
+  const asc = [40, 10, -20, -50], desc = [-20, -50, -80, -110];
+  assert.deepEqual(lineGroups(asc, desc, 150), [[0, 4]]);
+  assert.deepEqual(lineGroups(asc, desc, 120), [[0, 2], [2, 4]]);    // three fit, but two and two are as few groups
+  assert.deepEqual(lineGroups(asc, desc, 60), [[0, 1], [1, 2], [2, 3], [3, 4]]);
+  assert.equal(lineGroups(asc, desc, 50), null);                     // a line alone is taller than the window
+  assert.equal(lineGroups([], [], 30), null);
+  // lines of 10, 10, 40 and 10 px: the even groups do not fit, so each group takes as many lines as fit
+  assert.deepEqual(lineGroups([0, -10, -20, -60], [-10, -20, -60, -70], 45), [[0, 2], [2, 3], [3, 4]]);
+
+  const a3 = asc.slice(0, 3), d3 = desc.slice(0, 3), beat = { say: "a", text: "one two three four" };
+  const wrap = { lines: ["one two ", "three ", "four"], asc: a3, desc: d3 };
+  // the window holds one line: the text stays on the beat and gets its own for each further line
+  const fix = layoutFix({ beat, index: 2, wrap, heightLimit: 60 });
+  assert.deepEqual(fix.texts, ["one two", "three", "four"]);
+  assert.deepEqual(fix.fix, [{ op: "replace", path: "/beats/2/text", value: "one two" },
+                             { op: "add", path: "/beats/3", value: { say: "a", text: "three" } },
+                             { op: "add", path: "/beats/4", value: { say: "a", text: "four" } }]);
+  // a narration's beats are narrations too; the window holding two lines, the second beat takes the rest
+  const said = layoutFix({ beat: { narrate: "one two three four" }, index: 0, wrap, heightLimit: 90 });
+  assert.deepEqual(said.fix, [{ op: "replace", path: "/beats/0/narrate", value: "one two\nthree" },
+                              { op: "add", path: "/beats/1", value: { narrate: "four" } }]);
+  // the window holds all three: the line breaks where the game wraps it
+  assert.deepEqual(layoutFix({ beat, index: 0, wrap, heightLimit: 120 }).fix,
+                   [{ op: "replace", path: "/beats/0/text", value: "one two\nthree\nfour" }]);
+  assert.equal(layoutFix({ beat, index: 0, wrap: null, heightLimit: 120 }), null);
+  assert.equal(layoutFix({ beat: { say: "a", text: "one\ntwo\nthree" }, index: 0,             // it fits as written
+                           wrap: { lines: ["one\n", "two\n", "three"], asc: a3, desc: d3 }, heightLimit: 120 }), null);
+  assert.equal(layoutFix({ beat, index: 0, wrap, heightLimit: 50 }), null);                     // a line is too tall
+});
+
+test("the fixes of a script's problems are applied, later beats first", () => {
+  // a script with a mistyped stage, a mistyped beat key, a mistyped motion, a repeated beat id and a line that does
+  // not fit the window
+  const doc = script([
+    { scene: "gardne", positions: { a: "center", b: "center" } },
+    { say: "a", text: "One two three" },
+    { id: "x", say: "a", txt: "Hi", motion: "mtn_smil01" },
+    { id: "x", narrate: "The end." },
+  ]);
+  const c = checked(doc);
+  assert.deepEqual(codes(c.errors), [["/beats/2/txt", "unknownKey"], ["/beats/2/text", "missing"],
+                                     ["/beats/3/id", "duplicateId"], ["/beats/0/scene", "unknownStage"],
+                                     ["/beats/0/positions/b", "positionTaken"], ["/beats/2/motion", "unknownMotion"]]);
+  // the wrap of the first line's text and the room the window has
+  const wrap = { lines: ["One two ", "three"], asc: [40, 10], desc: [-20, -50] };
+  const layout = layoutFix({ beat: doc.beats[1], index: 1, wrap, heightLimit: 60 });
+  const { script: fixed, applied, failed } = applyFixes(doc, [...c.errors, { path: "/beats/1", code: "textTooTall", fix: layout.fix }]);
+  assert.deepEqual(failed, []);
+  // what the fixed script checks as
+  assert.deepEqual(checked(fixed).errors, []);
+  assert.deepEqual(fixed.beats, [
+    { scene: "garden", positions: { a: "center", b: "left" } },
+    { say: "a", text: "One two" },
+    { say: "a", text: "three" },
+    { id: "x", say: "a", text: "Hi", motion: "mtn_smile01" },       // a renamed key keeps its place
+    { id: "x_2", narrate: "The end." },
+  ]);
+  // later beats first, so that the beats the line's fix adds do not move the ones after it; a problem without a
+  // fix (the missing text) is not among them
+  assert.deepEqual(applied.map((a) => [a.path, a.code]), [["/beats/3/id", "duplicateId"], ["/beats/2/txt", "unknownKey"],
+                                                          ["/beats/2/motion", "unknownMotion"], ["/beats/1", "textTooTall"],
+                                                          ["/beats/0/scene", "unknownStage"],
+                                                          ["/beats/0/positions/b", "positionTaken"]]);
+  assert.deepEqual(doc.beats[2], { id: "x", say: "a", txt: "Hi", motion: "mtn_smil01" });  // the document is kept
+
+  // a fix that cannot be applied is reported and left out; the others still go in
+  const why = applyFixes({ beats: [{ say: "a", text: "x" }] }, [
+    { path: "/beats/1/text", code: "textTooTall", fix: [{ op: "replace", path: "/beats/1/text", value: "y" }] },
+    { path: "/beats/0", code: "other", fix: [{ op: "remove", path: "/beats/0" }] },
+  ]);
+  assert.deepEqual(why.applied, []);
+  assert.deepEqual(why.failed.map((f) => [f.code, f.message]), [["textTooTall", "/beats/1/text does not exist"],
+                                                               ["other", 'operation "remove" is not supported']]);
+});
+
 test("the compiled rows are commands the story player runs", () => {
   const ep = compiled(script([
     { scene: "garden", music: "sound_bgm_adv_quiet_morning", location: "L", positions: { a: "left" } },
@@ -379,5 +492,21 @@ test("the commands without a browser: new, check, build; the built story loads",
     r = run(["build", file, "--site", dir, "--name", "Bad Name"]);
     assert.equal(r.status, 2);
     assert.equal(run(["check", file, "--site", dir, "--nope"]).status, 2);
+
+    // check --fix: the script with its fixes applied, checked again
+    fs.writeFileSync(file, JSON.stringify({ ...doc, beats: [{ scene: "gardn", positions: { c1: "left", b: "left" } },
+                                                            { say: "b", txt: "Hello" }] }));
+    const fixedFile = path.join(dir, "fixed", "s.json");
+    r = run(["check", file, "--site", dir, "--fix", fixedFile]);
+    assert.equal(r.status, 1);
+    assert.deepEqual(codes(r.out.errors), [["/beats/1/txt", "unknownKey"], ["/beats/1/text", "missing"],
+                                           ["/beats/0/scene", "unknownStage"], ["/beats/0/positions/b", "positionTaken"]]);
+    assert.deepEqual(r.out.fixed, { file: fixedFile, applied: [{ path: "/beats/1/txt", code: "unknownKey" },
+      { path: "/beats/0/scene", code: "unknownStage" }, { path: "/beats/0/positions/b", code: "positionTaken" }],
+      failed: [], ok: true, errors: 0, warnings: 0 });
+    assert.deepEqual(JSON.parse(fs.readFileSync(fixedFile, "utf8")).beats,
+                     [{ scene: "garden", positions: { c1: "left", b: "far-left" } }, { say: "b", text: "Hello" }]);
+    assert.equal(JSON.parse(fs.readFileSync(file, "utf8")).beats[0].scene, "gardn");          // the script is kept
+    assert.equal(run(["check", fixedFile, "--site", dir]).status, 0);
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 });

From ac088ef5fdea3ca87260ad8c8648be1634898827 Mon Sep 17 00:00:00 2001
From: nichinichisou <nichinichisou0609@outlook.com>
Date: Wed, 14 Oct 2026 19:28:22 +0800
Subject: [PATCH 2/3] docs: list every export of the story and UI entry points

The entry points table of docs/story.md now lists everything
`ournotes-player/story` exports: SimpleStorySession, parseStorySpeed,
the command registry (unregisteredCommands, StoryPlayerCore,
StoryCommandError), the story UI interface (checkStoryUI, StoryUILayer,
createStoryUILayers), STORY_LANGUAGES, storyLines, advViewport, the
control labels (STORY_STRINGS, storyStrings) and ADV_PLAYBACK_SPEEDS.
docs/api.md lists cameraProjection for `ournotes-player/ui`.

The story author's documentation names the --timeout option of the
picture commands, and its usage text names render's --columns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api.md              | 2 +-
 docs/story-author.md     | 6 ++++--
 docs/story.md            | 2 +-
 scripts/story-author.mjs | 3 ++-
 4 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index d28f4a5..1cd7265 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -10,7 +10,7 @@ live UI, with the chart's music and sound effects, auto-played at Perfect. The d
 |---|---|
 | `ournotes-player` | `ChartPlayer`, `ChartSession`, `AssetStore`, `defineOurnotesPlayer`, `OurnotesPlayerElement`, `LIVE_SPEEDS`, `LIVE_OPTIONS`, `LIVE_OPTION_GROUPS`, `LiveSettingsError`, `PLAYER_LANGUAGES`, `formatTime` |
 | `ournotes-player/element` | the same exports; importing it defines `<ournotes-player>` |
-| `ournotes-player/ui` (experimental) | `UILibrary`, `UISession`, `UIPlayer`, `OurnotesUIElement`, `defineOurnotesUI`; [prefab preview API and limits](ui-preview.md) |
+| `ournotes-player/ui` (experimental) | `UILibrary`, `UISession`, `UIPlayer`, `OurnotesUIElement`, `defineOurnotesUI`, `cameraProjection`; [prefab preview API and limits](ui-preview.md) |
 | `ournotes-player/ui/element` (experimental) | the same UI exports; importing it defines `<ournotes-ui>` |
 | `ournotes-player/replay/preset` | `parseJustJudgementTypes`, `applyAccuracyPreset`, `applySegmentPreset`: declared input plans that set the judgement grades of an `ournotes.replay/1` request in place |
 
diff --git a/docs/story-author.md b/docs/story-author.md
index 01b375a..2d91e83 100644
--- a/docs/story-author.md
+++ b/docs/story-author.md
@@ -43,8 +43,10 @@ Look at the pictures after each render: the contact sheet shows every line with
 
 ## Commands
 
-All commands take `--site <dir>`. Exit status: 0 done, 1 the script has errors or the job failed (the JSON has
-`"ok": false` and the errors, or `error`), 2 a usage error (message on stderr).
+All commands take `--site <dir>`. The commands that draw pictures take `--chrome`, `--gpu` and `--core` (see
+[Requirements](#requirements)) and give up a picture job that has not finished after `--timeout <s>` seconds (default
+600). Exit status: 0 done, 1 the script has errors or the job failed (the JSON has `"ok": false` and the errors, or
+`error`), 2 a usage error (message on stderr).
 
 ### bases
 
diff --git a/docs/story.md b/docs/story.md
index c0ae635..f2ba2a4 100644
--- a/docs/story.md
+++ b/docs/story.md
@@ -33,7 +33,7 @@ mouth from the CRI Lips analysis in the story's own data ([crilips.md](crilips.m
 
 | Import | Contents |
 |---|---|
-| `ournotes-player/story` | `StoryPlayer`, `StorySession`, `AssetStore`, `loadStoryStore`, `fetchStoryManifest`, `defineOurnotesStory`, `OurnotesStoryElement`, `registerCommand`, `registeredCommands`, `STORY_FRAME_RATE` (30), `STORY_MANIFEST_FORMAT` / `STORY_MANIFEST_FORMATS` (the current story manifest format and the ones the player reads), the game's enums (`ADV_COMMAND`, `ADV_PLAYBACK_SPEED`, `ADV_PLAYBACK_MODE`, `ADV_CANVAS_LAYER`) |
+| `ournotes-player/story` | `StoryPlayer`, `StorySession`, `SimpleStorySession` (the session of an Overlay episode), `AssetStore`, `loadStoryStore`, `fetchStoryManifest`, `defineOurnotesStory`, `OurnotesStoryElement`, `parseStorySpeed`; the command registry (`registerCommand`, `registeredCommands`, `unregisteredCommands`, `StoryPlayerCore`, `StoryCommandError`) and the story UI interface (`checkStoryUI`, `StoryUILayer`, `createStoryUILayers`); `STORY_FRAME_RATE` (30), `STORY_MANIFEST_FORMAT` / `STORY_MANIFEST_FORMATS` (the current story manifest format and the ones the player reads), `STORY_LANGUAGES` (language code → text field), `storyLines` (the rows that show a line), `advViewport` (the 13:6 ADV viewport in a screen), the control labels (`STORY_STRINGS`, `storyStrings`), the game's enums (`ADV_COMMAND`, `ADV_PLAYBACK_SPEED`, `ADV_PLAYBACK_SPEEDS`, `ADV_PLAYBACK_MODE`, `ADV_CANVAS_LAYER`) |
 | `ournotes-player/story/element` | the same exports; importing it defines `<ournotes-story>` |
 
 Browser bundles in `dist/`: `ournotes-player.story.js` (ESM, the API), `ournotes-player.story.element.js` (ESM, defines
diff --git a/scripts/story-author.mjs b/scripts/story-author.mjs
index 11564a4..7b23d20 100644
--- a/scripts/story-author.mjs
+++ b/scripts/story-author.mjs
@@ -14,7 +14,8 @@
 //     new     <manifest> [--lang <l>]                   a starter script on that base story (the script itself)
 //     check   <script> [--fix <file>]                   the script's errors and warnings, each with its JSON pointer
 //                                                       and, where one is known, its fix (JSON Patch operations)
-//     render  <script> --out <dir> [--from <line>] [--to <line>] [--width <px>] [--settle <frames>] [--fix <file>]
+//     render  <script> --out <dir> [--from <line>] [--to <line>] [--width <px>] [--settle <frames>]
+//             [--columns <n>] [--fix <file>]
 //                                                       plays the script in the story player and saves a picture of
 //                                                       each line once its text is shown (line-<n>.png) and contact
 //                                                       sheets of them (sheet.png); a line that overflows the talk

From 2f216def5e5f15a60c647d8108cb4c3be0bd3bea Mon Sep 17 00:00:00 2001
From: nichinichisou <nichinichisou0609@outlook.com>
Date: Wed, 14 Oct 2026 19:28:22 +0800
Subject: [PATCH 3/3] ci: check that the package's public contracts agree

`npm run contract:check` (scripts/check-contracts.mjs) compares what
package.json, the modules, the type declarations, the schemas and the
documents say about the same things, and fails on any disagreement:

- package: main, module and types are the "." entry's, and every files
  entry, exports target and sideEffects pattern names files that exist
  inside `files`;
- entries: each entry point's runtime exports (its bundle's ES exports)
  are the values its .d.ts exports and the names its row of an entry
  points table in docs/ lists;
- schemas: each schema is draft 2020-12 with its raw URL as $id, uses
  only the keywords the validator implements, is loaded by
  validate-data and named in docs/;
- formats: the ournotes.* format ids of the code, types and schemas and
  those of the documents are the same;
- links: relative Markdown links and their #fragments resolve;
- story-author: the CLI's commands, options and problem codes are the
  ones its usage text and docs/story-author.md describe;
- workflows: the CI job and the release verification job run the same
  commands in the same order.

CI and the release verification job run it after the build check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml      |   1 +
 .github/workflows/release.yml |   1 +
 CONTRIBUTING.md               |   5 +-
 README.en.md                  |   1 +
 README.md                     |   1 +
 package.json                  |   1 +
 scripts/check-contracts.mjs   | 303 ++++++++++++++++++++++++++++++++++
 7 files changed, 312 insertions(+), 1 deletion(-)
 create mode 100644 scripts/check-contracts.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 52c9baf..1932b8e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,5 +33,6 @@ jobs:
       - run: npm run lint
       # --check builds twice and fails when the two outputs differ
       - run: node scripts/build.mjs --check
+      - run: npm run contract:check
       - name: Package contents
         run: npm pack --dry-run
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 6c6d6eb..8ff3b64 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -33,6 +33,7 @@ jobs:
       - run: npm run typecheck
       - run: npm run lint
       - run: node scripts/build.mjs --check
+      - run: npm run contract:check
 
       - name: Check the tag against package.json
         if: startsWith(github.ref, 'refs/tags/v')
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da9d80d..1da4e4f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,10 +22,13 @@ npm run typecheck      # type-checks tests/types/ against types/
 npm run lint           # ESLint's recommended rules (eslint.config.js)
 npm run build          # dist/: ESM, minified ESM and IIFE bundles with source maps
 node scripts/build.mjs --check   # builds twice and fails if the outputs differ
+npm run contract:check # package.json, entry points, types, schemas and docs agree (after a build)
 ```
 
 The source is plain JavaScript ES modules (`src/`), with type declarations in `types/`. Keep both in step when the
-public API changes, and document it in [docs/api.md](docs/api.md).
+public API changes, and document it in the entry points table of [docs/api.md](docs/api.md) (or of the entry's own
+document); `npm run contract:check` compares the three, and checks the documents' links, the format ids and the
+schemas.
 
 ### Tests
 
diff --git a/README.en.md b/README.en.md
index d7f04cb..fba517f 100644
--- a/README.en.md
+++ b/README.en.md
@@ -233,6 +233,7 @@ npm test                  # unit tests (node --test, synthetic inputs only)
 npm run build             # browser bundles in dist/
 npm run typecheck         # checks the type declarations in types/
 npm run lint              # ESLint (eslint.config.js)
+npm run contract:check    # package.json, entry exports, types, schemas and docs agree
 npm run validate-data -- <site dir> [chart id ...]              # validates a site against the data format
 node scripts/story-author.mjs help                              # the commands of the story script tool (experimental)
 OURNOTES_DATA=<site dir> npm run test:data                      # opt-in: runs the player in Node on real chart data
diff --git a/README.md b/README.md
index 3c15568..a8ef75c 100644
--- a/README.md
+++ b/README.md
@@ -182,6 +182,7 @@ npm test                  # 单元测试（node --test，仅使用合成输入
 npm run build             # 构建 dist/ 下的浏览器包
 npm run typecheck         # 检查 types/ 下的类型声明
 npm run lint              # ESLint 检查（eslint.config.js）
+npm run contract:check    # 核对 package.json、入口导出、类型声明、schema 与文档是否一致
 npm run validate-data -- <站点目录> [谱面 id ...]              # 按数据格式校验一个站点
 node scripts/story-author.mjs help                             # 自写剧情工具（实验功能）的命令
 OURNOTES_DATA=<站点目录> npm run test:data                     # 可选：用真实谱面数据在 Node 中运行播放器
diff --git a/package.json b/package.json
index 455e769..4aab9e9 100644
--- a/package.json
+++ b/package.json
@@ -112,6 +112,7 @@
     "test:data": "node --test tests/data/*.test.mjs",
     "typecheck": "tsc -p tests/types",
     "lint": "eslint .",
+    "contract:check": "node scripts/check-contracts.mjs",
     "validate-data": "node scripts/validate-data.mjs",
     "read-set": "node scripts/read-set.mjs"
   },
diff --git a/scripts/check-contracts.mjs b/scripts/check-contracts.mjs
new file mode 100644
index 0000000..d2a040d
--- /dev/null
+++ b/scripts/check-contracts.mjs
@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+// Checks that the package's public contracts agree with each other: what package.json, the modules, the type
+// declarations, the schemas and the documents each say about the same thing.
+//
+//   node scripts/check-contracts.mjs          (npm run contract:check; dist/ must be built: npm run build)
+//
+//   package       main, module and types are the "." entry's; every `files` entry exists; every `exports` target and
+//                 `sideEffects` pattern names files that exist, inside `files`
+//   entries       each entry point's runtime exports (the module's ES exports, through every re-export) are the values
+//                 its type declarations export, and the names its row of an entry points table in docs/ lists (a row
+//                 that says "the same" lists the entry without /element)
+//   schemas       each schema/*.json is a draft 2020-12 schema whose $id is its raw URL on the main branch, uses only
+//                 the keywords the validator implements, is loaded by scripts/validate-data.mjs and named in docs/
+//   formats       every ournotes.* format id the code, the types or the schemas name is in the documents, and every
+//                 one the documents name is in the code or the schemas
+//   links         every relative link of the Markdown files points at a file that exists and, with #fragment, at a
+//                 heading of that file
+//   story-author  the commands, options and problem codes of scripts/story-author.mjs are the ones its header and
+//                 docs/story-author.md describe
+//   workflows     the CI job runs the same commands as the release workflow's verification job, in the same order
+// Prints each problem as "<contract>: <message>"; exit status 0 when there is none, 1 otherwise.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as esbuild from "esbuild";
+import ts from "typescript";
+import { compile } from "./lib/json-schema.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const read = (rel) => fs.readFileSync(path.join(root, rel), "utf8");
+const exists = (rel) => fs.existsSync(path.join(root, rel));
+const posix = (p) => p.split(path.sep).join("/");
+const pkg = JSON.parse(read("package.json"));
+
+// the files under `dir` (relative, "/"-separated), without node_modules, dist (unless asked) and dot directories
+const walk = (dir, { dist = false } = {}) => {
+  const out = [];
+  const go = (rel) => {
+    for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true })) {
+      const p = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (e.name.startsWith(".") || e.name === "node_modules" || (e.name === "dist" && !dist && !rel)) continue;
+        go(p);
+      } else out.push(p);
+    }
+  };
+  go(dir);
+  return out;
+};
+
+const glob = (pattern) => new RegExp(`^${pattern.replace(/^\.\//, "").replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")}$`);
+const inFiles = (rel) => pkg.files.some((f) => (f.endsWith("/") ? rel.startsWith(f) : rel === f));
+const sameSet = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
+const list = (s) => [...s].sort().join(", ") || "(none)";
+
+// the package's entry points with a module of their own: [{name, specifier, types, module}]
+const entryPoints = () => Object.entries(pkg.exports).filter(([k, v]) => !k.includes("*") && typeof v === "object")
+  .map(([k, v]) => ({ name: k, specifier: k === "." ? pkg.name : `${pkg.name}/${k.slice(2)}`,
+                      types: v.types.replace(/^\.\//, ""), module: v.default.replace(/^\.\//, "") }));
+
+// ------------------------------------------------------------------------------------------------ package
+
+const checkPackage = () => {
+  const out = [], main = pkg.exports["."];
+  for (const k of ["main", "module"]) if (pkg[k] !== main.default) out.push(`${k} ${pkg[k]} is not the "." entry's module ${main.default}`);
+  if (pkg.types !== main.types) out.push(`types ${pkg.types} is not the "." entry's types ${main.types}`);
+  for (const f of pkg.files) if (!exists(f)) out.push(`files: ${f} does not exist`);
+  const all = walk("", { dist: true });
+  for (const [k, v] of Object.entries(pkg.exports)) {
+    for (const target of typeof v === "string" ? [v] : Object.values(v)) {
+      const rel = target.replace(/^\.\//, "");
+      if (rel.includes("*") ? !all.some((f) => glob(rel).test(f)) : !exists(rel)) out.push(`exports ${k}: ${target} names no file`);
+      else if (!inFiles(rel.replace(/\*.*$/, "")) && rel !== "package.json") out.push(`exports ${k}: ${target} is not in files`);
+    }
+  }
+  for (const p of pkg.sideEffects) {
+    const matched = all.filter((f) => glob(p).test(f));
+    if (!matched.length) out.push(`sideEffects: ${p} names no file${p.startsWith("./dist/") && !exists("dist") ? " (dist/ is not built)" : ""}`);
+    else if (!matched.every(inFiles)) out.push(`sideEffects: ${p} names files that are not in files`);
+  }
+  return out;
+};
+
+// ------------------------------------------------------------------------------------------------ entries
+
+// the runtime exports of a module: the ES exports of its bundle, so re-exports count -> Set, or the bundler's first
+// error when the module does not build
+const runtimeExports = async (module) => {
+  try {
+    const r = await esbuild.build({ entryPoints: [path.join(root, module)], bundle: true, format: "esm", write: false,
+                                    metafile: true, logLevel: "silent", outdir: path.join(root, ".contracts") });
+    return new Set(Object.values(r.metafile.outputs).find((o) => o.entryPoint).exports);
+  } catch (e) {
+    const m = e.errors && e.errors[0];
+    return m ? `${m.location ? `${m.location.file}:${m.location.line}: ` : ""}${m.text}` : e.message;
+  }
+};
+
+// the values (not the types) each declaration file exports: file -> Set
+const declaredValues = (files) => {
+  const program = ts.createProgram(files.map((f) => path.join(root, f)), {
+    noEmit: true, skipLibCheck: true, target: ts.ScriptTarget.ES2022, lib: ["lib.es2022.d.ts", "lib.dom.d.ts"] });
+  const checker = program.getTypeChecker(), out = new Map();
+  for (const f of files) {
+    const sym = checker.getSymbolAtLocation(program.getSourceFile(path.join(root, f)));
+    const value = (s) => ((s.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(s) : s).flags & ts.SymbolFlags.Value) !== 0;
+    out.set(f, new Set(sym ? checker.getExportsOfModule(sym).filter(value).map((s) => s.name) : []));
+  }
+  return out;
+};
+
+// the rows of the documents' entry points tables: specifier -> {file, names: Set | null ("the same")}
+const documentedEntries = () => {
+  const out = new Map(), problems = [];
+  for (const f of walk("docs").filter((f) => f.endsWith(".md"))) {
+    for (const line of read(f).split(/\r?\n/)) {
+      const m = /^\| `([^`]+)`(?: \([^)]*\))? \| (.*) \|$/.exec(line);
+      if (!m || !(m[1] === pkg.name || m[1].startsWith(`${pkg.name}/`))) continue;
+      if (out.has(m[1])) { problems.push(`${m[1]} has two entry points rows (${out.get(m[1]).file}, ${f})`); continue; }
+      const names = /^the same\b/.test(m[2]) ? null
+        : new Set([...m[2].matchAll(/`([^`]+)`/g)].map((x) => x[1]).filter((x) => /^[A-Za-z_$][\w$]*$/.test(x)));
+      out.set(m[1], { file: f, names });
+    }
+  }
+  return { rows: out, problems };
+};
+
+const checkEntries = async () => {
+  const entries = entryPoints(), out = [];
+  const declared = declaredValues([...new Set(entries.map((e) => e.types))]);
+  const { rows, problems } = documentedEntries();
+  out.push(...problems);
+  for (const e of entries) {
+    const runtime = await runtimeExports(e.module), values = declared.get(e.types);
+    if (typeof runtime === "string") { out.push(`${e.specifier}: ${e.module} does not build: ${runtime}`); continue; }
+    if (!sameSet(runtime, values)) {
+      const extra = [...runtime].filter((x) => !values.has(x)), missing = [...values].filter((x) => !runtime.has(x));
+      out.push(`${e.specifier}: ${e.module} and ${e.types} differ` + (extra.length ? `; not declared: ${list(extra)}` : "") +
+               (missing.length ? `; declared but not exported: ${list(missing)}` : ""));
+    }
+    const row = rows.get(e.specifier);
+    if (!row) { out.push(`${e.specifier}: no entry points row in docs/`); continue; }
+    const base = row.names ? row : rows.get(e.specifier.replace(/\/element$/, ""));
+    if (!base || !base.names) { out.push(`${e.specifier}: ${row.file} says "the same" with no entry to be the same as`); continue; }
+    if (!sameSet(runtime, base.names)) {
+      const extra = [...runtime].filter((x) => !base.names.has(x)), missing = [...base.names].filter((x) => !runtime.has(x));
+      out.push(`${e.specifier}: ${base.file} lists other exports` + (extra.length ? `; not listed: ${list(extra)}` : "") +
+               (missing.length ? `; listed but not exported: ${list(missing)}` : ""));
+    }
+  }
+  for (const s of rows.keys()) if (!entries.some((e) => e.specifier === s)) out.push(`${rows.get(s).file}: ${s} is not an entry point`);
+  return out;
+};
+
+// ------------------------------------------------------------------------------------------------ schemas
+
+const SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+const SCHEMA_BASE = `https://raw.githubusercontent.com/${pkg.repository.url.replace(/^git\+https:\/\/github\.com\/|\.git$/g, "")}/main/`;
+
+const checkSchemas = () => {
+  const out = [], validator = read("scripts/validate-data.mjs");
+  const loaded = new Set([...validator.matchAll(/schema\("([\w-]+)"\)/g)].map((m) => `${m[1]}.schema.json`));
+  const docs = walk("docs").filter((f) => f.endsWith(".md")).map(read).join("\n");
+  for (const f of fs.readdirSync(path.join(root, "schema")).filter((f) => f.endsWith(".json")).sort()) {
+    const rel = `schema/${f}`;
+    let s;
+    try { s = JSON.parse(read(rel)); } catch (e) { out.push(`${rel}: not JSON (${e.message})`); continue; }
+    if (s.$schema !== SCHEMA_DIALECT) out.push(`${rel}: $schema is not ${SCHEMA_DIALECT}`);
+    if (s.$id !== SCHEMA_BASE + rel) out.push(`${rel}: $id is not ${SCHEMA_BASE + rel}`);
+    try { compile(s); } catch (e) { out.push(`${rel}: ${e.message}`); }
+    if (!loaded.has(f)) out.push(`${rel}: scripts/validate-data.mjs does not load it`);
+    if (!docs.includes(rel)) out.push(`${rel}: no document in docs/ names it`);
+    for (const m of JSON.stringify(s).matchAll(/\bdocs\/[\w-]+\.md\b/g)) if (!exists(m[0])) out.push(`${rel}: ${m[0]} does not exist`);
+  }
+  for (const f of loaded) if (!exists(`schema/${f}`)) out.push(`scripts/validate-data.mjs loads schema/${f}, which does not exist`);
+  return out;
+};
+
+// ------------------------------------------------------------------------------------------------ formats
+
+const FORMAT_ID = /\bournotes\.[a-z][a-z0-9-]*\/\d+\b/g;
+
+const checkFormats = () => {
+  const ids = (files) => {
+    const m = new Map();
+    for (const f of files) for (const [id] of read(f).matchAll(FORMAT_ID)) if (!m.has(id)) m.set(id, f);
+    return m;
+  };
+  const code = ids(["src", "scripts", "examples", "types", "schema"].flatMap((d) => walk(d))
+    .filter((f) => /\.(m?js|d\.ts|json)$/.test(f)));
+  const docs = ids(["README.md", "README.en.md", "CONTRIBUTING.md", ...walk("docs").filter((f) => f.endsWith(".md"))]);
+  const out = [];
+  for (const [id, f] of code) if (!docs.has(id)) out.push(`${id} (${f}) is in no document`);
+  for (const [id, f] of docs) if (!code.has(id)) out.push(`${id} (${f}) is in no module, type declaration or schema`);
+  return out;
+};
+
+// ------------------------------------------------------------------------------------------------ links
+
+// GitHub's heading anchors: lowercase, punctuation removed (letters, marks, digits, spaces, "-" and "_" kept), spaces to
+// "-"; a repeated heading gets -1, -2, ...
+const anchors = (text) => {
+  const out = new Set(), seen = new Map();
+  let fence = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    const m = !fence && /^#{1,6}\s+(.*?)\s*#*\s*$/.exec(line);
+    if (!m) continue;
+    const slug = m[1].toLowerCase().replace(/[^\p{L}\p{M}\p{N}\s_-]/gu, "").replace(/\s/g, "-");
+    const n = seen.get(slug) || 0;
+    seen.set(slug, n + 1);
+    out.add(n ? `${slug}-${n}` : slug);
+  }
+  return out;
+};
+
+const checkLinks = () => {
+  const out = [], files = walk("").filter((f) => f.endsWith(".md")), cache = new Map();
+  const anchorsOf = (rel) => { if (!cache.has(rel)) cache.set(rel, anchors(read(rel))); return cache.get(rel); };
+  for (const f of files) {
+    let fence = false;
+    read(f).split(/\r?\n/).forEach((line, i) => {
+      if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+      if (fence) return;
+      for (const m of line.replace(/`[^`]*`/g, "").matchAll(/\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+        const target = m[1];
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target)) continue;                 // https:, mailto:, ...
+        const [file, frag] = target.split("#");
+        const rel = file ? posix(path.normalize(path.join(path.dirname(f), decodeURIComponent(file)))) : f;
+        const where = `${f}:${i + 1}`;
+        if (!exists(rel)) { out.push(`${where}: ${target} names no file`); continue; }
+        if (frag !== undefined && rel.endsWith(".md") && !anchorsOf(rel).has(decodeURIComponent(frag)))
+          out.push(`${where}: ${target} names no heading of ${rel}`);
+      }
+    });
+  }
+  return out;
+};
+
+// ------------------------------------------------------------------------------------------------ story-author
+
+const checkStoryAuthor = () => {
+  const cli = read("scripts/story-author.mjs"), lib = read("scripts/lib/story-author/script.js");
+  const doc = read("docs/story-author.md"), out = [];
+  const header = cli.split(/\r?\n/).slice(1).filter((l, i, a) => a.slice(0, i + 1).every((x) => x.startsWith("//"))).join("\n");
+  const body = cli.slice(cli.indexOf("const commands = {"), cli.indexOf("\n};", cli.indexOf("const commands = {")));
+  const commands = [...body.matchAll(/^ {2}async (\w+)\(/gm)].map((m) => m[1]);
+  for (const c of commands) {
+    if (!new RegExp(`^### ${c}$`, "m").test(doc)) out.push(`command ${c}: no "### ${c}" section in docs/story-author.md`);
+    if (!new RegExp(`^// {5}${c}\\b`, "m").test(header)) out.push(`command ${c}: not in the header of scripts/story-author.mjs`);
+  }
+  for (const m of doc.matchAll(/^### (\w+)$/gm))
+    if (/^[a-z]+$/.test(m[1]) && !commands.includes(m[1]) && m[1] !== "fixes") out.push(`docs/story-author.md: ### ${m[1]} is not a command`);
+  const options = [...cli.matchAll(/new Set\(\[([^\]]*)\]\)/g)].flatMap((m) => [...m[1].matchAll(/"([\w-]+)"/g)].map((x) => x[1]));
+  for (const o of options.filter((o) => o !== "help")) {
+    if (!doc.includes(`--${o}`)) out.push(`option --${o}: not in docs/story-author.md`);
+    if (!header.includes(`--${o}`)) out.push(`option --${o}: not in the header of scripts/story-author.mjs`);
+  }
+  for (const m of doc.matchAll(/(?<![\w-])--([a-z][\w-]*)/g))
+    if (!options.includes(m[1])) out.push(`docs/story-author.md: --${m[1]} is not an option`);
+  // the problem codes: code: "..." anywhere, and the code argument of the script checks' helpers (err(path, code, ...),
+  // unknown(path, code, ...) and named(value, table, path, code, what))
+  const codes = new Set([...cli.matchAll(/code: "(\w+)"/g), ...lib.matchAll(/code: "(\w+)"/g),
+                         ...lib.matchAll(/\b(?:err|unknown)\([^,]+,\s*"(\w+)"/g),
+                         ...lib.matchAll(/\bnamed\([^,]+,[^,]+,[^,]+,\s*"(\w+)"/g)]
+    .map((m) => m[1]));
+  const section = doc.slice(doc.indexOf("## Error and warning codes"), doc.indexOf("\n## ", doc.indexOf("## Error and warning codes") + 1));
+  const documented = new Set([...section.matchAll(/^\| ([^|]+) \|/gm)].flatMap((m) => [...m[1].matchAll(/`(\w+)`/g)].map((x) => x[1])));
+  for (const c of codes) if (!documented.has(c)) out.push(`problem code ${c}: not in the codes table of docs/story-author.md`);
+  for (const c of documented) if (!codes.has(c)) out.push(`docs/story-author.md: problem code ${c} is not one the tool reports`);
+  return out;
+};
+
+// ------------------------------------------------------------------------------------------------ workflows
+
+// the one-line `- run:` commands of a job of a workflow file (the job's block: from "  <job>:" to the next job)
+const jobRuns = (file, job) => {
+  const text = read(file), start = text.search(new RegExp(`^ {2}${job}:\\s*$`, "m"));
+  if (start < 0) return null;
+  const rest = text.slice(start + 1), end = rest.search(/^ {2}[\w-]+:\s*$/m);
+  return [...(end < 0 ? rest : rest.slice(0, end)).matchAll(/^ {6}- run: (.+)$/gm)].map((m) => m[1].trim());
+};
+
+const checkWorkflows = () => {
+  const ci = jobRuns(".github/workflows/ci.yml", "test"), release = jobRuns(".github/workflows/release.yml", "build");
+  if (!ci || !release) return ["the CI test job or the release build job is missing"];
+  return ci.join("\n") === release.join("\n") ? []
+    : [`the CI test job runs ${JSON.stringify(ci)}, the release build job ${JSON.stringify(release)}`];
+};
+
+// ------------------------------------------------------------------------------------------------ main
+
+const CONTRACTS = { package: checkPackage, entries: checkEntries, schemas: checkSchemas, formats: checkFormats,
+                    links: checkLinks, "story-author": checkStoryAuthor, workflows: checkWorkflows };
+
+let problems = 0;
+for (const [name, check] of Object.entries(CONTRACTS)) {
+  for (const p of await check()) { process.stdout.write(`${name}: ${p}\n`); problems++; }
+}
+process.stdout.write(problems ? `${problems} problem${problems > 1 ? "s" : ""}\n`
+                              : `${Object.keys(CONTRACTS).length} contracts hold\n`);
+process.exitCode = problems ? 1 : 0;