reframe-video 0.6.34 → 0.6.39

package/dist/types/compose.d.ts

@@ -83,6 +83,12 @@ export interface ComposeReport {
     }[];
     warnings: string[];
 }
+/**
+ * Which params an overlay may patch on a labeled timeline step, per kind — the
+ * single source of truth for both `applyOverlay` (what it accepts) and
+ * `sceneManifest` (what it advertises as patchable). Keep them from drifting.
+ */
+export declare const TIMELINE_PATCHABLE: Record<string, string[]>;
 export declare function composeScene(base: SceneIR, ...overlays: OverlayDoc[]): {
     ir: SceneIR;
     report: ComposeReport;

package/dist/types/devicePreset.d.ts

@@ -1,12 +1,28 @@
 /**
- * Device-mockup presets: a parametric vector frame (phone/laptop/browser/…) with
+ * Device-mockup presets — a parametric vector frame (phone/laptop/browser/…) with
  * a CLIPPED screen "content slot". The sibling of motionPreset — that generates
  * a TimelineIR, this generates a NodeIR subtree. Pure primitives + clip, so no
- * assets and fully deterministic (plain JSON, no Date/random). A 2.5D vector
- * tier — no true perspective.
+ * assets and fully deterministic (plain JSON, no Date/random).
  *
  *   devicePreset("phone", { id: "hero", content: [ ...your UI nodes ] })
  *
+ * Redesigned around three orthogonal layers (all back-compat; the public surface
+ * and the stable ids `${id}` / `${id}-screen` / `${id}-content` are unchanged):
+ *
+ *  1. A `DeviceCtx` resolved once (palette + dims + material + style + a seeded
+ *     PRNG) and threaded to every part.
+ *  2. A small PARTS vocabulary (`slab`, `screenStack`, `phoneNotch`, …) where the
+ *     material/lighting lives ONCE, so every chassis — and every future chassis —
+ *     inherits the premium look for free.
+ *  3. A `CHASSIS` registry (name → builder) that just ARRANGES parts; adding a
+ *     device is one entry + one `SCREENS`/`BOUNDS` row, not a new `switch` arm.
+ *
+ * Material is PREMIUM by default (gradient body, ambient screen glow, soft contact
+ * shadow, glass glare) — `material:"flat"` opts back to clean flat fills. `style`
+ * picks "glass" (realistic) or "neon" (graphic, additive edge glow). Each instance
+ * auto-varies from its `id` (a deterministic seed) within bounded, on-model ranges;
+ * pass `seed` to pin or explore. A 2.5D vector tier — no true perspective.
+ *
  * Each instance needs a distinct `id` (it prefixes every generated node id);
  * two with the same prefix collide via the scene's duplicate-id validation.
  *
@@ -18,6 +34,14 @@
 import type { NodeIR } from "./ir.js";
 export declare const DEVICE_PRESET_NAMES: readonly ["phone", "tablet", "laptop", "browser", "watch", "monitor", "tv", "foldable", "terminal", "car"];
 export type DevicePresetName = (typeof DEVICE_PRESET_NAMES)[number];
+/** Visual fidelity tier. `premium` (default) layers gradient/glow/shadow on top
+ *  of the silhouette; `flat` is clean solid fills (lightest, golden-style). */
+export type DeviceMaterial = "premium" | "flat";
+/** Premium aesthetic. `glass` = realistic glass/metal + soft shadow; `neon` =
+ *  flat body + additive edge glow (graphic, motion-graphics punch). */
+export type DeviceStyle = "glass" | "neon";
+/** Phone front-camera treatment. Defaults to the iOS-style dynamic island. */
+export type DeviceNotch = "island" | "notch" | "punch" | "none";
 export interface DevicePresetOpts {
     /** Id PREFIX for every generated node (default "device"). Make it unique per instance. */
     id?: string;
@@ -38,6 +62,15 @@ export interface DevicePresetOpts {
     content?: NodeIR[];
     /** Browser/terminal address-bar text. */
     url?: string;
+    /** Visual tier (default "premium"). */
+    material?: DeviceMaterial;
+    /** Premium aesthetic (default "glass"). */
+    style?: DeviceStyle;
+    /** Deterministic variation. Omit ⇒ derived from `id` (each instance differs);
+     *  same value ⇒ identical; different value ⇒ same family, varied. */
+    seed?: number;
+    /** Phone front-camera style (default "island"). */
+    notch?: DeviceNotch;
 }
 /** The screen's content area (content-local coords: origin 0,0 = screen centre,
  *  pre-scale). Author/scroll `content` against these bounds. */

package/dist/types/dsl.d.ts

@@ -59,9 +59,10 @@ export interface BeatOpts {
     nodes?: string[];
     /** Group children in parallel instead of sequence. */
     parallel?: boolean;
-    /** Absolute start (rigid placement). */
-    at?: number;
-    /** Relative shift before the beat. */
+    /** Absolute start (number), or a timeline label to anchor to (string) — the
+     *  beat starts at that label's time, `gap` offsetting it. Keep anchor beats in a `par`. */
+    at?: number | string;
+    /** Relative shift before the beat (with a label `at`, the offset from the label). */
     gap?: number;
     /** Interior time-stretch factor. */
     scale?: number;

package/dist/types/index.d.ts

@@ -2,7 +2,8 @@ export * from "./ir.js";
 export * from "./dsl.js";
 export { validateScene, validateComposition, SceneValidationError, PROPS_BY_TYPE } from "./validate.js";
 export { compileComposition, type CompiledComposition, type ScenePlacement, } from "./composeComposition.js";
-export { composeScene, formatComposeReport, type OverlayDoc, type ComposeReport, } from "./compose.js";
+export { composeScene, formatComposeReport, TIMELINE_PATCHABLE, type OverlayDoc, type ComposeReport, } from "./compose.js";
+export { sceneManifest, lintScene, type SceneManifest, type NodeAddress, type StateAddress, type TimelineAddress, type BeatAddress, type BehaviorAddress, type ManifestSummary, type LintFinding, } from "./manifest.js";
 export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan, type MotionDriver } from "./compile.js";
 export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
 export { cameraTo, cameraFit, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
@@ -11,8 +12,9 @@ export { linearGradient, radialGradient, conicGradient, isGradient } from "./gra
 export { glow, dropShadow } from "./effects.js";
 export { row, column, grid, type RowOpts, type GridOpts } from "./layout.js";
 export { photoMontage, videoMontage, type MontageImage, type MontageOpts, type MontageResult, type KenBurns } from "./montage.js";
+export { title, lowerThird, type TitleOpts, type TitleResult, type LowerThirdOpts, type LowerThirdResult } from "./titles.js";
 export { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.js";
-export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, deviceScreenPoint, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.js";
+export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, deviceScreenPoint, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts, type DeviceMaterial, type DeviceStyle, type DeviceNotch } from "./devicePreset.js";
 export { cursor, cursorTo, cursorPath, cursorClick, cursorDouble, type CursorStyle, type CursorOpts, type CursorToOpts, type CursorPathOpts, type CursorClickOpts } from "./cursor.js";
 export { rig, rigPose, poseTo, ikReach, humanoid, ovalPath, type Bone, type RigOpts, type Pose, type HumanoidOpts } from "./rig.js";
 export { characterPreset, CHARACTER_PRESET_NAMES, type CharacterPresetName, type CharacterPresetOpts } from "./characterPreset.js";

package/dist/types/ir.d.ts

@@ -243,10 +243,12 @@ export interface VideoProps extends BaseProps {
     /** Box-fit into width×height, like the image node. `"fill"` (default) | `"cover"`. */
     fit?: ImageFit;
     /**
-     * Scene-time (seconds) at which playback begins. Before it, frame 0 (clipStart) shows;
-     * the node's visibility is still controlled by opacity/timeline. Default 0.
+     * Scene-time at which playback begins. Before it, frame 0 (clipStart) shows; the
+     * node's visibility is still controlled by opacity/timeline. Default 0. A NUMBER is
+     * an absolute time; a STRING anchors the start to that timeline label's t0 (like
+     * `beat.at`), so the clip follows when its shot is retimed (e.g. `start: "shot-2"`).
      */
-    start?: number;
+    start?: number | string;
     /** Playback speed multiplier (2 = double speed). Default 1. */
     rate?: number;
     /** Source in-point (seconds) shown at `start`. Default 0. */
@@ -373,8 +375,14 @@ export type TimelineIR = {
      */
     nodes?: string[];
     parallel?: boolean;
-    /** Absolute start (rigid placement). Overrides sequential flow. */
-    at?: number;
+    /**
+     * Start placement (overrides sequential flow). A NUMBER is an absolute time;
+     * a STRING anchors the beat to that timeline label's start (e.g.
+     * `at: "shot-2"`), so the beat stays synced when the target is retimed (the
+     * same idea as `audio.cues`). With a label anchor, `gap` is the offset from
+     * the label. Anchor beats should sit in a `par` branch, not a sequential flow.
+     */
+    at?: number | string;
     /** Relative shift: a leading delay before the beat (and everything after). */
     gap?: number;
     /** Interior time-stretch factor (every child offset and duration ×scale). */

package/dist/types/manifest.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Scene manifest + addressability lint — make the override namespace queryable.
+ *
+ * Both override stacks (authoring `composeScene`, runtime `sampleProp`) can only
+ * find anything through the node-id / timeline-label namespace. That namespace is
+ * the entire edit API, but it's implicit. `sceneManifest` enumerates it — every
+ * editable address a human or an AI editor can patch — and `lintScene` flags the
+ * surface that ISN'T addressable (motion with no label can't be retimed by an
+ * overlay). Pure reads over a CompiledScene; no IR/evaluate changes.
+ */
+import type { CompiledScene } from "./compile.js";
+import type { NodeIR, Size, TimelineIR } from "./ir.js";
+export interface NodeAddress {
+    id: string;
+    type: NodeIR["type"];
+    /** Enclosing group id (absent for a top-level node). */
+    parent?: string;
+    /** Overlay address for base-prop patches: `nodes.<id>`. */
+    address: string;
+    /** Props an overlay may set on this node (PROPS_BY_TYPE for its type). */
+    editableProps: string[];
+    /** Props this node actually animates (has a tween/to segment or a motion path). */
+    animatedProps: string[];
+    /** State names that override this node (`states.<name>.<id>` addresses). */
+    inStates: string[];
+}
+export interface StateAddress {
+    name: string;
+    address: string;
+    touches: {
+        id: string;
+        props: string[];
+    }[];
+}
+export interface TimelineAddress {
+    label: string;
+    kind: TimelineIR["kind"];
+    t0: number;
+    t1: number;
+    /** Params an overlay may patch on this step (TIMELINE_PATCHABLE for its kind). */
+    patchable: string[];
+    address: string;
+}
+export interface BeatAddress {
+    name: string;
+    t0: number;
+    t1: number;
+    /** Node ids the beat semantically owns (its `nodes` field). */
+    ownsNodes: string[];
+    address: string;
+}
+export interface BehaviorAddress {
+    target: string;
+    prop: string;
+    kind: string;
+    address: string;
+}
+export interface ManifestSummary {
+    nodeCount: number;
+    /** Labeled timeline steps + named beats (addressable timing). */
+    labeledSteps: number;
+    /** Motion steps (tween/to/motionPath) with NO label — unaddressable timing. */
+    unlabeledMotionSteps: number;
+    /** labeled motion steps / total motion steps (1 when there is no motion). */
+    motionAddressableRatio: number;
+}
+export interface SceneManifest {
+    scene: {
+        id: string;
+        duration: number;
+        fps: number;
+        size: Size;
+        background?: string;
+    };
+    nodes: NodeAddress[];
+    states: StateAddress[];
+    timeline: TimelineAddress[];
+    beats: BeatAddress[];
+    behaviors: BehaviorAddress[];
+    summary: ManifestSummary;
+}
+export interface LintFinding {
+    rule: string;
+    severity: "warn" | "error";
+    message: string;
+    /** Present when the finding refers to an existing address. */
+    address?: string;
+}
+/** Enumerate a scene's full addressable / editable surface. Pure + deterministic. */
+export declare function sceneManifest(compiled: CompiledScene): SceneManifest;
+/** Flag the surface that ISN'T overlay-addressable. Static, no render. */
+export declare function lintScene(compiled: CompiledScene): LintFinding[];

package/dist/types/titles.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Title + lower-third generators — the motion-graphic overlay vocabulary for a
+ * media piece (titles, name straps), the high-level analog of `photoMontage`.
+ *
+ * `title()` composes the kinetic-text engine (`splitText` + `textIn`/`textOut`);
+ * `lowerThird()` is a name/role strap with an accent bar. Both return
+ * `{ nodes, timeline }` (house style) so a caller spreads the nodes into the
+ * scene and composes the timeline with `seq`/`par`. Pure + deterministic; stable
+ * ids so overlay edits address them.
+ */
+import type { NodeIR, TimelineIR } from "./ir.js";
+import { type FontWeight, type TextBlock, type TextInName, type TextOutName } from "./textFx.js";
+export interface TitleOpts {
+    /** The headline text. */
+    text: string;
+    /** Id PREFIX → glyph ids `${id}-${i}` (default "title"). Make it unique. */
+    id?: string;
+    /** Anchor (default centre of a 1920×1080 frame). */
+    x?: number;
+    y?: number;
+    fontSize?: number;
+    fontWeight?: FontWeight;
+    fill?: string;
+    letterSpacing?: number;
+    /** Entrance preset (default "cascade"). */
+    entrance?: TextInName;
+    /** Optional exit preset — when set, the title plays in, holds, then exits. */
+    exit?: TextOutName;
+    /** Duration multiplier (>1 faster). */
+    speed?: number;
+    /** Deterministic per-glyph variation. */
+    seed?: number;
+    /** Seconds held before the exit (only used with `exit`). Default 2. */
+    hold?: number;
+}
+export interface TitleResult {
+    nodes: NodeIR[];
+    timeline: TimelineIR;
+    /** The laid-out text block — add `textLoop` behaviors or extra tweens off this. */
+    block: TextBlock;
+}
+/** A kinetic headline. Labels: `${id}-in` (entrance) and `${id}-out` (exit). */
+export declare function title(opts: TitleOpts): TitleResult;
+export interface LowerThirdOpts {
+    /** Main line (e.g. a name). */
+    name: string;
+    /** Sub line (e.g. a role). Omit for a single-line strap. */
+    role?: string;
+    /** Id PREFIX → `${id}` group + `${id}-bar`/`${id}-name`/`${id}-role` (default "lt"). */
+    id?: string;
+    /** Group anchor (default a bottom-left title-safe position). */
+    x?: number;
+    y?: number;
+    /** Accent bar colour (default "#FF4D00"). */
+    accent?: string;
+    /** Name colour (default "#FFFFFF"). */
+    fill?: string;
+    /** Role colour (default "#C9C9C9"). */
+    subFill?: string;
+    /** Name font size (default 48); the role is ~0.58× of it. */
+    fontSize?: number;
+    /** Seconds the strap holds before it exits. Default 3. */
+    hold?: number;
+}
+export interface LowerThirdResult {
+    nodes: NodeIR[];
+    timeline: TimelineIR;
+}
+/** A name/role strap with an accent bar that grows in, text sliding + fading.
+ *  Labels: `${id}-in` (entrance) and `${id}-out` (exit). */
+export declare function lowerThird(opts: LowerThirdOpts): LowerThirdResult;