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: explain authored cues and Studio items

kashorin9c661820c540
diff --git a/docs/guide/studio-temporal-windows.md b/docs/guide/studio-temporal-windows.md
index 8d312a43..f51128bf 100644
--- a/docs/guide/studio-temporal-windows.md
+++ b/docs/guide/studio-temporal-windows.md
@@ -11,8 +11,8 @@ the source domain.
| Author form | Moving it changes | Trimming it changes |
| --- | --- | --- |
-| `from="2s" for="8f"` | `from`; duration remains eight frames | `from` or `for` |
-| `until="3s" for="8f"` | `until`; duration remains eight frames | `for` or `until` |
+| `from="2s" for="8f"` | `from`; duration remains eight frames | leading: `from` + `for`; trailing: `for` |
+| `until="3s" for="8f"` | `until`; duration remains eight frames | leading: `for`; trailing: `until` + `for` |
| `from="1s" until="3s"` | both endpoints by the same delta | the selected endpoint |
| named Window declared with `from`/`until`/`for` | the named declaration | the selected relation |
| component `during={named-window}` | the named value's producer | the named value's producer |
@@ -44,6 +44,16 @@ different editing rules while publishing the same Temporal types.
If a producer declares no inverse, the resolved value remains usable but Studio does not guess a
write target. This keeps shared meaning, local clock values and component behavior separate.
+Each drag is solved as one complete constraint. A leading trim keeps the old end, a trailing trim
+keeps the old start, and a move keeps the old duration. Studio follows the executed Temporal graph
+to the exact author endpoints and commits every required source change together.
+
+Named values constructed inside `<time:Timeline>` follow the same rule. Timeline Author retains the
+child declaration that owns each literal offset or duration, so Studio can edit that exact
+`Instant.at`, `Window.from`, `Window.until` or `Window.for` value. Bare references continue upstream;
+an `earliest(...)` or `latest(...)` expression stays read-only when changing it would require choosing
+one branch on the author's behalf.
+
Unedited expressions retain their units: `2s` remains two seconds when frame rate changes, whereas
`60f` remains sixty frames. A changed clock value is written on a whole frame boundary for the
current Timeline.
diff --git a/docs/quickstart/preview.md b/docs/quickstart/preview.md
index ff734faf..ada7c766 100644
--- a/docs/quickstart/preview.md
+++ b/docs/quickstart/preview.md
@@ -65,11 +65,11 @@ The central Preview evaluates the composition's compiled `HtmlProgram`. It uses
media sampling and motion as an encoded render. Check the actual picture when adjusting caption
placement, graphic emphasis or coverage.
-The Timeline shows component appearances on a shared clock. A semantic composition also shows
-Segments, Words, Selections and Moments. Select an entity to seek to it; playback, frame stepping,
+The Timeline shows component appearances on a shared clock. Domain projections can also contribute
+mapping and evidence rows, while authored Instants and Windows share a temporal row. Select an Item to seek to it; playback, frame stepping,
zoom and scrolling help examine a particular transition or layout.
-The Inspector shows the selected entity's properties. Editable fields and timeline handles depend
+The Inspector shows the selected Item's properties. Editable fields and timeline handles depend
on the component's **Studio Companion**, which describes the component to Studio. A project component
can supply its own Companion alongside its rendering code. Renderability and the available editing
controls are separate: a field or gesture needs a clear source value to change.
@@ -96,7 +96,7 @@ available to explore the editable work and discuss further changes.
For component authors, [Timing edits in Studio](../guide/studio-temporal-windows.md) explains semantic
editing, and the [Companion SDK](https://github.com/hypit-ai/hypit/blob/main/packages/studio-companion/README.md)
-explains how to expose component entities and controls.
+explains how to expose component Items and controls.
To add another interface language, load a local JSON translation with `--locale-pack ./language.json`.
The [localization guide](https://github.com/hypit-ai/hypit/blob/main/packages/studio/LOCALIZATION.md)
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 4b26a625..d972ebd3 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -15,7 +15,7 @@ Caption uses a source-neutral document produced by Script and a replaceable Styl
```text
Script → CaptionDocument + NarrativeCaptionBinding
Binding + NarrativeProjection → complete Unit CaptionTiming
-CaptionDocument + CaptionTiming + Uses → family Cue schedule → VisualTrack
+authored Cues + CaptionTiming + Uses → family presentation schedule → VisualTrack
```
```svml
@@ -25,9 +25,10 @@ CaptionDocument + CaptionTiming + Uses → family Cue schedule → VisualTrack
<import as="fonts" from="@hypit/fontsource@1"/>
```
-`@hypit/caption` owns the common CaptionDocument contract, complete-unit Selection/Role projection,
-Style assignment and the flat timing join. `@hypit/caption-fine` is one Style family: it forms Cues
-and owns their geometry, glyph/Cue/Pill Paint and layered local motion.
+`@hypit/caption` owns the common CaptionDocument contract, including ordered Words, correspondence
+Units and authored Cues, plus complete-unit Selection/Role queries, Style assignment and the flat
+timing join. `@hypit/caption-fine` is one Style family: it presents those Cues and owns their
+geometry, glyph/Cue/Pill Paint and layered local motion.
### caption-fine:Style
diff --git a/skills/hypit/references/production/caption-authoring.md b/skills/hypit/references/production/caption-authoring.md
index 5cbadfc4..3567cbf7 100644
--- a/skills/hypit/references/production/caption-authoring.md
+++ b/skills/hypit/references/production/caption-authoring.md
@@ -50,11 +50,11 @@ and evaluate its state at the requested frame. Keep separately useful overlays a
## Keep the existing text and timing chain
```text
-Script → CaptionDocument (displayed words, Cue breaks and word attributes)
+Script → CaptionDocument (displayed Words, correspondence Units, authored Cues and word attributes)
NarrativeCaptionBinding + NarrativeProjection → CaptionTiming
Track Uses → resolved time windows, Styles and optional speaker filters
CaptionDocument + complete unit Timing + Uses + family parameters
- → family-owned Cues and schedule → VisualTrack
+ → family-owned schedule for the authored Cues → VisualTrack
```
Consume each display word's `separatorBefore` with its `text`; never rebuild wording by joining
@@ -98,10 +98,10 @@ keywords, long text and an N:M pronunciation span. Make author correction possib
attributes, `||` and Style configuration instead of inventing missing text or dropping words.
The projection publishes every complete Unit's absolute boundaries and does not form Cues. The
-family schedule respects authored Cue breaks and structural boundaries while forming its readable
-groups. Visual line wrapping is a separate operation. A narrow width should not silently rewrite the
-Script into new spoken Cues. If the family needs an additional grouping rule, give that rule explicit
-parameters and preserve the original word/unit associations in the schedule.
+CaptionDocument already partitions complete Units into authored Cues. A family schedule joins those
+Cues to Unit timing and may derive lines, pages, cards or local states, but it does not split or merge
+Cues. Visual line wrapping is a separate operation. A narrow width must not silently rewrite the
+Script into new Cues. Preserve the original Cue, Unit and Word associations in the schedule.
Display Words reflect Script's lexical units: a Han character is normally one Word, while an
English word is normally one Word. Keep that timing granularity separate from visual grouping.
diff --git a/skills/hypit/references/production/caption-presentation.md b/skills/hypit/references/production/caption-presentation.md
index 96e08867..d0a00e9e 100644
--- a/skills/hypit/references/production/caption-presentation.md
+++ b/skills/hypit/references/production/caption-presentation.md
@@ -4,8 +4,8 @@ Read this to apply subtitle treatments, change them during a passage, or hide th
[Caption craft](../playbooks/craft/captions.md) owns visual direction;
[Caption authoring](caption-authoring.md) explains creating a new family.
-**Script organizes content; the family forms Cues; Use organizes presentation in time.** `||` gives
-the family a hard content break. An upstream adapter resolves every document Unit's timing once; the
+**Script authors Words, Units and Cues; the family presents those Cues; Use organizes presentation
+in time.** `||` ends the current authored Cue. An upstream adapter resolves every document Unit's timing once; the
Track consumes that flat `CaptionTiming` without knowing whether it came from Narrative, SRT/VTT or
authored absolute time. Each Use selects a complete Style inside an already resolved time window.
diff --git a/skills/hypit/references/production/script-syntax.md b/skills/hypit/references/production/script-syntax.md
index fdab6d9b..499f74db 100644
--- a/skills/hypit/references/production/script-syntax.md
+++ b/skills/hypit/references/production/script-syntax.md
@@ -149,7 +149,7 @@ One Script publishes the full Narrative and the narrow views needed by the rest
| `{story.segment.hook}` | The `hook` Segment as a NarrativeSegmentRef for generation, alignment or another semantic consumer. |
| `{story.segment.hook.dialogue}` | Role-aware dialogue using the spoken side of Dual Text, suitable for a speaking performance request. |
| `{story.segment.hook.speech}` | Pronunciation-only Text, suitable for `hypit estimate` or independent speech. |
-| `{story.caption}` | Display Words, Alignment Units, attributes, Roles, and authored Cue Breaks for Caption. |
+| `{story.caption}` | Display Words, Alignment Units, attributes, Roles, and authored Cues for Caption. |
| `{story.selection.proof}` | The named semantic range. |
| `{story.moment.claim}` | The named semantic point. |
diff --git a/skills/hypit/references/production/studio-companions.md b/skills/hypit/references/production/studio-companions.md
index 06761f89..8ef5d786 100644
--- a/skills/hypit/references/production/studio-companions.md
+++ b/skills/hypit/references/production/studio-companions.md
@@ -6,18 +6,18 @@ component. [Studio](studio.md) owns opening and operating the editor;
The Companion describes two things: **what an author can recognize and select**, and **which
authored fact an edit changes**. Keep the same concepts across the picture, timeline and Inspector.
-A reveal can be one entity even when its graphic moves and later remains on a board. A coordinated
-presenter-and-diagram scene can stay one entity when its layout is intended to be edited together.
+A reveal can be one Item even when its graphic moves and later remains on a board. A coordinated
+presenter-and-diagram scene can stay one Item when its layout is intended to be edited together.
Recognition and editing are separate capabilities. A production may use Studio mainly to watch and
show its arrangement, with a few useful adjustments. Clear labels, timing and selected read-only
facts can fully serve a one-off scene; useful Caption controls can coexist with that fixed scene.
-## Choose useful entities and lanes
+## Choose useful Items and lanes
Match the component's actual Module ABI, Surface and terminal output Type. Generic VisualTrack or
-AudioTrack entities are enough for ordinary Clip occurrences. Use `project(context)` when the author needs
+AudioTrack Items are enough for ordinary Clip occurrences. Use `project(context)` when the author needs
domain meaning that the terminal drawing no longer contains. A Surface preview supplies a useful
-static recognition image; live entities and editable bindings come from the Companion.
+static recognition image; live Items and editable bindings come from the Companion.
Generic Studio projection recognizes the terminal Type, not the component's creative role. A custom
Caption can therefore render correct subtitles yet appear as a generic blue visual lane with
@@ -38,13 +38,13 @@ published output. `requiredReferencedValue` reads an exact typed author referenc
| Declaration | Authoring meaning |
| --- | --- |
| Companion label, tone, icon and `lane.heightPx` | Recognize the component and give its information enough room. |
-| Entity id and authored identity | Select the same authored object after recompilation or reordering. Qualify child ids across component instances. |
+| Item id and authored identity | Select the same authored object after recompilation or reordering. Qualify child ids across component instances. |
| `display.title` and display layers | Show useful content, text or declared media rather than an opaque implementation id. |
| `startFrame`, `endFrameExclusive` | Describe what this rectangle edits: occupancy, activation or another explicit interval. |
-| `stackOrder` | Order overlapping editor entities; this is separate from changing the Film's paint order. |
-| Companion `attachments` and entity `lane` | Expose a meaningful child lane, such as reveals under a board, with its own fields. |
+| `stackOrder` | Order overlapping editor Items; this is separate from changing the Film's paint order. |
+| Companion `attachments` and Item `lane` | Expose a meaningful child lane, such as reveals under a board, with its own fields. |
-Each declared lane is one row. Overlapping entities remain selectable; selection raises the selected
+Each declared lane is one row. Overlapping Items remain selectable; selection raises the selected
rectangle within that row. Parent and attached lanes use the same behavior. Add a child lane when
it explains another authoring relationship, such as activation within a persistent board.
@@ -52,23 +52,27 @@ An activation rectangle may end before the object disappears. Keep the activatio
and the object's continuing picture identity distinct. The installed Ranking Companion demonstrates
this with the board and its independent reveals.
-## Put related rules in a Band
+## Keep Track-owned rules in the Inspector
-A Track's `bands` are internal strips sharing its label. For example, Caption shows Cue content
-with a bottom band for Style Uses. Plain Visual and Audio Clips need no second authoring band.
-The rule is a selectable entity with its own Window, even when overridden or currently empty.
-It remains one Use across gaps and content boundaries.
+Use `inspectorObjects` for authored rules that configure a Track but are not timeline occurrences.
+For example, Caption keeps Style Uses in its Inspector while Cue Items occupy its Timeline. The
+Use can still show its authored scope and expose its Style controls without pretending that the
+scope is a draggable occurrence.
```ts
-bands: [{ id: "uses", placement: "after", heightPx: 15, display: "label" }]
-// The projected Use entity selects: band: "uses"
+inspectorObjects: [{
+ id: "uses",
+ label: "Presentation Rules",
+ bindings: [{ name: "style", companion: true }],
+ project: projectUses,
+}]
```
-Use `attachments` for independent child objects such as Ranking reveals. Use a Band for another
-aspect of the same Track such as its appearance choices. Both use ordinary entity selection,
-overlap order, field declarations and time editing. Each entity chooses one declared band or lane.
+Use `attachments` for independently represented child content such as Ranking reveals. An attached
+child is a real Track with its own Items and time identity; an Inspector object is not. Keep this
+distinction instead of turning every author rule into another timeline row.
-## Connect the picture to the entity
+## Connect the picture to the Item
Associate the actual rendered parts with `presentId` or `renderIds`. All phases belonging to the
same item can select that item: entrance, movement and settled appearance. Give the board/background
@@ -77,7 +81,7 @@ parts to the parent and the reveal's parts to its child when separate selection
The renderer's explicit `subjectId` can associate multiple rendered phases with one domain item;
the Companion carries their actual ids into `renderIds`. Studio uses the visible parts at the
current frame. This preserves selection after an icon lands without duplicating animation geometry
-in the Companion. A preset with no separately exposed child remains part of the parent entity.
+in the Companion. A preset with no separately exposed child remains part of the parent Item.
Picture selection and timeline selection identify the same authored object. If position and size
are exposed choices, its declared Inspector fields can adjust them.
@@ -86,14 +90,14 @@ are exposed choices, its declared Inspector fields can adjust them.
Declare `bindings` for the actual author endpoints, then choose visible `inspector` fields. A
binding can follow a shared authored Frame or Style through `referenced`, or an SVS Recipe through
-`recipe`. Use `parameterReferences` for an entity's actual reference, when a derived entity points to a different authored object. Shared values retain their shared effect when edited.
+`recipe`. Use `parameterReferences` for an Item's actual reference, when a derived Item points to a different authored object. Shared values retain their shared effect when edited.
A Companion presents the author model. A meaningful semantic event may deserve a timeline handle
without turning every animation key into an Inspector field. Conversely, a visible number or
qualitative setting inside drawing code need not become a public input. The
[parameter boundary](component-design.md#expose-the-choices-the-work-needs) applies before choosing UI controls. When an Inspector adjustment
is actually needed, bind it to a real Source input or domain event. A label inside a one-off renderer
-can remain an implementation detail until external control has a purpose. Useful child entities can
+can remain an implementation detail until external control has a purpose. Useful child Items can
live inside the same Track, and selection can be read-only. The
[component boundary](component-design.md#separate-responsibility-parameters-and-reuse) determines
what is independently organized; it does not prescribe how many controls to provide.
@@ -152,10 +156,10 @@ performs the declared conversion, serializes in the source language and saves th
## Preserve the timing decision through editing
-Carry the real Window/Instant lineage into each entity. For a domain Spec consumed beside a
+Carry the real Window/Instant lineage into each Item. For a domain Spec consumed beside a
projection, `temporalLineageFor(context, item.id, "activation")` follows that actual consumer input;
use the real input name, such as `window`, `outer` or `activation`. `authoredChildFor` and
-`childEntities` connect domain child identities to their exact author origins.
+`childItems` connect domain child identities to their exact author origins.
The [authored time form](timing.md#choose-what-a-later-edit-changes) determines the edit: a direct
Selection changes its two Script anchors, a direct Moment changes one anchor, and a quoted clock
@@ -182,6 +186,6 @@ optional package has been deliberately selected and installed by the project; it
default Distribution.
Try the component in its actual Run: select a meaningful picture part, inspect the corresponding
-timeline entity, change an exposed value and inspect the owning Source and resulting picture.
+timeline Item, change an exposed value and inspect the owning Source and resulting picture.
For a shared timing edit, inspect the other consumers too. Seek into both movement and settled
states when those belong to the component's behavior.
diff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.md
index 4dfb2fff..28801060 100644
--- a/skills/hypit/references/production/studio.md
+++ b/skills/hypit/references/production/studio.md
@@ -159,17 +159,18 @@ include when the user wants to continue editing on another machine.
| View | What it shows and what it can change |
| --- | --- |
| Source | The exact Run, Author and imported Source/Recipe files. Select a file and use Edit source; changes save automatically, and Cmd/Ctrl+S saves immediately. Check save/error state. This is not a project filesystem browser. |
-| Preview | The selected Film composition evaluated from its compiled `HtmlProgram` in the browser. Play or seek with the transport or timeline. Selecting a component-declared visual part selects its corresponding timeline entity; adjust its exposed position in the Inspector. |
-| Timeline | Semantic Segments, Selections and Moments, plus the component-projected Track entities and their visible intervals, materials or event lanes. A rectangle may describe occupancy, activation or persistent visibility; read the component's meaning. |
-| Inspector | With nothing selected, project, Canvas, time and Run facts. For a selected entity, its declared read-only facts and adjustable fields, organized under Where, When and How where applicable. |
+| Preview | The selected Film composition evaluated from its compiled `HtmlProgram` in the browser. Play or seek with the transport or timeline. Selecting a component-declared visual part selects its corresponding timeline Item; adjust its exposed position in the Inspector. |
+| Timeline | Projected domain evidence, authored Instants and Windows, plus component-projected Track Items and their visible intervals, materials or event lanes. A rectangle may describe occupancy, activation or persistent visibility; read the component's meaning. |
+| Inspector | With nothing selected, project, Canvas, time and Run facts. For a selected Item, its declared read-only facts and adjustable fields, organized under Where, When and How where applicable. |
| Tasks | One card per Build, grouped into ongoing and finished. Active status and progress come from the selected Runtime; completed, failed and cancelled Builds come from project Results. Cards retain the source Run, times and any failure or attention reason. |
| Artifacts | Image, video and audio file Outputs from project Results, including those already published by ongoing Builds. Use the sidebar to choose all media, videos, images or audio. View media on a Build opens its Outputs; opening the Artifacts tab returns to project media. Structured Outputs such as normalized media and NarrativeAlignment stay intact and do not add their internal files to this gallery. Click a card to view it in the central preview; video and audio have playback and a time slider. Back to composition returns to the existing composition position. Previewing a file does not select it as a Candidate in the Run. |
A declared lane stays one row even when items overlap. Later items cover earlier ones at equal
stacking order; selecting an item brings its full rectangle forward within that lane. This changes
editor selection, not the Film's paint order. The same behavior applies to attached child lanes.
-The time ruler and its Segment, Word and Selection/Moment bands form one pinned Timeline area.
-Empty information bands are omitted; a work without Segments keeps the ordinary time ruler.
+The time ruler, each projection's mapping and evidence rows, and the shared authored temporal row
+form one pinned Timeline area. Empty information rows are omitted; a work without a domain
+projection keeps the ordinary time ruler and its authored temporal declarations.
Select an overlapping object to bring it forward, or right-click the overlap to choose one covered
by its peers. This changes editor selection, not the composition.
@@ -246,6 +247,6 @@ lifetime, a reveal event, a Cue's actual Style, or a scene's layout choices. Its
the rendered work. Generic Track projection is useful when no additional authoring concepts are
needed; a component with meaningful child events or controls can publish those directly.
-Read [Companion authoring](studio-companions.md) for entities and child lanes, picture selection,
+Read [Companion authoring](studio-companions.md) for Items and child lanes, picture selection,
parameter controls, unit conversion, semantic writeback and package activation. It builds on the
same [component design](component-design.md) decisions used to make the video.
diff --git a/skills/hypit/references/production/system.md b/skills/hypit/references/production/system.md
index cfe3e000..531a106a 100644
--- a/skills/hypit/references/production/system.md
+++ b/skills/hypit/references/production/system.md
@@ -58,9 +58,9 @@ Behavior spanning several occurrences—such as a continuing presenter, slidesho
ducking relationship—belongs to a component. It can publish ordinary VisualTrack and/or AudioTrack
outputs for Film. [Tracks](tracks.md) routes ordinary Clips and richer components.
-Caption is another peer relation: a document owns displayed text and hard breaks, CaptionTiming owns
-complete absolute Unit boundaries, and a Caption family owns Cue formation, visible scheduling and
-drawing.
+Caption is another peer relation: a document owns displayed Words, correspondence Units and authored
+Cues; CaptionTiming owns complete absolute Unit boundaries; and a Caption family owns visible
+scheduling, layout, motion and drawing without redefining Cue membership.
## Give each part the direction it can realize