@motion-script/core 0.1.0

package/dist/render/measure-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-scope.js","sourceRoot":"","sources":["../../src/render/measure-scope.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,MAAM,OAAgB,YAAY;CAqBjC"}

package/dist/render/render-context.d.ts

@@ -0,0 +1,258 @@
+import { FontStyle } from "../attributes/text/span";
+import { type RectState } from "./descriptors/rect";
+import { TextState } from "./descriptors/text";
+import { RichTextState } from "./descriptors/richtext";
+import { TransformState } from "./descriptors/transform";
+import { PathState } from "./descriptors/path";
+import type { PathBuilder } from "./descriptors/path-builder";
+import { EllipseState } from "./descriptors/ellipse";
+import { LineState } from "./descriptors/line";
+import { ImageState } from "./descriptors/image";
+import { PolygonState } from "./descriptors/polygon";
+import { PolygramState } from "./descriptors/polygram";
+import { MeasureScope } from "./measure-scope";
+import { FillProp } from "../attributes/shape/fill/union";
+import { Vector2 } from "../attributes/layout/vector2";
+import { ShadowProp } from "../attributes/shape/shadow/resolver";
+import { StrokeProp } from "../attributes/shape/stroke/mapper";
+import { MaskOptions } from "../attributes/mask/mask";
+import { BooleanOperation } from "../attributes/mask/boolean";
+import type { BulgePinchEffect } from "../attributes/shape/effects/implementations/bulge-pinch";
+import type { ZoomEffect } from "../attributes/shape/effects/implementations/zoom";
+import type { SkSLEffect } from "../attributes/shape/effects/implementations/sksl";
+/**
+ * A shape outline to clip against, tagged by kind so the renderer can build the
+ * same path it would draw. Used by background blur to confine the backdrop blur
+ * to any shape's silhouette.
+ */
+export type ClipShape = {
+    kind: "rect";
+    state: Partial<RectState>;
+} | {
+    kind: "ellipse";
+    state: Partial<EllipseState>;
+} | {
+    kind: "polygon";
+    state: Partial<PolygonState>;
+} | {
+    kind: "polygram";
+    state: Partial<PolygramState>;
+} | {
+    kind: "path";
+    state: Partial<PathState>;
+} | {
+    kind: "line";
+    state: Partial<LineState>;
+};
+/**
+ * A bounding box in the current node's local space (origin = the node's
+ * layout-cell centre, the same space shapes are drawn in). `left/top` use the
+ * canvas convention (y down).
+ */
+export interface SpaceRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Reference rects a fill can resolve against, supplied per-node at `begin()`.
+ * `local`/`global` are derived from the drawn shapes themselves, so only the
+ * outer frames are passed here.
+ */
+export interface SpaceRects {
+    /** The parent node's content rect, in this node's local space. */
+    parent?: SpaceRect;
+    /** The render viewport, in this node's local space. */
+    view?: SpaceRect;
+}
+/**
+ * Low-level shape-drawing API. Each method declares a shape and returns a
+ * `Render2DPaintContext` that lets you chain further shapes and apply paint
+ * (fill / stroke / shadow). Multiple shapes chained before a paint call are
+ * combined into a single surface and painted together.
+ */
+export declare abstract class Render2DContext {
+    /** Declare an axis-aligned rectangle. */
+    abstract rect(state: Partial<RectState>): Render2DPaintContext;
+    /** Declare an ellipse (circle when width === height). */
+    abstract ellipse(state: Partial<EllipseState>): Render2DPaintContext;
+    /** Declare a single-style text run. */
+    abstract text(state: Partial<TextState>): Render2DPaintContext;
+    /** Declare a multi-span rich-text block. */
+    abstract richText(state: Partial<RichTextState>): Render2DPaintContext;
+    /** Declare a vector path, either from a `PathState` or a `PathBuilder`. */
+    abstract path(state: Partial<PathState> | PathBuilder): Render2DPaintContext;
+    /** Declare a straight line segment. */
+    abstract line(state: Partial<LineState>): Render2DPaintContext;
+    /** Declare a raster image. */
+    abstract image(state: Partial<ImageState>): Render2DPaintContext;
+    /** Declare a regular polygon (triangle, pentagon, …). */
+    abstract polygon(state: Partial<PolygonState>): Render2DPaintContext;
+    /** Declare a star / polygram. */
+    abstract polygram(state: Partial<PolygramState>): Render2DPaintContext;
+}
+/**
+ * The context returned after a shape is declared. It extends `Render2DContext`
+ * so further shapes can be chained — multiple shapes drawn before a paint call
+ * accumulate and are painted together:
+ *
+ *   draw.ellipse(...).rect(...).fill(...)   // both shapes share one fill
+ *
+ * `cut()` uses the most-recently drawn shape as a cutter: it unions the shapes
+ * before it and subtracts that last shape, so only it punches a hole. Shapes
+ * drawn after `cut()` are added back, and the whole result paints as one
+ * surface — a single gradient maps across all of it:
+ *
+ *   draw.rect(...).ellipse(...).cut().rect(...).fill(gradient)
+ *   // rect ∪ (previous) − ellipse, then ∪ the trailing rect
+ */
+export interface Render2DPaintContext extends Render2DContext {
+    fill(fills: FillProp | FillProp[]): Render2DPaintContext;
+    stroke(strokes: StrokeProp | StrokeProp[]): Render2DPaintContext;
+    shadow(shadows: ShadowProp | ShadowProp[]): Render2DPaintContext;
+    /**
+     * Use the last-drawn shape as a cutter: union the shapes before it and
+     * subtract that last shape, leaving the result as the current shape so
+     * subsequent shapes and paint calls treat everything as a single surface.
+     */
+    cut(): Render2DPaintContext;
+    /**
+     * Switch a mask scope from mask-collection phase to content phase. Call
+     * after drawing the mask shape(s) following `RenderContext.mask()`:
+     *
+     *   draw.mask({ mode: 'alpha' })
+     *       .ellipse({...}).fill(maskFill)
+     *       .applyMask()
+     *       .rect({...}).fill(this.fill).stroke(this.stroke)
+     *       .endMask();
+     */
+    applyMask(): Render2DPaintContext;
+    /** Close the mask scope opened by `RenderContext.mask()`. */
+    endMask(): void;
+}
+/**
+ * The full rendering context passed to every scene-graph node when it draws
+ * itself. Combines shape drawing (`Render2DContext`), text measurement
+ * (`MeasureScope`), and higher-level scoping operations (transforms, masks,
+ * clips, camera, boolean ops, backdrop effects).
+ *
+ * `begin(id)` / `end()` bracket each node's draw call so the context can
+ * track which node is active and look up per-node state (space rects, etc.).
+ * The concrete implementations (`CanvasKitRenderContext`, `SvgRenderContext`,
+ * …) translate these abstract calls into renderer-specific drawing commands.
+ */
+export declare abstract class RenderContext extends Render2DContext implements MeasureScope {
+    abstract measureText(text: string, fontSize: number, fontFamily: string, fontWeight?: number, letterSpacing?: number, fontStyle?: FontStyle): number;
+    /** Stack of node ids currently being drawn, innermost last. */
+    protected currentNodeStack: string[];
+    /** Returns the id of the innermost node currently being drawn. */
+    protected currentNodeId(): string;
+    /** Remove all renderer-side resources for the current node (called on unmount). */
+    abstract unmount(): void;
+    private _disposed;
+    /** `true` after `dispose()` — the context must not be used after this point. */
+    isDisposed(): boolean;
+    dispose(): void;
+    /**
+     * Execute `callback`, which issues shape/paint calls, and flush the result
+     * to the underlying render target (canvas, SVG document, etc.).
+     */
+    abstract render(callback: () => void): void;
+    /** Capture the current frame as a base-64 PNG data URL, or `undefined` if unsupported. */
+    abstract screenshot(): string | undefined;
+    /**
+     * Push a transform (position, rotation, scale, opacity, …) and return
+     * `this` so subsequent draw calls are issued in the transformed space.
+     * The transform is popped when `end()` is called for the node that pushed it.
+     */
+    abstract transform(state: Partial<TransformState>): RenderContext;
+    /**
+     * Open a boolean-path collection scope. Shapes drawn until `endBoolean()`
+     * are gathered (fills/strokes suppressed) and combined with `op`. The
+     * merged path is returned as a `Render2DPaintContext` so callers can
+     * style the combined result with `.fill()` / `.stroke()` / `.shadow()`.
+     */
+    abstract beginBoolean(op: BooleanOperation): void;
+    abstract endBoolean(): Render2DPaintContext;
+    abstract mask(options?: MaskOptions): Render2DPaintContext;
+    abstract beginMask(options?: MaskOptions): void;
+    abstract applyMask(): Render2DPaintContext;
+    abstract endMask(): void;
+    /**
+     * Push a rectangular clip region so children are confined to the node's
+     * rect boundary. Paired with `endClip()`.
+     */
+    abstract beginClipRect(state: Partial<RectState>): void;
+    /** Push an elliptical clip region. Paired with `endClip()`. */
+    abstract beginClipEllipse(state: Partial<EllipseState>): void;
+    /** Pop the most-recently pushed clip region. */
+    abstract endClip(): void;
+    /**
+     * Push a silhouette clip built from `shape`'s outline — used by backdrop
+     * effects to confine the effect to the node's exact boundary regardless of
+     * shape type. Paired with `endClip()`. No-op by default; renderers that
+     * don't support it can leave this unimplemented.
+     */
+    beginClipShape(_shape: ClipShape): void;
+    /**
+     * Open a backdrop-blur layer. The already-painted canvas beneath the node
+     * is blurred by `radius` and composited back, clipped to the active
+     * silhouette clip. No-op by default.
+     */
+    beginBackgroundBlur(_radius: number): void;
+    endBackgroundBlur(): void;
+    /**
+     * Open a backdrop-distortion (bulge/pinch or zoom) layer. The backdrop is
+     * warped by a lens centred on the node (`width` × `height`), clipped to
+     * the active silhouette clip. No-op by default.
+     */
+    beginBackgroundDistortion(_effect: BulgePinchEffect | ZoomEffect, _width: number, _height: number): void;
+    endBackgroundDistortion(): void;
+    /**
+     * Open a custom SkSL backdrop layer. The shader receives
+     * `uniform shader u_backdrop` (a snapshot of the canvas beneath the node)
+     * and can produce distortion, ripple, refraction, etc., clipped to the
+     * active silhouette clip. No-op by default.
+     */
+    beginBackdropSkSL(_effect: SkSLEffect, _width: number, _height: number): void;
+    endBackdropSkSL(): void;
+    /**
+     * Push a camera viewport. Clips to `viewport` (canvas-space, centred
+     * coords) and applies the inverse camera transform so children render as
+     * seen through the lens. `heading` rotates the world counter to the camera
+     * angle. Paired with `endCamera()`.
+     *
+     * @param viewport  Bounding rect of the camera node in canvas space.
+     * @param centerOn  World-space point the camera looks at.
+     * @param zoom      Uniform scale applied around `centerOn`.
+     * @param heading   Camera rotation in degrees.
+     */
+    abstract beginCamera(viewport: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, centerOn: Vector2, zoom: number, heading: number): void;
+    abstract endCamera(): void;
+    /**
+     * Reference rects (parent frame / viewport) for each node on the draw
+     * stack, in the node's local space. Kept parallel to `currentNodeStack`
+     * so fills with `space: 'parent' | 'view'` can resolve against them.
+     */
+    protected spaceRectsStack: SpaceRects[];
+    /**
+     * Open a node draw scope. Must be paired with `end()`. Pushes `id` onto
+     * the node stack and records the optional `rects` for gradient-space
+     * resolution.
+     *
+     * @param id    Stable node identifier (used for layer caching, etc.).
+     * @param rects Parent / viewport rects in this node's local space.
+     */
+    begin(id: string, rects?: SpaceRects): void;
+    /** Close the innermost node draw scope opened by `begin()`. */
+    end(): void;
+    /** Reference rects for the node currently being drawn (parent / viewport). */
+    protected currentSpaceRects(): SpaceRects;
+}
+//# sourceMappingURL=render-context.d.ts.map

