Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

merge: integrate main reconstruction tooling

kashorin75c4f61be9b4
diff --cc packages/caption-fine/src/render.ts
index ba46bfb9,fcc59534..a7b3cb3e
--- a/packages/caption-fine/src/render.ts
+++ b/packages/caption-fine/src/render.ts
@@@ -597,13 -594,20 +609,26 @@@ function cueElements
const 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.ts
index f1b0bf3f,07c67e17..c8409181
--- a/packages/hyperframes/src/text.ts
+++ b/packages/hyperframes/src/text.ts
@@@ -237,7 -257,12 +238,12 @@@ function documentGlyphPaintLayers(eleme
append(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.ts
index 8e20c37a,56f651ad..5f398bad
--- a/packages/markup/src/types.ts
+++ b/packages/markup/src/types.ts
@@@ -132,10 -126,19 +132,11 @@@ export type SurfaceRecipePropertyVocabu
readonly 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.ts
index 00000000,0dc55964..584a6315
mode 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.ts
index 00000000,bd8ad0ba..c2a1ae7a
mode 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.ts
index 00000000,f7abfdb9..ad58bc3d
mode 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.ts
index 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.json
index 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:*",