@vosjs/studio-core 0.4.0 → 0.5.0

package/README.md

@@ -1,69 +1,86 @@
-# @vosso/studio-core
+# @vosjs/studio-core
 
-The studio's editing model. This package holds the product opinions that turn a raw
-screen recording into an editable, re-renderable video: the `ProjectDoc` schema,
-the element-aware auto-zoom planner, and the lowering that compiles a doc down to
-a vos composition.
+> The document model of a screen recording: the `ProjectDoc` schema, the planners that read a cursor track (auto-zoom, speed, tilt), the digest that lets an agent see a recording, and the lowering from a document to a vos program.
 
-It is pure logic — no DOM, no React, no vos-render dependency. The generic
-editing mechanisms (patch store, edit classifier, editor-bridge client, timeline
-view-model) live in the open-source [`@vosjs/editor`](https://www.npmjs.com/package/@vosjs/editor);
-what stays here is studio-specific. Consumed in-source by the vosso web app and bundled
-into [`@vosso/vos-plugin`](../vos-plugin). MIT.
+[![npm](https://img.shields.io/npm/v/@vosjs/studio-core.svg)](https://www.npmjs.com/package/@vosjs/studio-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/vosjs/vos/blob/main/LICENSE)
+
+Part of [vos](https://github.com/vosjs/vos), the open programmatic video engine behind [vos.so](https://vos.so). This package holds the opinions that turn raw footage plus a cursor track into an editable, re-renderable video. It is pure logic: no DOM, no React, no engine import at run time (`@vosjs/core` is a peer for types). The generic editing mechanics (patch store, edit classifier, bridge client, view-model math) live in [`@vosjs/editor`](../editor); the time math in [`@vosjs/timeline`](../timeline). The `vos` CLI and the vos.so studio both build on this package, so a document cut on the command line opens in the studio with every span intact.
+
+## Install
+
+```bash
+pnpm add @vosjs/studio-core
+```
 
 ## The pipeline
 
 ```
-RecordingArtifact ──projectFromArtifact──▶ ProjectDoc ──lowerToComposition──▶ { config, data, duration }
-   (footage +          (normalize capture      (editable       (constant program +
-    cursor track)       space, plan zoom)        document)       ctx.data — live edits)
+RecordingArtifact ──projectFromArtifact──▶ ProjectDoc ──lowerStudioDoc──▶ { config, data, stack, duration }
+ (footage + cursor track)   normalize capture space,   (doc.json: the      constant program + ctx.data,
+                            plan zoom / speed / tilt    editable surface)   so every edit is live
 ```
 
-- **`projectFromArtifact(artifact)`** — build the initial `ProjectDoc` from a
-  recording: normalize the capture space (`normalizeCaptureSpace`, viewport crop
-  for window takes), then seed auto-zoom.
-- **`planAutoZoom(doc, options)`** — element-aware zoom planner. Emits
-  `source: 'auto'` spans from click/dwell clusters; honors the wand contract
-  (never touches `source: 'manual'` spans). Camera dynamics come from a named
-  style preset (`ZOOM_STYLES` — glide / focus / cinema / snappy / cut).
-- **`lowerToComposition(doc)`** — lower the doc to a **constant** vos program
-  plus a `ctx.data` payload. Zoom spans expand into an output-time keyframe
-  track; trims, speed, cursor follow, click effects, and audio envelopes all bake
-  into `data`. Because the program string is constant, edits replay live via
-  `SET_DATA`/`SET_DURATION` — nothing recompiles for a retime or a zoom tweak.
-
-## Key exports
-
-| Area           | Exports                                                                                                                       |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Ingest         | `projectFromArtifact`                                                                                                         |
-| Capture space  | `normalizeCaptureSpace`, `deriveViewportCrop`, `docToCropSpace`, `docToFullSpace`, `CAPTURE_COVERAGE_MIN`, `WINDOW_FOCUS_MIN` |
-| Planner        | `planAutoZoom`, `smoothCursor`                                                                                                |
-| Zoom styles    | `ZOOM_STYLES`, `DEFAULT_ZOOM_STYLE`, `resolveZoomStyle`                                                                       |
-| Lowering       | `lowerToComposition`, `zoomTrackFromDoc`, `followFocusEvents`, `extractClicks`, `ratedSegments`                               |
-| Layout / focus | `computeCardLayout`, `docCardLayout`, `focusBounds`, `clampFocus`, `recommendedExportResolution`                              |
-| Audio          | `clipEnvelope`, `duckCurve`, `computePeaks`, `computeMicRms`                                                                  |
-| Timeline lanes | `zoomLane`, `speedLane`, `camLane`, `audioLane`, `videoLane`                                                                  |
-
-See [`src/types.ts`](src/types.ts) for the full `ProjectDoc` shape.
+- **`projectFromArtifact(artifact, videoUrl, { frame? })`** builds the initial `ProjectDoc` from a recording: normalize the capture space (`normalizeCaptureSpace`; a viewport crop for window takes via `deriveViewportCrop`, fail-closed below `CAPTURE_COVERAGE_MIN`), then seed the automatic spans. Returns `{ doc, videoUrl }`.
+- **The planners** read the cursor track, never the pixels. `planAutoZoom(track, { width, height, style?, params? })` emits `source: 'auto'` zoom spans from click clusters (`z…`), typing sessions (`k…`) and dwells (`d…`); `planAutoSpeed` proposes speed-ups over idle gaps and scroll runs; `planAutoTilt` leans the card toward each zoom's focus. Every planner honors the wand contract: `source: 'manual'` spans are never touched, and a deleted proposal stays deleted (`rejectSpan` writes `doc.rejected`, `isRejected` filters the next plan).
+- **`lowerStudioDoc(doc)`** lowers a document to a constant vos program plus a `ctx.data` payload. Zoom, tilt and cam-motion spans expand into output-time keyframe tracks; trims, speed, cursor follow, click effects and audio envelopes all bake into data. Because the program string is constant, edits replay live through `SET_DATA` and `SET_DURATION`; nothing recompiles for a retime or a zoom tweak. `lowerToComposition` is the recording-only path underneath it.
+
+## Two documents, one editor
+
+`StudioDoc = ProjectDoc | ProgramAnchorDoc`, discriminated on `source`. A `ProjectDoc` is a recording: footage, `segments` (the kept source spans), `zoom`, `speed`, `tilt`, `camMotion`, the frame and cursor styles, plus the shared layers. A `ProgramAnchorDoc` is a vos program that gained the same shared layers (text, image and video overlays, 3D objects, audio clips, speed spans, a tween-retime overlay) without those being written into its config. `anchorKindOf`, `isRecordingDoc` and `isProgramDoc` read the discriminator; `lowerProgramDoc` lowers the program kind. Hosted documents carry `docSchemaVersion` (`DOC_SCHEMA_VERSION`, currently 2) and are upgraded on read with `migrateHostedDoc`.
+
+The shared layers lower as one engine `stack` entry, `STUDIO_ENTRY_ID` (`'vosso.studio'`), with its own data (`studioLayerData`), so either document kind hosts them and the engine's `SET_DATA { target }` updates them alone. `studioAudioPlan` turns the entry's audio clips and duck curve into the plan `@vosjs/core/audio` mixes.
+
+## Time and space conventions
+
+- **Seconds everywhere.** Zoom, speed, tilt and cam-motion spans and the cursor samples are anchored in source time, so they follow footage through trims. Overlays, audio clips and click effects are anchored in output time, so a title keeps its perceived length through a speed change. `ratedSegments`, `effectiveSegments`, `docOutputDuration` and `outputRangeToSource` are the remaps.
+- **Normalized coordinates.** A zoom's `cx`/`cy` and an overlay's `transform.x`/`y` are fractions of the frame in `[0, 1]`, never pixels, so a document survives an aspect-ratio switch. `focusBounds` and `clampFocus` keep a focus inside the card at a given `level`.
+- **Camera styles.** `ZOOM_STYLES` names eight camera personalities (`glide`, the default, then `focus`, `cinema`, `snappy`, `cut`, `keynote`, `drift`, `none`); a style parametrizes both the planner and the camera motion, and `doc.zoomParams` layers per-document overrides.
+- **The stage.** `CARD_FOV`, `CARD_Z`, `OVERLAY_Z`, `BACKGROUND_Z` and `planeSizeAtDepth` define the frustum-filling planes the program draws (background, the tiltable card, the overlay); `computeCardLayout` and `docCardLayout` are the host-side mirror of the program's card math, pinned to it by tests.
+- **Backdrops.** `withBackdrop(frame, backdrop)` and `backdropMedia` put a looping video or a still behind the card, output-anchored modulo its duration. The package carries the mechanism and `BASE_FRAME_STYLE`; which loop a host opens on is the host's choice.
+
+## Seeing a recording: the digest
+
+`momentsFromDoc`, `sceneChanges` and `buildDigest` derive the moments of a recording from its cursor track (click clusters, typing sessions, scroll runs, dwells, idle gaps, head, tail, frame-diff scene changes), each with source and output extents, a normalized focus rectangle a zoom span can copy, and the ids of the planner's proposals over it. `zoomCoversRect` and `zoomWindow` are the framing lint that closes the loop. The CLI's `vos digest` writes it as `digest.json` beside footage frames and crops; `STYLE_FIELDS`, `copyStyle` and `pickStyle` carry a signed-off document's look onto the next take.
+
+## Destinations
+
+`DESTINATIONS` is the table of launch destinations (store listings, Product Hunt, social, OG cards, README loops) with exact pixel sizes, byte and duration ceilings, generated from `channel-specs.json` in `@vosjs/cli` and hash-gated by a test. `destinationById`, `destinationsForChannel`, `exportSizeFor(ratio, resolution)` and `resolveExportSize` size an export; `ExportResolution` is `720p | 1080p | 2k | 4k`.
+
+## Exports by area
+
+| Area           | Exports                                                                                                                                                                                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Ingest         | `projectFromArtifact`, `normalizeCaptureSpace`, `deriveViewportCrop`, `docToCropSpace`, `docToFullSpace`, `CAPTURE_COVERAGE_MIN`, `WINDOW_FOCUS_MIN`                                                                                                              |
+| Document       | `StudioDoc`, `ProjectDoc`, `ProgramAnchorDoc`, `anchorKindOf`, `isRecordingDoc`, `isProgramDoc`, `DOC_SCHEMA_VERSION`, `migrateHostedDoc`, `DEFAULT_FRAME_STYLE`, `BASE_FRAME_STYLE`, the constants (`ZOOM_LEVELS`, `TILT_DEG_MAX`, …)                            |
+| Planners       | `planAutoZoom`, `planAutoSpeed`, `planAutoTilt`, `smoothCursor`, `idleGaps`, `scrollRuns`, `rejectSpan`, `isRejected`, `withoutRejected`                                                                                                                          |
+| Camera styles  | `ZOOM_STYLES`, `ZOOM_STYLE_OPTIONS`, `DEFAULT_ZOOM_STYLE`, `resolveZoomStyle`                                                                                                                                                                                     |
+| Lowering       | `lowerStudioDoc`, `lowerProgramDoc`, `lowerToComposition`, `zoomTrackFromDoc`, `tiltTrackFromDoc`, `camTrackFromDoc`, `motionTrack`, `followFocusEvents`, `extractClicks`, `cursorIdleFade`, `ratedSegments`, `STUDIO_ENTRY_ID`, `studioEntry`, `studioLayerData` |
+| Layout         | `computeCardLayout`, `docCardLayout`, `focusBounds`, `clampFocus`, `camBubbleRectAt`, `overlayRect`, `overlayHit`, `CARD_FOV`, `CARD_Z`, `planeSizeAtDepth`, `recommendedExportResolution`                                                                        |
+| Text           | `TEXT_PRESETS`, `OVERLAY_FONT_FACES`, `resolveOverlayStyle`, `resolveOverlayBox`, `resolveText3dAsset`                                                                                                                                                            |
+| Audio          | `studioAudioPlan`, `clipEnvelope`, `duckCurve`, `computePeaks`, `computeMicRms`, `voiceKey`, `musicBedClip`, `refillAudioBeds`                                                                                                                                    |
+| Backdrops      | `withBackdrop`, `backdropMedia`                                                                                                                                                                                                                                   |
+| Digest         | `momentsFromDoc`, `planForDigest`, `buildDigest`, `sceneChanges`, `zoomCoversRect`, `zoomWindow`, `cropBox`, `frameGeometry`, `STYLE_FIELDS`, `copyStyle`, `pickStyle`, `DIGEST_VERSION`                                                                          |
+| Destinations   | `DESTINATIONS`, `destinationById`, `destinationsForChannel`, `exportSizeFor`, `resolveExportSize`, `ASPECT_RATIOS`                                                                                                                                                |
+| Timeline lanes | `videoLane`, `micLane`, `camLane`, `zoomLane`, `tiltLane`, `camMoveLane`, `speedLane`, `overlaysLane`, `objectsLane`, `audioLane`; range actions `outputRangeToSource`, `removeSourceRange`, `setSpeedInRange`, `zoomSpanForRange`                                |
+
+The full document shape is in [`src/types.ts`](src/types.ts); the JSON Schema that ships to users is [`doc.schema.json`](../cli/schema/doc.schema.json) in `@vosjs/cli`.
 
 ## Design rules
 
-- **Never bake doc values into the program string.** The program is a structural
-  hash; all editable state travels in `ctx.data`. Baking values breaks live editing.
-- **Lowering is deterministic.** No stateful springs or wall-clock — `seek(t)` must
-  be a pure function of `t`, so cursor follow, click effects, and zoom are all
-  computed from the doc up front.
-- **Source-anchored spans.** Zoom and speed spans are anchored in source time and
-  follow footage through trims; the lowering remaps them to output time.
+- **Never bake a document value into the program string.** The program is a structural hash; all editable state travels in `ctx.data`. Baking a value breaks live editing.
+- **Lowering is deterministic.** No stateful springs, no wall clock: `seek(t)` is a pure function of `t`, so cursor follow, click effects and zoom are computed from the document up front.
+- **Perception reads the recording, never the composition.** The planners and the digest read the cursor track and the footage; they never inspect a rendered frame.
 
 ## Development
 
 ```bash
-pnpm --filter @vosso/studio-core test       # vitest
-pnpm --filter @vosso/studio-core typecheck
+pnpm --filter @vosjs/studio-core test
+pnpm --filter @vosjs/studio-core typecheck
 ```
 
-The `__tests__` suite pins the invariants that are easy to break — capture-space
-fail-closed matrix, zoom keyframe expansion, click extraction, layout↔ON_FRAME
-parity. Extend them when touching lowering.
+The test suite pins the invariants that are easy to break: the capture-space fail-closed matrix, zoom keyframe expansion, click extraction, layout-to-program parity, byte-identical lowering when a feature is absent, and the destinations hash. Extend it when touching the lowering.
+
+## License
+
+[MIT](https://github.com/vosjs/vos/blob/main/LICENSE) © vosso

package/dist/index.d.ts

@@ -180,6 +180,15 @@ declare function isPlayback(activity: readonly number[] | null | undefined, a: n
  * these types are intentionally generic so the core stays extraction-ready.
  */
 
+/**
+ * A kept span with an optional HOLD: after its last frame, a freeze for
+ * `hold` output seconds (the beat before a cut, the ground for the end
+ * card). Lowered as a rated segment whose tiny source span plays for the
+ * hold, so every consumer of the rated list inherits it.
+ */
+type DocSegment = Segment & {
+    hold?: number;
+};
 /** A single input event captured in the page, relative to the recording's t0. */
 interface CursorEvent {
     /** ms since t0 (recording start). */
@@ -810,8 +819,40 @@ interface FrameStyle {
     backgroundMedia?: BackgroundMedia | null;
     padding: number;
     radius: number;
-    /** shadow strength 0..1. */
+    /**
+     * Ambient shadow strength 0..1: the wide, soft layer under the card
+     * (blur 60, offset 24 design px). The look presets set it with
+     * `shadowContact`; every existing doc keeps its single layer.
+     */
     shadow: number;
+    /**
+     * Contact shadow strength 0..1: a second, tight layer (blur 10, offset 3
+     * design px) drawn over the ambient one. It is what makes a light card sit
+     * on a light ground, where a wide soft shadow alone reads as haze. Absent
+     * = 0 (no second layer; byte-identical to before the field existed).
+     */
+    shadowContact?: number;
+    /**
+     * Shadow colour as a `#rrggbb` hex; the strengths are its alpha. Absent =
+     * black. A dark look lifts it toward its accent so the card glows instead
+     * of sinking.
+     */
+    shadowColor?: string;
+    /**
+     * Per-side card placement as FRACTIONS of the frame (left/right of its
+     * width, top/bottom of its height), each overriding `padding` on its side
+     * when present. A negative side BLEEDS the card past the frame edge (the
+     * feature-clip grammar: headroom above, the window running off the
+     * bottom). Absent sides keep `padding`, so every existing doc is untouched.
+     * Under contain the card centres inside the inset area; under cover the
+     * inset area IS the card.
+     */
+    inset?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
     /** stroke around the card, 0..1 alpha (0 = off). The switch AND the opacity. */
     border: number;
     /**
@@ -850,6 +891,43 @@ interface FrameStyle {
      * as the zoom camera moves (depth cue). 0/absent = static.
      */
     parallax?: number;
+    /**
+     * How the card ENTERS at t = 0 (the feature-clip grammar: no clip opens
+     * on a static, centred, flat window). `tilt-in` swings in from a
+     * perspective pose while the card settles up and in; `pull-out` opens
+     * zoomed in and pulls out; `rise` settles up and in flat. Lowered into
+     * the tilt or zoom track's head and a card-pose track, so the card's only
+     * rotation is still the tilt track. Absent = none, byte-identical.
+     */
+    entrance?: FrameEntrance;
+    /**
+     * Under `fit:'cover'`, follow the zoom track's focus with the crop
+     * (`'camera'`), so a 9:16 cut of a 16:9 take keeps the affordance in
+     * frame instead of the centre. Absent = `focus` (or the centre).
+     */
+    focusFollow?: 'camera';
+}
+interface FrameEntrance {
+    kind: 'tilt-in' | 'pull-out' | 'rise' | 'none';
+    /** Seconds to settle (default 1.2, clamped 0.2..3). */
+    seconds?: number;
+}
+/**
+ * The end card: the last frame holds for `seconds` while the card recedes
+ * and the words rise over it (the house title, caption and label presets,
+ * so they lower like any overlay). The clip's last frame is its poster.
+ */
+interface EndCard {
+    seconds?: number;
+    headline?: string;
+    sub?: string;
+    wordmark?: string;
+    /**
+     * The words' colour (any CSS colour). The house presets are white for
+     * footage; over a light plate the brand's ink is what reads. Absent =
+     * the presets' own.
+     */
+    ink?: string;
 }
 /**
  * Overlay clips (compositor v2: "elements-shaped data"). Screen-
@@ -1216,7 +1294,7 @@ interface ProjectDoc {
      * their concatenation — trim/split/cut are all segment edits. Canonical form
      * is one full-source segment; an empty list is tolerated and means "untrimmed".
      */
-    segments: Segment[];
+    segments: DocSegment[];
     /**
      * Speed-change spans (SOURCE time, footage-anchored — see SpeedSpan).
      * Optional for backward compatibility with persisted docs; absent = all 1×.
@@ -1287,6 +1365,12 @@ interface ProjectDoc {
      * Card presentation (tilt / entrance) — compositor v2. Optional: absent
      * lowers byte-identically to a pre-v2 doc and renders pixel-identically.
      */
+    /**
+     * The end card the clip closes on: a hold on the last frame, the card
+     * receding, the words rising. Absent = the clip ends where the footage
+     * ends.
+     */
+    endCard?: EndCard;
     /**
      * Screen-space overlay clips (text; later image/video) — compositor v2.
      * OUTPUT-anchored spans on the overlay layer. Optional: absent lowers
@@ -1792,7 +1876,15 @@ interface CardLayout {
 declare function computeCardLayout(frame: FrameStyle, video: {
     width: number;
     height: number;
-}, W: number, H: number): CardLayout;
+}, W: number, H: number, 
+/**
+ * The zoom track's current focus, for a frame whose cover crop FOLLOWS
+ * the camera (`focusFollow: 'camera'`); absent = the frame's own focus.
+ */
+zoomFocus?: {
+    cx: number;
+    cy: number;
+}): CardLayout;
 /**
  * The doc's card layout at design size (H = 1080, W from the output aspect).
  * All layout terms scale linearly with the canvas at a fixed aspect, so the
@@ -2316,7 +2408,7 @@ declare function studioLayerData(layers: {
     objects?: ObjectClip[];
     audio?: AudioClip[];
 }, duration: number): Record<string, unknown>;
-declare function lowerToComposition(doc: ProjectDoc): LoweredComposition;
+declare function lowerToComposition(input: ProjectDoc): LoweredComposition;
 
 /**
  * ONE lowering for the document family: the anchor's program
@@ -2402,10 +2494,31 @@ interface Destination {
     accepts: string;
     /** How footage meets an off-ratio frame (a still fills, a video letterboxes). */
     fit: 'contain' | 'cover';
+    /**
+     * The destination's word policy: 'none' = the picture carries it alone (a
+     * tile, a store screenshot), 'allowed', 'expected' = a card that should
+     * say something. The picture checks read it.
+     */
+    text: 'none' | 'allowed' | 'expected';
+    /**
+     * The rect, as fractions of the frame, every text box must sit inside:
+     * the platform's own chrome or crop covers the rest.
+     */
+    safe: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * The poster template a card destination renders from by default (the
+     * family that ships with the CLI); absent on screenshots and videos.
+     */
+    template?: string;
     notes: string;
 }
 declare const CHANNEL_SPECS_VERIFIED = "2026-08-04";
-declare const CHANNEL_SPECS_HASH = "7a3ad4301f96507ec471a35fa37f367dcaf4bd405b008f551d0ac4cd395d61f7";
+declare const CHANNEL_SPECS_HASH = "e48926c22737b5dfaabf5cb33916a50a5eccd4b93498c2059a1468bd963a0a86";
 declare const DESTINATIONS: Destination[];
 declare function destinationById(id: string): Destination | undefined;
 declare function destinationsForChannel(channel: string): Destination[];
@@ -2505,6 +2618,145 @@ declare const AUDIO_PLAN_STEP: number;
 declare function envelopeAt(env: readonly EnvelopePoint[], t: number, def: number): number;
 declare function studioAudioPlan(clips: readonly LoweredAudioClip[], duckEnv: readonly EnvelopePoint[], duration: number, step?: number): StudioAudioPlan;
 
+/**
+ * A LOOK is how the card is presented: the ground it sits on, how much of
+ * the frame it takes, the shadow that makes it an object, the stroke that
+ * separates a light card from a light ground. Three house looks cover the
+ * feature-clip and poster grammar the premium tools default to (a cream
+ * plate with a soft wide shadow; a warm gradient; a near-black plate with a
+ * light streak and a glow), and a maker's brand kit resolves to one of them
+ * with its own colours. Pure: a look resolves to `FrameStyle` fields, so
+ * every renderer and every still reads the same placement.
+ */
+
+type LookKind = 'plate' | 'gradient' | 'dark';
+/**
+ * Where the card goes. `hero` is the feature-clip grammar: the card at
+ * ~84% of the width with headroom above and its bottom edge running off
+ * the frame ("this continues"). `card` is the poster grammar: the card
+ * centred on the ground with even room around it; on a frame too wide to
+ * hold the whole card it falls back to `hero`.
+ */
+type LookPlacement = 'hero' | 'card';
+interface Look {
+    kind: LookKind;
+    /** CSS ground painted under the card (a colour or a gradient). */
+    ground: string;
+    /** The card's width as a fraction of the frame. */
+    cardWidth: number;
+    /** Room above the card in the hero placement, a fraction of the height. */
+    headroom: number;
+    /** Corner radius in design px. */
+    radius: number;
+    /** Ambient shadow 0..1. */
+    shadow: number;
+    /** Contact shadow 0..1. */
+    shadowContact: number;
+    /** `#rrggbb`; absent = black. */
+    shadowColor?: string;
+    /** Hairline stroke alpha 0..1 (0 = none). */
+    border: number;
+    borderColor?: string;
+}
+/** The frontmatter roles a brand kit carries that a look reads. */
+interface LookBrand {
+    look?: string | null;
+    ground?: string | null;
+    bgA?: string | null;
+    bgB?: string | null;
+    bgC?: string | null;
+    accent?: string | null;
+    ink?: string | null;
+}
+/** The house coral, the ground every take opened on before looks existed. */
+declare const HOUSE_GRADIENT = "linear-gradient(135deg, #ff5148, #ffb03a)";
+/** The Chrome feature-clip plate, measured on three clips. */
+declare const PLATE_GROUND = "#f0f2f4";
+/** Near-black with a warm light streak from the top right. */
+declare const DARK_GROUND = "radial-gradient(ellipse at 82% 0%, #2a1d16, #07080b)";
+declare const LOOK_KINDS: LookKind[];
+declare function isLookKind(v: unknown): v is LookKind;
+/** One of the three house looks, copied. */
+declare function houseLook(kind: LookKind): Look;
+/**
+ * Which house look a site's own ground asks for: a paper site is a plate, a
+ * dark site is dark, anything else takes the gradient. What `vos brand`
+ * writes as the `look` role, so an outside maker never gets the house coral
+ * by accident.
+ */
+declare function lookKindForGround(bgA: string | null | undefined): LookKind;
+/**
+ * Resolve a brand kit to a look: the `look` role picks the kind (else the
+ * site's ground decides), `ground` overrides the ground outright, and the
+ * kit's colours colour the house look (plate = bgB, gradient = accent →
+ * bgC, dark = bgA with a lifted shadow). A kit with none of them is the
+ * house look unchanged.
+ */
+declare function lookFromBrand(brand: LookBrand | null | undefined): Look;
+/**
+ * The card's per-side inset for a frame of `frameW:frameH` holding footage
+ * of `videoW:videoH` under contain fit, as fractions of the frame. Card
+ * height follows from the width (contain keeps the footage aspect): a card
+ * that fits is centred (`card`) or given headroom (`hero`); one taller than
+ * the frame bleeds off the bottom by at least 2%, the feature-clip cue.
+ */
+declare function cardInset(look: Pick<Look, 'cardWidth' | 'headroom'>, frame: {
+    w: number;
+    h: number;
+}, video: {
+    w: number;
+    h: number;
+}, placement: LookPlacement): NonNullable<FrameStyle['inset']>;
+/**
+ * Apply a look to a frame for one output size and placement: the ground,
+ * the inset, the radius, both shadow layers and the hairline. The bar and
+ * the media layer are the document's own (a look presents the card, it
+ * does not decide what chrome the card wears). `fit` is forced to contain,
+ * because the card IS the footage's aspect under a look.
+ */
+declare function applyLook(frame: FrameStyle, look: Look, size: {
+    w: number;
+    h: number;
+}, video: {
+    w: number;
+    h: number;
+}, placement: LookPlacement): FrameStyle;
+
+/** The entrance's default length, seconds. */
+declare const ENTRANCE_SECONDS = 1.2;
+/** The end card's default length, seconds. */
+declare const END_CARD_SECONDS = 2.5;
+declare function entranceSeconds(e: FrameEntrance | null | undefined): number;
+/**
+ * The rated segments with every `hold` expanded: after the last rated
+ * piece of a held segment, a freeze piece whose tiny source span at the
+ * segment's end plays for `hold` output seconds. Every consumer of the
+ * rated list (mapTime, the zoom remap, the audio splice, the duration)
+ * inherits the hold from this one seam.
+ */
+declare function withHolds(docSegments: readonly (Segment & {
+    hold?: number;
+})[], rated: Segment[]): Segment[];
+/**
+ * The card-pose track [scale, dy, opacity] in OUTPUT seconds: the entrance
+ * settles the card in from a slightly smaller, lower, transparent pose;
+ * the end card recedes it under the words. Undefined when neither
+ * exists, so a doc without them lowers byte-identically.
+ */
+declare function cardPoseTrack(e: FrameEntrance | null | undefined, endStart: number | null, endSeconds: number): KeyframeTrack<number[]> | undefined;
+/**
+ * A doc with its end card expanded: the last segment holds for the card's
+ * seconds and the card's words ride as OUTPUT-anchored text overlays over
+ * the receding footage (the house presets, so they resolve at lowering like
+ * any title). Returns the output second the card starts at, for the pose
+ * track. A doc with no end card comes back as itself.
+ */
+declare function expandEndCard(doc: ProjectDoc, outputDuration: number): {
+    doc: ProjectDoc;
+    endStart: number | null;
+    seconds: number;
+};
+
 /**
  * Compositor v2 — the layer stage geometry.
  *
@@ -3064,4 +3316,4 @@ declare function rejectSpan(rejected: RejectedSpan[] | undefined, lane: Rejected
     anchor?: StepAnchor;
 }, note?: string): RejectedSpan;
 
-export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CAMERA_FAR, CAMERA_NEAR, CAM_CHAIN_GAP, CAM_EASE, CAM_PAN, CAM_PAN_EASE, CAM_RAMP_IN, CAM_RAMP_OUT, CAM_SIZE_MAX, CAM_SIZE_MIN, CAM_SPAN_MIN, CAPTURE_COVERAGE_MIN, CARD_FOV, CARD_Z, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CROP_MAX_PX, CROP_MIN_FRAC, CROP_MIN_PX, CROP_PAD, CURSOR_IDLE_EPS_FRAC, CURSOR_IDLE_FADE_IN, CURSOR_IDLE_FADE_OUT, CURSOR_IDLE_HOLD, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CaptureNormalization, type CardLayout, type ClickFxStyle, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DEFAULT_BROWSER_BAR, DEFAULT_CAM_POSE, DEFAULT_CAM_STYLE, DEFAULT_CLICK_FX, DEFAULT_CURSOR_STYLE, DEFAULT_DUCK, DEFAULT_FRAME_STYLE, DEFAULT_SPEED_PARAMS, DEFAULT_TILT_POSE, DEFAULT_ZOOM_LEVEL, DEFAULT_ZOOM_STYLE, DESTINATIONS, DIGEST_CROP_MAX, DIGEST_FULL_MAX, DIGEST_VERSION, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DuckOptions, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, type FocusBounds, type FollowEvent, type FollowOptions, type FrameGeometry, type FrameStyle, type IngestOptions, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type MediaOverlayClip, type MicRms, type MinimalBarTheme, type Moment, type MomentKind, type MomentsOptions, type MotionKey, type MotionPose, type MotionPose3D, type MusicBedInput, type NormRect, OBJECT_DEFAULT_SCALE, OVERLAY_FONT_FACES, OVERLAY_LINE_HEIGHT, OVERLAY_MEDIA_DEFAULT_RADIUS, OVERLAY_MEDIA_DEFAULT_WIDTH, OVERLAY_MIN_DURATION, OVERLAY_SCALE_MAX, OVERLAY_SIZE_MAX, OVERLAY_SIZE_MIN, OVERLAY_TRANSITION_DUR, OVERLAY_Z, type ObjectAnimation, type ObjectAsset, type ObjectClip, type ObjectPrimitiveShape, type OverlayClip, type OverlayFontFace, type OverlayKind, type OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PLAYBACK_ACTIVITY, PROGRAM_RETIME, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STUDIO_ENTRY_ID, STYLE_FIELDS, type SmoothOptions, type SmoothPoint, type SpeedParams, type SpeedSpan, type StepAnchor, type StepSpan, type StudioAudioPlan, type StudioDoc, type StudioEntry, type StyleField, TEXT3D_DEPTH_DEFAULT, TEXT3D_DEPTH_MAX, TEXT3D_DEPTH_MIN, TEXT_PRESETS, TILT_AUTO_DEAD_ZONE, TILT_AUTO_MIN, TILT_CHAIN_GAP, TILT_DEG_MAX, TILT_EASE, TILT_INTENSITY_MAX, TILT_PAN, TILT_PAN_EASE, TILT_RAMP_IN, TILT_RAMP_OUT, TILT_SPAN_MIN, TILT_UI_DEG_MAX, TRANSITION_SPEED_MULT, type Text3dMaterial, type TextFxDirection, type TextFxKind, type TextFxSpec, type TextFxUnit, type TextOverlayBox, type TextOverlayClip, type TextOverlayPreset, type TextOverlayStroke, type TiltPersonality, type TiltSpan, type TiltStyleName, type TranscriptSegment, type TransitionSpeed, WINDOW_FOCUS_MIN, ZOOM_CHAIN_GAP, ZOOM_EASE, ZOOM_LEVELS, ZOOM_LEVEL_MAX, ZOOM_LEVEL_MIN, ZOOM_PAN, ZOOM_PAN_EASE, ZOOM_RAMP_IN, ZOOM_RAMP_IN_OVERLAP, ZOOM_RAMP_OUT, ZOOM_SPAN_MIN, ZOOM_STYLES, ZOOM_STYLE_OPTIONS, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomWindow, anchorKindOf, anchorSourceDuration, aspectRatioValue, audioLane, backdropMedia, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cardPointToScreen, clampCamFrac, clampCamSize, clampFocus, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, computeCardLayout, computeMicRms, computePeaks, copyStyle, cropBox, cursorIdleFade, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docOutputDuration, docToCropSpace, docToFullSpace, duckCurve, effectiveSegments, envelopeAt, envelopeValueAt, expectedFrameSize, exportSizeFor, extractClicks, focusBounds, followFocusEvents, frameGeometry, hexToRgbTriplet, idleGaps, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, levelForFocusFraction, lowerProgramDoc, lowerStudioDoc, lowerToComposition, micLane, migrateHostedDoc, momentsFromDoc, motionTrack, musicBedClip, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayRect, overlaysLane, pageDisplayUrl, parsePoseId, pickStyle, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolveText3dAsset, resolveZoomStyle, sceneChanges, scrollRuns, setSpeedInRange, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, videoLane, voiceKey, withBackdrop, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomWindow };
+export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CAMERA_FAR, CAMERA_NEAR, CAM_CHAIN_GAP, CAM_EASE, CAM_PAN, CAM_PAN_EASE, CAM_RAMP_IN, CAM_RAMP_OUT, CAM_SIZE_MAX, CAM_SIZE_MIN, CAM_SPAN_MIN, CAPTURE_COVERAGE_MIN, CARD_FOV, CARD_Z, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CROP_MAX_PX, CROP_MIN_FRAC, CROP_MIN_PX, CROP_PAD, CURSOR_IDLE_EPS_FRAC, CURSOR_IDLE_FADE_IN, CURSOR_IDLE_FADE_OUT, CURSOR_IDLE_HOLD, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CaptureNormalization, type CardLayout, type ClickFxStyle, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DARK_GROUND, DEFAULT_BROWSER_BAR, DEFAULT_CAM_POSE, DEFAULT_CAM_STYLE, DEFAULT_CLICK_FX, DEFAULT_CURSOR_STYLE, DEFAULT_DUCK, DEFAULT_FRAME_STYLE, DEFAULT_SPEED_PARAMS, DEFAULT_TILT_POSE, DEFAULT_ZOOM_LEVEL, DEFAULT_ZOOM_STYLE, DESTINATIONS, DIGEST_CROP_MAX, DIGEST_FULL_MAX, DIGEST_VERSION, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocSegment, type DuckOptions, END_CARD_SECONDS, ENTRANCE_SECONDS, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EndCard, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, type FocusBounds, type FollowEvent, type FollowOptions, type FrameEntrance, type FrameGeometry, type FrameStyle, HOUSE_GRADIENT, type IngestOptions, LOOK_KINDS, type Look, type LookBrand, type LookKind, type LookPlacement, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type MediaOverlayClip, type MicRms, type MinimalBarTheme, type Moment, type MomentKind, type MomentsOptions, type MotionKey, type MotionPose, type MotionPose3D, type MusicBedInput, type NormRect, OBJECT_DEFAULT_SCALE, OVERLAY_FONT_FACES, OVERLAY_LINE_HEIGHT, OVERLAY_MEDIA_DEFAULT_RADIUS, OVERLAY_MEDIA_DEFAULT_WIDTH, OVERLAY_MIN_DURATION, OVERLAY_SCALE_MAX, OVERLAY_SIZE_MAX, OVERLAY_SIZE_MIN, OVERLAY_TRANSITION_DUR, OVERLAY_Z, type ObjectAnimation, type ObjectAsset, type ObjectClip, type ObjectPrimitiveShape, type OverlayClip, type OverlayFontFace, type OverlayKind, type OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PLATE_GROUND, PLAYBACK_ACTIVITY, PROGRAM_RETIME, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STUDIO_ENTRY_ID, STYLE_FIELDS, type SmoothOptions, type SmoothPoint, type SpeedParams, type SpeedSpan, type StepAnchor, type StepSpan, type StudioAudioPlan, type StudioDoc, type StudioEntry, type StyleField, TEXT3D_DEPTH_DEFAULT, TEXT3D_DEPTH_MAX, TEXT3D_DEPTH_MIN, TEXT_PRESETS, TILT_AUTO_DEAD_ZONE, TILT_AUTO_MIN, TILT_CHAIN_GAP, TILT_DEG_MAX, TILT_EASE, TILT_INTENSITY_MAX, TILT_PAN, TILT_PAN_EASE, TILT_RAMP_IN, TILT_RAMP_OUT, TILT_SPAN_MIN, TILT_UI_DEG_MAX, TRANSITION_SPEED_MULT, type Text3dMaterial, type TextFxDirection, type TextFxKind, type TextFxSpec, type TextFxUnit, type TextOverlayBox, type TextOverlayClip, type TextOverlayPreset, type TextOverlayStroke, type TiltPersonality, type TiltSpan, type TiltStyleName, type TranscriptSegment, type TransitionSpeed, WINDOW_FOCUS_MIN, ZOOM_CHAIN_GAP, ZOOM_EASE, ZOOM_LEVELS, ZOOM_LEVEL_MAX, ZOOM_LEVEL_MIN, ZOOM_PAN, ZOOM_PAN_EASE, ZOOM_RAMP_IN, ZOOM_RAMP_IN_OVERLAP, ZOOM_RAMP_OUT, ZOOM_SPAN_MIN, ZOOM_STYLES, ZOOM_STYLE_OPTIONS, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomWindow, anchorKindOf, anchorSourceDuration, applyLook, aspectRatioValue, audioLane, backdropMedia, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cardInset, cardPointToScreen, cardPoseTrack, clampCamFrac, clampCamSize, clampFocus, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, computeCardLayout, computeMicRms, computePeaks, copyStyle, cropBox, cursorIdleFade, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docOutputDuration, docToCropSpace, docToFullSpace, duckCurve, effectiveSegments, entranceSeconds, envelopeAt, envelopeValueAt, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, focusBounds, followFocusEvents, frameGeometry, hexToRgbTriplet, houseLook, idleGaps, isLookKind, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, levelForFocusFraction, lookFromBrand, lookKindForGround, lowerProgramDoc, lowerStudioDoc, lowerToComposition, micLane, migrateHostedDoc, momentsFromDoc, motionTrack, musicBedClip, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayRect, overlaysLane, pageDisplayUrl, parsePoseId, pickStyle, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolveText3dAsset, resolveZoomStyle, sceneChanges, scrollRuns, setSpeedInRange, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, videoLane, voiceKey, withBackdrop, withHolds, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomWindow };