@openvidstudio/mcp-server 1.3.1 → 1.4.0

package/dist/lessonArc.d.ts

@@ -0,0 +1,68 @@
+/** With no caption element in the frame, the bottom of the frame is assumed to hold the captions: the Reels safe zone. */
+export declare const DEFAULT_CAPTION_BAND = 0.22;
+export interface ArcThresholds {
+    /** The first drawn element after this many seconds is a warning. */
+    diagramWarnSeconds: number;
+    /** After this many seconds it is an error. */
+    diagramErrorSeconds: number;
+    /** A run of identical sampled frames longer than this is a warning. */
+    staticSeconds: number;
+}
+export declare const DEFAULT_ARC_THRESHOLDS: ArcThresholds;
+/** A rectangle in frame pixels. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** What one sampled frame contributes to the arc checks. */
+export interface ArcSample {
+    /** Seconds from the start of the lesson. */
+    time: number;
+    beatId: string;
+    /** Share of the unmasked pixels drawn beyond the background, 0 to 1. */
+    drawn: number;
+    /** Share of the unmasked pixels that moved since the previous sample, or null for the first one. */
+    changedFromPrevious: number | null;
+}
+/** What is kept of a frame so the next one can be compared with it. */
+export interface ArcSignature {
+    data: Buffer;
+    mask: Uint8Array;
+    width: number;
+    height: number;
+}
+export interface ArcFinding {
+    beatId: string;
+    check: "diagram-late" | "static-stretch";
+    severity: "warning" | "error";
+    message: string;
+}
+/** Rectangles to ignore in a frame: the captions' own boxes when the page has them, otherwise the bottom band. */
+export declare function captionMaskRects(found: Rect[], frame: {
+    width: number;
+    height: number;
+}): Rect[];
+/** Pure: the share of unmasked pixels that sit further than DRAWN_DISTANCE from the frame's background colour. */
+export declare function drawnShare(data: Buffer, mask: Uint8Array, width: number, height: number): number;
+/** Pure: the share of pixels, unmasked in both frames, that moved by more than MOVED_DISTANCE. */
+export declare function movedShare(a: ArcSignature, b: ArcSignature): number;
+/**
+ * Reads one screenshot into what the arc checks need. `previous` is the signature of the sample before it, so
+ * the caller keeps one frame in memory, not all of them.
+ */
+export declare function measureArcFrame(shot: string, captionRects: Rect[], previous: ArcSignature | null): Promise<{
+    drawn: number;
+    changedFromPrevious: number | null;
+    signature: ArcSignature;
+}>;
+/**
+ * Pure: the findings, given the samples in lesson order and the lesson's length.
+ *
+ * `diagram-late` reads the first sampled frame with anything drawn. `static-stretch` finds each run of sampled
+ * frames that did not change, and estimates how long the hold really lasted: the true edges lie between a held
+ * sample and its changed neighbour, so each is taken as the midpoint, and the lesson's own start and end bound a
+ * run that touches them. A 6 s hold sampled twice is therefore still about 6 s, not the 4 s between its samples.
+ */
+export declare function judgeLessonArc(samples: ArcSample[], lessonSeconds: number, thresholds?: ArcThresholds): ArcFinding[];

package/dist/lessonArc.js