package/dist/render/render-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-context.d.ts","sourceRoot":"","sources":["../../src/render/render-context.ts"],"names":[],"mappings":"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"}

package/dist/render/render-context.js

@@ -0,0 +1,95 @@
+/**
+ * Low-level shape-drawing API. Each method declares a shape and returns a
+ * `Render2DPaintContext` that lets you chain further shapes and apply paint
+ * (fill / stroke / shadow). Multiple shapes chained before a paint call are
+ * combined into a single surface and painted together.
+ */
+export class Render2DContext {
+}
+/**
+ * The full rendering context passed to every scene-graph node when it draws
+ * itself. Combines shape drawing (`Render2DContext`), text measurement
+ * (`MeasureScope`), and higher-level scoping operations (transforms, masks,
+ * clips, camera, boolean ops, backdrop effects).
+ *
+ * `begin(id)` / `end()` bracket each node's draw call so the context can
+ * track which node is active and look up per-node state (space rects, etc.).
+ * The concrete implementations (`CanvasKitRenderContext`, `SvgRenderContext`,
+ * …) translate these abstract calls into renderer-specific drawing commands.
+ */
+export class RenderContext extends Render2DContext {
+    /** Stack of node ids currently being drawn, innermost last. */
+    currentNodeStack = [];
+    /** Returns the id of the innermost node currently being drawn. */
+    currentNodeId() {
+        if (this.currentNodeStack.length === 0) {
+            throw new Error("No current node in context");
+        }
+        return this.currentNodeStack[this.currentNodeStack.length - 1];
+    }
+    _disposed = false;
+    /** `true` after `dispose()` — the context must not be used after this point. */
+    isDisposed() {
+        return this._disposed;
+    }
+    dispose() {
+        this._disposed = true;
+    }
+    /**
+     * Push a silhouette clip built from `shape`'s outline — used by backdrop
+     * effects to confine the effect to the node's exact boundary regardless of
+     * shape type. Paired with `endClip()`. No-op by default; renderers that
+     * don't support it can leave this unimplemented.
+     */
+    beginClipShape(_shape) { }
+    /**
+     * Open a backdrop-blur layer. The already-painted canvas beneath the node
+     * is blurred by `radius` and composited back, clipped to the active
+     * silhouette clip. No-op by default.
+     */
+    beginBackgroundBlur(_radius) { }
+    endBackgroundBlur() { }
+    /**
+     * Open a backdrop-distortion (bulge/pinch or zoom) layer. The backdrop is
+     * warped by a lens centred on the node (`width` × `height`), clipped to
+     * the active silhouette clip. No-op by default.
+     */
+    beginBackgroundDistortion(_effect, _width, _height) { }
+    endBackgroundDistortion() { }
+    /**
+     * Open a custom SkSL backdrop layer. The shader receives
+     * `uniform shader u_backdrop` (a snapshot of the canvas beneath the node)
+     * and can produce distortion, ripple, refraction, etc., clipped to the
+     * active silhouette clip. No-op by default.
+     */
+    beginBackdropSkSL(_effect, _width, _height) { }
+    endBackdropSkSL() { }
+    /**
+     * Reference rects (parent frame / viewport) for each node on the draw
+     * stack, in the node's local space. Kept parallel to `currentNodeStack`
+     * so fills with `space: 'parent' | 'view'` can resolve against them.
+     */
+    spaceRectsStack = [];
+    /**
+     * Open a node draw scope. Must be paired with `end()`. Pushes `id` onto
+     * the node stack and records the optional `rects` for gradient-space
+     * resolution.
+     *
+     * @param id    Stable node identifier (used for layer caching, etc.).
+     * @param rects Parent / viewport rects in this node's local space.
+     */
+    begin(id, rects) {
+        this.currentNodeStack.push(id);
+        this.spaceRectsStack.push(rects ?? {});
+    }
+    /** Close the innermost node draw scope opened by `begin()`. */
+    end() {
+        this.currentNodeStack.pop();
+        this.spaceRectsStack.pop();
+    }
+    /** Reference rects for the node currently being drawn (parent / viewport). */
+    currentSpaceRects() {
+        return this.spaceRectsStack[this.spaceRectsStack.length - 1] ?? {};
+    }
+}
+//# sourceMappingURL=render-context.js.map

