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.

feat: decide base pictures, material and the reconstruction loop

rponee0579979c17f
diff --git a/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
new file mode 100644
index 00000000..fb5875e5
--- /dev/null
+++ b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
@@ -0,0 +1,68 @@
+# Graphic compositions and material
+
+This file decides what a picture *is* before anything decides which component draws it. It applies to
+original authoring and to reconstruction equally.
+
+## A base picture is a depicted scene
+
+- A base picture is a depicted scene: a place, a person, an object, or a world with its own space,
+ light and camera. Live action and animation both qualify — a drawn or rendered world is a scene.
+- A designed graphic field is never a base picture. Ruled or gridded paper, document sheets, flat or
+ gradient colour, blurred wallpaper, boards, canvases, panels and slide backdrops exist so that
+ authored elements can sit on them. They are the surface of a composition, not a place.
+- Judge by what the surface is *for*, not by how convincing it looks. A photographed desk with a real
+ notebook on it is a scene. A full screen of paper that exists only so words can appear on it is a
+ graphic composition, however good the paper texture is.
+- Never send a designed field to a video generation model as a shot, and never author one as a base
+ Track. A scene generator asked for a backdrop returns unreproducible footage in place of content
+ you could have timed, edited and corrected.
+
+## A full-screen graphic composition is one component
+
+- When the whole picture is a designed field carrying authored content — a list, a ranking, a
+ leaderboard, a chart, a score, a quiz, a code sheet, a card wall, a title board — that whole
+ picture is one self-contained composition. It owns its background surface, its elements, its
+ reveal and its motion.
+- Author it as one component that owns all of it. Never as a generated base plus a separate text or
+ overlay Track: that split makes the background unreproducible and scatters one visual system
+ across unrelated tags with no shared timing.
+- Text drawn over a depicted scene stays an overlay on that scene. Only a picture whose entire field
+ is designed becomes a composition of its own. A framed graphic occupying part of a scene is an
+ inserted element, and the same ownership rule applies inside its frame.
+- If no installed package owns the composition, that is a real vocabulary gap. Read
+ `../../local-author-package.md` and build the package. Do not approximate it with tags that own a
+ different role.
+
+## Material and structure are sourced differently
+
+Every visible thing is either depicted material or drawn structure.
+
+- **Depicted material** is what a picture must show: scenes, people, products, textures, paper and
+ backdrop surfaces, artwork, screenshots, and any picture sitting inside a frame, card, device or
+ inset.
+- **Drawn structure** is what the composition computes: text content, exact font, size, weight,
+ spacing, alignment, colour, stroke, shadow, glow, frames, borders, corner radius, padding, stack
+ order, placement, reveal order and timing.
+
+Never bake drawn structure into generated material. A generated picture of text cannot be re-timed,
+re-read or corrected, and its wording drifts. A card, inset, phone, browser or screenshot element is
+not one picture: its inner picture is material, its frame and entry are structure.
+
+## Missing material must be generated
+
+- Source depicted material in this order: material supplied for the task or already in the project;
+ an Artifact the project already produces; otherwise generation.
+- If a required picture does not exist, generating it is mandatory. Do not substitute flat colour, an
+ empty frame, a placeholder, a stand-in borrowed from elsewhere, or a silently emptied element. A
+ picture inside a card is part of the work, not decoration.
+- Choose the generating package by inspecting what is installed at that moment: read the declared
+ inputs, outputs and Recipe properties of every installed package whose declared output is the
+ required media type, then choose. Never assume a package name from memory or from another project,
+ and never write a tag before its declaration has been read.
+- Static material is generated as an image. Generate video only when the element is a moving depicted
+ scene.
+- Generate one material per depicted thing, at the aspect ratio it will be used at, carrying only
+ what it depicts. Keep captions, labels, arrows, badges and titles out of the prompt; the
+ composition draws those.
+- Pass every generated image through the image gate in `production-gates.md` before connecting it
+ downstream, and pin accepted Records for reuse.
diff --git a/.agents/skills/hypit/references/playbooks/index.md b/.agents/skills/hypit/references/playbooks/index.md
index 3e808557..b61be434 100644
--- a/.agents/skills/hypit/references/playbooks/index.md
+++ b/.agents/skills/hypit/references/playbooks/index.md
@@ -6,7 +6,8 @@ needed for that craft or format.
## Required load order
-1. Always read `craft/production-gates.md` and `craft/visual-continuity.md`.
+1. Always read `craft/production-gates.md`, `craft/visual-continuity.md`, and
+ `craft/graphic-compositions.md`.
2. Read `craft/seedance-directing.md` whenever the Author Source invokes Seedance.
3. Read the selected format file and only the additional craft files it names.
4. Read `packages/<name>/README.md` for every package whose elements you write, and the relevant
@@ -48,6 +49,8 @@ needed for that craft or format.
- `craft/production-gates.md` — staged Targets, image review, paid generation, and explicit reuse.
- `craft/visual-continuity.md` — identity, shot groups, reverse-view geometry, and prop invariants.
+- `craft/graphic-compositions.md` — what counts as a base picture, full-screen graphic compositions,
+ and where missing material comes from.
- `craft/image-prompt-style.md` — English reference-image prompts and camera geometry.
- `craft/seedance-directing.md` — Kit selection, Recipe axes, references, and motion direction.
- `craft/b-roll.md` — story-led silent inserts and semantic placement.
diff --git a/.agents/skills/hypit/references/reference-video/continuity.md b/.agents/skills/hypit/references/reference-video/continuity.md
index 63731598..f70dc3ab 100644
--- a/.agents/skills/hypit/references/reference-video/continuity.md
+++ b/.agents/skills/hypit/references/reference-video/continuity.md
@@ -21,3 +21,30 @@ These invariants override superficial layer order and shot boundaries:
Shot boundaries are observation windows, not authoring units. Never generate independent SVML per
shot and concatenate it afterward.
+
+## A system that spans shots is authored once
+
+- A visual system that persists across cuts — captions, a running list that keeps its state, a
+ progress indicator, a persistent badge or logo, a recurring lower third — is one system: one
+ Program, one Track and one shared Style over its full observed lifetime, even when the visible
+ words, items or values change.
+- Do not recreate the system per shot, and do not create a second Style because a new shot begins. A
+ new shot is never itself evidence of a change in appearance.
+- Author an observed local difference as a scoped variation inside the one system, on exactly the
+ words, items or interval where it was observed.
+- Whether the system is one Program with per-item timing or separate instances is decided by the
+ declared vocabulary of the chosen package, never by shot count.
+- The `persistent_systems` observation from `prepare_reference` reports these systems for the whole
+ reference, including whether each one's appearance ever changes and where. Use it instead of
+ inferring lifetimes from per-shot prose.
+
+## Base pictures and designed fields
+
+What may be a base picture at all, when a full screen is one graphic composition rather than a
+generated base plus an overlay, and where a missing picture comes from, are decided by
+`../playbooks/craft/graphic-compositions.md`. Read it; the rules there are not restated here and are
+not weakened by any observation, package convenience or check result.
+
+Each shot's `visual` observation states explicitly whether the frame is a depicted scene or a flat
+designed field, and describes each framed element's inner picture separately from its frame. That
+answer is the evidence for this decision.
diff --git a/.agents/skills/hypit/references/reference-video/final-sources.md b/.agents/skills/hypit/references/reference-video/final-sources.md
index 8f66e080..e81038b7 100644
--- a/.agents/skills/hypit/references/reference-video/final-sources.md
+++ b/.agents/skills/hypit/references/reference-video/final-sources.md
@@ -1,7 +1,8 @@
# Reference-video final sources
After every required package exists and its vocabulary has been read, read
-`../authoring.md` completely and write one complete project:
+`../authoring.md` completely, then read `../playbooks/index.md` and the craft files it names for the
+systems this reference actually contains, and write one complete project:
- `main.svml` describes the whole video in original time order, keeps continuing base/sound intact,
and represents one continuing overlay as one visual track.
@@ -24,3 +25,6 @@ pnpm hypit check path/to/build.svrun
Fix package resolution and package implementation before repairing source use. Continue until all
three files are accepted. Do not create `check_svml_project` or another wrapper.
+
+Accepted checks end the structural work, not the reconstruction. Every element you authored still has
+to be rendered and compared against the reference under `reconstruction-loop.md`.
diff --git a/.agents/skills/hypit/references/reference-video/index.md b/.agents/skills/hypit/references/reference-video/index.md
index f51812da..bc117e9a 100644
--- a/.agents/skills/hypit/references/reference-video/index.md
+++ b/.agents/skills/hypit/references/reference-video/index.md
@@ -7,9 +7,13 @@ visual and audio evidence only.
Before acting, read these files completely in order:
1. `workflow.md` — CLI sequence, evidence flow and responsibility boundaries.
-2. `continuity.md` — mandatory shot, overlay, B-roll, speaker and product rules.
-3. `vocabulary.md` — existing-package selection and the route for a real vocabulary gap.
-4. `final-sources.md` — complete source authoring and check loop.
+2. `continuity.md` — mandatory shot, overlay, B-roll, speaker, product and persistent-system rules.
+3. `../playbooks/craft/graphic-compositions.md` — what may be a base picture, when a full screen is
+ one authored composition, and where a missing picture comes from.
+4. `vocabulary.md` — existing-package selection, appearance-property resolution, and the route for a
+ real vocabulary gap.
+5. `reconstruction-loop.md` — rendering what was built and comparing it against the reference.
+6. `final-sources.md` — complete source authoring and check loop.
Paths above are relative to this file's directory. Do not skip a file because the task looks like a
familiar video format.
diff --git a/.agents/skills/hypit/references/reference-video/reconstruction-loop.md b/.agents/skills/hypit/references/reference-video/reconstruction-loop.md
new file mode 100644
index 00000000..15636a9d
--- /dev/null
+++ b/.agents/skills/hypit/references/reference-video/reconstruction-loop.md
@@ -0,0 +1,58 @@
+# Closing the loop on what was built
+
+Structural checks prove that a source is legal. They prove nothing about whether it looks like the
+reference. A newly written package can resolve, activate, decode and pass every check while drawing
+something the reference never contained. Close that gap deliberately.
+
+## The reference side is finished
+
+The reference video does not change. Its observations are cached and authoritative. Re-observing at a
+fixed temperature of `1.0` buys paraphrase drift and another bill, so never re-run a completed
+observation to "check" it. `--reobserve` exists for a shot whose media was rebuilt, not for doubt.
+
+Everything in this file happens on the reconstruction side, which changes every time a package,
+Recipe or source edge is edited.
+
+## The loop unit is one element
+
+Loop over one reconstructed element at a time — the new component, one caption system, one inserted
+card:
+
+1. Render that element to a still image locally, without a paid Provider. A new package's visual
+ Surface needs a preview image anyway, as `../local-author-package.md` requires. The repository's
+ own visual test `packages/hyperframes/test/browser-visual.test.ts` shows the local path end to
+ end: build the Track, compile the HyperFrames document, and render it through the local
+ HyperFrames Runtime.
+2. Compare it against the reference frame that shows it most clearly:
+ `.hypit/reference-video-tools/<reference-id>/shots/NNN-representative.jpg`.
+3. Repair, then render again.
+
+The SVML Playground in `../preview.md` is a browser preview for a person to look at. It is not a
+source of the image this loop needs.
+
+Repairing one element never re-runs the others. Do not rebuild the whole video to inspect one piece,
+and do not defer every comparison to a final delivery Build.
+
+## Comparison is blind
+
+Use `compare_reconstruction --reference-id <id> --shot-id <id> --image <rendered.png>`.
+
+- Never tell the observer which image is the reconstruction, what was built, which component drew it,
+ or what you expect to be wrong. An observer told what to confirm will confirm it.
+- The only permitted extra input is scope, through `--question`: which region of the picture to look
+ at, and nothing else.
+- Results are not cached. Every iteration is a fresh comparison.
+
+## Repair in dependency order
+
+When the difference is structural rather than cosmetic, repair in the order given by
+`../local-author-package.md`: package and workspace resolution, activation contribution, Manifest,
+Producer, Type and Validator agreement, Surface vocabulary and decoding, implementation behaviour,
+then source usage. Fixing source usage over a broken implementation hides the defect one layer down.
+
+## Converged means the differences are wording
+
+Stop when the returned differences are wording-level — a describer's phrasing rather than a visible
+change — or when a remaining difference is explicitly recorded as an accepted deviation with its
+reason. Passing `pnpm check` and `hypit check` is not convergence; it is the precondition for
+starting the loop.
diff --git a/.agents/skills/hypit/references/reference-video/vocabulary.md b/.agents/skills/hypit/references/reference-video/vocabulary.md
index 3c500f12..a1429da2 100644
--- a/.agents/skills/hypit/references/reference-video/vocabulary.md
+++ b/.agents/skills/hypit/references/reference-video/vocabulary.md
@@ -4,6 +4,12 @@ After observations, select candidate packages and run `inspect_svml_vocabulary`.
package README as syntax authority. Compare the observation against declared inputs, outputs,
attributes, children, ports, Recipe properties, timing behavior, appearance and examples.
+First enumerate every system the reference actually contains — base pictures, inserted elements,
+full-screen graphic compositions, persistent overlays, captions, speech, music, sound effects — and
+inspect candidates for each one. A system you never inspected is a system you are about to invent.
+`inspect_svml_vocabulary` does not list what is installed; it reads the packages you name. Discover
+candidate names from `docs/guide/packages.md` and the `packages/` directory before inspecting.
+
Use this decision order:
1. Reuse one existing component when it fully expresses the observation.
@@ -12,10 +18,42 @@ Use this decision order:
3. Declare a real vocabulary gap only when neither option works.
Do not force a similar-looking tag into a role it does not own. Do not invent attributes or write a
-nonexistent tag with the intention of implementing it later.
+nonexistent tag with the intention of implementing it later. A picture that
+`../playbooks/craft/graphic-compositions.md` defines as one self-contained graphic composition may
+never be split across unrelated tags to make installed vocabulary fit.
+
+## Resolve every declared appearance property
+
+Declared vocabulary tells you which properties exist. Only observation tells you their values.
+
+- After inspection, list the declared properties that change what the viewer sees and are not yet
+ resolved by evidence: exact font and weight, size, line height, alignment, colour, stroke colour
+ and width, shadow colour, offset, blur and opacity, glow, emphasis or active-item treatment, frame
+ geometry, corner radius, border, padding, stack order, and reveal or typing rhythm.
+- Each shot's `text_appearance` observation already describes drawn type in these terms. Read it
+ before asking anything.
+- Resolve what remains with a narrow `observe_reference --question` over the one to three shots where
+ the element is most legible. Ask about visible attributes, never about components or syntax. A
+ question costs one request and does not disturb cached observations.
+- A default value is not an observation. Accepting one is allowed only as a recorded deviation after
+ the evidence came back inconclusive.
+- Read a persistent system's appearance from the shots where it is clearest and apply it to the whole
+ system, as `continuity.md` requires.
+
+## Real gaps
For a real gap, stop final-source authoring and read
`../local-author-package.md` completely. Implement and install the new project-local package, then
-run `inspect_svml_vocabulary` against it before using its tag. The reference-video CLI remains
-limited to observation and vocabulary inspection; it does not generate components. Gemini does not
-write the package.
+run `inspect_svml_vocabulary` against it before using its tag. That call is not redundant with having
+just written the package: it proves the specifier resolves, the activation contribution is wired, and
+the loader can decode the Surface. `pnpm check` proves none of those, because activation lookups fail
+at runtime rather than at compile time.
+
+The new package owns the whole observed composition, including the surface its elements sit on, and
+consumes missing pictures as material edges rather than generating or embedding them itself.
+
+Installing the package is not the end of the gap route. Continue into `reconstruction-loop.md`: a
+component that loads is not yet a component that looks like the reference.
+
+The reference-video CLI remains limited to observation, vocabulary inspection and blind image
+comparison; it does not generate components. Gemini does not write the package.
diff --git a/.agents/skills/hypit/references/reference-video/workflow.md b/.agents/skills/hypit/references/reference-video/workflow.md
index 6b35e34f..6efd7784 100644
--- a/.agents/skills/hypit/references/reference-video/workflow.md
+++ b/.agents/skills/hypit/references/reference-video/workflow.md
@@ -1,47 +1,92 @@
# Reference-video workflow
-The public interface is exactly three CLI subcommands from `@hypit/reference-video-tools`:
+The public interface is exactly four CLI subcommands from `@hypit/reference-video-tools`:
```bash
hypit-reference-video-tools prepare_reference --video-path <path>
hypit-reference-video-tools observe_reference --reference-id <reference-id>
hypit-reference-video-tools inspect_svml_vocabulary --package <package> --tag <tag>
+hypit-reference-video-tools compare_reconstruction --reference-id <reference-id> --shot-id <shot-id> --image <path>
```
-Defaults are sufficient for normal use. When a completed preparation stage needs to be rerun, use
-one of the small `--redo` values:
-
-```bash
-hypit-reference-video-tools prepare_reference --video-path <path> --redo people
-```
-
-Use `--redo media` to rebuild shot media and clear derived observations, `--redo voices` for the
-whole-reference voice pass, or `--redo all` for every preparation stage. For observation, omit shot
-IDs to process all unfinished work. Supplying `--shot-id` one or more times forces those shots and
-their adjacent continuity boundaries to run again; three continuous IDs also trigger the three-shot
-continuity review. Add one `--question` for a narrow follow-up. The tool always attaches the
-preceding tail frame, audio tail and full-reference people/voice/product evidence automatically.
-
-Each also accepts `--input <json>`. Follow this sequence:
+Defaults are sufficient for normal use. Each also accepts `--input <json>`. Follow this sequence:
```text
prepare_reference
→ observe_reference for all shots
-→ narrow observe_reference follow-ups for unresolved conflicts
+→ narrow observe_reference questions for unresolved appearance and conflicts
→ inspect_svml_vocabulary for candidate packages
→ develop a project-local package only for a proven vocabulary gap
→ author complete main.svml, studio.svs, build.svrun
→ use existing checks and repair until legal
+→ render each authored element and close the loop with compare_reconstruction
+```
+
+## prepare_reference
+
+`prepare_reference` deterministically prepares clips, representative frames, tail frames, audio tails
+and storyboard context, then obtains three whole-reference observations: `people_and_product`,
+`voices`, and `persistent_systems` — the on-screen text and graphic systems that continue or recur
+across the whole video, each one's lifetime, and whether its appearance ever changes.
+
+When a completed preparation stage must be rerun, use one small `--redo` value:
+
+```bash
+hypit-reference-video-tools prepare_reference --video-path <path> --redo people
+```
+
+`--redo media` rebuilds shot media and clears every derived observation. `--redo people`,
+`--redo voices` and `--redo systems` rerun one whole-reference stage. `--redo all` reruns everything.
+
+## observe_reference
+
+Omit shot IDs to process all unfinished work; supply `--shot-id` one or more times to work on
+selected shots. Each shot produces three observations:
+
+- `visual` — the base picture, covering and non-covering content, continuity from the preceding shot,
+ whether the frame is a depicted scene or a flat designed field, and each framed element's inner
+ picture described separately from its frame;
+- `text_appearance` — the typeface character, weight, size, spacing, alignment, colour, stroke,
+ shadow, glow, per-word emphasis, position and entry of text drawn over the picture;
+- `audio` — who is speaking, and what continues from the previous shot.
+
+Boundary pairs additionally produce same-take and overlay-continuity observations, and a window of
+three consecutive shots triggers a three-shot continuity review. The preceding tail frame, audio tail
+and full-reference evidence are attached automatically; do not reconstruct that context by hand.
+
+Completed observations are reused. Naming a shot does not re-run it. `--reobserve` is the only way to
+run a completed observation again, and it exists for rebuilt media, not for doubt.
+
+`unresolved` lists the keys of observations that failed outright. It is not a judgement about
+evidence quality: a complete observation that says "unclear" is still complete, and that is what a
+narrow question is for.
+
+## Narrow questions
+
+`--question` is a separate path. It requires one to three `--shot-id` values, answers only that
+question from those shots' clips and frames in a single request, and neither reads nor writes the
+observation cache:
+
+```bash
+hypit-reference-video-tools observe_reference --reference-id <id> --shot-id shot-007 \
+ --question "How thick is the outline on the caption words, relative to the stroke width of the letters?"
```
-`prepare_reference` deterministically prepares clips, representative frames, tail frames, audio
-tails and storyboard context, then obtains whole-reference people/product and voice observations.
-`observe_reference` automatically attaches the preceding tail frame/audio tail and whole-reference
-context. The main agent does not manually reconstruct this context.
+Ask about visible attributes. Never ask which component to use.
+
+## compare_reconstruction
+
+`compare_reconstruction` sends the shot's reference frame and a rendered image as an unlabelled pair
+and returns a description of their visible differences. It is never told which image is which, what
+was built, or how; `--question` may narrow it to one region of the picture and nothing else. Results
+are not cached. `reconstruction-loop.md` governs when and how to use it.
+
+## Boundaries
Gemini returns natural language only. Never send it SVML syntax, package declarations, vocabulary,
-previews or implementation code. Never ask it to write SVML, SVS, SVRun, a structured reference
-plan, component names or TypeScript. It is evidence, not the final decision maker.
+previews or implementation code. Never ask it to write SVML, SVS, SVRun, a structured reference plan,
+component names or TypeScript. Never tell it what you built or what you expect it to find. It is
+evidence, not the final decision maker.
Inspect every failed or unresolved result. Follow up with one narrow question over one to three
relevant shots rather than repeating the entire analysis. Preserve successful cached observations