@@ -0,0 +1,188 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ARC_THRESHOLDS = exports.DEFAULT_CAPTION_BAND = void 0;
+exports.captionMaskRects = captionMaskRects;
+exports.drawnShare = drawnShare;
+exports.movedShare = movedShare;
+exports.measureArcFrame = measureArcFrame;
+exports.judgeLessonArc = judgeLessonArc;
+const sharp_1 = __importDefault(require("sharp"));
+/**
+ * The two rules of a lesson's shape (SCRIPT.md, "The arc") that are about the picture, not the words:
+ * the diagram is on screen early, and the viewer never waits long with nothing changing.
+ *
+ * Both are judged from the frames validate_scenes already samples in render mode, so there is no extra
+ * render pass. Each sampled frame is reduced to two numbers, taken with the caption region masked:
+ * how much of it is drawn beyond the background, and how much of it moved since the previous sample.
+ */
+/** Frame width the "has anything been drawn" measure runs at: wide enough that a thin axis line survives. */
+const CONTENT_WIDTH = 540;
+/** Frame width two samples are compared at; averaging away encoder noise is the point of the small size. */
+const SIGNATURE_WIDTH = 270;
+/** A pixel counts as drawn when it differs from the frame's background colour by more than this in any channel. The Void's 5% hairline grid is about 13, so it does not count. */
+const DRAWN_DISTANCE = 40;
+/** Share of the unmasked pixels that must be drawn before a frame counts as having a diagram, about 250 pixels of a 540x960 frame. */
+const DRAWN_MIN_SHARE = 0.0005;
+/** Per-channel change that counts as a moved pixel, and the share of moved pixels below which two samples are identical (frameDiff's numbers). */
+const MOVED_DISTANCE = 12;
+const IDENTICAL_MAX_SHARE = 0.002;
+/** With no caption element in the frame, the bottom of the frame is assumed to hold the captions: the Reels safe zone. */
+exports.DEFAULT_CAPTION_BAND = 0.22;
+exports.DEFAULT_ARC_THRESHOLDS = { diagramWarnSeconds: 15, diagramErrorSeconds: 25, staticSeconds: 8 };
+/** Rectangles to ignore in a frame: the captions' own boxes when the page has them, otherwise the bottom band. */
+function captionMaskRects(found, frame) {
+    if (found.length > 0)
+        return found;
+    const band = Math.round(frame.height * exports.DEFAULT_CAPTION_BAND);
+    return [{ x: 0, y: frame.height - band, width: frame.width, height: band }];
+}
+function maskFor(rects, scale, width, height) {
+    const mask = new Uint8Array(width * height);
+    for (const r of rects) {
+        const x0 = Math.max(0, Math.floor(r.x * scale));
+        const y0 = Math.max(0, Math.floor(r.y * scale));
+        const x1 = Math.min(width, Math.ceil((r.x + r.width) * scale));
+        const y1 = Math.min(height, Math.ceil((r.y + r.height) * scale));
+        for (let y = y0; y < y1; y++)
+            mask.fill(1, y * width + x0, y * width + x1);
+    }
+    return mask;
+}
+/** The background colour of a frame: the most common colour once each channel is rounded to a multiple of 8. */
+function backgroundOf(data, mask, pixels) {
+    const counts = new Map();
+    let best = 0;
+    let bestCount = 0;
+    for (let p = 0; p < pixels; p++) {
+        if (mask[p])
+            continue;
+        const key = ((data[p * 3] >> 3) << 10) | ((data[p * 3 + 1] >> 3) << 5) | (data[p * 3 + 2] >> 3);
+        const n = (counts.get(key) ?? 0) + 1;
+        counts.set(key, n);
+        if (n > bestCount) {
+            best = key;
+            bestCount = n;
+        }
+    }
+    return [((best >> 10) & 31) * 8 + 4, ((best >> 5) & 31) * 8 + 4, (best & 31) * 8 + 4];
+}
+/** Pure: the share of unmasked pixels that sit further than DRAWN_DISTANCE from the frame's background colour. */
+function drawnShare(data, mask, width, height) {
+    const pixels = width * height;
+    const [br, bg, bb] = backgroundOf(data, mask, pixels);
+    let considered = 0;
+    let drawn = 0;
+    for (let p = 0; p < pixels; p++) {
+        if (mask[p])
+            continue;
+        considered++;
+        const i = p * 3;
+        if (Math.max(Math.abs(data[i] - br), Math.abs(data[i + 1] - bg), Math.abs(data[i + 2] - bb)) > DRAWN_DISTANCE)
+            drawn++;
+    }
+    return considered === 0 ? 0 : drawn / considered;
+}
+/** Pure: the share of pixels, unmasked in both frames, that moved by more than MOVED_DISTANCE. */
+function movedShare(a, b) {
+    if (a.width !== b.width || a.height !== b.height)
+        return 1;
+    const pixels = a.width * a.height;
+    let considered = 0;
+    let moved = 0;
+    for (let p = 0; p < pixels; p++) {
+        if (a.mask[p] || b.mask[p])
+            continue;
+        considered++;
+        const i = p * 3;
+        if (Math.abs(a.data[i] - b.data[i]) > MOVED_DISTANCE ||
+            Math.abs(a.data[i + 1] - b.data[i + 1]) > MOVED_DISTANCE ||
+            Math.abs(a.data[i + 2] - b.data[i + 2]) > MOVED_DISTANCE) {
+            moved++;
+        }
+    }
+    return considered === 0 ? 0 : moved / considered;
+}
+/**
+ * Reads one screenshot into what the arc checks need. `previous` is the signature of the sample before it, so
+ * the caller keeps one frame in memory, not all of them.
+ */
+async function measureArcFrame(shot, captionRects, previous) {
+    const meta = await (0, sharp_1.default)(shot).metadata();
+    const frame = { width: meta.width ?? CONTENT_WIDTH, height: meta.height ?? CONTENT_WIDTH };
+    const rects = captionMaskRects(captionRects, frame);
+    const wide = await (0, sharp_1.default)(shot).removeAlpha().resize({ width: CONTENT_WIDTH }).raw().toBuffer({ resolveWithObject: true });
+    const wideMask = maskFor(rects, wide.info.width / frame.width, wide.info.width, wide.info.height);
+    const drawn = drawnShare(wide.data, wideMask, wide.info.width, wide.info.height);
+    const small = await (0, sharp_1.default)(shot).removeAlpha().resize({ width: SIGNATURE_WIDTH }).raw().toBuffer({ resolveWithObject: true });
+    const signature = {
+        data: small.data,
+        mask: maskFor(rects, small.info.width / frame.width, small.info.width, small.info.height),
+        width: small.info.width,
+        height: small.info.height,
+    };
+    return { drawn, changedFromPrevious: previous ? movedShare(previous, signature) : null, signature };
+}
+const seconds = (s) => `${Math.round(s * 10) / 10} s`;
+/**
+ * Pure: the findings, given the samples in lesson order and the lesson's length.
+ *
+ * `diagram-late` reads the first sampled frame with anything drawn. `static-stretch` finds each run of sampled
+ * frames that did not change, and estimates how long the hold really lasted: the true edges lie between a held
+ * sample and its changed neighbour, so each is taken as the midpoint, and the lesson's own start and end bound a
+ * run that touches them. A 6 s hold sampled twice is therefore still about 6 s, not the 4 s between its samples.
+ */
+function judgeLessonArc(samples, lessonSeconds, thresholds = exports.DEFAULT_ARC_THRESHOLDS) {
+    const findings = [];
+    if (samples.length === 0)
+        return findings;
+    const firstDrawn = samples.find((s) => s.drawn >= DRAWN_MIN_SHARE);
+    if (!firstDrawn) {
+        findings.push({
+            beatId: "*",
+            check: "diagram-late",
+            severity: "error",
+            message: `No sampled frame has anything drawn beyond the background and the captions, so the diagram never ` +
+                `appears. The arc wants its first element on screen inside ${thresholds.diagramWarnSeconds} s.`,
+        });
+    }
+    else if (firstDrawn.time > thresholds.diagramWarnSeconds) {
+        const error = firstDrawn.time > thresholds.diagramErrorSeconds;
+        findings.push({
+            beatId: firstDrawn.beatId,
+            check: "diagram-late",
+            severity: error ? "error" : "warning",
+            message: `The first thing drawn beyond the background and the captions is in a frame ${seconds(firstDrawn.time)} into the ` +
+                `lesson. The arc wants the diagram's first element inside ${thresholds.diagramWarnSeconds} s (an error past ` +
+                `${thresholds.diagramErrorSeconds} s): a viewer facing an empty frame that long scrolls on.`,
+        });
+    }
+    let i = 1;
+    while (i < samples.length) {
+        const held = (n) => samples[n].changedFromPrevious !== null && samples[n].changedFromPrevious <= IDENTICAL_MAX_SHARE;
+        if (!held(i)) {
+            i++;
+            continue;
+        }
+        const first = i - 1;
+        let last = i;
+        while (last + 1 < samples.length && held(last + 1))
+            last++;
+        const start = first > 0 ? (samples[first - 1].time + samples[first].time) / 2 : 0;
+        const end = last < samples.length - 1 ? (samples[last].time + samples[last + 1].time) / 2 : lessonSeconds;
+        if (end - start > thresholds.staticSeconds) {
+            findings.push({
+                beatId: samples[first].beatId,
+                check: "static-stretch",
+                severity: "warning",
+                message: `Nothing changes for about ${seconds(end - start)} (from about ${seconds(start)} to ${seconds(end)}; frames sampled ` +
+                    `across it match, captions aside). The arc wants something to move at least every ${thresholds.staticSeconds} s: ` +
+                    `bring the next element in sooner, add a Spark move, or split the beat.`,
+            });
+        }
+        i = last + 1;
+    }
+    return findings;
+}

