Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

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.md
index 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, and
looking at, as an element and a half-open range of the Script's own words, with the reason it earned a
place. 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 the
plan names has to have been answered.
@@ -164,9 +159,10 @@ one default Style and a `caption:Use` override for one Selection is two looks, w
two first appear, not one per Segment. This is the same reading `script-time.md` applies to every
other 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 once
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
index 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/ri
judged mechanically. The reader still decides whether visible text or marks fit the intent and whether
any 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.md
index 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 subagents
Answering 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.ts
index 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.ts
index 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: ParsedNarr
if (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: ParsedNarra
if (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: ParsedNarra
tag,
key: `${ownKey}>>${[declarationKey(tag, attributes), ...childDeclarations(inner, parsed)].join("&&")}`,
stretch,
- attributes,
});
}
@@ -322,148 +290,12 @@ function placementsOf(svml: string, element: PlannedElement, parsed: ParsedNarra
tag: `${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 };