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: name the roles a component package fills
rponeee535413fb32
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.mdindex 0badf3c5..bd4db621 100644--- a/.agents/skills/hypit/references/local-author-package.md+++ b/.agents/skills/hypit/references/local-author-package.md@@ -14,12 +14,16 @@ Read all of these completely before editing:4. `packages/component-kit/README.md`5. The closest existing package's README, `manifest.ts`, `surface.ts`, `component.ts`, and`activation.ts`-6. For a package that produces a visual output, that same package's `render.ts`, `schedule.ts` and- `fragment.ts` as well. The implementation section below requires a renderer, a Fragment and the- lowering between them, and none of those live in the five files above — reading only those five- means discovering the shapes by failing.--Read item 5's files in full. Read item 6's for their shapes: how a Program becomes elements, where+6. `docs/guide/component-anatomy.md`, which names the roles every component package fills and where+ each one lives. The implementation section below requires a renderer, a Fragment and the lowering+ between them, and none of those are in the five files above — reading only those five means+ discovering the shapes by failing.+7. In the closest existing package, the files filling the roles that anatomy names. Their filenames+ differ per package — `ranking` calls them `schedule.ts` and `render.ts`, `media-track` calls them+ `program.ts` and `lower.ts`, `comment-sticker` calls them `program.ts` and `author.ts` — so find+ them by what they export, not by name.++Read item 5's files in full. Read item 7's for their shapes: how a Program becomes elements, wheretiming is resolved, what the Fragment declares. They are long, and copying one package's specifics isa worse outcome than understanding its structure.@@ -78,9 +82,9 @@ nothing.## Freeze the Types before writing in parallelThe nominal Types and the Manifest are what every other file agrees with, so write them first and-stop changing them. Once they are frozen, `render.ts`, `style.ts` and `schedule.ts` depend on the-Types rather than on each other and can be written in any order or at the same time. `surface.ts`,-`component.ts` and `fragment.ts` follow, because they wire what those three produce.+stop changing them. Once they are frozen, the value layer, the Style decoder and the renderer depend+on the Types rather than on each other and can be written in any order or at the same time. The+Surface, the Producer handlers and the Fragment follow, because they wire what those three produce.Do not start that parallel stretch while a Type is still in question. Interface drift mid-flightcosts more than the ordering saves, and the symptom — a Producer rejecting a value that looks right —diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 2c8ee7df..24f733fe 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -166,6 +166,7 @@ const enTheme = {{ text: "Overview", link: "/guide/develop" },{ text: "Package Architecture", link: "/guide/packages" },{ text: "Adding an Author Package", link: "/guide/author-packages" },+ { text: "Component Anatomy", link: "/guide/component-anatomy" },{ text: "Adding a Provider", link: "/guide/providers" },{ text: "Runtime", link: "/guide/runtime" },{ text: "Testing", link: "/guide/testing" },diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdindex 2b700dd9..dd4ad376 100644--- a/docs/guide/author-packages.md+++ b/docs/guide/author-packages.md@@ -91,6 +91,9 @@ export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element })};```+[Component Anatomy](./component-anatomy.md) names every role a component package fills and where to+find each one in an existing package, since the filenames differ between packages.+Look at existing Surface implementations for reference:- `packages/seedance/src/surface.ts` — Prompt, Speech and Video Surfaces- `packages/caption/src/surface.ts` — the common Program Surface; concrete Style/Track Surfaces live in Style-family packagesdiff --git a/docs/guide/component-anatomy.md b/docs/guide/component-anatomy.mdnew file mode 100644index 00000000..40c011a9--- /dev/null+++ b/docs/guide/component-anatomy.md@@ -0,0 +1,75 @@+---+title: Component Anatomy+description: The roles a component package fills, and how to find them in an existing package.+---++# Component Anatomy++Every component package fills the same set of roles. The filenames differ from package to package, so+find a role by what it exports, not by what its file is called. This page describes the roles;+[Adding an Author Package](./author-packages.md) is the step-by-step.++Read this instead of reading a neighbouring package end to end. One package's specifics are a worse+thing to copy than its structure.++## The roles++| Role | What it owns | Called |+|---|---|---|+| Manifest | Module identity, nominal Types, Producers, Surface declarations and their vocabulary | `manifest.ts`, sometimes `index.ts` |+| Types | The TypeScript shapes those nominal Types carry | `types.ts` |+| Value layer | `assert…`, `seal…` and `create…` for every authored value | `program.ts`, `schedule.ts` |+| Style decoder | One SVS Recipe plus exact fonts into a Style value | `author.ts`, `style.ts` |+| Renderer | A Program into the elements a Track presents | `lower.ts`, `render.ts`, `presentation.ts` |+| Surface | XML element into typed records and inputs | `surface.ts` |+| Producers | The deterministic handlers the Manifest declared, and Validators | `component.ts` |+| Fragment | The graph a Surface expands into: inputs, operations, outputs | `fragment.ts` |+| Activation | The host facets a Host installs | `activation.ts` |++Three packages worth comparing, because they name things differently and do the same work:+`packages/ranking/` (`schedule.ts`, `style.ts`, `render.ts`), `packages/media-track/`+(`program.ts`, `lower.ts`, `presentation.ts`) and `packages/comment-sticker/` (`program.ts`,+`author.ts`).++## What each role must get right++**Types and Manifest are the contract.** Everything else agrees with them, so write them first and+stop changing them. A nominal Type belongs to your Module; Core keeps no central union, so adding one+needs no Core release.++**The value layer is where authored data becomes trustworthy.** Every value that crosses a boundary+gets an `assert…` that states what is wrong in the author's terms, and a `seal…` that canonicalises+it. A Producer that receives an unsealed value has no way to tell a mistake from a shape it has not+met. `assertMediaItemSpec` and `sealMediaItemSpec` in `packages/media-track/src/program.ts` are the+pattern.++**The Style decoder reads a Recipe, not a stylesheet.** It takes one `SvsRecipe` and the exact fonts,+validates the keys it admits, and produces a Style value. Unknown keys fail; defaults are declared,+not implied. See `decodeCommentStickerStyle` in `packages/comment-sticker/src/author.ts`.++**The renderer turns a Program into elements and nothing else.** It resolves no timing of its own and+reaches into no other Track. Timing arrives already projected; placement arrives as a Frame.++**The Surface decodes one element.** It reads attributes and children, resolves references, pushes+typed records, and returns the graph declarations. It is the only place that knows the markup exists.++**The Fragment is the shape, not the work.** It declares which inputs the Surface supplies, which+operations run, and which outputs the element publishes. Producers do the work; the Fragment says how+they are wired.++## Assets a package ships++A component's own chrome — its paper, board, panel, texture or default backdrop — is a file inside+the package, read with `readFile(new URL("../assets/…", import.meta.url))`. So is the preview image+its Surface declares. Neither is an input the installing project supplies, and neither is produced by+a Build: use `hypit image` while authoring the package and commit the result.++A component that cannot draw itself without a Source supplying its background is the wrong shape.+The symptom is unmistakable — it imports cleanly and renders nothing.++## What does not belong in a component package++- Credentials, HTTP, queues or Provider selection. A model package owns request semantics only.+- Timing resolved from anything other than the ProgramSpace and SemanticMap it was given.+- Access to another Track's values.+- A field added to Core, Composition or Visual IR to make one component work.