@vosjs/cli 0.53.0 → 0.53.2

package/skills/vos-port/references/elements-and-context.md

@@ -0,0 +1,591 @@
+<!-- Generated by scripts/build-element-reference.mjs from @vosjs/core 0.25.1, @vosjs/elements 0.8.2 and @vosjs/timeline 0.4.1. Do not edit by hand: re-run the script. -->
+
+# Elements, the context and eases: the declarations
+
+What a program's config and functions accept, copied from the published
+type declarations so a port never has to read `node_modules`. The notes
+between the blocks are the facts the declarations do not say; the units
+are in SKILL.md's "coordinates, measured" and the draw order in its
+"Layering".
+
+## The config
+
+A `config.json` is this shape, functions as strings. `elements` is typed
+loosely here; its members are the element types below.
+
+```ts
+interface FontFaceDecl {
+    /** Family name as used in `font.family` / canvas font strings. */
+    family: string;
+    /** Font file URL (woff2/woff/ttf). Must be reachable from render pages. */
+    url: string;
+    /** CSS weight the file carries (default 'normal'). One decl per weight. */
+    weight?: number | string;
+    style?: 'normal' | 'italic';
+}
+
+/**
+ * JSON-serializable version of VosConfig.
+ * Functions are stored as strings that can be embedded in the compiled template.
+ *
+ * Note: Elements are typed loosely as Record<string, unknown>[] for JSON
+ * transport compatibility. The actual ElementConfig type validation happens
+ * at compile time in compileVosConfig.
+ */
+interface VosConfigJson {
+    /**
+     * Which schema era this config was written against.
+     *
+     * Required, because this is the CANONICAL shape: what is stored, served
+     * and read back later, when nobody can tell the era from the file itself.
+     * `migrateConfig` stamps it, so the type you hand a storer always has one.
+     * The authoring shape that may omit it is `AuthoredVosConfigJson`.
+     */
+    version: number;
+    /**
+     * Total duration of one animation cycle in seconds.
+     */
+    duration: number;
+    /** Scene configuration (background, fog) */
+    scene?: SceneConfig;
+    /** Camera configuration */
+    camera: CameraConfig;
+    /** Post-processing effects */
+    postprocessing?: PostprocessingEffect[];
+    /** Declare per-layer effect types for addon imports */
+    perLayerEffects?: PostprocessingEffect[];
+    /** Enable per-frame render group rebuild when zIndex changes at runtime */
+    dynamicLayers?: boolean;
+    /** 2D Elements rendered as textured planes (loosely typed for JSON transport) */
+    elements?: Record<string, unknown>[];
+    /** Declarative world-space 3D objects (primitives / GLB). */
+    objects?: Record<string, unknown>[];
+    /**
+     * Webfont faces to register and load BEFORE anything rasterizes text.
+     * Canvas text silently falls back to a default font when a family isn't
+     * loaded — headless render environments have near-zero system fonts, so any
+     * non-generic family used by text elements (or setup-drawn canvases) should
+     * be declared here with a self-hosted URL. Loading is awaited capped and
+     * fail-open: a dead URL degrades to fallback stacks, never a hung page.
+     */
+    fonts?: FontFaceDecl[];
+    /**
+     * Arbitrary input data made available to functions as `ctx.data`.
+     * The shape is the author's/app's, not vos's — vos passes it through verbatim.
+     * Overridable at runtime via `initVos(container, deps)` `deps.data` (so a live
+     * editor can update data without recompiling); `config.data` is the baked default.
+     * @example { cursor: [{ t: 0, x: 10, y: 20, type: 'down' }] }
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Async setup hook as a string.
+     * @example "(ctx) => { const loader = new ctx.loaders.FontLoader(); ... }"
+     */
+    setup?: string;
+    /**
+     * Create scene content function as a string.
+     * @example "(ctx, setupData) => { const { THREE, scene } = ctx; ... }"
+     */
+    createContent: string;
+    /**
+     * Create GSAP timeline function as a string.
+     * @example "(ctx, content, duration) => { const tl = ctx.gsap.timeline(); ... }"
+     */
+    createTimeline: string;
+    /**
+     * Optional per-frame update function as a string.
+     * @example "(ctx, content, deltaTime) => { content.refs.uniforms.iTime.value += deltaTime; }"
+     */
+    onFrame?: string;
+    /**
+     * Evaluate the program at `f(t)`, as a string: `(t, data) => number`, a
+     * pure function of the OUTPUT time and `ctx.data`. Slow motion, ramps,
+     * reverse, freeze frames, ping-pong loops. See `VosConfig.retime`.
+     */
+    retime?: string;
+    /**
+     * The program stack: more programs on this context, run after the main one
+     * in array order, each with its own `ctx.data` and error boundary. A HUD, a
+     * subtitle pass, a watermark, an overlay a remixer adds without touching the
+     * main program's code. No timeline of their own — one master clock.
+     */
+    stack?: ProgramEntryJson[];
+}
+```
+
+## Elements (`config.elements[]`)
+
+`content`, `font.family` and `font.color` of a text element are the three
+fields that take a `{ "$data": "<key>" }` binding, and the only ones that
+re-resolve on a data edit; every other field is read once at build.
+`font.size`, `letterSpacing`, `transform.translateX/Y`, `stroke.width`
+and `shadow.blur` are design pixels (a 1080-high frame). There is no
+`mask`, `clip`, `blend` or group field on any element: SKILL.md's
+"honest gaps" says what to do instead.
+
+```ts
+/**
+ * `{$data: key}` binding — the value resolves from the host's data object at
+ * render time and re-resolves on setData (a pure data edit, no recompile).
+ */
+interface DataRef {
+    $data: string;
+}
+
+/**
+ * Base interface for all element types
+ */
+interface BaseElement {
+    /** Unique identifier for referencing in createTimeline */
+    id?: string;
+    type: 'text' | 'image' | 'svg' | 'video' | 'audio';
+    /** Position on screen */
+    position: ElementPosition;
+    /** Transform origin */
+    anchor?: Anchor;
+    /** Layer order (higher = on top, default: 100) */
+    zIndex?: number;
+    /** Opacity 0-1 */
+    opacity?: number;
+    /** 3D transform */
+    transform?: Transform;
+}
+
+/**
+ * Position can be pixels, percentages, or preset strings
+ */
+type ElementPosition = {
+    x: number;
+    y: number;
+} | {
+    x: string;
+    y: string;
+} | PositionPreset;
+
+type PositionPreset = 'center' | 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+type Anchor = 'center' | 'top-left' | 'top' | 'top-right' | 'left' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+
+/**
+ * 3D transform properties
+ */
+interface Transform {
+    translateX?: number;
+    translateY?: number;
+    translateZ?: number;
+    rotateX?: number;
+    rotateY?: number;
+    rotateZ?: number;
+    rotation?: number;
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    perspective?: number;
+    origin?: {
+        x: string;
+        y: string;
+    };
+}
+
+interface TextElement extends BaseElement {
+    type: 'text';
+    /** Text content (supports \n for multiline), or a `{$data}` binding */
+    content: string | DataRef;
+    font?: {
+        family?: string | DataRef;
+        size?: number;
+        weight?: number | string;
+        style?: 'normal' | 'italic';
+        color?: string | DataRef;
+        letterSpacing?: number;
+        lineHeight?: number;
+        align?: 'left' | 'center' | 'right';
+    };
+    stroke?: {
+        color: string;
+        width: number;
+    };
+    shadow?: {
+        color: string;
+        blur: number;
+        offsetX?: number;
+        offsetY?: number;
+    };
+    /**
+     * Split text into segments for per-character/word/line animation.
+     * When split is defined, the element exposes a `segments` array
+     * of ElementProps for animating individual parts.
+     */
+    split?: {
+        /** Type of split: 'chars', 'words', or 'lines' */
+        type: 'chars' | 'words' | 'lines';
+    };
+}
+
+interface ImageElement extends BaseElement {
+    type: 'image';
+    /** URL, base64, or imported asset path */
+    src: string;
+    size?: {
+        width?: number | 'auto';
+        height?: number | 'auto';
+        fit?: 'contain' | 'cover' | 'fill';
+    };
+    filters?: {
+        brightness?: number;
+        contrast?: number;
+        saturate?: number;
+        blur?: number;
+        hueRotate?: number;
+        grayscale?: number;
+    };
+    borderRadius?: number;
+}
+
+interface SVGElement extends BaseElement {
+    type: 'svg';
+    /** SVG string, URL, or imported asset */
+    src: string;
+    size?: {
+        width?: number | 'auto';
+        height?: number | 'auto';
+    };
+    /** Override colors in SVG */
+    colors?: Record<string, string>;
+}
+
+interface VideoElement extends BaseElement {
+    type: 'video';
+    src: string;
+    size?: {
+        width?: number | 'auto';
+        height?: number | 'auto';
+        fit?: 'contain' | 'cover' | 'fill';
+    };
+    loop?: boolean;
+    muted?: boolean;
+    playbackRate?: number;
+    startTime?: number;
+    /**
+     * Decode strategy:
+     *  - 'html5' (default): HTMLVideoElement + VideoTexture (legacy; not frame-accurate)
+     *  - 'webcodecs': frame-accurate WebCodecs decode (deterministic export/scrub)
+     *  - 'auto': webcodecs when available, else html5
+     */
+    frameSource?: 'auto' | 'webcodecs' | 'html5';
+}
+
+/**
+ * Non-visual element that plays an audio file synced to the master clock.
+ * Drive it like an html5 video: set `playing` and/or animate `currentTime`
+ * in createTimeline; playback honors the global pause/seek state, and
+ * `props.gain` (0-1) is animatable for fades. Renders no pixels — position,
+ * anchor and transform are accepted for BaseElement compatibility but ignored.
+ */
+interface AudioElement extends Omit<BaseElement, 'position'> {
+    type: 'audio';
+    /** Audio file URL (anything the browser's media stack decodes) */
+    src: string;
+    /** Ignored (audio renders no pixels) */
+    position?: ElementPosition;
+    /** Initial volume 0-1 (default: 1); animatable via props.gain */
+    gain?: number;
+    loop?: boolean;
+    /** Offset into the source when playback begins, seconds (default: 0) */
+    startTime?: number;
+    /**
+     * A gain envelope over OUTPUT time: `[t, gain]` points, linear between
+     * them, held flat outside, multiplied with `props.gain`. Fades, ducking, a
+     * bed that swells under a title, as data the offline renderer replays
+     * (`@vosjs/core/audio`) and live playback follows frame by frame.
+     */
+    gainEnvelope?: Array<[t: number, gain: number]>;
+}
+```
+
+## An element at runtime (`ctx.elements.get(id)`)
+
+What `createTimeline` and `onFrame` animate: `el.props` (and
+`el.segments[i]` under `split`). `props.x` / `props.y` are RENDER pixels
+from the frame centre with `y` down, and `rotation` is degrees
+counter-clockwise, unlike the config's design-pixel `transform`.
+
+Writing any of `content`, `fontSize`, `fontFamily`, `fontWeight`, `fontStyle`, `letterSpacing`, `color`, `strokeColor`, `strokeWidth` on a text element's `props`
+re-rasters it (the runtime's own list), so a scramble or a counter writes
+`el.props.content` in `onFrame` and a colour change sets `el.props.color`.
+The tween dialect animates numbers only: tween `fontSize` and
+`letterSpacing`, SET the strings. `props.zIndex` is settable too.
+
+Every such write queues a re-raster, even of an unchanged value, so guard
+a per-frame write: `if (el.props.content !== next) el.props.content = next`.
+A `split` text element does not re-raster at all: these writes are ignored
+on it, so text that changes and text that animates per letter are two
+elements.
+
+```ts
+/**
+ * GSAP-animatable properties exposed on each element instance
+ */
+interface ElementProps {
+    x: number;
+    y: number;
+    z: number;
+    opacity: number;
+    scale: number;
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+    rotationX: number;
+    rotationY: number;
+    /** Layer order inside the element's overlay scene (writes `renderOrder`) */
+    zIndex?: number;
+    content?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: number | string;
+    fontStyle?: 'normal' | 'italic';
+    letterSpacing?: number;
+    color?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    /** Current playback position in seconds (animatable with GSAP) */
+    currentTime?: number;
+    /** Video duration in seconds (read-only) */
+    readonly duration?: number;
+    /** Whether the video is playing (controls native playback) */
+    playing?: boolean;
+    /** Start offset for video playback */
+    startOffset?: number;
+    /** Volume 0-1 (audio elements; animatable for fades) */
+    gain?: number;
+}
+
+/**
+ * Runtime element instance with animatable props and methods
+ */
+interface ElementInstance {
+    /** Original configuration */
+    config: ElementConfig;
+    /** Three.js mesh (textured plane) */
+    mesh: THREE.Mesh;
+    /** DOM node for SplitText (text elements only) - typed as unknown for portability */
+    node: unknown;
+    /** GSAP-animatable properties */
+    props: ElementProps;
+    /**
+     * Split text segments (only available when split config is defined).
+     * Each segment has its own ElementProps for individual animation.
+     */
+    segments?: ElementProps[];
+    /** Update element content (text or image src) */
+    setContent: (content: string) => void;
+    /**
+     * Re-resolve `{$data}`-bound props against fresh data (called by the
+     * compiled module's setData). Returns true when a change was picked up.
+     */
+    updateData?: (data: Record<string, unknown> | null | undefined) => boolean;
+    /**
+     * Re-raster with unchanged values — the late-webfont hook (a data-carried
+     * face landing after first paint re-draws over the fallback stack).
+     */
+    refreshRaster?: () => boolean;
+    /** Re-rasterize canvas-backed textures for a new output resolution */
+    updateResolution?: (resolution: unknown) => boolean;
+    /** Remove element from scene */
+    destroy: () => void;
+}
+```
+
+## The context (`ctx`)
+
+`setup(ctx)` gets a `SetupContext` and may return assets;
+`createContent(ctx, setupData)` returns a `ContentResult`;
+`createTimeline(ctx, content, duration)` returns the timeline;
+`onFrame(ctx, content, deltaTime)` runs every frame, `ctx.time` being the
+program's time in seconds. `ctx.data` is read-only: a knob changes it from outside,
+and `onFrame` reads the new value on the next frame. Read `ctx.data` on
+every frame, never a copy taken in `createContent`.
+
+```ts
+/**
+ * Resolution configuration passed to animations
+ */
+interface Resolution {
+    width: number;
+    height: number;
+    pixelRatio: number;
+    /** Physical drawing buffer width (width × pixelRatio) - for shader uniforms */
+    drawingBufferWidth: number;
+    /** Physical drawing buffer height (height × pixelRatio) - for shader uniforms */
+    drawingBufferHeight: number;
+}
+
+/**
+ * Loaders registry - common Three.js loaders
+ */
+interface LoadersRegistry {
+    FontLoader: any;
+    TextureLoader: any;
+    GLTFLoader: any;
+    HDRLoader: any;
+    CubeTextureLoader: any;
+}
+
+/**
+ * Utilities registry - common Three.js utilities
+ */
+interface UtilsRegistry {
+    MeshSurfaceSampler: any;
+    BufferGeometryUtils: any;
+    TextGeometry: any;
+}
+
+/**
+ * Context available during async setup phase
+ */
+interface SetupContext {
+    THREE: typeof THREE;
+    resolution: Resolution;
+    loaders: LoadersRegistry;
+    utils: UtilsRegistry;
+    /**
+     * Read-only input data exposed to all functions as `ctx.data`.
+     * Sourced from `config.data`, overridable at runtime by `initVos` `deps.data`.
+     * Always defined (defaults to `{}`). Shape is the author's/app's, not vos's.
+     */
+    data: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Context available during animation creation
+ */
+interface VosContext extends SetupContext {
+    gsap: typeof gsap;
+    scene: THREE.Scene;
+    camera: THREE.Camera;
+    renderer: THREE.WebGLRenderer;
+    /** Dedicated scene for 2D overlay elements (rendered on top of main scene) */
+    overlayScene: THREE.Scene;
+    /** Orthographic camera for 2D overlay (pixel-space: 1 unit = 1 pixel) */
+    overlayCamera: THREE.OrthographicCamera;
+    composer?: unknown;
+    /** Element instances for timeline animations */
+    elements: Map<string, ElementInstance>;
+    /** Current playback time in seconds (available in onFrame) */
+    time: number;
+    /** Playback progress 0-1 (available in onFrame) */
+    progress: number;
+    /**
+     * The OUTPUT time in seconds: what the transport shows and the capture
+     * counts. Equal to `time` unless the config carries a `retime`, in which
+     * case `time` is `retime(outputTime, data)` — the program's own time —
+     * while `outputTime` keeps counting the output. Stack entries read
+     * `ctx.time` as output time (they are output-anchored by contract).
+     */
+    outputTime: number;
+}
+
+/**
+ * Result from createContent function
+ */
+interface ContentResult {
+    /** Objects added to scene */
+    objects: THREE.Object3D[];
+    /** Named references for timeline animations */
+    refs?: Record<string, unknown>;
+    /** Cleanup function for content-specific resources */
+    dispose?: () => void;
+}
+```
+
+## The timeline (what `createTimeline` returns)
+
+Author it as GSAP: `const tl = ctx.gsap.timeline({ paused: true })`, tweens
+on `el.props`, `tl.addLabel(name, t)` per scene, return `tl`. This is the
+whole surface the engine calls on it.
+
+```ts
+/**
+ * Structural master-clock interface the engine seeks each frame.
+ *
+ * This is the ONLY surface the runtime uses from the timeline object returned by
+ * `createTimeline` (pause/seek/play + transport queries + carrier retiming). It is
+ * satisfied structurally by `gsap.core.Timeline` today, so authoring against real
+ * GSAP is unchanged — but the public API no longer hard-depends on the `gsap` type,
+ * which lets an alternate deterministic backend provide a conformant timeline later
+ * without a breaking change. Method shorthand is intentional (bivariant params) so
+ * GSAP's overloaded signatures remain structurally assignable.
+ */
+interface VosTimeline {
+    /** Pause playback (frame-stepped export pauses before the first frame). */
+    pause(): unknown;
+    /** Resume playback. */
+    play(): unknown;
+    /** Seek to `time` seconds. `suppressEvents=false` fires onUpdate callbacks. */
+    seek(time: number, suppressEvents?: boolean): unknown;
+    /** Rebuild/clear children (used by the vosCarrier duration-retime path). */
+    clear(): unknown;
+    /** Set playback rate. */
+    timeScale(value: number): unknown;
+    /** Current playhead in seconds. */
+    time(): number;
+    /** Normalized progress 0..1. */
+    progress(): number;
+    /**
+     * Optional (the vos tween backend): re-apply a tween-timing overlay over the
+     * recorded tweens, from the recording every time. The bridge's
+     * SET_TWEEN_EDITS rides it; absent on a gsap timeline.
+     */
+    applyEdits?(edits: readonly Record<string, unknown>[]): unknown;
+    /** Configured duration in seconds. */
+    duration(): number;
+    /** Total duration including repeats (seconds). */
+    totalDuration(): number;
+    /** Attach/read a lifecycle callback (engine uses onUpdate). */
+    eventCallback(type: string, callback?: (...args: any[]) => void): unknown;
+    /** Opaque author-attached marker (e.g. `{ vosCarrier: true }`). */
+    data?: unknown;
+}
+```
+
+## Eases
+
+An `ease` string anywhere GSAP takes one. Beyond the names below the
+engine accepts the parameterized forms `back.out(1.7)`,
+`elastic.out(1, 0.3)`, `steps(5)`, and `css-bezier(x1, y1, x2, y2)`,
+which is CSS's `cubic-bezier` and Remotion's `Easing.bezier` with the same
+four numbers (`cubic-bezier` itself is not a name). A bare family
+(`'power2'`) means `.out`. **An unknown name is not an error: it plays
+linear.** `vos check` warns `unknown-ease` for a literal `ease: '…'` it
+cannot resolve; through `@vosjs/core` 0.25.0 that warning also fired on
+`css-bezier`, wrongly, so ignore it there. An ease held in a variable is
+not checked: the side-by-side is where it shows.
+
+```ts
+/**
+ * Value types for deterministic timeline math.
+ *
+ * These are meant to be EMBEDDED inside an app's own document schema — @vosjs/timeline
+ * is an evaluation library, not a document format. Everything is JSON-serializable
+ * (eases are registry names, never functions) so the same values travel through
+ * `ctx.data` into a running vos program and evaluate identically on both sides.
+ */
+type EaseFamily = 'power1' | 'power2' | 'power3' | 'power4' | 'sine' | 'expo' | 'circ' | 'back' | 'elastic' | 'bounce';
+
+type EaseDirection = 'in' | 'out' | 'inOut';
+
+/**
+ * Serializable easing name. The vocabulary (and the curves) match GSAP's so one
+ * ease language spans freeform function-strings and declarative keyframes.
+ */
+type EaseName = 'none' | 'linear' | `${EaseFamily}.${EaseDirection}`;
+
+/**
+ * Resolve an ease by name, including parameterized forms (`back.out(1.7)`,
+ * `elastic.out(1, 0.3)`, `steps(5)`) and GSAP's bare-family default
+ * (`'power2'` → `power2.out`). Unknown names fall back to linear — evaluation
+ * must never throw per-frame inside a running program; authoring layers are
+ * expected to validate names at edit time instead.
+ */
+function resolveEase(name: string | undefined): EaseFn;
+```

package/skills/vos-port/references/hyperframes.md

@@ -21,6 +21,7 @@ units (render pixels, y down, degrees counter-clockwise).
 | a sub-composition or scene `div` with a time window | `tl.addLabel(name, t)` and its elements tweened in and out inside the window |
 | an `onUpdate` proxy clock that draws (`renderAll(t)`) | `onFrame(ctx)`, reading `ctx.time`, for exactly those procedural parts |
 | GSAP ease names (`power3.out`, `back.out(1.7)`, `expo.inOut`) | the same names |
+| a CSS `cubic-bezier(a, b, c, d)` timing | `ease: 'css-bezier(a, b, c, d)'` (exact; spelled `cubic-bezier` it plays linear) |
 | CSS `--chrome` set by the timeline | a `data` value read in `onFrame`, or a tween on the element that shows it |
 | faces resolved by the runtime from CSS families | `fonts: [{ family, weight, url }]` from the catalog |
 | `mix-blend-mode`, `clip-path`, `overflow: hidden` reveals | GAPS: the painter, or an opacity approximation, said |