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.

docs(hypit): close the gaps a full run through the route exposed

rponefcdb560da700
diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.md
index dd996e11..92145fda 100644
--- a/.agents/skills/hypit/references/environment.md
+++ b/.agents/skills/hypit/references/environment.md
@@ -116,6 +116,12 @@ WhisperX, for example, lives under `programs/whisperx/`; OpenCV under
`programs/image-opencv/`. Service process records and logs live with the program. Project Build and
Worker state remains under `<project>/.hypit/`.
+Reference-video state joins it there, at `.hypit/reference-video-tools/<reference-id>/`, resolved
+against the directory the command ran in rather than against a project boundary. Run every
+`hypit-reference-video-tools` command that touches a reference from the same directory: the clips,
+frames, transcript and observations one command writes are what the next one expects to find at that
+relative path.
+
This split is why opening a second project cannot install WhisperX again, and why updating the npm
Distribution does not overwrite a Python environment or a user's project-local component.
@@ -132,3 +138,10 @@ changes an exact adapter dependency, the next explicit `runtime up` lets npm upd
Only someone changing Hypit itself clones the repository. In that checkout, follow
`docs/guide/develop.md` and use its pinned pnpm version and official `pnpm-lock.yaml`. Never place an
author project or its local packages inside that checkout.
+
+A project directory carries its own `package.json` — a name and `"private": true` is the whole file,
+since nothing reads its fields. `hypit check`, `plan` and `build` locate the package root by walking
+up from the project until some `package.json` appears; the file is what stops that walk at the
+project, so `packages/local-<slug>/` resolves from there rather than from whichever ancestor
+directory happened to hold one. It is matched by no `pnpm-workspace.yaml` glob and adds the project
+to no workspace.
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index c517a254..9d78c48e 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -30,27 +30,31 @@ not. Everything after them is specific to this component and cannot be copied fr
**Read this whole file first.** The rules that decide what the package is — read the observation
before shaping it, a media slot is an input port, the package draws its own chrome, the Types are
-frozen before parallel writing — are in this file, and they apply before any other reading. Do not
-jump to the closest package and start copying roles before these rules are in front of you; the
-rules here are the contract, the closest package is only a shape to learn from.
+frozen before parallel writing — are in this file, and they apply before any other reading.
Then read:
-1. `../../../../docs/guide/component-anatomy.md` — the roles every component package fills, and how to find each
- one in an existing package. Read this first; it is what the rest is measured against.
+1. `../../../../docs/guide/component-anatomy.md` — the roles every component package fills. Read this
+ first; it is what the rest is measured against.
2. `../../../../docs/guide/author-packages.md`
3. `../../../../docs/guide/packages.md` and `../../../../docs/guide/conventions.md`
4. the installed `@hypit/component-kit` README
-Use `hypit paths --json` to locate the installed Distribution. Then open the closest existing
-package there and read **the roles you are about to write**, not the package
-end to end. Anatomy names them; find them by what they export, since the filenames differ — `ranking`
-calls two of them `schedule.ts` and `render.ts`, `media-track` calls them `program.ts` and `lower.ts`,
-`comment-sticker` calls them `program.ts` and `author.ts`.
+**Write the package from those docs.** They state each role, what it declares and what it hands the
+next one, and that is what a new package is built out of. Author every file yourself against them:
+the Manifest, the Types, the Surface and decoder, the Producers, the Fragment.
-Read for shape: how a Program becomes elements, where timing is resolved, what the Fragment declares.
-Those files run to a couple of thousand lines between them, and copying one package's specifics is a
-worse outcome than understanding its structure — which is what anatomy is for.
+Open a package's source when the docs genuinely do not settle a question — a role whose shape the
+guide leaves implicit, an export whose signature you need exactly. Use `hypit paths --json` to locate
+the installed Distribution and read **the one role you are stuck on**, not the package end to end.
+Find it by what it exports, since the filenames differ: `ranking` calls two of them `schedule.ts` and
+`render.ts`, `media-track` calls them `program.ts` and `lower.ts`, `comment-sticker` calls them
+`program.ts` and `author.ts`.
+
+Check every signature you take that way against the current package's exports before you rely on it.
+A call read out of any source that is not the installed Distribution — an older project in the same
+checkout, a snippet in an issue, something you remember — is a name that may no longer exist, and
+what it costs is a compile error at the end of a package rather than at the line that borrowed it.
## Package boundary
@@ -59,24 +63,17 @@ Place the package at `<project>/packages/local-<slug>/`, named in the project's
version `0.0.0-dev` and logical Module version `1`. Only create a new package: do not
edit, extend, delete or overwrite an existing Hypit package to fill the gap.
-**Starting that new package from a copy of the closest installed one is allowed, and is usually the
-right way to do it.** The ban is on modifying a package other projects share, not on learning from
-its source: a Style family that differs from `caption-fine` in its timing model, or a board that
-differs from `ranking` in its rows, is most of that package again. Copy it, then make it genuinely
-its own — a new Module ref, a new name for every nominal Type it declares, since a Type belongs to
-the Module that declares it, and new Producer names. Leave the original untouched. The official
-packages are built for exactly this: `caption-fine` states that Common Caption, Composition and Core
-know none of its Recipe fields or layout policy, and `deck-track` that another Deck family can
-install independently and lower to the same terminal `VisualTrack` without changing it. A sibling
-family is the designed extension point, not a workaround.
-
-Read "modelled on the installed packages" that way wherever it appears. Writing two thousand lines
-from scratch to avoid a copy is not more correct, and the ban does not ask for it.
-
-What a copy does cost is upstream: it will not receive the fixes the original gets, and nobody will
-notice it drifted. That is acceptable for a project-local package, which is part of one deliverable
-rather than a library. If the behaviour turns out to be generally useful, that is the promotion this
-section already describes — not a reason to add a parameter to the shared package after all.
+The package it stands beside is untouched. A Style family that differs from `caption-fine` in its
+timing model, or a board that differs from `ranking` in its rows, installs as a sibling: its own
+Module ref, its own name for every nominal Type it declares, since a Type belongs to the Module that
+declares it, and its own Producer names. The official packages are built for exactly this —
+`caption-fine` states that Common Caption, Composition and Core know none of its Recipe fields or
+layout policy, and `deck-track` that another Deck family can install independently and lower to the
+same terminal `VisualTrack` without changing it. A sibling family is the designed extension point,
+not a workaround.
+
+Read "modelled on the installed packages" that way wherever it appears: the same role in the same
+place in the graph, written for this component from the anatomy the guide states.
The project is never the Hypit Distribution. Do not move a local package into an official package
automatically. After the result is accepted, offer promotion as a separate contribution.
@@ -87,6 +84,15 @@ only Studio interpretation and operations through `hypit.studio-adapter@1`; it n
`packages/studio`, and the author package never imports Studio. A generic block is valid while no
special interpretation is needed.
+Know what that fallback gives it, because it is enough for a lot of packages. The `visual-track` rule
+in `packages/studio-video-adapters/src/generic.ts` declares no module filter, and a rule that
+declares none matches whatever the module is, so a project-local Track producing a `VisualTrack`
+lands there and gets `role: "track"`. Studio draws it in a flat media lane and exposes five timing
+parameters — `start`, `end` and `for` writable, `during` and `at` read-only — over a read-only
+interaction: the block can be selected and seeked, not dragged or trimmed. A companion package is
+what buys anything past that: parameters named for what the component actually has, child entities,
+and a lane laid out the way it is shaped.
+
## Complete implementation
The main agent writes all code. Gemini must not receive or produce TypeScript, `package.json`,
@@ -103,7 +109,7 @@ Implement the parts required by the behavior, including:
- README and a preview for each visual Surface.
Choose raw versus structured Surface, timing dependencies, ProgramSpace, Frame, SemanticTrack,
-Artifact, Recipe and output Types from the observed behavior and closest package architecture. A
+Artifact, Recipe and output Types from the observed behavior and the anatomy the guide states. A
declaration-only or Surface-only package is incomplete.
## The package draws itself
@@ -210,12 +216,14 @@ the preview check and repair until it passes — a graph failure is not a differ
work that is not finished, and it is not bounded by the loop's attempt ceiling:
```bash
-hypit-preview-check path/to/build.svrun
+hypit-reference-video-tools preview_check path/to/build.svrun
```
-It takes the Run Source, not the `.svml`. A pass here means the graph reaches a Film and a semantic
-spine; it exits zero while the Providers are still unrun, and says which capabilities it is waiting
-on. See `preview.md` for what that does and does not prove — notably, a
+It takes the Run Source, not the `.svml`. `preview.md` says why this spelling rather than the
+`hypit-preview-check` bin: the subcommand honours `--package-root`, which is what a project-local
+package needs when the Run is not at the project root. A pass here means the graph reaches a Film and
+a semantic spine; it passes while the Providers are still unrun, and says which capabilities it is
+waiting on. See `preview.md` for what that does and does not prove — notably, a
Producer that refuses the media kind it is handed is not caught here, because nothing is handed to
it until the Build runs.
diff --git a/.agents/skills/hypit/references/playbooks/craft/captions.md b/.agents/skills/hypit/references/playbooks/craft/captions.md
index 79513e99..c375b500 100644
--- a/.agents/skills/hypit/references/playbooks/craft/captions.md
+++ b/.agents/skills/hypit/references/playbooks/craft/captions.md
@@ -22,9 +22,10 @@ them stale, they are unreachable by anything that reasons about captions, and th
them checkable is gone.
When the caption vocabulary cannot express the appearance, that is a vocabulary gap and it is
-declared as one. Write a new project-local caption package modelled on the installed caption
-packages — read them as the pattern for Style, Program, planning and alignment — and drive it from
-the same Script and map. Reaching for a typography Track because it already draws the shape is the
+declared as one. Write a new project-local caption package that fills the same roles the installed
+caption packages fill — Style, Program, planning and alignment — and drive it from the same Script
+and map. `../../local-author-package.md` says where those roles are stated and when a package's own
+source is worth opening. Reaching for a typography Track because it already draws the shape is the
mistake this section exists to prevent.
Text that is *not* a caption keeps its own vocabulary: a title nobody says, a lower third, a label on
@@ -65,6 +66,21 @@ exact font → caption-fine:Style → caption:Program
Add `{captions.track}` to `film:Film` as one peer Visual Track. If the format intentionally has no
captions, omit the Caption components entirely.
+## A Fine Caption Recipe writes eleven keys or it throws
+
+`caption-fine:Style` requires `align`, `background`, `fill`, `line-height`, `padding`, `radius`,
+`size`, `stack-order`, `width`, `x` and `y`. None of them has a fallback: a Recipe missing one is
+refused when the Style decodes, before anything draws.
+
+The three that get left out are the box keys — `background`, `padding` and `radius` — because a
+design that wants no Cue box reads as having nothing to say about them. Write them anyway: an
+invisible box is `background="#00000000"` with `padding` and `radius` at `0`, which is a value, not
+an omission.
+
+`cue-min-words` and `cue-max-words` are not read. `docs/quickstart/styles.md` and
+`docs/quickstart/composition.md` still show them; a Recipe carrying either is refused as an unknown
+property, since the Style admits exactly the required keys plus the documented optional ones.
+
## Keep the Script authoritative
- Preserve the exact Script display text. Do not copy burned-in reference subtitles or rewrite the
diff --git a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
index 0896e49e..ced741cd 100644
--- a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
+++ b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
@@ -191,6 +191,31 @@ default to `none`, and a Recipe named for a cut that fades for a frame is one of
`production-gates.md` measures the delivery for these before it is reported as finished.
+## A Selection carries two edges; a Moment carries one
+
+Both name time in the Script's own words, and which to reach for follows how many edges the words
+fix.
+
+- **Both edges are spoken.** `@id` … `@/id` opens and closes a Selection around the stretch, and
+ `during={story.selection.X}` spans its first word to its last. That is what the tiling above is
+ about: an insert that arrives on a phrase and leaves on another, one Selection picking up where the
+ last left off.
+- **One edge is spoken and the other is decided elsewhere.** `@id!` marks a Moment — a point, not a
+ range, right-absorbing at the next word's start, `~@id!` left-absorbing at the previous word's end.
+ Give the element the span it actually occupies and let the Moment cut it: `during="program"
+ until={story.moment.X}` runs from the start of the program to that word, and `at={story.moment.X}`
+ places a single arrival there. A Deck that stacks cards as they are named and clears on a word
+ reads this way.
+
+A Selection is free to open in one Segment and close in another. Each end records its own Segment,
+and nothing closes it at the boundary — the only refusal is `SCRIPT_SELECTION_UNCLOSED`, raised after
+the whole Script is read for a Selection with no close marker anywhere. Selections may also cross one
+another; they do not nest like tags. What a Selection crossing a Segment does cost is upstream: the
+Segment is the generation boundary the section above describes, so a window spanning two of them
+spans two Takes and two seams.
+
+Selection and Moment share one name namespace, so the same id cannot be both.
+
## A short stretch is not a short take
An authored take stays inside the selected model's declared duration range — read the range from the
diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.md
index 1699d7fe..2608959e 100644
--- a/.agents/skills/hypit/references/preview.md
+++ b/.agents/skills/hypit/references/preview.md
@@ -12,13 +12,25 @@ a new package with a bad schedule, a target that is not an output, a Film with n
composition. Find that now, not on the author's screen:
```bash
-hypit-preview-check /path/to/project/build.svrun
+hypit-reference-video-tools preview_check /path/to/project/build.svrun
```
It takes the Run Source, not the Author SVML — Studio's unit of work is the Run, and it reads the
`.svml` back out of it.
-It exits non-zero when the graph itself is wrong, and it names what refused — a target that is not a
+The same check is also a bin of its own:
+
+```bash
+hypit-preview-check /path/to/project/build.svrun
+```
+
+Prefer the subcommand. It honours `--package-root`, so it reaches a project's own
+`packages/local-<slug>/` from wherever you are standing, and it is a subcommand of the bin the
+reconstruction route already runs. The bare bin fixes the package root to the Run file's own
+directory and takes no flags, so reach for it when the Run sits at the project root and you want the
+prose summary rather than a JSON result.
+
+Either one refuses when the graph itself is wrong, and names what refused — a target that is not a
Film or Render output of the current SVML, a Film with no traceable composition, a Film with no
`SemanticTake` / Speech Track chain. This is not a guessing problem: the error says what is wrong, and
you repair that. A graph that does not trace is not done, and **every failure it reports must be
@@ -29,7 +41,8 @@ rather than performing it leaves the closure waiting on Providers, and Studio re
closure before it will open. That is the expected state of a Source nobody has built yet, not a defect
in it. When every issue is `the Studio projection closure requires unresolved capabilities: …`, the
graph traced all the way to a Film and a semantic spine, and what remains is work a Provider has to
-do — the script prints the waiting capabilities and exits zero:
+do. The subcommand returns `"sound": true` with the capabilities under `awaiting`; the bin prints
+them and exits zero:
```
preview-check: the graph is sound, waiting on 6 capabilities.
diff --git a/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.md
index 5fdb7d82..99935aab 100644
--- a/.agents/skills/hypit/references/reconstruction/index.md
+++ b/.agents/skills/hypit/references/reconstruction/index.md
@@ -71,7 +71,11 @@ discoverable:
- **Where you are, and what is installed.** `../environment.md`.
- **Where the project goes.** Its own directory outside the installed Distribution, normally
`<home>/<something>-reverse/`, named after the video. `../runtime.md` defines the hard boundary.
- Use a directory the author named only if they named one.
+ Use a directory the author named only if they named one. Give it a `package.json` when you create
+ it — a name and `"private": true`, nothing else, since no field in it is read. `hypit check`,
+ `plan` and `build` find the package root by walking up from the project until a `package.json`
+ appears, so the file is what stops that walk at the project and lets `packages/local-<slug>/`
+ resolve. It is matched by no `pnpm-workspace.yaml` glob, so it enrolls the directory in nothing.
- **Credentials.** A project may keep them in an uncommitted `.env`; load it as shown below. A variable a Provider
needs and this machine does not hold is named, and the route stops there — with one exception, the
Vertex pair, which selects an observer rather than blocking one. `observers.md` owns that.
diff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
index da56a11f..11bb4872 100644
--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
+++ b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
@@ -58,6 +58,11 @@ hypit-reference-video-tools render_element projects/<name>/build.svrun \
--element <id> --segment <id>|--selection <id> --out <path>.mp4
```
+`--element` takes the element's bare id — `captions`, the `id=` the Source wrote on the element. The
+command appends the output suffix itself when it looks for the track, so `--element captions.track`
+matches nothing: it refuses with `the Source places no element named captions.track` and lists the
+bare ids that are placed.
+
It reads the Canvas, the Recipe values and the Script text out of the Source, stands in for the
speech with the Source's own `estimate:Speech`, mocks every layer a Build has not made, and drives
the package's Producer. Nothing is transcribed by hand, so nothing is transcribed one line at a time
@@ -96,6 +101,22 @@ A mock lives only in this render. It is never written into the Source, and no ga
`playback` check in `reconstruction_check` reads the Source's Recipes, so a mock cannot be mistaken
for coverage.
+### The derived Run holds one Segment, not the whole Source
+
+The mocks are substituted into a Source that has already been cut to the window. `render_element`
+keeps the Segment the window names, drops the rest of the Script, and then drops every element that
+named a Segment, Selection or Moment that went with it — and every element naming one of those, to a
+fixed point, plus any container the cut left with no children. So an element bound to a Selection or
+Moment in another Segment is not in this render, and its absence says nothing about the Source.
+
+The cut Source is on disk at `<project>/.hypit/compare/sliced.svml`, byte-for-byte from the original
+except for what was removed, and the derived Run sits beside it. Open it whenever something you
+expected to see is not in the picture: an element that is not in the fragment was cut by the window,
+and one that is in the fragment and still not on screen is the package failing to draw it. Those two
+repair in opposite directions, and the fragment is what tells them apart.
+`packages/reference-video-tools/src/slice.ts` records the same thing as `SliceResult.dropped` — each
+dropped id and the name it could no longer reach — and explains what decides survival.
+
### Compare the whole stretch, against every stretch the element is drawn over
Compare clips, not chosen frames:
diff --git a/.agents/skills/hypit/references/reconstruction/workflow.md b/.agents/skills/hypit/references/reconstruction/workflow.md
index 1c29d19a..f846311a 100644
--- a/.agents/skills/hypit/references/reconstruction/workflow.md
+++ b/.agents/skills/hypit/references/reconstruction/workflow.md
@@ -23,6 +23,15 @@ video. This route runs both, at the step the sequence names;
`node_modules/@hypit` relative to the working directory and refuses when it is empty, so run it from
the repository root.
+**Run every `hypit-reference-video-tools` command that touches a reference from the same directory.**
+`prepare_reference` writes the reference under `.hypit/reference-video-tools/<reference-id>` relative
+to the working directory, and `observe_reference`, `record_observation`, `compare_reconstruction`,
+`render_element` and `reconstruction_check` all read it back from that same relative path. Run one
+from the project and the next from its parent and the second looks in a directory the first never
+wrote to: it reports no prepared reference at all. Pick one directory at the start and stay in it for
+the whole route — the repository root, where `list_svml_packages` already has to run, is the one that
+costs nothing. The two vocabulary subcommands carry no reference state and are outside this.
+
Defaults are sufficient for normal use. Each also accepts `--input <json>`. Follow this sequence:
```text
diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.md
index e50507d6..9cfaf82b 100644
--- a/.agents/skills/hypit/references/runtime.md
+++ b/.agents/skills/hypit/references/runtime.md
@@ -137,6 +137,10 @@ Relative Author Sources and assets stay inside the independently resolved Source
- `--workspace` explicitly selects the Source Workspace boundary.
- `--package-root` only changes where the Host locates installed packages. It does not widen Source
- access.
+ access. Reach for it when a project you did not create has no `package.json` of its own: `check`,
+ `plan` and `build` walk up from the project until one appears, so a project without one resolves
+ its packages against an ancestor directory, and a project package resolves to nothing. Run those
+ commands with `--package-root .` from the project, or write the project the `package.json`
+ `../environment.md` describes and drop the flag.
- Do not symlink an external project into the Distribution. The external directory is the intended
workspace, not an escape from one.