@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

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

@@ -0,0 +1,217 @@
+# Designing a good component
+
+Read this when deciding how to organize a picture, a transition or a recurring visual system.
+Design it with the taste of a director and the care of someone who will use it in a real composition.
+A useful component makes a particular idea legible and keeps its behavior understandable within the
+production. Its author interface can be as small as the work requires.
+
+[Graphic composition](../playbooks/craft/graphic-compositions.md) owns visual hierarchy;
+[motion graphics](../playbooks/craft/motion-graphics.md) owns changes in the picture over time;
+[Track authoring](track-authoring.md) owns the implementation. A new Caption family also draws on
+[Caption craft](../playbooks/craft/captions.md) and [Caption authoring](caption-authoring.md).
+
+## Find the relationship worth giving a name
+
+Start with the viewer's experience: a comparison becomes clear, an answer resolves a question, a
+ranking accumulates, or a phrase lands with particular emphasis. Explain what appears, why it appears
+there, what changes, and what the viewer should retain afterward. That explanation suggests both
+the visual design and the component boundary.
+
+Existing components are useful expressions of familiar relationships. Use one when its behavior
+fits, or define a project component for the role this work needs. Its content and timing can vary
+while the relationship remains clear. A new component can combine existing helpers with its own
+drawing and animation; ordinary authoring includes both using and extending that vocabulary.
+
+A board whose rows share layout and persistent state benefits from one component. An independent
+photo and title can remain peer Tracks. An object that survives several camera cuts keeps the same
+authored identity while its state develops. Let shared behavior define the unit.
+
+A performance moving from full screen into a side viewport and a diagram filling the released space
+can share one component. It owns their relative layout, overlap, masking and coordinated motion.
+A-roll supplies the performed passage; visual ownership follows the behavior being designed.
+Existing footage can use [Performance Styles](performance.md); independent assets use Media. A
+one-off scene is a useful component too. Caption and independent overlays can remain separate.
+
+Decompose a scene further where its parts have meaningful independent responsibilities. Keep
+coordinated geometry, state and transitions together where that makes their behavior clear. Internal
+functions and subcomponents can organize this code without each becoming another Track or package.
+The useful division preserves the relationship through change; more layers alone do not improve it.
+
+## Separate responsibility, parameters and reuse
+
+Adaptive composition introduces structure where it makes the work easier to understand and direct.
+A boundary gives a responsibility an owner; a parameter expresses a choice supplied from outside
+that owner; reuse preserves a relationship across uses. These decisions serve different needs.
+
+| Decision | What justifies it |
+| --- | --- |
+| Independent organization | A distinct visual responsibility, lifetime or behavior benefits from its own owner. Parts sharing geometry, state or motion can stay together. |
+| Parameterization | The production needs an external choice: an asset, a spoken trigger, a placement or a setting the author will actually adjust. |
+| Reusable design | Actual uses share a relationship or treatment. Share that behavior and generalize only the variation those uses need. |
+
+An author input is not a requirement to publish a package or provide a Studio control. A shared
+internal function is not necessarily another Track. Numeric and qualitative choices use the same
+criterion: does an external dependency or a useful directing decision belong here? A color, mood,
+layout mode or easing name does not deserve a public parameter merely because it could vary.
+
+One-off effects can be independently organized with fixed designs. A future edit may appropriately
+change their implementation. Consider likely revisions to reveal tangled responsibilities or useful
+inputs, rather than treating every possible edit as a parameter to implement in advance. Even repeated
+use can share the same fixed treatment. Interface breadth and reuse count do not measure component quality.
+
+For example, a backdrop and an editor demonstration have different jobs and can be organized
+separately. The editor can keep its button sizes, panel spacing, illustrative labels and pointer paths
+inside its implementation. Its pointer, dragged image and target slot share geometry and belong
+together. Supply the actual assets and speech-linked events through author inputs; expose Caption
+placement or color when those are useful adjustments. This gives the piece clear structure without
+turning the illustrated editor into configurable editing software.
+
+Choose peer Tracks for independently composed contributions, internal parts for a coordinated scene,
+and ordinary modules for code organization. These boundaries need not coincide with parameter or
+package boundaries. Splitting files helps maintenance; a named Track around a whole passage gives
+it occupancy. Judge both by whether they clarify the actual responsibilities. The spoken outline
+supplies timing context: several passages may develop one object, and one passage may contain
+several independent objects. Sharing a Moment does not by itself require a shared Track.
+
+## Keep implementation changes local
+
+Use the work's revisions to check its boundaries: a change to one visual responsibility should
+remain with its owner, while a shared change should flow through a shared dependency. When an edit
+requires reconstructing the same decision across several scenes, consolidate that decision's source.
+The aim is to make the relationship explicit, whether its owner is a fixed implementation or an author input.
+
+A useful revision question is: if delivery pauses before the result, which event should move and
+which local design should stay? Inspect the input that carries that event rather than counting how
+many parameters the component exposes. If the work needs a qualitatively different relationship,
+change its implementation or define a new component instead of accumulating speculative mode flags.
+
+Keep revisions local as the scene grows. Separate independently edited scene bodies, styling and
+frame evaluation into ordinary source modules while sharing their actual mechanics. A palette,
+typing function or media-sampling helper can be an ordinary project dependency; it needs no Surface
+or Track of its own. A shared package becomes useful when several components really use it.
+Source connects selected assets, semantic events and the component's external choices; these modules
+own their realization, including any fixed design specific to this piece.
+
+Derive related geometry from one layout. A pointer's destination should come from the target it
+clicks; an attached badge should follow its pointer; two presentations of one playing source should
+share their sampling. Then revising a layout changes its dependent motion with it.
+
+Choose visual grouping and timing independently. A combined scene can respond to spoken Moments;
+separate Tracks can share an authored event. What belongs together on the canvas does not decide
+what gives that behavior its time.
+
+Fine Caption similarly offers reusable flowing text, while a custom Caption family can own a new
+relationship among words and graphics. Both consume Script wording and semantic timing. Shared
+behavior can keep these visuals together; [Caption authoring](caption-authoring.md) explains the
+specialized text inputs and the same freedom to compose.
+
+Give a reusable scene the prepared performance, its outer Window and the Moment that changes its
+layout through the Timeline and shared temporal projections. Replacing a product or rewriting the
+Script then changes content and semantic anchors while preserving the behavior. The final frame
+positions come from the placed Takes.
+
+The repository's [video examples](https://github.com/hypit-ai/hypit/tree/main/examples) show different
+applications: a persistent ranking board, related podcast views, a shared interview encounter and
+coordinated explainer scenes. Trace why a behavior has its owner, what drives its time, and which
+inputs a changed brief would replace. Their notes explain those choices; the scene lists are each
+production's design. In the explainer, scenes retain fixed internal details while Script events,
+Caption and presenter framing remain independently authored.
+For that whole-work relationship, read [Presenter-led visual explainers](../playbooks/formats/presenter-led-explainer.md).
+The [explainer's craft notes](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/productions/explainer/CRAFT-NOTES.md)
+trace concrete revisions back to their design decisions and source owners.
+
+## Let meaning drive the behavior
+
+Prefer Script Selections, Moments and Segments for events that respond to the argument or performance.
+The Surface projects them through the accepted Timeline; the component consumes the resulting
+Windows or Instants. A different delivery can then move the event while preserving its purpose.
+Explicit time remains useful for an authored lead, a short entrance or another clock-based decision.
+In a pure MG piece, name the events that carry its meaning and direct their reading rhythm. A useful
+component accepts resolved Instants or Windows so the same reveal can follow a Script Moment or an
+authored time. Keep message content and its trigger together in Source; repeated children can each
+have their own trigger. Use semantic examples first for speech-led roles, showing how a new performance
+preserves the relationship. [Authored animation](rendering.md#compose-an-authored-animation) covers
+the film clock when there is no performance.
+
+A semantic outer Window alone does not establish the timing of its internal events. In a drag-and-drop
+scene, selecting a picture, dropping it into an editor and revealing the result may answer three
+different phrases. Give those actions their own semantic inputs. Placing them at fixed seconds or
+at 20%, 50% and 80% of the outer Window preserves neither their identities nor their relationship
+to unevenly changed speech.
+
+The Surface can accept an outer Selection and separate Moments for those events, projecting each
+through Timeline. The implementation derives movement between the resulting events and keeps its
+pointer path, button geometry, click rebound and decoration local. A movement that simply unfolds
+inside one authored event interval may use normalized progress there; it needs no marker for every
+animation key. Meaningful event location and the designed duration/shape of motion are different choices.
+
+Choose the temporal input from what the component does. A picture covering an explanation occupies
+its Selection. An answer revealed on a word can remain visible after that word ends. A ranking item
+may move during a reveal Window and stay in its settled row afterward. The board's outer lifetime,
+the trigger and the resulting state each have a clear meaning.
+
+Direct motion through that relationship. Arrival draws attention, settling establishes a new state,
+replacement makes a change readable, and departure releases space for the next idea. Choose how much
+time each needs relative to the meaning it carries. When an authored interval changes length, decide
+which part follows that interval and which part keeps its own readable duration. Document that choice.
+
+One authored event can also coordinate peer Tracks: a reveal, sound and flash can use the same
+Moment. A shared event is enough when each contribution already has a useful independent component.
+[Track authoring](track-authoring.md#keep-selection-projection-and-consumption-distinct) explains the
+projection and consumption boundary in detail.
+
+## Expose the choices the work needs
+
+A good parameter earns its place by enabling a useful directing choice or connecting a real dependency.
+Keep Script wording and semantic anchors connected to their existing owners, and supplied media
+explicitly wired. Illustrative text, decorative geometry and purpose-built animation may remain local
+to a one-off scene. A fixed design is complete when it serves the piece; adding controls is a separate
+decision. If a label later needs repeated variation, promote that choice to an input then.
+
+For the inputs that matter, sketch their Source use before implementing them. Related authored visual
+choices can form a Style or Recipe. A comparison may need labels, images and a reveal relationship;
+its internal layout can derive from those few inputs. One meaningful control can coordinate many
+details while preserving a designed whole. Semantic triggers remain valuable even for a scene used
+once: they connect its behavior to the actual performance without exposing every animation detail.
+
+When reuse is needed, support the actual variation: longer names, another product or a different
+number of rows. A new visual relationship may deserve another component.
+[Caption craft](../playbooks/craft/captions.md#caption-families-styles-and-parameters) illustrates
+family, Style and parameter choices for a commonly reused role.
+
+## Design the component in its frame
+
+Judge it beside the presenter, coverage, Caption and other graphics it will share the picture with.
+Give the eye a clear entry point, useful grouping and a settled state that remains readable. The
+component's local palette, density and motion should support the whole composition's hierarchy.
+
+Use the chosen Frame to express placement and derive the internal layout from it. Decide how real
+text and media occupy that space: what wraps, what crops, what scales, and what stays aligned. A useful
+fixed layout can suit the present work; expose placement or size when the composition needs to direct
+them externally. Let a genuinely unsupported configuration produce an actionable explanation of the
+content or space that needs changing.
+[Spatial layout](spatial.md) owns fitting and coordinate relationships; [Fonts and text](fonts-and-text.md)
+owns text resources and placement.
+
+Look at the important states in the actual composition: before the reveal, during the change, after
+it settles, and when the system leaves. A preview with representative content can answer hierarchy,
+readability, collisions and timing together. Make the correction at its owner: a semantic anchor,
+the chosen Recipe, the component's behavior or the visual idea itself. Reuse the production's media
+while refining those relationships.
+
+## Make the idea easy to use and revise
+
+Give the component vocabulary and an example that show its purpose, required inputs, public outputs
+and the meaning of its timing. For persistent state, explain what remains after activation. A preview
+should reveal the behavior that makes someone choose this component, with useful default content.
+
+For a production the user will explore in Studio, make its useful objects recognizable: a board's
+lifetime, a row's reveal, a Caption Cue's actual Style. Watching and understanding the work are useful
+on their own; a read-only scene with a clear identity can be complete. Expose controls for the real
+adjustments the user needs, such as Caption position and color, through the existing author inputs.
+An empty parameter panel alone is no reason to widen the component interface.
+[Companion authoring](studio-companions.md) owns those bindings.
+
+For an existing example, read the installed `@hypit/ranking` README and the part of its implementation
+that answers the current question. It connects semantic reveals, settled state, layout and editor
+entities. Carry the relevant relationship into the project component's own design.

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

@@ -0,0 +1,150 @@
+# Sharing a project package
+
+Read this when someone else needs a project component, Prompt Kit, Model, or Provider.
+
+Creating a component and distributing it answer different questions. Create the component when the
+work needs its visual role, semantic behavior or interaction. Distribution begins when its owner
+wants another project or person to use the same package. Its component model and ownership stay the
+same across that boundary.
+
+## Share the package that owns the component
+
+A component normally begins under the video project's `packages/` directory. Give it an owner-scoped name,
+such as `@studio/score-strip`. Sharing it means giving the other project that package's code, assets,
+and usage instructions. Neither author nor consumer needs a Hypit repository checkout.
+
+Keep the same name when distributing it. The Source import names its logical Module ABI:
+
+```xml
+<import as="score" from="@studio/score-strip@1"/>
+```
+
+Here `@1` names the logical Module ABI used by the Source. The package manager separately records
+the physical npm release, such as `1.2.0`. Updating that package release does not by itself change
+the logical import. Follow the package's actual published vocabulary for its author interface.
+
+## Publish for repeated distribution
+
+For stable reuse across projects, publish a versioned package under its owner's npm scope or private
+registry when that owner chooses distribution. For a public scoped package, the publication command is:
+
+```bash
+npm publish --access public
+```
+
+Consumers install the selected release with their usual package manager:
+
+```bash
+npm install --save-exact @studio/score-strip@1.2.0
+# or
+pnpm add --save-exact @studio/score-strip@1.2.0
+```
+
+The project lockfile records the installed dependency tree. Updates are explicit package-manager
+operations; Builds use the selected installed code. A missing package is an installation problem.
+Select the intended new release in the consumer project, inspect its changed vocabulary where
+relevant, check the actual Source/Run and review the changed behavior. New Builds load that selected
+implementation; restart an existing Studio session to load package-code changes. Reuse compatible
+media through Run Candidates while recomputing the component being revised. The package's own
+release notes describe any required author changes; no Build upgrades or migrates it automatically.
+
+## Send a tarball to another person
+
+For an explicit direct handoff or development check, build the package and run `npm pack` in its directory. A TypeScript package
+compiles to JavaScript; a JavaScript package may already have executable files. Its `prepack` script
+can perform the build. For example:
+
+```bash
+cd packages/score-strip
+npm pack
+```
+
+For `@studio/score-strip` version `1.2.0`, npm creates `studio-score-strip-1.2.0.tgz`. Send that file.
+This route needs no registry account or publication. The consumer can keep it under the video
+project's `vendor/` directory and install it from that project:
+
+```bash
+npm install ./vendor/studio-score-strip-1.2.0.tgz
+```
+
+Keep the tarball with the project while its dependency points to that file, along with `package.json`
+and the lockfile. Source imports select author contributions; Runtime Profile entries select Provider
+contributions. To send the next release, give it a new package version, create a new tarball, and
+install that file explicitly.
+
+## Make a public release discoverable
+
+People can find a public component through its npm page, source repository, or a community link.
+Ordinary package metadata makes those existing discovery surfaces useful. For example, add fields
+like these to the package that already owns the component:
+
+```json
+{
+  "description": "A speech-timed score strip for Hypit videos.",
+  "keywords": ["hypit", "hypit-author-package", "scoreboard"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/studio/score-strip.git"
+  },
+  "license": "MIT"
+}
+```
+
+The description and keywords help npm search; they do not define the component ABI. The README should
+show the visual role, a copyable Source import and element example, the package's public outputs, and
+the selected Hypit release used to check it. Include the Surface poster and, when motion or state is
+central to the idea, a short representative clip or animation. The source repository, publisher,
+license and selected release give a recipient the facts needed to choose whether to install it.
+
+After installation, inspect the package's own declarations:
+
+```bash
+hypit vocabulary @studio/score-strip
+```
+
+That output explains the installed release's Surfaces and vocabulary. npm or the selected private
+registry remains the authority for package bytes and versions; the project lockfile records the
+consumer's exact choice.
+
+## Adapt the package under its owner's identity
+
+Ordinary changes to words, media, timing, palette or exposed parameters remain in the consuming
+project's Source and Recipes. When someone changes the reusable mechanics or public behavior, the
+fork can take that owner's package scope and Module identity, subject to the original license. The
+new package is then installed, versioned and imported through the same mechanism as any other shared
+component.
+
+## Include what the recipient needs
+
+The package's `files` and `exports` should include its built activation, runtime code, preview assets,
+and any Sources or templates exposed by its vocabulary. `hypit.activation` points to the shipped
+JavaScript entry. Declare third-party runtime dependencies in `dependencies`. Include a README with
+an actual Source example, the public outputs, any companion or asset requirements, and the Hypit
+release used to check it. Inspect the tarball contents with `npm pack --dry-run`.
+
+An executable Author Package develops against `@hypit/hypit/author-kit` and the relevant `@hypit/hypit/*` domain
+subpaths, with `@hypit/hypit` as a development dependency. Its release contains its own code and assets;
+the active Hypit Distribution supplies the framework APIs when loading it. Check the package from a
+separate consumer project so local source links do not conceal omitted files or dependencies.
+
+Package code runs as trusted JavaScript in the host process. The recipient chooses which package and
+release to install.
+
+## Data packages remain data
+
+A Prompt Kit can export an `.svs` Source through ordinary package `exports` without activation code:
+
+```xml
+<import as="ugc" source="@studio/image-kits/phone-ugc-v1"/>
+```
+
+That reads the selected package data. The same packing, installation, versioning, and file-completeness
+rules apply. [Project handoff](../creation/project-files.md#hand-over-an-editable-production) explains
+sharing the Sources, Runs, assets and Results needed to continue a video on another machine.
+
+## Official Distribution ownership is a separate decision
+
+A package maintained in the official Hypit Distribution becomes part of Hypit's product and release
+surface. A proposal for that ownership begins with an issue that explains the shared production need
+and maintenance boundary. Community reuse remains under the package owner's own releases, independent
+of that product decision.

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

@@ -0,0 +1,152 @@
+# Drawing a component
+
+Read this while implementing a project component's rendered output. [Track authoring](track-authoring.md)
+owns its author interface, temporal inputs and state behavior. [Spatial layout](spatial.md) explains
+the incoming geometry; [Studio](studio.md) explains an optional Companion.
+
+## From program to visible Track
+
+A component's drawing output describes what appears, where it appears and how it changes over its
+visible lifetime. For a reveal card, those decisions become a box and text, a destination Frame,
+an entrance animation and the interval for which the answer remains visible.
+
+A component can first compute a domain program, such as a list of answers and their reveal times.
+Its drawing Producer receives that program, Timeline, Frames, Style and explicit assets, then
+returns a VisualTrack. A simple component can produce the Track directly when no separate program
+would help its behavior or editing.
+
+The public representation has these parts:
+
+| Part | What it means |
+| --- | --- |
+| Track | Named picture contribution belonging to one Timeline |
+| Present | An independently timed and stacked appearance |
+| `span` | Program frames from `startFrame` through the frame before `endFrameExclusive` |
+| `stacking` | Absolute paint order among Presents; higher order appears above lower order |
+| Elements | One rooted tree of boxes, text, media, masks, compositable surfaces or renderer programs |
+| Animation | Keyframes relative to the containing Present's start |
+
+Use several Presents when items have separate lifetimes or stacking positions. A persistent board
+can keep its settled rows visible while later rows enter. Its domain program decides those spans
+and states; the drawing output makes them explicit.
+
+Track grouping is an authoring boundary; each Present has its own paint order among the film's
+appearances. Its element tree supplies local layout and compositing scope. Use that tree or a browser
+program for content that moves, clips or changes layout together. The final DOM follows these owned
+visual relationships rather than the nesting of tags in Source.
+
+## A working drawing function
+
+[visuals.ts](examples/visuals.ts) contains `renderCard`, a complete pure drawing function using
+`sealVisualTrack` from `@hypit/hypit/composition`. It receives a projected span and a resolved Frame,
+draws a colored box with exact-font text, and optionally fades in relative to the Present's start.
+Its colors, size, padding, layer and entrance duration are supplied by the caller. These drawing-function
+arguments need not all become Surface parameters: the owning component can supply its fixed design
+and expose only the inputs the production needs.
+
+The root uses Canvas coordinates. The text child uses the root's local coordinates, so padding is
+added once. When a component computes child geometry in Canvas space, subtract the parent's origin
+before writing child `left` and `top`.
+Element `order` values are distinct within the Present; `stacking.order` separately places that
+whole Present among the composition's other appearances.
+
+The function is the drawing part of a package. Connect it to a Producer with matching typed inputs,
+then publish the Track through the Fragment and Surface as described in
+[Track authoring](track-authoring.md#connect-the-implementation-at-its-real-boundaries). Surface outputs
+map the Fragment's export name to a public Source name such as `answers.track`.
+
+Use `programSpaceFrameCount` from `@hypit/hypit/program-space` for the full program's frame count and
+`assertVisualTrackIdentity(track, space)` to check a produced Track against that space. Direct seeking
+and range rendering evaluate the same declared keyframes at the requested frame.
+
+## Elements, fonts and other assets
+
+`box` provides a container or painted shape. `text`, `text-flow` and `path-text` carry text and exact
+font resources. `image` and `video` reference their media artifacts. A `mask` names owned mask and
+content children in the same Present. The installed vocabulary queries expose their value shapes:
+
+```bash
+hypit vocabulary --visual visual-track
+hypit vocabulary --visual text
+```
+
+Visual styles and Motion use the installed CSS-shaped property vocabulary; query the relevant visual
+shapes above for their supported values. Motion uses frame-indexed keyframes. Media sampling separately
+describes which source frame to show at each part of a Present; it is needed for timed video playback,
+trims, loops and holds. Existing Media Track is useful when that is the whole role.
+
+Carry asset and font references through declared inputs. Source assets can be resolved at the
+Surface's asset boundary; generated media remains a graph reference until its Producer runs.
+The drawing function receives those values. For a visual preparation that reads bytes or invokes an
+external tool, use its preparation capability and pass the resulting material into drawing.
+
+## Compose externally prepared pixels
+
+A `surface` element accepts a CompositableSurfaceRef: prepared pixels with explicit extent, color,
+alpha and, for animation, frame information. This is useful when the component uses a raster or
+animated asset produced by another tool. Its preparation determines the pixels; the Track determines
+placement, sampling and lifetime.
+
+For an effect that transforms an image, pass that image as an explicit input to the effect's
+preparation. For a local mask, own the mask and content in the same element tree. These relationships
+make the required materials available both in Studio and in a render of any selected interval.
+
+## Compose video and graphics in one browser program
+
+When a scene's video viewport and graphics share motion or layout, one component can draw them
+together. `browserProgram` from `@hypit/hypit/hyperframes` creates a `program` element's payload. Its HTML
+owns the local structure; CSS supplies layout, stacking, masks, filters and blending; optional
+`setup(root, data)` code returns `render(localFrame)`. This function sets the complete state at that
+frame synchronously. A range render may start in the middle, so compute state from the frame and authored inputs.
+
+Prepare stable structure in `setup`: locate elements, construct geometry and retain reusable drawing
+objects there. Paint static procedural textures once their resources are ready.
+Let `render(localFrame)` update the state that changes with time. This supports both
+fast repeated capture and direct seeking. A program is sampled within its Present's lifetime;
+outside it, the renderer may retain the boundary pose. Re-entry and repeated active seeks must
+produce the complete requested state, including when an image became ready since the last call.
+
+Repeated browser-program instances share one document's HTML/SVG ID space even though their CSS
+is scoped. For SVG masks, gradients or filters, derive each required ID from `root.id` in `setup`
+and update its references together. The installed `@hypit/hyperframes` README owns the browser-program
+API and resource-loading behavior.
+
+For a depth or material effect, choose the representation that carries its visible behavior:
+CSS can tilt a panel, while a deforming textured surface may warrant mesh geometry and Canvas or
+WebGL drawing. Keep that implementation inside the project component; give Source the useful
+material, amplitude or timing choices rather than the renderer's internal construction.
+
+For shared opacity or a filter, put the affected content under the element that owns the treatment.
+A translucent panel can use backdrop filtering; its painted position and browser compositing scope
+determine which background it affects. A transition can own both participating pictures and their
+handoff. Choose the scope from the visible relationship, keeping independently useful contributions
+as peer Presents. These are ordinary composition choices within the same rendering path.
+
+Use ordinary typed children for prepared video, images and exact-font text. A `{{child-id}}` slot in
+the HTML places each direct child exactly once. These children retain their declared resources,
+video sampling and font handling while participating in the program's HTML layout. Extra artifacts
+used by the program belong in its `artifacts` list; `hyperframesResourceUri` supplies their resource
+URLs. The rendering environment materializes those references.
+
+For a placed performance, `projectTimelineMedia(timeline, window.span)` from
+`@hypit/hypit/timeline` returns each intersecting Take's prepared media, program span and source
+span. Subtract the containing Present's start to obtain Present-local video sampling intervals
+(when that Present uses the outer Window as its span, subtract the Window start). Preserve
+the returned source offset: moving or reframing a video changes its presentation while playback
+continues from the same place. A separate Sound presentation can continue the existing audio in Film.
+
+Project each independently meaningful event before rendering. Convert its program frame to the
+containing Present's local frame once, then animate relative to that event. Keep source sampling
+based on the returned source span; neither the event's local offset nor the viewport's movement
+replaces it. [Component design](component-design.md#let-meaning-drive-the-behavior) distinguishes these
+inputs from internal motion details.
+
+A reusable scene might expose `during={story.selection.explanation}` for its lifetime and
+`reveal={story.moment.demonstrate}` for its layout change. The Surface projects these independently;
+the Producer receives a Window and an Instant. The installed Distribution's
+`examples/semantic-composition/packages/responsive-explainer` shows this complete package: video
+moves from full screen to a side viewport while a diagram enters, with Caption available as a peer.
+
+The program format belongs to the renderer package. `hypit.browser-program@1` runs in the
+HyperFrames browser; another renderer implements the formats it supports. Core still schedules
+ordinary Needs and has no knowledge of scenes, video windows or browser layout.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/examples/detail.svrun

@@ -0,0 +1,8 @@
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+  <author source="./production.svml"/>
+  <target output="detail.video"/>
+  <!-- Replace the Build id with the Result containing this production's Take. -->
+  <build-record id="kept-take" build="bld_..." output="opening-semantic.take"/>
+  <satisfy output="opening-semantic.take" candidate="kept-take"/>
+</svrun>

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/examples/direction.svs

@@ -0,0 +1,14 @@
+<?svml using="@hypit/text/svs@1"?>
+<sheet version="1" id="performance">
+  text-template.performance { separator: paragraph; }
+  text-template.performance.block.direction {
+    kind: slot;
+    order: 10;
+    slot: direction;
+  }
+  text-template.performance.block.dialogue {
+    kind: slot;
+    order: 20;
+    slot: dialogue;
+  }
+</sheet>

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/examples/look.svs

@@ -0,0 +1,6 @@
+<?svml using="@hypit/svs@1"?>
+<sheet version="1">
+  media.performance { stack-order: 0; fit: cover; }
+  text.title { size: 54; weight: 700; stack-order: 20; }
+  film.main { background: #18212A; }
+</sheet>

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/examples/material.svrun

@@ -0,0 +1,5 @@
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+  <author source="./production.svml"/>
+  <target output="opening-semantic.take"/>
+</svrun>

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/examples/production.svml

@@ -0,0 +1,73 @@
+<?svml using="@hypit/markup@1"?>
+<svml>
+  <import as="sound" from="@hypit/sound@1"/>
+  <import as="performance" from="@hypit/performance@1"/>
+  <import from="@hypit/script@1"/>
+  <import as="text" from="@hypit/text@1"/>
+  <import as="seedance" from="@hypit/seedance@1"/>
+  <import as="pipeline" from="@hypit/media-pipeline@1"/>
+  <import as="whisperx" from="@hypit/whisperx@1"/>
+  <import as="time" from="@hypit/timeline-author@1"/>
+  <import as="space" from="@hypit/spatial@1"/>
+  <import as="program" from="@hypit/program-space@1"/>
+  <import as="fonts" from="@hypit/fonts-open@1"/>
+  <import as="typo" from="@hypit/typography-track@1"/>
+  <import as="film" from="@hypit/film@1"/>
+  <import as="render" from="@hypit/render-hyperframes@1"/>
+  <import as="look" source="./look.svs"/>
+  <import as="kit" source="./direction.svs"/>
+
+  <script id="story">
+    <opening><HOST>Here is @{proof}the useful part.@{/proof}</opening>
+  </script>
+  <space:Canvas id="canvas" width="720" height="1280"/>
+  <program:Clock id="clock" frame-rate="30"/>
+  <space:Frame id="full" within={canvas}
+    left="0%" top="0%" right="100%" bottom="100%"/>
+  <space:Frame id="title-frame" within={canvas}
+    left="8%" top="12%" right="92%" bottom="30%"/>
+
+  <text:Value id="direction">
+    A close, naturally lit phone-video view of a presenter in a workshop.
+    HOST is the presenter, speaking to the camera with relaxed confidence.
+  </text:Value>
+  <text:Render id="prompt" template={kit.performance}>
+    <text:Set name="direction" text={direction}/>
+    <text:Set name="dialogue" text={story.segment.opening.dialogue}/>
+  </text:Render>
+  <seedance:TextVideo id="performance" model="mini" prompt={prompt}
+    duration="5" aspect-ratio="9:16" generate-audio="true"/>
+  <pipeline:Normalize id="performance-media" source={performance.video} clock={clock}
+    video="primary-moving" audio="default" span-authority="video"/>
+  <whisperx:SemanticTake id="opening-semantic" narrative={story}
+    segment={story.segment.opening} media={performance-media.media} language="en"/>
+  <time:Timeline id="speech" clock={clock}>
+    <time:Take source={opening-semantic.take}/>
+  </time:Timeline>
+
+  <sound:Style id="speech-sound-style"/>
+  <sound:Track id="speech-sound" timeline={speech.timeline}>
+    <sound:Use style={speech-sound-style}/>
+  </sound:Track>
+  <performance:Style id="speech-picture-style" frame={full} appearance={look.media.performance}/>
+  <performance:Track id="speech-picture" timeline={speech.timeline} canvas={canvas}>
+    <performance:Use style={speech-picture-style} during="program"/>
+  </performance:Track>
+
+  <fonts:Stack id="title-font" family="inter" weight="700" style="normal" emoji="color"/>
+  <typo:Style id="title-style" recipe={look.text.title} font={title-font}>
+    <typo:Fill color="#F1E7D8"/>
+  </typo:Style>
+  <typo:Track id="titles" timeline={speech.timeline}>
+    <typo:Area id="proof-label" placement={title-frame} style={title-style}
+      during={story.selection.proof}>The useful part</typo:Area>
+  </typo:Track>
+  <film:Film id="main" canvas={canvas} timeline={speech.timeline} appearance={look.film.main}>
+    <film:Track source={speech-picture.visual}/>
+    <film:Track source={speech-sound.audio}/>
+    <film:Track source={titles.track}/>
+  </film:Film>
+  <render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
+  <render:Video id="detail" composition={main.composition} timeline={speech.timeline}
+    start-frame="30" end-frame-exclusive="90"/>
+</svml>

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/examples/production.svrun

@@ -0,0 +1,5 @@
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+  <author source="./production.svml"/>
+  <target output="final.video"/>
+</svrun>