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: 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.md
index 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, where
timing is resolved, what the Fragment declares. They are long, and copying one package's specifics is
a worse outcome than understanding its structure.
@@ -78,9 +82,9 @@ nothing.
## Freeze the Types before writing in parallel
The 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-flight
costs 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.ts
index 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.md
index 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 packages
diff --git a/docs/guide/component-anatomy.md b/docs/guide/component-anatomy.md
new file mode 100644
index 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.