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
refactor(hypit): sample visual declaration changes only (#121)
rponeawa0f01805cac17
diff --git a/.agents/skills/hypit/references/element-review.md b/.agents/skills/hypit/references/element-review.mdindex 04b68596..f6adce6f 100644--- a/.agents/skills/hypit/references/element-review.md+++ b/.agents/skills/hypit/references/element-review.md@@ -35,17 +35,12 @@ named. Neither gate expects you to guess; each one tells you what is wrong, andlooking at, as an element and a half-open range of the Script's own words, with the reason it earned aplace. Render that list and read that list. Nothing here asks you to decide which stretches matter.-Three rules produce it, and all three are read off the Source. **A distinct declaration is a distinct-picture**, so an element is looked at once per way it is declared, at the stretch where that way first-appears — which is also the floor, since every placed element declares something. **Content that can-break the layout earns its own look**, which is why a caption Style is read over its longest Cue rather-than its shortest. **A window length earns one only when something scales with it** — an enter costs-its frames at one edge whatever the window is, but a typewriter, a loop or a `stretch` playback runs-for as long as the window does.--A range rather than a name, because the answer is not always a name: a Cue ends at a speaker change, so-it is a run of words the Script never marked. `--tokens from:to` is how every command takes one, and-`--segment`/`--selection` remain for the ranges that do have names.+One rule produces it, read off the Source: **a distinct declaration is a distinct picture**. An+element is looked at once per way it is declared, at the stretch where that declaration first+appears. This is also the floor, since every placed element declares something.++A token range is the stable identity used by every command. `--segment` and `--selection` remain+available for ranges that already have names.The gate then holds the round to that list. An element looked at once used to pass; now every entry theplan names has to have been answered.@@ -164,9 +159,10 @@ one default Style and a `caption:Use` override for one Selection is two looks, wtwo first appear, not one per Segment. This is the same reading `script-time.md` applies to everyother system that spans cuts: the system is authored once, so it is read once.-What is not covered by that is anything a Style does not decide. A Cue that overflows the frame is a-Segment nobody broke with `||` rather than a Style at the wrong width — `playbooks/craft/captions.md`-says so — and it belongs to the stretch whose words are long, not to the Style.+Source-level Canvas safety is checked separately. `authoring_check` and `reconstruction_check` resolve+every declared Frame into Canvas coordinates and report the elements bound to any Frame that crosses+a Canvas edge. Package-internal glyph or private layout bounds remain visible-review facts because+the Source does not expose geometry that a mechanical check could measure.### Render every stretch first, then send them all at oncediff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.mdindex 54c04ec2..d8bf74ef 100644--- a/.agents/skills/hypit/references/original-authoring/route.md+++ b/.agents/skills/hypit/references/original-authoring/route.md@@ -194,7 +194,7 @@ for vertical centre offsets, frame capacity, and containment; horizontal left/rijudged mechanically. The reader still decides whether visible text or marks fit the intent and whetherany offset, overlap or bleed is deliberate.-**Read now:** `../element-review.md` — what the three rules are and why the list is what it is.+**Read now:** `../element-review.md` — why each distinct visual declaration is read where it first appears.`../preview.md` holds `render_element` itself.Render the whole set before reading any of it. Studio is also free and is for the author to look at;diff --git a/.agents/skills/hypit/references/reconstruction/observers.md b/.agents/skills/hypit/references/reconstruction/observers.mdindex 787c2b0a..9eb78c6d 100644--- a/.agents/skills/hypit/references/reconstruction/observers.md+++ b/.agents/skills/hypit/references/reconstruction/observers.md@@ -188,6 +188,5 @@ as equivalent, in the words the observer used.## Comparing without subagentsAnswering the comparison yourself makes the report yours, and you know what you built.-`../element-review.md` states the three rules that stand in for the blindness a harness without-subagents cannot give you, and they apply here unchanged. What a subagent adds, and they cannot, is-that the comparer is not the builder.+`../element-review.md` states the declaration-change rule that selects comparisons, and it applies+here unchanged. What a subagent adds, and they cannot, is that the comparer is not the builder.diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.tsindex 6263527b..d82e2e57 100644--- a/packages/reference-video-tools/src/checks.ts+++ b/packages/reference-video-tools/src/checks.ts@@ -1211,15 +1211,6 @@ export async function authoringCheck(}// What a round has to look at, decided from the Source rather than left to whoever runs it.- //- // The Recipe bodies come along because one of the three rules asks whether an element's appearance- // runs for as long as its window does, and that is written in the Recipe rather than on the tag.- const recipeBodies = new Map<string, string>();- for (const sheet of svml.matchAll(/<import\s+as="[^"]+"\s+source="([^"]+\.svs)"/gu)) {- const text = await readFile(resolve(dirname(svmlPath), sheet[1] ?? ""), "utf8").catch(() => undefined);- if (text === undefined) continue;- for (const recipe of text.matchAll(/([A-Za-z0-9_.-]+)\s*\{([^}]*)\}/gu)) recipeBodies.set(recipe[1] ?? "", recipe[2] ?? "");- }// Where each stretch's picture goes, named here rather than by whoever reads this.//// A round is three commands — this one, `render_element --batch`, `compare_reconstruction --batch` —@@ -1229,7 +1220,7 @@ export async function authoringCheck(//// Named for the range and not for `named`: the range is what identifies an entry, so two entries of// one element always differ in it, while `named` is a sentence written to be read.- const plan = reviewPlan({ svml, svmlPath, scriptBody: scriptBody(svml), drawn, recipes: recipeBodies })+ const plan = reviewPlan({ svml, svmlPath, scriptBody: scriptBody(svml), drawn }).map((entry) => ({...entry,out: join(dirname(runPath), "renders", `${entry.element}-${entry.tokens[0]}-${entry.tokens[1]}.mp4`),@@ -1521,8 +1512,7 @@ export async function authoringCheck(entries: owed,note: `${owed.length} stretch${owed.length === 1 ? "" : "es"} the Source asks for ${owed.length === 1 ? "has" : "have"} `+ "not been looked at. Each one is an element over a range of the Script's own words, and the reason it is "- + "here is beside it — a declaration nobody has seen, the longest cue a caption Style has to hold, or a "- + "window long enough that an animation inside it behaves differently.",+ + "here is beside it — the first appearance of a distinct visual declaration nobody has seen.",commands: owed.map((entry) => mode === "reconstruction"? `hypit-reference-video-tools compare_reconstruction --reference-id ${reference} --run ${runPath} `+ `--tokens ${entry.tokens[0]}:${entry.tokens[1]} --video ${entry.out} --element ${entry.element}`diff --git a/packages/reference-video-tools/src/plan.ts b/packages/reference-video-tools/src/plan.tsindex ad58bc3d..7a9c07dc 100644--- a/packages/reference-video-tools/src/plan.ts+++ b/packages/reference-video-tools/src/plan.ts@@ -1,30 +1,19 @@/*** Which stretches of a program are worth looking at, decided from the Source alone.*- * An element drawn over five Segments does not need five looks. It needs one per way it can fail,- * and two stretches fail the same way when they are the same declaration over the same kind of- * content for the same length of time. Deciding that by reading the Source is what makes a round- * reproducible and what lets the gate ask for coverage rather than for participation.+ * An element drawn over five Segments does not need five looks. It needs one per distinct visual+ * declaration. Deciding that by reading the Source is what makes a round reproducible and what lets+ * the gate ask for coverage rather than for participation.*- * Three rules produce the list, and every one of them reads text:+ * **A distinct declaration is a distinct picture.** Group an element's placements by what they+ * declare and look at each group once, where it first appears. This is also the floor: every placed+ * element has at least one declaration, so every element gets at least one look.*- * 1. **A distinct declaration is a distinct picture.** Group an element's placements by what they- * declare and look at each group once, where it first appears. This is also the floor: every- * placed element has at least one declaration, so every element gets at least one look — which is- * exactly what the gate required before this file existed.- * 2. **Content that can break the layout is worth its own look.** Within a group, the stretch- * holding the most is a different question from the stretch holding the least: a caption system- * read over its shortest line looks correct, because one line has nothing to collide with.- * 3. **A window length is worth its own look only when something scales with it.** An enter and an- * exit happen at the edges for a fixed number of frames; a typewriter, a loop or a `stretch`- * playback runs for as long as the window does.- *- * The unit is a token range rather than a Segment name, because the answer is not always a name. A- * caption Cue is a run of words the Script never marked, and it is exactly what rule 2 wants to look- * at. Both sides of a comparison already work in words — `frameOfToken` here, `spokenRange` on the- * reference — so the range is what they both take, and a name comes along only to be read.+ * The unit is a token range rather than a Segment name because both sides of a comparison already+ * work in words — `frameOfToken` here, `spokenRange` on the reference — so the range is what they+ * both take, and a name comes along only to be read.*/-import { captionDocument, parseScript } from "@hypit/script";+import { parseScript } from "@hypit/script";import type { ParsedNarrative } from "@hypit/script";/** One thing to look at: an element, over a range of the Script's words, and why it earned a look. */@@ -68,31 +57,11 @@ const MOCKED_ATTRIBUTES = new Set(["image", "video", "media", "source", "icon",/** Never a declaration: the id is what the key is being computed *for*. */const IGNORED_ATTRIBUTES = new Set(["id"]);-/**- * Recipe keys whose effect lasts as long as the window does.- *- * An `enter` costs its `enter-frames` at one edge whatever the window is; these do not. A window- * twice as long runs twice as much typewriter, twice as many loop cycles, and stretches its material- * to twice the duration — so two windows of very different lengths are two questions.- *- * This is review policy, not Studio's Where / How / When presentation: a fixed six-frame entrance is- * a When field but does not scale with the window. Only behaviours whose duration consumes the whole- * window belong here.- */-const WHOLE_WINDOW_KEYS = [- "sustain", "playback", "playback-future", "playback-past", "trim-start", "trim-end",- "loop", "loop-target", "loop-period-frames", "loop-intensity",- "atom-reveal", "karaoke", "karaoke-transition", "active-underline",- "active-box", "active-box-continuity",-];-type Placement = {readonly element: string;readonly tag: string;readonly key: string;readonly stretch: Stretch;- /** Everything the placement declares, kept so rule 3 can read the Recipes it names. */- readonly attributes: ReadonlyMap<string, string>;};type Stretch = {@@ -265,7 +234,7 @@ function captionStyles(svml: string, element: PlannedElement, parsed: ParsedNarrif (stretch === undefined || style === undefined) continue;found.push({element: element.id, tag: `${tag} (caption:Use)`,- key: `${tag}|style=${style}`, stretch, attributes,+ key: `${tag}|style=${style}`, stretch,});}return found;@@ -288,7 +257,7 @@ function placementsOf(svml: string, element: PlannedElement, parsed: ParsedNarraif (ownStretch !== undefined) {found.push({element: element.id, tag: `${element.alias}:${element.tag}`,- key: ownKey, stretch: ownStretch, attributes: own,+ key: ownKey, stretch: ownStretch,});}@@ -310,7 +279,6 @@ function placementsOf(svml: string, element: PlannedElement, parsed: ParsedNarratag,key: `${ownKey}>>${[declarationKey(tag, attributes), ...childDeclarations(inner, parsed)].join("&&")}`,stretch,- attributes,});}@@ -322,148 +290,12 @@ function placementsOf(svml: string, element: PlannedElement, parsed: ParsedNarratag: `${element.alias}:${element.tag}`,key: ownKey,stretch: wholeProgram(parsed),- attributes: own,- });- }- return found;-}--/**- * Rule 2, for captions: where the longest Cue is.- *- * A Cue is the unit a caption's layout can break on, and it is not a Segment. Four things end one,- * and only one of them is the `||` the author wrote: the other three are a Segment ending, a speaker- * changing, and a Style changing. Partitioning on the authored breaks alone reads a two-speaker- * script as a handful of enormous Cues, and then reports the longest line as the whole exchange.- *- * The units come from `captionDocument`, and each one carries the speech tokens it corresponds to.- * That mapping is what makes the answer a range of the Script's own words rather than a guess: a Dual- * Text alias is one indivisible unit spanning its whole region, and reading its display words back- * against the speech by counting would land in the wrong place.- *- * `temporalizeCaptionDocument` groups on the same four facts, but it needs a SemanticTrack to assign- * frames and this check never builds one. Only the grouping is repeated here; the frames it would- * have assigned are not something anything on this path asks for.- */-function longestCue(- parsed: ParsedNarrative,- styleBoundaries: ReadonlySet<number>,- narrativeId: string,-): Stretch | undefined {- let document;- try { document = captionDocument(parsed, "captions", narrativeId); } catch { return undefined; }- if (document.units.length === 0) return undefined;-- const tokenIndex = new Map(parsed.tokens.map((token, index) => [token.id, index] as const));- const spanOf = (unit: typeof document.units[number]): { readonly from: number; readonly to: number } | undefined => {- const indexes = unit.sourceTokenIds.flatMap((id) => {- const at = tokenIndex.get(id);- return at === undefined ? [] : [at];});- return indexes.length === 0 ? undefined : { from: Math.min(...indexes), to: Math.max(...indexes) + 1 };- };-- const breaks = new Set(document.cueBreaks.map((cueBreak) => cueBreak.afterUnitId));- let current: { from: number; to: number; characters: number } | undefined;- let previous: typeof document.units[number] | undefined;- let best: { from: number; to: number; characters: number } | undefined;- const close = (): void => {- if (current !== undefined && (best === undefined || current.characters > best.characters)) best = current;- };-- for (const unit of document.units) {- const span = spanOf(unit);- if (span === undefined) continue;- const characters = unit.wordIds.length === 0- ? 0- : document.words.filter((word) => word.unitId === unit.id).reduce((sum, word) => sum + word.text.length, 0);- // The same four things that end a Cue: a Segment ends, the speaker changes, the Style changes, or- // the author wrote one. The first two are on the unit; the third is where a `caption:Use` starts- // or stops; the fourth is the document's own list.- const ended = previous !== undefined && (- previous.segmentId !== unit.segmentId- || previous.turnId !== unit.turnId- || breaks.has(previous.id)- || styleBoundaries.has(span.from));- if (current === undefined || ended) { close(); current = { ...span, characters }; }- else { current = { from: current.from, to: span.to, characters: current.characters + characters }; }- previous = unit;- }- close();- if (best === undefined) return undefined;-- const holding = parsed.segments.find((item) => best!.from >= item.tokenStart && best!.from < item.tokenEndExclusive);- return {- tokens: [best.from, best.to],- named: holding === undefined ? "the longest cue" : `the longest cue, in segment ${holding.id}`,- };-}--/**- * Where a `caption:Program` changes Style, in token space.- *- * `<caption:Use selection=…>` is how one stretch is drawn differently from the rest, and it is the- * only place a caption's declaration varies — the Track's own tag is identical over the whole- * program. Both ends of the named Selection are Cue boundaries, because a Style change ends a Cue.- */-function captionStyleBoundaries(svml: string, parsed: ParsedNarrative): ReadonlySet<number> {- const found = new Set<number>();- for (const use of svml.matchAll(/<[a-z][a-z0-9-]*:(?:Use|Mute)\b([^>]*?)\/?>/gsu)) {- const selection = /\bselection=\{story\.selection\.([A-Za-z0-9_-]+)\}/u.exec(use[1] ?? "")?.[1];- if (selection === undefined) continue;- const marked = parsed.selections.find((item) => item.id === selection);- if (marked === undefined) continue;- found.add(marked.open.boundary.tokenIndex);- found.add(marked.close.boundary.tokenIndex);}return found;}-/**- * Rule 2, for anything holding a list: which stretch holds the most of it.- *- * Items are written into the Source as children, each bound to its own Moment or Selection, so the- * count per stretch is a count of children — no rendering and no measurement. The stretch holding- * the most is where the layout has the most chance to run out of room.- */-function fullestStretch(placements: readonly Placement[]): Stretch | undefined {- const counts = new Map<string, { readonly stretch: Stretch; count: number }>();- for (const placement of placements) {- const key = `${placement.stretch.tokens[0]}-${placement.stretch.tokens[1]}`;- const held = counts.get(key);- if (held === undefined) counts.set(key, { stretch: placement.stretch, count: 1 });- else held.count += 1;- }- const ranked = [...counts.values()].sort((one, other) => other.count - one.count);- const most = ranked[0];- // One each is not a list. Nominating a stretch here would just re-name what rule 1 already has.- return most === undefined || most.count < 2 ? undefined : most.stretch;-}--/**- * Rule 3: does anything about this element's appearance run for as long as its window does?- *- * This is deliberately narrower than Inspector's `when` page: an edge animation belongs on that- * page but does not make a longer window a different animation sample.- */-function scalesWithWindow(bodies: readonly string[]): boolean {- return bodies.some((body) => WHOLE_WINDOW_KEYS.some((key) => new RegExp(`\\b${key}\\s*:`, "u").test(body)));-}--/** The Recipe bodies one placement's declaration names, so rule 3 can read their keys. */-function recipeBodiesOf(attributes: ReadonlyMap<string, string>, recipes: ReadonlyMap<string, string>): readonly string[] {- const bodies: string[] = [];- for (const [name, value] of attributes) {- if (WINDOW_ATTRIBUTES.has(name) || MOCKED_ATTRIBUTES.has(name)) continue;- const named = /^\{([A-Za-z0-9_.-]+)\}$/u.exec(value)?.[1];- if (named === undefined) continue;- const body = recipes.get(named.replace(/^recipes\./u, ""));- if (body !== undefined) bodies.push(body);- }- return bodies;-}--/** Rule 1: one look per distinct declaration, at the stretch where that declaration first appears. */+/** One look per distinct declaration, at the stretch where that declaration first appears. */function firstOfEachDeclaration(placements: readonly Placement[]): readonly PlanEntry[] {const seen = new Set<string>();const entries: PlanEntry[] = [];@@ -483,8 +315,8 @@ function firstOfEachDeclaration(placements: readonly Placement[]): readonly Plan/*** Merge nominations that landed on the same thing.*- * Three rules can each name one stretch — the first occurrence of a Style may also hold its longest- * line and its longest window — and that is one look with three reasons, not three looks.+ * Two distinct declarations can first appear over the same stretch. That is one rendered picture+ * with both reasons, not two copies of the same picture.*/function merge(entries: readonly PlanEntry[]): readonly PlanEntry[] {const byKey = new Map<string, PlanEntry>();@@ -503,12 +335,8 @@ export function reviewPlan(input: {readonly svmlPath: string;readonly scriptBody: { readonly id: string; readonly text: string; readonly offset: number };readonly drawn: readonly PlannedElement[];- /** Recipe bodies by their sheet-local name, for rule 3. Absent means rule 3 nominates nothing. */- readonly recipes?: ReadonlyMap<string, string>;}): readonly PlanEntry[] {const parsed = parseScript(input.svmlPath, input.scriptBody.text, input.scriptBody.offset);- const recipes = input.recipes ?? new Map<string, string>();- const styleBoundaries = captionStyleBoundaries(input.svml, parsed);const entries: PlanEntry[] = [];for (const element of input.drawn) {@@ -519,33 +347,6 @@ export function reviewPlan(input: {...(element.specifier.includes("caption") ? captionStyles(input.svml, element, parsed) : []),];entries.push(...firstOfEachDeclaration(placements));-- // Rule 2. A caption's layout breaks on a Cue, and a list's breaks on how many items one stretch- // holds; every other element draws one thing and has no content extreme to find.- if (element.specifier.includes("caption")) {- const cue = longestCue(parsed, styleBoundaries, input.scriptBody.id);- if (cue !== undefined) entries.push({ element: element.id, tokens: cue.tokens, named: cue.named, why: ["longest cue"] });- }- const fullest = fullestStretch(placements);- if (fullest !== undefined) {- entries.push({ element: element.id, tokens: fullest.tokens, named: fullest.named, why: ["most items in one stretch"] });- }-- // Rule 3. Only where something runs for as long as the window does, and only then are the- // longest and the shortest two different questions rather than the same picture twice.- const animates = placements.some((placement) => scalesWithWindow(recipeBodiesOf(placement.attributes, recipes)));- if (animates && placements.length > 1) {- const byLength = [...placements].sort((one, other) =>- (one.stretch.tokens[1] - one.stretch.tokens[0]) - (other.stretch.tokens[1] - other.stretch.tokens[0]));- const shortest = byLength[0]!;- const longest = byLength.at(-1)!;- if (longest.stretch.tokens[1] - longest.stretch.tokens[0] !== shortest.stretch.tokens[1] - shortest.stretch.tokens[0]) {- entries.push({ element: element.id, tokens: longest.stretch.tokens, named: longest.stretch.named, why: ["longest window, and this element animates across it"] });- entries.push({ element: element.id, tokens: shortest.stretch.tokens, named: shortest.stretch.named, why: ["shortest window, and this element animates across it"] });- }- }}return merge(entries);}--export { WHOLE_WINDOW_KEYS };