Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(reference-video-tools): gate a reconstruction on the comparisons it never made
rponee066a930cebe
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.mdindex 1701c04f..5d6fb05d 100644--- a/.agents/skills/hypit/references/local-author-package.md+++ b/.agents/skills/hypit/references/local-author-package.md@@ -103,6 +103,14 @@ Implement the parts required by the behavior, including:- lowering, Fragment or renderer implementation needed to produce the declared output;- README and a preview for each visual Surface.+The README opens with the gap this package exists to fill, in one sentence naming the installed+package that came closest, the property it does not carry, and what the reference needs instead —+"`media-track` clips a Frame square or rounded, and the reference's player is a circle." The+enumeration `../vocabulary.md` requires happened before the first line of code was written; without+that sentence it survives nowhere, and the next reader cannot tell a proven gap from an assumed one.+A package whose README cannot state its gap that concretely is usually a package that did not need to+exist.+Choose raw versus structured Surface, timing dependencies, ProgramSpace, Frame, SemanticTrack,Artifact, Recipe and output Types from the observed behavior and closest package architecture. Adeclaration-only or Surface-only package is incomplete.@@ -165,6 +173,13 @@ nothing.is most of its life.- A component that cannot render on its own cannot produce the preview image its Surface owes. Treata missing preview as evidence of this mistake rather than a step to skip.+- **The render harness takes its state as arguments.** The Surface preview is one picture: every+ feature on, at whatever moment shows the component best. `reconstruction-loop.md` needs a different+ picture for every reference shot — the state that shot happens to show, at a matching moment — and+ a component appears across several. A harness with its state and frame written into it produces the+ catalogue picture and nothing else, and the next agent reuses that picture for a comparison it does+ not fit. Give it `--out`, the frame, and whichever of the component's own switches the reference+ varies; the preview then becomes one invocation of it rather than its only purpose.## Freeze the Types before writing in paralleldiff --git a/.agents/skills/hypit/references/reconstruction/continuity.md b/.agents/skills/hypit/references/reconstruction/continuity.mdindex 896be43d..e62e3324 100644--- a/.agents/skills/hypit/references/reconstruction/continuity.md+++ b/.agents/skills/hypit/references/reconstruction/continuity.md@@ -24,6 +24,27 @@ These invariants override superficial layer order and shot boundaries:Shot boundaries are observation windows, not authoring units. Never generate independent SVML pershot and concatenate it afterward.+## Their seconds are not authoring units either++The shot list arrives as a table of `start_seconds` and `end_seconds`, and copying those numbers into+the Source as `start="3.25s" end="7.42s"` is the shortest path from the evidence to a placement. It+produces a reconstruction that is wrong the moment it is built.++Those seconds describe the reference's own clock, and nothing in the reconstruction runs on that+clock. Every take is generated, comes back at whatever length the model returned, and the+SemanticTrack is built from the words WhisperX finds inside it. An Item bound to 3.25 seconds points+at whichever word happens to land there, which is not the word the number was copied from. One take+returning half a second long moves every window after it.++Bind covering content to a Script Selection over the words it covers — mark the range in the Script,+pass `semantic={speech.semantic}` to the Track, and use `during={story.selection.NAME}` — and let the+projection resolve the frames. The reference's seconds then decide *which words* a Selection spans,+which is what they can honestly tell you, rather than which frame an Item starts on.++Explicit `start`/`end` is for a program with no speech to anchor to. `../playbooks/craft/b-roll.md`+states the same rule from the authoring side, and reads it as a deliberate choice rather than a+transcription.+## A system that spans shots is authored once- A visual system that persists across cuts — captions, a running list that keeps its state, adiff --git a/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.mdindex a540337e..0c66415a 100644--- a/.agents/skills/hypit/references/reconstruction/index.md+++ b/.agents/skills/hypit/references/reconstruction/index.md@@ -173,7 +173,23 @@ Two more are required, at the point where they apply rather than now. Reading threading them half an hour before they matter, with a dozen other files in between:- `final-sources.md` when the components exist and the sources are about to be written.-- `reconstruction-loop.md` when something has been built and is about to be compared.+- `reconstruction-loop.md` **the first time any element is rendered to a still** — including the+ preview a new package owes its Surface. No Build is submitted on this route, so a trigger worded+ around one never fires: the picture that gets compared is a local render, and the moment one+ exists the loop applies.++This route ends on a command rather than on a judgement that the work looks done. Every element a+project-local package draws must have been compared against the reference at least once, and that is+checkable:++```text+node --import tsx .agents/skills/hypit/scripts/reconstruction-check.mjs projects/<name>/build.svrun+```++It names each element that has never been compared and the command that compares it, and exits+non-zero until none are left. It asks for participation rather than convergence — `reconstruction-loop.md`+is deliberately bounded and may stop with visible differences remaining — so an element compared once+and stopped at its ceiling passes, and an element nobody looked at does not.Paths above are relative to this file's directory. Do not skip a file because the task looks like afamiliar video format.diff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.mdindex 318877de..db8fbdf8 100644--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md+++ b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md@@ -108,6 +108,12 @@ return a difference every round for ever. So the loop ends on whichever of these- **Every attempt aims at a difference the comparison named.** Changing something the comparison didnot mention is not an attempt; it is thrashing, and it does not earn one of the attempts below.+- **A difference caused by an input that does not exist yet is not a repair target.** This route+ declares its generation rather than performing it, so a component's media slots are empty for the+ whole stretch between being written and being built. The comparison sees that and names it every+ round — an empty card where the reference shows a screenshot. Do not aim an attempt at it, and do+ not read its reappearance as the no-progress rule below firing: that rule is about the difference+ the repair was aimed at, not about every line the comparison returns.- **No progress ends it immediately.** If a comparison returns the same difference it returned beforethe repair, stop. The repair is not reaching the problem, and two more rounds of the same reasoningwill not find it. Rendering and comparing cost real time on every round.@@ -147,7 +153,29 @@ comparison to name what remains. Do not spend one to find out — a comparison tand exists only to report the gap is a paid step for a report nobody asked for. The element is whatit is; move on to the next one.-When there is no next element the reconstruction is complete, and two things follow it.+When there is no next element the reconstruction is complete, and three things follow it.++## Say what this route did not verify++"Complete" here means every element was compared and every loop stopped. It does not mean the video+was watched, because on this route no video exists: the Build has not run. Report the difference+rather than letting the word carry it.++State plainly, in the completion report, that the following are unverified and name the gate each one+waits for in `../playbooks/craft/production-gates.md`:++- **every generated picture and take** — the images and the shots a Provider has still to make, at+ Gate 1 and Gate 2;+- **the authored values on installed vocabulary** — a caption Style's size, colour and placement, a+ Media Item's frame, a Typography Track's copy, at Gate 3 against the real SemanticTrack;+- **whether the picture is continuous** — the black stretches and the frames nobody authored that+ `frame-coverage.md` is about, at Gate 4, which measures them on the delivery;+- **whether the delivery says the Script's words** — measured at Gate 4 by transcribing the finished+ video, since a take generated from a prompt that lost its dialogue passes every gate before it.++`reconstruction-check` is the mechanical half of this: it names the elements that were never compared+and refuses to pass while any remain. It cannot name what a Build has not produced yet, which is why+this list is stated rather than computed.If the author wants the result to differ from the reference — their presenter, their product, theirbrand — read the sources you wrote and change them to what they asked for. `index.md` says why thatdiff --git a/.agents/skills/hypit/references/reconstruction/workflow.md b/.agents/skills/hypit/references/reconstruction/workflow.mdindex e74ee90b..e40d3252 100644--- a/.agents/skills/hypit/references/reconstruction/workflow.md+++ b/.agents/skills/hypit/references/reconstruction/workflow.md@@ -7,7 +7,7 @@ and belong to this route:hypit-reference-video-tools prepare_reference --video-path <path> --observer gemini|agenthypit-reference-video-tools observe_reference --reference-id <reference-id>hypit-reference-video-tools record_observation --reference-id <reference-id> --key <key> --text-file <path>-hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --shot-id <shot-id> --image <path>+hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --shot-id <shot-id> --image <path> [--element <id>]````--observer` is answered once, before anything runs, and `observers.md` owns that question.@@ -35,6 +35,8 @@ list_svml_packagesthis has no attempt ceiling; a target Studio cannot trace is not done.Waiting on unrun Providers is a pass, not a failure→ read reconstruction-loop.md, then render each authored element and compare it+→ run reconstruction-check (index.md) and keep going until it passes; it names+ every locally-drawn element that has never been compared```## prepare_reference@@ -158,6 +160,11 @@ and returns a description of their visible differences. It is never told which iwas built, or how; `--question` may narrow it to one region of the picture and nothing else. Resultsare not cached. `reconstruction-loop.md` governs when and how to use it.+`--element` names the reconstructed element the image draws. It never reaches the observer — the+comparison stays as blind as it is without it — and is written to the reference's `comparisons.jsonl`+so `reconstruction-check` can tell an element that was looked at from one that never was. A+comparison run without it is not credited to any element.+The reference has one observer for its whole life, and this command goes through the same one thatwrote its observations. On the `gemini` observer that observer is not you, and opening the referenceframe yourself is what `reconstruction-loop.md` forbids; on the `agent` observer it is you, and thatdiff --git a/.agents/skills/hypit/scripts/reconstruction-check.mjs b/.agents/skills/hypit/scripts/reconstruction-check.mjsnew file mode 100644index 00000000..31be00c5--- /dev/null+++ b/.agents/skills/hypit/scripts/reconstruction-check.mjs@@ -0,0 +1,179 @@+#!/usr/bin/env node+/**+ * Report which reconstructed elements have never been compared against the reference.+ *+ * `preview-check` proves the graph is wired. It proves nothing about whether what the graph draws+ * resembles the reference video, and a Source can pass every structural check while a+ * project-local component draws something the reference never contained. Closing that gap is+ * `references/reconstruction/reconstruction-loop.md`, which is prose, and prose is what a route+ * skips silently. This is the same requirement as a command with an exit code.+ *+ * Usage: node --import tsx .agents/skills/hypit/scripts/reconstruction-check.mjs <build.svrun> [--reference-id <id>]+ * Exit: 0 when every locally-drawn element has at least one recorded comparison.+ * 1 when one or more have none, naming each and the command that compares it.+ * 2 on a usage or discovery error.+ *+ * What it checks is **participation, not convergence**. The loop 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.+ *+ * Only elements drawn by a `@hypit/local-*` package are required. Installed vocabulary is already+ * reviewed; a package written for this one video is the thing with no other reader.+ */+import { readFile, readdir } from "node:fs/promises";+import { dirname, join, resolve } from "node:path";++const packageLoader = new URL("../../../../packages/package-loader-node/src/index.ts", import.meta.url).href;+const { loadNodePackageSelection } = await import(packageLoader);++const runArgument = process.argv[2];+if (runArgument === undefined || runArgument.startsWith("--")) {+ console.error("usage: reconstruction-check.mjs <build.svrun> [--reference-id <id>]");+ process.exit(2);+}+const flagIndex = process.argv.indexOf("--reference-id");+const suppliedReference = flagIndex === -1 ? undefined : process.argv[flagIndex + 1];++const invokedFrom = process.env.INIT_CWD ?? process.cwd();+const runPath = resolve(invokedFrom, runArgument);+const packageRoot = resolve(invokedFrom);++function fail(message) {+ console.error(`reconstruction-check: ${message}`);+ process.exit(2);+}++const runSource = await readFile(runPath, "utf8").catch(() => fail(`cannot read ${runPath}`));+const authorMatch = /<author\s+source="([^"]+)"/u.exec(runSource);+if (authorMatch === null) fail(`${runArgument} declares no <author source="…"/>`);+const svmlPath = resolve(dirname(runPath), authorMatch[1]);+const svml = await readFile(svmlPath, "utf8").catch(() => fail(`cannot read ${svmlPath}`));++// Every package this Source imports, and which of them were written for this project.+const imports = [...svml.matchAll(/<import\s+as="([^"]+)"\s+from="(@hypit\/[^"@]+)@\d+"/gu)]+ .map(([, alias, specifier]) => ({ alias, specifier, local: specifier.startsWith("@hypit/local-") }));+if (imports.length === 0) {+ console.log("reconstruction-check: the Source imports no package; nothing to compare.");+ process.exit(0);+}++// 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))];+const loaded = await loadNodePackageSelection(specifiers, packageRoot).catch(() => []);+const drawingTags = new Map();+for (const pack of loaded) {+ for (const facet of pack.contribution.hostFacets ?? []) {+ const surface = facet.implementation;+ const draws = (surface.outputs ?? []).some((output) =>+ output.module?.name === "@hypit/composition" && (output.name === "VisualTrack" || output.name === "AudioTrack"));+ if (draws) drawingTags.set(`${pack.specifier}#${surface.tag}`, true);+ }+}++// Every use of one of those tags, by the id the Source gave it.+const drawn = [];+for (const { alias, specifier, local } of imports) {+ const pattern = new RegExp(`<${alias}:([A-Za-z][A-Za-z0-9]*)\\b[^>]*?\\bid="([^"]+)"`, "gu");+ for (const [, tag, id] of svml.matchAll(pattern)) {+ if (!drawingTags.has(`${specifier}#${tag}`)) continue;+ if (!drawn.some((item) => item.id === id)) drawn.push({ id, tag, alias, specifier, local });+ }+}++// A project-local package is required here: it was written for this one video and nothing else has+// read it. A Track from installed vocabulary carries authored values too — a caption Style's size,+// colour and placement are as unverified as a new package's — but it cannot be rendered before a+// Build without a fixture SemanticTrack, so it is reported rather than demanded.+const elements = drawn.filter((item) => item.local);+const deferred = drawn.filter((item) => !item.local);+if (elements.length === 0) {+ console.log("reconstruction-check: no locally-drawn element is placed in the Source; nothing to require.");+ if (deferred.length > 0) reportDeferred();+ process.exit(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.+const referenceRoot = join(packageRoot, ".hypit", "reference-video-tools");+const prepared = (await readdir(referenceRoot, { withFileTypes: true }).catch(() => []))+ .filter((entry) => entry.isDirectory()).map((entry) => entry.name);+let reference = suppliedReference;+if (reference === undefined) {+ if (prepared.length === 1) reference = prepared[0];+ else if (prepared.length === 0) fail(`no prepared reference under ${referenceRoot}; run prepare_reference first`);+ else fail(`${prepared.length} prepared references; pass --reference-id (${prepared.join(", ")})`);+}+if (!prepared.includes(reference)) fail(`reference ${reference} is not prepared under ${referenceRoot}`);++const logPath = join(referenceRoot, reference, "comparisons.jsonl");+const log = (await readFile(logPath, "utf8").catch(() => ""))+ .split("\n").filter((line) => line.trim().length > 0)+ .map((line) => { try { return JSON.parse(line); } catch { return undefined; } })+ .filter((entry) => entry !== undefined && entry.status === "complete");++// Which shots each element was compared against, in order. The gate cannot judge whether a shot was+// the right one to compare against — it does not know what the element draws — so it prints them and+// lets a reader notice a component compared against a shot that never showed it.+const rounds = new Map();+for (const entry of log) {+ if (entry.element === undefined) continue;+ const seen = rounds.get(entry.element) ?? [];+ seen.push(entry.shot_id);+ rounds.set(entry.element, seen);+}++const never = elements.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)))];++for (const element of elements) {+ const shots = rounds.get(element.id) ?? [];+ const state = shots.length === 0+ ? "never compared"+ : `${shots.length} comparison${shots.length === 1 ? "" : "s"} against ${[...new Set(shots)].join(", ")}`;+ console.log(` ${element.alias}:${element.tag} id=${element.id}\n ${state}`);+}++function reportDeferred() {+ console.log("");+ console.log(` ${deferred.length} Track${deferred.length === 1 ? "" : "s"} from installed vocabulary carry authored values this gate does not require:`);+ for (const item of deferred) console.log(` ${item.alias}:${item.tag} id=${item.id}`);+ console.log(" Their Styles, placements and windows are as unauthored-until-checked as a new package's,");+ console.log(" and none of them renders before a Build without a fixture SemanticTrack. They are checked");+ console.log(" against the delivery under playbooks/craft/production-gates.md Gate 3 and Gate 4.");+}++if (unknown.length > 0) {+ console.log("");+ console.log(` ${unknown.length} logged element name${unknown.length === 1 ? " does" : "s do"} not exist in the Source: ${unknown.join(", ")}`);+ console.log(" A misspelled --element credits nothing; the element it was meant for is still at zero.");+}+if (unlabelled > 0) {+ console.log("");+ console.log(` ${unlabelled} comparison${unlabelled === 1 ? " was" : "s were"} recorded without --element and cannot be credited to one.`);+}+if (deferred.length > 0) reportDeferred();++if (never.length === 0) {+ console.log("");+ console.log(`reconstruction-check: every locally-drawn element has been compared (${elements.length}).`);+ process.exit(0);+}++console.log("");+console.log(`reconstruction-check: ${never.length} of ${elements.length} elements have never been compared.`);+console.log("");+console.log("Read .claude/skills/hypit/references/reconstruction/reconstruction-loop.md, then for each:");+console.log("render the element to a still in the state the reference shot shows, and compare it blind.");+console.log("");+for (const element of never) {+ console.log(` hypit-reference-video-tools compare_reconstruction --reference-id ${reference} \\`);+ console.log(` --shot-id <the shot that shows ${element.id} most clearly> \\`);+ console.log(` --image <rendered still>.png --element ${element.id}`);+}+process.exit(1);diff --git a/package.json b/package.jsonindex ea5c0bf3..0c326795 100644--- a/package.json+++ b/package.json@@ -53,12 +53,11 @@"@hypit/hyperframes": "workspace:*","@hypit/image-compose": "workspace:*","@hypit/image-transform": "workspace:*",- "@hypit/runtime-local": "workspace:*","@hypit/media": "workspace:*",- "@hypit/media-track": "workspace:*","@hypit/media-pipeline": "workspace:*",- "@hypit/minimax-h3": "workspace:*",+ "@hypit/media-track": "workspace:*","@hypit/mimo-tts": "workspace:*",+ "@hypit/minimax-h3": "workspace:*","@hypit/nano-banana": "workspace:*","@hypit/narrative": "workspace:*","@hypit/program-space": "workspace:*",@@ -76,8 +75,9 @@"@hypit/raster": "workspace:*","@hypit/render-hyperframes": "workspace:*","@hypit/run-markup": "workspace:*",- "@hypit/runtime-kit": "workspace:*","@hypit/runtime-host-node": "workspace:*",+ "@hypit/runtime-kit": "workspace:*",+ "@hypit/runtime-local": "workspace:*","@hypit/screen-overlay": "workspace:*","@hypit/script": "workspace:*","@hypit/seedance": "workspace:*",diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.tsindex 3ec452aa..bf431427 100644--- a/packages/reference-video-tools/src/cli.ts+++ b/packages/reference-video-tools/src/cli.ts@@ -14,7 +14,11 @@ function usage(): string {" hypit-reference-video-tools observe_reference --reference-id <id> --shot-id <id> [--shot-id <id> ...] --question <text>"," hypit-reference-video-tools record_observation --reference-id <id> --key <key> --text <text>|--text-file <path>"," hypit-reference-video-tools inspect_svml_vocabulary --package <name> [--package <name> ...] [--tag <tag> ...] [--without-previews]",- " hypit-reference-video-tools compare_reconstruction --reference-id <id> --shot-id <id> --image <path> [--question <scope>]",+ " hypit-reference-video-tools compare_reconstruction --reference-id <id> --shot-id <id> --image <path> [--question <scope>] [--element <id>]",+ "",+ "--element names the reconstructed element the image draws. It is written to the reference's",+ "comparison log and never sent to the observer, so the comparison stays blind while a later gate can",+ "still tell which elements have been compared.","","--observer picks who reads the reference, once per reference. `gemini` uploads video to Vertex and","needs GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS_JSON. `agent` needs no credentials: it",@@ -123,8 +127,9 @@ async function main(): Promise<void> {shot_id: required(flags, "shot-id"),image_path: required(flags, "image"),...(one(flags, "question") === undefined ? {} : { question: one(flags, "question") }),+ ...(one(flags, "element") === undefined ? {} : { element: one(flags, "element") }),};- result = await tools.compare_reconstruction(input as { reference_id: string; shot_id: string; image_path: string; question?: string });+ result = await tools.compare_reconstruction(input as { reference_id: string; shot_id: string; image_path: string; question?: string; element?: string });} else if (command === "inspect_svml_vocabulary") {const packages = many(flags, "package");const input = supplied ?? {diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 18f43822..a0b0fac9 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -1,6 +1,7 @@import { GoogleGenAI } from "@google/genai";import type { Part } from "@google/genai";-import { access, readdir, stat, writeFile } from "node:fs/promises";+import { access, appendFile, readdir, readFile, stat, writeFile } from "node:fs/promises";+import { createHash } from "node:crypto";import { dirname, join, resolve } from "node:path";import { createRequire } from "node:module";import { loadNodePackageSelection } from "@hypit/package-loader-node";@@ -47,6 +48,12 @@ export type CompareReconstructionInput = {readonly shot_id: string;readonly image_path: string;readonly question?: string;+ /**+ * Names the reconstructed element this image draws, for the comparison log only. It is never sent+ * to the observer: the comparison stays blind, and this is what lets a later gate tell which+ * elements have been compared and which have never been looked at.+ */+ readonly element?: string;};export type ReferenceVideoTools = {@@ -85,6 +92,26 @@ function stateRoot(workspaceRoot: string, reference: string): string {return join(workspaceRoot, ".hypit", "reference-video-tools", reference);}+/** One line per comparison performed, appended so a stopped loop still leaves its trail. */+export type ComparisonRecord = {+ readonly at: string;+ readonly shot_id: string;+ readonly element?: string;+ readonly image_path: string;+ readonly image_digest: string;+ readonly observer: Observer;+ readonly status: Observation["status"];+ readonly scoped: boolean;+};++async function fileDigest(path: string): Promise<string> {+ return `sha256:${createHash("sha256").update(await readFile(path)).digest("hex")}`;+}++async function appendComparison(root: string, record: ComparisonRecord): Promise<void> {+ await appendFile(join(root, "comparisons.jsonl"), `${JSON.stringify(record)}\n`, "utf8");+}+async function defaultGenerate(model: string): Promise<GenerateText> {const project = process.env.GOOGLE_CLOUD_PROJECT?.trim();const credentials = process.env.GOOGLE_APPLICATION_CREDENTIALS_JSON?.trim();@@ -695,6 +722,20 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVinstruction: "You compare two supplied still images and describe their visible differences in natural language only. You are not told how either image was made. Do not write code, markup, SVML, component names, or production advice.",prompt: `Two still images are supplied in order: image one, then image two.${scope.length === 0 ? "" : `\n\nLimit the comparison to this part of the picture: ${scope}`}\n\nDescribe every visible difference between them: layout and arrangement, the position and size of each element, cropping and margins, colour, typeface, weight, letter and line spacing, alignment, outline or stroke, shadow, glow, borders and corner treatment, and anything present in one image and absent from the other. State plainly which differences are large enough to read as a different design and which are minor. If they are visually equivalent, say exactly that.\n\nDo not speculate about how either image was produced, which one is a source, or which one is a copy. Return natural language only.`,});+ // The answer is deliberately not cached — every iteration is a fresh comparison. What is+ // recorded is that a comparison happened, so a gate can tell an element that was looked at+ // from one that never was. The loop is allowed to stop with differences remaining, so this+ // records participation rather than convergence.+ await appendComparison(stateRoot(workspaceRoot, state.reference_id), {+ at: new Date().toISOString(),+ shot_id: shot.shot_id,+ ...(input.element === undefined ? {} : { element: input.element.trim() }),+ image_path: imagePath,+ image_digest: await fileDigest(imagePath),+ observer,+ status: differences.status,+ scoped: scope.length > 0,+ });return {reference_id: state.reference_id,observer,