Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
merge: integrate main reconstruction tooling
kashorin75c4f61be9b4
diff --cc packages/caption-fine/src/render.tsindex ba46bfb9,fcc59534..a7b3cb3e--- a/packages/caption-fine/src/render.ts+++ b/packages/caption-fine/src/render.ts@@@ -597,13 -594,20 +609,26 @@@ function cueElementsconst transform = anchorTransform(parameters);const cueMotion = cueAnimation(parameters, durationFrames);const cueLoop = parameters.motion.loopTarget === "cue" ? loopAnimation(parameters, durationFrames) : undefined;+ const gapPx = `${compactNumber(parameters.layout.wordGapPx)}px`;+ const atomSurfaces = atoms.map((atom) => atom.wordIds.map((wordId) => wordText.get(wordId) ?? ""));+ // A Cue whose boundaries all agree carries one `column-gap`, which is also what keeps a row that+ // wraps from opening on a margin. A Cue that mixes scripts spaces each element instead.+ const atomGaps = atomSurfaces.map((surfaces, index) => {+ const previous = atomSurfaces[index - 1];+ return previous === undefined ? false : wordGapBetween(previous.at(-1) ?? "", surfaces[0] ?? "");+ });+ const cueGap = uniformGap(atomGaps);+ // The Visual IR carries physical margins, so the leading edge follows the Cue's own direction.+ const marginStart = parameters.layout.direction === "rtl" ? "margin-right" : "margin-left";+ const spacedStyle = (spaced: boolean): readonly VisualStyleDeclaration[] =>+ spaced ? [{ name: marginStart, value: gapPx }] : [];const fonts = parameters.typography.exactFonts;+ if (parameters.layout.maxLines !== undefined) {+ const rows = structuralRowCount(atoms, parameters.layout.maxWordsPerLine!);+ if (rows > parameters.layout.maxLines) {+ throw new Error(`Fine Caption Style ${styleId} constructs ${rows} rows for a Cue whose maximum is ${parameters.layout.maxLines}`);+ }+ }push({id: "placement",kind: "box",@@@ -836,9 -863,13 +873,12 @@@parent: atomId,kind: "text",text,- style: glyphStyle(parameters, parameters.basePaint, parameters.underline),+ style: [+ ...glyphStyle(parameters, parameters.basePaint, parameters.underline),+ ...(wordGap === undefined ? spacedStyle(gaps[wordIndex] ?? false) : []),+ ],...glyphPaintFields(parameters.basePaint),fonts,- attributes: [{ name: "data-caption-word", value: wordId }],});}const addActivatedTextLayer = (diff --cc packages/hyperframes/src/text.tsindex f1b0bf3f,07c67e17..c8409181--- a/packages/hyperframes/src/text.ts+++ b/packages/hyperframes/src/text.ts@@@ -237,7 -257,12 +238,12 @@@ function documentGlyphPaintLayers(elemeappend(paragraph.style?.paints);for (const inline of paragraph.inlines) if (inline.kind === "text") append(inline.style?.paints);}+ return layers;+ }++ function glyphFilterDefinitions(element: TerminalTextElement, context: TextRenderContext): string {+ const layers = documentGlyphPaintLayers(element);- const filtered = layers.filter((paint): paint is Extract<GlyphPaintLayer, { kind: "stroke" | "shadow" | "glow" }> => paint.kind !== "fill");+ const filtered = layers.filter(usesGlyphFilter);const definitions = [...new Map(filtered.map((paint) => [canonicalStringify(paint), paint])).values()].map((paint) => glyphFilterDefinition(paint, context)).join("");return definitions;diff --cc packages/markup/src/types.tsindex 8e20c37a,56f651ad..5f398bad--- a/packages/markup/src/types.ts+++ b/packages/markup/src/types.ts@@@ -132,10 -126,19 +132,11 @@@ export type SurfaceRecipePropertyVocabureadonly name: string;readonly required: boolean;readonly summary: string;- /** Stable Inspector page owned by the component package. */- readonly group?: "where" | "how" | "when" | string;- /** Optional package-owned subsection inside the page. */- readonly section?: string;+ /** The author value's public structure; it contains no editor presentation. */+ readonly schema?: ValueSchema;readonly values?: readonly string[];- /**- * The default as it is written in a Recipe, which is text even when it reads as a number: `"0"`,- * not `0`. A Recipe property's value arrives as written and each Style decodes its own, so what a- * fallback records is the source line an author would have typed. A number here is refused deep- * inside the surface declaration, where the complaint is about the whole vocabulary rather than- * about this field.- */- readonly fallback?: string;++ /** Decoded author default; when a schema is present this value conforms to that public structure. */+ readonly fallback?: CanonicalValue;};export type SurfaceAttributeVocabulary = {diff --cc packages/reference-video-tools/src/authoring.tsindex 00000000,0dc55964..584a6315mode 000000,100644..100644--- a/packages/reference-video-tools/src/authoring.ts+++ b/packages/reference-video-tools/src/authoring.ts@@@ -1,0 -1,1368 +1,1371 @@@+ import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";+ import { existsSync } from "node:fs";+ import { spawnSync } from "node:child_process";++ import { writePlaceholder } from "./placeholder.js";+ import { createHash } from "node:crypto";+ import { createRequire } from "node:module";+ import { cpus } from "node:os";+ import { basename, dirname, join, resolve } from "node:path";+ import { fileURLToPath } from "node:url";++ import { compileHyperframesDocument, materializeHyperframesHtml } from "@hypit/hyperframes";+ import {+ countSpeechEstimateUnits,+ estimateSpeechDuration,+ resolveSpeechEstimateLanguage,+ speechEstimatePolicyFromRecipe,+ } from "@hypit/estimate";+ import type { SpeechEstimatePolicy } from "@hypit/estimate";+ import type { SynchronizedMedia } from "@hypit/media";+ import type { ProgramSpace } from "@hypit/program-space";+ import type { BlobRef, Digest } from "@hypit/protocol";+ import { parseScript } from "@hypit/script";+ import type { SemanticTake, SemanticTakeToken } from "@hypit/speech";+ import { videoCliDistribution } from "@hypit/video-cli";-import { loadStudioAdapterRegistry } from "@hypit/studio/src/adapter-profile.js";++import { loadStudioCompanionRegistry } from "@hypit/studio/src/companion-profile.js";+ import { openStudioArchive } from "@hypit/studio/src/archive.js";+ import { loadStudioDomain } from "@hypit/studio/src/domain.js";+ import type { Preview } from "@hypit/studio/src/programme.js";+ import { preview } from "@hypit/studio/src/programme.js";+ import { loadStudioRun } from "@hypit/studio/src/run.js";+ import { inspectStudioRun } from "@hypit/studio/src/studio-preflight.js";+ import type { SvsRecipe } from "@hypit/svs";++ import { assert, round } from "./media.js";+ import type { TranscriptFile } from "./types.js";++ /** A frame range of the stand-in program, half-open in the Script's own order. */+ export type AuthoringWindow = {+ readonly startFrame: number;+ readonly endFrameExclusive: number;+ };++ /**+ * A stand-in Take. Its `media.audio` carries the sample count beside the Artifact, which is the+ * shape the `<value>` fixture is written with.+ */+ export type StandInTakeValue = Omit<SemanticTake, "media"> & {+ readonly media: Omit<SynchronizedMedia, "audio"> & {+ readonly audio: { readonly artifact: BlobRef; readonly sampleFrames: number };+ };+ };++ export type StandInTake = {+ readonly segmentId: string;+ readonly startFrame: number;+ readonly take: StandInTakeValue;+ };++ /**+ * What timed one Segment's stand-in, and how long that clock said it runs.+ *+ * `seconds` is the clock's own answer. `frames` is what the Segment occupies in the program, which is+ * shorter for a Segment outside the window being drawn.+ */+ export type StandInTiming = {+ readonly segment: string;+ readonly basis: "reference" | "estimate";+ readonly seconds: number;+ readonly frames: number;+ readonly tokens: number;+ /** Script words the reference's transcript matched. Zero on the estimate basis. */+ readonly matched: number;+ };++ export type StandInTakes = {+ readonly takes: readonly StandInTake[];+ readonly selections: ReadonlyMap<string, AuthoringWindow>;+ readonly frameCount: number;+ readonly timing: readonly StandInTiming[];+ /**+ * Where every Script word sits in the program, in order.+ *+ * A window named by a Segment or a Selection is looked up above; one named by index is read+ * straight off this, which is the same table those two are built from.+ */+ readonly frameOfToken: readonly { readonly frame: number; readonly end: number }[];+ };++ /** Which Segment the render is looking at, named directly or through a Selection's words. */+ export type StandInFocus = {+ readonly segment?: string;+ readonly selection?: string;+ /**+ * A half-open range of the Script's own speech tokens.+ *+ * The finest thing worth looking at is not always a thing the Script named. A caption Cue is a run+ * of words ended by a speaker change or an authored break, and the planner picks it out by index —+ * so the index is what both sides take. `segment` and `selection` remain as the convenient way to+ * write down a range that does have a name.+ */+ readonly tokens?: readonly [number, number];+ };++ /**+ * The Hypit tree this package is installed into.+ *+ * Studio's domain and the HyperFrames runtime are both found from it, and neither can be found from+ * the working directory: a command run from a project directory would resolve no packages, and one+ * that assumed the root would work there and crash anywhere else. Walking up from this module reaches+ * the tree from wherever the package was installed.+ *+ * What identifies it is holding the packages this module imports. A name in `package.json` does not:+ * a checkout and an installed Distribution carry different ones, so a check against either name+ * refuses the other, and the refusal reads as "this is not a Hypit checkout" while standing inside+ * one.+ */+ const NEEDED = ["studio", "hyperframes", "script", "estimate"] as const;++ function isHypitTree(directory: string): boolean {+ return NEEDED.every((name) => existsSync(join(directory, "packages", name, "package.json")));+ }++ function nearestTree(start: string): string | undefined {+ let directory = resolve(start);+ while (true) {+ if (isHypitTree(directory)) return directory;+ const parent = dirname(directory);+ if (parent === directory) return undefined;+ directory = parent;+ }+ }++ function repositoryRoot(): string {+ // An explicit override is taken as given. Re-deriving it would refuse a layout the caller can see+ // and this cannot, which leaves no way out of a wrong guess.+ const override = process.env.HYPIT_REPOSITORY?.trim();+ if (override !== undefined && override.length > 0) {+ const directory = resolve(override);+ assert(existsSync(directory), `HYPIT_REPOSITORY names no directory: ${directory}`);+ return directory;+ }+ const found = nearestTree(dirname(fileURLToPath(import.meta.url))) ?? nearestTree(process.cwd());+ assert(found !== undefined,+ `no Hypit tree above ${dirname(fileURLToPath(import.meta.url))} or ${process.cwd()} — one holding packages/${NEEDED.join(", packages/")}. Set HYPIT_REPOSITORY to name it.`);+ return found;+ }++ /**+ * Where installed packages are resolved from, found the way `hypit check` finds it: the nearest+ * directory at or above the project that holds a `package.json`.+ *+ * A project's own `packages/local-*` are installed against the project, so a root taken from+ * anywhere else resolves none of them. This is the same walk `packages/cli/src/main.ts` performs,+ * and the reason a project is given a `package.json` of its own — without one the walk passes+ * through it and lands on the tree.+ */+ export function nearestPackageRoot(start: string): string | undefined {+ let directory = resolve(start);+ while (true) {+ if (existsSync(join(directory, "package.json"))) return directory;+ const parent = dirname(directory);+ if (parent === directory) return undefined;+ directory = parent;+ }+ }++ /** Where a relative path on the command line is measured from. */+ export function invokedFrom(): string {+ return process.cwd();+ }+-/** The Script body, which `parseScript` takes on its own. */-export function scriptBody(svml: string): { readonly text: string; readonly offset: number } {++/** The one active Script identity and body, which semantic stand-ins must preserve together. */++export function scriptBody(svml: string): { readonly id: string; readonly text: string; readonly offset: number } {+ const open = /<script\b[^>]*>/u.exec(svml);+ if (open === null) throw new Error("the Source declares no <script>");++ const id = /\bid="([^"]+)"/u.exec(open[0])?.[1];++ if (id === undefined || id.length === 0) throw new Error("the Source's <script> declares no id");+ const start = open.index + open[0].length;+ const end = svml.indexOf("</script>", start);+ if (end < 0) throw new Error("the Source's <script> is not closed");- return { text: svml.slice(start, end), offset: start };++ return { id, text: svml.slice(start, end), offset: start };+ }++ /**+ * What a Source calls each package it imports.+ *+ * These tools find elements by tag — `SemanticTake`, `Normalize`, `Canvas` — and a tag is written+ * behind whatever alias the Source chose in `<import as="…" from="…"/>`. The alias is the author's,+ * not the package's: two Sources importing one package under two names are the same Source as far as+ * anything downstream is concerned.+ *+ * Assuming the conventional alias is therefore a reading that is right until somebody writes+ * `as="speech-track"`, at which point the element is invisible and whatever depended on finding it+ * reports the Source as missing something it plainly has. So the alias is read from the Source, and+ * the conventional one is the fallback for a Source that imports without naming one.+ */+ export function aliasPattern(svml: string, specifier: string, conventional: string): string {+ const found = new Set<string>();+ for (const match of svml.matchAll(/<import\s+([^>]*?)\/?>/gu)) {+ const attributes = match[1] ?? "";+ // The scope's own `@` is part of the name, so only the last one separates it from the version.+ const from = /\bfrom="(.+)@\d+"/u.exec(attributes)?.[1];+ if (from !== specifier) continue;+ found.add(/\bas="([^"]+)"/u.exec(attributes)?.[1] ?? conventional);+ }+ if (found.size === 0) found.add(conventional);+ // Longest first, so `speech-track` is not matched as `speech` followed by a stray `-track`.+ return [...found].sort((left, right) => right.length - left.length)+ .map((alias) => alias.replace(/[.*+?^${}()|[\]\\-]/gu, "\\$&")).join("|");+ }++ /** Every Recipe body in every sheet the Source imports, keyed `alias.path`. */+ async function recipeSheets(svml: string, svmlPath: string): Promise<ReadonlyMap<string, SvsRecipe>> {+ const sheets = new Map<string, SvsRecipe>();+ for (const match of svml.matchAll(/<import\s+as="([^"]+)"\s+source="([^"]+\.svs)"/gu)) {+ const alias = match[1] ?? "";+ const source = match[2] ?? "";+ const text = await readFile(resolve(dirname(svmlPath), source), "utf8").catch(() => undefined);+ if (text === undefined) continue;+ for (const recipe of text.matchAll(/([A-Za-z0-9_.-]+)\s*\{([^}]*)\}/gu)) {+ const name = recipe[1] ?? "";+ const body = recipe[2] ?? "";+ const properties: Record<string, string | number> = {};+ for (const property of body.matchAll(/([a-z][a-z0-9-]*)\s*:\s*([^;]+);/gu)) {+ const key = property[1] ?? "";+ const value = (property[2] ?? "").trim();+ properties[key] = /^-?\d+(\.\d+)?$/u.test(value) ? Number(value) : value;+ }+ sheets.set(`${alias}.${name}`, { path: `${alias}.${name}`, properties });+ }+ }+ return sheets;+ }++ /**+ * The policy each Segment's duration was estimated with. A Source names it once per Segment through+ * `<estimate:Speech source={story.segment.NAME.speech} policy={recipes.X}/>`, and reading it back is+ * what keeps this on the Source's own basis rather than a second one.+ */+ function policiesBySegment(svml: string, sheets: ReadonlyMap<string, SvsRecipe>): {+ readonly policies: ReadonlyMap<string, SpeechEstimatePolicy>;+ readonly shared: SpeechEstimatePolicy | undefined;+ readonly policyCount: number;+ } {+ const policies = new Map<string, SpeechEstimatePolicy>();+ const named = new Set<string>();+ const estimate = aliasPattern(svml, "@hypit/estimate", "estimate");+ for (const match of svml.matchAll(new RegExp(`<(?:${estimate}):Speech\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const segment = /\bsource=\{story\.segment\.([A-Za-z0-9_-]+)\.speech\}/u.exec(attributes)?.[1];+ const recipe = /\bpolicy=\{([A-Za-z0-9_.-]+)\}/u.exec(attributes)?.[1];+ if (segment === undefined || recipe === undefined) continue;+ const sheet = sheets.get(recipe);+ if (sheet === undefined) throw new Error(`policy Recipe ${recipe} is not in any imported sheet`);+ named.add(recipe);+ policies.set(segment, speechEstimatePolicyFromRecipe(sheet));+ }+ // A Segment whose take is shared with another Segment carries no estimate of its own, so it has no+ // policy named against it. One policy across the Source settles those; several leaves no basis to+ // pick from, and guessing would put a Segment on a pace the Source never chose for it.+ const shared = named.size === 1 ? policies.get([...policies.keys()][0]!) : undefined;+ return { policies, shared, policyCount: named.size };+ }++ const SILENT_AUDIO: BlobRef = { kind: "blob", digest: `sha256:${"0".repeat(64)}` as Digest, size: 1, mediaType: "audio/wav" };++ /**+ * Build a stand-in SemanticTake for every Segment a Source declares.+ *+ * A Track timed against speech cannot be projected before the speech exists, and on this route it+ * does not exist: the Build has not run. Two clocks can stand in for it, and each Segment is sized by+ * whichever one can speak for it.+ *+ * **The reference's own words.** For a reconstruction, the words have already been spoken once and+ * timed: the Script was transcribed from the reference video, and `prepare_reference` wrote the+ * seconds of every word of it. A Segment timed this way runs for exactly as long as the reference+ * spends on those words, and every window inside it does too, which is what a progressive reveal, a+ * typewriter, a staggered row or an enter animation is compared on.+ *+ * **`estimate:Speech` with a policy Recipe.** The estimator the Source already trusts to size its own+ * generations. Running it here produces the same numbers the Source used to order its takes, so it+ * introduces no third clock; it reads one already written down. This is what sizes a Segment the+ * reference has nothing to say about, and what sizes every Segment when no reference is given.+ *+ * Word ranges and Recipe values are exact on either clock, so which elements are on screen together,+ * where each sits, at what size and colour follow from the Source itself. Alignment against the+ * speech a Build synthesizes is settled once that speech exists.+ *+ * @param svmlPath the Author SVML this Source is written in+ * @param frameRate the Program's frame rate, as a whole number of frames per second+ * @param focus which Segment the render is looking at+ * @param reference the reference's per-word times, from `referenceWords`+ * @returns one `{ segmentId, take }` per Segment in Script order, and what timed each of them+ */++ /**+ * The Author SVML a Run declares, both as it is written and as a path.+ *+ * Studio's unit of work is the Run, so everything on this route is handed one and reads the Source+ * back out of it. `declared` is what the Run wrote, which a derived Run has to repoint.+ */+ export async function authorSource(runPath: string): Promise<{ readonly path: string; readonly declared: string }> {+ const runSource = await readFile(runPath, "utf8").catch(() => undefined);+ assert(runSource !== undefined, `cannot read ${runPath}`);+ const declared = /<author\s+source="([^"]+)"/u.exec(runSource)?.[1];+ assert(declared !== undefined, `${runPath} declares no <author source="…"/>`);+ return { path: resolve(dirname(runPath), declared), declared };+ }++ /** One word of a reference's transcript, at the seconds the reference speaks it. */+ export type ReferenceWord = {+ readonly text: string;+ readonly startSeconds: number;+ readonly endSeconds: number;+ };++ /** Where `prepare_reference` writes a reference's per-word times. */+ export function referenceRoot(): string {+ return join(repositoryRoot(), ".hypit", "reference-video-tools");+ }++ /**+ * The per-word times a prepared reference was transcribed to, in the order it speaks them.+ *+ * Words the aligner left untimed are dropped: a word with no seconds against it cannot anchor+ * anything, and carrying it would shift every index after it away from the clock.+ */+ export async function referenceWords(reference: string): Promise<readonly ReferenceWord[]> {+ const path = join(referenceRoot(), reference, "transcript.json");+ const text = await readFile(path, "utf8").catch(() => undefined);+ assert(text !== undefined, `reference ${reference} has no transcript at ${path}; run prepare_reference first`);+ const file = JSON.parse(text) as TranscriptFile;+ const words = file.passages.flatMap((passage) => passage.words).flatMap((word) =>+ word.start_seconds === undefined || word.end_seconds === undefined+ ? []+ : [{ text: word.text, startSeconds: word.start_seconds, endSeconds: word.end_seconds }]);+ assert(words.length > 0, `reference ${reference} has a transcript with no timed words`);+ return words;+ }++ /** Lowercase letters and digits only, so `AI,` and `ai` are the same word and `11 labs` is two. */+ function normalizeWord(text: string): string {+ return text.toLowerCase().replace(/[^a-z0-9]+/gu, "");+ }++ type MatchingBlock = { readonly left: number; readonly right: number; readonly size: number };++ /**+ * The longest run of words that appears in both sequences, within the given ranges.+ *+ * `lengths` carries, for each position in the right sequence, how long a run ends there against the+ * word just read from the left. Reading one left word at a time turns the whole search into two+ * passes rather than a comparison of every pair.+ */+ function longestRun(+ left: readonly string[], right: readonly string[],+ leftFrom: number, leftTo: number, rightFrom: number, rightTo: number,+ positions: ReadonlyMap<string, readonly number[]>,+ ): MatchingBlock {+ let bestLeft = leftFrom;+ let bestRight = rightFrom;+ let bestSize = 0;+ let lengths = new Map<number, number>();+ for (let index = leftFrom; index < leftTo; index += 1) {+ const next = new Map<number, number>();+ for (const at of positions.get(left[index]!) ?? []) {+ if (at < rightFrom) continue;+ if (at >= rightTo) break;+ const run = (lengths.get(at - 1) ?? 0) + 1;+ next.set(at, run);+ if (run > bestSize) {+ bestSize = run;+ bestLeft = index - run + 1;+ bestRight = at - run + 1;+ }+ }+ lengths = next;+ }+ return { left: bestLeft, right: bestRight, size: bestSize };+ }++ /**+ * Which Script word is which transcript word, as runs that appear in both in the same order.+ *+ * The two sequences say the same thing and are not the same list. A transcriber writes `11 labs`+ * where the Script writes `elevenlabs`, splits a word in two, or hears one that is not there, and a+ * single insertion is enough to put a positional pairing a word out for the whole rest of the+ * reference — on this project it drops the pairing from 96% of words to 41%. So the two are aligned:+ * the longest run common to both is taken as fixed, and the stretches on either side of it are+ * aligned the same way, down to the words that do not appear on both sides. Anchoring on runs rather+ * than on single words is what keeps a common word like `the` from pairing with a `the` elsewhere in+ * the reference.+ */+ function alignWords(script: readonly string[], reference: readonly string[]): ReadonlyMap<number, number> {+ const positions = new Map<string, number[]>();+ for (const [index, word] of reference.entries()) {+ const seen = positions.get(word);+ if (seen === undefined) positions.set(word, [index]);+ else seen.push(index);+ }+ const pairs = new Map<number, number>();+ const pending: (readonly [number, number, number, number])[] = [[0, script.length, 0, reference.length]];+ while (pending.length > 0) {+ const [leftFrom, leftTo, rightFrom, rightTo] = pending.pop()!;+ const block = longestRun(script, reference, leftFrom, leftTo, rightFrom, rightTo, positions);+ if (block.size === 0) continue;+ for (let step = 0; step < block.size; step += 1) pairs.set(block.left + step, block.right + step);+ if (leftFrom < block.left && rightFrom < block.right) pending.push([leftFrom, block.left, rightFrom, block.right]);+ const leftEnd = block.left + block.size;+ const rightEnd = block.right + block.size;+ if (leftEnd < leftTo && rightEnd < rightTo) pending.push([leftEnd, leftTo, rightEnd, rightTo]);+ }+ return pairs;+ }++ type WordSpan = { readonly start: number; readonly end: number };++ /**+ * A time for every Script word, from the ones that matched.+ *+ * A matched word takes the seconds the reference speaks it at. A run of unmatched words is spread+ * evenly across the stretch between the matched words on either side of it — the reference was+ * saying something there, and what it was saying is the run. A run at either end of the Script has a+ * matched word on one side only, so it takes the reference words immediately outside that one, at a+ * word apiece.+ */+ function wordSpans(count: number, pairs: ReadonlyMap<number, number>, reference: readonly ReferenceWord[]): readonly WordSpan[] {+ const anchors = [...pairs.keys()].sort((left, right) => left - right);+ const spans: WordSpan[] = new Array(count) as WordSpan[];+ for (const index of anchors) {+ const word = reference[pairs.get(index)!]!;+ spans[index] = { start: word.startSeconds, end: word.endSeconds };+ }+ for (let position = 0; position <= anchors.length; position += 1) {+ const before = position === 0 ? undefined : anchors[position - 1]!;+ const after = position === anchors.length ? undefined : anchors[position]!;+ const from = before === undefined ? 0 : before + 1;+ const to = after === undefined ? count : after;+ if (from >= to) continue;+ const run = to - from;+ let start: number;+ let end: number;+ if (before !== undefined && after !== undefined) {+ start = reference[pairs.get(before)!]!.endSeconds;+ end = reference[pairs.get(after)!]!.startSeconds;+ } else if (after !== undefined) {+ const at = pairs.get(after)!;+ start = reference[Math.max(0, at - run)]!.startSeconds;+ end = reference[at]!.startSeconds;+ } else {+ const at = pairs.get(before!)!;+ start = reference[at]!.endSeconds;+ end = reference[Math.min(reference.length - 1, at + run)]!.endSeconds;+ }+ const step = (end - start) / run;+ for (let offset = 0; offset < run; offset += 1) {+ spans[from + offset] = { start: start + step * offset, end: start + step * (offset + 1) };+ }+ }+ return spans;+ }++ /**+ * The stretch of a reference that speaks one Segment's or one Selection's words.+ *+ * A render covers a word range; a shot is a cut in the picture. The two are unrelated stretches of+ * the same video, and a Segment routinely runs across five of them. So a comparison against the+ * reference finds its stretch the way every other window on this route is found — the Script's own+ * tokens, aligned against the transcript — and reads the seconds off the words it lands on.+ *+ * `first` and `last` carry the end words' own spans, which is what an end can be moved inside of+ * without the range gaining or losing a whole word.+ */+ export type SpokenRange = {+ readonly startSeconds: number;+ readonly endSeconds: number;+ readonly first: ReferenceWord;+ readonly last: ReferenceWord;+ readonly words: number;+ /** How many of those words the transcript carries. The rest take their seconds from `wordSpans`. */+ readonly matched: number;+ };++ export async function spokenRange(+ svmlPath: string,+ focus: StandInFocus,+ reference: readonly ReferenceWord[],+ ): Promise<SpokenRange> {+ const svml = await readFile(svmlPath, "utf8");+ const body = scriptBody(svml);+ const parsed = parseScript(svmlPath, body.text, body.offset);++ // Which Script words the range covers. A Selection is marked once, so its word range is the+ // tokens between the anchors its open and close markers name.+ //+ // A range given by index skips the lookup entirely: it is already the answer the other two forms+ // are resolved into, and it is the only form that can name a stretch the Script never marked.+ let from: number | undefined;+ let to: number | undefined;+ if (focus.tokens !== undefined) {+ [from, to] = focus.tokens;+ assert(from >= 0 && to > from && to <= parsed.tokens.length,+ `token range [${from}, ${to}) is outside the Script's ${parsed.tokens.length} words`);+ } else if (focus.selection !== undefined) {+ const selection = parsed.selections.find((item) => item.id === focus.selection);+ assert(selection !== undefined, `the Script marks no Selection ${focus.selection}`);+ from = selection.open.boundary.tokenIndex;+ to = selection.close.boundary.tokenIndex;+ } else {+ assert(focus.segment !== undefined, "name a Segment, a Selection or a token range to read a word range from");+ const segment = parsed.segments.find((item) => item.id === focus.segment);+ assert(segment !== undefined, `the Script has no Segment ${focus.segment}`);+ from = segment.tokenStart;+ to = segment.tokenEndExclusive;+ }+ const start = from ?? 0;+ const end = to ?? 0;+ assert(start < end, `${focus.selection ?? focus.segment} covers no words`);++ const pairs = alignWords(+ parsed.tokens.map((token) => normalizeWord(token.text)),+ reference.map((word) => normalizeWord(word.text)));+ let matched = 0;+ for (let index = start; index < end; index += 1) if (pairs.has(index)) matched += 1;+ // Without a matched word inside the range, its seconds are an interpolation between whatever the+ // reference was saying on either side of it, which is a stretch of the video nobody asked for.+ assert(matched > 0,+ `the reference's transcript carries none of the words of ${focus.selection ?? focus.segment}, so the seconds it spoke them at are unknown`);++ const spans = wordSpans(parsed.tokens.length, pairs, reference);++ // Where the range closes. A render gives each word the screen until the next one starts, so the+ // pause the reference leaves between two words belongs to the word before it and a Take covers its+ // Segment without holes — `standInTakes` says why. A Selection closing part-way through a Segment+ // is therefore drawn up to the next word's start, and cutting the reference at the last word's end+ // instead leaves the reference short of the render by that pause. The Segment's own last word has+ // no next word inside it and closes on its own end, which is the length the take was given.+ const holder = parsed.segments.find((item) => end - 1 >= item.tokenStart && end - 1 < item.tokenEndExclusive);+ const closesMidSegment = holder !== undefined && end < holder.tokenEndExclusive;+ const endSeconds = closesMidSegment ? spans[end]!.start : spans[end - 1]!.end;++ const word = (index: number, until = spans[index]!.end): ReferenceWord => ({+ text: parsed.tokens[index]!.text,+ startSeconds: spans[index]!.start,+ endSeconds: until,+ });+ return {+ startSeconds: spans[start]!.start,+ endSeconds,+ first: word(start),+ // The end word carries the same close, so moving the end onto a shot boundary inside it looks at+ // the seconds the render actually drew rather than a shorter word.+ last: word(end - 1, endSeconds),+ words: end - start,+ matched,+ };+ }++ export async function standInTakes(+ svmlPath: string,+ frameRate: number,+ focus: StandInFocus = {},+ reference: readonly ReferenceWord[] = [],+ timingSource: string = svmlPath,+ ): Promise<StandInTakes> {+ const svml = await readFile(svmlPath, "utf8");+ const body = scriptBody(svml);+ const parsed = parseScript(svmlPath, body.text, body.offset);++ // Which Script the reference is aligned against. A render is drawn from a fragment holding one+ // Segment, and aligning that fragment's words against the whole transcript is not the same+ // alignment the whole Script produces: a word that matched inside a longer run of context stops+ // matching, and the unmatched runs at the fragment's own two ends are interpolated from the words+ // just outside them rather than from the neighbouring Segments. The comparison reads the whole+ // Source, so a render timed from the fragment covers seconds the comparison never cuts.+ //+ // So the alignment is made once, against the whole Source, and each Segment takes its own slice out+ // of it by id. The fragment is a byte-for-byte cut, so a Segment holds the same words in both.+ const timed = timingSource === svmlPath+ ? parsed+ : await (async () => {+ const text = await readFile(timingSource, "utf8");+ const whole = scriptBody(text);+ return parseScript(timingSource, whole.text, whole.offset);+ })();+ const sheets = await recipeSheets(svml, svmlPath);+ const { policies, shared, policyCount } = policiesBySegment(svml, sheets);++ // Which Script word the reference speaks when. The Script was transcribed from that video, so the+ // words are the same words in the same order, and a stand-in timed from them runs at the pace the+ // reconstruction is being compared against.+ const words = reference.length === 0+ ? undefined+ : (() => {+ const pairs = alignWords(timed.tokens.map((token) => normalizeWord(token.text)), reference.map((word) => normalizeWord(word.text)));+ return pairs.size === 0 ? undefined : { pairs, spans: wordSpans(timed.tokens.length, pairs, reference) };+ })();++ const takes: StandInTake[] = [];+ const timing: StandInTiming[] = [];+ // Global frame span of every word, in Script order, so a Selection can be turned into a frame+ // range without going near a clock. This is the correspondence the route uses everywhere else:+ // a stretch of the reference is found by its words, and its words are where the Script says.+ const frameOfToken: { readonly frame: number; readonly end: number }[] = [];+ let frameCursor = 0;+ for (const segment of parsed.segments) {+ const tokens = parsed.tokens.slice(segment.tokenStart, segment.tokenEndExclusive);+ const text = tokens.map((token) => token.text).join(" ");++ // A Segment is timed from the reference when the reference was heard saying some of its words.+ // The decision is made per Segment: an ordinary transcription difference costs one Segment its+ // reference clock and leaves the rest of the Script on it.+ const whole = timed.segments.find((item) => item.id === segment.id);+ let matched = 0;+ if (words !== undefined && whole !== undefined) {+ for (let index = whole.tokenStart; index < whole.tokenEndExclusive; index += 1) if (words.pairs.has(index)) matched += 1;+ }+ const spoken = words === undefined || whole === undefined || matched === 0+ ? undefined+ : words.spans.slice(whole.tokenStart, whole.tokenEndExclusive);++ // How long the Segment runs. The reference's own words when it was heard saying them, the+ // estimator the Source already trusts when it was not.+ let seconds: number;+ let basis: StandInTiming["basis"];+ let weights: readonly number[] | undefined;+ if (spoken !== undefined) {+ seconds = Math.max(0, spoken.at(-1)!.end - spoken[0]!.start);+ basis = "reference";+ } else {+ const policy = policies.get(segment.id) ?? shared;+ if (policy === undefined) {+ throw new Error(`Segment ${segment.id} names no estimate:Speech policy, and the Source uses ${policyCount} policies, so there is no single one to fall back to`);+ }+ seconds = estimateSpeechDuration({ value: text }, policy);+ basis = "estimate";+ const language = resolveSpeechEstimateLanguage(text, policy.language);+ weights = tokens.map((token) => Math.max(1, countSpeechEstimateUnits(token.text, language)));+ }++ // Every Segment at the length its clock gives it. The program is drawn once and a window is cut+ // out of it by frame, so a Segment nobody is looking at costs nothing by being its true length —+ // and the frame numbers then mean what they say instead of indexing a compressed timeline.+ const frameCount = Math.max(tokens.length, Math.round(seconds * frameRate));+ timing.push({ segment: segment.id, basis, seconds: round(seconds), frames: frameCount, tokens: tokens.length, matched });++ // Where each word ends. On the reference clock a word holds the screen until the next one starts+ // and the last holds until the reference stops saying it, so the small gaps the reference leaves+ // between words go to the word before them and the Take covers its Segment without holes. On the+ // estimate the share is the estimator's own unit count, so the word order and the relative widths+ // both come from the same place the duration did.+ const total = weights?.reduce((sum, weight) => sum + weight, 0) ?? 0;+ const edge = spoken !== undefined+ ? (index: number, start: number): number =>+ Math.max(start + 1, Math.round((spoken[index + 1]!.start - spoken[0]!.start) * frameRate))+ : (index: number, start: number): number =>+ start + Math.max(1, Math.round(frameCount * weights![index]! / total));++ const anchors: { readonly identity: string; readonly frame: number }[] = [+ { identity: `segment:${segment.id}:start`, frame: 0 },+ { identity: `segment:${segment.id}:end`, frame: frameCount },+ ];+ const placed: SemanticTakeToken[] = [];+ let used = 0;+ for (const [index, token] of tokens.entries()) {+ const start = used;+ // The last token closes the Segment exactly, so rounding never leaves a frame unclaimed, and+ // every earlier one is held back far enough that the ones after it still get a frame each.+ used = index === tokens.length - 1+ ? frameCount+ : Math.min(frameCount - (tokens.length - 1 - index), edge(index, start));+ const id = `segment:${segment.id}:token:${index + 1}`;+ placed.push({+ tokenId: id, segmentId: segment.id, text: token.text,+ startAnchorId: `${id}:start`, endAnchorId: `${id}:end`,+ startFrame: start, endFrameExclusive: used,+ });+ anchors.push({ identity: `${id}:start`, frame: start }, { identity: `${id}:end`, frame: used });+ }++ frameOfToken.push(...placed.map((token) => ({ frame: frameCursor + token.startFrame, end: frameCursor + token.endFrameExclusive })));+ takes.push({+ segmentId: segment.id,+ startFrame: frameCursor,+ take: {++ narrativeId: body.id,+ media: {+ timeline: { frameRate: { numerator: frameRate, denominator: 1 }, frameCount },+ audio: { artifact: SILENT_AUDIO, sampleFrames: Math.round(frameCount / frameRate * 48_000) },+ },+ segment: {+ segmentId: segment.id,+ startAnchorId: `segment:${segment.id}:start`,+ endAnchorId: `segment:${segment.id}:end`,+ startFrame: 0,+ endFrameExclusive: frameCount,+ },+ tokens: placed,+ anchors,+ },+ });+ frameCursor += frameCount;+ }++ // Every Selection the Script marks, as the frames its words occupy. Selections nest freely, so a+ // window runs from the frame of its open anchor's word to the end of the word before its close.+ const selections = new Map<string, AuthoringWindow>();+ for (const selection of parsed.selections) {+ const first = frameOfToken[selection.open.boundary.tokenIndex];+ const last = frameOfToken[selection.close.boundary.tokenIndex - 1];+ if (first === undefined || last === undefined) continue;+ if (first.frame < last.end) selections.set(selection.id, { startFrame: first.frame, endFrameExclusive: last.end });+ }+ return { takes, selections, frameCount: frameCursor, timing, frameOfToken };+ }++ function blobRef(bytes: Uint8Array, mediaType: string): BlobRef {+ return { kind: "blob", digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`, size: bytes.byteLength, mediaType };+ }++ /** 48 kHz mono PCM silence, written by hand so the mock needs no encoder and lands on exact bytes. */+ function silentWav(sampleFrames: number): Buffer {+ const data = Math.max(2, sampleFrames * 2);+ const buffer = Buffer.alloc(44 + data);+ buffer.write("RIFF", 0);+ buffer.writeUInt32LE(36 + data, 4);+ buffer.write("WAVEfmt ", 8);+ buffer.writeUInt32LE(16, 16);+ buffer.writeUInt16LE(1, 20);+ buffer.writeUInt16LE(1, 22);+ buffer.writeUInt32LE(48_000, 24);+ buffer.writeUInt32LE(48_000 * 2, 28);+ buffer.writeUInt16LE(2, 32);+ buffer.writeUInt16LE(16, 34);+ buffer.write("data", 36);+ buffer.writeUInt32LE(data, 40);+ return buffer;+ }++ /**+ * One browser render per Run and clock, within this process.+ *+ * A round asks for several windows of one program, and each of them would otherwise draw the whole+ * program again to throw most of it away. Keyed by the same hash the working directory is, so two+ * entries that share a directory share the render that fills it. Between processes this holds+ * nothing, which is correct: a new process is the one case where the Source may have changed.+ */+ const programRenders = new Map<string, Promise<void>>();+ async function drawProgramOnce(key: string, draw: () => Promise<void>): Promise<void> {+ const running = programRenders.get(key);+ if (running !== undefined) return await running;+ const started = draw();+ programRenders.set(key, started);+ try { await started; } catch (error) { programRenders.delete(key); throw error; }+ }++ /**+ * How big a mock for one declared generation should be.+ *+ * The shape matters and the pixel count does not. A mock is a flat fill, so nothing reads its+ * resolution — but a `fit: cover` crops a 4:5 source into a 9:16 Frame differently from a 9:16 one,+ * and a mock of the wrong shape makes the reader report a framing difference the real render will+ * not have, or miss one it will.+ *+ * The generation declares its own `aspect-ratio`, so that is what is read. Where it says `adaptive`+ * — seedance's "inherit from the input" — the shape comes from whatever it was handed, so the edge+ * is followed one hop to the upstream generation. Beyond one hop the returns fall away and a+ * malformed or circular graph starts to matter, so the Canvas is the answer from there.+ *+ * `resolution` is deliberately not read. It is a vendor token (`720p` naming a short side, `4K` a+ * long one) with no pixel mapping anywhere in this repository, and it decides only how large a+ * rectangle of flat colour would be.+ */+ function mockExtent(svml: string, id: string, canvas: { readonly width: number; readonly height: number }): {+ readonly width: number;+ readonly height: number;+ } {+ const declaring = (target: string): string | undefined =>+ new RegExp(`<[a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*\\b[^>]*?\\bid="${target}"[^>]*?/?>`, "su").exec(svml)?.[0];++ const ratioOf = (target: string): string | undefined => {+ const tag = declaring(target);+ if (tag === undefined) return undefined;+ const declared = /\baspect-ratio="([^"]+)"/u.exec(tag)?.[1];+ if (declared !== undefined && declared !== "adaptive") return declared;+ // One hop upstream. Two shapes need it: `adaptive`, which takes the shape of whatever it was+ // handed, and a `pipeline:Normalize`, which is what a mock is actually keyed by — the Source+ // names the normalized media, and the generation that declared the shape is behind its `source`.+ const upstream = /\b(?:source|image|first-frame|reference-image)=\{([A-Za-z0-9_-]+)[.}]/u.exec(tag)?.[1];+ if (upstream === undefined) return undefined;+ const inherited = /\baspect-ratio="([^"]+)"/u.exec(declaring(upstream) ?? "")?.[1];+ return inherited === "adaptive" ? undefined : inherited;+ };++ const ratio = ratioOf(id);+ const parts = /^(\d+):(\d+)$/u.exec(ratio ?? "");+ if (parts === null) return { width: canvas.width, height: canvas.height };+ const wide = Number(parts[1]);+ const tall = Number(parts[2]);+ if (!(wide > 0 && tall > 0)) return { width: canvas.width, height: canvas.height };+ // Scaled off the Canvas's short side, so a mock is never larger than the picture it sits in.+ const short = Math.min(canvas.width, canvas.height);+ return wide >= tall+ ? { width: Math.round(short * wide / tall), height: short }+ : { width: short, height: Math.round(short * tall / wide) };+ }++ export type RenderElementInput = {+ /**+ * A round of renders, run together. Each entry names its own element, stretch and output and+ * inherits `run` and `reference_id`. The route renders every element before it compares any, and+ * each render is now written under its own directory, so a round has nothing to serialise for.+ */+ readonly renders?: readonly RenderElementInput[];+ /** Required for one render; a round carries them per entry and inherits `run` from the outer input. */+ readonly run?: string;+ readonly element?: string;+ readonly out?: string;+ readonly segment?: string;+ readonly selection?: string;+ /** A half-open token range, for a stretch the Script never named. See `StandInFocus`. */+ readonly tokens?: readonly [number, number];+ /**+ * A prepared reference to time the stand-in from. Its transcript holds the seconds each word was+ * spoken at, and the Script was transcribed from that video, so the stand-in runs at the pace the+ * render is compared against. Without one the Source's own `estimate:Speech` sizes each Segment.+ */+ readonly reference_id?: string;+ };++ /** What timed the stand-in behind one render, per Segment. */+ export type StandInTimingReport = {+ readonly reference_id: string | null;+ /** `mixed` when some Segments were timed from the reference and others fell back to the estimate. */+ readonly basis: "reference" | "estimate" | "mixed";+ readonly segments: readonly StandInTiming[];+ };++ /**+ * The record `render_element` leaves beside its output.+ *+ * A comparison is made from a file, and the file alone says nothing about what timed the picture in+ * it. Writing that beside the output means `compare_reconstruction` can copy it into the comparison+ * log from the path it was handed, and the gate can report which comparisons were made at the+ * reference's pace without re-deriving anything.+ */+ export type StandInSidecar = {+ readonly element: string;+ readonly window: AuthoringWindow;+ readonly timing: StandInTimingReport;+ };++ /** Where `render_element` writes the record of what timed a render. */+ export function standInSidecarPath(outPath: string): string {+ return `${outPath}.stand-in.json`;+ }++ function timingReport(reference: string | undefined, segments: readonly StandInTiming[]): StandInTimingReport {+ const bases = new Set(segments.map((item) => item.basis));+ return {+ reference_id: reference ?? null,+ basis: bases.size > 1 ? "mixed" : segments.some((item) => item.basis === "reference") ? "reference" : "estimate",+ segments,+ };+ }++ /**+ * Render one element of a Source the way that Source configures it, without a Build and without a+ * Provider.+ *+ * `comparison-round.md` compares a reconstructed element against the reference. What it must+ * compare is the element as this video places it — the Recipe values the Source passes, the Script+ * text it feeds, the windows it binds — because a Source can fill those with values that collide+ * while a package's catalogue preview, drawn from sample values, stays perfect. Producing that+ * picture by hand means transcribing values into a per-package harness, one line at a time, which is+ * how a caption system gets compared as a single line that has nothing to collide with.+ *+ * So this reads the values instead. Everything it needs is already written down:+ *+ * Canvas and Frames, Recipe values, bindings the Source+ * which elements share a window, in what order the Script's words, through their Selections+ * how long each Segment runs the reference's own words, or `estimate:Speech`+ * the layers a Build has not made `make_placeholder`, sized from the Canvas+ *+ * The one thing missing before a Build is real speech, and `standInTakes` supplies a Segment+ * skeleton for it. Given `reference_id` it reads the seconds out of that reference's transcript, so+ * every window is as long as the reference spends on the words inside it; without one it reads the+ * estimator the Source already trusts, the same numbers it ordered its takes with. Those takes enter+ * through `<value>` and `<satisfy>`, the mechanism `examples/all-components-preview` uses to open in+ * Studio without spending anything, so nothing here is a private back door into the graph.+ *+ * What this settles: which elements are on screen together, where each sits, at what size, weight and+ * colour, and — on a reference-timed stand-in — how long each of them has to arrive in. What it does+ * not: alignment against the speech a Build synthesizes, which is settled once that speech+ * exists. `timing` in the result, and the sidecar written+ * beside the output, name which of the two clocks sized each Segment.+ */+ export async function renderElement(input: RenderElementInput): Promise<Record<string, unknown>> {+ // A round carries these per entry; one render has to name all three itself.+ assert(input.run !== undefined, "run is required");+ assert(input.element !== undefined, "element is required");+ assert(input.out !== undefined, "out is required");+ const element = input.element;+ const out = input.out;+ const run = input.run;+ const cwd = invokedFrom();+ const runPath = resolve(cwd, run);+ const projectRoot = dirname(runPath);+ // Where installed packages are found, which is not where the Hypit tree is. A project carries its+ // own `packages/local-*`, so the search starts at the project and walks up the way the CLI's does —+ // resolving against the tree instead would miss every package the project installed for itself.+ const packageRoot = nearestPackageRoot(projectRoot) ?? repositoryRoot();+ const outPath = resolve(cwd, out);++ const runSource = await readFile(runPath, "utf8").catch(() => undefined);+ assert(runSource !== undefined, `cannot read ${runPath}`);+ const author = /<author\s+source="([^"]+)"/u.exec(runSource)?.[1];+ assert(author !== undefined, `${run} declares no <author source="…"/>`);+ const svmlPath = resolve(projectRoot, author);+ let svml = await readFile(svmlPath, "utf8").catch(() => undefined);+ assert(svml !== undefined, `cannot read ${svmlPath}`);++ // The Program's frame rate and the Canvas the render composes at, both read rather than assumed. A+ // harness that hard-codes either produces a picture at a geometry the reference never had.+ const clock = /<[a-z-]*:?Clock\b[^>]*?\bframe-rate="(\d+)"/su.exec(svml)?.[1]+ ?? /<time:Clock\b[^>]*?\bfps="(\d+)"/su.exec(svml)?.[1];+ const frameRate = Number(clock ?? 30);+ const space = aliasPattern(svml, "@hypit/spatial", "space");+ const canvasMatch = new RegExp(`<(?:${space}):Canvas\\b[^>]*?\\bwidth="(\\d+)"[^>]*?\\bheight="(\\d+)"`, "su").exec(svml);+ assert(canvasMatch !== null, `the Source declares no <${space.split("|")[0]}:Canvas width= height=/>`);+ const canvas = { width: Number(canvasMatch[1]), height: Number(canvasMatch[2]) };++ // Which SemanticTake output belongs to which Segment, so each stand-in lands on the right one.+ const whisperx = aliasPattern(svml, "@hypit/whisperx", "whisperx");+ const takeOutputs = new Map<string, string>();+ for (const match of svml.matchAll(new RegExp(`<(?:${whisperx}):SemanticTake\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const id = /\bid="([^"]+)"/u.exec(attributes)?.[1];+ const segment = /\bsegment=\{story\.segment\.([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1];+ if (id !== undefined && segment !== undefined) takeOutputs.set(segment, id);+ }+ assert(takeOutputs.size > 0, `the Source declares no ${whisperx.split("|")[0]}:SemanticTake to stand in for`);++ // What the Run already brings. A project Run declares nothing and everything is mocked; a package's+ // preview Run ships its own sample pictures, and those are carried across untouched so the catalogue+ // picture shows the component holding something rather than a placeholder.+ const alreadySatisfied = new Set([...runSource.matchAll(/<satisfy\s+output="([^"]+)"/gu)].map((match) => match[1] ?? ""));+ const carried = [...runSource.matchAll(/^[ \t]*<(?:file|value|satisfy)\b[^>]*\/>[ \t]*$/gmu)].map((match) => (match[0] ?? "").trim());++ // The window is resolved before the stand-ins are built, so the program is only as long as the+ // stretch being looked at. Rendering the whole program to crop six seconds out of it is the+ // difference between a few seconds and a few minutes.+ const segmentArgument = input.segment;+ const selectionArgument = input.selection;+ const tokensArgument = input.tokens;+ const focus = {+ ...(segmentArgument === undefined ? {} : { segment: segmentArgument }),+ ...(selectionArgument === undefined ? {} : { selection: selectionArgument }),+ };++ // The derived Run is written here, and so is the cut, so the directory comes first.+ // One directory per render, named for what this render is. Every call used to write one shared+ // `.hypit/compare` and empty it on the way in, so two renders could not run at once — the second+ // deleted the first one's sliced Source and mocks out from under it. The route asks for every+ // element to be rendered before any is compared, which is a set of renders with nothing to say to+ // each other, and they can now run together.+ //+ // The key is the Run and the clock, and deliberately not the element or the window: the picture+ // does not depend on either. `render_element` draws the whole program and the window is cut out of+ // the frames afterwards, so every render of one Run under one clock wants the identical directory,+ // the identical mocks and the identical frames.+ const renderKey = createHash("sha256")+ .update(`${resolve(runPath)}\u0000${input.reference_id ?? ""}`)+ .digest("hex").slice(0, 12);+ const compareRoot = join(projectRoot, ".hypit", "compare", renderKey);+ // Made, not remade. The frames inside are reused by every window cut out of this program, and the+ // mocks beside them are written from ids that do not move, so emptying it would only throw away the+ // render the next entry of the round is about to ask for.+ await mkdir(compareRoot, { recursive: true });++ const sourcePath = svmlPath;++ // The reference's per-word times, when one was named. Read after the cut so a transcript that is+ // missing is reported before a minute of rendering rather than after it.+ const reference = input.reference_id?.trim();+ const spoken = reference === undefined || reference.length === 0 ? [] : await referenceWords(reference);++ const { takes, selections, frameCount: programFrames, timing, frameOfToken } = await standInTakes(sourcePath, frameRate, focus, spoken, svmlPath);+ const framesBySegment = new Map(takes.map((item) => [item.segmentId, item.take.segment.endFrameExclusive]));+ // A Selection's window in frames, summed over the stand-in tokens it covers. This is the same word+ // span the Source binds to, carried into frames by the same clock that sized the Segment.+ const framesBySelection = new Map<string, number>();+ for (const { segmentId, take } of takes) {+ for (const token of take.tokens) framesBySelection.set(token.tokenId, token.endFrameExclusive - token.startFrame);+ framesBySelection.set(`segment:${segmentId}`, take.segment.endFrameExclusive);+ }++ /**+ * Every media a Build would have produced, and how long its window is. A speech take carries no+ * picture and a base take fills a Segment; a cutaway fills whatever its `during=` binds. Each becomes+ * a placeholder of the Canvas's own size, so the composite has the geometry the Source declares.+ */+ const mockedMedia = (): ReadonlyMap<string, { readonly frames: number; readonly picture: boolean }> => {+ const windows = new Map<string, number>();+ for (const match of svml.matchAll(new RegExp(`<(?:${whisperx}):SemanticTake\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const media = /\bmedia=\{([A-Za-z0-9_-]+)\.media\}/u.exec(attributes)?.[1];+ const segment = /\bsegment=\{story\.segment\.([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1];+ if (media !== undefined && segment !== undefined) windows.set(media, framesBySegment.get(segment) ?? frameRate);+ }+ for (const match of svml.matchAll(/<[a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*\b([^>]*?)\/?>/gsu)) {+ const attributes = match[1] ?? "";+ const media = /\bmedia=\{([A-Za-z0-9_-]+)\.media\}/u.exec(attributes)?.[1];+ if (media === undefined || windows.has(media)) continue;+ const segment = /\bduring=\{story\.segment\.([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1];+ if (segment !== undefined) { windows.set(media, framesBySegment.get(segment) ?? frameRate); continue; }+ // A cutaway's window is the Selection it is bound to, which the stand-in already measured in+ // frames. A mock shorter than its window runs out inside it, and with `playback` at its default+ // the frames after that draw nothing — a gap the Source never wrote, appearing only in the+ // comparison, in exactly the shape of the defect the comparison is looking for.+ const selection = /\bduring=\{story\.selection\.([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1];+ const window = selection === undefined ? undefined : selections.get(selection);+ windows.set(media, window === undefined+ ? frameRate+ : window.endFrameExclusive - window.startFrame);+ }+ const carries = new Map<string, { readonly frames: number; readonly picture: boolean }>();+ const pipeline = aliasPattern(svml, "@hypit/media-pipeline", "pipeline");+ for (const match of svml.matchAll(new RegExp(`<(?:${pipeline}):Normalize\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const id = /\bid="([^"]+)"/u.exec(attributes)?.[1];+ const video = /\bvideo="([^"]+)"/u.exec(attributes)?.[1];+ if (id === undefined || !windows.has(id)) continue;+ // A Run that already satisfies this output brought its own material — a package's preview Source+ // supplies sample pictures this way — and a mock over the top would hide what it came to show.+ if (alreadySatisfied.has(`${id}.media`)) continue;+ carries.set(id, { frames: windows.get(id)!, picture: video !== "none" });+ }+ return carries;+ };++ // A derived Run lives beside the project so the original's relative sources still resolve, and under+ // `.hypit/` so it is never mistaken for something the author wrote. It is rewritten every run.+ const declarations: string[] = [];+ const satisfactions: string[] = [];+ for (const { segmentId, take } of takes) {+ const output = takeOutputs.get(segmentId);+ if (output === undefined) continue;+ // The take's own audio has to be servable, not a digest stub: Studio resolves every Artifact a+ // projection references, and a preview that cannot serve one stops there.+ const sampleFrames = Math.round(take.segment.endFrameExclusive / frameRate * 48_000);+ const silence = silentWav(sampleFrames);+ await writeFile(join(compareRoot, `${segmentId}-take.wav`), silence);+ const spoken = { ...take, media: { ...take.media, audio: { artifact: blobRef(silence, "audio/wav"), sampleFrames } } };+ const fixture = join(compareRoot, `${segmentId}.json`);+ await writeFile(fixture, `${JSON.stringify({ kind: "inline", value: spoken }, null, 2)}\n`, "utf8");+ declarations.push(` <file id="stand-in-${segmentId}-audio" type="@hypit/artifact@1#BlobArtifact" from="./${segmentId}-take.wav" media-type="audio/wav"/>`);+ declarations.push(` <value id="stand-in-${segmentId}" type="@hypit/speech@1#SemanticTake" from="./${segmentId}.json"/>`);+ satisfactions.push(` <satisfy output="${output}.take" candidate="stand-in-${segmentId}"/>`);+ }+ // The layers a Build has not made, as placeholders of the Canvas's own size. `make_placeholder` is+ // the route's one tool for this: deterministic, Provider-free, and the same mock the comparison is+ // told to bypass. A mock never enters the project's own Source — it is declared in the derived Run+ // and nowhere else.+ // Every picture mock at once. Each one is a solid fill, so they do not contend for anything but+ // ffmpeg, and drawn one after another they cost more than every frame they stand in for.+ const mocks = [...mockedMedia()];+ await Promise.all(mocks+ .filter(([, { picture }]) => picture)+ .map(async ([id, { frames }]) => await writePlaceholder({+ out: join(compareRoot, `${id}.mp4`), ...mockExtent(svml, id, canvas),+ video: true, seconds: Math.max(1, Math.ceil(frames / frameRate)), color: "mid",+ })));+ for (const [id, { frames, picture }] of mocks) {+ const file = join(compareRoot, `${id}.mp4`);+ // Every SynchronizedMedia carries audio, and it is validated as WAV, so the silence is written as+ // one rather than pointed at the video. Both are declared: the picture is what gets drawn, the+ // silence is what makes the value legal.+ const wavPath = join(compareRoot, `${id}.wav`);+ const wav = silentWav(Math.round(frames / frameRate * 48_000));+ await writeFile(wavPath, wav);+ const audioBlob = blobRef(wav, "audio/wav");+ declarations.push(` <file id="mock-${id}-audio" type="@hypit/artifact@1#BlobArtifact" from="./${id}.wav" media-type="audio/wav"/>`);+ let visual: SynchronizedMedia["visual"];+ if (picture) {+ const bytes = await readFile(file);+ visual = { artifact: blobRef(bytes, "video/mp4"), ...mockExtent(svml, id, canvas) };+ declarations.push(` <file id="mock-${id}" type="@hypit/artifact@1#BlobArtifact" from="./${id}.mp4" media-type="video/mp4"/>`);+ }+ const media: SynchronizedMedia = {+ timeline: { frameRate: { numerator: frameRate, denominator: 1 }, frameCount: frames },+ audio: { artifact: audioBlob },+ ...(visual === undefined ? {} : { visual }),+ };+ await writeFile(join(compareRoot, `${id}.media.json`), `${JSON.stringify({ kind: "inline", value: media }, null, 2)}\n`, "utf8");+ declarations.push(` <value id="media-${id}" type="@hypit/media@1#SynchronizedMedia" from="./${id}.media.json"/>`);+ satisfactions.push(` <satisfy output="${id}.media" candidate="media-${id}"/>`);+ }++ // Still images the Source declares as generations. Same treatment, same tool, at the Canvas's size:+ // a picture slot that is empty in the render is black, and black is not what will be there.+ const imageIds = [...new Set([...svml.matchAll(/\{([a-z0-9-]+)\.image\}/gu)].map((match) => match[1] ?? ""))]+ .filter((id) => !alreadySatisfied.has(`${id}.image`));+ await Promise.all(imageIds.map(async (id) => await writePlaceholder({+ out: join(compareRoot, `${id}.png`), ...mockExtent(svml, id, canvas), color: "mid",+ })));+ for (const id of imageIds) {+ declarations.push(` <file id="mock-${id}" type="@hypit/artifact@1#BlobArtifact" from="./${id}.png" media-type="image/png"/>`);+ satisfactions.push(` <satisfy output="${id}.image" candidate="mock-${id}"/>`);+ }++ const derivedRun = join(compareRoot, "compare.svrun");+ await writeFile(derivedRun, [+ `<?svml using="@hypit/run-markup@1"?>`,+ ``,+ `<svrun version="1">`,+ // The cut, when there was one: it sits beside this Run, and its own imports were repointed to+ // reach the project from here.+ // Three levels up: the derived Run sits at `.hypit/compare/<key>/`, and the Source it names is at+ // the project root. This branch used to run only when no window was asked for, which is the one+ // case nothing exercised, so it was short by one the whole time.+ ` <author source="../../../${author.replace(/^\.\//u, "")}"/>`,+ // Whatever the Run brought, repointed: the derived Run sits two directories deeper than the one+ // that declared these paths.+ ...carried.map((line) => ` ${line.replace(/from="\.\//gu, 'from="../../../')}`),+ // Targeting the element's own output rather than the Film prunes the closure to what this one+ // Track needs. Asking for the whole delivery would pull in every generation the Source declares+ // and report each as unresolved, which is true and useless: none of them is what is being looked at.+ ` <target output="final.video"/>`,+ ``,+ ...declarations,+ ``,+ ...satisfactions,+ `</svrun>`,+ ``,+ ].join("\n"), "utf8");++ const distributionPackageRoot = videoCliDistribution.packageRoot;+ if (distributionPackageRoot === undefined) throw new Error("active Hypit Distribution has no package root");+- const registry = await loadStudioAdapterRegistry({ workspaceRoot: projectRoot, packageRoot, distributionPackageRoot });++ const registry = await loadStudioCompanionRegistry({ workspaceRoot: projectRoot, packageRoot, distributionPackageRoot });+ const domain = await loadStudioDomain({ run: derivedRun, workspaceRoot: projectRoot, packageRoot });+ const archive = await openStudioArchive(undefined, packageRoot, projectRoot, distributionPackageRoot);+ let built: Preview;+ try {- const run = await loadStudioRun({ run: derivedRun, domain, ...(archive === undefined ? {} : { archive }) });++ const run = await loadStudioRun({ run: derivedRun, domain, registry, ...(archive === undefined ? {} : { archive }) });+ const inspection = inspectStudioRun(registry, run.source, run);+ // Every Track, not only the one being looked at: the element is compared where it sits, over the+ // mocked base rather than on its own, because text that is legible on black may not be on a picture.+ built = await preview({+ source: run.source,+ run,+ domain,+ outputRefs: [inspection.filmComposition, ...inspection.projections.map((item) => item.ref)],+ compositionRef: inspection.filmComposition,+ projections: inspection.projections,+ ...(archive === undefined ? {} : { archive }),+ });+ } catch (error) {+ const issues = (error as { readonly issues?: unknown } | null)?.issues;+ if (Array.isArray(issues)) {+ throw new Error(["the Source does not project yet.", ...issues.slice(0, 12).map((issue) => ` ${String(issue)}`)].join("\n"));+ }+ throw error instanceof Error ? error : new Error(String(error));+ }++ const placed = built.tracks.find((track) => String(track.outputRef ?? "").endsWith(`::output::${element}.track`)+ || String(track.outputRef ?? "").includes(`::output::${element}.`));+ if (placed === undefined) {+ // An output is named `<id>.<output>`, and --element takes the id on its own. Listing the outputs+ // would hand the reader a name that fails the same way the one they passed did, so the last part+ // is dropped and one element placed twice is named once.+ const ids = [...new Set(built.tracks.map((track) => {+ const output = String(track.outputRef ?? "").split("::output::")[1];+ return output === undefined ? track.name : output.replace(/\.[^.]*$/u, "");+ }))];+ throw new Error([+ `the Source places no element named ${element}. --element takes the bare id, and these are placed:`,+ ...ids.map((id) => ` ${id}`),+ ].join("\n"));+ }++ // The window to render, named in words. A shot of the reference is found by the words spoken over it+ // and those words are a Segment or a Selection here, so no reference timestamp is ever read across.+ let window: AuthoringWindow = { startFrame: 0, endFrameExclusive: programFrames };+ if (tokensArgument !== undefined) {+ // A range given by index is the general form: a Segment and a Selection are both resolved into+ // one, and a Cue is a range that has no other way to be named.+ const [from, to] = tokensArgument;+ assert(from >= 0 && to > from && to <= frameOfToken.length,+ `token range [${from}, ${to}) is outside the Script's ${frameOfToken.length} words`);+ window = { startFrame: frameOfToken[from]!.frame, endFrameExclusive: frameOfToken[to - 1]!.end };+ } else if (selectionArgument !== undefined) {+ const marked = selections.get(selectionArgument);+ assert(marked !== undefined, `the Script marks no Selection ${selectionArgument}`);+ window = marked;+ } else if (segmentArgument !== undefined) {+ let cursor = 0;+ const take = takes.find((item) => { const hit = item.segmentId === segmentArgument; if (!hit) cursor += item.take.segment.endFrameExclusive; return hit; });+ assert(take !== undefined, `the Script has no Segment ${segmentArgument}`);+ window = { startFrame: cursor, endFrameExclusive: cursor + take.take.segment.endFrameExclusive };+ }++ // Compile once, materialize with the artifact bytes written beside the document, and let the+ // HyperFrames runtime draw it. This is the path packages/hyperframes/test/browser-visual.test.ts+ // takes; nothing here is a private renderer.+ const document = compileHyperframesDocument(built.composition, built.space as ProgramSpace);+ const stage = join(compareRoot, "stage");+ await mkdir(stage, { recursive: true });+ const names = new Map<string, string>();+ for (const [digest, file] of built.served) {+ const name = `${digest.replace(/[^a-z0-9]/giu, "")}`;+ await writeFile(join(stage, name), file.bytes);+ names.set(digest, name);+ }+ await writeFile(join(stage, "index.html"), materializeHyperframesHtml(document, (artifact) => {+ const name = names.get(artifact.digest);+ assert(name !== undefined, `the projection references Artifact ${artifact.digest}, which was not served`);+ return `./${name}`;+ }), "utf8");++ const clip = /\.(mp4|mov|webm)$/iu.test(outPath);+ const frames = join(compareRoot, "frames");+ // Drawn once per Run and clock, however many windows are asked for.+ //+ // The picture does not depend on the element or the window — the whole program is drawn and the+ // window is cut out of these frames — so a round of eight looks over one Source is one browser+ // render and eight ffmpeg cuts. Rendering per entry would draw the same program eight times.+ await drawProgramOnce(renderKey, async () => {+ await rm(frames, { recursive: true, force: true });+ await mkdir(frames, { recursive: true });+ // The runtime ships with the tree, not with the project. Resolving it against the package root+ // finds nothing whenever those two differ, which is every project that installs packages of its own.+ const hyperframesCli = createRequire(join(repositoryRoot(), "packages/provider-hyperframes-local/package.json"))+ .resolve("hyperframes/bin/hyperframes.mjs");+ const drawn = spawnSync(process.execPath, [+ hyperframesCli, "render", stage,+ "--format", "png-sequence", "--output", frames, "--fps", String(frameRate),+ "--workers", String(Math.max(1, cpus().length - 2)),+ // Halves the time and lands on the same pixels — verified frame for frame against a run without+ // it, PSNR reporting no error at all. The flag is marked experimental upstream; that is the+ // reason to check the pixels, which is done, rather than the reason to draw twice as long.+ "--experimental-fast-capture", "--no-best-effort", "--quiet",+ ], { encoding: "utf8", windowsHide: true, timeout: 600_000 });+ assert(drawn.status === 0, `the HyperFrames runtime refused: ${(drawn.stderr ?? "").trim().slice(-2000)}`);+ });++ const written = (await readdir(frames)).filter((name) => name.endsWith(".png")).sort();+ assert(written.length > 0, "the HyperFrames runtime wrote no frames");+ const first = Math.min(window.startFrame, written.length - 1);+ const last = Math.min(window.endFrameExclusive, written.length);+ // The runtime draws with an alpha channel and leaves unpainted area transparent. What a viewer is+ // under is the Film's own clear colour, so it is composited in here rather than left to whatever+ // opens the file: a reference clip is opaque, and an observer handed a transparent counterpart reads+ // the difference as design when it came from the encoding.+ const clear = built.canvas?.clearColor ?? "#000000";+ const background = `color=c=${clear.replace("#", "0x")}:s=${canvas.width}x${canvas.height}:r=${frameRate}`;+ const count = Math.max(1, clip ? last - first : 1);+ const encoded = spawnSync("ffmpeg", [+ "-hide_banner", "-loglevel", "error", "-y",+ "-f", "lavfi", "-i", background,+ "-framerate", String(frameRate), "-start_number", String(clip ? first : Math.min(first + Math.floor((last - first) / 2), written.length - 1)),+ "-i", join(frames, "frame_%06d.png"),+ "-filter_complex", "[0][1]overlay=shortest=1[v]", "-map", "[v]",+ "-frames:v", String(count),+ ...(clip ? ["-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "20"] : []),+ outPath,+ ], { encoding: "utf8", windowsHide: true, timeout: 600_000 });+ assert(encoded.status === 0, `ffmpeg refused: ${(encoded.stderr ?? "").trim().slice(-2000)}`);++ // What timed this picture, written where the picture is. `compare_reconstruction` is handed a path+ // and nothing else, so this is how the comparison log comes to say whether the stretch it looked at+ // ran at the reference's pace or at an estimate of it.+ const report = timingReport(reference, timing);+ const sidecar: StandInSidecar = { element, window, timing: report };+ await writeFile(standInSidecarPath(outPath), `${JSON.stringify(sidecar, null, 2)}\n`, "utf8");++ return {+ element,+ out: outPath,+ compared: clip ? "clip" : "still",+ canvas,+ frame_rate: frameRate,+ window,+ program_frames: programFrames,+ timing: report,+ stand_in_ref: standInSidecarPath(outPath),+ mocked: { media: mockedMedia().size, images: imageIds.length },+ };+ }++ export type RenderPreviewsInput = {+ readonly package_dirs: readonly string[];+ };++ /**+ * Draw a package's catalogue preview images from the package's own preview Source.+ *+ * A Manifest hands Studio and the README a picture per Surface, read off disk with `readFile`. Those+ * pictures were made once and committed, and nothing could make them again: a Recipe could change, a+ * Surface could gain a port, and the catalogue would go on showing what the package used to draw.+ *+ * So the sample lives in the package as a Source it can be drawn from. `preview/preview.svml`,+ * `preview/recipes.svs` and `preview/build.svrun` hold the package's own copy, its own Recipe values+ * and its own Canvas — nothing about any project — and `renderElement` draws them through the+ * real authoring path. A Surface that stopped working cannot produce a preview that looks fine.+ *+ * Which element draws which file comes from the Manifest's own naming: a Surface tagged `Track`+ * declares `preview/Track.png`, so `Track.png` is drawn from whichever element in the preview Source+ * carries that tag. No third file has to agree with the other two.+ */+ export async function renderPreviews(input: RenderPreviewsInput): Promise<Record<string, unknown>> {+ const directories = input.package_dirs;+ assert(directories.length > 0, "package_dirs must name at least one package directory");++ const cwd = invokedFrom();+ const pictures: Record<string, unknown>[] = [];+ let written = 0;+ for (const directory of directories) {+ const packageDir = resolve(cwd, directory);+ const previewDir = join(packageDir, "preview");+ const run = join(previewDir, "build.svrun");+ const svml = await readFile(join(previewDir, "preview.svml"), "utf8").catch(() => undefined);+ assert(svml !== undefined,+ `${directory} has no preview/preview.svml. Write one: the package's own copy, its own Recipe values, its own Canvas.`);++ // The alias the preview Source imports this package under. A preview Source places Tracks from+ // several packages — it needs a semantic spine and a Film like any other — and `Track` is a common+ // tag, so the tag alone would draw whichever one happened to be written first.+ const manifestJson = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8").catch(() => "{}")) as { readonly name?: unknown };+ const specifier = manifestJson.name;+ assert(typeof specifier === "string", `${directory} has no package.json name`);+ const imported = [...svml.matchAll(/<import\s+as="([^"]+)"\s+from="(@[^"]+)@\d+"/gu)];+ const alias = imported.find((match) => match[2] === specifier)?.[1];+ assert(alias !== undefined,+ `${directory}'s preview Source does not import ${specifier}, so nothing in it is this package's`);++ // The pictures the Manifest promises, and the element tag each one is named for.+ const manifest = await readFile(join(packageDir, "src", "manifest.ts"), "utf8").catch(() => "");+ const promised = [...new Set([...manifest.matchAll(/previewImage\(\s*["']([^"']+)["']/gu)].map((match) => match[1] ?? ""))];+ const existing = (await readdir(previewDir).catch(() => [] as string[]))+ .filter((name) => /\.(png|jpe?g|svg)$/iu.test(name));+ const promisedPictures = promised.length > 0 ? promised : existing;+ assert(promisedPictures.length > 0, `${directory} promises no preview picture; nothing to draw`);++ for (const picture of promisedPictures) {+ if (/\.svg$/iu.test(picture)) {+ // Drawn by hand, not from a Source.+ pictures.push({ package_dir: directory, picture, drawn: false, reason: "drawn by hand, not from a Source" });+ continue;+ }+ const tag = basename(picture).replace(/\.[^.]+$/u, "");+ const element = new RegExp(`<${alias}:${tag}\\b[^>]*?\\bid="([^"]+)"`, "su").exec(svml)?.[1];+ assert(element !== undefined,+ `${directory} promises ${picture} but its preview Source places no <${alias}:${tag}> to draw it from`);+ const out = join(previewDir, picture);+ try {+ await renderElement({ run, element, out });+ } catch (error) {+ throw new Error(`${directory} could not draw ${picture}: ${error instanceof Error ? error.message : String(error)}`);+ }+ // A catalogue picture is compared against nothing, so the record of what timed it is dropped+ // rather than committed beside the package's own pictures.+ await rm(standInSidecarPath(out), { force: true });+ pictures.push({ package_dir: directory, picture, drawn: true, tag, element, out });+ written += 1;+ }+ }+ return { package_dirs: directories, drew: written, pictures };+ }diff --cc packages/reference-video-tools/src/checks.tsindex 00000000,bd8ad0ba..c2a1ae7amode 000000,100644..100644--- a/packages/reference-video-tools/src/checks.ts+++ b/packages/reference-video-tools/src/checks.ts@@@ -1,0 -1,1210 +1,1199 @@@+ import { readFile, readdir } from "node:fs/promises";+ import { dirname, join, resolve, sep } from "node:path";++ import { markupSurfaceHostFacetAbi } from "@hypit/markup";+ import type { RegisteredSurface } from "@hypit/markup";+ import { loadNodePackageSelection } from "@hypit/package-loader-node";+ import { parseScript } from "@hypit/script";+ import { videoCliDistribution } from "@hypit/video-cli";-import { loadStudioAdapterRegistry } from "@hypit/studio/src/adapter-profile.js";++import { loadStudioCompanionRegistry } from "@hypit/studio/src/companion-profile.js";+ import { openStudioArchive } from "@hypit/studio/src/archive.js";+ import { loadStudioDomain } from "@hypit/studio/src/domain.js";+ import { loadStudioRun } from "@hypit/studio/src/run.js";+ import { readStudioSession } from "@hypit/studio/src/session.js";+ import type { StudioSession } from "@hypit/studio/src/session.js";+ import { inspectStudioRun } from "@hypit/studio/src/studio-preflight.js";++ import { aliasPattern, invokedFrom, nearestPackageRoot, referenceRoot, scriptBody } from "./authoring.js";+ import { assert, round } from "./media.js";+ import { reviewPlan } from "./plan.js";++ export type PreviewCheckInput = {+ readonly run: string;+ readonly runtime?: string;+ };++ const AWAITING = "the Studio projection closure requires unresolved capabilities:";++ /**+ * Preview-check a reconstruction before it is delivered.+ *+ * `pnpm hypit check` proves a Source is legal; it proves nothing about whether+ * the tracks it declares can actually be built. A track that fails here fails+ * the same way when the author opens Studio, so find out now.+ *+ * The input is the Run Source, not the Author SVML. Studio's unit of work is+ * the Run — it reads the Author SVML back out of it — so a check that took the+ * `.svml` would be checking something Studio never opens.+ *+ * Studio names what it cannot resolve and stops, so preflight throwing is itself+ * the report rather than something to inspect around. Two kinds of issue come+ * back, and they mean opposite things. An unresolved *capability* means the+ * graph traced all the way to a Film and a semantic spine, and what remains is+ * work a Provider has to do — the ordinary state of a Source that declares its+ * generation rather than performing it. Every other issue means the graph is+ * wrong and no amount of generation will fix it. Only the second kind is+ * reported as unsound. `StudioPreflightError` carries `issues` as an array so+ * the two can be told apart rather than matched out of one joined message.+ */+ export async function previewCheck(+ input: PreviewCheckInput,+ roots: { readonly packageRoot: string },+ ): Promise<Record<string, unknown>> {+ const cwd = invokedFrom();+ const runPath = resolve(cwd, input.run);+ const runtimePath = input.runtime === undefined ? undefined : resolve(cwd, input.runtime);+ const packageRoot = nearestPackageRoot(dirname(runPath)) ?? roots.packageRoot;+ const workspaceRoot = dirname(runPath);++ const distributionPackageRoot = videoCliDistribution.packageRoot;+ if (distributionPackageRoot === undefined) throw new Error("active Hypit Distribution has no package root");+- const registry = await loadStudioAdapterRegistry({ workspaceRoot, packageRoot, distributionPackageRoot });++ const registry = await loadStudioCompanionRegistry({ workspaceRoot, packageRoot, distributionPackageRoot });+ const domain = await loadStudioDomain({ run: runPath, workspaceRoot, packageRoot });+ const archive = await openStudioArchive(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);++ let session: StudioSession | undefined;+ let refusal: string | undefined;+ let awaiting: readonly string[] | undefined;+ try {+ const run = await loadStudioRun({+ run: runPath,+ domain,++ registry,+ ...(archive === undefined ? {} : { archive }),+ });+ // Preflight first, so an unopenable Run is reported as the refusal it is+ // rather than as whatever the build happens to fail on afterwards.+ inspectStudioRun(registry, run.source, run);+ session = await readStudioSession({+ domain,+ registry,+ run,+ workspaceRoot,+ ...(archive === undefined ? {} : { archive }),+ revision: 0,+ });+ } catch (error) {+ const issues = (error as { readonly issues?: unknown } | null)?.issues;+ if (Array.isArray(issues) && issues.every((issue) => String(issue).startsWith(AWAITING))) {+ awaiting = issues.flatMap((issue) => String(issue).slice(AWAITING.length).split(",").map((capability) => capability.trim()));+ } else {+ refusal = error instanceof Error ? error.message : String(error);+ }+ } finally {+ // Close before reporting: a runtime archive left open outlives the check.+ await archive?.close();+ }++ if (refusal !== undefined) return { run: runPath, sound: false, refused: refusal };++ if (awaiting !== undefined) {+ // The graph traced all the way to a Film and a semantic spine; what is left is+ // work a Provider has to do. That is a pass for this gate, and the delivery+ // measurements happen on the real Build either way.+ const noun = awaiting.length === 1 ? "capability" : "capabilities";+ return {+ run: runPath,+ sound: true,+ summary: `the graph is sound, waiting on ${awaiting.length} ${noun}.`,+ awaiting,+ };+ }++ const tracks = session!.snapshot.tracks;+ const problems: Record<string, unknown>[] = [];+ for (const track of tracks) {+ const { status, errors, output } = track.provenance;+ if (errors.length > 0) problems.push({ track: track.label, errors });+ else if (status === "unresolved") problems.push({ track: track.label, unresolved: output });+ }++ if (problems.length === 0) {+ return { run: runPath, sound: true, summary: `every Track resolved (${tracks.length}).`, tracks: tracks.length };+ }+ return { run: runPath, sound: false, problems };+ }++ export type ReconstructionCheckInput = {+ readonly run: string;+ readonly reference_id?: string;+ };++ /**+ * Which route wrote the Source, and therefore what "this element was looked at" means.+ *+ * `reconstruction` credits a comparison against the reference video, logged under that reference.+ * `description` credits a review of the element against what the author asked for, logged under the+ * project — there is no reference to compare to, so the question is conformance rather than+ * difference. Everything else the check does is the same on both: which elements draw, which words+ * nothing covers, which Frames reach past the Canvas, and which timed pictures empty their windows+ * are all read from the Source and know nothing about where the Source came from.+ */+ export type AuthoringCheckMode = "reconstruction" | "description";++ export type AuthoringCheckInput = ReconstructionCheckInput & {+ readonly mode?: AuthoringCheckMode;+ };++ /**+ * Where a description-authored project's reviews are logged.+ *+ * Beside the per-render directories rather than inside them: `render_element` empties its own+ * `.hypit/compare/<key>` on the way in, and a log kept under there would be deleted by the next+ * render of the element it is the evidence for.+ *+ * Under the project rather than under a reference, because a review is about one project. That is+ * also what spares this log the cross-project filter the comparison log needs: a reference is shared+ * between every reconstruction of one video, and a project's `.hypit` is not shared with anyone.+ */+ export function reviewLogPath(runPath: string): string {+ return join(dirname(runPath), ".hypit", "reviews.jsonl");+ }++ /**+ * Which clock timed the stand-ins an element's comparisons were made over.+ *+ * `reference` is every recorded comparison drawn at the pace the reference speaks those words;+ * `estimate` is every one drawn at the pace `estimate:Speech` predicts; `mixed` is both among them.+ * `not recorded` is a comparison whose picture carried no `render_element` sidecar, so what timed it+ * is unknown.+ */+ type TimingBasis = "reference" | "estimate" | "mixed" | "not recorded";++ /** One element that draws a Track, and the comparisons recorded against its id. */+ type ElementReport = {+ readonly element: string;+ readonly id: string;+ readonly package_name: string;+ readonly comparisons: number;+ /** The stretches it was compared against: a shot, or the words a Segment or Selection marks. */+ readonly compared_against: readonly string[];+ readonly state: string;+ readonly timing_basis: TimingBasis;+ readonly note?: string;+ };++ /** One timed picture and the Recipe key that decides what it draws once its material ends. */+ type PlaybackReport = {+ readonly id: string;+ readonly tag: string;+ readonly recipe: string;+ readonly playback: string;+ };++ /** One run of consecutive Script words that nothing filling the frame is drawn over. */+ type CoverageGap = {+ readonly segment: string;+ /** The words themselves, so a reader can find the stretch in the Script. */+ readonly words: string;+ readonly word_count: number;+ };++ /** How many words the Script has, and which runs of them carry no full-frame picture. */+ type CoverageReport = {+ readonly words: number;+ readonly gaps: readonly CoverageGap[];+ };++ type Edge = "left" | "top" | "right" | "bottom";++ /** One edge of a Frame that lands outside the Canvas, and how far past it reaches. */+ type FrameEdge = {+ readonly edge: Edge;+ /** The value as the Source writes it. */+ readonly declared: string;+ /** How far past the Canvas edge it sits, as a share of the Canvas and in Canvas pixels. */+ readonly outside_percent: number;+ readonly outside_pixels: number;+ };++ /** One Frame that does not sit wholly inside its Canvas, and the elements drawn into it. */+ type OutOfBoundsFrame = {+ readonly frame: string;+ readonly canvas: string;+ /** Every element that names this Frame, by its own id. */+ readonly elements: readonly string[];+ readonly edges: readonly FrameEdge[];+ /** How much of the Frame's area lands off the Canvas, from 0 to 1. */+ readonly outside_fraction: number;+ };++ /** A rectangle in Canvas pixels. The origin is top-left and y increases downward. */+ type Box = { readonly left: number; readonly top: number; readonly right: number; readonly bottom: number };++ /**+ * Whether some rectangles, together, leave no part of a Canvas unpainted.+ *+ * One picture filling the frame is the ordinary case and the cheap one. What this exists for is the+ * case where no single picture does: a split screen, a stacked pair, a grid of panels. Those cover the+ * delivery completely while every one of them is, on its own, an insert.+ *+ * The test is exact rather than an area sum, because rectangles overlap and overlapping ones add up to+ * more area than they cover. Cutting the Canvas at every edge any rectangle contributes leaves a grid+ * of cells, each of which is wholly inside a rectangle or wholly outside all of them; the Canvas is+ * covered when no cell is outside all of them. Rectangles are grouped by the Canvas they are rooted+ * in, since two rooted in different Canvases never meet.+ */+ function fillsACanvas(+ placed: readonly { readonly canvas: string; readonly box: Box }[],+ canvases: ReadonlyMap<string, Box>,+ ): boolean {+ const byCanvas = new Map<string, Box[]>();+ for (const item of placed) byCanvas.set(item.canvas, [...(byCanvas.get(item.canvas) ?? []), item.box]);+ for (const [id, boxes] of byCanvas) {+ const canvas = canvases.get(id);+ if (canvas === undefined) continue;+ // Clipped to the Canvas: a Frame declared past the edge covers only the part of the picture that+ // exists, and counting the rest would let an overhang stand in for coverage it never provides.+ const clipped = boxes+ .map((box) => ({+ left: Math.max(box.left, canvas.left), top: Math.max(box.top, canvas.top),+ right: Math.min(box.right, canvas.right), bottom: Math.min(box.bottom, canvas.bottom),+ }))+ .filter((box) => box.right > box.left && box.bottom > box.top);+ if (clipped.length === 0) continue;+ const xs = [...new Set([canvas.left, canvas.right, ...clipped.flatMap((box) => [box.left, box.right])])]+ .filter((value) => value >= canvas.left && value <= canvas.right).sort((a, b) => a - b);+ const ys = [...new Set([canvas.top, canvas.bottom, ...clipped.flatMap((box) => [box.top, box.bottom])])]+ .filter((value) => value >= canvas.top && value <= canvas.bottom).sort((a, b) => a - b);+ let whole = true;+ for (let column = 0; whole && column + 1 < xs.length; column += 1) {+ for (let row = 0; whole && row + 1 < ys.length; row += 1) {+ const x = (xs[column]! + xs[column + 1]!) / 2;+ const y = (ys[row]! + ys[row + 1]!) / 2;+ whole = clipped.some((box) => x > box.left && x < box.right && y > box.top && y < box.bottom);+ }+ }+ if (whole) return true;+ }+ return false;+ }++ type FrameDeclaration ={ readonly within: string; readonly edges: Readonly<Record<Edge, string>> };+ type FrameGeometry = {+ readonly canvases: ReadonlyMap<string, Box>;+ readonly declared: ReadonlyMap<string, FrameDeclaration>;+ /** The rectangle a Frame or Canvas finally occupies, in the pixels of the Canvas it is rooted in. */+ readonly resolve: (id: string) => Box | undefined;+ /** Which Canvas a Frame is finally measured inside, found by following `within` up to one. */+ readonly canvasOf: (id: string) => string | undefined;+ };++ /**+ * Where every Canvas and Frame the Source declares actually sits.+ *+ * `within` names a Canvas or a parent Frame, and a length is a number followed by `px` or `%`, a+ * percentage resolving against the parent's width on the x axis and its height on the y axis. So a+ * Frame is resolved by resolving whatever it is written inside and measuring its own edges against+ * that rectangle, however deep the chain runs.+ *+ * Two readings need this: whether a Frame reaches outside its Canvas, and whether the Frames drawn+ * over a word add up to the whole picture.+ */+ function frameGeometry(svml: string): FrameGeometry {+ const space = aliasPattern(svml, "@hypit/spatial", "space");+ const canvases = new Map<string, Box>();+ for (const match of svml.matchAll(new RegExp(`<(?:${space}):Canvas\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const id = /\bid="([^"]+)"/u.exec(attributes)?.[1];+ const width = Number(/\bwidth="(\d+)"/u.exec(attributes)?.[1]);+ const height = Number(/\bheight="(\d+)"/u.exec(attributes)?.[1]);+ if (id !== undefined && Number.isFinite(width) && Number.isFinite(height)) {+ canvases.set(id, { left: 0, top: 0, right: width, bottom: height });+ }+ }++ const declared = new Map<string, FrameDeclaration>();+ for (const match of svml.matchAll(new RegExp(`<(?:${space}):Frame\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const id = /\bid="([^"]+)"/u.exec(attributes)?.[1];+ const within = /\bwithin=\{([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1];+ const written = (name: Edge): string | undefined => new RegExp(`\\b${name}="([^"]+)"`, "u").exec(attributes)?.[1];+ const left = written("left");+ const top = written("top");+ const right = written("right");+ const bottom = written("bottom");+ if (id === undefined || within === undefined) continue;+ if (left === undefined || top === undefined || right === undefined || bottom === undefined) continue;+ declared.set(id, { within, edges: { left, top, right, bottom } });+ }++ const measure = (value: string, span: number, origin: number): number | undefined => {+ const parsed = /^\s*(-?\d+(?:\.\d+)?)\s*(%|px)\s*$/u.exec(value);+ if (parsed === null) return undefined;+ const number = Number(parsed[1]);+ return parsed[2] === "%" ? origin + span * number / 100 : origin + number;+ };++ const resolving = new Set<string>();+ const resolved = new Map<string, Box | undefined>();+ const resolve = (id: string): Box | undefined => {+ const canvas = canvases.get(id);+ if (canvas !== undefined) return canvas;+ if (resolved.has(id)) return resolved.get(id);+ // A Frame written inside itself is refused by `hypit check`; this keeps the walk finite anyway.+ if (resolving.has(id)) return undefined;+ const frame = declared.get(id);+ if (frame === undefined) return undefined;+ resolving.add(id);+ const parent = resolve(frame.within);+ resolving.delete(id);+ let box: Box | undefined;+ if (parent !== undefined) {+ const width = parent.right - parent.left;+ const height = parent.bottom - parent.top;+ const left = measure(frame.edges.left, width, parent.left);+ const top = measure(frame.edges.top, height, parent.top);+ const right = measure(frame.edges.right, width, parent.left);+ const bottom = measure(frame.edges.bottom, height, parent.top);+ if (left !== undefined && top !== undefined && right !== undefined && bottom !== undefined) {+ box = { left, top, right, bottom };+ }+ }+ resolved.set(id, box);+ return box;+ };++ const canvasOf = (id: string): string | undefined => {+ const seen = new Set<string>();+ let at: string | undefined = id;+ while (at !== undefined && !canvases.has(at)) {+ if (seen.has(at)) return undefined;+ seen.add(at);+ at = declared.get(at)?.within;+ }+ return at;+ };++ return { canvases, declared, resolve, canvasOf };+ }++ /**+ * Every Frame that reaches past the Canvas it is measured inside.+ *+ * A Frame places its four edges against a Canvas, and an edge outside 0%–100% puts that much of+ * whatever is drawn into it off the picture. This is arithmetic on the Source: no threshold, no+ * measurement of a rendered frame, no observer.+ *+ * It is the one thing on this route a comparison cannot see. An element authored mostly below the+ * bottom edge is drawn at the Canvas the Source declares, and so is the stand-in it is compared+ * against, so the render and the reference both put it in the same place off the edge and agree with+ * each other. Both are wrong the same way, which reads as correct.+ *+ * Reaching past the edge is also how a great deal of correct authoring works: an element that slides+ * in from off-screen is outside at the start of its window, and a full-bleed picture is routinely+ * declared past the edge so a `fit` crops it rather than letterboxing it. The arithmetic is the same+ * either way, so what this produces is a list of candidates for a reader to answer one at a time. It+ * never decides `passed`: the Source cannot tell an intended overhang from an unintended one, and a+ * gate that ruled on it would be ruling on something it cannot see.+ */+ function framesPastTheCanvas(svml: string): readonly OutOfBoundsFrame[] {+ const { canvases, declared, resolve, canvasOf } = frameGeometry(svml);++ // Which elements draw into each Frame. A Track names it `frame=`, and a speech Track names the Frame+ // it draws each Take into `visual-frame=`, so any attribute whose name ends in `frame` counts.+ const bound = new Map<string, string[]>();+ for (const match of svml.matchAll(/<([a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*)\b([^>]*?)\/?>/gsu)) {+ const tag = match[1] ?? "";+ const attributes = match[2] ?? "";+ const id = /\bid="([^"]+)"/u.exec(attributes)?.[1] ?? tag;+ for (const reference of attributes.matchAll(/\b[a-z-]*frame=\{([A-Za-z0-9_-]+)\}/gu)) {+ const frame = reference[1] ?? "";+ const named = bound.get(frame) ?? [];+ if (!named.includes(id)) named.push(id);+ bound.set(frame, named);+ }+ }++ const report: OutOfBoundsFrame[] = [];+ for (const [id, frame] of declared) {+ const box = resolve(id);+ const canvasId = canvasOf(id);+ const canvas = canvasId === undefined ? undefined : canvases.get(canvasId);+ if (box === undefined || canvas === undefined || canvasId === undefined) continue;+ const width = canvas.right - canvas.left;+ const height = canvas.bottom - canvas.top;+ // An edge is outside when it is outside the Canvas at all, on either side. A Frame parked wholly+ // off the left has both its x edges past the left edge, and naming only the one on its own side+ // would report half of where it sits.+ const outside = (value: number, low: number, high: number): number => Math.max(low - value, value - high, 0);+ const past: readonly { readonly edge: Edge; readonly outside: number; readonly span: number }[] = [+ { edge: "left", outside: outside(box.left, canvas.left, canvas.right), span: width },+ { edge: "top", outside: outside(box.top, canvas.top, canvas.bottom), span: height },+ { edge: "right", outside: outside(box.right, canvas.left, canvas.right), span: width },+ { edge: "bottom", outside: outside(box.bottom, canvas.top, canvas.bottom), span: height },+ ];+ const edges = past.filter((item) => item.outside > 0).map((item) => ({+ edge: item.edge,+ declared: frame.edges[item.edge],+ outside_percent: round(item.outside / item.span * 100),+ outside_pixels: round(item.outside),+ }));+ if (edges.length === 0) continue;+ const area = Math.max(0, box.right - box.left) * Math.max(0, box.bottom - box.top);+ const inside = Math.max(0, Math.min(box.right, canvas.right) - Math.max(box.left, canvas.left))+ * Math.max(0, Math.min(box.bottom, canvas.bottom) - Math.max(box.top, canvas.top));+ report.push({+ frame: id,+ canvas: canvasId,+ elements: bound.get(id) ?? [],+ edges,+ outside_fraction: round(area === 0 ? 1 : 1 - inside / area),+ });+ }+ return report;+ }++ /**+ * Report what a route can still settle after the Source is written and before a Build runs: which+ * drawing elements nobody has looked at, which words of the Script nothing draws a full-frame+ * picture over, and which timed pictures are configured to stop before their window ends.+ *+ * Both routes end here, and `mode` is the only thing that differs. A reconstruction is looked at by+ * comparing each element against the reference; a description-authored program has no reference, so+ * each element is reviewed against what the author asked for. What counts as evidence and where it+ * is logged follow from that; everything else below is read from the Source and does not care.+ *+ * `preview_check` proves the graph is wired. It proves nothing about whether what the graph draws is+ * what was wanted, and a Source can pass every structural check while a component draws something+ * nobody asked for. Closing that gap is `references/element-review.md` and the route file beside it,+ * which is prose, and prose is what a route skips silently. This is the same requirement as a command+ * that answers whether it was met.+ *+ * What it checks is **participation, not convergence**. The round is deliberately bounded and may+ * stop with visible differences remaining, so requiring convergence here would contradict it. An+ * element that was compared once and stopped at its ceiling passes; an element nobody ever looked+ * at does not.+ *+ * Every element that draws is required, whichever package draws it. A Track from installed+ * vocabulary carries authored values exactly as a project-local one does — a caption Style's size,+ * colour and placement are as unverified as a new package's — and `render_element` stands in for the+ * speech, so it renders before a Build like any other.+ *+ * A look counts once it has been answered: in band (`complete`, the gemini observer) or handed out+ * and closed by whoever answered it (`pending` until then). Only `failed` is not a look. The gate+ * cannot judge whether the stretch an element was looked at over actually showed it, so the stretches+ * are reported for a reader, and a lone look is called out rather than assumed meaningful.+ *+ * Each element also carries what timed the stand-ins it was compared over, read from the sidecar+ * `render_element` writes beside its output and carried into the log by `compare_reconstruction`.+ * That is reported rather than required: participation is the rule here, and an estimate-timed+ * comparison is a comparison. What it says is which elements have had their behaviour over their+ * window looked at and which have only had their layout looked at.+ *+ * Where each Frame sits is decided from the Source alone and is reported rather than required.+ * `framesPastTheCanvas` above says why an overhang cannot decide `passed`.+ *+ * Frame coverage is decided from the Source alone and is required: a word is either drawn over by+ * something bound to the whole picture or it is not. What covers is read from an element's own+ * opening tag — a full-bleed `frame=`, the `canvas=`, or a speech Track's full-frame `visual-frame=`+ * over the Segments whose Takes carry a picture — so a Track never inherits its children's `during=`+ * bindings.+ *+ * A project that places no drawing element passes with nothing to require.+ */+ export async function authoringCheck(+ input: AuthoringCheckInput,+ roots: { readonly packageRoot: string },+ ): Promise<Record<string, unknown>> {+ const mode: AuthoringCheckMode = input.mode ?? "reconstruction";+ // What looking at an element is called on this route. A reconstruction compares it against the+ // reference; a description-authored program has nothing to compare to and is read against what the+ // author asked for. The arithmetic is the same either way, so only the word differs — and the keys+ // do not, so one shape describes both reports.+ const looked = mode === "reconstruction" ? "compared" : "reviewed";+ const looking = mode === "reconstruction" ? "comparison" : "review";+ const cwd = invokedFrom();+ const runPath = resolve(cwd, input.run);+ // Where the Source's imports resolve from. A project's own packages are installed against the+ // project, so the Run names its own root: the nearest directory at or above it holding a+ // `package.json`, which is the same walk `hypit check` makes. Taking it from the working directory+ // instead meant a Run named by a path resolved its packages somewhere else entirely, and the+ // project's own elements read as packages that do not exist.+ const packageRoot = nearestPackageRoot(dirname(runPath)) ?? roots.packageRoot;++ const runSource = await readFile(runPath, "utf8").catch(() => undefined);+ assert(runSource !== undefined, `cannot read ${runPath}`);+ const author = /<author\s+source="([^"]+)"/u.exec(runSource)?.[1];+ assert(author !== undefined, `${input.run} declares no <author source="…"/>`);+ const svmlPath = resolve(dirname(runPath), author);+ const svml = await readFile(svmlPath, "utf8").catch(() => undefined);+ assert(svml !== undefined, `cannot read ${svmlPath}`);++ // Read from the Source alone, so every answer below carries it, including the ones that stop early.+ const overhang = framesPastTheCanvas(svml);++ // Every package this Source imports. The scope is whatever the Source wrote: a project that declares+ // a vocabulary gap and fills it publishes under its own scope, and those elements draw exactly as an+ // installed one does.+ // Attribute order is not significant in this markup, and a pattern that fixed it read a Source+ // written the other way round as importing nothing at all — then passed it, because nothing to+ // compare and nothing found look alike from here.+ const imports = [...svml.matchAll(/<import\b([^>]*?)\/?>/gsu)]+ .map((match) => ({+ alias: /\bas="([^"]+)"/u.exec(match[1] ?? "")?.[1] ?? "",+ specifier: /\bfrom="(@[^"@/]+\/[^"@]+)@\d+"/u.exec(match[1] ?? "")?.[1] ?? "",+ }))+ .filter((item) => item.alias.length > 0 && item.specifier.length > 0);+ if (imports.length === 0) {+ return {+ run: runPath,+ // Not one aliased package import could be read. Whether the Source truly imports nothing or+ // this failed to read it, what follows knows nothing about what the Source draws — and a+ // reading that came back empty is not a reconstruction that is covered.+ passed: false,+ summary: [`no aliased package import could be read from ${svmlPath}, so nothing is known about what this Source draws.`],+ elements: [],+ playback: [],+ uncovered: [],+ out_of_bounds: overhang,+ };+ }++ // Which of their Surfaces draw a Track. A Style Surface publishes a Style and draws nothing, so+ // requiring a comparison of it would be asking for a picture that does not exist.+ const specifiers = [...new Set(imports.map((item) => item.specifier))];+ // One unresolvable package used to take the rest with it: the whole selection loads or none of it+ // does, and a swallowed failure left `drawingTags` empty, so every element in the Source read as+ // drawing nothing and the check passed on an empty answer. Fall back to loading them one at a time so+ // the ones that resolve still count, and keep the names of the ones that did not.+ const unresolved: string[] = [];+ const loaded = await loadNodePackageSelection(specifiers, packageRoot).catch(async () => {+ const each = await Promise.all(specifiers.map(async (specifier) =>+ await loadNodePackageSelection([specifier], packageRoot).catch(() => {+ unresolved.push(specifier);+ return [];+ })));+ return each.flat();+ });+ const drawingTags = new Set<string>();- const timeVaryingKeys = new Set<string>();+ for (const pack of loaded) {+ for (const facet of pack.contribution.hostFacets ?? []) {+ if (facet.abi !== markupSurfaceHostFacetAbi) continue;+ const surface = facet.implementation as RegisteredSurface;+ const draws = surface.outputs.some((output) =>+ output.module.name === "@hypit/composition" && (output.name === "VisualTrack" || output.name === "AudioTrack"));+ if (draws) drawingTags.add(`${pack.specifier}#${surface.tag}`);- // Which Recipe properties the package itself calls time-varying.- //- // `caption-fine` sorts every property it declares into where / how / when, and `when` is- // exactly the question one of the planning rules asks: does this run for as long as the window- // does? Reading the package's own answer keeps that rule correct for properties added after- // this file was written, which a list maintained here would not be.- for (const attribute of surface.vocabulary?.attributes ?? []) {- for (const property of attribute.recipe ?? []) {- if (property.group === "when") timeVaryingKeys.add(property.name);- }- }+ }+ }++ // Every use of one of those tags, by the id the Source gave it.+ const drawn: { readonly id: string; readonly tag: string; readonly alias: string; readonly specifier: string }[] = [];+ for (const { alias, specifier } of imports) {+ const pattern = new RegExp(`<${alias}:([A-Za-z][A-Za-z0-9]*)\\b[^>]*?\\bid="([^"]+)"`, "gu");+ for (const match of svml.matchAll(pattern)) {+ const tag = match[1] ?? "";+ const id = match[2] ?? "";+ if (!drawingTags.has(`${specifier}#${tag}`)) continue;+ if (!drawn.some((item) => item.id === id)) drawn.push({ id, tag, alias, specifier });+ }+ }++ // Which Normalize ids carry a picture. A take normalized with `video="none"` is a voice: it has no+ // window to fill, and nothing it feeds puts anything on the Canvas.+ const moving = new Set<string>();+ const pipeline = aliasPattern(svml, "@hypit/media-pipeline", "pipeline");+ for (const match of svml.matchAll(new RegExp(`<(?:${pipeline}):Normalize\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const id = /\bid="([^"]+)"/u.exec(attributes)?.[1];+ const video = /\bvideo="([^"]+)"/u.exec(attributes)?.[1];+ if (id !== undefined && video !== undefined && video !== "none") moving.add(id);+ }++ // ---- Timed pictures that stop before their window ends ----+ //+ // A generated take is asked for a whole number of seconds, and the window it has to fill comes from+ // speech the same Build synthesizes. The two lengths are arrived at separately and do not meet: the+ // estimate rounds, and the voice that finally speaks is not the voice the estimate predicted. So the+ // material is routinely shorter than the window it was made for, by anything from a rounding+ // remainder to a couple of seconds.+ //+ // What happens then is decided by one Recipe key. `playback` defaults to `once-start`, which draws+ // the material once and then draws nothing at all — `sampling.ts` emits no segment for the remainder,+ // so those frames fall through to whatever is beneath. Under a full-frame base that is the Film+ // background, which is black. `hold-start` pins the last frame for the rest of the window instead,+ // `loop-start` repeats, and `stretch` retimes to fit; any of the three fills it.+ //+ // This is `frame-coverage.md`'s inherited edge — "a generated take, which ends where its material+ // ends rather than where the shot should" — in the one form the route can settle before a Build, from+ // the Source and its Recipe sheets alone.+ const playbackReport = async (): Promise<readonly PlaybackReport[]> => {+ // Every Recipe body the Source can name, by the alias its sheet was imported under.+ const sheets = new Map<string, Map<string, string>>();+ for (const match of svml.matchAll(/<import\s+as="([^"]+)"\s+source="([^"]+\.svs)"/gu)) {+ const alias = match[1] ?? "";+ const source = match[2] ?? "";+ const text = await readFile(resolve(dirname(svmlPath), source), "utf8").catch(() => undefined);+ if (text === undefined) continue;+ const recipes = new Map<string, string>();+ for (const recipe of text.matchAll(/([A-Za-z0-9_.-]+)\s*\{([^}]*)\}/gu)) recipes.set(recipe[1] ?? "", recipe[2] ?? "");+ sheets.set(alias, recipes);+ }++ // Which aliases belong to a package that draws. Plenty of elements consume a normalized media+ // without placing it — `whisperx:SemanticTake` reads one to align speech against it and puts no+ // picture on the Canvas, so it has no window to fill and no occupancy to choose. Requiring the+ // alias to come from a package with a Track that outputs a VisualTrack keeps those out, and keeps+ // the Items and Sequences written inside such a Track in, without this needing to know their tags.+ const draws = new Set(imports+ .filter(({ specifier }) => [...drawingTags].some((key) => key.startsWith(`${specifier}#`)))+ .map(({ alias }) => alias));++ // Every element that places one of those pictures, and what its Recipe says to do with a window the+ // material does not fill.+ const running: PlaybackReport[] = [];+ for (const match of svml.matchAll(/<([a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*)\b([^>]*?)\/?>/gsu)) {+ const tag = match[1] ?? "";+ const attributes = match[2] ?? "";+ if (!draws.has(tag.slice(0, tag.indexOf(":")))) continue;+ const media = /\bmedia=\{([A-Za-z0-9_-]+)\.media\}/u.exec(attributes)?.[1];+ if (media === undefined || !moving.has(media)) continue;+ const appearance = /\bappearance=\{([A-Za-z0-9_-]+)\.([A-Za-z0-9_.-]+)\}/u.exec(attributes);+ const body = appearance === null ? undefined : sheets.get(appearance[1] ?? "")?.get(appearance[2] ?? "");+ const playback = body === undefined ? undefined : /\bplayback\s*:\s*([A-Za-z-]+)/u.exec(body)?.[1];+ if (playback !== undefined && playback !== "once-start" && playback !== "once-end") continue;+ running.push({+ id: /\bid="([^"]+)"/u.exec(attributes)?.[1] ?? tag,+ tag,+ recipe: appearance === null ? "no appearance Recipe" : `${appearance[1]}.${appearance[2]}`,+ playback: playback ?? "once-start, by default",+ });+ }+ return running;+ };++ // ---- Words nothing draws a full-frame picture over ----+ //+ // A delivery is a picture at every frame; a Source is a list of placements. A word no full-frame+ // element is drawn over is an instant the Source hands to whatever lies beneath it, and beneath the+ // last placement is the Film background, which is black. That is `frame-coverage.md`'s rule in the+ // one form the Source settles on its own, and it needs no threshold: it is a yes or no per word.+ //+ // What covers is read from each element's own opening tag and never from what is written inside it.+ // A Track holding forty Lines with `during=` bindings draws nothing itself; crediting it with its+ // children's bindings would report full coverage for a Source that places text over nothing.+ const coverageReport = (): CoverageReport => {+ const body = scriptBody(svml);+ const parsed = parseScript(svmlPath, body.text, body.offset);++ // Where every Frame and Canvas the Source declares actually sits, so a word can be asked whether+ // the pictures drawn over it add up to the whole one rather than whether any single one does.+ //+ // A split screen is why. Two people on a podcast, one above the other, each half the height: the+ // one speaking owns the Segment and the one listening covers the rest, and neither Frame is the+ // whole picture. Read one Frame at a time, both are inserts and every word of the program is+ // uncovered — which is the opposite of what the delivery shows.+ const geometry = frameGeometry(svml);++ // What each word has drawn over it, as rectangles in the pixels of the Canvas they are rooted in.+ const claims: { readonly canvas: string; readonly box: Box }[][] = Array.from(+ { length: parsed.tokens.length }, () => []);+ const claimSpan = (from: number, to: number, canvas: string, box: Box): void => {+ for (let index = Math.max(0, from); index < Math.min(to, claims.length); index += 1) {+ claims[index]!.push({ canvas, box });+ }+ };+ const claimSegment = (id: string, canvas: string, box: Box, stops = Infinity): void => {+ const segment = parsed.segments.find((item) => item.id === id);+ if (segment !== undefined) claimSpan(segment.tokenStart, Math.min(segment.tokenEndExclusive, stops), canvas, box);+ };+ const claimSelection = (id: string, canvas: string, box: Box, stops = Infinity): void => {+ const selection = parsed.selections.find((item) => item.id === id);+ if (selection !== undefined) {+ claimSpan(selection.open.boundary.tokenIndex, Math.min(selection.close.boundary.tokenIndex, stops), canvas, box);+ }+ };+ // A Frame drawn into, resolved to where it sits. Naming the Canvas directly is the whole of it.+ const placement = (frame: string | undefined, canvas: string | undefined): { readonly canvas: string; readonly box: Box } | undefined => {+ const named = frame ?? canvas;+ if (named === undefined) return undefined;+ const rooted = geometry.canvasOf(named);+ const box = geometry.resolve(named);+ if (rooted === undefined || box === undefined) return undefined;+ return { canvas: rooted, box };+ };++ // Every element that draws a picture, and the words its own `during=` claims. `program` is the+ // whole Script; a Segment or a Selection is the words it marks.+ for (const match of svml.matchAll(/<[a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*\b([^>]*?)\/?>/gsu)) {+ const attributes = match[1] ?? "";+ const where = placement(+ /\bframe=\{([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1],+ /\bcanvas=\{([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1]);+ if (where === undefined) continue;+ // A Moment in `until=` cuts the span short, so the words after it have this picture over them in+ // the Source and not in the delivery. Reading `during=` alone would let an element that leaves+ // half way through the program answer for the whole of it.+ const until = /\buntil=\{story\.moment\.([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1];+ const stops = until === undefined+ ? claims.length+ : parsed.moments.find((item) => item.id === until)?.boundary.tokenIndex ?? claims.length;+ if (/\bduring="program"/u.test(attributes)) claimSpan(0, stops, where.canvas, where.box);+ const bound = /\bduring=\{story\.(segment|selection)\.([A-Za-z0-9_-]+)\}/u.exec(attributes);+ if (bound?.[1] === "segment") claimSegment(bound[2] ?? "", where.canvas, where.box, stops);+ if (bound?.[1] === "selection") claimSelection(bound[2] ?? "", where.canvas, where.box, stops);+ }++ // A speech Track draws each Take it assembles into its own `visual-frame`, so that Frame is what+ // the Take's Segment has over it. A Take fed by a Normalize with `video="none"` is a voice and+ // puts nothing there, so its Segment is spoken over whatever is already on screen.+ const takes = new Map<string, { readonly segment: string; readonly picture: boolean }>();+ const whisperx = aliasPattern(svml, "@hypit/whisperx", "whisperx");+ const speech = aliasPattern(svml, "@hypit/speech-track", "speech");+ for (const match of svml.matchAll(new RegExp(`<(?:${whisperx}):SemanticTake\\b([^>]*?)/?>`, "gsu"))) {+ const attributes = match[1] ?? "";+ const id = /\bid="([^"]+)"/u.exec(attributes)?.[1];+ const segment = /\bsegment=\{story\.segment\.([A-Za-z0-9_-]+)\}/u.exec(attributes)?.[1];+ const media = /\bmedia=\{([A-Za-z0-9_-]+)\.media\}/u.exec(attributes)?.[1];+ if (id === undefined || segment === undefined) continue;+ takes.set(id, { segment, picture: media !== undefined && moving.has(media) });+ }+ for (const track of svml.matchAll(new RegExp(`<(?:${speech}):Track\\b([^>]*?)>(.*?)</(?:${speech}):Track>`, "gsu"))) {+ const where = placement(/\bvisual-frame=\{([A-Za-z0-9_-]+)\}/u.exec(track[1] ?? "")?.[1], undefined);+ if (where === undefined) continue;+ for (const take of (track[2] ?? "").matchAll(new RegExp(`<(?:${speech}):Take\\b[^>]*?\\bsource=\\{([A-Za-z0-9_-]+)\\.take\\}`, "gu"))) {+ const named = takes.get(take[1] ?? "");+ if (named?.picture === true) claimSegment(named.segment, where.canvas, where.box);+ }+ }++ const covered = claims.map((placed) => placed.length > 0 && fillsACanvas(placed, geometry.canvases));++ // The uncovered words as runs, cut at Segment boundaries so each run is named by the Segment a+ // reader would look in to find it.+ const gaps: CoverageGap[] = [];+ for (const segment of parsed.segments) {+ let run: number[] = [];+ const close = (): void => {+ if (run.length === 0) return;+ gaps.push({ segment: segment.id, words: run.map((index) => parsed.tokens[index]!.text).join(" "), word_count: run.length });+ run = [];+ };+ for (let index = segment.tokenStart; index < segment.tokenEndExclusive; index += 1) {+ if (covered[index] === true) close();+ else run.push(index);+ }+ close();+ }+ return { words: parsed.tokens.length, gaps };+ };++ const running = await playbackReport();++ if (drawn.length === 0 && running.length === 0) {+ // Nothing placed and nothing seen are the same answer from here, and only one of them is a pass.+ // A project whose vocabulary resolved and placed no drawing element has nothing to require; one+ // whose packages did not resolve, or none of whose packages publishes a Surface that draws, has+ // been read by something that could not see — and the names of what it could not see were being+ // dropped on the way out.+ const blind = unresolved.length > 0 || drawingTags.size === 0;+ return {+ run: runPath,+ passed: !blind,+ summary: [unresolved.length > 0+ ? `${unresolved.length} imported package${unresolved.length === 1 ? "" : "s"} could not be resolved from ${packageRoot}, so nothing is known about what the Source draws.`+ : drawingTags.size === 0+ ? `no package the Source imports publishes a Surface that draws, so nothing is known about what the Source draws.`+ : "no drawing element is placed in the Source; nothing to require."],+ elements: [],+ playback: [],+ uncovered: [],+ out_of_bounds: overhang,+ ...(unresolved.length === 0 ? {} : {+ unresolved_packages: {+ names: unresolved,+ package_root: packageRoot,+ note: "A project that publishes its own packages resolves them from the project root, where "+ + "`packages/<name>/package.json` carries the scoped name. Run the command from that directory, "+ + "or pass --package-root <project directory>.",+ },+ }),+ };+ }++ // What a round has to look at, decided from the Source rather than left to whoever runs it.+ //+ // The Recipe bodies come along because one of the three rules asks whether an element's appearance+ // runs for as long as its window does, and that is written in the Recipe rather than on the tag.+ const recipeBodies = new Map<string, string>();+ for (const sheet of svml.matchAll(/<import\s+as="[^"]+"\s+source="([^"]+\.svs)"/gu)) {+ const text = await readFile(resolve(dirname(svmlPath), sheet[1] ?? ""), "utf8").catch(() => undefined);+ if (text === undefined) continue;+ for (const recipe of text.matchAll(/([A-Za-z0-9_.-]+)\s*\{([^}]*)\}/gu)) recipeBodies.set(recipe[1] ?? "", recipe[2] ?? "");+ }- const plan = reviewPlan({ svml, svmlPath, scriptBody: scriptBody(svml), drawn, recipes: recipeBodies, timeVaryingKeys });++ const plan = reviewPlan({ svml, svmlPath, scriptBody: scriptBody(svml), drawn, recipes: recipeBodies });+ // The same parse the plan was built from, so a look recorded against a Segment can be resolved to+ // the words that Segment marks and compared with a plan entry on one axis.+ const plannedBody = scriptBody(svml);+ const plannedScript = parseScript(svmlPath, plannedBody.text, plannedBody.offset);++ const coverage = coverageReport();+ const uncoveredWords = coverage.gaps.reduce((sum, gap) => sum + gap.word_count, 0);++ // The Source does not name the reference it reconstructs, so a single prepared reference is used+ // when there is exactly one and named explicitly when there is more than one.+ //+ // Only on the route that has a reference. A description-authored project has none, and resolving+ // one here is what used to stop this command before it reached the checks that have nothing to do+ // with a reference — the `playback` refusal, frame coverage and the Canvas overhang are read from+ // the Source alone, and were unreachable to that route for no reason but this block.+ const preparedRoot = referenceRoot();+ let reference: string | undefined;+ if (mode === "reconstruction") {+ const prepared = (await readdir(preparedRoot, { withFileTypes: true }).catch(() => []))+ .filter((entry) => entry.isDirectory()).map((entry) => entry.name);+ reference = input.reference_id;+ if (reference === undefined) {+ assert(prepared.length > 0, `no prepared reference under ${preparedRoot}; run prepare_reference first`);+ assert(prepared.length === 1, `${prepared.length} prepared references; pass --reference-id (${prepared.join(", ")})`);+ reference = prepared[0]!;+ }+ assert(prepared.includes(reference), `reference ${reference} is not prepared under ${preparedRoot}`);+ }++ type LoggedComparison = {+ readonly element?: string;+ readonly shot_id?: string;+ readonly range?: { readonly segment?: string; readonly selection?: string; readonly tokens?: readonly [number, number] };+ readonly status: string;+ readonly id?: string;+ readonly image_path?: string;+ readonly stand_in?: { readonly timing?: { readonly basis?: string } };+ };+ // What the comparison was made against, as a reader would name it: a shot, or the words a Segment+ // or Selection marks.+ const against = (entry: LoggedComparison): string =>+ entry.shot_id+ ?? (entry.range?.segment === undefined ? undefined : `segment ${entry.range.segment}`)+ ?? (entry.range?.selection === undefined ? undefined : `selection ${entry.range.selection}`)+ ?? "an unnamed stretch";+ const logPath = mode === "reconstruction"+ ? join(preparedRoot, reference!, "comparisons.jsonl")+ : reviewLogPath(runPath);+ // A reference is keyed by the video, and rightly: its observations are about that video and cost+ // real money, so two reconstructions of one file share them. Its comparisons are not about the+ // video — they are about one reconstruction — and they were being kept in the same place, so a+ // second project reconstructing the same file was credited with the first one's looking, over+ // Segments its own Script does not contain.+ //+ // What separates them is already on every row: the render it compared. A render belongs to the+ // project that produced it, so a row whose picture is not under this project is not this project's+ // evidence. Nothing has to move and no earlier log has to be migrated.+ //+ // A review log needs none of this: it is already the project's own, so every row in it is this+ // project's evidence and there is nothing to separate.+ const inThisProject = (entry: LoggedComparison): boolean => {+ if (mode === "description") return true;+ if (entry.image_path === undefined) return false;+ const at = resolve(entry.image_path);+ return at === packageRoot || at.startsWith(`${packageRoot}${sep}`);+ };+ const everything = (await readFile(logPath, "utf8").catch(() => ""))+ .split("\n").filter((line) => line.trim().length > 0)+ .flatMap((line) => { try { return [JSON.parse(line) as LoggedComparison]; } catch { return []; } });+ const elsewhere = everything.length - everything.filter(inThisProject).length;+ const logged = everything.filter(inThisProject);+ // A pair handed out and not yet reported on. Naming these separately is what keeps an element with+ // three open comparisons from reading as one that was never looked at.+ const awaiting = logged.filter((entry) => entry.status === "pending");+ const log = logged+ // A comparison counts when it was answered. The observer that uploads answers in band and the+ // entry is written `complete`; the observer that reads pictures is handed the pair and closes its+ // entry with `record_observation --key comparison:<id>`. An entry still `pending` is a pair nobody+ // has reported on, and crediting it credited the tool call rather than the look.+ .filter((entry) => entry.status === "complete");++ // Which stretches each element was compared against, in order. The gate cannot judge whether a+ // stretch was the right one to compare against — it does not know what the element draws — so it+ // reports them and lets a reader notice a component compared against one that never showed it.+ const rounds = new Map<string, string[]>();+ // What timed each comparison's stand-in. A picture drawn at the estimator's pace holds every+ // element in the right place for the wrong length of time, so an element compared only that way has+ // had its layout settled and its behaviour over the window left alone.+ const bases = new Map<string, TimingBasis[]>();+ for (const entry of log) {+ if (entry.element === undefined) continue;+ const seen = rounds.get(entry.element) ?? [];+ seen.push(against(entry));+ rounds.set(entry.element, seen);+ const recorded = entry.stand_in?.timing?.basis;+ const basis: TimingBasis = recorded === "reference" || recorded === "estimate" || recorded === "mixed" ? recorded : "not recorded";+ bases.set(entry.element, [...(bases.get(entry.element) ?? []), basis]);+ }+ // One answer per element, over every comparison it has. Agreement carries through; disagreement is+ // `mixed`, which is the honest answer for an element compared once each way.+ const timingBasis = (id: string): TimingBasis => {+ const recorded = new Set(bases.get(id) ?? []);+ if (recorded.size === 0) return "not recorded";+ return recorded.size === 1 ? [...recorded][0]! : "mixed";+ };++ // Which of the plan's entries have been answered.+ //+ // A logged look and a planned one are compared as word ranges, because that is the one form both+ // can always be put in: a look recorded against a Segment resolves to the words that Segment marks,+ // and a look recorded against a Cue was never anything else. Comparing the names instead would let+ // a Cue in the middle of a Segment match the Segment, and the coverage this gate claims would be+ // wider than the coverage it has.+ const asTokens = (entry: LoggedComparison): string | undefined => {+ if (entry.range?.tokens !== undefined) return `${entry.range.tokens[0]}-${entry.range.tokens[1]}`;+ const segment = entry.range?.segment === undefined+ ? undefined+ : plannedScript.segments.find((item) => item.id === entry.range!.segment);+ if (segment !== undefined) return `${segment.tokenStart}-${segment.tokenEndExclusive}`;+ const selection = entry.range?.selection === undefined+ ? undefined+ : plannedScript.selections.find((item) => item.id === entry.range!.selection);+ if (selection !== undefined) return `${selection.open.boundary.tokenIndex}-${selection.close.boundary.tokenIndex}`;+ // A shot names a cut in the reference's picture rather than a range of the Script's words, so it+ // answers no plan entry. It still counts as having looked, which `rounds` already records.+ return undefined;+ };+ const answered = new Set(log.flatMap((entry) => {+ const tokens = asTokens(entry);+ return entry.element === undefined || tokens === undefined ? [] : [`${entry.element} ${tokens}`];+ }));+ const owed = plan.filter((entry) => !answered.has(`${entry.element} ${entry.tokens[0]}-${entry.tokens[1]}`));++ const never = drawn.filter((element) => (rounds.get(element.id) ?? []).length === 0);+ const unlabelled = log.filter((entry) => entry.element === undefined).length;+ // A misspelled --element is otherwise silent: the comparison happens, the log grows, and the element+ // it was meant for stays at zero for ever.+ const known = new Set(drawn.map((item) => item.id));+ const unknown = [...new Set([...rounds.keys()].filter((id) => !known.has(id)))];++ const elements: ElementReport[] = drawn.map((element) => {+ const stretches = rounds.get(element.id) ?? [];+ const state = stretches.length === 0+ ? `never ${looked}`+ : `${stretches.length} ${looking}${stretches.length === 1 ? "" : "s"} against ${[...new Set(stretches)].join(", ")}`;+ return {+ element: `${element.alias}:${element.tag}`,+ id: element.id,+ package_name: element.specifier,+ comparisons: stretches.length,+ compared_against: [...new Set(stretches)],+ state,+ timing_basis: timingBasis(element.id),+ // The gate cannot judge whether the stretch chosen actually showed the element, so a lone+ // comparison is called out for a reader to confirm rather than silently accepted.+ ...(stretches.length === 1 ? { note: `single ${looking} — confirm this stretch shows the element, not a look-alike` } : {}),+ };+ });++ // Elements whose comparisons say nothing about how they behave over their window: every recorded+ // comparison was drawn at the estimator's pace, or its picture carried no record of what timed it.+ const untimed = elements.filter((element) => element.comparisons > 0 && element.timing_basis !== "reference");++ const summary: string[] = [];+ if (never.length === 0 && running.length === 0) {+ summary.push(`every drawing element has been ${looked} (${elements.length}), and every timed picture fills its window.`);+ }+ if (never.length > 0) summary.push(`${never.length} of ${elements.length} elements have never been ${looked}.`);+ if (owed.length > 0) {+ summary.push(`${owed.length} of ${plan.length} stretch${plan.length === 1 ? "" : "es"} the Source asks for `+ + `${owed.length === 1 ? "has" : "have"} not been ${looked}.`);+ }+ if (running.length > 0) {+ summary.push(`${running.length} window${running.length === 1 ? "" : "s"} will empty before ${running.length === 1 ? "it ends" : "they end"}.`);+ }+ summary.push(uncoveredWords === 0+ ? `every word of the Script is drawn over by something that fills the frame (${coverage.words}).`+ : `${uncoveredWords} of ${coverage.words} words are drawn over by nothing that fills the frame.`);+ if (overhang.length > 0) {+ summary.push(`${overhang.length} Frame${overhang.length === 1 ? "" : "s"} `+ + `${overhang.length === 1 ? "reaches" : "reach"} past the Canvas; read each one against the reference.`);+ }+ const compared = elements.filter((element) => element.comparisons > 0).length;+ if (compared > 0 && mode === "reconstruction") {+ summary.push(untimed.length === 0+ ? `every compared element was looked at over a reference-timed stand-in (${compared}).`+ : `${untimed.length} of ${compared} compared elements have comparisons over a stand-in that was not reference-timed.`);+ }+ // On the description route every stand-in is estimate-timed, because `estimate:Speech` is the only+ // clock there is until the Build synthesizes the speech. Reporting that as a shortfall would name+ // every element every time and ask for a re-render against a reference that does not exist, so it+ // is stated once as what it is.+ if (compared > 0 && mode === "description") {+ summary.push(`every ${looking} was made over a stand-in timed by estimate:Speech (${compared}); how each element `+ + "sits against the speech the Build synthesizes is settled once that speech exists.");+ }+ if (unresolved.length > 0) {+ summary.push(`${unresolved.length} imported package${unresolved.length === 1 ? "" : "s"} could not be resolved, `+ + "so nothing is known about what they draw.");+ }+ if (elsewhere > 0) {+ summary.push(`${elsewhere} comparison${elsewhere === 1 ? "" : "s"} in this reference's log compared a render `+ + "outside this project and are not counted here.");+ }+ if (awaiting.length > 0) {+ summary.push(`${awaiting.length} ${looking}${awaiting.length === 1 ? " is" : "s are"} still waiting for `+ + `${mode === "reconstruction" ? "the differences" : "the findings"} to be recorded.`);+ }++ return {+ run: runPath,+ ...(reference === undefined ? {} : { reference_id: reference }),+ plan,+ // Where this command actually read and resolved from. Said here, no document has to describe it+ // from the outside and go stale when it moves.+ roots: mode === "reconstruction"+ ? { reference: preparedRoot, packages: packageRoot }+ : { reviews: logPath, packages: packageRoot },+ passed: owed.length === 0 && never.length === 0 && running.length === 0 && coverage.gaps.length === 0 && unresolved.length === 0,+ summary,+ elements,+ ...(owed.length === 0 ? {} : {+ owed: {+ entries: owed,+ note: `${owed.length} stretch${owed.length === 1 ? "" : "es"} the Source asks for ${owed.length === 1 ? "has" : "have"} `+ + "not been looked at. Each one is an element over a range of the Script's own words, and the reason it is "+ + "here is beside it — a declaration nobody has seen, the longest cue a caption Style has to hold, or a "+ + "window long enough that an animation inside it behaves differently.",+ commands: owed.map((entry) => mode === "reconstruction"+ ? `hypit-reference-video-tools compare_reconstruction --reference-id ${reference} --run ${runPath} `+ + `--tokens ${entry.tokens[0]}:${entry.tokens[1]} --video <rendered clip>.mp4 --element ${entry.element}`+ : `hypit-reference-video-tools review_element --run ${runPath} `+ + `--tokens ${entry.tokens[0]}:${entry.tokens[1]} --video <rendered clip>.mp4 --element ${entry.element} `+ + `--intent-file <what ${entry.element} was asked to be>`),+ },+ }),+ ...(never.length === 0 ? {} : {+ never_compared: {+ ids: never.map((element) => element.id),+ next: mode === "reconstruction"+ ? "Read .agents/skills/hypit/references/element-review.md and "+ + ".agents/skills/hypit/references/reconstruction/comparison-round.md, then for each: "+ + "render the element as the Source configures it, mock the layers a Build has not made, "+ + "and compare the whole stretch blind — one comparison per Segment or Selection it is drawn over."+ : "Read .agents/skills/hypit/references/element-review.md and "+ + ".agents/skills/hypit/references/original-authoring/conformance-round.md, then for each: "+ + "render the element as the Source configures it, mock the layers a Build has not made, "+ + "and have it read against what this element was asked to be — one review per Segment or "+ + "Selection it is drawn over.",+ commands: never.map((element) => mode === "reconstruction"+ ? `hypit-reference-video-tools compare_reconstruction --reference-id ${reference} --run ${runPath} `+ + `--segment <each Segment ${element.id} is drawn over> `+ + `--video <rendered clip>.mp4 --element ${element.id}`+ : `hypit-reference-video-tools review_element --run ${runPath} `+ + `--segment <each Segment ${element.id} is drawn over> `+ + `--video <rendered clip>.mp4 --element ${element.id} --intent-file <what ${element.id} was asked to be>`),+ },+ }),+ ...(awaiting.length === 0 ? {} : {+ awaiting_answer: {+ ids: awaiting.map((entry) => entry.id).filter((id) => id !== undefined),+ elements: [...new Set(awaiting.map((entry) => entry.element).filter((id) => id !== undefined))],+ note: mode === "reconstruction"+ ? `${awaiting.length} comparison${awaiting.length === 1 ? " was" : "s were"} performed and handed to an `+ + "observer that answers out of band, and the differences have not come back. Until they do, the pair has "+ + "been drawn and cut but nobody has said what it shows, so it credits nothing here.\n\n"+ + "Close each one with its id:\n"+ + " hypit-reference-video-tools record_observation --reference-id "+ + `${reference} --key comparison:<id> --text-file <the differences>`+ : `${awaiting.length} review${awaiting.length === 1 ? " was" : "s were"} handed out and the findings have `+ + "not come back. Until they do, the picture has been drawn but nobody has said what it shows, so it "+ + "credits nothing here.\n\n"+ + "Close each one with its id:\n"+ + ` hypit-reference-video-tools record_review --run ${runPath} --review-id <id> --text-file <the findings>`,+ },+ }),+ ...(unresolved.length === 0 ? {} : {+ unresolved_packages: {+ names: unresolved,+ package_root: packageRoot,+ note: `${unresolved.length} package${unresolved.length === 1 ? "" : "s"} the Source imports could not be `+ + `resolved from ${packageRoot}. Whatever they draw is invisible here, so no element of theirs is asked `+ + "for a comparison and this check cannot say the reconstruction is covered.\n\n"+ + "A project that publishes its own packages resolves them from the project root, where "+ + "`packages/<name>/package.json` carries the scoped name. Run the command from that directory, or "+ + "pass --package-root <project directory>.",+ },+ }),+ ...(unknown.length === 0 ? {} : {+ unknown_elements: {+ names: unknown,+ note: `${unknown.length} logged element name${unknown.length === 1 ? " does" : "s do"} not name a drawing `+ + "element in the Source — either the id is not there at all, or it belongs to something that puts no "+ + "picture on the Canvas. Either way the comparison credits nothing, and the element it was meant for "+ + "is still at zero.",+ },+ }),+ ...(unlabelled === 0 ? {} : {+ unlabelled_comparisons: {+ count: unlabelled,+ note: `${unlabelled} comparison${unlabelled === 1 ? " was" : "s were"} recorded without --element and cannot be credited to one.`,+ },+ }),+ // Only where a reference-timed stand-in is reachable. On the description route every stand-in is+ // estimate-timed by definition, so this would list every element and point at a `--reference-id`+ // that does not exist; the summary states that fact once instead.+ ...(untimed.length === 0 || mode === "description" ? {} : {+ timing_next: {+ ids: untimed.map((element) => element.id),+ note: "A stand-in sized by estimate:Speech puts every element where the Source puts it and gives it "+ + "the wrong length of time to be there. Anything whose appearance is a function of elapsed time "+ + "inside its window — a progressive reveal, a typewriter, staggered rows at a fixed rate, an "+ + "enter animation scaled to the window — was therefore compared at a speed the reference never "+ + "ran at, and is unverified. A comparison with no recorded basis says the same thing, because "+ + "nothing on the record says otherwise.\n\n"+ + "Re-render each of these with render_element --reference-id "+ + `${reference} and compare again: the reference's own transcript times every Segment whose words `+ + "it carries, so each window runs for as long as the reference spends on it. What is left after "+ + "that is alignment against the speech the Build synthesizes, which is settled once that "+ + "speech exists.",+ commands: untimed.map((element) =>+ `hypit-reference-video-tools render_element ${runPath} --element ${element.id} `+ + `--reference-id ${reference} --segment <the Segment the shot covers> --out <rendered clip>.mp4`),+ },+ }),+ uncovered: coverage.gaps,+ ...(coverage.gaps.length === 0 ? {} : {+ uncovered_next: "Each stretch listed here shows whatever the placements around it left on screen, and "+ + "beneath the last of them is the Film background, which is black. Read "+ + "playbooks/craft/frame-coverage.md, then claim each stretch with whatever the reference shows "+ + "there: an element bound to the full Frame or to the Canvas, drawn over those words. Placing "+ + "something beneath the stretch instead changes which wrong picture appears and leaves the stretch "+ + "unclaimed.",+ }),+ out_of_bounds: overhang,+ ...(overhang.length === 0 ? {} : {+ out_of_bounds_note: "Each Frame here places part of what is drawn into it off the picture, by the amount "+ + "beside each edge. `outside_fraction` is how much of the Frame's own area lands off the Canvas. This "+ + "is read from the Source's own `space:Canvas` and `space:Frame` arithmetic — no rendered frame is "+ + "measured and no observer is asked.\n\n"+ + "Answer each one: is this overhang intended? Two shapes of it are, and both are visible in the "+ + "Source. An element that travels in from off-screen is outside for part of its window, so its "+ + "Recipe carries the movement — an `enter`, a fly-from origin, an animated offset — and the Frame is "+ + "where it starts rather than where it stays. A full-bleed picture is declared past the edge on "+ + "purpose so a `fit` crops it instead of letterboxing it, so its Recipe carries that `fit`. A Frame "+ + "with neither, holding something the reference shows whole, is placed wrong: the part past the edge "+ + "is the part nobody will see.\n\n"+ + "This decides nothing on its own, because the Source cannot tell the two apart. It is here because "+ + "comparison cannot see it at all: an element authored mostly off the picture is drawn at the Canvas "+ + "the Source declares, and the stand-in it is compared against is drawn at that same Canvas, so both "+ + "put it in the same place off the edge and agree with each other.",+ }),+ playback: running,+ ...(running.length === 0 ? {} : {+ playback_next: "A generated take is ordered in whole seconds and its window is measured from speech the "+ + "Build has yet to synthesize, so the material is shorter than the window it fills more "+ + "often than not. Under a full-frame picture the remainder is the Film background, which "+ + "reads as a black gap; under a cutaway it is the layer beneath blinking through.\n\n"+ + "Give each Recipe listed here a playback: hold-start to pin the last frame for the rest of the "+ + "window, loop-start to repeat, or stretch to retime. Read playbooks/craft/frame-coverage.md "+ + "on inherited edges before choosing — lengthening the material instead leaves the same edge.",+ }),+ };+ }diff --cc packages/reference-video-tools/src/plan.tsindex 00000000,f7abfdb9..ad58bc3dmode 000000,100644..100644--- a/packages/reference-video-tools/src/plan.ts+++ b/packages/reference-video-tools/src/plan.ts@@@ -1,0 -1,561 +1,551 @@@+ /**+ * Which stretches of a program are worth looking at, decided from the Source alone.+ *+ * An element drawn over five Segments does not need five looks. It needs one per way it can fail,+ * and two stretches fail the same way when they are the same declaration over the same kind of+ * content for the same length of time. Deciding that by reading the Source is what makes a round+ * reproducible and what lets the gate ask for coverage rather than for participation.+ *+ * Three rules produce the list, and every one of them reads text:+ *+ * 1. **A distinct declaration is a distinct picture.** Group an element's placements by what they+ * declare and look at each group once, where it first appears. This is also the floor: every+ * placed element has at least one declaration, so every element gets at least one look — which is+ * exactly what the gate required before this file existed.+ * 2. **Content that can break the layout is worth its own look.** Within a group, the stretch+ * holding the most is a different question from the stretch holding the least: a caption system+ * read over its shortest line looks correct, because one line has nothing to collide with.+ * 3. **A window length is worth its own look only when something scales with it.** An enter and an+ * exit happen at the edges for a fixed number of frames; a typewriter, a loop or a `stretch`+ * playback runs for as long as the window does.+ *+ * The unit is a token range rather than a Segment name, because the answer is not always a name. A+ * caption Cue is a run of words the Script never marked, and it is exactly what rule 2 wants to look+ * at. Both sides of a comparison already work in words — `frameOfToken` here, `spokenRange` on the+ * reference — so the range is what they both take, and a name comes along only to be read.+ */+ import { captionDocument, parseScript } from "@hypit/script";+ import type { ParsedNarrative } from "@hypit/script";++ /** One thing to look at: an element, over a range of the Script's words, and why it earned a look. */+ export type PlanEntry = {+ readonly element: string;+ /** Half-open over the Script's speech tokens, the same index space `frameOfToken` is in. */+ readonly tokens: readonly [number, number];+ /** What that range is, for a reader. Never parsed back — the range is the identity. */+ readonly named: string;+ readonly why: readonly string[];+ };++ /** A drawing element as the gate enumerates it, before its placements are read. */+ export type PlannedElement = {+ readonly id: string;+ readonly tag: string;+ readonly alias: string;+ readonly specifier: string;+ };++ /**+ * Attributes that say *when* rather than *what*, so they never join a declaration key.+ *+ * Two placements differing only in these are the same design over different words, which is one+ * look and two stretches — the case rule 1 exists to collapse.+ */+ const WINDOW_ATTRIBUTES = new Set([+ "during", "at", "for", "start", "end", "selection", "segment", "moment", "until",+ "until-boundary", "terminal", "semantic", "document", "narrative", "program-ref",+ ]);++ /**+ * Attributes naming material a Build has not made, so they never join a declaration key either.+ *+ * Every one of these is a flat placeholder in the render this plan is for. Two Items differing only+ * in which unbuilt picture they name draw the identical mock, so looking at both spends a subagent+ * to see the same grey rectangle twice.+ */+ const MOCKED_ATTRIBUTES = new Set(["image", "video", "media", "source", "icon", "audio", "source-audio"]);++ /** Never a declaration: the id is what the key is being computed *for*. */+ const IGNORED_ATTRIBUTES = new Set(["id"]);++ /**+ * Recipe keys whose effect lasts as long as the window does.+ *+ * An `enter` costs its `enter-frames` at one edge whatever the window is; these do not. A window+ * twice as long runs twice as much typewriter, twice as many loop cycles, and stretches its material+ * to twice the duration — so two windows of very different lengths are two questions.+ *- * `caption-fine` publishes the same judgement as machine-readable metadata (`group: "when"`), and- * where that is present it is read instead of this list. This is the fallback for the packages that- * do not yet classify their own properties.++ * This is review policy, not Studio's Where / How / When presentation: a fixed six-frame entrance is++ * a When field but does not scale with the window. Only behaviours whose duration consumes the whole++ * window belong here.+ */+ const WHOLE_WINDOW_KEYS = [+ "sustain", "playback", "playback-future", "playback-past", "trim-start", "trim-end",+ "loop", "loop-target", "loop-period-frames", "loop-intensity",+ "atom-reveal", "karaoke", "karaoke-transition", "active-underline",+ "active-box", "active-box-continuity",+ ];++ type Placement = {+ readonly element: string;+ readonly tag: string;+ readonly key: string;+ readonly stretch: Stretch;+ /** Everything the placement declares, kept so rule 3 can read the Recipes it names. */+ readonly attributes: ReadonlyMap<string, string>;+ };++ type Stretch = {+ readonly tokens: readonly [number, number];+ readonly named: string;+ };++ /** Every attribute on an opening tag, as written. */+ function attributesOf(text: string): ReadonlyMap<string, string> {+ const found = new Map<string, string>();+ for (const match of text.matchAll(/\b([a-z][a-z0-9-]*)="([^"]*)"/gu)) found.set(match[1] ?? "", match[2] ?? "");+ // A reference is written `attr={id}` rather than quoted, and it is the form every Recipe and Frame+ // arrives in, so a key built from quoted attributes alone would miss the whole declaration.+ for (const match of text.matchAll(/\b([a-z][a-z0-9-]*)=\{([^}]*)\}/gu)) found.set(match[1] ?? "", `{${match[2] ?? ""}}`);+ return found;+ }++ /**+ * What this placement declares, as one comparable string.+ *+ * Everything on the tag except the three excluded sets, sorted so attribute order — which this+ * markup does not make significant — cannot split one group into two. The tag name leads, because+ * the same attributes on a different element are a different picture.+ *+ * Taking everything rather than a list of known Recipe attributes is deliberate. `screen-overlay`+ * declares its entire appearance as tag literals and names no Recipe at all, and a package added+ * tomorrow will be read correctly without this file learning its vocabulary. The cost of the wide+ * net is a split group, which is one extra look; the cost of a narrow one is a merged group, which+ * is a picture nobody sees.+ */+ function declarationKey(tag: string, attributes: ReadonlyMap<string, string>): string {+ const parts: string[] = [];+ for (const [name, value] of attributes) {+ if (WINDOW_ATTRIBUTES.has(name) || MOCKED_ATTRIBUTES.has(name) || IGNORED_ATTRIBUTES.has(name)) continue;+ parts.push(`${name}=${value}`);+ }+ return `${tag}|${parts.sort().join("|")}`;+ }++ /** The whole Script, for an element bound to the program rather than to a marked range. */+ function wholeProgram(parsed: ParsedNarrative): Stretch {+ return { tokens: [0, parsed.tokens.length], named: "the whole program" };+ }++ /**+ * Where a placement's `during=` or `at=` puts it, in words.+ *+ * Returns undefined when the binding names something the Script does not mark, which is a Source+ * defect `preview_check` reports rather than something to guess at here.+ */+ function stretchOf(attributes: ReadonlyMap<string, string>, parsed: ParsedNarrative): Stretch | undefined {+ const during = attributes.get("during");+ if (during === "program") return wholeProgram(parsed);++ const named = (value: string | undefined): { readonly kind: string; readonly id: string } | undefined => {+ const match = /^\{story\.(segment|selection|moment)\.([A-Za-z0-9_-]+)\}$/u.exec(value ?? "");+ return match === undefined || match === null ? undefined : { kind: match[1]!, id: match[2]! };+ };++ const bound = named(during) ?? named(attributes.get("at"));+ if (bound === undefined) return undefined;++ if (bound.kind === "segment") {+ const segment = parsed.segments.find((item) => item.id === bound.id);+ return segment === undefined+ ? undefined+ : { tokens: [segment.tokenStart, segment.tokenEndExclusive], named: `segment ${bound.id}` };+ }+ if (bound.kind === "selection") {+ const selection = parsed.selections.find((item) => item.id === bound.id);+ return selection === undefined+ ? undefined+ : {+ tokens: [selection.open.boundary.tokenIndex, selection.close.boundary.tokenIndex],+ named: `selection ${bound.id}`,+ };+ }+ // A Moment is an instant, not a range. What it marks is a change inside whichever Segment holds+ // it, so that Segment is the stretch a look would be rendered over.+ const moment = parsed.moments.find((item) => item.id === bound.id);+ if (moment === undefined) return undefined;+ const index = moment.boundary.tokenIndex;+ const holding = parsed.segments.find((item) => index >= item.tokenStart && index < item.tokenEndExclusive);+ return holding === undefined+ ? undefined+ : { tokens: [holding.tokenStart, holding.tokenEndExclusive], named: `segment ${holding.id} (at moment ${bound.id})` };+ }++ /**+ * The body of one element, so its children can be read.+ *+ * These Tracks do not nest inside themselves, so the first matching close tag is this element's.+ * Returns an empty string for a self-closing element, which has no children to find.+ */+ function bodyOf(svml: string, alias: string, tag: string, id: string): string {+ const opening = new RegExp(`<${alias}:${tag}\\b[^>]*?\\bid="${id}"[^>]*?(/?)>`, "su").exec(svml);+ if (opening === null || opening[1] === "/") return "";+ const after = svml.slice(opening.index + opening[0].length);+ const close = after.indexOf(`</${alias}:${tag}>`);+ return close === -1 ? after : after.slice(0, close);+ }++ /**+ * What an element's own children add to its declaration.+ *+ * A child that binds a window is a placement in its own right and is read as one. A child that does+ * not is part of how its parent looks: `<media-track:Sampling>` is a zoom across the whole window,+ * `<text:Motion>` holds the keyframes, `<caption-fine:Fallback>` names the font to reach for, and a+ * `<P>` or `<Span>` overrides the Style for one run of text. None of them appears on the parent tag,+ * so a key built from attributes alone reads two Items as one design when only one of them animates.+ *+ * Sorted, because the order children are written in is not what they look like.+ */+ function childDeclarations(body: string, parsed: ParsedNarrative): readonly string[] {+ const parts: string[] = [];+ for (const child of body.matchAll(/<([a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*|[A-Z][A-Za-z0-9]*)\b([^>]*?)\/?>/gsu)) {+ const tag = child[1] ?? "";+ const attributes = attributesOf(child[0] ?? "");+ if (stretchOf(attributes, parsed) !== undefined) continue;+ parts.push(declarationKey(tag, attributes));+ }+ return parts.sort();+ }++ /** The opening tag of one element, by id. */+ function openingOf(svml: string, alias: string, tag: string, id: string): string {+ return new RegExp(`<${alias}:${tag}\\b[^>]*?\\bid="${id}"[^>]*?/?>`, "su").exec(svml)?.[0] ?? "";+ }++ /**+ * The Styles a caption Program hands out, and the stretch each one covers.+ *+ * A caption Track is one tag with no window on it — it draws wherever the Script has words — so+ * reading its placements the way every other element is read finds exactly one, and reports one+ * design. That is wrong whenever the Program overrides a Style: `<caption:Use style=… selection=…>`+ * is how one stretch is drawn differently from the rest, and it is written inside the Program rather+ * than on the Track, so nothing on the Track says it happened.+ *+ * Each override is its own declaration over its own words. The default is a declaration too, over+ * whatever the overrides did not claim, which is where the Track's single placement belongs.+ */+ function captionStyles(svml: string, element: PlannedElement, parsed: ParsedNarrative): readonly Placement[] {+ const opening = openingOf(svml, element.alias, element.tag, element.id);+ const program = /\bprogram=\{([A-Za-z0-9_-]+)\}/u.exec(opening)?.[1];+ if (program === undefined) return [];+ const declaring = new RegExp(`<[a-z][a-z0-9-]*:Program\\b[^>]*?\\bid="${program}"[^>]*?(/?)>`, "su").exec(svml);+ if (declaring === null) return [];++ const body = declaring[1] === "/" ? "" : (() => {+ const after = svml.slice(declaring.index + declaring[0].length);+ const close = after.search(/<\/[a-z][a-z0-9-]*:Program>/u);+ return close === -1 ? after : after.slice(0, close);+ })();++ const tag = `${element.alias}:${element.tag}`;+ const found: Placement[] = [];+ for (const use of body.matchAll(/<[a-z][a-z0-9-]*:Use\b([^>]*?)\/?>/gsu)) {+ const attributes = attributesOf(use[0] ?? "");+ // A Use names its stretch with `selection=`, not the `during=` every drawn element uses, because+ // it is assigning a Style to a run of words rather than placing a picture over them.+ const marked = /^\{story\.selection\.([A-Za-z0-9_-]+)\}$/u.exec(attributes.get("selection") ?? "")?.[1];+ const selection = marked === undefined ? undefined : parsed.selections.find((item) => item.id === marked);+ const stretch = selection === undefined+ ? stretchOf(attributes, parsed)+ : {+ tokens: [selection.open.boundary.tokenIndex, selection.close.boundary.tokenIndex] as readonly [number, number],+ named: `selection ${marked}`,+ };+ const style = attributes.get("style");+ if (stretch === undefined || style === undefined) continue;+ found.push({+ element: element.id, tag: `${tag} (caption:Use)`,+ key: `${tag}|style=${style}`, stretch, attributes,+ });+ }+ return found;+ }++ /**+ * Every placement one drawing element makes.+ *+ * A Track holding forty Items draws nothing itself: the Items carry the windows and the Recipes, and+ * they are what a look is actually of. So the element's own tag is a placement only when it binds a+ * window itself, and each child that binds one is a placement too.+ */+ function placementsOf(svml: string, element: PlannedElement, parsed: ParsedNarrative): readonly Placement[] {+ const found: Placement[] = [];+ const opening = openingOf(svml, element.alias, element.tag, element.id);+ const own = attributesOf(opening);+ const body = bodyOf(svml, element.alias, element.tag, element.id);+ const ownKey = [declarationKey(`${element.alias}:${element.tag}`, own), ...childDeclarations(body, parsed)].join("&&");+ const ownStretch = stretchOf(own, parsed);+ if (ownStretch !== undefined) {+ found.push({+ element: element.id, tag: `${element.alias}:${element.tag}`,+ key: ownKey, stretch: ownStretch, attributes: own,+ });+ }++ for (const child of body.matchAll(/<([a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*)\b([^>]*?)(\/?)>/gsu)) {+ const tag = child[1] ?? "";+ const attributes = attributesOf(child[0] ?? "");+ const stretch = stretchOf(attributes, parsed);+ if (stretch === undefined) continue;+ // An Item's own children — its Sampling, its Paint, its inline runs — are part of how it looks.+ const inner = child[3] === "/" ? "" : (() => {+ const after = body.slice((child.index ?? 0) + (child[0]?.length ?? 0));+ const close = after.indexOf(`</${tag}>`);+ return close === -1 ? "" : after.slice(0, close);+ })();+ // The child's own declaration is what it draws, but it sits inside the Track's, so the Track's+ // is part of the key: the same Item under two Tracks with different Canvases is two pictures.+ found.push({+ element: element.id,+ tag,+ key: `${ownKey}>>${[declarationKey(tag, attributes), ...childDeclarations(inner, parsed)].join("&&")}`,+ stretch,+ attributes,+ });+ }++ // An element that binds no window anywhere is on screen for the whole program — a persistent+ // badge, a Film-wide treatment — and the whole program is the stretch it is looked at over.+ if (found.length === 0) {+ found.push({+ element: element.id,+ tag: `${element.alias}:${element.tag}`,+ key: ownKey,+ stretch: wholeProgram(parsed),+ attributes: own,+ });+ }+ return found;+ }++ /**+ * Rule 2, for captions: where the longest Cue is.+ *+ * A Cue is the unit a caption's layout can break on, and it is not a Segment. Four things end one,+ * and only one of them is the `||` the author wrote: the other three are a Segment ending, a speaker+ * changing, and a Style changing. Partitioning on the authored breaks alone reads a two-speaker+ * script as a handful of enormous Cues, and then reports the longest line as the whole exchange.+ *+ * The units come from `captionDocument`, and each one carries the speech tokens it corresponds to.+ * That mapping is what makes the answer a range of the Script's own words rather than a guess: a Dual+ * Text alias is one indivisible unit spanning its whole region, and reading its display words back+ * against the speech by counting would land in the wrong place.+ *+ * `temporalizeCaptionDocument` groups on the same four facts, but it needs a SemanticTrack to assign+ * frames and this check never builds one. Only the grouping is repeated here; the frames it would+ * have assigned are not something anything on this path asks for.+ */+ function longestCue(+ parsed: ParsedNarrative,+ styleBoundaries: ReadonlySet<number>,- svmlPath: string,++ narrativeId: string,+ ): Stretch | undefined {+ let document;- try { document = captionDocument(parsed, "captions"); } catch { return undefined; }++ try { document = captionDocument(parsed, "captions", narrativeId); } catch { return undefined; }+ if (document.units.length === 0) return undefined;++ const tokenIndex = new Map(parsed.tokens.map((token, index) => [token.id, index] as const));+ const spanOf = (unit: typeof document.units[number]): { readonly from: number; readonly to: number } | undefined => {+ const indexes = unit.sourceTokenIds.flatMap((id) => {+ const at = tokenIndex.get(id);+ return at === undefined ? [] : [at];+ });+ return indexes.length === 0 ? undefined : { from: Math.min(...indexes), to: Math.max(...indexes) + 1 };+ };++ const breaks = new Set(document.cueBreaks.map((cueBreak) => cueBreak.afterUnitId));+ let current: { from: number; to: number; characters: number } | undefined;+ let previous: typeof document.units[number] | undefined;+ let best: { from: number; to: number; characters: number } | undefined;+ const close = (): void => {+ if (current !== undefined && (best === undefined || current.characters > best.characters)) best = current;+ };++ for (const unit of document.units) {+ const span = spanOf(unit);+ if (span === undefined) continue;+ const characters = unit.wordIds.length === 0+ ? 0+ : document.words.filter((word) => word.unitId === unit.id).reduce((sum, word) => sum + word.text.length, 0);+ // The same four things that end a Cue: a Segment ends, the speaker changes, the Style changes, or+ // the author wrote one. The first two are on the unit; the third is where a `caption:Use` starts+ // or stops; the fourth is the document's own list.+ const ended = previous !== undefined && (+ previous.segmentId !== unit.segmentId+ || previous.turnId !== unit.turnId+ || breaks.has(previous.id)+ || styleBoundaries.has(span.from));+ if (current === undefined || ended) { close(); current = { ...span, characters }; }+ else { current = { from: current.from, to: span.to, characters: current.characters + characters }; }+ previous = unit;+ }+ close();+ if (best === undefined) return undefined;++ const holding = parsed.segments.find((item) => best!.from >= item.tokenStart && best!.from < item.tokenEndExclusive);+ return {+ tokens: [best.from, best.to],+ named: holding === undefined ? "the longest cue" : `the longest cue, in segment ${holding.id}`,+ };+ }++ /**+ * Where a `caption:Program` changes Style, in token space.+ *+ * `<caption:Use selection=…>` is how one stretch is drawn differently from the rest, and it is the+ * only place a caption's declaration varies — the Track's own tag is identical over the whole+ * program. Both ends of the named Selection are Cue boundaries, because a Style change ends a Cue.+ */+ function captionStyleBoundaries(svml: string, parsed: ParsedNarrative): ReadonlySet<number> {+ const found = new Set<number>();+ for (const use of svml.matchAll(/<[a-z][a-z0-9-]*:(?:Use|Mute)\b([^>]*?)\/?>/gsu)) {+ const selection = /\bselection=\{story\.selection\.([A-Za-z0-9_-]+)\}/u.exec(use[1] ?? "")?.[1];+ if (selection === undefined) continue;+ const marked = parsed.selections.find((item) => item.id === selection);+ if (marked === undefined) continue;+ found.add(marked.open.boundary.tokenIndex);+ found.add(marked.close.boundary.tokenIndex);+ }+ return found;+ }++ /**+ * Rule 2, for anything holding a list: which stretch holds the most of it.+ *+ * Items are written into the Source as children, each bound to its own Moment or Selection, so the+ * count per stretch is a count of children — no rendering and no measurement. The stretch holding+ * the most is where the layout has the most chance to run out of room.+ */+ function fullestStretch(placements: readonly Placement[]): Stretch | undefined {+ const counts = new Map<string, { readonly stretch: Stretch; count: number }>();+ for (const placement of placements) {+ const key = `${placement.stretch.tokens[0]}-${placement.stretch.tokens[1]}`;+ const held = counts.get(key);+ if (held === undefined) counts.set(key, { stretch: placement.stretch, count: 1 });+ else held.count += 1;+ }+ const ranked = [...counts.values()].sort((one, other) => other.count - one.count);+ const most = ranked[0];+ // One each is not a list. Nominating a stretch here would just re-name what rule 1 already has.+ return most === undefined || most.count < 2 ? undefined : most.stretch;+ }++ /**+ * Rule 3: does anything about this element's appearance run for as long as its window does?+ *- * `caption-fine` classifies its own properties, so where a Recipe body carries a key that package- * marked `when`, that is the authority. Everything else is matched against the list above, which is- * the same judgement made by hand for the packages that do not publish one yet.++ * This is deliberately narrower than Inspector's `when` page: an edge animation belongs on that++ * page but does not make a longer window a different animation sample.+ */-function scalesWithWindow(bodies: readonly string[], published: ReadonlySet<string>): boolean {- const keys = [...new Set([...published, ...WHOLE_WINDOW_KEYS])];- return bodies.some((body) => keys.some((key) => new RegExp(`\\b${key}\\s*:`, "u").test(body)));++function scalesWithWindow(bodies: readonly string[]): boolean {++ return bodies.some((body) => WHOLE_WINDOW_KEYS.some((key) => new RegExp(`\\b${key}\\s*:`, "u").test(body)));+ }++ /** The Recipe bodies one placement's declaration names, so rule 3 can read their keys. */+ function recipeBodiesOf(attributes: ReadonlyMap<string, string>, recipes: ReadonlyMap<string, string>): readonly string[] {+ const bodies: string[] = [];+ for (const [name, value] of attributes) {+ if (WINDOW_ATTRIBUTES.has(name) || MOCKED_ATTRIBUTES.has(name)) continue;+ const named = /^\{([A-Za-z0-9_.-]+)\}$/u.exec(value)?.[1];+ if (named === undefined) continue;+ const body = recipes.get(named.replace(/^recipes\./u, ""));+ if (body !== undefined) bodies.push(body);+ }+ return bodies;+ }++ /** Rule 1: one look per distinct declaration, at the stretch where that declaration first appears. */+ function firstOfEachDeclaration(placements: readonly Placement[]): readonly PlanEntry[] {+ const seen = new Set<string>();+ const entries: PlanEntry[] = [];+ for (const placement of placements) {+ if (seen.has(placement.key)) continue;+ seen.add(placement.key);+ entries.push({+ element: placement.element,+ tokens: placement.stretch.tokens,+ named: placement.stretch.named,+ why: [`first use of this declaration (${placement.tag})`],+ });+ }+ return entries;+ }++ /**+ * Merge nominations that landed on the same thing.+ *+ * Three rules can each name one stretch — the first occurrence of a Style may also hold its longest+ * line and its longest window — and that is one look with three reasons, not three looks.+ */+ function merge(entries: readonly PlanEntry[]): readonly PlanEntry[] {+ const byKey = new Map<string, PlanEntry>();+ for (const entry of entries) {+ const key = `${entry.element}+ const held = byKey.get(key);+ if (held === undefined) { byKey.set(key, entry); continue; }+ byKey.set(key, { ...held, why: [...held.why, ...entry.why.filter((reason) => !held.why.includes(reason))] });+ }+ return [...byKey.values()];+ }++ /** What a round has to look at, for one Source. */+ export function reviewPlan(input: {+ readonly svml: string;+ readonly svmlPath: string;- readonly scriptBody: { readonly text: string; readonly offset: number };++ readonly scriptBody: { readonly id: string; readonly text: string; readonly offset: number };+ readonly drawn: readonly PlannedElement[];+ /** Recipe bodies by their sheet-local name, for rule 3. Absent means rule 3 nominates nothing. */+ readonly recipes?: ReadonlyMap<string, string>;- /**- * Property names the packages themselves marked time-varying, read from their own vocabulary.- *- * A package that classifies its properties is the authority on them, and it stays right as it adds- * more. The list in this file is the fallback for the packages that publish no classification.- */- readonly timeVaryingKeys?: ReadonlySet<string>;+ }): readonly PlanEntry[] {+ const parsed = parseScript(input.svmlPath, input.scriptBody.text, input.scriptBody.offset);+ const recipes = input.recipes ?? new Map<string, string>();- const published = input.timeVaryingKeys ?? new Set<string>();+ const styleBoundaries = captionStyleBoundaries(input.svml, parsed);+ const entries: PlanEntry[] = [];++ for (const element of input.drawn) {+ // A caption Track's designs are declared inside its Program, not on the Track, so they are read+ // separately and joined to whatever the ordinary placement scan found.+ const placements = [+ ...placementsOf(input.svml, element, parsed),+ ...(element.specifier.includes("caption") ? captionStyles(input.svml, element, parsed) : []),+ ];+ entries.push(...firstOfEachDeclaration(placements));++ // Rule 2. A caption's layout breaks on a Cue, and a list's breaks on how many items one stretch+ // holds; every other element draws one thing and has no content extreme to find.+ if (element.specifier.includes("caption")) {- const cue = longestCue(parsed, styleBoundaries, input.svmlPath);++ const cue = longestCue(parsed, styleBoundaries, input.scriptBody.id);+ if (cue !== undefined) entries.push({ element: element.id, tokens: cue.tokens, named: cue.named, why: ["longest cue"] });+ }+ const fullest = fullestStretch(placements);+ if (fullest !== undefined) {+ entries.push({ element: element.id, tokens: fullest.tokens, named: fullest.named, why: ["most items in one stretch"] });+ }++ // Rule 3. Only where something runs for as long as the window does, and only then are the+ // longest and the shortest two different questions rather than the same picture twice.- const animates = placements.some((placement) => scalesWithWindow(recipeBodiesOf(placement.attributes, recipes), published));++ const animates = placements.some((placement) => scalesWithWindow(recipeBodiesOf(placement.attributes, recipes)));+ if (animates && placements.length > 1) {+ const byLength = [...placements].sort((one, other) =>+ (one.stretch.tokens[1] - one.stretch.tokens[0]) - (other.stretch.tokens[1] - other.stretch.tokens[0]));+ const shortest = byLength[0]!;+ const longest = byLength.at(-1)!;+ if (longest.stretch.tokens[1] - longest.stretch.tokens[0] !== shortest.stretch.tokens[1] - shortest.stretch.tokens[0]) {+ entries.push({ element: element.id, tokens: longest.stretch.tokens, named: longest.stretch.named, why: ["longest window, and this element animates across it"] });+ entries.push({ element: element.id, tokens: shortest.stretch.tokens, named: shortest.stretch.named, why: ["shortest window, and this element animates across it"] });+ }+ }+ }+ return merge(entries);+ }++ export { WHOLE_WINDOW_KEYS };diff --cc packages/reference-video-tools/src/tools.tsindex a3c59d63,56673881..084104ae--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@@ -1,7 -1,12 +1,11 @@@import type { Part } from "@google/genai";- import { access, readdir, stat, writeFile } from "node:fs/promises";- import { join, resolve } from "node:path";+ import { access, appendFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";+ import { spawn } from "node:child_process";+ import { cpus } from "node:os";+ import { createHash } from "node:crypto";+ import { deflateSync } from "node:zlib";+ import { basename, dirname, join, resolve } from "node:path";-import { createRequire } from "node:module";-import { loadNodePackageSelection } from "@hypit/package-loader-node";+import { loadNodePackageSelection, locateNodePackage } from "@hypit/package-loader-node";import { markupSurfaceHostFacetAbi } from "@hypit/markup";import type { RegisteredSurface, SurfaceVocabulary } from "@hypit/markup";import { exactModelHostAbi } from "@hypit/model-kit";diff --cc packages/studio/package.jsonindex c7fe91e2,5a3f385d..295c9500--- a/packages/studio/package.json+++ b/packages/studio/package.json@@@ -5,11 -5,10 +5,12 @@@"type": "module","exports": {"./start": "./start.ts",- "./preview-check": "./preview-check.ts"+ "./preview-check": "./preview-check.ts",+ "./src/*": "./src/*"},"dependencies": {+ "@hypit/audio-track-studio": "workspace:*",+ "@hypit/caption-fine-studio": "workspace:*","@hypit/cli": "workspace:*","@hypit/compiler-node": "workspace:*","@hypit/component-kit": "workspace:*",