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
fix(reference-video-tools): repair the audit findings on the comparison gate
rponee057293d7a04
diff --git a/.agents/skills/hypit/references/authoring.md b/.agents/skills/hypit/references/authoring.mdindex 9b82242f..ee45ee0e 100644--- a/.agents/skills/hypit/references/authoring.md+++ b/.agents/skills/hypit/references/authoring.md@@ -10,13 +10,15 @@ place. For `@hypit/<name>@1`, the repository README is `packages/<name>/README.mcomponent, attribute, child, port, Recipe property or literal value. Do not infer one package'ssyntax from a neighboring package.-Install dependencies after package selections change. Validate with the existing commands:+Install dependencies after package selections change. Validate with the existing commands, run from+the repository root:```bashpnpm checkpnpm hypit check path/to/main.svmlpnpm hypit check path/to/recipes.svspnpm hypit check path/to/build.svrun+node --import tsx .agents/skills/hypit/scripts/preview-check.mjs path/to/build.svrun```Check all of them, not only the Author Source: a Recipe the Author Source references and a Target the@@ -25,7 +27,9 @@ Run Source demands are just as able to be wrong. Do not create a check wrapper.**A check that passes is not a graph that traces.** `hypit check` proves a Source is legal — itssyntax, its references, its graph structure — and proves nothing about whether the tracks it declarescan actually be built, nor that an uncertain requirement was understood correctly. `preview.md`-proves the Run traces, before any Provider is reached.+proves the Run traces, before any Provider is reached — which is why the last command above, the+preview-check, is part of validating a Run and not a later step. Run it from the repository root:+`tsx` is the repository's own dependency, so a working directory outside it fails to resolve it.This file is about writing an element correctly, which is a narrower question than making the videoright. What a Track should contain, when a picture may be generated at all, how long a thing stays ondiff --git a/.agents/skills/hypit/references/credentials.md b/.agents/skills/hypit/references/credentials.mdindex 61c2c496..086cebd0 100644--- a/.agents/skills/hypit/references/credentials.md+++ b/.agents/skills/hypit/references/credentials.md@@ -43,7 +43,8 @@ $env:GOOGLE_APPLICATION_CREDENTIALS_JSON = Get-Content -Raw "$HOME\.config\hypitKeep keys outside Author/Run/Runtime source and committed files. Verify presence without printingvalues with, for example,`node .agents/skills/hypit/scripts/check-credentials.mjs KIE_API_KEY MIMO_API_KEY`, then run-`hypit doctor <profile>`.+`hypit doctor` (once a Runtime Profile is selected with `hypit runtime use hypit.runtime.json`;+doctor audits the selected profile, so it needs no profile argument of its own).## A changed credential does not reach a running Workerdiff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.mdindex 90e98bed..e528847c 100644--- a/.agents/skills/hypit/references/environment.md+++ b/.agents/skills/hypit/references/environment.md@@ -64,6 +64,13 @@ pnpm checkpnpm test```+`npm link` links the `hypit` binary. The route also calls `hypit-reference-video-tools`+(`prepare_reference`, `observe_reference`, `compare_reconstruction`, `list_svml_packages`,+`inspect_svml_vocabulary`) — a separate bin that the repository links on `pnpm install`, so it is+present once the workspace install above has run. If `hypit-reference-video-tools` is not on `PATH`+after installing, re-run `pnpm install` from the repository root; the bin resolves from+`packages/reference-video-tools/bin/`.+For managed local programs:```textdiff --git a/.agents/skills/hypit/references/playbooks/craft/seedance-directing.md b/.agents/skills/hypit/references/playbooks/craft/seedance-directing.mdindex ac0be627..fbfadb80 100644--- a/.agents/skills/hypit/references/playbooks/craft/seedance-directing.md+++ b/.agents/skills/hypit/references/playbooks/craft/seedance-directing.md@@ -38,9 +38,10 @@ than relying on an unstated assumption.of them are regenerated more than once, so the tier multiplies the whole bill for a difference thatcosts more to find than it is worth. Take an instruction to use a particular model literally whenone is given, and otherwise never raise the tier and never stop to ask which to use.-- The other values are `fast`, `standard` and `2.5`. `mini` and `fast` support only 480p/720p;- `standard` also supports 1080p/4k, which is the one reason to name it — a delivery that genuinely- requires 1080p, recorded as the deliberate choice it is.+- The other values are `fast`, `standard` and `2.5`. `mini`, `fast` and `2.5` all render at 480p or+ 720p only; `standard` alone also supports 1080p/4k, which is the one reason to name it — a delivery+ that genuinely requires 1080p, recorded as the deliberate choice it is. What `2.5` buys is+ duration and reference capacity, not resolution.- Keep duration an integer inside the selected model's declared range, and read that range from themodel rather than from memory: they differ, and one accepts far longer takes than the others.Invalid values fail closed.diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex 43bbfe7f..4c43cd8d 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -52,6 +52,24 @@ without a paid Provider. A new package's visual Surface needs a preview image anown visual test `packages/hyperframes/test/browser-visual.test.ts` shows the path end to end: buildthe Track, compile the HyperFrames document, and render it through the local HyperFrames Runtime.+There is no one command for the still: a package's `test/render-preview.ts` harness is what renders+it, and `local-author-package.md` requires that harness to take its state, frame and output path as+arguments. That requirement exists because the still has two distinct jobs that must not collapse+into one picture:++- the **Surface preview** — one catalogue image, every feature on, whatever moment shows the+ component best, for Studio and the package README;+- the **comparison still** — for `reconstruction-loop.md`, one picture per reference shot, showing+ the element in the state that shot happens to show at a matching moment.++A harness whose state is written into it produces the first and nothing else; the route then reuses+that catalogue picture for a comparison it does not fit. So the still render is one invocation of a+parameterised harness, not the whole of it.++One case where a still render is the wrong tool: an element whose appearance depends on a media slot+a Build has not filled — the comparison would report the empty slot every round, which+`reconstruction-loop.md` says is not a repair target. Render only the parts the element draws itself.+This is the image to reach for whenever one element has to be looked at rather than the wholeprogram. Rendering the delivery to inspect a single piece is the waste it exists to prevent.diff --git a/.agents/skills/hypit/references/quickstart.md b/.agents/skills/hypit/references/quickstart.mdindex 16db5b2a..f89e10f6 100644--- a/.agents/skills/hypit/references/quickstart.md+++ b/.agents/skills/hypit/references/quickstart.md@@ -1,6 +1,8 @@# Quickstart map-The repository docs are authoritative:+The repository docs are authoritative. Imports pin the physical version: an element is written as+`<import as="tag" from="@hypit/<name>@1"/>`, and the `@1` is the Module version, not a range to+loosen. The repository docs and package READMEs describe the `@1` vocabulary.| Need | Read ||---|---|diff --git a/.agents/skills/hypit/references/reconstruction/final-sources.md b/.agents/skills/hypit/references/reconstruction/final-sources.mdindex 908e2018..f30665f1 100644--- a/.agents/skills/hypit/references/reconstruction/final-sources.md+++ b/.agents/skills/hypit/references/reconstruction/final-sources.md@@ -57,4 +57,7 @@ Fix package resolution and package implementation before repairing source use. Cthree files are accepted. Do not create `check_svml_project` or another wrapper.Accepted checks end the structural work, not the reconstruction. Every element you authored still has-to be rendered and compared against the reference under `reconstruction-loop.md`.+to be rendered and compared against the reference under `reconstruction-loop.md`, and that work ends+on `reconstruction-check` (`index.md` holds the command), which refuses to pass while any+locally-drawn element has never been compared. It needs a prepared reference; when several are+prepared it takes `--reference-id <id>`.diff --git a/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.mdindex 0c66415a..83f3989e 100644--- a/.agents/skills/hypit/references/reconstruction/index.md+++ b/.agents/skills/hypit/references/reconstruction/index.md@@ -114,7 +114,10 @@ set -a && source .env && set +a`prepare_reference` and the full `observe_reference` sweep take several minutes and need none of theknowledge below: their prompts are fixed, and nothing you are about to read changes what they ask.Start them first and read while they run. Reading first and observing afterwards makes the same run-several minutes longer for nothing.+several minutes longer for nothing. This is not the whole command order — `workflow.md` names the+sequence — it is specifically that the observation sweep must not wait on the reading. `list_svml_packages`+is an instant directory read that runs independently at the step the sequence names; it neither+delays the sweep nor is delayed by it.```bashhypit-reference-video-tools prepare_reference --video-path <path> --observer <chosen> # about a minute@@ -191,5 +194,17 @@ non-zero until none are left. It asks for participation rather than convergenceis deliberately bounded and may stop with visible differences remaining — so an element compared onceand stopped at its ceiling passes, and an element nobody looked at does not.+The script uses a prepared reference, and how it picks which one is worth knowing before it is run:++- exactly one reference is prepared → it uses that one;+- several are prepared → it demands `--reference-id <id>`, and without it exits 2;+- none → it exits 2 telling you to run `prepare_reference` first.++A comparison run without `--element` is not credited to any element, and a misspelled `--element`+credits nothing either — the script reports logged element names that do not exist in the Source. A+project that places no `@hypit/local-*` element passes with nothing to require: the Tracks that+installed vocabulary draws carry authored values this gate does not demand (none renders before a+Build), and they are listed as deferred rather than required, to be checked at the delivery gates.+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 db8fbdf8..4eae5704 100644--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md+++ b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md@@ -43,9 +43,18 @@ card:Surface needs a preview image anyway, as `../local-author-package.md` requires. The repository'sown visual test `packages/hyperframes/test/browser-visual.test.ts` shows the local path end toend: build the Track, compile the HyperFrames document, and render it through the local- HyperFrames Runtime.+ HyperFrames Runtime. The still must show the element in the state the shot below shows, which is+ what `local-author-package.md`'s "the render harness takes its state as arguments" exists for:+ the catalogue preview is one invocation of it, not the whole of it.2. Compare it against the reference frame that shows it most clearly:- `.hypit/reference-video-tools/<reference-id>/shots/NNN-representative.jpg`.+ `.hypit/reference-video-tools/<reference-id>/shots/NNN-representative.jpg`. The shot is a choice,+ and the wrong one is invisible to the comparison gate, which only records that a comparison+ happened. Pick the shot where the element is the clearest thing on screen — a caption system+ against a frame that shows the caption, a card against a frame that shows the card — and pass+ `--element <id>` so the gate credits it to that element. When a shot shows the element in+ different states across several frames, pick the one that matches the state you rendered; when+ the reference's own observation of that shot describes the element, use that description to+ confirm the choice.3. Repair, then render again.### One observer reads the reference, and it is the one the reference was prepared with@@ -147,6 +156,12 @@ shows it most clearly returns a measurement in one step, from whichever observerDo that instead of spending an attempt. An attempt is for differences that have no number — atypeface's character, a texture, a rhythm — where the only route is change it and look again.+Measure against the frame, not against the screen it is viewed on. A quantity read off a rendered+still means what it means relative to that still's own width and height — a stroke that is "one+percent of the frame height", a shape "a third of the frame width" — which is the same basis the+Recipe's fractions use. Saying "a little too tall" and changing it on feel spends the attempt the+measurement exists to save.+Stopping is the end, and the end carries no final comparison. When the attempts are spent the loopstops as it is: the second repair is the last thing the observer saw, and there is no thirdcomparison to name what remains. Do not spend one to find out — a comparison that changes nothingdiff --git a/.agents/skills/hypit/references/reconstruction/workflow.md b/.agents/skills/hypit/references/reconstruction/workflow.mdindex e40d3252..82338b72 100644--- a/.agents/skills/hypit/references/reconstruction/workflow.md+++ b/.agents/skills/hypit/references/reconstruction/workflow.md@@ -12,11 +12,14 @@ hypit-reference-video-tools compare_reconstruction --reference-id <reference-id>`--observer` is answered once, before anything runs, and `observers.md` owns that question.`record_observation` is how the `agent` observer returns an answer; on the `gemini` observer the tool-writes its own and the command is unused.+writes its own and the command is unused. A long answer arrives whole with `--text-file <path>`;+`--text <text>` suits a short one.The other two — `list_svml_packages` and `inspect_svml_vocabulary` — read installed vocabulary andhave nothing to do with a reference video. This route runs both, at the step the sequence names;-`../vocabulary.md` documents them and decides how a package is chosen.+`../vocabulary.md` documents them and decides how a package is chosen. `list_svml_packages` reads+`node_modules/@hypit` relative to the working directory and refuses when it is empty, so run it from+the repository root.Defaults are sufficient for normal use. Each also accepts `--input <json>`. Follow this sequence:@@ -24,7 +27,9 @@ Defaults are sufficient for normal use. Each also accepts `--input <json>`. Folllist_svml_packages→ prepare_reference→ observe_reference for all shots, in the background — read the route's required- files while it runs, since its prompts do not depend on anything you read+ files while it runs, since its prompts do not depend on anything you read.+ `index.md`'s "start the evidence before you read" is this line, not the whole+ order: `list_svml_packages` is instant and may run before or during the sweep→ narrow observe_reference questions for unresolved appearance and conflicts→ inspect_svml_vocabulary for candidate packages→ develop a project-local package only for a proven vocabulary gap@@ -36,7 +41,8 @@ list_svml_packagesWaiting 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+ every locally-drawn element that has never been compared. When more than one+ reference is prepared it needs --reference-id <id>```## prepare_referencediff --git a/.agents/skills/hypit/references/vocabulary.md b/.agents/skills/hypit/references/vocabulary.mdindex c5138cc6..9ff420a0 100644--- a/.agents/skills/hypit/references/vocabulary.md+++ b/.agents/skills/hypit/references/vocabulary.md@@ -10,7 +10,7 @@ First enumerate every system the program actually contains — base pictures, infull-screen graphic compositions, persistent overlays, captions, speech, music, sound effects — andinspect candidates for each one. **A system you never inspected is a system you are about to invent.**-Then, for each: select candidate packages and run `inspect_svml_vocabulary`. Read each selected+Then, for each: select candidate packages and run `hypit-reference-video-tools inspect_svml_vocabulary`. Read each selectedpackage README as syntax authority. Compare what the element must be against declared inputs,outputs, attributes, children, ports, Recipe properties, timing behavior, appearance and examples.@@ -47,6 +47,13 @@ hypit-reference-video-tools inspect_svml_vocabulary --package @hypit/<name> [--pnamed packages is returned. The README remains the syntax authority; this reports what the loaderwill actually accept, which is what a mistaken attribute is checked against.+Both commands print one JSON object to stdout. `list_svml_packages` is an array of+`{ package_name, tags, models }`; `inspect_svml_vocabulary` returns `{ packages, surfaces }` where+each Surface carries `tag`, `mode`, `outputs`, `vocabulary` (its `attributes`, `children`, `ports`,+`recipe` properties and `preview`) and `readme_path`. Read the `accepts` lists on attributes — that+is the declared Type an element must satisfy, and a property with nowhere to land in those lists is+the finding that makes a gap.+## Reuse, compose, or declare a gapUse this decision order:@@ -99,7 +106,7 @@ it deliberately and writes it down.## A real gapFor a real gap, stop authoring sources and read `local-author-package.md` completely. Implement and-install the new project-local package, then run `inspect_svml_vocabulary` against it before using its+install the new project-local package, then run `hypit-reference-video-tools inspect_svml_vocabulary` against it before using itstag. That call is not redundant with having just written the package: it proves the specifierresolves, the activation contribution is wired, and the loader can decode the Surface. `pnpm check`proves none of those, because activation lookups fail at runtime rather than at compile time.diff --git a/.agents/skills/hypit/scripts/reconstruction-check.mjs b/.agents/skills/hypit/scripts/reconstruction-check.mjsindex 31be00c5..82d719bd 100644--- a/.agents/skills/hypit/scripts/reconstruction-check.mjs+++ b/.agents/skills/hypit/scripts/reconstruction-check.mjs@@ -20,6 +20,16 @@** 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.+ *+ * A comparison counts whether its answer came back in-band (`complete`, the gemini observer) or was+ * handed out to be answered by looking (`pending`, the agent observer); only `failed` is not a+ * comparison. The gate cannot judge whether the shot an element was compared against actually showed+ * it, so the shots are printed for a reader, and a lone comparison is called out rather than assumed+ * meaningful.+ *+ * A project that places no locally-drawn element passes with nothing to require — installed-vocabulary+ * Tracks are listed as deferred rather than demanded, since none renders before a Build without a+ * fixture SemanticTrack.*/import { readFile, readdir } from "node:fs/promises";import { dirname, join, resolve } from "node:path";@@ -111,7 +121,10 @@ 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");+ // A comparison counts when it was performed. On the gemini observer the answer comes back in-band+ // as `complete`; on the agent observer it is handed out as `pending` and answered by looking at the+ // images, which is participation too. Only `failed` means nothing was compared.+ .filter((entry) => entry !== undefined && (entry.status === "complete" || entry.status === "pending"));// 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@@ -137,6 +150,11 @@ for (const element of elements) {? "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}`);+ // The gate cannot judge whether the shot chosen actually showed the element, so a lone comparison+ // is called out for a reader to confirm rather than silently accepted.+ if (shots.length === 1) {+ console.log(" (single comparison — confirm this shot shows the element, not a look-alike)");+ }}function reportDeferred() {