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: remove the friction a reconstruction run actually paid for (#63)
rponeawae2e64d8a8eff
diff --git a/.agents/skills/hypit/references/reconstruction/observers.md b/.agents/skills/hypit/references/reconstruction/observers.mdindex a43a80ef..f2129b1d 100644--- a/.agents/skills/hypit/references/reconstruction/observers.md+++ b/.agents/skills/hypit/references/reconstruction/observers.md@@ -161,6 +161,10 @@ A clip comparison reaches this observer as two frame tiles — the reference's ofrom the render against the same duration, both drawn at the same cell width. Read them as a pair ofgrids sampling the same stretch at the same rate.+The pair is always sent in one order: **one is the reference, two is the render.** The observer is not+told that and must not be; you need it, because a difference reported "in one" is a difference in the+reference and one "in two" is something to repair. Read the answer with that in hand.+### Record the differences against the comparison that asked for them`compare_reconstruction` returns a `comparison_id`, and the answer goes back under it:diff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.mdindex e81c2e14..7c821312 100644--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md+++ b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md@@ -55,7 +55,7 @@ One command produces it, and it is not written per package:```hypit-reference-video-tools render_element projects/<name>/build.svrun \- --element <id> --segment <id>|--selection <id> --out <path>.mp4+ --element <id> --segment <id>|--selection <id> --reference-id <id> --out <path>.mp4````--element` takes the element's bare id — `captions`, the `id=` the Source wrote on the element. The@@ -63,10 +63,17 @@ command appends the output suffix itself when it looks for the track, so `--elemmatches nothing: it refuses with `the Source places no element named captions.track` and lists thebare ids that are placed.-It reads the Canvas, the Recipe values and the Script text out of the Source, stands in for the-speech with the Source's own `estimate:Speech`, mocks every layer a Build has not made, and drives-the package's Producer. Nothing is transcribed by hand, so nothing is transcribed one line at a time-— which is what made a caption system look correct while its lines collided.+It reads the Canvas, the Recipe values and the Script text out of the Source, mocks every layer a+Build has not made, and drives the package's Producer. Nothing is transcribed by hand, so nothing is+transcribed one line at a time — which is what made a caption system look correct while its lines+collided.++`--reference-id` names the reference, and it times the stand-in from that reference's own transcript,+so each Segment runs for as long as the reference spends on its words. Pass it every time: the+comparison cuts both sides to the same words and refuses a pair whose two halves are different+lengths, and only this clock puts the render on the reference's. It is also what lets anything whose+appearance is a function of elapsed time — a progressive reveal, a typewriter, staggered rows — be+compared at the speed it will be seen at.The window is named in words. `--segment` and `--selection` take a Script name, never a timestamp:name the Segment or the Selection the element is drawn over, and give the same name to thediff --git a/.agents/skills/hypit/references/vocabulary.md b/.agents/skills/hypit/references/vocabulary.mdindex 3211c9b1..2da26d60 100644--- a/.agents/skills/hypit/references/vocabulary.md+++ b/.agents/skills/hypit/references/vocabulary.md@@ -49,10 +49,13 @@ will 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.+each Surface carries `package_name`, `module`, `surface`, `tag`, `mode`, `outputs`, `readme_path` and+`vocabulary` — whose own keys are `summary`, `attributes`, `children`, `example` and `notes`. **The+Recipe properties are inside the `recipe` attribute**, at `vocabulary.attributes[name=recipe].recipe`,+one entry per property; there is no `recipe` key beside `attributes`. A Surface re-exported from+another package carries no `vocabulary` at all — follow its `module` to the one that declares it. 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.**That output is the complete authoring contract. Author from it, and do not read a package's sourcecode to learn an element's syntax.** Every recipe property carries its own `summary` and its admitteddiff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.mdindex 984690a4..66582628 100644--- a/docs/quickstart/composition.md+++ b/docs/quickstart/composition.md@@ -238,7 +238,6 @@ width and is rejected.exit: fade; exit-frames: 4; exit-easing: ease-in;}caption.base {- cue-min-words: 1; cue-max-words: 5;stack-order: 70; x: 0.08; y: 0.76; width: 0.84;size: 58; line-height: 1; align: center;fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.mdindex 00bc95ea..35fe9cab 100644--- a/docs/quickstart/styles.md+++ b/docs/quickstart/styles.md@@ -72,8 +72,6 @@ The first official Caption Style family keeps planning and rendering parameters```svscaption.dialogue {- cue-min-words: 2;- cue-max-words: 7;stack-order: 70;x: 0.08;y: 0.76;@@ -90,7 +88,6 @@ caption.dialogue {| Property | Description ||---|---|-| `cue-min-words`, `cue-max-words` | Common Cue word-count bounds || `stack-order` | Z-stacking order among all Tracks (higher = on top) || `x`, `y` | Position as fraction of canvas (0–1) || `width` | Width as fraction of canvas |@@ -117,7 +114,6 @@ Define multiple caption Recipes for different speakers:```svscaption.alice {- cue-min-words: 2; cue-max-words: 5;stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;@@ -127,7 +123,6 @@ caption.alice {}caption.bob {- cue-min-words: 2; cue-max-words: 5;stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;@@ -144,7 +139,7 @@ Then assign them via `caption:Program`:<caption-fine:Style id="default-caption" recipe={recipes.caption.dialogue} font={caption-font}/><caption-fine:Style id="alice-caption" recipe={recipes.caption.alice} font={caption-font}/><caption-fine:Style id="bob-caption" recipe={recipes.caption.bob} font={caption-font}/>-<caption:Program id="caption-program" display={story.caption} default={default-caption}>+<caption:Program id="caption-program" document={story.caption} default={default-caption}><caption:Use role="ALICE" style={alice-caption}/><caption:Use role="BOB" style={bob-caption}/></caption:Program>@@ -421,8 +416,6 @@ A complete `recipes.svs` file for a four-take talking-head project:}caption.primary {- cue-min-words: 2;- cue-max-words: 5;stack-order: 70;x: 0.08;y: 0.74;diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.mdindex e9564f36..06b428b6 100644--- a/docs/zh/quickstart/composition.md+++ b/docs/zh/quickstart/composition.md@@ -232,7 +232,6 @@ Build Target,也可以直接接到媒体裁切、音频/帧提取或模型参exit: fade; exit-frames: 4; exit-easing: ease-in;}caption.base {- cue-min-words: 1; cue-max-words: 5;stack-order: 70; x: 0.08; y: 0.76; width: 0.84;size: 58; line-height: 1; align: center;fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.mdindex cd264f21..ee5f5d50 100644--- a/docs/zh/quickstart/styles.md+++ b/docs/zh/quickstart/styles.md@@ -68,8 +68,6 @@ film.vertical {```svscaption.dialogue {- cue-min-words: 2;- cue-max-words: 7;stack-order: 70;x: 0.08;y: 0.76;@@ -86,7 +84,6 @@ caption.dialogue {| 属性 | 描述 ||---|---|-| `cue-min-words`、`cue-max-words` | 通用 Cue 字数边界 || `stack-order` | 所有 Track 之间的 Z 轴层叠顺序(值越大越靠前) || `x`、`y` | 位置,以画布比例表示(0–1) || `width` | 宽度,以画布比例表示 |@@ -113,7 +110,6 @@ Style。字体家族、字重和字形只在这条精确字体边上声明一次```svscaption.alice {- cue-min-words: 2; cue-max-words: 5;stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;@@ -123,7 +119,6 @@ caption.alice {}caption.bob {- cue-min-words: 2; cue-max-words: 5;stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;@@ -140,7 +135,7 @@ caption.bob {<caption-fine:Style id="default-caption" recipe={recipes.caption.dialogue} font={caption-font}/><caption-fine:Style id="alice-caption" recipe={recipes.caption.alice} font={caption-font}/><caption-fine:Style id="bob-caption" recipe={recipes.caption.bob} font={caption-font}/>-<caption:Program id="caption-program" display={story.caption} default={default-caption}>+<caption:Program id="caption-program" document={story.caption} default={default-caption}><caption:Use role="ALICE" style={alice-caption}/><caption:Use role="BOB" style={bob-caption}/></caption:Program>@@ -398,8 +393,6 @@ Caption Recipe 不再重复家族、字重或字形。CJK 与 Emoji 即使由多}caption.primary {- cue-min-words: 2;- cue-max-words: 5;stack-order: 70;x: 0.08;y: 0.74;diff --git a/packages/composition/src/track.ts b/packages/composition/src/track.tsindex 4c5c946c..925c9aba 100644--- a/packages/composition/src/track.ts+++ b/packages/composition/src/track.ts@@ -340,6 +340,12 @@ export type VisualSurfaceElement = VisualElementBase & {** Elements may reference only parents in the same Present. They have no selector,* script, sibling Track id or accumulated-composite input.+ *+ * A Present holds exactly one root; everything else names a `parent`, which has to be a box or a+ * mask. **Position is measured from that parent, not from the Canvas.** A component that computes+ * its layout in Canvas pixels and then nests its elements has to subtract the parent's own origin,+ * or every child lands offset by it — which draws without complaint and is wrong by exactly the+ * distance the parent sits from the corner.*/export type VisualElement = VisualBoxElement | VisualMaskElement | VisualTextElement | VisualTextFlowElement | VisualPathTextElement | VisualMediaElement | VisualSurfaceElement;diff --git a/packages/media-track/src/manifest.ts b/packages/media-track/src/manifest.tsindex 647f3fdf..10e80ea7 100644--- a/packages/media-track/src/manifest.ts+++ b/packages/media-track/src/manifest.ts@@ -397,7 +397,7 @@ export const mediaTrackMarkupSurfaces = [{{ name: "surface", kind: "reference", required: false, accepts: [mediaTypes.compositableSurface],summary: "Shows an alpha-aware still or timed Surface." },{ name: "extent", kind: "reference", required: false, accepts: [spatialTypes.extent],- summary: "Gives the still image its authored pixel Extent." },+ summary: "Gives the still image its authored pixel Extent. The `fit` scales this Extent into the Frame, so what it decides is the shape: its width-to-height ratio has to be the picture's, and the pixel numbers themselves only have to hold that ratio. A generated picture's own size is the generator's to choose and is not knowable when the Source is written, so write the ratio you asked that generator for." },{ name: "audio", kind: "literal", required: false, values: ["include", "omit"],summary: "Decides whether a raw `video` source contributes its own audio; defaults to `omit`." },{ name: "source-audio", kind: "literal", required: false,diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.tsindex 543286d3..2bcd31f0 100644--- a/packages/reference-video-tools/src/authoring.ts+++ b/packages/reference-video-tools/src/authoring.ts@@ -141,7 +141,7 @@ function repositoryRoot(): string {* 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.*/-function nearestPackageRoot(start: string): string | undefined {+export function nearestPackageRoot(start: string): string | undefined {let directory = resolve(start);while (true) {if (existsSync(join(directory, "package.json"))) return directory;diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.tsindex 4131792e..fbcabe39 100644--- a/packages/reference-video-tools/src/checks.ts+++ b/packages/reference-video-tools/src/checks.ts@@ -14,7 +14,7 @@ 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, referenceRoot, scriptBody } from "./authoring.js";+import { aliasPattern, invokedFrom, nearestPackageRoot, referenceRoot, scriptBody } from "./authoring.js";import { assert, round } from "./media.js";export type PreviewCheckInput = {@@ -52,7 +52,7 @@ export async function previewCheck(const cwd = invokedFrom();const runPath = resolve(cwd, input.run);const runtimePath = input.runtime === undefined ? undefined : resolve(cwd, input.runtime);- const packageRoot = roots.packageRoot;+ const packageRoot = nearestPackageRoot(dirname(runPath)) ?? roots.packageRoot;const workspaceRoot = dirname(runPath);const distributionPackageRoot = videoCliDistribution.packageRoot;@@ -477,7 +477,12 @@ export async function reconstructionCheck(): Promise<Record<string, unknown>> {const cwd = invokedFrom();const runPath = resolve(cwd, input.run);- const packageRoot = roots.packageRoot;+ // 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}`);diff --git a/packages/reference-video-tools/src/placeholder.ts b/packages/reference-video-tools/src/placeholder.tsindex f394759a..cc0b24e9 100644--- a/packages/reference-video-tools/src/placeholder.ts+++ b/packages/reference-video-tools/src/placeholder.ts@@ -80,7 +80,12 @@ function resolvePlaceholderColor(value: string | undefined): PlaceholderPalettefunction placeholderPng(width: number, height: number, palette: PlaceholderPalette): Uint8Array {const { base, border } = palette;const raw = Buffer.alloc(height * (1 + width * 3));- const margin = Math.max(2, Math.round(Math.min(width, height) * 0.05));+ // A hairline, not a band. At a twentieth of the shorter side the frame was fifty pixels thick on a+ // full-frame mock, and an observer measuring what the element covers read that as the element+ // stopping short of the edge — "does not span the full width", reported every round, about the+ // mock rather than about anything the Source says. It has to be visible enough to read as a slot+ // and thin enough to measure as nothing.+ const margin = Math.max(1, Math.round(Math.min(width, height) * 0.004));for (let y = 0; y < height; y += 1) {raw[y * (1 + width * 3)] = 0;for (let x = 0; x < width; x += 1) {diff --git a/packages/reference-video-tools/src/slice.ts b/packages/reference-video-tools/src/slice.tsindex b962af3a..1e747183 100644--- a/packages/reference-video-tools/src/slice.ts+++ b/packages/reference-video-tools/src/slice.ts@@ -120,6 +120,27 @@ export function sliceSource(source: string, segment: string): SliceResult {alive.add(`moment.${match[1]!}`);}+ // Which Script names are marked after the kept Segment ends.+ //+ // A name outside the cut is not always a name the element can do without. An element given the span+ // it occupies and a Moment to cut it — `during="program" until={story.moment.done}` — is on screen+ // for the whole of any stretch that ends before that word. Dropping it made the one element a+ // reference is about unrenderable over every Segment but the last, while the loop asks for it to be+ // compared over each of them. Marked before the cut it really is gone, and marked inside it survives+ // already, so this is the one case: a close that has not arrived yet, which the fragment reaches by+ // no longer closing.+ const later = new Set<string>();+ for (const match of body.slice(kept.index + kept[0].length).matchAll(/@([a-z][a-z0-9-]*)\b/gu)) {+ later.add(`selection.${match[1]!}`);+ later.add(`moment.${match[1]!}`);+ }+ /** The `until=` attribute naming a name the cut left behind, when dropping it is enough. */+ const closesLater = (tag: string, name: string): string | undefined => {+ if (!later.has(name)) return undefined;+ const written = new RegExp(`\\suntil=\\{story\\.(?:[a-z]+\\.)*?${name.replace(".", "\\.")}\\}`, "u").exec(tag);+ return written?.[0];+ };+const skip: (readonly [number, number])[] = [[bodyStart, bodyEnd]];for (const comment of source.matchAll(/<!--.*?-->/gsu)) skip.push([comment.index, comment.index + comment[0].length]);const all = elements(source, skip);@@ -132,15 +153,26 @@ export function sliceSource(source: string, segment: string): SliceResult {// by position: a `<speech:Take>` has no id, and still has to be droppable on its own.const opening = (element: Element): string => /^<[^>]*>/su.exec(element.text)?.[0] ?? element.text;const dropped = new Map<number, string>();+ /** Opening tags rewritten by the cut, keyed by where the element starts. */+ const reopened = new Map<number, string>();const byId = new Map(all.flatMap((element) => element.id === undefined ? [] : [[element.id, element] as const]));const deadIds = new Set<string>();for (;;) {let changed = false;for (const element of all) {if (dropped.has(element.start)) continue;- const { story, ids } = references(opening(element));+ const tag = reopened.get(element.start) ?? opening(element);+ const { story, ids } = references(tag);const missingStory = [...story].find((name) => !alive.has(name));if (missingStory !== undefined) {+ // A close that has not arrived in this stretch is removed rather than fatal: the element keeps+ // the span it was given and simply does not end inside the fragment.+ const close = closesLater(tag, missingStory);+ if (close !== undefined) {+ reopened.set(element.start, tag.replace(close, ""));+ changed = true;+ continue;+ }dropped.set(element.start, `story.${missingStory}`);if (element.id !== undefined) deadIds.add(element.id);changed = true;@@ -179,12 +211,30 @@ export function sliceSource(source: string, segment: string): SliceResult {&& !(other.start === element.start && other.end === element.end))).sort((left, right) => left.start - right.start);+ // A rewritten opening tag replaces its own bytes, in the same pass and in the same order as a cut,+ // so the two never disagree about where the cursor is. A tag inside a range being cut is not+ // reached: the cut takes it with everything else.+ const edits = [+ ...cuts.map((element) => ({ start: element.start, end: element.end, text: undefined as string | undefined })),+ ...[...reopened].flatMap(([start, tag]) => {+ const element = all.find((candidate) => candidate.start === start);+ if (element === undefined || dropped.has(start)) return [];+ const length = (/^<[^>]*>/su.exec(element.text)?.[0] ?? element.text).length;+ return [{ start, end: start + length, text: tag }];+ }),+ ].sort((left, right) => left.start - right.start);+let text = "";let cursor = 0;- for (const cut of cuts) {- if (cut.start < cursor) continue;- text += source.slice(cursor, cut.start);- cursor = cut.end;+ for (const edit of edits) {+ if (edit.start < cursor) continue;+ text += source.slice(cursor, edit.start);+ if (edit.text !== undefined) {+ text += edit.text;+ cursor = edit.end;+ continue;+ }+ cursor = edit.end;// Take the rest of the line with it, so a removal never leaves a blank indented line behind.while (source[cursor] === " " || source[cursor] === "\t") cursor += 1;if (source[cursor] === "\n") cursor += 1;diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 13c31bd0..7450517d 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -1250,7 +1250,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst differences = await ask(`comparison:${comparisonId}`, {media: [referenceMedia, renderedMedia],instruction: `You compare two supplied ${unit} and describe their visible differences in natural language only. You are not told how either was made. Do not write code, markup, SVML, component names, or production advice.`,- prompt: `Two ${unit} are supplied in order: one, then two.${reading}${asClip ? cut?.incomplete ?? "" : ""}${scope.length === 0 ? "" : `\n\nLimit the comparison to this: ${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 and absent from the other.${asClip ? " Also describe differences in what changes over the stretch: what appears, what leaves, in what order, and how anything moves." : ""} 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 was produced, which one is a source, or which one is a copy. Return natural language only.`,+ prompt: `Two ${unit} are supplied in order: one, then two. Call them one and two throughout your answer, and say which of the two each difference is in.${reading}${asClip ? cut?.incomplete ?? "" : ""}${scope.length === 0 ? "" : `\n\nLimit the comparison to this: ${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 and absent from the other.${asClip ? " Also describe differences in what changes over the stretch: what appears, what leaves, in what order, and how anything moves." : ""} 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 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