package/dist/render/render-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-context.js","sourceRoot":"","sources":["../../src/render/render-context.ts"],"names":[],"mappings":"AAqEA;;;;;GAKG;AACH,MAAM,OAAgB,eAAe;CAmBpC;AA6CD;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,aAAc,SAAQ,eAAe;IAGvD,+DAA+D;IACrD,gBAAgB,GAAa,EAAE,CAAC;IAE1C,kEAAkE;IACxD,aAAa;QACnB,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAClD,CAAC;QAED,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnE,CAAC;IAKO,SAAS,GAAG,KAAK,CAAC;IAC1B,gFAAgF;IAChF,UAAU;QACN,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IACD,OAAO;QACH,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IAC1B,CAAC;IAkED;;;;;OAKG;IACH,cAAc,CAAC,MAAiB,IAAU,CAAC;IAE3C;;;;OAIG;IACH,mBAAmB,CAAC,OAAe,IAAU,CAAC;IAC9C,iBAAiB,KAAW,CAAC;IAE7B;;;;OAIG;IACH,yBAAyB,CAAC,OAAsC,EAAE,MAAc,EAAE,OAAe,IAAU,CAAC;IAC5G,uBAAuB,KAAW,CAAC;IAEnC;;;;;OAKG;IACH,iBAAiB,CAAC,OAAmB,EAAE,MAAc,EAAE,OAAe,IAAU,CAAC;IACjF,eAAe,KAAW,CAAC;IAkB3B;;;;OAIG;IACO,eAAe,GAAiB,EAAE,CAAC;IAE7C;;;;;;;OAOG;IACH,KAAK,CAAC,EAAU,EAAE,KAAkB;QAChC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,+DAA+D;IAC/D,GAAG;QACC,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,CAAC;QAC5B,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,CAAC;IAC/B,CAAC;IAED,8EAA8E;IACpE,iBAAiB;QACvB,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACvE,CAAC;CAIJ"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,4 @@
+export * from './playback-controller';
+export * from './state-evaluator';
+export * from './precompisition';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/runtime/index.js

