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(skill): teach Studio companion authoring and keep design notes local
kashorindddca8149c29
diff --git a/.gitignore b/.gitignoreindex 5132f4b9..7d2e5cae 100644--- a/.gitignore+++ b/.gitignore@@ -1,6 +1,10 @@node_modules/dist/coverage/+# Local architecture notes and repository-specific working instructions.+/design/+/.agents/development/+/AGENTS.md.nyc_output/.DS_Store*.logdiff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.mdindex 17b6818f..cdd0f49d 100644--- a/skills/hypit/SKILL.md+++ b/skills/hypit/SKILL.md@@ -225,7 +225,8 @@ practical, revisit that choice and carry the improvement into the work and its n| drawing a component's elements, animation, resources or prepared surfaces | `references/production/component-visuals.md` || writing a Caption family with new word relationships, scheduling or layout | `references/production/caption-authoring.md` || `plan`, Provider pricing information, `build`, a retry or interrupted submission, following work, Results and exports | `references/production/builds.md` |-| opening Studio, understanding its views and edits, or adding a component Companion | `references/production/studio.md` |+| opening Studio, using its views, editing parameters or moving semantic timing | `references/production/studio.md` |+| giving a component useful timeline entities, picture selection and author controls | `references/production/studio-companions.md` || Film assembly, pure MG with authored time, picture and sound, final rendering or a selected frame interval | `references/production/rendering.md` || judging the preview or finished Result and deciding what to fix | `references/production/review.md` || recognizing a whole-work format, combining formats, or discovering another directing Craft | `references/playbooks/index.md` |diff --git a/skills/hypit/references/production/component-design.md b/skills/hypit/references/production/component-design.mdindex 362660c6..85d98863 100644--- a/skills/hypit/references/production/component-design.md+++ b/skills/hypit/references/production/component-design.md@@ -115,7 +115,7 @@ should reveal the behavior that makes someone choose this component, with usefulWhen 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.+Source fact. [Companion authoring](studio-companions.md) owns those bindings.For an existing example, read the installed `@hypit/ranking` README and the part of its implementationthat answers the current question. It connects semantic reveals, settled state, layout and editordiff --git a/skills/hypit/references/production/studio-companions.md b/skills/hypit/references/production/studio-companions.mdnew file mode 100644index 00000000..5df8f4b1--- /dev/null+++ b/skills/hypit/references/production/studio-companions.md@@ -0,0 +1,129 @@+# Make a component useful in Studio++Read this while adding timeline meaning, picture selection or author controls to a project+component. [Studio](studio.md) owns opening and operating the editor;+[component design](component-design.md) owns the component's creative boundary.++The Companion describes two things: **what an author can recognize and select**, and **which+authored fact an edit changes**. Keep the same concepts across the picture, timeline and Inspector.+A reveal can be one entity even when its graphic moves and later remains on a board. A coordinated+presenter-and-diagram scene can stay one entity when its layout is intended to be edited together.++## Choose useful entities and lanes++Match the component's actual Module ABI, Surface and terminal output Type. Generic VisualTrack or+AudioTrack entities are enough for simple occupancy. Use `project(context)` when the author needs+domain meaning that the terminal drawing no longer contains. A Surface preview supplies a useful+static recognition image; live entities and editable bindings come from the Companion.++For example, a board can expose its outer lifetime and its individual reveal events. Publish the+deterministic schedule/program needed to describe these from the same Surface, then request its+exact output port through `requiredValues`. `requiredSurfaceValue(context, "schedule")` reads that+published output. `requiredReferencedValue` reads an exact typed author reference instead.++| Declaration | Authoring meaning |+| --- | --- |+| Companion label, tone, icon and `lane.heightPx` | Recognize the component and give its information enough room. |+| Entity id and authored identity | Select the same authored object after recompilation or reordering. Qualify child ids across component instances. |+| `display.title` and display layers | Show useful content, text or declared media rather than an opaque implementation id. |+| `startFrame`, `endFrameExclusive` | Describe what this rectangle edits: occupancy, activation or another explicit interval. |+| `stackOrder` | Order overlapping editor entities; this is separate from changing the Film's paint order. |+| Companion `attachments` and entity `lane` | Expose a meaningful child lane, such as reveals under a board, with its own fields. |++Each declared lane is one row. Overlapping items remain selectable; selection raises the selected+rectangle within that row. Parent and attached lanes use the same behavior. Add a child lane when+it explains another authoring relationship, such as activation within a persistent board.++An activation rectangle may end before the object disappears. Keep the activation's editable range+and the object's continuing picture identity distinct. The installed Ranking Companion demonstrates+this with board, reveal and activation lanes.++## Connect the picture to the entity++Associate the actual rendered parts with `presentId` or `renderIds`. All phases belonging to the+same item can select that item: entrance, movement and settled appearance. Give the board/background+parts to the parent and the reveal's parts to its child when separate selection is useful.++The renderer's explicit `subjectId` can associate multiple rendered phases with one domain item;+the Companion carries their actual ids into `renderIds`. Studio uses the visible parts at the+current frame. This preserves selection after an icon lands without duplicating animation geometry+in the Companion. A preset with no separately exposed child remains part of the parent entity.++Picture selection and timeline selection identify the same authored object. Position and size can+then be adjusted through its declared Inspector fields.++## Expose decisions, not implementation debris++Declare `bindings` for the actual author endpoints, then choose visible `inspector` fields. A+binding can follow a shared authored Frame or Style through `referenced`, or an SVS Recipe through+`recipe`. Use `parameterReferences` for an entity's actual reference, such as the Style selected+for this Caption Cue. Shared values retain their shared effect when edited.++Where describes placement and layout. When describes timing, playback and motion. How describes+appearance, content and sound. Each Companion chooses useful pages and sections within them.++| Control | Useful choice |+| --- | --- |+| `text` | Wording or a meaningful expression; `multiline` for longer text. |+| `number` | Magnitude, with appropriate units, scale and limits. |+| `boolean` | An actual two-state choice. |+| `select` | Preset, font, alignment or another finite choice, with readable labels. |+| `color` | Exact hex color, optionally with suggested `swatches`. |+| `list` / `record` | A schema-described ordered list or named set of values, edited as one Apply/Reset draft. |++For a Surface with a literal `label` attribute, a minimal declaration is:++```ts+bindings: [{ name: "label", writable: true }],+inspector: [{+ binding: "label", label: "Label", domain: "how",+ section: { id: "content", label: "Content" }, control: "text",+}],+```++The Surface already owns `label`; the Companion exposes it. A width stored as `"78%"` can use+`control: "number", number: { suffixes: ["%", "px"] }`: editing 42 retains the existing suffix.+An opacity stored as `0.78` can use `unit: "%", number: { scale: 100, minimum: 0, maximum: 100 }`:+the control shows 78 and entering 42 writes 0.42. `unit` alone is a display label. Suffix handling+retains an authored unit; it does not convert percentages to pixels.++Select options may be plain strings or `{ value, label, description, preview }` entries. Color and+font previews are small visual hints; the actual option value is written. A font hint uses a family+available to the editor, while the production font remains an explicit resource as described in+[fonts and text](fonts-and-text.md). The component's schema owns valid author values. Studio+performs the declared conversion, serializes in the source language and saves the owning file.++## Preserve the timing decision through editing++Carry the real Window/Instant lineage into each entity. For a domain Spec consumed beside a+projection, `temporalLineageFor(context, item.id, "activation")` follows that actual consumer input;+use the real input name, such as `window`, `outer` or `activation`. `authoredChildFor` and+`childEntities` connect domain child identities to their exact author origins.++The [authored time form](studio.md#edit-the-owning-source-fact) determines the edit: a direct+Selection changes its two Script anchors, a direct Moment changes one anchor, and a quoted clock+expression changes its local time or offset. A projected frame alone does not establish that+relationship. Several objects can consume the same Selection or Moment; changing it updates them+all through normal compilation. A separate offset remains a separate local decision.++## Load it with the project package++Keep the Companion separate from the component's Producers. External packages import+`@hypit/hypit/studio-adapter` and relevant public `@hypit/hypit/*` APIs, with the Distribution as a+development dependency. Add `createStudioTrackCompanionHostFacet(companions)` to the existing+activation's `hostFacets`, retaining its author and producer contributions. Ship the compiled+Companion through the package's normal activation entry.++The Source-selected package activates its Companion. Restart Studio after changing package code+or activation. Ordinary Source and Recipe edits recompile within the current session.++Use the installed `packages/studio-adapter/README.md` for the complete minimal Companion and+activation example, `packages/studio/INSPECTOR.md` for field declarations, and+`packages/temporal-markup/EDITING.md` for exact time-form behavior. These are package references+inside the installed Distribution. Ranking, Caption Fine and Media Track Companions demonstrate+persistent events, per-Cue styles and material occupancy respectively.++Try the component in its actual Run: select a meaningful picture part, inspect the corresponding+timeline entity, change an exposed value and inspect the owning Source and resulting picture.+For a shared timing edit, inspect the other consumers too. Seek into both movement and settled+states when those belong to the component's behavior.diff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.mdindex 970ffec3..26ca0f6c 100644--- a/skills/hypit/references/production/studio.md+++ b/skills/hypit/references/production/studio.md@@ -1,7 +1,8 @@-# Working in Studio and adding a Companion+# Work in StudioRead this when opening a Run, using its timeline and Inspector, or giving a project component a-useful Studio presentation. [Review](review.md) owns the judgment made from the visible work;+useful Studio presentation. For component implementation, read [Companion authoring](studio-companions.md).+[Review](review.md) owns the judgment made from the visible work;[Track authoring](track-authoring.md) owns the component's production behavior.## Open the actual Run@@ -51,12 +52,17 @@ include when the user wants to continue editing on another machine.| View | What it shows and what it can change || --- | --- || Source | The exact Run, Author and imported Source/Recipe files. Select a file and use Edit source; changes save automatically, and Cmd/Ctrl+S saves immediately. Check save/error state. This is not a project filesystem browser. |-| Preview | The selected Film composition rendered by HyperFrames in the browser. Play or seek to inspect the actual selected media and graphics. |+| Preview | The selected Film composition rendered by HyperFrames in the browser. Play or seek with the transport or timeline. Selecting a component-declared visual part selects its corresponding timeline entity; adjust its exposed position in the Inspector. || Timeline | Semantic Segments, Selections and Moments, plus the component-projected Track entities and their visible intervals, materials or event lanes. A rectangle may describe occupancy, activation or persistent visibility; read the component's meaning. || Inspector | With nothing selected, project, Canvas, time and Run facts. For a selected entity, only its declared adjustable fields, organized under Where, How and When where applicable. || Tasks | One card per Build, grouped into ongoing and finished. Active status and progress come from the selected Runtime; completed, failed and cancelled Builds come from project Results. Cards retain the source Run, times and any failure or attention reason. || Artifacts | Image, video and audio file Outputs from project Results, including those already published by ongoing Builds. Use the sidebar to choose all media, videos, images or audio. View media on a Build opens its Outputs; opening the Artifacts tab returns to project media. Composite Outputs such as normalized media and Semantic Takes stay intact and do not add their internal files to this gallery. Click a card to view it in the central preview; video and audio have playback and a time slider. Back to composition returns to the existing composition position. Previewing a file does not select it as a Candidate in the Run. |+A declared lane stays one row even when items overlap. Later items cover earlier ones at equal+stacking order; selecting an item brings its full rectangle forward within that lane. This changes+editor selection, not the Film's paint order. The same behavior applies to attached child lanes.+When semantic time is present, its lane stays below the time ruler while the other lanes scroll.+Open either library tab or click Refresh to read its latest state. These lists do not poll.Refresh replaces the view; scrolling to the end loads more. Media categories query matching filesacross Result pages, so an intervening Build without that kind of media does not require a separate action. A failed refresh keeps the@@ -107,6 +113,8 @@ then follows the changed relation. The authored time form determines what the ge| 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. |@@ -115,51 +123,37 @@ then follows the changed relation. The authored time form determines what the geA semantic stop is a distinct frame position occupied by word or structural boundaries. Select asemantic marker to see its exact anchors; when several share a frame, the Inspector offers the-choices supported by its editable consumers. Direct Segment/Program spans follow their structural-boundaries without timeline dragging. Components declare their own handles and writable fields.+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](../creation/script-and-time.md#bind-meaning-to-script-identities)+as authored markers. Writeback normalizes ordinary same-line spacing while preserving line breaks,+indentation, words, punctuation, pronunciation and display attributes. The resulting formatting+becomes the next edit's starting point. A shared Selection or Moment remains one relationship:+editing through any consumer updates its other consumers according to their own projections.++A successful parameter or timeline edit saves the owning Source and recompiles the selected Run+for the view. Rejected edits retain the accepted Source and values. Result renaming instead updates+Result presentation metadata; it does not change the authored composition or trigger a Build.+Source edits outside Studio are observed too. If a stale UI edit conflicts with a newer file, readthe current Source and retry the intended change against it instead of overwriting the newer work.-All successful edits return to the ordinary Sources; they do not create a second Studio project.+Composition edits return to the ordinary Sources; they do not create a second Studio project.## Give a project component a useful Companion-The component's Producers own its rendered video. A **Studio Companion** explains that component to-the editor: which output it understands, what its timeline entities mean, which materials to show,-which authored parameters to expose and how an edit relates back to Source.--Generic VisualTrack and AudioTrack presentation already exists. Add a Companion when it makes the-new role legible or editable: for example, a score board's outer lifetime and per-score activations,-or a Caption family's Cue text and actual per-Cue Style. A static vocabulary preview helps recognize-a component; it does not supply these live entities or edit bindings.--Keep Companion code separate from domain computation and contribute its Host facet from the-Source-selected project package's activation. The Distribution supplies official Companions; a-project package can supply its own without editing Studio or adding a Studio Profile. Installing an-otherwise unselected package does not activate a plugin. The installed `@hypit/studio-adapter`-README gives the exact ABI, a minimal Companion and the activation wiring.--An external Companion imports `@hypit/hypit/studio-adapter` and the relevant public `@hypit/hypit/*` domain APIs,-with `@hypit/hypit` as a development dependency. Ship the compiled Companion with the component. Its-Source-selected activation contributes the editor facet alongside the component's existing facets.--Expose meaningful deterministic schedule/program outputs when the Companion needs more than the-terminal Track. Ask for exact same-Surface output ports through `requiredValues`, or follow one-exact typed authored reference. Preserve child identities and consume the real Window/Instant graph-edges so Studio can trace temporal authority. Never infer a Moment from matching frame numbers,-an id prefix or a parsed attribute name.--Declare Source bindings separately from visible Inspector fields. Offer the parameters useful to-this production, including explicit reference paths into Recipes. The Companion selects finite-presentation and controls; Studio owns DOM, CSS, validation and Source writes. A Companion does not-need its own filesystem mutation, Provider calls or rendering loop.--For implementation patterns, read the installed `@hypit/ranking-studio` for persistent state and-activation lanes, `@hypit/caption-fine-studio` for Cue/Style relationships, or-`@hypit/media-track-studio` for media occupancy. Verify the new component in an ordinary Run:-select the intended entity, adjust one exposed value, inspect the exact Source change and seek to-the affected frames. For shared semantic timing, also inspect the other consumers of that marker.+A Companion makes the component's own production relationships legible and editable: a board's+lifetime, a reveal event, a Cue's actual Style, or a scene's layout choices. Its Producers still own+the rendered work. Generic Track presentation is useful when no additional authoring concepts are+needed; a component with meaningful child events or controls can publish those directly.++Read [Companion authoring](studio-companions.md) for entities and child lanes, picture selection,+parameter controls, unit conversion, semantic writeback and package activation. It builds on the+same [component design](component-design.md) decisions used to make the video.diff --git a/skills/hypit/references/production/track-authoring.md b/skills/hypit/references/production/track-authoring.mdindex 16cfbe1e..fac2477e 100644--- a/skills/hypit/references/production/track-authoring.md+++ b/skills/hypit/references/production/track-authoring.md@@ -195,7 +195,7 @@ Document which Outputs are public, including useful deterministic program values## Verify the behavior the component introducedWhen the new role needs its own timeline presentation or Inspector, read-[Studio and Companions](studio.md#give-a-project-component-a-useful-companion). Expose the domain+[Companion authoring](studio-companions.md). Expose the domainschedule and temporal identities at their actual boundaries so the editor consumes them directlyinstead of reconstructing them from pixels.