package/dist/server.d.ts

@@ -2,7 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { OpenvidstudioConfig } from "./config";
 export * from "./api";
 export declare const SERVER_NAME = "openvidstudio";
-export declare const SERVER_VERSION = "1.3.1";
+export declare const SERVER_VERSION = "1.4.0";
 /**
  * Assembly only, mirrors pepiros/mcp/server.ts's shape: transport lives in the entry
  * point (stdio.ts), not here, so the same server instance could later be served over a

package/dist/server.js

@@ -22,7 +22,7 @@ const mcp_1 = require("./tools/mcp");
 // The non-MCP entry points, for callers with no agent in the loop (CI, cron).
 __exportStar(require("./api"), exports);
 exports.SERVER_NAME = "openvidstudio";
-exports.SERVER_VERSION = "1.3.1";
+exports.SERVER_VERSION = "1.4.0";
 /**
  * Assembly only, mirrors pepiros/mcp/server.ts's shape: transport lives in the entry
  * point (stdio.ts), not here, so the same server instance could later be served over a

package/dist/stdio.js

@@ -27,7 +27,15 @@ async function main() {
     await server.connect(transport);
     process.stderr.write("openvidstudio-mcp: connected over stdio\n");
 }
-main().catch((err) => {
-    process.stderr.write(`openvidstudio-mcp: fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
-    process.exit(1);
-});
+// `openvidstudio-mcp install <client>` writes the server into a client's MCP config and exits. It is
+// the only mode that prints to stdout; a normal start (no arguments) never does.
+if (process.argv[2] === "install") {
+    const { installCli } = require("./install");
+    process.exit(installCli(process.argv.slice(3)));
+}
+else {
+    main().catch((err) => {
+        process.stderr.write(`openvidstudio-mcp: fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/tools/checkScript.d.ts

@@ -25,12 +25,37 @@ export interface ConceptCard {
     referenceSpoken?: string;
     /** The longest the lesson may run, in seconds. Default 120. */
     maxSeconds?: number;
