@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

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

@@ -0,0 +1,189 @@
+# Spatial layout
+
+Read this when positioning or fitting media, text or a project component. Timing is explained in
+[Timing](timing.md); it is independent of these coordinates. Read
+[component design](component-design.md) when deciding which content shares layout or motion;
+[image direction](../playbooks/craft/image-direction.md) owns the source camera view. This page owns
+the destination geometry, for Performance, independent Media and project scenes alike.
+
+## Canvas, extent and destination
+
+The Canvas gives the final image's pixel dimensions and coordinate basis. Introduce Frames and
+component scopes where they help organize the picture; they need not tile the canvas or remain
+separate rectangles. Components can overlap, share motion and own local trees. Canvas itself does
+not contain a central list of layers. Each rendered Present supplies its own paint order.
+
+An IntrinsicExtent gives a source image's actual dimensions. A Frame gives the destination rectangle
+a consumer should occupy. A landscape image can retain its real extent while appearing in a portrait
+composition. An A-roll source has no prescribed Frame or crop. For performance remaining mostly
+full-screen, its intended final aspect can guide source direction; later insets or splits remain
+presentation choices. Translate required source framing into visible camera facts before generation.
+
+```svml
+<import as="space" from="@hypit/spatial@1"/>
+
+<space:Canvas id="canvas" width="1080" height="1920"/>
+<space:Extent id="photo-size" width="1600" height="1200"/>
+<space:Frame id="full" within={canvas}
+  left="0%" top="0%" right="100%" bottom="100%"/>
+<space:Frame id="content" within={full}
+  left="6%" top="8%" right="94%" bottom="90%"/>
+```
+
+Coordinates start at the top left; x increases rightward and y downward. Frame edges are positions
+from the parent's left/top, so `right="94%"` is the right edge at 94% of parent width. It leaves a
+6% margin. A percentage on the x axis uses the parent width; on y it uses parent height. Nesting
+changes that reference rectangle. Pixel lengths use `px`.
+
+## Anchor an object or preserve its aspect
+
+```svml
+<space:AnchoredFrame id="label" within={content}
+  x="50%" y="85%" width="80%" height="12%" anchor="center"/>
+<space:AspectFrame id="photo-frame" within={content}
+  x="100%" y="0%" width="45%" aspect={photo-size} anchor="top-right"/>
+```
+
+AnchoredFrame pins the named point of a sized rectangle to x/y in the parent. AspectFrame derives
+one dimension from the other: specify width or height, plus an Extent or a ratio such as `4/3`.
+An `offset-x` or `offset-y` is an additional pixel nudge. An anchored frame can extend beyond its
+parent when that is the intended composition.
+
+For text, `space:Point` supplies a pixel position and `space:Path` supplies authored Move/Line/curve
+commands. [Fonts and text](fonts-and-text.md) shows which Typography placement consumes each.
+
+## Fit the source into the Frame
+
+Media Track and the ordinary Performance Style 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.
+
+The selected Media/Performance 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"/>
+<time:Clock id="clock" frame-rate="30"/>
+<time:Timeline id="speech" clock={clock}>
+  <time:Take source={opening.take}/>
+</time:Timeline>
+<performance:Style id="presenter-style" frame={presenter-frame} appearance={look.presenter}/>
+  <performance:Track id="presenter" timeline={speech.timeline} canvas={canvas}>
+    <performance:Use style={presenter-style} during="program"/>
+  </performance:Track>
+```
+
+```svs
+look.presenter {
+  stack-order: 20;
+  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
+<media:Item media={prepared.media} during={story.selection.detail}
+  frame={detail-frame} appearance={look.detail}>
+  <media:Sampling at="start" zoom="1"/>
+  <media:Sampling at="end" zoom="1.08" y="-18"/>
+</media:Item>
+```
+
+This excerpt belongs inside Media Track, with prepared media, a Selection, Frame and Recipe already
+available. Sampling fields apply to a direct-source Item or Member, or 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.
+
+[Performance](performance.md) applies fixed or custom Styles to existing Timeline footage. A moving
+Style retains the original Use Window across partial coverage and Take boundaries. A scene that
+coordinates the viewport with surrounding graphics can own the shared motion in its
+[component program](component-visuals.md#compose-video-and-graphics-in-one-browser-program), retaining
+source playback positions.
+
+[Media presentation](media-presentation.md) and [Performance](performance.md) own their content and
+playback inputs. Read their installed vocabulary for the complete appearance and motion fields.
+
+## Carry measured regions through the same geometry
+
+RegionTimeline contains already measured boxes indexed by program frame. Its recipe uses normalized
+`[x, y, width, height]` boxes and `null` for absent measurements, converted against the chosen Canvas.
+Take-local measurements need their actual program offsets. Reframed or cropped footage needs the
+corresponding spatial transform before its boxes can position text correctly.
+
+[Caption tracking](../playbooks/craft/caption-tracking.md) explains producing and applying head
+regions. In a new component's visual element tree, child positions are relative to their parent;
+[component visuals](component-visuals.md) shows that final layout boundary.

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

@@ -0,0 +1,186 @@
+# 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.
+Recognition and editing are separate capabilities. A production may use Studio mainly to watch and
+show its arrangement, with a few useful adjustments. Clear labels, timing and selected read-only
+facts can fully serve a one-off scene; useful Caption controls can coexist with that fixed scene.
+
+## 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.
+
+Generic presentation recognizes the terminal Type, not the component's creative role. A custom
+Caption Track can therefore render correct subtitles yet appear as a generic blue visual lane with
+opaque ids when its package has no matching Companion. Inspect the selected Companion and its
+Module/Surface match before treating this as misplaced content or moving visuals between Tracks.
+The package declares its role; Studio does not infer one from a tag name or the text in a picture.
+
+When adapting an existing family, carry forward its editor meaning wherever the public content,
+schedule and author identities still agree. Reuse its Companion with the actual Module/Surface
+identity, or adapt its projection for the changed behavior. Preserve useful Cue/Use or item/event
+relationships along with rendering. A rendering wrapper alone does not activate that integration.
+
+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 the board and its independent reveals.
+
+## Put related rules in a Band
+
+A Track's `bands` are internal strips sharing its label. For example, Caption shows Cue content
+with a bottom band for Style Uses; Performance and Sound show placed Takes with their Uses below.
+The rule is a selectable entity with its own Window, even when overridden or currently empty.
+It remains one Use across gaps and content boundaries.
+
+```ts
+bands: [{ id: "uses", placement: "after", heightPx: 15, display: "label" }]
+// The projected Use entity selects: band: "uses"
+```
+
+Use `attachments` for independent child objects such as Ranking reveals. Use a Band for another
+aspect of the same Track such as its presentation choices. Both use ordinary entity selection,
+overlap order, field declarations and time editing. Each entity chooses one declared band or lane.
+
+## 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. If position and size
+are exposed choices, its declared Inspector fields can adjust them.
+
+## 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, when a derived entity points to a different authored object. Shared values retain their shared effect when edited.
+
+A Companion presents the author model. A meaningful semantic event may deserve a timeline handle
+without turning every animation key into an Inspector field. Conversely, a visible number or
+qualitative setting inside drawing code need not become a public input. The
+[parameter boundary](component-design.md#expose-the-choices-the-work-needs) applies before choosing UI controls. When an Inspector adjustment
+is actually needed, bind it to a real Source input or domain event. A label inside a one-off renderer
+can remain an implementation detail until external control has a purpose. Useful child entities can
+live inside the same Track, and selection can be read-only. The
+[component boundary](component-design.md#separate-responsibility-parameters-and-reuse) determines
+what is independently organized; it does not prescribe how many controls to provide.
+
+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, saved together when editing ends and the value is complete. |
+
+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.
+
+A Style can own its controls independently of the Track that consumes it. The Track declares
+`{ name: "style", companion: true }`; the Style's package contributes
+`createStudioCompanionHostFacet({ parameters: [{ id, match: { module, surface }, bindings, inspector }] })`.
+Its field names are local to that Style. Studio follows the reference and combines those fields
+with the Use's time controls. This works for a new project motion Style as well as a familiar
+framed presentation. Shared Style edits continue to affect its other Uses.
+
+A binding's typed `fallback` exposes an omitted default; first editing it writes the property or
+attribute into its owning source. A fallback function can express a dependent default from the
+authored properties. Choose useful valid defaults in the component's own vocabulary. Read-only
+facts and controls share Where, When and How; unpaged fields remain visible beside the active page.
+
+Related scalar attributes can share one `record` draft through a binding's `attributes` list and
+schema. Use object alternatives with a literal mode field when each choice needs different inputs;
+Once its required fields are complete, editing writes the chosen group together and removes unused members. Audio playback demonstrates
+this for its mode and stretch bounds. The package owns those alternatives; see
+the installed Studio adapter README, “Edit related attributes together,” for the exact declaration.
+
+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](timing.md#choose-what-a-later-edit-changes) 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, Cue content with Style Uses, 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.

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

@@ -0,0 +1,249 @@
+# Work in Studio
+
+Read this when opening a Run, choosing its interface language, using its timeline and Inspector, or giving a project component a
+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
+
+From the video project, use the installed Distribution's command:
+
+```bash
+hypit studio --run build.svrun
+```
+
+Supply `--runtime <profile>` when intentionally using a different Profile from the project's
+`hypit runtime use` selection. Studio needs a Run whose selected targets reach one Film with resolved
+composition and time. The Timeline supplies the clock and any placed Script anchors for component
+lanes, including a pure animation with no Takes. An image-generation-only Run is not a Film view; several distinct
+Films need separate Runs or sessions.
+
+Open the URL actually printed by the process and retain it with the Run it serves. For review, open
+that URL with `#comments` appended, such as `http://localhost:5179/#comments`; this selects the
+Comments view directly. The printed port is authoritative. The default
+requested port is 5179; `--port` selects another, and an occupied port can cause Vite to choose a
+different one. Reuse an existing session when it serves the intended project and Run.
+
+The startup output identifies the project, absolute Run path, Runtime Profile and selection source.
+An explicit `--runtime` applies to this session; the project's default comes from `.hypit/runtime`.
+When launching from another directory, use `--workspace` to select the project and supply the Run
+path from the current directory, as shown in [project boundaries](../creation/project-files.md#establish-the-project-boundary).
+
+Studio watches the Run and its loaded Author/Recipe Sources and recompiles them after changes.
+Changing package code, adding a package import, changing Companion activation, or selecting another
+Runtime or Result repository requires restarting that Studio session: those implementations and
+selections are loaded at startup. A browser refresh alone does not reload the server-side modules.
+Stop only the relevant Studio process; stopping Studio does not cancel a submitted Build.
+
+## Choose the interface language
+
+The globe menu to the left of **Studio / Comments** changes the interface language. English and
+Simplified Chinese are included. The first visit follows browser language preferences; later visits
+remember the user's choice. Switching preserves the playhead, selection and comment draft. When
+introducing the review, point out this menu if it helps the user work in their preferred language.
+This choice affects Studio's interface, not the video's Script, captions or user comments;
+component-owned names and Companion labels retain their authored text.
+
+Additional languages are ordinary JSON data, loaded explicitly when opening Studio:
+
+```bash
+hypit studio --check-locale ./studio-ja.json
+hypit studio --run build.svrun --locale-pack ./studio-ja.json
+```
+
+For a new translation, copy `packages/studio/locales/en.json` from the installed Distribution.
+Set `locale`, the native language `name`, and `direction` (`ltr` or `rtl`); translate `messages`
+while keeping their IDs and named variables such as `{count}`. Missing entries use English.
+The check command reports missing entries, unknown IDs and invalid variables without opening a Run.
+Relative file paths start at the command's working directory. Repeat `--locale-pack` for several
+languages, or pass an installed package's JSON export instead, such as
+`--locale-pack @your-scope/studio-ja/locale.json`. A local file is enough; sharing it as a package
+is optional. Restart Studio to load changed language files. The installed
+`packages/studio/LOCALIZATION.md` covers plural forms and JSON package exports.
+
+## Discuss the work while composing
+
+When the user is collaborating locally, open the actual composition once a meaningful passage is
+available and keep its Studio URL connected to the current Run. Point to the passage, object or
+transition being discussed so the user can give concrete direction. Continue through settled choices;
+showing progress need not become an approval stop. Use the prepared production media and explain
+which passages are already composed. A rendered frame or clip remains useful when it answers the
+current question more directly.
+
+Check that the objects being discussed are recognizable and that their useful author choices are
+available. A successful preview establishes that the picture renders; the component's Companion
+establishes what the user can select and revise. [Companion authoring](studio-companions.md) explains
+this view of the same Source, including generic fallback and project-defined families.
+
+## Revise from timestamped Comments
+
+Open Comments directly when the user wants to point at a moment and describe a change.
+It gives the same composition a larger player and a comment column. A change of visual style,
+choreography or graphic structure often needs authored code or direction, while a position or color
+may fit an Inspector field. Both are ordinary collaboration: Comments carries the desired result,
+and the Agent chooses the owning Source, Recipe, component or material decision to change.
+
+Comments live in `FEEDBACK.json` at the project workspace root. Read the entries for the reviewed Run
+and the open notes before revising. Each entry has a stable `id`, workspace-relative `run`, `at` in
+seconds, `text`, and optional `resolved` (false when omitted). For example:
+
+```json
+{"comments":[{"id":"opening-title","run":"runs/render.svrun","at":1.5,
+"text":"Give the title a softer pink and a stronger offset shadow.","resolved":false}]}
+```
+
+The UI displays notes in time order; its `#` labels follow submission order within that Run. Identify
+file edits by `id` and preserve the array order and unrelated entries. Clicking a note seeks to its
+saved time. Interpret that time with its words and the reviewed composition: changing Script or Take
+placement can move the intended event. Comments retain the reviewed seconds rather than silently
+following new semantic timing.
+
+Explain the changes you will make, apply them to their owning facts, and inspect the affected passage
+and handoffs. Mark the addressed notes `resolved: true`; a note can be reopened with false. Both the
+user and Agent can edit this file, and Studio observes saved changes. Read the current file before
+writing so newly added comments survive. Retain useful directing decisions in Treatment or Progress;
+comments remain the concrete review conversation.
+
+Send saves a comment. Agent notification is not connected yet; when the user asks for another review
+pass, read the latest file. [Composition review](review.md) explains the judgment, and
+[project files](../creation/project-files.md) owns the production's durable memory.
+
+## Review before export
+
+For visual inspection, use [snapshot](snapshots.md) on this session first. It reads the current
+compiled programme and selected resources, captures exact original frames, and writes PNGs with
+optional grids. Studio remains the interactive view for playback, sound and editing.
+
+
+When the composition is substantially ready and the user can access it, open the current Run at
+`#comments` for discussion and introduce Comments and Studio together. Comments lets the user
+pause and leave direction at a time; Studio shows the timeline, component relationships and exposed
+parameters they can adjust. Both views stay with the same work and playhead. Browser playback does not render an MP4,
+create an export Build or save frame sequences. It can therefore show real material and animation
+while avoiding a full encode for changes the user is still choosing. Use Studio's other view for
+Inspector or timeline edits, and an encoded frame or clip when that evidence is needed.
+
+Introduce the review in the user's language: explain what is ready, invite timestamped comments,
+and say whether export is waiting for their review or already covered by their request. For example:
+“I've opened the editable video. You can pause and leave timestamped notes in Comments, or switch
+to Studio to explore the timeline and adjust available parameters. When you're happy with it,
+I can export the video.” This is a collaboration choice, not a mandatory
+approval stage. A user who has asked for final export has already chosen that step.
+
+A first-time reviewer may benefit from one short welcome note at the relevant time, saved with
+`resolved: true`. Write it explicitly as the Agent's invitation, such as “You can pause here and
+leave a note about anything you'd like changed.” It demonstrates the file workflow without adding
+an unfinished production task or pretending that the user requested a change. Keep this optional
+and specific to the collaboration; existing comments need no repeated welcome.
+
+Once export is wanted, reuse the accepted material in a Build, retrieve its completed video and
+check that encoded deliverable. [Rendering](rendering.md) and [Builds](builds.md) own that execution.
+Comments is a review view of the editable work; the exported file is the deliverable.
+
+## Show the finished work
+
+Alongside the delivered video, a brief look at its editable production can make the handoff more
+tangible. When Studio is readily accessible to the user, open the finished work and share the session
+URL. Use a Run that reuses the completed media and SemanticTakes while keeping its Tracks and Recipes
+available for editing. Reuse a suitable existing session or launch one as described above.
+
+Point out something specific to this piece: a reveal tied to a word, the Caption styling, or a
+component parameter they can adjust. Let the actual work demonstrate the editing experience. For a
+remote user, a readily available screenshot or short recording can provide the same introduction.
+[Project handoff](../creation/project-files.md#hand-over-an-editable-production) explains what to
+include when the user wants to continue editing on another machine.
+
+## Read the different views
+
+| 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 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, its declared read-only facts and adjustable fields, organized under Where, When and How 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.
+The time ruler and its Segment, Word and Selection/Moment bands form one pinned Timeline area.
+Empty information bands are omitted; a work without Segments keeps the ordinary time ruler.
+Select an overlapping object to bring it forward, or right-click the overlap to choose one covered
+by its peers. This changes editor selection, not the composition.
+
+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
+previous view and displays the error. Multiple references to one stored file share a media card;
+its source details retain the originating Builds and Outputs. Highlighted Outputs appear first.
+Names show up to two lines. Double-click a name or press F2 to edit; Enter or leaving the field
+saves, and Escape cancels. Renaming changes the displayed Output name in the finished Result,
+not its reference identifier or media file.
+
+Use [Builds and Results](builds.md) to inspect Output names, export media, finish an incomplete Result,
+edit Result presentation metadata or select an earlier Output. Studio reads the same project Result
+repository. With no Runtime selected, finished Results remain accessible; preview works when its
+display closure needs no unresolved Endpoint work. Active Runtime status and transient Endpoint
+processing require the selected environment.
+
+Studio opens the selected work for interactive playback and editing. It creates no Build and submits
+no paid generation. It can evaluate deterministic Producers and the exact immediate capabilities a
+Provider permits for transient authoring, such as media inspection and normalization. Select existing
+files or produced Outputs through the Run for the material the view needs. If a required generation
+is still running, continue component work and open its resulting composition when the material is ready.
+
+[Runs](runs.md) explains selection and reuse. [Snapshots](snapshots.md) captures the current picture
+directly with `hypit snapshot --studio <this-studio-url>`. [Rendering](rendering.md) provides frame-range Builds
+for inspecting the composition as encoded media; choose the view that helps answer the current question.
+
+## Edit the owning Source fact
+
+Inspector fields and timeline handles write back to actual Source endpoints. A field can live in a
+referenced Frame, Style or SVS Recipe rather than on the selected Track tag. Editing a shared Recipe
+changes every consumer that uses it; create and select a separate authored instance when the design
+needs independent variation. Lists and records save their complete validated value when editing ends. Required fields that are
+still incomplete remain in the editor with a completion hint. Check save status and the resulting preview.
+
+Where groups position, size, fitting and layout. When groups timing, playback, trims and motion.
+How groups content, typography, color, effects and audio levels. Components name their own pages
+and sections within these questions. Numeric units sit outside the editable value: a width authored
+as `78%` keeps `%` when edited, while a fractional opacity may display as a percentage and write
+back as a fraction. Dropdowns can have readable option names and previews; their underlying value
+is what the Source receives. Color fields support exact hex values and suggested swatches.
+
+For catalog fonts, Caption, Typography and Ranking can expose the primary font family's dropdown
+through the selected Style. It edits the shared font declaration; its weight and style must be
+available in the chosen family. A local font continues to use its exact file. A project component
+can offer its own font or preset choices through Companion fields.
+
+Timeline's placed Takes and complete extent provide reference information. Edit their `at` and
+`end` declarations in Source when their placement should change. Presentation handles edit Uses
+or component events; they do not move Takes or adjust Canvas dimensions implicitly.
+
+Timing edits follow the authored relationship. A direct Selection or Moment edits that identity
+in Script; a quoted expression edits its local clock value or offset; a duration changes independently.
+[Timing and edit behavior](timing.md#choose-what-a-later-edit-changes) gives the complete forms,
+affinity choices and shared-consumer consequences. Marker moves preserve unrelated prose whitespace. With unchanged spoken tokens and identities,
+new marker references can use the existing Take's anchor times. [Reuse boundaries](authoring.md#reuse-produced-work-explicitly)
+explain when to retain prepared Takes and when to retain only their upstream media.
+
+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.
+Composition edits return to the ordinary Sources; they do not create a second Studio project.
+
+## Give a project component a useful Companion
+
+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.