@@ -0,0 +1,4 @@
+export * from './playback-controller';
+export * from './state-evaluator';
+export * from './precompisition';
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/runtime/playback-controller.d.ts

@@ -0,0 +1,105 @@
+import { MeasureScope } from "../render/measure-scope";
+import { RenderContext } from "../render/render-context";
+import { NodeState, TreeState } from "../project/tree";
+import { StorageAdapter } from "../platform/storage-adapter";
+import { Precomp, PrecompResult } from "./precompisition";
+import { Scene } from "../nodes/base/scene-node";
+import { MasterClock, TimeCallback } from "../platform/master-clock";
+import { AudioDevice } from "../platform/audio-device";
+import { AssetCatalog } from "../assets/catalog";
+import { Size2D } from "../attributes/layout/size";
+import { Node } from "../nodes/base/node";
+/** Dependencies injected into `PlaybackController` at construction time. */
+export type ControllerParams = {
+    renderContext: RenderContext;
+    measureScope: MeasureScope;
+    storageAdapter: StorageAdapter;
+    masterClock: MasterClock;
+    audioDevice: AudioDevice;
+    assets: AssetCatalog;
+    precomposition: Precomp;
+    fps: number;
+    viewport: Size2D;
+    scenes: Scene[];
+};
+/**
+ * Orchestrates playback of a compiled motion-script project.
+ *
+ * On construction it runs the precomp pass (`Precomp.run()`) to build the
+ * global asset timeline and node lifespans, then wires the master clock to
+ * the audio device and render pipeline so every tick:
+ *
+ * 1. Loads assets required at the current frame (`AssetManager.loadAt`).
+ * 2. Evaluates scene state and lays out nodes (`StateEvaluator`).
+ * 3. Renders the frame to the render context.
+ * 4. Prefetches assets for upcoming frames.
+ *
+ * External callers interact via `play`, `pause`, `seek`, `seekWhilePlaying`,
+ * `screenshot`, `getTreeState`, and `getNodeState`.
+ */
+export declare class PlaybackController {
+    private renderContext;
+    private measureScope;
+    private storageAdapter;
+    private masterClock;
+    private stateEvaluator;
+    private assetManager;
+    private audioDevice;
+    readonly fps: number;
+    readonly viewport: Size2D;
+    readonly precomp: PrecompResult;
+    /** Per-scene frame counts in timeline order, used to build the track list. */
+    get tracks(): number[];
+    /** Total frame count across all scenes. */
+    get totalFrames(): number;
+    /** Total playback duration in seconds. */
+    get totalDuration(): number;
+    /** Errors collected during the precomp pass (one entry per failing scene). */
+    get buildErrors(): import("./precompisition").BuildError[];
+    constructor(params: ControllerParams);
+    get isPlaying(): boolean;
+    /** Current playback position in seconds. */
+    get currentTime(): number;
+    /** Current playback position in frames (float). */
+    get currentFrame(): number;
+    /** Register a callback that fires on every clock tick with the current time. */
+    onTime(cb: TimeCallback): void;
+    /** Register a callback that fires when playback starts. */
+    onPlay(cb: () => void): void;
+    /** Register a callback that fires when playback pauses. */
+    onPause(cb: () => void): void;
+    /**
+     * Evaluate scene state, lay out nodes, and render `frame` to the render
+     * context. Called on every clock tick and also directly by `seek` /
+     * `screenshot` to ensure the surface is up-to-date.
+     */
+    private renderAt;
+    /**
+     * Jump to `frame`, pausing playback first. Waits for required assets to
+     * load before rendering, then prefetches upcoming frames.
+     */
+    seek(frame: number): Promise<void>;
+    /** Reposition the clock to `frame` without interrupting playback. */
+    seekWhilePlaying(frame: number): void;
+    /**
+     * Capture the current frame as a base-64 PNG data URL. Forces a fresh
+     * render before snapshotting because the WebGL drawing buffer may have
+     * been cleared since the last tick (we don't set `preserveDrawingBuffer`).
+     * Uses `stateEvaluator.currentFrame` (integer) rather than the clock's
+     * float so `stateAt` always hits its early-return and never resets scene state.
+     */
+    screenshot(): string | undefined;
+    /**
+     * Return the full node tree for the current scene, with lifespan frame
+     * ranges and waveform data attached. Used by the timeline UI.
+     * Returns `null` when no scene is active.
+     */
+    getTreeState(): TreeState | null;
+    getNodeState(nodeId: string): NodeState | null;
+    play(speed?: number, reverse?: boolean): void;
+    pause(): void;
+    setMuted(muted: boolean): void;
+    dispose(): void;
+}
+export declare function isParentNode(node: Node): boolean;
+//# sourceMappingURL=playback-controller.d.ts.map

package/dist/runtime/playback-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playback-controller.d.ts","sourceRoot":"","sources":["../../src/runtime/playback-controller.ts"],"names":[],"mappings":"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"}