Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs(skill): teach Studio companion authoring and keep design notes local

kashorindddca8149c29
diff --git a/.gitignore b/.gitignore
index 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
*.log
diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.md
index 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.md
index 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 useful
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.
+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 implementation
that answers the current question. It connects semantic reveals, settled state, layout and editor
diff --git a/skills/hypit/references/production/studio-companions.md b/skills/hypit/references/production/studio-companions.md
new file mode 100644
index 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.md
index 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 Studio
Read 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 files
across 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 ge
A semantic stop is a distinct frame position occupied by word or structural boundaries. Select a
semantic marker to see its exact anchors; when several share a frame, the Inspector offers the
-choices supported by its editable consumers. 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, read
the 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.md
index 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 introduced
When 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 domain
schedule and temporal identities at their actual boundaries so the editor consumes them directly
instead of reconstructing them from pixels.