Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs: explain semantic component design and spatial composition
kashorin8126aca3de0a
diff --git a/packages/media-track/README.md b/packages/media-track/README.mdindex c8f19573..36014b0d 100644--- a/packages/media-track/README.md+++ b/packages/media-track/README.md@@ -14,6 +14,61 @@ Moving media enters after [normalization](../media-pipeline/README.md), with theframe clock already selected. Still images use their actual intrinsic Extent. Placement, fitting,sampling and motion remain separate authored choices.+## Place the frame, then fit its contents++An Item or Sequence owns an outer destination `frame`. Each sampled source has a fitted content+rectangle calculated from its intrinsic extent and its fit Recipe. Border and padding reduce the+fitting area inside the outer Frame. Source dimensions stay factual; the calculated rectangle can+be smaller or larger than the fitting area.++[Spatial](../spatial/README.md#destination-and-fitted-content) owns the seven fit modes, the two+alignment points, pixel offsets and bounded/free placement. `frame-x` / `frame-y` are alignment+fractions in that fitting area. Move the whole visual by changing the `frame` reference; choose+which part of the picture is visible through the fit and content alignment.++The appearance Recipe separates the outer presentation from the sampled picture:++| Properties | What they affect |+| --- | --- |+| `stack-order` | Absolute visual stacking of the Item or Sequence; required |+| `clip` | Outer clipping: `frame` (default), `rounded`, or `none` |+| `radius` | Pixel radius when `clip: rounded`; half a square Frame's side gives a circle |+| `padding` | Fitting inset, as quoted pixel values: `"12"`, `"8 12"`, or `"8 12 16 12"` |+| `border-width`, `border-style`, `border-color` | Border inside the outer Frame; a positive width requires a color |+| `shadows` | Frame shadows, as quoted `x y blur spread color` entries separated by semicolons |+| `frame-paint` | Solid or gradient backing behind the content |+| `fit`, alignment and fit offsets | The scaled source's rectangle |+| `opacity`, `blur`, `brightness`, `contrast`, `saturation` | The sampled picture, independently of frame decoration |++For example, this is a rounded card with an inset picture and a painted backing:++```svs+media.card {+ stack-order: 40;+ fit: contain;+ clip: rounded;+ radius: 24;+ padding: "12";+ border-width: 2;+ border-color: #B9A88B;+ frame-paint: #25332D;+ shadows: "0 8 20 0 #00000055";+}+```++The outer size includes the border; border and padding both reduce the fitting area. The clip+follows the outer Frame, so a smaller contained picture may retain square corners inside a rounded+card. A rounded picture with a flush edge uses a Frame matching its displayed aspect. `clip: none`+allows source overflow; fitting alone supplies no mask. An authored spatial Path can be bound to+an Item or Sequence with `clip={path}` in place of the Recipe's clip choice. Path coordinates are in+Canvas pixels.++A `motion` Recipe transforms the framed unit, including its backing and decoration. `Sampling`+transforms the fitted source inside it, around the source rectangle's center. It accepts `zoom`,+pixel `x` / `y`, degree `rotate`, and `easing`, at `start`, `end`, or intermediate percentages. Supply+keys spanning start to end. Sampling runs after fitting and is not constrained by `fit-constraint`;+a deliberate pan or rotation may reveal the backing or lower layers.+## Author Items and replacement SequencesThese excerpts assume the imports, named assets, normalized media, Frames, Extents, Script,@@ -52,6 +107,11 @@ an explicit `cut` when no blended transition is intended. `from` names the outgosuccessor is the incoming Member. A Handoff's duration and boundary ratio place the visual transitionaround that logical boundary without moving the semantic event.+For layered content, `Paint` and `Layer` children draw in Source order inside the shared Frame. Give+each Layer its own fit/sample Recipe. A Member appearance override selects its source fit, sampling+and frame paint; the Sequence still owns the outer Frame, clip, padding, border, shadow, motion and+stack order. Separate Items supply independently placed Frames.+An Item or Member can select audio using `source-audio`: `content` for its direct source, or a childLayer id for layered content. This is opt-in. `Sound` can instead attach normalized audio to Item`at="enter"` / `at="exit"`, or to a Sequence `handoff="one-two"`. The Track publishes `.visual` anddiff --git a/packages/media-track/src/manifest.ts b/packages/media-track/src/manifest.tsindex 48a8b8da..f40cca88 100644--- a/packages/media-track/src/manifest.ts+++ b/packages/media-track/src/manifest.ts@@ -272,11 +272,11 @@ const sequenceInputs = [const appearanceRecipeProperties = [{ name: "fit", required: false, fallback: "contain",values: ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"],- summary: "Decides how the source is scaled into the Frame." },+ summary: "Scales the source into the fitting area left inside the Frame after border and padding." },{ name: "frame-x", required: false, fallback: "0.5",- summary: "Places the anchor point across the Frame, from 0 at its left edge to 1 at its right." },+ summary: "Places the destination alignment point across the fitting area, from 0 at its left edge to 1 at its right." },{ name: "frame-y", required: false, fallback: "0.5",- summary: "Places the anchor point down the Frame, from 0 at its top edge to 1 at its bottom." },+ summary: "Places the destination alignment point down the fitting area, from 0 at its top edge to 1 at its bottom." },{ name: "content-x", required: false, fallback: "0.5",summary: "Places the anchor point across the scaled source, from 0 at its left edge to 1 at its right." },{ name: "content-y", required: false, fallback: "0.5",@@ -286,7 +286,7 @@ const appearanceRecipeProperties = [{ name: "fit-offset-y", required: false, fallback: "0",summary: "Shifts the fitted source vertically in pixels once the two anchor points meet." },{ name: "fit-constraint", required: false, values: ["bounded", "free"], fallback: "bounded",- summary: "Decides whether the fitted source is held inside the Frame or may overflow it." },+ summary: "With bounded, large content keeps the fitting area covered on each axis and small content stays inside it; free preserves the authored alignment and offsets. Clipping is controlled separately." },{ name: "opacity", required: false, fallback: "1",summary: "Sets how opaque the sampled picture is drawn." },{ name: "blur", required: false, fallback: "0",@@ -305,7 +305,7 @@ const appearanceRecipeProperties = [{ name: "trim-end", required: false,summary: "Ends timed material before this whole frame of its own timeline, and is written with `trim-start`." },{ name: "stack-order", required: true,- summary: "Orders this unit against every other Item and Sequence on the Track, higher drawing in front." },+ summary: "Sets this unit's absolute stacking order in the Film, higher drawing in front." },{ name: "clip", required: false, values: ["none", "frame", "rounded"], fallback: "frame",summary: "Decides how the picture is clipped to the Frame." },{ name: "radius", required: false, fallback: "0",@@ -365,7 +365,7 @@ export const mediaTrackMarkupSurfaces = [{compositionTypes.visualTrack, compositionTypes.audioTrack],vocabulary: {summary: "One Media Track: independently timed Items and replacement Sequences placed on a shared SemanticTrack and Canvas, lowered to one peer VisualTrack and, when audio is authored, one peer AudioTrack.",- appearance: "Rectangular pictures, each filling its own Frame exactly where that Frame sits on the Canvas, and nothing besides: the Track draws no chrome, caption or backdrop of its own, and lays nothing out relative to anything else. Inside one Frame the layers stack back to front in the order they are written — flat or gradient Paint fills, then a still image, a video or a Surface scaled in by the fit — clipped to the Frame as a square, a rounded rectangle or an authored Path, optionally ringed by a border and sitting on drop shadows. An Item appears for its own window and leaves at the end of it, entering and exiting on one operator such as a fade, a slide from an edge, a scale, a pop or a wipe, holding a small continuous float, pulse or drift while it is up, and panning, zooming or rotating its picture inside the Frame across the window. A Sequence instead keeps one Frame occupied without a break and replaces the picture inside it at each activation point, the outgoing picture giving way on a cut, a crossfade, a push, a wipe, a cover or a page-turn; where two units overlap, the higher stack order draws in front.",+ appearance: "Pictures and layered compositions occupy authored Frames on the Canvas. Each source is scaled and aligned inside its Frame's border and padding; a contain fit can leave space, while cover can crop. Paint and sampled Layers draw in Source order under a shared rectangular, rounded or Path clip, with optional border and shadows. Lifecycle motion moves the framed unit; Sampling pans, zooms or rotates the picture inside it. Each Item has an independent window. A Sequence shares one outer Frame while Members replace its contents through cut, crossfade, push, wipe, cover or page-turn Handoffs. Source playback determines whether moving content covers the whole assigned span. Absolute stack order decides which overlapping unit draws in front.",preview: previewImage("Track.png"),attributes: [{ name: "id", kind: "identifier", required: true,diff --git a/packages/seedance-kits/README.md b/packages/seedance-kits/README.mdindex 5b7612da..b0c0a234 100644--- a/packages/seedance-kits/README.md+++ b/packages/seedance-kits/README.md@@ -49,15 +49,25 @@ Speaker uses the same graph vocabulary. The Kit assumes `@image1` is the visible</seedance:ReferenceVideo>```-The seven templates are:--- `speaker-v1`: one visible speaker, one character-and-scene image and one voice reference;-- `broll-v1`: silent visual micro-story;-- `podcast-v1`: two fixed podcast views with two voices;-- `call-v1`: two live video-call reverse views;-- `street-interview-v1`: interviewer, guest and shared street views, two voices and microphone positioning;-- `motion-reference-v1`: preserve the subject and transfer body motion only;-- `camera-reference-v1`: preserve the subject and transfer camera language only.+## Choose a template++Each import below has the prefix `@hypit/seedance-kits/`. The selected Source exports the listed+template id. Its linked `.svs` file owns the exact fixed wording, default choices and allowed values.++| Import suffix / template | Intended relationship and media references | Text slots |+| --- | --- | --- |+| `speaker` / [`speaker-v1`](kits/speaker-v1.svs) | One visible speaker: `@image1` is the character-and-scene view; `@audio1` is that speaker's voice. | Required `dialogue`; optional `action` |+| `broll` / [`broll-v1`](kits/broll-v1.svs) | A silent visual micro-story; images appear in authored reference order, with their roles explained in the story. | Required `story` |+| `podcast` / [`podcast-v1`](kits/podcast-v1.svs) | Two fixed views: images 1/2 show A/B, and audio 1/2 supplies their corresponding voices. | Required `dialogue`; optional `action` |+| `call` / [`call-v1`](kits/call-v1.svs) | Image 1 shows A in the main tile and B in the inset; image 2 reverses them. Both are live views, with audio 1/2 for A/B. | Required `dialogue`; optional `action` |+| `street-interview` / [`street-interview-v1`](kits/street-interview-v1.svs) | Images 1/2/3 are interviewer A, guest B and shared street setups; audio 1/2 is A/B. A holds the microphone. | Required `dialogue`; optional `action` |+| `motion-reference` / [`motion-reference-v1`](kits/motion-reference-v1.svs) | Image 1 supplies the subject; video 1 supplies body motion, gestures and pose dynamics. | Optional `direction` |+| `camera-reference` / [`camera-reference-v1`](kits/camera-reference-v1.svs) | Image 1 supplies the subject; video 1 supplies camera framing, lens, movement and photographic rhythm. | Optional `direction` |++For example, `source="@hypit/seedance-kits/call"` imported as `kit` exposes `kit.call-v1`.+Text slots use `text:Set`; scalar Recipe choices use the selected template's named axes. Reading the+template reveals what each choice actually asks the generator to do. Rendering the Text Output as a+Run Target lets an author inspect the assembled prompt without generating media.Speaker, B-roll, Podcast, Call and Street Interview expose prompt choices through their TextTemplates. The examples above use author-chosen literal durations. Measure adopted speech withdiff --git a/packages/spatial/README.md b/packages/spatial/README.mdindex bb6fefb0..3786f8bd 100644--- a/packages/spatial/README.md+++ b/packages/spatial/README.md@@ -8,6 +8,42 @@ renderer, Provider or Core behavior.The package exposes self-described `Canvas`, `Point`, `Path`, `Extent`, `RegionTimeline`, `Frame`,`AnchoredFrame` and `AspectFrame` author Surfaces plus pure geometry functions and fixed-port Producers.+## Destination and fitted content++`SpatialFrame` is a destination rectangle in Canvas pixels. `IntrinsicExtent` supplies source+dimensions. `fitContent(frame, extent, fit)` returns a `FittedContent.contentFrame`: the scaled+source's rectangle in the same coordinates. The caller supplies the fitting area; Media Track+derives that area by subtracting its border and padding from its outer Frame.++`ContentFit.sizing` selects the size before alignment:++| Sizing | Result |+| --- | --- |+| `contain` | Preserve aspect and fit both dimensions inside the destination |+| `cover` | Preserve aspect and cover both destination dimensions |+| `fit-width` / `fit-height` | Preserve aspect and match the named dimension |+| `native` | Keep the source's pixel dimensions |+| `scale-down` | Use `contain` while limiting scale to at most 1 |+| `stretch` | Use the destination width and height independently |++`framePoint` and `contentPoint` are separate normalized points in `[0,1]`. The scaled source point+is placed at the destination point, then `offsetPx` is added. Before any constraint, the horizontal+position is `frame.xPx + frame.widthPx * framePoint.x - contentWidth * contentPoint.x + offsetPx.x`;+the vertical position follows the same relationship.++`constraint: bounded` clamps each coordinate between `frameStart` and+`frameStart + frameSize - contentSize`, whichever is lower or higher. Large content keeps the+destination covered on that axis, and small content stays inside it. `free` leaves the calculated+position unchanged. Fitting calculates rectangles; the consuming component owns clipping.++`decodeContentFitProperties` exposes these through Recipe keys: `fit`, `frame-x`, `frame-y`,+`content-x`, `content-y`, `fit-offset-x`, `fit-offset-y`, and `fit-constraint`. Defaults are `contain`,+center points (`0.5`), zero pixel offsets and `bounded`. These alignment fractions place the source+inside the supplied destination. Canvas placement remains the job of Frame / AnchoredFrame /+AspectFrame. Media Track and Speech Track use this same decoder.++## Measured regions+`RegionTimeline` accepts already measured data rather than running a detector. Face detection andtracking can observe the footage produced by an earlier Build: keep useful boxes as ordinary numbers,then reuse that media while rendering Caption with the finished timeline. Measurement precedes thediff --git a/packages/speech-track/README.md b/packages/speech-track/README.mdindex e9075c28..d31cf217 100644--- a/packages/speech-track/README.md+++ b/packages/speech-track/README.md@@ -67,6 +67,23 @@ crop anchors, opacity and filters, rounded or rectangular clipping, padding, borframe paint. Lifecycle motion can move that visual presentation as it enters, remains or exits. Noneof these choices changes the Take's semantic timing or audio.+This is the same destination/content geometry as a Media Item: the outer `frame` places and shapes+the presentation; border and padding define its fitting area; the source's intrinsic extent, fit+and alignment determine the inner picture rectangle. The shared spatial Recipe keys and defaults+are described in [Spatial](../spatial/README.md#destination-and-fitted-content), and frame decoration+in [Media Track](../media-track/README.md#place-the-frame-then-fit-its-contents). Rounded clipping is+applied to the outer Frame, including when a contain fit leaves space around the picture.++A Take override replaces the corresponding Track setting. In particular, `appearance` selects a+complete Recipe rather than merging individual properties from `visual-appearance`. Speech Track+authors stacking through `visual-z` / `z`; its appearance Recipe carries the shared picture and+frame properties without Media Track's `stack-order`, playback or trim fields.++Speech visuals occupy their prepared Take's Segment span. Their lifecycle motion repeats within+each Take's span, and Sampling moves only the picture under the frame's clip. The current Speech+Surface supports rectangular, rounded and unclipped frame presentation. An authored Path clip and+Canvas-edge `enter-origin` / `exit-origin` are Media Track interfaces.+Sampling children move the Take's picture inside its Frame over normalized Segment progress, usingthe same fields as a direct Media Item:diff --git a/packages/speech-track/src/manifest.ts b/packages/speech-track/src/manifest.tsindex 77e04c77..4cc06c07 100644--- a/packages/speech-track/src/manifest.ts+++ b/packages/speech-track/src/manifest.ts@@ -73,9 +73,9 @@ const visualRecipeProperties = [values: ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"],summary: "Decides how the Take's picture is scaled before it is placed: `contain` and `cover` keep its aspect ratio inside or across the Frame, `fit-width` and `fit-height` match one Frame edge, `native` keeps its own pixels, `scale-down` shrinks it only when it overflows, and `stretch` takes the Frame's exact size." },{ name: "frame-x", required: false, fallback: "0.5",- summary: "Places the anchor point across the Frame's width, as a fraction from 0 at its left edge to 1 at its right." },+ summary: "Places the destination alignment point across the fitting area left after border and padding, from 0 at its left edge to 1 at its right." },{ name: "frame-y", required: false, fallback: "0.5",- summary: "Places the anchor point down the Frame's height, as a fraction from 0 at its top edge to 1 at its bottom." },+ summary: "Places the destination alignment point down the fitting area left after border and padding, from 0 at its top edge to 1 at its bottom." },{ name: "content-x", required: false, fallback: "0.5",summary: "Chooses the point across the scaled picture's width that meets the Frame's anchor, as a fraction from 0 at its left edge to 1 at its right." },{ name: "content-y", required: false, fallback: "0.5",@@ -85,7 +85,7 @@ const visualRecipeProperties = [{ name: "fit-offset-y", required: false, fallback: "0",summary: "Shifts the placed picture vertically in pixels once the two anchor points meet." },{ name: "fit-constraint", required: false, fallback: "bounded", values: ["bounded", "free"],- summary: "Decides whether the placed picture is pulled back until it covers as much of the Frame as its size allows, or left exactly where the anchors and offsets put it." },+ summary: "With bounded, large content keeps the fitting area covered on each axis and small content stays inside it; free preserves the authored alignment and offsets. Clipping is controlled separately." },{ name: "opacity", required: false, fallback: "1",summary: "Sets how opaque the Take's picture is drawn." },{ name: "blur", required: false, fallback: "0",@@ -101,7 +101,7 @@ const visualRecipeProperties = [{ name: "radius", required: false, fallback: "0",summary: "Sets the rounded clip radius in pixels; half the side of a square Frame makes a circle." },{ name: "padding", required: false, fallback: "0",- summary: "Insets the Take's picture from its Frame edges using one, two or four pixel values." },+ summary: "Insets the picture's fitting area inside the border, using quoted pixel values: one for all sides, two for vertical/horizontal, or four for top/right/bottom/left." },{ name: "border-width", required: false, fallback: "0",summary: "Draws a border of this pixel width around the Frame." },{ name: "border-style", required: false, values: ["solid", "dashed", "dotted"], fallback: "solid",@@ -150,7 +150,7 @@ export const speechTrackMarkupSurfaces = [{compositionTypes.visualTrack, compositionTypes.audioTrack],vocabulary: {summary: "Folds ordered SemanticTakes into one SemanticTrack, then publishes its aligned VisualTrack and AudioTrack projections.",- appearance: "The speaking picture itself, and the layer every other Track is stacked over. Each Take's own footage fills the Frame the Track names, fitted by its Recipe, and the Takes run one after another in the order they are written, so the picture cuts from one to the next at each Take boundary with nothing between them. A Take may name its own Frame, so the picture can move or resize at a boundary; otherwise the framing holds. Nothing is drawn on top: titles, captions and cutaways are separate Tracks lying above this one.",+ appearance: "The performance picture, presented full-frame, as an inset, or as a transparent foreground cutout. Each Take is fitted into its selected Frame with optional rounded clipping, border, padding, backing and shadow. Visual-z or the Take's z sets its position among other visual Tracks. Takes run in Source order; a Take can choose its own Frame and appearance at a boundary. Lifecycle motion moves the framed presentation, while Sampling moves its picture inside the Frame. These visual choices preserve the performance's semantic time and separate audio output.",preview: previewImage("Track.png"),attributes: [{ name: "id", kind: "identifier", required: true,diff --git a/skills/hypit/references/playbooks/craft/graphic-compositions.md b/skills/hypit/references/playbooks/craft/graphic-compositions.mdindex 4b0c1daf..8dcc2236 100644--- a/skills/hypit/references/playbooks/craft/graphic-compositions.md+++ b/skills/hypit/references/playbooks/craft/graphic-compositions.md@@ -55,6 +55,8 @@ one enormous component.Group elements when their shared layout, state or semantic behavior would otherwise have to bereimplemented across unrelated tags. Keep independently useful layers separate when ordinarycomposition already expresses the relationship. A new shared visual role can be a project component.+[Component design](../../production/component-design.md) connects that visual idea to semantic behavior,+useful author controls and its place in the actual composition.The package owns reusable mechanics, default chrome and any bundled assets that belong to itsidentity. Source and Recipe supply this work's text, media, palette, placement and events. A surfacediff --git a/skills/hypit/references/production/authoring.md b/skills/hypit/references/production/authoring.mdindex 38d205ee..841c34df 100644--- a/skills/hypit/references/production/authoring.md+++ b/skills/hypit/references/production/authoring.md@@ -8,6 +8,7 @@ Caption Cue handoffs and semantic anchors. [Source syntax](source-syntax.md) expreferences and the language around that Script.[Composing Tracks](tracks.md) connects the visual and audio roles; [Track authoring](track-authoring.md)and [Caption authoring](caption-authoring.md) explain creating a new project component for them.+[Component design](component-design.md) explains shaping its behavior and controls around the work.[System relationships](system.md) connects these concepts to execution and Results;[media preparation](media.md) explains the values entering the timeline.diff --git a/skills/hypit/references/production/caption-authoring.md b/skills/hypit/references/production/caption-authoring.mdindex 29babbfc..71ee92a6 100644--- a/skills/hypit/references/production/caption-authoring.md+++ b/skills/hypit/references/production/caption-authoring.md@@ -5,6 +5,8 @@ Read this when a work needs a new relationship among its spoken words, layout an[Track authoring](track-authoring.md) owns project package wiring.[Fonts and text](fonts-and-text.md) explains exact font resources and fallbacks;[component visuals](component-visuals.md) explains the final drawing representation.+[Component design](component-design.md) connects a new family's visual idea to useful author controls+and its fit beside the rest of the video.## Decide what is actually newdiff --git a/skills/hypit/references/production/component-design.md b/skills/hypit/references/production/component-design.mdnew file mode 100644index 00000000..8e73e504--- /dev/null+++ b/skills/hypit/references/production/component-design.md@@ -0,0 +1,97 @@+# Designing a good component++Read this when a video needs a new visual role, shared state or expressive structure. 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 gives its author clear ways to direct that idea.++[Graphic composition](../playbooks/craft/graphic-compositions.md) owns visual hierarchy and motion;+[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.++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.++Sketch its intended Source use with this video's actual content. The tag and its children should+read like a concise account of the visual idea: which subjects are compared, which answer is already+known, and which statement reveals the next one. This makes the important choices visible early and+helps reveal a missing relationship before it becomes rendering code.++## 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 SemanticTrack; 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.++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 that preserve the idea++Separate the work's content from the behavior that presents it. Words, images, identities and event+references belong in Source. Related visual choices can form a Recipe. The component supplies a+coherent default treatment and the reusable layout, state and motion that make its role recognizable.++A good parameter earns its place by enabling a useful directing choice. A comparison may need labels,+images, emphasis, a Frame and a reveal relationship. Its internal coordinates can follow those choices.+Keep independently useful decisions independent, while letting one meaningful control coordinate details+that belong together. Palette, spacing and motion defaults should already form a designed whole.++Support the variation the work actually needs. Longer names, another product, a different number of+rows or a changed performance may be ordinary inputs; a new visual relationship may deserve another+component. Reuse becomes valuable when the next author can change the content while retaining the+idea. [Caption craft](../playbooks/craft/captions.md#one-data-contract-three-presentation-layers) gives+a concrete example of this distinction through family, Recipe/Style and parameters.++## 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 supplied 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+default can suit the present work while leaving size, position and assets authored. 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.++When a Studio Companion helps, expose the same meaningful entities and choices: a board's lifetime,+a row's reveal, a Caption Cue's actual Style. Editing the displayed entity should change the owning+Source fact. [Studio](studio.md#give-a-project-component-a-useful-companion) 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.diff --git a/skills/hypit/references/production/prompt-kits.md b/skills/hypit/references/production/prompt-kits.mdindex 42ed3149..a67b9831 100644--- a/skills/hypit/references/production/prompt-kits.md+++ b/skills/hypit/references/production/prompt-kits.md@@ -1,14 +1,40 @@-# Authoring Prompt Kits+# Choosing and authoring Prompt Kits-Read this when a useful piece of prompt direction should be assembled consistently across several-shots or projects. For one prompt whose wording belongs only to the current Source, ordinary-`text:Value` elements are enough.+Read this when choosing a reusable prompt treatment, assembling its Text inputs, or preserving useful+direction in a new Kit. A Kit can preserve proven wording even for one image or Take. Ordinary+`text:Value` elements carry the parts authored specifically for the current work.A Prompt Kit is a data-only TextTemplate Source. It owns reusable wording and meaningful choices;it does not own a model, Provider, media reference, output size, or production workflow. Keep fluentshot direction fluent. Turn something into a Kit when preserving the exact text or exposing a smallrepeated choice improves real productions, rather than splitting every sentence into a parameter.+## Choose an existing treatment by its relationship++[Image direction](../playbooks/craft/image-direction.md) and+[video direction](../playbooks/craft/video-direction.md) guide what the prompt should accomplish.+Choose a Kit whose fixed assumptions serve that intention:++| Direction needed | Where to look |+| --- | --- |+| The fixed phone-video capture wording, with this picture's framing, subject and environment | The installed `@hypit/gpt-image-kits` README and its `phone-ugc-v1` template |+| A speaking performer, podcast, street encounter, video call, silent B-roll, or motion/camera transfer | The installed `@hypit/seedance-kits` README and its corresponding exported template |++These are packaged Sources, so their README and exported `.svs` files supply the template names,+Text slots, defaults and Recipe choices. A package's Surface vocabulary serves a different role:+`hypit vocabulary @hypit/text --tag Render` describes assembly, and the selected model's vocabulary+describes generation. Read the chosen template when its fixed text or a choice's exact wording matters.++For an ordinary speaking passage, connect the Segment's `.dialogue` and this passage's action;+the selected Recipe supplies recurring performance choices. For an image, bring the framing and+subject/environment direction from Craft. Keep the template's reference roles consistent with the+actual media connected to the model. The owning package documents that order.++Fit includes assumptions as well as available knobs. A two-view conversation and a combined+split-screen opening may need different prompt structures. Keep the useful Kit for passages it+serves, and use authored Text or a project template for a different relationship. A Prompt Kit is+also distinct from a Run Fragment that supplies substitute media; [Runs](runs.md) owns that use.+## Declare the reusable text programAn `.svs` file selects Text's Recipe Frontend and declares one template root. This example preservesdiff --git a/skills/hypit/references/production/spatial.md b/skills/hypit/references/production/spatial.mdindex 6524fb9f..f2ef3aa9 100644--- a/skills/hypit/references/production/spatial.md+++ b/skills/hypit/references/production/spatial.md@@ -47,15 +47,115 @@ commands. [Fonts and text](fonts-and-text.md) shows which Typography placement c## Fit the source into the Frame-Media Track and Speech Track consume fit choices through their appearance Recipes:+Media Track and Speech Track's visual branch share two spatial roles:++- The **destination Frame** places the visual on the Canvas and supplies its outer shape.+- The **fitted content rectangle** places the scaled source inside that Frame. Its size and position+ come from the source's real Extent and the appearance Recipe's fit and alignment choices.++Supply the destination Frame and the source's actual dimensions. A still image needs an Extent;+prepared moving media already carries its dimensions. The component calculates the content rectangle.+Border and padding reduce the area used for fitting inside the outer Frame. This inset is derived+from those settings, rather than requiring another authored Frame.++For example, with no border or padding, a `1600 × 900` image fitted into a `600 × 600` Frame becomes+`600 × 337.5` under `contain`, leaving room above and below when centered. Under `cover`, it becomes+about `1066.7 × 600`; a frame clip shows the middle square. Moving the destination moves the whole+presentation; changing content alignment changes which part of that image occupies the square.++Choose fitting through the component's appearance Recipe:- **contain** keeps the complete image visible and may leave space around it;- **cover** fills the destination and may crop the image;- **stretch** changes the source proportions to occupy the destination.-Choose fitting with the subject and its surrounding composition in view. A Frame only places the-rectangle; it does not identify the face or choose an editorial crop. Query the selected component's-appearance vocabulary for its crop and alignment controls.+The installed vocabulary also exposes `fit-width`, `fit-height`, `native` and `scale-down` when one+dimension or the source's own pixel size should determine the scale. The default is centered+`contain`. `fit: stretch` is spatial resizing; Media Track's `playback: stretch` is a separate choice+about video speed.++## Align the picture inside its destination++The fit aligns a point on the scaled picture with a point in the fitting area:++| Control in the appearance Recipe | Meaning |+| --- | --- |+| `frame-x`, `frame-y` | The destination alignment point, from `0` to `1` across the fitting area's width and height |+| `content-x`, `content-y` | The point on the scaled source that meets it, also from `0` to `1` |+| `fit-offset-x`, `fit-offset-y` | Additional source displacement in pixels, positive right and down |+| `fit-constraint` | `bounded` keeps the fitted rectangle within the available placement range; `free` preserves the authored alignment and offsets |++The four point coordinates default to `0.5`; offsets default to zero. To keep a cover crop aligned+to the top, use `frame-y: 0; content-y: 0;`. `frame-x` and `frame-y` are alignment fractions inside+this fitting area. Position the whole card or inset with its spatial Frame.++With `bounded`, a source larger than the fitting area keeps it covered on that axis; a smaller+source stays inside it. An offset can therefore be limited, including to zero when the dimensions+match. Use `free` when exposing space through an offset is part of the design. Choose alignment from+the actual subject and composition; these coordinates express your crop choice.++## Shape the outer frame++Clipping, border, padding, shadow and frame paint belong to the outer Frame. The shared appearance+Recipe uses `clip: frame` for a rectangular clip, `clip: rounded` with a pixel `radius` for rounded+corners, or `clip: none` to show overflow. A radius takes effect with the rounded clip.++Here is a circular presenter inset; the named Canvas, SemanticTake and imported namespaces are+already available:++```svml+<space:AnchoredFrame id="presenter-frame" within={canvas}+ x="94%" y="94%" width="320px" height="320px" anchor="bottom-right"/>+<speech:Track id="speech" visual-frame={presenter-frame}+ visual-appearance={look.presenter} visual-z="20">+ <speech:Take source={opening.take}/>+</speech:Track>+```++```svs+look.presenter {+ fit: cover;+ clip: rounded;+ radius: 160;+ border-width: 3;+ border-color: #D8C7A8;+}+```++A square Frame with radius half its side makes a circle. This crops the source geometrically;+subject-shaped transparency comes from the prepared media. For a rounded card, choose a radius+appropriate to its size. Rounded clipping follows the Frame: a smaller `contain` picture sitting+away from its corners can still have square picture corners. For rounded edges that follow the+picture itself, make the Frame match its displayed aspect and place the content flush inside it.++`padding` uses quoted pixel values: `"12"` for all sides, `"8 12"` for vertical/horizontal, or+`"8 12 16 12"` for top/right/bottom/left. Border and padding both reduce the fitting area while the+outer Frame keeps its size. Padding changes where fitting happens; the clip still follows the outer+Frame. `frame-paint` colors the space behind the source, including space left by fitting. Borders+outline the Frame and `shadows` sit behind it. Sample `opacity` and filters affect the picture;+the frame's paint and decoration have their own appearance.++## Move the frame or move its contents++A lifecycle `motion` Recipe moves or fades the complete framed presentation, including its border+and paint. `Sampling` children pan, zoom or rotate the fitted picture under that frame. Use Sampling+for a moving crop or a slow push-in while a card's outline stays still:++```svml+<speech:Take source={opening.take}>+ <speech:Sampling at="start" zoom="1"/>+ <speech:Sampling at="end" zoom="1.08" y="-18"/>+</speech:Take>+```++This Take excerpt belongs inside Speech Track. Media Track accepts the same Sampling fields on a+direct-source Item or Member, or on a sampled Layer. `x` and `y` are pixel offsets, `rotate` is in+degrees, and `at` follows the source unit's active span from `start` to `end`, with percentages for+intermediate keys. Sampling acts after the static fit; its movement can expose space inside the+Frame. Choose the crop and motion together for the intended coverage.++[Tracks](tracks.md) explains the Media/Speech inputs and timing roles. Read their installed+vocabulary for the complete appearance and motion fields.## Carry measured regions through the same geometrydiff --git a/skills/hypit/references/production/track-authoring.md b/skills/hypit/references/production/track-authoring.mdindex 108a9ed9..b930817d 100644--- a/skills/hypit/references/production/track-authoring.md+++ b/skills/hypit/references/production/track-authoring.md@@ -2,6 +2,8 @@Read this when a production needs new graphic structure, state or rendering behavior. Begin fromwhat 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 discoveryand project package ownership. [Caption authoring](caption-authoring.md) covers the speech-text case.diff --git a/skills/hypit/references/production/tracks.md b/skills/hypit/references/production/tracks.mdindex 805fdb2f..55096bdc 100644--- a/skills/hypit/references/production/tracks.md+++ b/skills/hypit/references/production/tracks.md@@ -120,6 +120,12 @@ order. Sampling children can pan, zoom or rotate the Take's picture inside thatSegment progress. Media Track remains the owner of an independent Window, source playback and trim,source audio, replacement Sequences and pictures that are not the speaking performance.+The Track's `visual-frame`, `visual-appearance`, `visual-motion` and `visual-z` are defaults for its+Takes. A Take's `frame`, `appearance`, `motion` or `z` replaces that corresponding choice; an+appearance override selects a complete Recipe. In Speech Track, use `visual-z` / `z` for stacking.+The visual branch uses the Take's existing span, so a new Frame or crop changes its presentation+while preserving semantic time and speech.+Semantic structure also supports a wordless passage. It has no speaking A-roll, yet a named emptyScript Segment receives its actual boundaries from prepared media and remains addressable throughthe assembled SemanticTrack. Semantic identity here means that the work can refer to the passage and@@ -146,6 +152,17 @@ An image needs its intrinsic Extent. Moving media enters through explicit normal`surface` accepts an already compositable surface from another component. Frame says where it goes;fit/crop says how the source occupies it.+[Spatial layout](spatial.md#fit-the-source-into-the-frame) explains the shared destination/content+model, including alignment, rounded corners, padding, borders and the difference between moving+the Frame and moving its contents. A Media Item or Sequence takes its outer Frame from `frame` and+its stack order from the appearance Recipe's `stack-order`.++For a picture with a designed backing, an Item can use ordered `Paint` and `Layer` children in place+of a direct source. Paint fills the frame; each sampled Layer has its own fit and picture styling.+The unit owns the shared clip, border and motion. A Sequence keeps that outer presentation while its+Members replace the content. Use separate Items when pictures need independent Frames. The Media+Track vocabulary supplies the exact Layer, Sampling and Handoff forms.+For natural moving B-roll, start with `once-start`: a short Window truncates the clip; a long Windowreturns to the layer below after the clip finishes. If uninterrupted coverage matters, choose itsmedia and boundaries from the actual clip length. `hold-start` freezes a tail; choose it when thatdiff --git a/skills/hypit/references/production/vocabulary.md b/skills/hypit/references/production/vocabulary.mdindex 507342e5..1a9587e9 100644--- a/skills/hypit/references/production/vocabulary.md+++ b/skills/hypit/references/production/vocabulary.md@@ -81,9 +81,10 @@ Describe the Surface's role, attributes and outputs with a small valid example scan select it. A visual preview makes its appearance recognizable; Studio shows the actualconfiguration used in a production.-For existing Track composition, read [Tracks](tracks.md). For a new Track, read-[Track authoring](track-authoring.md) when deciding temporal inputs, spatial ownership, persistent-state, preset content or peer visual/audio outputs. [Caption authoring](caption-authoring.md) covers+For existing Track composition, read [Tracks](tracks.md). For a new Track,+[Component design](component-design.md) shapes its visual idea, semantic behavior and useful controls.+[Track authoring](track-authoring.md) explains temporal inputs, spatial ownership, persistent+state, preset content and peer visual/audio outputs. [Caption authoring](caption-authoring.md) coversa new speech-text family without rebuilding its transcript or timing.[Studio and Companions](studio.md) covers timeline presentation and Inspector editing for the new