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: add geometry-first review diagnostics
rpone9bb49edf31a0
diff --git a/.agents/skills/hypit/references/element-review.md b/.agents/skills/hypit/references/element-review.mdindex 3ab7f8af..61729539 100644--- a/.agents/skills/hypit/references/element-review.md+++ b/.agents/skills/hypit/references/element-review.md@@ -91,6 +91,30 @@ Then tell the reader that those regions are preview mocks standing in for declargenerations, and to read only what the element itself draws. Said plainly it costs one clause andsaves the mock coming back as a finding in the one round there is.+### Geometry first: Canvas, outer frame, content++Every look starts with a geometry pass before style or polish. Identify the three nested levels:+Canvas, the outer Frame/background that owns the region, and the inner text or element that must fit+inside it. For each level, check the following explicitly:++- **Centre:** when the design calls for centring, compare the content centre with the outer-frame+ centre on both axes. Report the direction and approximate offset (for example, `12% too far+ right` or `8% too high`), not just “misaligned”.+- **Containment:** report whether every visible glyph/mark stays inside its intended outer Frame and+ whether the Frame itself stays inside the Canvas. Name the offending edge and the estimated amount+ outside. Distinguish intentional bleed, crop, or enter/exit motion from an accidental overflow.+- **Capacity:** verify that the outer Frame is actually wide and tall enough for the text/element,+ including padding, stroke, shadow, and the longest line. A centred item in an undersized box is still+ a failure even when its centre is correct.+- **Canvas safety:** check the final visible bounds against all four Canvas edges. Nothing should be+ clipped unless the reference/intent clearly calls for it.++`authoring_check` and `reconstruction_check` return a deterministic `layout_geometry` report with+Canvas/Frame bounds, sizes, centres, parent/Canvas centre offsets, containment overflow, and bound+element ids. Use those numbers as the mechanical findings and let the observer decide whether the+alignment or overflow matches the reference/intent. The report cannot measure renderer-shaped glyph+bounds or infer intent, so the visual pass must still confirm text and marks in the rendered image.+A mock lives only in this render. It is never written into the Source, and no gate reads it: the`playback` check reads the Source's Recipes, so a mock cannot be mistaken for coverage.diff --git a/.agents/skills/hypit/references/original-authoring/conformance-round.md b/.agents/skills/hypit/references/original-authoring/conformance-round.mdindex c68fa841..6343e57f 100644--- a/.agents/skills/hypit/references/original-authoring/conformance-round.md+++ b/.agents/skills/hypit/references/original-authoring/conformance-round.md@@ -59,6 +59,19 @@ The preview-mock clause is in the prompt already: the reader is told that flat-ffor generations that have not run and to read only what is drawn over them. Do not add it by hand, anddo not add anything that says what you built or what you expect to be found.+The visual pass is geometry-first. Read the hierarchy Canvas → outer Frame/background → inner text or+element. When the intent calls for centring, compare the inner and outer centres on both axes and report+the direction and approximate offset. Check containment at both boundaries (content inside its Frame,+Frame inside Canvas), naming any overflowing edge. Confirm the outer Frame is wide and tall enough for+the longest line/mark plus padding, stroke, shadow, and corner treatment; correct centring does not make+an undersized box acceptable. Separate intentional bleed/crop or enter/exit motion from accidental+overflow, and check the final visible bounds against all four Canvas edges.++`authoring_check` returns `layout_geometry` with deterministic Canvas/Frame bounds, centres, parent and+Canvas offsets, containment overflow, and bound element ids. Use it as the mechanical report and make+the conformance decision from the rendered picture and intent. It cannot measure actual glyph bounds or+infer intent, so those still require the reader.+`--question` is available and means what it means on the other route: which region to read, never whatto conclude.diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.mdindex 3685e6a7..483d6f7c 100644--- a/.agents/skills/hypit/references/original-authoring/route.md+++ b/.agents/skills/hypit/references/original-authoring/route.md@@ -98,6 +98,10 @@ hypit-reference-video-tools authoring_check projects/<name>/build.svrunIts `plan` is the list: each entry an element and a word range, with the reason. Feed it to`render_element --batch` — the program is drawn once and every entry is cut out of those frames.+Keep the check JSON's `layout_geometry` with the renders. It is the deterministic Canvas/Frame report+for centre offsets, frame capacity, and containment; the reader still decides whether the visible text+or marks fit the intent and whether any bleed is deliberate.+**Read now:** `../element-review.md` — what the three rules are and why the list is what it is.`../preview.md` holds `render_element` itself.diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex e18975ea..2ac14e53 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -96,6 +96,11 @@ well.Each Segment's length comes from the Source's own `estimate:Speech`; `--reference-id` selects referenceevidence and comparison windows only. The sidecar records `"timing_basis": "estimate"`.+Before reading the picture, run the route's `reconstruction_check` or `authoring_check` and keep its+`layout_geometry` object with the render. It is the mechanical Canvas/Frame report used to check centre+offsets, frame capacity, and Canvas containment; the observer still confirms rendered text bounds and+whether any bleed is intentional.+## Open the whole Run for a personAfter a meaningful Author Source change, start Hypit Studio and give the author the actual URL.diff --git a/.agents/skills/hypit/references/reconstruction/comparison-round.md b/.agents/skills/hypit/references/reconstruction/comparison-round.mdindex b644ffba..7be8402a 100644--- a/.agents/skills/hypit/references/reconstruction/comparison-round.md+++ b/.agents/skills/hypit/references/reconstruction/comparison-round.md@@ -137,6 +137,22 @@ The pair is always sent in one order: **one is the reference, two is the render.told that and must not be; you need it, because a difference reported "in one" is a difference in thereference and one "in two" is something to repair.+## Geometry is a first-class comparison++Before comparing colour, typography, or motion, compare the layout hierarchy: Canvas → outer+Frame/background → inner text or element. For every centred region, report the content-to-frame centre+offset on both axes and its direction. Then report containment separately at each boundary: content+inside outer Frame, outer Frame inside Canvas, naming the edge and approximate overflow when one fails.+Check that the outer Frame has enough width/height for the longest line or mark plus padding, stroke,+shadow, and corner treatment. A box can be centred and still be too small. Treat intentional bleed,+crop, and enter/exit motion as a separate possibility and only call it a defect when the reference+does not show that intention.++The `reconstruction_check` JSON includes `layout_geometry`, a mechanical report of Canvas/Frame bounds,+centres, parent/Canvas offsets, containment overflow, and bound element ids. The agent should use those+facts alongside the comparison text. They are deterministic Source facts, not a decision: rendered+glyph bounds and whether an overhang is intentional still require the observer.+## Measuring, on this route`../element-review.md` says to ask for a number rather than spend an attempt. Here that question isdiff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.mdindex a1c580e8..4a60b477 100644--- a/.agents/skills/hypit/references/reconstruction/route.md+++ b/.agents/skills/hypit/references/reconstruction/route.md@@ -275,6 +275,10 @@ hypit-reference-video-tools render_element projects/<name>/build.svrun --batch rThe program is drawn once and every entry is cut out of those frames, so renderthe whole list in one `--batch` call.+Keep the check JSON's `layout_geometry` beside the round. It gives the observer/agent deterministic+Canvas and Frame centres, parent/Canvas offsets, overflow edges, and bound element ids to use when+judging centring, frame capacity, and Canvas safety.+### 20. Send every comparison at onceThe same file is a `compare_reconstruction --batch` file too — `comparisons` is in it, and each entrydiff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.tsindex 7988ee2f..ad5ed1f8 100644--- a/packages/reference-video-tools/src/checks.ts+++ b/packages/reference-video-tools/src/checks.ts@@ -277,6 +277,36 @@ type OutOfBoundsFrame = {readonly outside_fraction: number;};+/**+ * Deterministic geometry facts handed to the observer alongside the human-readable round.+ *+ * This deliberately reports only what the Source can prove: Canvas/Frame rectangles, parent and+ * Canvas containment, and centre offsets. Whether a particular box *ought* to be centred, or whether+ * a child is intentionally clipped (for example during an enter animation), remains a visual and+ * intent judgement. Text glyph bounds are renderer-dependent and therefore are not invented here.+ */+type LayoutGeometryEntry = {+ readonly id: string;+ readonly kind: "canvas" | "frame";+ readonly within?: string;+ readonly canvas?: string;+ readonly bounds?: Box;+ readonly size?: { readonly width: number; readonly height: number };+ readonly center?: { readonly x: number; readonly y: number };+ readonly center_offset_from_within?: { readonly x: number; readonly y: number };+ readonly center_offset_from_canvas?: { readonly x: number; readonly y: number };+ readonly outside_within?: { readonly left: number; readonly top: number; readonly right: number; readonly bottom: number };+ readonly outside_canvas?: { readonly left: number; readonly top: number; readonly right: number; readonly bottom: number };+ readonly bound_elements?: readonly string[];+ readonly unresolved?: string;+};++type LayoutGeometryReport = {+ readonly coordinate_system: "Canvas pixels, origin top-left, y increases downward";+ readonly note: string;+ readonly entries: readonly LayoutGeometryEntry[];+};+/** 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 };@@ -503,6 +533,66 @@ function framesPastTheCanvas(svml: string): readonly OutOfBoundsFrame[] {return report;}+/** Build a machine-readable layout report for the agent/observer to interpret. */+function layoutGeometry(svml: string): LayoutGeometryReport {+ const geometry = frameGeometry(svml);+ 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([^>]*?)\/?\s*>/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 names = bound.get(frame) ?? [];+ if (!names.includes(id)) names.push(id);+ bound.set(frame, names);+ }+ }++ const outside = (child: Box, parent: Box) => ({+ left: round(Math.max(parent.left - child.left, 0)),+ top: round(Math.max(parent.top - child.top, 0)),+ right: round(Math.max(child.right - parent.right, 0)),+ bottom: round(Math.max(child.bottom - parent.bottom, 0)),+ });+ const centre = (box: Box) => ({ x: round((box.left + box.right) / 2), y: round((box.top + box.bottom) / 2) });+ const delta = (a: Box, b: Box) => ({ x: round((a.left + a.right - b.left - b.right) / 2), y: round((a.top + a.bottom - b.top - b.bottom) / 2) });+ const entries: LayoutGeometryEntry[] = [];++ for (const [id, canvas] of geometry.canvases) {+ entries.push({+ id, kind: "canvas", bounds: canvas,+ size: { width: round(canvas.right - canvas.left), height: round(canvas.bottom - canvas.top) },+ center: centre(canvas),+ });+ }+ for (const [id, declaration] of geometry.declared) {+ const box = geometry.resolve(id);+ const canvasId = geometry.canvasOf(id);+ const parent = geometry.resolve(declaration.within);+ const canvas = canvasId === undefined ? undefined : geometry.canvases.get(canvasId);+ if (box === undefined) {+ entries.push({ id, kind: "frame", within: declaration.within, ...(canvasId === undefined ? {} : { canvas: canvasId }),+ bound_elements: bound.get(id) ?? [], unresolved: "frame edges or its parent could not be resolved to Canvas pixels" });+ continue;+ }+ entries.push({+ id, kind: "frame", within: declaration.within,+ ...(canvasId === undefined ? {} : { canvas: canvasId }), bounds: box,+ size: { width: round(box.right - box.left), height: round(box.bottom - box.top) },+ center: centre(box),+ ...(parent === undefined ? {} : { center_offset_from_within: delta(box, parent), outside_within: outside(box, parent) }),+ ...(canvas === undefined ? {} : { center_offset_from_canvas: delta(box, canvas), outside_canvas: outside(box, canvas) }),+ bound_elements: bound.get(id) ?? [],+ });+ }+ return {+ coordinate_system: "Canvas pixels, origin top-left, y increases downward",+ note: "Use these facts to decide whether centering and containment match the reference/intent. They do not measure rendered glyph bounds or decide whether an overhang is intentional.",+ entries,+ };+}+/*** 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@@ -582,6 +672,8 @@ export async function authoringCheck(// Read from the Source alone, so every answer below carries it, including the ones that stop early.const overhang = framesPastTheCanvas(svml);+ // Deterministic facts for a geometry-first visual review. The observer still decides intent.+ const geometry = layoutGeometry(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@@ -607,6 +699,7 @@ export async function authoringCheck(playback: [],uncovered: [],out_of_bounds: overhang,+ layout_geometry: geometry,};}@@ -864,6 +957,7 @@ export async function authoringCheck(playback: [],uncovered: [],out_of_bounds: overhang,+ layout_geometry: geometry,...(unresolved.length === 0 ? {} : {unresolved_packages: {names: unresolved,@@ -1285,6 +1379,7 @@ export async function authoringCheck(+ "unclaimed.",}),out_of_bounds: overhang,+ layout_geometry: geometry,...(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 "diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.tsindex f2a17959..e58c1900 100644--- a/packages/reference-video-tools/src/cli.ts+++ b/packages/reference-video-tools/src/cli.ts@@ -67,6 +67,10 @@ function usage(): string {"element slides in from off-screen and how a full-bleed picture is cropped by a fit, and a mistake","looks the same. A comparison cannot answer it either way, because the render and reference are","drawn at the same Canvas and put the element in the same place off the edge.",+ "Both checks also return layout_geometry: deterministic Canvas/Frame bounds, centres, parent and",+ "Canvas offsets, containment overflow and bound element ids. Use it as a mechanical geometry report",+ "for the observer to judge centring, frame capacity and Canvas safety; it does not measure rendered",+ "glyph bounds or decide whether an overhang is intentional.","","render_element draws one element of a Source the way that Source configures it, without a Build.","The Canvas, frame rate, Recipe values and bindings come from the compiled Graph; missing media is",diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 2f753733..680bd096 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -1692,7 +1692,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. 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.`,+ 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\nStart with a geometry pass before style: identify the Canvas, the outer frame or background box, and the inner text/element. For every region that should be centred, compare inner and outer centres on both axes and report the direction and approximate offset. Check containment separately (inner content inside its outer frame; outer frame inside the Canvas), naming the overflowing edge and approximate amount. Check that the outer frame is wide and tall enough for the longest line or mark including padding, stroke, shadow and corner treatment. Distinguish intentional bleed, crop, or enter/exit motion from accidental overflow. Then describe every other 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.`,});// What was compared, and what was seen. The record is what a gate reads to tell an element that// was looked at from one that never was, and what an identical pair is answered from without@@ -1924,11 +1924,16 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV+ "Matches the description: state which parts of the description the picture satisfies and which"+ " it does not. Name anything the description asks for that is not there, and anything present"+ " that the description does not mention.\n\n"- + "Visible defects: report each of these you can see, and say it is absent when you cannot."- + " Anything cut off by the edge of the frame or reaching past it. Anything overlapping or"- + " covering something else that is meant to be read. Anything whose position or alignment"- + " against the edges of the frame looks unintended. Text or marks too low in contrast against"- + " what is behind them to read."+ + "Visible defects: begin with a geometry pass. Identify Canvas, outer frame/background, and"+ + " inner text/element. For centred regions report the inner-to-outer centre offset and direction."+ + " Check inner-content containment inside the outer frame, outer-frame containment inside the"+ + " Canvas, and whether the frame has enough width/height for the longest content plus padding,"+ + " stroke, shadow and corner treatment. Report each overflowing edge and approximate amount;"+ + " distinguish intentional bleed/crop or enter/exit motion from accidental overflow. Then report"+ + " each other defect you can see, and say it is absent when you cannot: anything cut off by the"+ + " edge of the frame or reaching past it; anything overlapping or covering something else that"+ + " is meant to be read; anything whose position or alignment against the edges of the frame"+ + " looks unintended; and text or marks too low in contrast against what is behind them to read."+ (asClip ? " Anything that appears, moves or leaves in a way the description does not account for." : "")+ "\n\nMeasure what you can against the frame's own width and height rather than in pixels."+ " Return natural language only.",diff --git a/packages/reference-video-tools/test/tools.test.ts b/packages/reference-video-tools/test/tools.test.tsindex 30fadc10..d2825516 100644--- a/packages/reference-video-tools/test/tools.test.ts+++ b/packages/reference-video-tools/test/tools.test.ts@@ -214,6 +214,9 @@ test("reconstruction comparison sends an unlabelled pair and accepts rendered PNassert.deepEqual(calls[0]!.mimeTypes, ["image/jpeg", "image/png"]);assert.match(calls[0]!.text, /supplied in order: one, then two/u);assert.match(calls[0]!.text, /only the full-screen list area/u);+ assert.match(calls[0]!.text, /geometry pass/u);+ assert.match(calls[0]!.text, /outer frame/u);+ assert.match(calls[0]!.text, /overflow/u);assert.doesNotMatch(calls[0]!.text, /reconstruction|rendered|generated|authored|component|SVML/iu,"the comparison must never say which image was built or how");assert.match(calls[0]!.instruction, /You are not told how either was made/u);