@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/system.md

@@ -0,0 +1,169 @@
+# How a Hypit production fits together
+
+Read this for the relationships among material, meaning, time, space, presentation and execution.
+[Production navigation](index.md) routes each current question to its detailed owner.
+
+> Give semantics to the timeline, rather than the timeline to semantics.
+>
+> Give layers to the canvas, rather than the canvas to layers.
+
+The work has a complete time range and a canvas. Attach events to their meaning in the performed
+work; introduce component boundaries where content shares useful layout, state or motion. Semantic
+coverage need not fill time, and visual components need not partition the canvas into fixed regions.
+The author decides which relationships the work needs. Hypit expresses and realizes them.
+
+## Materials acquire their roles through use
+
+A supplied file, a generated Output and a reused Result can supply the same kind of material.
+An image has dimensions; moving media has local time and selected picture/audio streams. Transparency
+is a property of the prepared picture. A model reference, a performed passage and an independent
+illustration are uses of material, not separate file classes.
+
+For a work carried by performance, including a short drama or an otherwise pure A-roll piece,
+prefer Script and semantic preparation. Script names meaningful, performable passages and events;
+the accepted performance supplies their actual time. This remains useful without MG: replacing a
+passage, revising dialogue, placing Caption or directing sound can preserve the same relationships.
+A Segment need not equal one camera shot or one speaker turn.
+
+In this spoken chain, A-roll is the performance carrying the Script passage. Its picture can fill
+the frame, move, disappear beneath evidence, or be absent in an audio-only performance. That role
+specifies neither a source aspect ratio nor a visual component type.
+
+Material identity, performance role and current appearance answer different questions. One placed
+performance can supply several simultaneous views; a later replay of its source can have independent
+playback. Direct cuts and continuous movement are authored ways to change presentation. The Timeline
+keeps the performance's time, while each visual owner determines its use on the Canvas. A layout
+change can reuse the same accepted material and semantic evidence.
+
+A **SemanticTake** combines one Segment's prepared media with its local word and boundary positions.
+The current Timeline Take input is this value. Independent images, video inserts and music instead
+enter the components that use them; they do not need artificial Script passages. A wordless performed
+Segment has real media and its boundary times. A standalone material transformation can finish with
+the transformed asset. [Media preparation](media.md) explains these input relationships.
+
+## One Timeline provides the work's time
+
+The **Timeline** holds the complete range and placed Takes. A Take's placement translates its local
+positions into program time. Gaps, overlaps and a range with no Takes are valid. A code-authored ending
+can extend past the last performance; a wholly authored animation uses the same Timeline.
+
+For an event that responds to a word or passage, retain the Script Moment or Selection. The component's
+Surface projects that reference through the actual Timeline to an Instant or Window. Independent
+rhythm can use authored clock positions, and motion can have its own duration. These all use the
+same program clock. [Timeline](timeline.md) owns placement; [Timing](timing.md) owns event expressions.
+
+Placed content is available before any presentation is selected. Timeline chooses no winning
+picture, transition or audible mix. An overlap supplies multiple sources; the presentation owns how
+they appear or sound. Independent Media, graphics and audio also use this Timeline to place events,
+including events attached to speech.
+
+## One Canvas provides the work's space
+
+The **Canvas** supplies picture dimensions and coordinates. A Frame locates a destination; fitting
+maps a source's real extent into it. Components own their internal layout and motion. A presenter
+and diagram can share a scene, while an independent title remains a peer. Frames may overlap, nest,
+move or extend beyond the canvas.
+
+Canvas is a geometry value, not a second asset store or a central layer tree. Each visual contribution
+publishes its own appearances and internal trees. A **Present** owns an appearance's lifetime and
+paint order; that order determines what covers what. [Spatial layout](spatial.md) owns geometry;
+[component design](component-design.md) owns useful visual scope.
+
+Time authority and visual scope are independent choices. One scene can follow several semantic
+events; separate components can share one Moment. Giving a scene the whole canvas does not require
+fixed-second choreography. Giving an image a semantic Window does not turn it into a Take.
+
+## Present existing content or supply independent content
+
+Two content relationships recur in ordinary authoring:
+
+| Content | Present already authored content | Supply content for this contribution |
+| --- | --- | --- |
+| Picture | Performance obtains footage and source positions from Timeline. | Media receives images, prepared video or compositable surfaces. |
+| Sound | Sound obtains placed audio from Timeline. | Audio Track receives independent audio-bearing material. |
+| Text | Caption obtains Script display content and its performed timing. | Typography/Text receives independent writing. |
+
+These are useful starting points. A project scene can combine placed footage, independent assets,
+text and projected events when they share behavior. The same video can carry a performance here and
+serve as an independent replay elsewhere. [Tracks](tracks.md) routes the actual presentation choices.
+
+Performance, Sound and Caption separate available content, timed **Uses**, and the **Style** applied
+by each Use. Later matching Uses replace the treatment locally; independent Tracks can coexist.
+The content retains its original timing under these choices. Each family owns its rendering and
+content-specific rules.
+
+Keep three times distinct: program time locates the appearance, source time identifies the media
+frame, and local animation time determines the presentation's state. A Take placed at second 5 is
+at source second 2 at program second 7, even if its viewport only becomes visible then. Performance
+and project scenes can consume this mapping directly. An independent Media Item instead declares
+its own source and playback policy. [Performance](performance.md) explains continuous presentation.
+
+An original and a cutout are explicit material choices. If the placed Take contains only the cutout
+picture, a presentation needing its original background must receive the retained original as an
+input. No Style can recover pixels absent from its material.
+
+## Components express the relationship worth preserving
+
+A component owns shared behavior. Its public inputs connect actual dependencies and useful directing
+choices: selected assets, important events, placement or a treatment that the work needs to vary.
+Decorative geometry and a fixed local design can remain in its implementation. A one-off scene is
+ordinary production work; reuse and cross-project distribution are separate decisions.
+
+Critical internal events need their own semantic relationships when they answer different parts of
+the performance. Making only the scene's outer Window semantic does not keep several word-linked
+actions synchronized. Interpolation and local motion can then follow those events without exposing
+every number as a control. [Component design](component-design.md#let-meaning-drive-the-behavior)
+explains that boundary; [Track authoring](track-authoring.md) explains the public implementation path.
+
+Visual components publish VisualTracks; audible contributions publish AudioTracks. Film explicitly
+selects the wanted contributions and combines them with Timeline and Canvas into a **Composition**.
+Including picture does not include sibling sound automatically. A whole scene can publish both
+outputs while keeping their assembly explicit. Source nesting, component scope, paint order and
+execution dependencies describe different relationships and need not have matching boundaries.
+
+## Give each part the direction it can realize
+
+The Agent keeps the complete creative intention and translates it into each part's effective inputs.
+
+| Recipient | Direction it can realize |
+| --- | --- |
+| Image generation | Visible appearance, setting, camera relationship, activity and reference facts. |
+| Video generation | Dialogue, performance, physical interaction, camera behavior and intended cuts. |
+| Voice generation | Wording, vocal character, delivery and suitable voice references. |
+| Visual/audio components | Selected content, layout, events, treatments and mix. |
+
+A planned diagram may call for a person framed on the right. Give the image request that visible
+camera relationship; give the diagram component its placement and events. Translate later MG or
+screen-writing needs into the picture facts the image model can produce. The full Treatment remains
+the director's context. [Image direction](../playbooks/craft/image-direction.md),
+[video direction](../playbooks/craft/video-direction.md), [voice direction](../playbooks/craft/voice-direction.md)
+and [Prompt Kits](prompt-kits.md) own those local decisions and templates.
+
+## Source describes the work; Run selects this execution
+
+The Author Source connects content, media requests, components and deliverables. Recipes provide
+authored values. A Run chooses public Outputs as **Targets** and can supply alternative **Candidates**,
+such as a file or an exact earlier Result Output. The selected dependencies determine what executes.
+
+For a layout revision, keeping a compatible SemanticTake preserves the performance and alignment
+while the presentation recomputes. Keeping only its generated video lets normalization and alignment
+recompute too. Keeping the old Composition would also preserve the old layout. Choose the reuse
+boundary according to the current edit. [Authoring](authoring.md#reuse-produced-work-explicitly)
+owns that judgment; [Runs](runs.md) owns the syntax.
+
+A **Build** executes the selected work. Its **Result** retains completed public Outputs, including
+usable products completed before a later failure. A new Build uses prior work only through explicit
+selection. [Builds](builds.md) owns execution, recovery and retrieval.
+
+## Runtime and Studio serve the authored work
+
+External work is expressed as a Need. Model and processing packages define capabilities; Providers
+implement them through Endpoints selected by a Runtime Profile. Tools, credentials and capacity belong
+to those execution choices. [Environment](../environment/profile.md) owns setup; [rendering](rendering.md)
+owns requesting an encoded output from the Composition.
+
+Studio inspects the same selected Run. A package's Companion connects recognizable entities and
+useful controls to their actual authored facts. Editing a shared Style or semantic event affects
+its consumers; a local parameter changes its own owner. Studio does not require every internal
+detail to become editable. [Studio](studio.md) explains use and writeback;
+[Companion authoring](studio-companions.md) explains project integration.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/timeline.md

@@ -0,0 +1,74 @@
+# Placing Takes on the Timeline
+
+Use this when placing prepared Takes, leaving passages for MG, or creating a work without speech.
+[Media preparation](media.md) produces local SemanticTakes; [Script syntax](script-syntax.md)
+names Selection/Moment identities. [Timing](timing.md) projects them; [Tracks](tracks.md) explains presentation.
+
+A Timeline contains the complete time range and the Takes placed within it. Semantic anchors exist
+where those Takes supply them. Prefer this semantic organization for performance-led work, including
+pure A-roll and short drama without MG. A meaningful passage can span shots or speakers; its actual
+performance gives the authored words and boundaries time. For an event responding to speech, bind
+to its Selection or Moment; use authored time for independently directed rhythm. Both belong to this
+one Timeline.
+The project's reference `TIMELINE.md` records observations and their meaning; the production
+`time:Timeline` declaration places the new work's material. Reference times locate evidence, while
+production placements determine the rendered work.
+
+```svml
+<import as="time" from="@hypit/timeline-author@1"/>
+<time:Clock id="clock" frame-rate="30"/>
+<time:Timeline id="program" clock={clock} end="content.end+2s">
+  <time:Take source={opening.take} at="2s"/>
+  <time:Take source={explanation.take} at="previous.end+3s"/>
+  <time:Take source={closing.take} at="previous.end-12f"/>
+</time:Timeline>
+```
+
+First omitted `at` means zero; later omitted `at` means the preceding Take's end. Omitted Timeline
+`end` means the latest end of all Takes. Ordinary sequential assembly therefore needs only the
+Clock and Take references. Material lengths resolve when preparation finishes; generation can run
+concurrently while these placement relations wait for their inputs.
+
+`previous.end` refers to the preceding declaration. `content.end` is the maximum of all placed
+ends, even when the latest-ending Take is not the last declaration. Absolute positions such as `20s`
+work too. `end="30s"` reserves a fixed complete duration; `end="content.end+2s"` reserves a tail.
+Reordering Take declarations changes placements that depend on `previous.end`, including omitted
+`at` values, and can therefore move later dependent Takes.
+Seconds, milliseconds and frames must resolve to exact frames on the Clock. All complete Takes fit
+inside the authored extent. Take placement retains native speed and local semantic evidence.
+
+The current `time:Take source` accepts a SemanticTake, not an arbitrary image, video or audio file.
+Independent assets enter their own components with this Timeline as their time context. Each placed
+Segment and its token/anchor identities occur once in a Timeline. To show the same footage again as
+an independent replay, use Media; a separate performed Script occurrence has its own Segment.
+Timeline holds placed material and evidence; it publishes no picture or sound by itself.
+
+A gap contains no performance source. A wordless Segment instead has actual prepared media, as with
+someone dancing. MG can occupy either passage according to the intended picture. Pure MG needs no
+placeholder media or Script:
+
+```svml
+<time:Timeline id="animation" clock={clock} end="30s"/>
+```
+
+The output `.timeline` supplies Film and component contexts through `timeline={program.timeline}`.
+Component Surfaces, Fragments and Producers use that same Timeline; shared temporal helpers
+project both literal times and Script references against it.
+Timeline exports only `.timeline`. [Sound](sound.md) presents its existing audio and supplies an
+AudioTrack to Film. Its ordinary Style chooses the last declared active audio source; a project
+Style can explicitly mix sources. Material remains available independently of its presentation.
+
+[Performance](performance.md) obtains existing footage from the Timeline. Ordinary Media Items take their own
+assets. Caption obtains existing words, while Typography takes authored text. A custom scene can
+consume the same placed footage and projected event times. New display Windows preserve the source
+frame corresponding to the current Program time; moving a viewport does not restart playback.
+
+Overlapping Takes make both sources available. They do not prescribe a dissolve or choose a picture.
+The ordinary Performance Style places its sampled layers in declaration order; for a coordinated blend or layout,
+use a scene that owns that behavior. Simultaneous Caption Cues retain their spoken intervals; use
+Role-based styles or separate Caption presentations when their placement should differ.
+
+Caption also receives a Script-derived CaptionDocument: the document supplies display text and cue
+structure, while Timeline supplies placed timing. Independent B-roll and music receive Timeline for
+placement and their own assets for content; semantic preparation is needed for a performed Script,
+not for every asset used in a composition.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/timing.md

@@ -0,0 +1,96 @@
+# Timing authored relationships
+
+Read this when deciding when a component acts or what moving it in Studio should change.
+[Script syntax](script-syntax.md) names speech relationships; [Timeline](timeline.md) places prepared
+Takes and declares the complete work. This page owns the common author-facing time forms.
+The consuming package's vocabulary declares which forms its Surface actually supports.
+
+## Choose time from the relationship
+
+For speech-led work, bind a reveal to the Moment it answers and a covering picture to the Selection
+it explains. The accepted SemanticTake locates those identities in its media; Timeline placement
+carries them into the whole work. Rewording or changing the performance can then preserve what the
+picture follows. Reference timecodes document observations, not the new performance's timing.
+
+Authored animation can instead place messages or state changes on a clock and give them an intended
+reading rhythm. It needs no invented Script or media-backed Segment. A spoken Moment can also trigger
+a component whose internal animation uses authored durations. The trigger, its offset and the length
+of its response are separate decisions; one video can use all of them.
+
+## Express an Instant or Window
+
+Surfaces that expose Hypit's shared temporal vocabulary accept the forms appropriate to their role.
+A Window occupies an interval:
+
+| Form | Result |
+| --- | --- |
+| `during="program"` | The complete program Window. |
+| `during={story.segment.hook}` | The Segment's Window. |
+| `during={story.selection.proof}` | The Selection's Window, including its authored affinities. |
+| `at={story.moment.claim} for="8f"` | A Window beginning at a Moment and lasting eight frames. |
+| `at="2s" for="12f"` | A Window beginning two seconds into the film and lasting twelve frames. |
+| `until={story.moment.claim} for="250ms"` | A 250 ms Window ending at a Moment. |
+| `start="program.start" end="moment.cue" moment={story.moment.claim}` | A Window composed from two explicit endpoints. |
+
+Each Window uses one complete form. Explicit endpoint expressions can use `program.start`,
+`program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end`, or `moment.cue`,
+with the corresponding semantic reference supplied alongside it. They can also use a clock position
+such as `1.5s` or an offset such as `selection.start - 2f`. Frames and milliseconds are integers;
+seconds may be fractional.
+
+An Instant names one point:
+
+| Form | Result |
+| --- | --- |
+| `at={story.moment.claim}` | The authored Moment. |
+| `at="2s"` or `at="12f"` | A point on the film clock, in seconds or frames. |
+| `at={story.selection.proof} boundary="start"` | The Selection's chosen boundary. |
+| `at={story.segment.hook} boundary="end"` | The Segment's chosen boundary. |
+| `instant="program.start + 8f"` | An explicit clock expression. |
+| `instant="moment.cue + 12f" moment={story.moment.claim}` | Twelve frames after the Moment, following it when the delivery changes. |
+
+`at="12f"` locates an event; `for="12f"` gives an interval its length. Frames use the selected
+film clock. Semantic projection keeps the event's Script identity alongside its resolved frame,
+so its authored relationship remains available for later changes.
+
+A particular Surface may deliberately expose only some of these forms. Its vocabulary reports the
+attributes it actually accepts; the shared spelling does not grant every component every temporal
+behavior.
+
+## Choose what a later edit changes
+
+Dragging a direct Selection or Moment changes that identity in Script. Every Track consuming it
+then follows the changed relation. The authored time form determines what the gesture changes:
+
+| Time form | Timeline editing |
+| --- | --- |
+| `during={story.selection.proof}` | Move both boundaries by the same number of semantic stops; the duration can change. Trim either boundary independently. |
+| `at={story.moment.reveal}` on an event | Move its Moment anchor. |
+| `at={story.selection.proof} boundary="start"` or `boundary="end"` on an event | Move only that Selection boundary. |
+| `at={story.moment.reveal} for="8f"` | Move the Moment, or trim the trailing edge to change the duration. |
+| `until={story.moment.reveal} for="8f"` | Move the Moment, or trim the leading edge to change the duration. |
+| `at="2s" for="8f"` | Move the clock position, or trim the trailing duration; `until/for` works conversely. |
+| `instant="moment.cue"` or `instant="moment.cue + 2f"` with a bound Moment | Move the local offset while retaining the Moment; an omitted offset starts at zero. |
+| `start="..." end="..."` | Trim one endpoint's time expression, or move both by the same frame delta. Referenced Script markers stay in place. |
+
+A semantic stop is a distinct frame position occupied by word or structural boundaries. Select a
+semantic marker to see its exact anchors; when several share a frame, the Inspector offers the
+choices supported by its editable consumers. Word starts, word ends and structural boundaries
+are all eligible anchors; a pause can belong to
+either neighboring interval. Direct Segment/Program spans follow their structural boundaries
+without timeline dragging. The executed time authority determines the available gestures, and
+the Companion connects them to the component's entities and Source bindings.
+
+Clock-based dragging writes the changed value or offset in whole frames at the current frame rate.
+Unedited expressions retain their units: `2s` keeps its duration across frame-rate changes, while
+`60f` keeps its frame count. Direct semantic dragging changes the Script anchors instead.
+
+Script marker moves use the [same semantic affinities](script-syntax.md#bind-meaning-to-script-identities)
+as authored markers. Writeback removes and inserts the moved markers while preserving unrelated
+source whitespace, words, punctuation, pronunciation and display attributes. A shared Selection or Moment remains one relationship:
+editing through any consumer updates its other consumers according to their own projections.
+
+A component's Companion exposes the gestures it can write back to the authoring source.
+[Studio](studio.md) explains the editing interface; [Track authoring](track-authoring.md) explains
+using the shared temporal helpers in a project component. The installed `@hypit/temporal-markup`
+package owns exact parsing, projection and write-target APIs.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/track-authoring.md

@@ -0,0 +1,215 @@
+# Writing a project Track
+
+Read this when a production needs new visual or audible structure, state or rendering behavior,
+including a scene that coordinates existing footage with independent content. Begin from
+what the viewer should perceive and what should follow a changed performance.
+[Component design](component-design.md) develops that idea into a useful author interface and a
+coherent treatment in the actual composition.
+[Composing Tracks](tracks.md) covers existing Track roles; [vocabulary](vocabulary.md) covers discovery
+and project package ownership. [Caption authoring](caption-authoring.md) covers the speech-text case.
+
+## Start with the author-visible behavior
+
+Prefer semantic inputs when the component responds to the words or performance. A comparison can occupy
+a Selection; a verdict can trigger a Moment; the whole board can live for a Segment. Expose those
+choices on the Surface and pass their projected Windows or Instants to the implementation. This
+keeps the component useful when a new performance changes the pace. Expose separately meaningful
+internal events as well as the outer lifetime. The [event-versus-animation boundary](component-design.md#let-meaning-drive-the-behavior)
+explains why a single semantic Window cannot replace several word-linked triggers. In an authored animation,
+content events carry their own reading rhythm. Their Instants and Windows enter the same component
+inputs; durations and frame offsets direct how a change unfolds.
+
+Write a small intended Source use before implementing it. A new score strip might have one Style,
+an outer Window, preset scores and score-changing Moments. Decide whether its items appear briefly,
+remain after activation, replace a previous state, or rearrange the layout. Those differences define
+the component more usefully than a long list of decorative parameters.
+
+This existing answer-strip vocabulary illustrates a concrete choice:
+
+```svml
+<emoji:Track id="answers" timeline={speech.timeline} canvas={canvas}
+  style={answer-style} placeholder={question-icon} during="program">
+  <emoji:Item id="known" icon={known-icon} preset="true"/>
+  <emoji:Item id="surprise" icon={answer-icon} at={story.moment.reveal}/>
+</emoji:Track>
+```
+
+Its outer Window owns visibility; source order owns slots; preset answers exist at the beginning;
+each Moment changes only its slot and the answer persists. A chart or scoreboard can instead own
+repeated updates or simultaneous events.
+
+## Keep selection, projection and consumption distinct
+
+Script names meaning: a Selection, Segment or Moment. The Timeline supplies where that
+event falls after its prepared media is placed. The consuming component's Surface lowers its authored timing
+form into a projection subgraph, which resolves an Instant or Window in the program's frame space.
+The component's own Fragment and Producers then decide what to do with that value.
+
+```text
+Script Selection / Segment / Moment + Timeline
+                         ↓ component Surface creates projection
+                Timeline + Window / Instant
+                         ↓ component Fragment / Producer consumption
+              media occupancy, graphic state, sound or effect
+```
+
+This separation lets one Moment drive an answer reveal, a short sound and a flash. Each consumer
+receives its own appropriate projection, but all refer to the same authored event. Changed speech
+moves the event without asking each component to search for a word or inspect the Script parser.
+
+Use `resolveTemporalContext` from `@hypit/hypit/temporal-markup` to resolve the component's
+`timeline` input. Pass that same Timeline to its Fragment and Producers, alongside projected
+Instants/Windows. A component can combine literal times and word-bound events without switching time
+models. The installed `examples/semantic-composition/packages/chat-scene` demonstrates repeated
+content children with their own events and a picture drawn entirely in code.
+
+For a Window consumer, `during={story.selection.example}` can take both semantic boundaries.
+`at={story.moment.answer} for="8f"` starts a short effect at a Moment. An Instant consumer may accept
+`at={story.moment.answer}` with no duration because it owns a state transition. Read the actual
+Surface: identical-looking `at` attributes do not imply identical consumption. [Timing](timing.md) describes the shared author
+forms; the component chooses which of them fit its behavior.
+
+## Separate lifetime, activation and persistent state
+
+For a board that stays on screen, author its outer Window independently of individual reveals.
+Then decide what its children mean:
+
+- an Item window may mean “draw only during this interval,” as with ordinary Media;
+- an activation window may stage an item's entrance and movement, after which it remains in a board;
+- a Moment may replace a question mark with an answer that persists until the outer Window ends;
+- a preset item may already occupy the initial state and need no reveal trigger.
+
+Document that meaning in the component. `preset` is the answer strip's package-owned initial-state
+concept. An answer strip consumes an Instant for a reveal that persists, while Media consumes a
+Window for occupancy. Expose timing inputs whose consumption matches the behavior.
+
+The interview's project emoji strip illustrates this design: one outer Window, ordered answer
+items, a placeholder asset and one icon per answer. Each Moment changes its own slot. The Track does
+not decide when the spoken answer occurred; it consumes the already projected event.
+
+## Use the Timeline's existing placement model
+
+The [Timeline](timeline.md) places intact prepared Takes at native speed. Sequential placement,
+head/interior/tail space and simultaneous Takes share the same data type. A project scene consumes
+its range, media samples and semantic events through ordinary projection helpers.
+
+A different material operation, such as trimming or retiming a performance, changes the local media
+and its preparation. A display operation, such as crossfading two available sources, belongs to the
+visual scope owning them. Keep these decisions distinct so a layout change preserves source timing
+and a material change establishes truthful local evidence.
+
+## Make spatial decisions equally explicit
+
+CanvasSpace identifies the coordinate system. SpatialFrame, anchors, extents and fitting describe
+where content goes and how its intrinsic shape occupies that place. RegionTimeline supplies authored
+per-frame regions in a chosen Canvas. These are distinct from Timeline, which owns the complete time range.
+
+Keep image dimensions, placement and crop transformations visible so a measured head or a reserved
+MG area maps into the actual composition. Take the production's Canvas and the placement inputs the role needs. Derive related internal
+geometry from their common owner. A project scene may keep a fixed layout and speaker arrangement;
+a reusable behavior exposes the variation its real uses require. Keep renderer viewport selection
+and any detector in their own execution or measurement boundary.
+
+## Write the smallest component that expresses the role
+
+Declare the new package in the project's `packages/` and ordinary package configuration. Read the
+installed `@hypit/hypit/author-kit` README for the public package boundary and inspect a close installed sibling for
+the relevant implementation, rather than depending on a monorepo example directory being present.
+`@hypit/interview-emoji-reveal` demonstrates persistent Moment-driven state; `@hypit/ranking`
+demonstrates reveal Windows and settled rows; `@hypit/media-track` demonstrates occupancy and Handoffs.
+
+Ranking provides a complete example in the installed Distribution. Its `packages/ranking/README.md`
+links the relevant files: `surface.ts` projects authored time, `fragment.ts` connects typed inputs,
+`schedule.ts` computes reveal and settled spans, `render.ts` draws them, and
+`packages/ranking-studio/src/index.ts` turns the same program into editor entities. Follow the part
+that answers the current question. A new component may use fewer operations or different state.
+
+The Surface exposes author intent and lowers its supported temporal forms through shared projection
+helpers such as `createTemporalWindowProjection` and `createTemporalInstantProjection`. The Fragment
+wires those projections, the shared Timeline/Canvas and authored values into the component's
+Producers. The Producer consumes the resulting time and geometry and owns the visual/state behavior;
+Studio consumes that published meaning for presentation and editing.
+
+Wire supplied media, Script content and event references through Source. Expose other content or
+treatment in Source or Recipe where the work needs those choices. A one-off component can own fixed
+illustrative labels, dimensions and animation alongside its state and visual structure; its boundary
+does not require every detail to become a parameter. [Component design](component-design.md#separate-responsibility-parameters-and-reuse)
+explains that distinction. A new Caption family consumes the common Caption document and timing.
+
+## Connect the implementation at its real boundaries
+
+The useful pieces of a project package are:
+
+| Piece | Responsibility |
+| --- | --- |
+| Manifest | Module identity, nominal Types, Producer input/output ports and dependencies |
+| Surface | Validate authored attributes and children, resolve typed references, emit inert Records, Components and Fragments |
+| Fragment | Wire the finite computation graph and publish outputs |
+| Producer | Compute the immutable state or render program from declared inputs |
+| Activation | Register the Manifest, deterministic handlers and Markup facets with their matching Host ABI |
+| Vocabulary and preview | Explain the role and show a recognizable, configured example |
+| Optional Studio Companion | Project meaningful editor entities, real parameter bindings and temporal lineage without changing video rendering |
+
+Resolve the Track's `timeline` through `resolveTemporalContext` and wire `context.timeline.ref`
+directly to its Timeline input. Words and source footage are available where prepared Takes provide
+them. The visual Producer consumes Timeline and projected times, not Script syntax.
+
+For each Window, call `createTemporalWindowProjection`; for an event, use
+`createTemporalInstantProjection`. Pass the resolved context, the child element
+and `resolveReference`. Preserve all returned `records`, `components` and `fragments`, and wire the
+returned `ref` into the domain Fragment. The common `at` accepts a Moment or an authored duration
+from program start. Selection and Segment boundaries use `boundary="start"` or `boundary="end"`.
+A Moment needs the semantic context that locates its Script anchor.
+
+Keep each child's `subjectId` meaningful to the component while qualifying graph ids by its owning
+Track, so multiple instances can coexist. A finite create/append/finalize graph supports any authored
+number of messages or cards with ordinary fixed Producer ports. The exact helpers and vocabulary
+live in `@hypit/hypit/temporal-markup`; the `@example/chat-scene` package demonstrates authored and semantic events on one Timeline.
+
+A scene may publish computed event times when another component needs them, just as it publishes a
+Track. This shares pre-render data. When the author already specifies a common trigger, consumers
+can share that input directly. Expose additional outputs for a real composition relationship.
+
+For persistent state, reason about a requested frame directly. For example: outside the outer Window,
+draw nothing; inside it, each slot shows its preset/activated answer or its placeholder. Apply an
+entrance motion relative to that slot's activation frame. Deriving state directly from declared inputs
+and the requested frame keeps Studio scrubbing and partial or concurrent rendering deterministic.
+
+Emit the public VisualTrack representation through `@hypit/hypit/composition` and `@hypit/hypit/visual-ir`.
+[Component visuals](component-visuals.md) explains Presents, element trees, local animation,
+prepared surfaces and a complete drawing function. [Spatial layout](spatial.md) explains incoming
+Frames, and [Fonts and text](fonts-and-text.md) explains font resources.
+Pass asset references and exact font data through declared inputs. A visual Producer does not open
+files, call GVI, run ffmpeg or choose a Provider. If an external preparation operation is needed,
+represent it separately through its capability; its result becomes another input.
+
+A component-owned sound can be a peer AudioTrack output; alternatively the Source can place a sound
+on the same Moment. Neither choice requires a Track to inspect another Track's private state.
+Document which Outputs are public, including useful deterministic program values for inspection.
+
+## Verify the behavior the component introduced
+
+When the new role needs its own timeline presentation or Inspector, read
+[Companion authoring](studio-companions.md). Expose the domain
+schedule and temporal identities at their actual boundaries so the editor consumes them directly
+instead of reconstructing them from pixels.
+
+Give the component a concise README, public vocabulary, a meaningful visual example and a preview
+showing the state change. State each exposed event's meaning and which state persists after it.
+When several actions follow different phrases, check their separate anchors through a delivery with
+uneven spacing; stretching only the outer Window would conceal a wrongly fixed internal trigger.
+Verify the actual intended transition: an answer appears on its Moment,
+previous answers persist, future ones remain hidden, and the whole strip respects its outer Window.
+A designed still alone cannot establish that behavior. For stateful MG, a few meaningful frame
+checks around activation and exit are more useful than snapshots of every implementation detail.
+Also check a second instance, a differently sized Frame and direct seeking into the middle when
+those exercise the new behavior.
+
+## A reusable performance presentation
+
+When the behavior presents existing Timeline footage, [Performance Styles](performance.md) offer
+an occurrence model with broad and local Uses. A Style binds a typed fragment's additional inputs;
+each Use supplies Timeline, Canvas and its original Window. The fragment exports a VisualTrack.
+This supports project-owned HTML behavior and explicit extra events or material without introducing
+a new Track protocol. A larger scene that coordinates footage and independent graphics can remain
+its own component. Both paths use the same rendering capabilities.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/tracks.md

@@ -0,0 +1,67 @@
+# Choosing and composing contributions
+
+Read this to choose how content enters the picture or sound. [System](system.md) explains the
+relationships; [media preparation](media.md), [Timing](timing.md) and [spatial layout](spatial.md)
+own the shared inputs. A new shared behavior belongs in a [project component](component-design.md).
+
+## Choose by content relationship
+
+| Content relationship | Useful starting point | Published contribution |
+| --- | --- | --- |
+| Present footage already placed on Timeline | [Performance](performance.md) | `.visual` |
+| Supply an independent image, prepared video or compositable surface | [Media](media-presentation.md) | `.visual`, optional `.audio` |
+| Present audio already placed on Timeline | [Sound](sound.md) | `.audio` |
+| Supply independent audio-bearing material | [Audio Track](audio-presentation.md) | `.audio` |
+| Present Script's display words at their performed times | [Caption](caption-presentation.md) | Fine publishes `.track` |
+| Supply a title, label or other independent writing | [Typography/Text](fonts-and-text.md) | Package-owned; Typography publishes `.track` |
+| Coordinate content through a new layout, state or motion | [Project component](track-authoring.md) | Its declared VisualTrack and/or AudioTrack outputs |
+
+The table routes common relationships; it does not define a closed list of visual roles. A board,
+effect or whole scene is a component whose behavior owns its inputs and outputs. Images, text and
+video can share one scene. Film receives their ordinary visual and audio contributions.
+
+## Present a performance without reauthoring its playback
+
+For pure A-roll as well as mixed work, place prepared SemanticTakes on the [Timeline](timeline.md),
+then use Performance and Sound for the picture and audio the work needs. A broad Style can cover the
+whole program; local Uses change its treatment. Caption independently joins Script display content
+to that same timing. A performance need not remain visible to supply speech and semantic events.
+
+An audio-only Take supplies no picture. A wordless performed Take can supply material and Segment
+boundaries. A gap has no Take. These facts remain independent of graphics occupying that interval.
+Independent material can also occupy the full canvas; size and transparency do not decide its role.
+
+A new scene can consume `projectTimelineMedia` to keep placed footage at its current source frame
+while coordinating it with other content. [Performance](performance.md) explains Styles;
+[component visuals](component-visuals.md#compose-video-and-graphics-in-one-browser-program) explains
+owning a larger scene. Media receives separately supplied material when that is the intended use.
+
+## Let events and shared behavior determine organization
+
+A Media picture can cover a Selection, a sound can follow a Moment, and a board can retain its answer
+after a reveal. All use the same Timeline, with timing forms supported by their own Surfaces.
+[Timing](timing.md) owns those forms; [Track authoring](track-authoring.md#keep-selection-projection-and-consumption-distinct)
+owns implementing their projection and consumption.
+
+An outer Window describes a component's lifetime. Internal events can have their own semantic
+triggers, and the resulting state may persist. A scene's single lifetime does not justify moving all
+its meaningful events to fixed percentages of that Window. Use the [component design principles](component-design.md#let-meaning-drive-the-behavior)
+to separate event relationships from local animation.
+
+Shared movement or state can justify a shared component. Independent contributions may stay peers
+while consuming the same Moment. A Track is not required for each asset, each Script Segment or each
+rectangle, and creating a component does not require publishing a package outside the project.
+
+## Assemble the intended contributions
+
+Film receives Canvas, Timeline and each selected visual/audio output. Timeline establishes the
+complete extent; components establish appearances and their paint order. Include sibling audio
+explicitly when wanted. A silent covering picture leaves the selected voice audible; selecting the
+same voice through multiple audio contributions can duplicate it.
+
+Film child order does not move a picture to the front. Each Present has its authored stacking and
+its internal element tree. An internal transform, mask or transition can keep related content
+together while independent Presents overlap it according to their own stacking.
+
+[Rendering](rendering.md#assemble-the-picture-and-sound) shows assembly and full/range delivery.
+[Review](review.md) judges the selected work, including performance, boundaries and the complete mix.