+    /**
+     * The lesson's shape. "seven-beat" (the default, and what a card without this field gets) is the arc in SCRIPT.md;
+     * "story" is the story-first arc: a real situation told as a problem, a narrator, the key formulas, the formulas
+     * applied to the story's numbers, one watch out, then a practice question. The story fields below are only read
+     * for "story".
+     */
+    arc?: "seven-beat" | "story";
+    /** Story arc: the one real-world scene the lesson opens on. The first beat has to name it. */
+    situation?: string;
+    /** Story arc: the narrator's name. */
+    character?: string;
+    /**
+     * Story arc: the key formulas, in the order they are stated. `tex` is what is on screen, `spoken` how it is said
+     * (it has to occur in the narration, in this order), `source` where it comes from (a syllabus booklet, a derivation).
+     */
+    formulas?: StoryFormula[];
+    /** Story arc: the original practice question. The last beat ends with it. */
+    practiceQuestion?: string;
+    /** Story arc: the practice question's answer. It is withheld from the narration (it goes in the pinned comment). */
+    answer?: string;
+}
+export interface StoryFormula {
+    tex: string;
+    spoken: string;
+    source: string;
 }
 export type ScriptFindingSeverity = "error" | "warning" | "note";
 export interface ScriptFinding {
     severity: ScriptFindingSeverity;
     /** Which check produced it. */
-    check: "sentence-length" | "reading-level" | "glossary" | "new-terms" | "spoken" | "hook" | "pace" | "closing-question" | "length" | "reference";
+    check: "sentence-length" | "reading-level" | "glossary" | "new-terms" | "spoken" | "hook" | "pace" | "closing-question" | "length" | "reference" | "story-situation" | "story-formula" | "story-practice" | "story-comment" | "story-subscribe" | "story-answer";
     beatId: string;
     message: string;
 }
