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
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.mdindex 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 andWorker 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 npmDistribution 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 updOnly 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 anauthor 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.mdindex 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 observationbefore 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'sversion `0.0.0-dev` and logical Module version `1`. Only create a new package: do notedit, 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 packageautomatically. 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 nospecial 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 implementationThe 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. Adeclaration-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 differwork 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, aProducer that refuses the media kind it is handed is not caught here, because nothing is handed toit until the Build runs.diff --git a/.agents/skills/hypit/references/playbooks/craft/captions.md b/.agents/skills/hypit/references/playbooks/craft/captions.mdindex 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 ththem 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 themistake 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:ProgramAdd `{captions.track}` to `film:Film` as one peer Visual Track. If the format intentionally has nocaptions, 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 thediff --git a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.mdindex 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 takeAn authored take stays inside the selected model's declared duration range — read the range from thediff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex 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 ncomposition. 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 aFilm 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, andyou 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 reclosure before it will open. That is the expected state of a Source nobody has built yet, not a defectin it. When every issue is `the Studio projection closure requires unresolved capabilities: …`, thegraph 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.mdindex 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 Providerneeds and this machine does not hold is named, and the route stops there — with one exception, theVertex 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.mdindex 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 thespeech with the Source's own `estimate:Speech`, mocks every layer a Build has not made, and drivesthe 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 mistakenfor 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 overCompare clips, not chosen frames:diff --git a/.agents/skills/hypit/references/reconstruction/workflow.md b/.agents/skills/hypit/references/reconstruction/workflow.mdindex 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 fromthe 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:```textdiff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.mdindex 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 intendedworkspace, not an escape from one.