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: make author package guidance self-sufficient
rpone712cef929412
diff --git a/.agents/skills/hypit/references/credentials.md b/.agents/skills/hypit/references/credentials.mdindex eeaf1923..390e7759 100644--- a/.agents/skills/hypit/references/credentials.md+++ b/.agents/skills/hypit/references/credentials.md@@ -43,7 +43,7 @@ $env:GOOGLE_APPLICATION_CREDENTIALS_JSON = Get-Content -Raw "$HOME\.config\hypitKeep keys outside Author/Run/Runtime source and committed files. Verify presence without printingvalues with, for example,-`node .agents/skills/hypit/scripts/check-credentials.mjs KIE_API_KEY MIMO_API_KEY`, then run+`node <skill-root>/scripts/check-credentials.mjs KIE_API_KEY MIMO_API_KEY`, then run`hypit doctor` (once a Runtime Profile is selected with `hypit runtime use hypit.runtime.json`;doctor audits the selected profile, so it needs no profile argument of its own).diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.mdindex 1df9eca9..738590f1 100644--- a/.agents/skills/hypit/references/environment.md+++ b/.agents/skills/hypit/references/environment.md@@ -59,6 +59,9 @@ them as the selected launchers above. Do not globally link the checkout, use `npdependencies into an author project. Run reference-video-tool commands that share reference statefrom the same working directory, even though their launcher lives in the checkout.+When a reference names `<skill-root>`, substitute the installed Hypit skill directory (the directory+containing `SKILL.md` and `scripts/`); it is not relative to the author's project or checkout.+If neither an installed CLI nor a contributor checkout is available, report that no runnable HypitDistribution is present and stop. A registry install is not a recovery path.@@ -109,8 +112,9 @@ 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 sits beside the Distribution, at `.hypit/reference-video-tools/<reference-id>/`,-wherever the command is run from. It is keyed by the video, so two reconstructions of one file share+Reference-video state sits beside the Distribution, at `.hypit/reference-video-tools/<reference-id>/`.+Commands may run from any directory; the tool locates this canonical state from the selected+Distribution. It is keyed by the video, so two reconstructions of one file sharethe observations it cost money to make; each command reports the root it used.This split is why opening a second project cannot install WhisperX again, and why updating the npmdiff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.mdindex 207ad72e..1808d950 100644--- a/.agents/skills/hypit/references/local-author-package.md+++ b/.agents/skills/hypit/references/local-author-package.md@@ -100,6 +100,22 @@ A filled media slot arrives in `inputs` as the `BlobRef` itself, not wrapped inlauthored value is, so read its `mediaType` off the Artifact rather than assuming what the slot's namesuggests.+## Decoder and runtime value shapes++The Style decoder receives a decoded recipe as `{ path, properties }`: `path` is the authored recipe+id and `properties` is the canonical property map. A resolved authored reference may expose its+record; only read an inline value after checking `record.value.kind === "inline"`, then use+`record.value.value`. Never infer a value from the reference path.++The temporal-markup helpers take one object `{ id, subjectId?, element, semantic, resolveReference }`+and return `records`, `components` and `fragments` collections to append to the Surface result. The resulting+`TemporalInstant` carries `frame`; a `TemporalWindow` carries `span` with `startFrame` and+`endFrameExclusive`.++`SpatialFrame` uses `xPx`, `yPx`, `widthPx` and `heightPx`; `ProgramSpace` provides `id`,+`narrativeId`, `durationSec` and `frameRate` (`numerator` and `denominator`). A `fonts:Stack` Surface publishes a+`FontStackRef`; pass that same record to a Visual IR text element's `fonts` field.+## Package boundaryPlace the package at `<project>/packages/<slug>/`, named in the project's own scope such as@@ -160,6 +176,11 @@ Choose raw versus structured Surface, timing dependencies, ProgramSpace, Frame,Artifact, Recipe and output Types from the observed behavior and the anatomy the guide states. Adeclaration-only or Surface-only package is incomplete.+For variable child counts, emit one Fragment operation per child and pass those fixed-port results+to an append/merge Producer (for example `head`, `item`, `tail`). Do not add an undeclared+`items[]` input or let a handler consume arbitrary children; every child must be represented by a+sealed operation.+## The package draws itselfA package is installed vocabulary. `.svml`, `.svs` and `.svrun` are documents that use it. A package@@ -224,6 +245,12 @@ nothing.not render a complete PNG sequence; when no interval is stable for two frames, it uses the middleframe of the longest Present.+For a media slot, declare an Artifact Fragment input and read the BlobRef from `inputs`. Branch on+its `mediaType` (`image/*` or `video/*`) when choosing the Visual IR element, and still draw the+empty frame/cell when no material is supplied. `hypit image` uses the selected Runtime Profile's+image endpoint and is billed; obtain approval before using it and reserve it for package-owned+chrome, never video content or previews.+## Freeze the Types before writing in parallelThe nominal Types and the Manifest are what every other file agrees with, so write them first anddiff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.mdindex bbc91888..f5ed0a4f 100644--- a/.agents/skills/hypit/references/original-authoring/route.md+++ b/.agents/skills/hypit/references/original-authoring/route.md@@ -47,9 +47,9 @@ interruption or context compaction, read `../recovery.md`, run `route_state --ac| `environment` | explicit checkpoint after Distribution, project and credentials are selected | `hypit paths --json` || `brief-frozen` | explicit checkpoint naming the frozen brief, audience, format and claims | return to the brief checkpoint || `vocabulary-checked` | Run-scoped vocabulary inspection and the frozen `.hypit/component-fit.json` are both persisted | `inspect_svml_vocabulary --run <run>` |+| `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` || `package-ready` | every project-owned package under `packages/` has a real Surface/Producer/Fragment and is used by the compiled Graph | `validate_local_author_packages --run <run>` || `script-checked` | every caption Cue has at most four visible words | `validate_script_cues --run <run>` |-| `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` || `graph-checked` | `preview_check` returns `sound: true` after package and Cue gates | `preview_check <run>` || `layout-checked` | `layout_check` executed and every candidate was repaired or explicitly accepted | `layout_check --run <run>` / `layout_accept` || `review-planned` | `authoring_check` writes a plan | `authoring_check <run>` |@@ -173,7 +173,9 @@ of them; the Runtime Profile is part of the deliverable.**Read now:** `../authoring.md` — the syntax authority, the check set, and how an accepted Record isreused in the Run Source. `../runtime.md` — how to author a Profile.-Now run the persisted, Run-scoped gates before `hypit check`:+Author the Source before validating project-local packages: `package-ready` can only be completed+after `main.svml` and `build.svrun` compile a Graph that actually uses each package. Run the persisted,+Run-scoped gates before `hypit check`:```bashhypit-reference-video-tools inspect_svml_vocabulary --package <name> [--package …] --run build.svrundiff --git a/.agents/skills/hypit/references/playbooks/craft/captions.md b/.agents/skills/hypit/references/playbooks/craft/captions.mdindex f1239d7f..7f575d50 100644--- a/.agents/skills/hypit/references/playbooks/craft/captions.md+++ b/.agents/skills/hypit/references/playbooks/craft/captions.md@@ -83,9 +83,8 @@ Recipe padding must be a string* while `radius: 0` beside it is correct, and theand twelve horizontal — which no JSON number can carry, so it travels as text and is split on thespace. A single value is still written as one: `padding: "0"`.-`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.+`cue-min-words` and `cue-max-words` are not Recipe properties. Cue length belongs to Script `||`+boundaries and the route's `validate_script_cues` gate.## Cue boundaries are marked in the Script, with `||`diff --git a/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md b/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.mdindex 2184a395..452eae1c 100644--- a/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md+++ b/.agents/skills/hypit/references/playbooks/formats/ranking-listicle.md@@ -1,55 +1,30 @@# Ranking-listicle format-Use one progressive Ranking component to reveal a stable ordered set while speech and evidence-explain why every item belongs where it is placed.+Use a progressive ranking or list to reveal an ordered set while speech and evidence explain why+each item belongs where it is placed. The format is a narrative pattern; the concrete visual board+comes from the vocabulary/component-fit decision, not from a required package or tag.-## Author the Script schedule+## Plan the story-- Write one outer Script Selection covering the complete ranking window.-- `ranking:TierBoard` and `ranking:TopThree` are driven by item-owned Moments: give every item its own- `at={story.moment.NAME}` and declare one terminal Moment for the completed board. Reveal order comes- from the Moments' real frame order, not from a repeated marker id.-- `ranking:Column` is driven by its items: give each item that is not `preset` its own Script- Selection, and declare no Moments for it.-- Give every item a stable id, its rank or tier, its icon or image, and one evidence beat. Copy- belongs to the item only where the component carries it: `ColumnItem` and `TopThreeItem` require a- `label`, while a `TierItem` requires an `icon` and carries no copy of its own.+- Open with a clear question, claim or ranking criterion.+- Give every item a stable id, an explicit order or tier, one evidence beat and a concise reveal.+- Keep order, labels, icon/image treatment and evidence relationships stable across the list.+- Build toward a decisive top-ranked reveal and close with the implication or CTA.-## Author the SVML program+## Author the sources-1. Normalize each accepted speaking or audio-only source, create its `whisperx:SemanticTake`, then- assemble those Takes with `speech:Track` so Selections and Moments resolve against real audio.-2. Declare exact font bytes and the variant's package-owned Style.-3. Choose exactly one primary component: `ranking:TierBoard`, `ranking:Column`, or- `ranking:TopThree`.-4. Connect `semantic={speech.semantic}`, the outer `during`, an explicit `frame`, the Style, and the- complete ordered item list. `TierBoard` and `TopThree` also take the repeated `triggers` Moment- and the `terminal` Moment; `Column` takes a required `canvas` instead and reads its timing from- each item's own `during`.-5. Add the component's `.visual` output to `film:Film`; add its optional `.audio` output only when- authored sound is present.-6. Put screenshots, demonstrations, or proof clips on a separate `media-track:Track`. Use- `deck:DepthStack` only as an intentional evidence treatment, not as a second ranking system.-7. Add the full Caption pipeline when spoken words should be captioned, then render and target the- delivery through `.svrun`.--## Write and design the list--- Use setup → concrete evidence or cost → punchline for each spoken item.-- Give higher-ranked entries stronger proof and a more decisive close, not merely a brighter color.-- Keep row/tier vocabulary stable. Do not change layout grammar, label style, or icon logic halfway- through the list.-- Keep claims verifiable. Do not invent performance numbers, votes, comparisons, or product facts.-- Separate ranking copy from captions: item labels belong to the Ranking component; spoken dialogue- belongs to Script and Caption; supporting proof belongs to Media Track.+1. Create the semantic speech chain and one outer ranking window.+2. Declare exact fonts and the package-owned Style selected during vocabulary inspection.+3. Use the selected ranking/list component and its documented timing/placement vocabulary; do not+ invent attributes or copy a removed component's timing model.+4. Connect semantic timing, the outer window, explicit placement, Style and the complete ordered+ item set. Reveal timing must come from the component's admitted Moment/Selection inputs.+5. Add the visual output to `film:Film`; keep proof clips or screenshots on a separate media track.+6. Add the Caption pipeline when spoken words should be captioned, then route the delivery through+ `.svrun`.## Review and reuse-Review the resolved trigger count and order and the terminal timing where the component uses them,-item identity, rank/tier, labels, icon assets,-evidence alignment, safe zones, stack order, and optional sounds. Pin accepted generated evidence-media through `.svrun` before the final ranking Build.--Read `../craft/captions.md`, `../craft/overlays.md`, `../craft/b-roll.md`, and `../craft/sfx.md`.--That list is complete, and the always-read craft in `../index.md` applies regardless of format.+Check item identity and order, reveal timing, labels, icon assets, evidence alignment, safe zones,+stack order and optional sounds. Read `../craft/captions.md`, `../craft/overlays.md`,+`../craft/b-roll.md` and `../craft/sfx.md`; the always-read craft in `../index.md` applies too.diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex 8f8a52e0..aeb162ee 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -35,12 +35,10 @@ The same check is also a bin of its own:hypit-preview-check /path/to/project/build.svrun```-Prefer the subcommand. It takes `--package-root <dir>`, which is where the packages the Source-imports are resolved from — a project's own packages under `packages/<slug>/` are installed against the-project root, so name it there and the check reaches them from wherever you are standing. Without-the flag the working directory is used. 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.+Prefer the subcommand. `--package-root <dir>` is needed only when the project has no `package.json`+or when an explicit package root is desired; it changes Host package lookup, not Source Workspace.+With a project-root `package.json`, omit it. The bare bin fixes the package root to the Run file's own+directory and takes no flags.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 nodiff --git a/.agents/skills/hypit/references/reconstruction/evidence.md b/.agents/skills/hypit/references/reconstruction/evidence.mdindex 60dd07f1..bd14edee 100644--- a/.agents/skills/hypit/references/reconstruction/evidence.md+++ b/.agents/skills/hypit/references/reconstruction/evidence.md@@ -25,9 +25,9 @@ whole-reference observations under `observations.people_and_product`, `observatifor compatibility. Do not mix `.text`, `.answer.text` and `.result.text` as competing conventions.A reference is found from the Distribution rather than from where you are standing, so these commands-may be run from anywhere. What does depend on where you are is which packages resolve: name the-project with `--package-root` when the command is not run from inside it. `paths` reports both roots-and every prepared reference, which is what to run when a command reports something it cannot see.+may be run from anywhere. `--package-root` only affects project package discovery when a project has+no `package.json` of its own; it never changes the reference-state location. `paths` reports both+roots and every prepared reference.Defaults are sufficient for normal use. Each also accepts `--input <json>`.diff --git a/.agents/skills/hypit/references/reconstruction/observers.md b/.agents/skills/hypit/references/reconstruction/observers.mdindex 9eb78c6d..54b45e90 100644--- a/.agents/skills/hypit/references/reconstruction/observers.md+++ b/.agents/skills/hypit/references/reconstruction/observers.md@@ -26,7 +26,7 @@ Ask the author once, before `prepare_reference`. Report what this machine actualasking them to recall it:```text-node .agents/skills/hypit/scripts/check-credentials.mjs GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON+node <skill-root>/scripts/check-credentials.mjs GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON```Both variables `set` means `gemini` is available and the author chooses between the two. Either onediff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.mdindex 2fb183ff..f8f0cd07 100644--- a/.agents/skills/hypit/references/reconstruction/route.md+++ b/.agents/skills/hypit/references/reconstruction/route.md@@ -87,9 +87,9 @@ of intent; files and check results remain the authority.| `reference-prepared` | checkpoint after `prepare_reference` reports ready `state.json` | `prepare_reference` or `route_state reconcile` || `reference-observed` | explicit observer checkpoint; all required observation answers are complete | `observe_reference` / `record_observation` || `vocabulary-checked` | Run-scoped vocabulary inspection and the frozen `.hypit/component-fit.json` are both persisted | `inspect_svml_vocabulary --run <run>` |+| `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` || `package-ready` | every project-owned package under `packages/` has a real Surface/Producer/Fragment and is used by the compiled Graph | `validate_local_author_packages --run <run>` || `script-checked` | every caption Cue has at most four visible words | `validate_script_cues --run <run>` |-| `source-authored` | explicit checkpoint naming `main.svml` (and Recipe/Run when available) | `hypit check <run>` || `graph-checked` | `preview_check` returns `sound: true` after package and Cue gates | `preview_check <run>` || `layout-checked` | `layout_check` executed and every candidate was repaired or explicitly accepted | `layout_check --run <run>` / `layout_accept` || `review-planned` | `reconstruction_check` writes a plan | `reconstruction_check <run>` |@@ -297,7 +297,9 @@ Write `main.svml`, `recipes.svs` and `build.svrun`, then extend the existing `hyevery capability those Sources reach. The Runtime Profile is part of the deliverable: without it thefirst thing the author meets is `RUNTIME_CAPABILITY_UNBOUND`.-Now persist the Run-scoped half of the frozen vocabulary decision. This completes+Author the Source before validating project-local packages: `package-ready` can only be completed+after `main.svml` and `build.svrun` compile a Graph that actually uses each package. Now persist the+Run-scoped half of the frozen vocabulary decision. This completes`vocabulary-checked` only when `.hypit/component-fit.json` remains valid:```bashdiff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.mdindex 26374f45..64b5f7ba 100644--- a/.agents/skills/hypit/references/runtime.md+++ b/.agents/skills/hypit/references/runtime.md@@ -180,10 +180,8 @@ 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. 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.+ access. With a `package.json` at the project root, omit it. Use it when a project has no own+ `package.json` or when explicitly selecting another package root; this never changes Source+ Workspace resolution.- Do not symlink an external project into the Distribution. The external directory is the intendedworkspace, not an escape from one.diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdindex e49b2cef..0b6ee008 100644--- a/docs/guide/author-packages.md+++ b/docs/guide/author-packages.md@@ -19,7 +19,7 @@ must not be added to the Style record merely to describe its role.## 1. Create the package```bash-mkdir -p packages/my-component/src packages/my-component/test+mkdir -p packages/my-component/src```## 2. Write package.jsondiff --git a/docs/guide/component-anatomy.md b/docs/guide/component-anatomy.mdindex cd67a741..be0f85c8 100644--- a/docs/guide/component-anatomy.md+++ b/docs/guide/component-anatomy.md@@ -43,9 +43,9 @@ it. A Producer that receives an unsealed value has no way to tell a mistake frommet. The fixture's value layer is the minimal pattern; a close sibling may be used as a boundedimplementation skeleton only after vocabulary inspection.-**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. Use the fixture's decoder for the generic boundary, or the selected close sibling when+**The Style decoder reads a Recipe, not a stylesheet.** It takes one decoded `SvsRecipe` shaped as+`{ path, properties }` and the exact fonts, validates the keys it admits, and produces a Style value.+Unknown keys fail; defaults are declared, not implied. Use the fixture's decoder for the generic boundary, or the selected close sibling whenthe new package intentionally extends that sibling's domain contract.**The renderer turns a Program into elements and nothing else.** It resolves no timing of its own anddiff --git a/docs/guide/skill.md b/docs/guide/skill.mdindex 8279c0a7..0e331f34 100644--- a/docs/guide/skill.md+++ b/docs/guide/skill.md@@ -203,8 +203,8 @@ spending. `hypit build` is submitted only after explicit cost approval.```textenvironment → brief-frozen → examples/format/craft decisions-→ vocabulary/component-fit → package-ready → Script and four sources-→ script-checked → source-authored → graph-checked → layout-checked+→ vocabulary/component-fit → Script and four sources → source-authored+→ package-ready → script-checked → graph-checked → layout-checked→ review-planned → preview-rendered → review-complete → repairs-complete→ final-checked → Studio confirmation → optional Build```@@ -231,8 +231,8 @@ edge needed by the Film. It has no reference video, so `brief.json` is the autho```textenvironment → reference-prepared → reference-observed-→ examples/format/craft decisions → vocabulary/component-fit → package-ready-→ Script and four sources → script-checked → source-authored → graph-checked+→ examples/format/craft decisions → vocabulary/component-fit+→ Script and four sources → source-authored → package-ready → script-checked → graph-checked→ layout-checked → review-planned → preview-rendered → comparison-complete→ repairs-complete → final-checked → initial-adaptation → final check again→ Studio confirmation → optional Builddiff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.mdindex c22317aa..f0e21ae3 100644--- a/docs/quickstart/styles.md+++ b/docs/quickstart/styles.md@@ -103,7 +103,7 @@ For reproducible rendering, select an exact installed face in the `.svml` sourceRecord to the Fine Style. Family, weight and style have one source of truth on this exact font edge:```svml-<fonts:Face id="caption-font" family="inter" weight="600" style="normal"/>+<fonts:Stack id="caption-font" family="inter" weight="600" style="normal"/><caption-fine:Style id="primary-caption" recipe={recipes.caption.dialogue}font={caption-font}/>```@@ -117,6 +117,8 @@ caption.alice {stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;+ line-height: 0.96;+ align: center;fill: #73FBD3;background: #09090BCC;padding: 16 24; radius: 18;@@ -126,6 +128,8 @@ caption.bob {stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;+ line-height: 0.96;+ align: center;fill: #FFD166;background: #09090BCC;padding: 16 24; radius: 18;diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdindex 31e75d4f..0c819c46 100644--- a/docs/quickstart/tracks.md+++ b/docs/quickstart/tracks.md@@ -330,13 +330,11 @@ placement, timing, style and motion. Use inline `P`/`Span`/`Break` when the auth## Ranking boards-A board animates an ordered list against the Script: it enters on a Selection, moves on Moments, and-settles on a Moment that ends it. Three variants share one shape — a container, its own item tag,-and its own style tag.+A ranking board animates an ordered list against the Script. The concrete container, item and Style+vocabulary is package-owned; inspect the installed package before authoring it.| Container | Item | Style ||---|---|---|-| `ranking:TierBoard` | `ranking:TierItem` | `ranking:TierBoardStyle` || `ranking:Column` | `ranking:ColumnItem` | `ranking:ColumnStyle` || `ranking:TopThree` | `ranking:TopThreeItem` | `ranking:TopThreeStyle` |@@ -362,9 +360,8 @@ against the variant, so a Column recipe on a TierBoard is refused by name.| `terminal` | the Moment where the completed board settles. `TopThree` only || `canvas` | a `space:Canvas` — the independent reveal stage. TierBoard/Column |-`TierBoard` and `Column` take no `terminal`: every non-preset item carries an explicit reveal-Selection. Sibling windows must already be non-overlapping and inside the container's `during`-span.+Use only the timing forms admitted by the selected package; do not infer a terminal or reveal model+from another component family.`move-sound` is refused on `TopThree`, which has no move phase. On a `TierBoard` it needs at leastone item with `entry="drop"`. A drop Item appears in place on the independent Canvas stage when itsdiff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.mdindex 5457b941..fef2066c 100644--- a/docs/zh/quickstart/styles.md+++ b/docs/zh/quickstart/styles.md@@ -99,7 +99,7 @@ caption.dialogue {Style。字体家族、字重和字形只在这条精确字体边上声明一次:```svml-<fonts:Face id="caption-font" family="inter" weight="600" style="normal"/>+<fonts:Stack id="caption-font" family="inter" weight="600" style="normal"/><caption-fine:Style id="primary-caption" recipe={recipes.caption.dialogue}font={caption-font}/>```@@ -113,6 +113,8 @@ caption.alice {stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;+ line-height: 0.96;+ align: center;fill: #73FBD3;background: #09090BCC;padding: 16 24; radius: 18;@@ -122,6 +124,8 @@ caption.bob {stack-order: 70;x: 0.08; y: 0.76; width: 0.84;size: 58;+ line-height: 0.96;+ align: center;fill: #FFD166;background: #09090BCC;padding: 16 24; radius: 18;diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.mdindex c0743165..3308b5dd 100644--- a/docs/zh/quickstart/tracks.md+++ b/docs/zh/quickstart/tracks.md@@ -270,11 +270,10 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。## 榜单板-榜单板让一份有序列表跟着 Script 动起来:在某个 Selection 期间出现,在 Moment 上移动,在另一个 Moment 上定格。三个变体共用同一套形状——一个容器、它专属的条目标签、以及它专属的样式标签。+榜单板让一份有序列表跟着 Script 动起来。具体的容器、条目和 Style 词汇由包声明;写作前先检查已安装包的词汇。| 容器 | 条目 | 样式 ||---|---|---|-| `ranking:TierBoard` | `ranking:TierItem` | `ranking:TierBoardStyle` || `ranking:Column` | `ranking:ColumnItem` | `ranking:ColumnStyle` || `ranking:TopThree` | `ranking:TopThreeItem` | `ranking:TopThreeStyle` |@@ -298,7 +297,7 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。| `canvas` | 一个 `space:Canvas`——独立揭示舞台。TierBoard/Column || `appear-sound`、`move-sound` | 可选,Synchronized Media |-TierBoard 与 Column 都不使用 `terminal`:每个非 preset item 直接消费一个 `during` Selection,所有窗口必须位于外层区间内且互不相交。`move-sound` 在 `TopThree` 上会被拒绝;在 `TierBoard` 上它要求至少有一个 `entry="drop"` 的条目。drop 条目会在 Selection 开始时原地弹入独立的 Canvas 舞台,整段讲解期间保持静止,只在窗口末尾的 `move-frames` 内沿缓动弧线滑入 tier;移动音效也从这里开始。+只使用所选包明确声明的时间形式;不要从另一个组件族推断 terminal 或 reveal 规则。### 条目标签diff --git a/examples/minimal-author-package/README.md b/examples/minimal-author-package/README.mdindex 99013cab..d639e4c4 100644--- a/examples/minimal-author-package/README.md+++ b/examples/minimal-author-package/README.md@@ -3,3 +3,8 @@Use this directory only as the generic author-package fixture. It is deliberately not a complete videoproject: the `packages/example-component` package is the authoritative small implementation, whilethe package's `preview/` asset demonstrates a Surface preview.++The fixture's Surface decoder also demonstrates the public value boundary: Style-like values consume+a decoded recipe shaped as `{ path, properties }`, exact `FontStackRef` records and inline values+only after checking `record.value.kind === "inline"`. Media slots remain graph inputs rather than+package files.diff --git a/examples/minimal-author-package/packages/example-component/src/index.ts b/examples/minimal-author-package/packages/example-component/src/index.tsindex 4dec87ff..7a6274a2 100644--- a/examples/minimal-author-package/packages/example-component/src/index.ts+++ b/examples/minimal-author-package/packages/example-component/src/index.ts@@ -2,4 +2,5 @@ export { exampleComponent } from "./component.js";export { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";export { exampleManifest, exampleMarkupSurfaces, exampleModuleRef, exampleProducers, exampleTypes } from "./manifest.js";export { decodeExampleSurface } from "./surface.js";+export { decodeExampleStyle } from "./style.js";export { projectExampleMoment, projectExampleWindow, temporalInstantAttributeNames, temporalWindowAttributeNames } from "./temporal.js";diff --git a/examples/minimal-author-package/packages/example-component/src/manifest.ts b/examples/minimal-author-package/packages/example-component/src/manifest.tsindex fb60b72b..d8d6a320 100644--- a/examples/minimal-author-package/packages/example-component/src/manifest.ts+++ b/examples/minimal-author-package/packages/example-component/src/manifest.ts@@ -4,6 +4,8 @@ import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";import { programSpaceTypes } from "@hypit/program-space";import { semanticTrackTypes } from "@hypit/semantic-track";import { temporalTypes } from "@hypit/temporal";+import { mediaTypes } from "@hypit/media";+import { svsRecipeType } from "@hypit/svs";const previewImage = (file: string) => ({mediaType: "image/png",@@ -16,6 +18,7 @@ export const exampleTypes = {box: { module: exampleModuleRef, name: "ExampleBox" },text: { module: exampleModuleRef, name: "ExampleText" },mediaSlot: { module: exampleModuleRef, name: "ExampleMediaSlot" },+ style: { module: exampleModuleRef, name: "ExampleStyle" },} satisfies Record<string, TypeRef>;export const exampleProducers = {renderBox: { module: exampleModuleRef, name: "render-example-box" },@@ -58,4 +61,12 @@ export const exampleMarkupSurfaces = [{ name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A framed box surface.", "<example:Box id=\"box\" semantic={speech.semantic}/>") , preview: previewImage("Box.png") } },{ name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A text-bearing surface.", "<example:Text id=\"title\" semantic={speech.semantic}>Hello</example:Text>"), preview: previewImage("Box.png") } },{ name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" semantic={speech.semantic}/>") , preview: previewImage("Box.png") } },+ { name: "style", tag: "Style", mode: "structured", outputs: [exampleTypes.style], vocabulary: {+ summary: "Decodes one SVS Recipe and exact FontStackRef into a Style value.",+ attributes: [+ { name: "id", kind: "identifier", required: true, summary: "Names this Style." },+ { name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType], summary: "The decoded recipe with path and properties." },+ { name: "font", kind: "reference", required: true, accepts: [mediaTypes.fontStack], summary: "An exact FontStackRef." },+ ], example: "<example:Style id=\"card\" recipe={recipes.card} font={caption-font}/>",+ } },] as const;diff --git a/examples/minimal-author-package/packages/example-component/src/style.ts b/examples/minimal-author-package/packages/example-component/src/style.tsnew file mode 100644index 00000000..aab9cf2d--- /dev/null+++ b/examples/minimal-author-package/packages/example-component/src/style.ts@@ -0,0 +1,13 @@+import type { FontStackRef } from "@hypit/media";+import type { SvsRecipe } from "@hypit/svs";++/** The two values a Style decoder receives after author references are resolved. */+export type ExampleStyleInput = {+ readonly recipe: { readonly path: string; readonly properties: SvsRecipe["properties"] };+ readonly fonts: FontStackRef;+};++/** A deliberately small, runnable Style boundary for the fixture. */+export function decodeExampleStyle(input: ExampleStyleInput): { readonly recipe: ExampleStyleInput["recipe"]; readonly fonts: FontStackRef } {+ return { recipe: { path: input.recipe.path, properties: { ...input.recipe.properties } }, fonts: input.fonts };+}diff --git a/examples/minimal-author-package/packages/example-component/src/surface.ts b/examples/minimal-author-package/packages/example-component/src/surface.tsindex 6a16e8c5..5c5d2283 100644--- a/examples/minimal-author-package/packages/example-component/src/surface.ts+++ b/examples/minimal-author-package/packages/example-component/src/surface.ts@@ -1,6 +1,8 @@import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference } from "@hypit/markup";import { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";import { exampleMarkupSurfaces, exampleTypes } from "./manifest.js";+import { mediaTypes } from "@hypit/media";+import { svsRecipeType } from "@hypit/svs";function text(element: StructuredElement, name: string): string {const value = element.attributes[name];@@ -17,6 +19,14 @@ function reference(element: StructuredElement, name: string, resolve: (path: strexport const decodeExampleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {const id = text(element, "id");+ if (element.name.endsWith(":Style")) {+ const recipe = reference(element, "recipe", resolveReference);+ const font = reference(element, "font", resolveReference);+ if (recipe.type.module.name !== svsRecipeType.module.name || recipe.type.name !== svsRecipeType.name) throw new Error("Style.recipe must be an SVS Recipe.");+ if (font.type.module.name !== mediaTypes.fontStack.module.name || font.type.name !== mediaTypes.fontStack.name) throw new Error("Style.font must be a FontStackRef.");+ if (recipe.record?.value.kind !== "inline" || font.record?.value.kind !== "inline") throw new Error("Style references must resolve to inline records.");+ return { records: [{ id, type: exampleTypes.style, value: { kind: "inline", value: { recipe: recipe.record.value.value, fonts: font.record.value.value } }, range: element.range }], components: [], fragments: [], exports: [id] };+ }const semantic = reference(element, "semantic", resolveReference);const surface = exampleMarkupSurfaces.find((item) => item.tag === element.name.split(":").at(-1));if (surface === undefined) throw new Error(`Unknown example surface ${element.name}`);