@@ -69,6 +94,11 @@ export declare function syllables(word: string): number;
 export declare function fleschKincaidGrade(text: string): number;
 /** The `spoken` strings of the Equations in a scene's source. */
 export declare function spokenStrings(source: string): string[];
+/**
+ * The `spoken` strings of each `<Derivation>` in a scene's source, in step order, one list per Derivation. The steps
+ * may be written inline (`steps={[{ tex, spoken }, ...]}`) or as a constant in the same file (`steps={STEPS}`).
+ */
+export declare function derivationSpoken(source: string): string[][];
 export declare function checkScriptLogic(beatsJson: unknown, card: ConceptCard, readScene?: (beat: BeatLike, id: string) => string | null): CheckScriptResult;
 export declare function runCheckScript(input: CheckScriptInput): CheckScriptResult;
 export declare function registerCheckScript(server: McpServer): void;

package/dist/tools/checkScript.js

@@ -38,6 +38,7 @@ exports.splitSentences = splitSentences;
 exports.syllables = syllables;
 exports.fleschKincaidGrade = fleschKincaidGrade;
 exports.spokenStrings = spokenStrings;
+exports.derivationSpoken = derivationSpoken;
 exports.checkScriptLogic = checkScriptLogic;
 exports.runCheckScript = runCheckScript;
 exports.registerCheckScript = registerCheckScript;
@@ -83,6 +84,11 @@ function fleschKincaidGrade(text) {
     return 0.39 * (words.length / sentences.length) + 11.8 * (syl / words.length) - 15.59;
 }
 const normalise = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().replace(/\s+/g, " ");
+const STOP_WORDS = new Set("the and for with that this from have has had was were are but not you your his her its our their they them then than into onto over under about what when where which while will would could should can did does out off one all any too very just also more most some such only own same each both few other how why who whom".split(" "));
+/** The distinct content words of a text: normalised, three letters or more, no stop words. */
+function contentWords(text) {
+    return new Set(normalise(text).split(" ").filter((w) => w.length >= 3 && !STOP_WORDS.has(w)));
+}
 const NUMBER_WORDS = /\b(zero|one|two|three|four|five|six|seven|eight|nine|ten|hundred|thousand|million|billion|half|double|twice)\b/i;
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const wordRe = (term) => new RegExp(`(?<![A-Za-z0-9])${escapeRe(term)}(?![A-Za-z0-9])`, "i");
@@ -105,12 +111,145 @@ function spokenStrings(source) {
         out.push(m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? "");
     return out;
 }
