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: make author package guidance self-sufficient

rpone712cef929412
diff --git a/.agents/skills/hypit/references/credentials.md b/.agents/skills/hypit/references/credentials.md
index 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\hypit
Keep keys outside Author/Run/Runtime source and committed files. Verify presence without printing
values 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.md
index 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 `np
dependencies into an author project. Run reference-video-tool commands that share reference state
from 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 Hypit
Distribution 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 and
Worker 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 share
the 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 npm
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index 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 inl
authored value is, so read its `mediaType` off the Artifact rather than assuming what the slot's name
suggests.
+## 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 boundary
Place 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. A
declaration-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 itself
A 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 middle
frame 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 parallel
The nominal Types and the Manifest are what every other file agrees with, so write them first and
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
index 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 is
reused 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`:
```bash
hypit-reference-video-tools inspect_svml_vocabulary --package <name> [--package …] --run build.svrun
diff --git a/.agents/skills/hypit/references/playbooks/craft/captions.md b/.agents/skills/hypit/references/playbooks/craft/captions.md
index 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 the
and twelve horizontal — which no JSON number can carry, so it travels as text and is split on the
space. 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.md
index 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.md
index 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 a
Film or Render output of the current SVML, a Film with no traceable composition, a Film with no
diff --git a/.agents/skills/hypit/references/reconstruction/evidence.md b/.agents/skills/hypit/references/reconstruction/evidence.md
index 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`, `observati
for 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.md
index 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 actual
asking 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 one
diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.md
index 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 `hy
every capability those Sources reach. The Runtime Profile is part of the deliverable: without it the
first 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:
```bash
diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.md
index 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 intended
workspace, not an escape from one.
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.md
index 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.json
diff --git a/docs/guide/component-anatomy.md b/docs/guide/component-anatomy.md
index 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 from
met. The fixture's value layer is the minimal pattern; a close sibling may be used as a bounded
implementation 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 when
the 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 and
diff --git a/docs/guide/skill.md b/docs/guide/skill.md
index 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.
```text
environment → 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
```text
environment → 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 Build
diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.md
index 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` source
Record 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.md
index 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 least
one item with `entry="drop"`. A drop Item appears in place on the independent Canvas stage when its
diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.md
index 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.md
index 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.md
index 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 video
project: the `packages/example-component` package is the authoritative small implementation, while
the 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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: str
export 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}`);