+/** The text between the bracket at `open` and its match, strings respected, or null if it never closes. */
+function balanced(source, open) {
+    const pairs = { "[": "]", "{": "}", "(": ")" };
+    const stack = [];
+    let quote = null;
+    for (let i = open; i < source.length; i++) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === "\\")
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`")
+            quote = ch;
+        else if (ch in pairs)
+            stack.push(pairs[ch]);
+        else if (ch === stack[stack.length - 1]) {
+            stack.pop();
+            if (stack.length === 0)
+                return source.slice(open, i + 1);
+        }
+    }
+    return null;
+}
+/**
+ * The `spoken` strings of each `<Derivation>` in a scene's source, in step order, one list per Derivation. The steps
+ * may be written inline (`steps={[{ tex, spoken }, ...]}`) or as a constant in the same file (`steps={STEPS}`).
+ */
+function derivationSpoken(source) {
+    const out = [];
+    for (const tag of source.matchAll(/<Derivation\b/g)) {
+        const open = tag.index ?? 0;
+        const props = source.slice(open, open + 20000);
+        const steps = /\bsteps\s*=\s*\{/.exec(props);
+        if (!steps)
+            continue;
+        const braceAt = open + steps.index + steps[0].length - 1;
+        const inner = balanced(source, braceAt);
+        if (inner === null)
+            continue;
+        let list = inner;
+        const ident = /^\{\s*([A-Za-z_$][\w$]*)\s*\}$/.exec(inner);
+        if (ident) {
+            const decl = new RegExp(`\\b${ident[1]}\\b\\s*(?::[^=]+)?=\\s*\\[`).exec(source);
+            list = decl ? balanced(source, decl.index + decl[0].length - 1) : null;
+        }
+        if (list === null)
+            continue;
+        const found = [];
+        for (const m of list.matchAll(/\bspoken\s*:\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/g))
+            found.push(m[1] ?? m[2] ?? m[3] ?? "");
+        out.push(found);
+    }
+    return out;
+}
+/**
+ * The checks for the story arc. They look at the narration as a whole and at its first and last beat, and never
+ * count beats, so a story lesson may take as many beats as it needs.
+ */
+function checkStoryArc(spoken, card, add) {
+    if (spoken.length === 0)
+        return;
+    const idOf = (beat, i) => String(beat.id ?? `beat ${i + 1}`);
+    const first = spoken[0];
+    const last = spoken[spoken.length - 1];
+    const lastId = idOf(last, spoken.length - 1);
+    // beat 1 names the situation: it shares at least two content words with it
+    if (typeof card.situation !== "string" || card.situation.trim().length === 0) {
+        add("warning", "story-situation", idOf(first, 0), `The story arc needs a situation on the concept card, so the first beat cannot be checked for naming it.`);
+    }
+    else {
+        const wanted = contentWords(card.situation);
+        const said = contentWords(first.vo);
+        const shared = [...wanted].filter((w) => said.has(w));
+        const need = Math.min(2, wanted.size);
+        if (shared.length < need) {
+            add("error", "story-situation", idOf(first, 0), `The first beat shares ${shared.length} content word${shared.length === 1 ? "" : "s"} with the situation "${card.situation}", and the story arc needs ${need}. Open on the situation, told as a problem.`);
+        }
+    }
+    // each formula's spoken form is in the narration, in the order the card gives them
+    const beatText = spoken.map((b) => normalise(b.vo));
+    const heard = beatText.join(" ");
+    const starts = [];
+    beatText.reduce((at, t) => (starts.push(at), at + t.length + 1), 0);
+    const beatAt = (pos) => {
+        let k = 0;
+        while (k + 1 < starts.length && starts[k + 1] <= pos)
+            k++;
+        return idOf(spoken[k], k);
+    };
+    let cursor = 0;
+    (card.formulas ?? []).forEach((f, k) => {
+        if (typeof f?.spoken !== "string" || normalise(f.spoken).length === 0)
+            return;
+        const phrase = normalise(f.spoken);
+        const at = heard.indexOf(phrase, cursor);
+        if (at >= 0) {
+            cursor = at + phrase.length;
+        }
+        else if (heard.includes(phrase)) {
+            add("error", "story-formula", beatAt(heard.indexOf(phrase)), `Formula ${k + 1} ("${f.spoken}") is said before the formula above it. The card lists the formulas in the order they are stated, so the narration has to say them in that order.`);
+        }
+        else {
+            add("error", "story-formula", idOf(first, 0), `Formula ${k + 1}, spoken as "${f.spoken}", is not in the narration. The voice has to say each key formula the way the card spells it.`);
+        }
+    });
+    // the last beat ends with the practice question and asks for an answer in the comments
+    if (typeof card.practiceQuestion !== "string" || normalise(card.practiceQuestion).length === 0) {
+        add("warning", "story-practice", lastId, `The story arc needs a practiceQuestion on the concept card, so the last beat cannot be checked for ending with it.`);
+    }
+    else if (!normalise(last.vo).endsWith(normalise(card.practiceQuestion))) {
+        add("error", "story-practice", lastId, `The last beat does not end with the practice question "${card.practiceQuestion}". End on the question and let the last frame hold.`);
+    }
+    if (!/comment/i.test(last.vo)) {
+        add("error", "story-comment", lastId, `The last beat never asks the viewer to answer in the comments. Add a prompt such as "put your answer in the comments".`);
+    }
+    // "like and subscribe" anywhere is a warning
+    spoken.forEach((b, i) => {
+        if (/\blike\s*(?:,|and|&)?\s*(?:and\s+)?subscribe\b/i.test(b.vo)) {
+            add("warning", "story-subscribe", idOf(b, i), `This beat says "like and subscribe". The lesson ends on its question and the prompt to comment, nothing else.`);
+        }
+    });
+    // the answer is withheld until the pinned comment
+    if (typeof card.answer === "string" && normalise(card.answer).length > 0) {
+        const at = beatText.findIndex((t) => ` ${t} `.includes(` ${normalise(card.answer)} `));
+        if (at >= 0) {
+            add("warning", "story-answer", idOf(spoken[at], at), `The answer "${card.answer}" is in the narration. Withhold it: it belongs in the pinned comment, not in the video.`);
+        }
+    }
+}
 function checkScriptLogic(beatsJson, card, readScene = () => null) {
     const findings = [];
     const root = (typeof beatsJson === "object" && beatsJson !== null ? beatsJson : {});
     const fps = typeof root.fps === "number" && root.fps > 0 ? root.fps : 30;
     const beats = (Array.isArray(root.beats) ? root.beats : []);
     const add = (severity, check, beatId, message) => findings.push({ severity, check, beatId, message });
+    const story = card.arc === "story";
     const seen = new Set();
     const spoken = beats.filter((b) => typeof b.vo === "string" && b.vo.length > 0);
     spoken.forEach((beat, index) => {
@@ -160,6 +299,23 @@ function checkScriptLogic(beatsJson, card, readScene = () => null) {
                     add("error", "spoken", id, `The equation's spoken form "${said}" is not in this beat's narration. The voice and the equation must say the same thing.`);
                 }
             }
+            // A Derivation's steps are said in order: each one after the one before it.
+            for (const steps of derivationSpoken(source)) {
+                let cursor = 0;
+                steps.forEach((said, k) => {
+                    const phrase = normalise(said);
+                    const at = heard.indexOf(phrase, cursor);
+                    if (at >= 0) {
+                        cursor = at + phrase.length;
+                    }
+                    else if (heard.includes(phrase)) {
+                        add("error", "spoken", id, `The derivation's step ${k + 1} ("${said}") is said in this beat's narration, but before the step above it. The steps are revealed in order, so the voice has to say them in that order.`);
+                    }
+                    else {
+                        add("error", "spoken", id, `The derivation's step ${k + 1} spoken form "${said}" is not in this beat's narration. The voice and the formula must say the same thing.`);
+                    }
+                });
+            }
         }
     });
     // terms the card names that the narration never mentions
@@ -192,18 +348,20 @@ function checkScriptLogic(beatsJson, card, readScene = () => null) {
         if (/^\s*in this video\b/i.test(lead)) {
             add("error", "hook", id, `The script opens "in this video". Open on a question or a surprising fact, not a promise of what is coming.`);
         }
-        else if (!lead.trim().endsWith("?") && !/\d/.test(lead) && !NUMBER_WORDS.test(lead)) {
+        else if (!story && !lead.trim().endsWith("?") && !/\d/.test(lead) && !NUMBER_WORDS.test(lead)) {
             add("warning", "hook", id, `The first sentence is neither a question nor does it hold a number. The hook is a question or a surprising fact.`);
         }
     }
-    // the end: a check question
-    if (spoken.length > 0) {
+    // the end: a check question (a story lesson ends on its practice question instead, checked below)
+    if (!story && spoken.length > 0) {
         const last = spoken[spoken.length - 1];
         const lastSentence = splitSentences(last.vo).slice(-1)[0] ?? "";
         if (!lastSentence.trim().endsWith("?")) {
             add("error", "closing-question", String(last.id ?? "last beat"), `The last beat does not end with a question. End with a one-line recap, then a check question the viewer can answer in their head.`);
         }
     }
+    if (story)
+        checkStoryArc(spoken, card, add);
     return { ok: !findings.some((f) => f.severity === "error"), beatsChecked: spoken.length, findings };
 }
 function runCheckScript(input) {
@@ -226,7 +384,10 @@ function runCheckScript(input) {
         card = JSON.parse(fs.readFileSync(file, "utf8"));
     }
     if (typeof card !== "object" || card === null || typeof card.goal !== "string" || !Array.isArray(card.terms) || typeof card.example !== "string") {
-        throw new Error("The concept card must be { goal: string, terms: string[], example: string } with the optional reference, referenceSpoken and maxSeconds.");
+        throw new Error("The concept card must be { goal: string, terms: string[], example: string } with the optional reference, referenceSpoken, maxSeconds and, for the story arc, arc, situation, character, formulas, practiceQuestion and answer.");
+    }
+    if (card.arc !== undefined && card.arc !== "seven-beat" && card.arc !== "story") {
+        throw new Error(`The concept card's arc must be "seven-beat" or "story", not ${JSON.stringify(card.arc)}.`);
     }
     const readScene = (beat, id) => {
         const rel = typeof beat.scene === "string" && beat.scene.length > 0 ? beat.scene : path.join("scenes", `${(0, util_1.pascalCase)(id)}.tsx`);
@@ -247,17 +408,24 @@ function registerCheckScript(server) {
         title: "Lint a lesson script against its concept card",
         description: "Mechanical lint for a Supernova lesson script, no model call: it counts and matches patterns, so it can " +
             "say a sentence is long or a term was never defined, not that the explanation is good. Reads " +
-            "src/videos/<videoName>/beats.json and concept.json ({ goal, terms: string[], example, reference?, referenceSpoken?, maxSeconds? }, next to it), or the " +
+            "src/videos/<videoName>/beats.json and concept.json ({ goal, terms: string[], example, reference?, referenceSpoken?, maxSeconds?, arc?, situation?, character?, formulas?, practiceQuestion?, answer? }, next to it), or the " +
             "beatsJson and conceptCard inputs. Returns { ok, beatsChecked, findings } where each finding has a severity " +
             "(error, warning or note), the check, and the beat it points at. Checks: average sentence length per beat " +
             "(warning above 16 words), Flesch-Kincaid reading level per beat (warning above grade 9), each concept-card " +
             "term used with a definition beside it at first mention (note), more than two new terms in a beat (warning), " +
-            "every Equation's `spoken` string present in its beat's narration (error; the scene is read from the beat's " +
+            "every Equation's `spoken` string present in its beat's narration, and every step of a Derivation present and in the order " +
+            "the steps are given (error; the scene is read from the beat's " +
             "scene path or scenes/<BeatId>.tsx), a hook in the first sentence that is a question or holds a number and " +
             "does not open \"in this video\" (error for that opener, warning otherwise), words per second against the " +
             "beat length using validate_beats' own budget (error), a last beat that ends with a question (error), the " +
             "total length against the card's maxSeconds (default 120, error), and, when the card has a reference such as a " +
             "chapter code, that the first beat's narration says its referenceSpoken (error; warning if referenceSpoken is missing). " +
+            "The card's `arc` is \"seven-beat\" (the default) or \"story\". For \"story\" (situation, character, formulas: [{ tex, spoken, source }], " +
+            "practiceQuestion, answer), the closing-question check and the hook's warning give way to these, none of which count beats: " +
+            "story-situation (the first beat shares at least two content words with the situation, error), story-formula (each formula's spoken form is in the " +
+            "narration, in the order given, error), story-practice (the last beat ends with the practice question, error), story-comment (the last beat " +
+            "contains a prompt matching /comment/i, error), story-subscribe (\"like and subscribe\" anywhere, warning) and story-answer (the answer is " +
+            "in the narration, warning); a missing situation or practiceQuestion is a warning. Length, reference and the per-beat checks apply to both arcs. " +
             "ok is false only when a finding is an error. See SCRIPT.md's lesson script rules.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
@@ -271,6 +439,15 @@ function registerCheckScript(server) {
                 reference: zod_1.z.string().optional(),
                 referenceSpoken: zod_1.z.string().optional(),
                 maxSeconds: zod_1.z.number().positive().optional(),
+                arc: zod_1.z.enum(["seven-beat", "story"]).optional().describe('The lesson shape. Default "seven-beat".'),
+                situation: zod_1.z.string().optional().describe("Story arc: the real-world scene the first beat names."),
+                character: zod_1.z.string().optional().describe("Story arc: the narrator's name."),
+                formulas: zod_1.z
+                    .array(zod_1.z.object({ tex: zod_1.z.string(), spoken: zod_1.z.string(), source: zod_1.z.string() }))
+                    .optional()
+                    .describe("Story arc: the key formulas in the order they are stated; each spoken form must be in the narration, in order."),
+                practiceQuestion: zod_1.z.string().optional().describe("Story arc: the question the last beat ends with."),
+                answer: zod_1.z.string().optional().describe("Story arc: the answer, which must not be in the narration."),
             })
                 .optional()
                 .describe("The concept card, instead of reading concept.json."),