@motionscript/react 0.0.0-stage → 0.1.0-alpha.0

package/dist/ui/stage.d.ts

@@ -0,0 +1,98 @@
+import { CSSProperties } from 'react';
+import { Size2D } from '@motionscript/core';
+import { Player } from './use-motion-player';
+export interface MotionStageProps {
+    /** The player whose session this stage draws. */
+    player: Player;
+    /**
+     * Device pixels to rasterize per viewport unit. Defaults to `1`.
+     *
+     * **Not a zoom and not a crop.** The viewport stays the scene's logical
+     * coordinate space; this only changes how many real pixels that space is
+     * drawn into, and CSS scales the canvas back up to fill its box.
+     *
+     * The lever exists because a preview is usually displayed far smaller than
+     * the project's output size: a 1920×1080 project in a 700px-wide panel
+     * rasterizes roughly seven times the pixels anyone can see. `0.5` there is a
+     * quarter of the fill, the shader work and the effect offscreens.
+     *
+     * Two things to know before animating it:
+     *
+     * - **Every change re-creates the Skia surface**, which drops the storage
+     *   adapter's texture-backed images (decoded video frames, 3D composites;
+     *   still images survive) and asks for a fresh GL context. Quantize to a few
+     *   steps and let it settle — never drive it from a resize observer.
+     * - **Prefer scales that keep both dimensions whole.** `pixelRatio` is one
+     *   uniform number, so a scale that rounds differently on each axis shifts
+     *   the frame's centre by up to half a device pixel.
+     *
+     * A snapshot from `player.screenshot()` comes back at the surface's size, so
+     * it is scaled too — render at `1` if you need full resolution out of it.
+     */
+    renderScale?: number;
+    /**
+     * The canvas's own size in CSS pixels, when it is **not** the frame.
+     *
+     * Omitted — the default — the canvas is the frame: sized `viewport ×
+     * renderScale` and stretched over its box by CSS, which is what every
+     * export, thumbnail and plain player wants.
+     *
+     * Supplied, together with {@link view}, the canvas becomes a *window* onto
+     * the frame: it takes the size of the area it is shown in, `renderScale`
+     * stops meaning "fraction of the project's resolution" and starts meaning
+     * device pixels per CSS pixel, and only what is on screen is rasterized.
+     * That is what lets an editor zoom in without going soft or paying for the
+     * whole frame at the zoomed resolution.
+     *
+     * It re-creates the surface exactly as `renderScale` does, and wants the
+     * same treatment: quantize it and let it settle.
+     */
+    surfaceSize?: Size2D;
+    /**
+     * A pan and zoom applied to the render itself. Requires {@link surfaceSize}.
+     *
+     * `zoom` multiplies scene units; `x`/`y` offset the frame's centre in CSS
+     * pixels, positive `y` downwards — the same sign convention as a CSS
+     * translate, so a preview can hand over the pan it was already computing.
+     *
+     * Changing it costs a repaint and nothing else: no surface, no textures, no
+     * precomp. That is the point of it living here rather than in a CSS
+     * transform, which cannot add resolution it was not rasterized with.
+     */
+    view?: {
+        zoom: number;
+        x: number;
+        y: number;
+    };
+    /**
+     * Whether the frame's edge bounds what draws, rather than only where its own
+     * backdrop goes. Requires {@link surfaceSize} and {@link view}. Defaults to
+     * `true`.
+     *
+     * Off lets a node parked past the frame's edge rasterize into the rest of
+     * the surface instead of being discarded — for a host that wants to show,
+     * faded, what a node placed there while animating in or out.
+     */
+    clipToFrame?: boolean;
+    /**
+     * What the frame's backdrop is painted with. Defaults to `"black"`.
+     *
+     * `"transparent"` leaves the frame unpainted where nothing was drawn, so
+     * whatever the host renders behind the canvas shows through — a
+     * checkerboard, for an editor that has to distinguish "no scene covers this"
+     * from "a scene covers it in black". Requires {@link surfaceSize} and
+     * {@link view}, the same way {@link clipToFrame} does.
+     */
+    frameBackground?: "black" | "transparent";
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A canvas bound to a {@link Player}'s session.
+ *
+ * The stage owns how the frame is rasterized — resolution, view, clipping — and
+ * nothing about what is in it or when. A session drives **one** surface, so one
+ * stage per player: a second would take the surface from the first.
+ */
+export declare function MotionStage({ player, renderScale, surfaceSize, view, clipToFrame, frameBackground, className, style, }: MotionStageProps): import("react").JSX.Element;
+//# sourceMappingURL=stage.d.ts.map

package/dist/ui/stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/ui/stage.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAE9D,OAAO,KAAK,EAAuB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAsBlD,MAAM,WAAW,gBAAgB;IAC7B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EACxB,MAAM,EACN,WAAe,EACf,WAAW,EACX,IAAI,EACJ,WAAW,EACX,eAAe,EACf,SAAS,EACT,KAAK,GACR,EAAE,gBAAgB,+BAgJlB"}

package/dist/ui/use-motion-player.d.ts

@@ -0,0 +1,156 @@
+import { BuildError, Engine, NodeBox, Node3DFrame, NodeOverride, NodeState, NodeTextLayout, ProjectDocument, SceneDocument, Session, Size2D, TrackSpan, TreeState, Vector2, Vector3 } from '@motionscript/core';
+import { PlayheadStore } from './playhead';
+/**
+ * How far background discovery has got. Only the tracks on frame 0 are
+ * discovered before the player mounts; the rest stream in behind it (see
+ * `AssetTimeline.runAsync`). The timeline's length never waits on it — every track
+ * declares its own.
+ */
+export interface PrecompProgress {
+    /** Tracks discovered so far. */
+    discoveredTracks: number;
+    /** Tracks in the project. */
+    totalTracks: number;
+    /** True once every track has been discovered. */
+    complete: boolean;
+}
+export interface MotionPlayerOptions {
+    /**
+     * The engine this player opens its session on.
+     *
+     * Nullable on purpose: building one is asynchronous
+     * (`await createBrowserEngine(...)`), so a host holds it in state and it is
+     * `null` for the first render or two. The player no-ops until it arrives,
+     * which is what keeps the hook out of a conditional.
+     *
+     * **Create it once, and share it.** It holds CanvasKit and the exporter, so
+     * a fresh one per render rebuilds the WebGL surface behind every player on
+     * it. Identity-compared: a different engine is a different CanvasKit, and so
+     * a full rebuild.
+     */
+    engine: Engine | null | undefined;
+    /**
+     * What to play. Nothing opens until there is one.
+     *
+     * A **project** document is the whole answer: it carries its own viewport,
+     * fps, theme and tracks. A **scene** document (still or composition) is one
+     * clip and carries none of that, so `viewport` and `fps` must come from here
+     * or from the engine.
+     *
+     * Content-diffed, with identity as the fast path: a new document is reconciled
+     * onto the running session, each track's built tree patched in place and
+     * rebuilt only when its change cannot be patched. Treat documents as
+     * immutable — an edit made in place to one the player already holds is not
+     * seen.
+     *
+     * A new document keeps the player's place: the playhead stays where it was
+     * (clamped when the timeline got shorter), and playback carries on if it was
+     * running. Seek or pause yourself when a swap means "start over".
+     */
+    document?: ProjectDocument | SceneDocument;
+    /** Overrides the engine's, for a source that carries none. */
+    viewport?: Size2D;
+    /** Overrides the engine's, for a source that carries none. */
+    fps?: number;
+    /** Initial playback rate. Change it later with {@link Player.setSpeed}. */
+    speed?: number;
+    /** Initial mute state. Change it later with {@link Player.setMuted}. */
+    muted?: boolean;
+    /** Initial loop state. Change it later with {@link Player.setLoop}. */
+    loop?: boolean;
+    /**
+     * Called **synchronously**, on the same task as the draw, each time a frame
+     * has been painted — whether by the clock, a seek, or a document swap.
+     *
+     * Not the playhead, which reports where the *clock* is. A seek is
+     * asynchronous, so between the two there is a window in which the number has
+     * moved and the canvas has not. Reach for this to keep an overlay — a
+     * selection box, a caret, a handle — in step with the pixels, and keep the
+     * listener cheap: it runs on the render loop, before the browser has had a
+     * chance to composite.
+     *
+     * Read through a ref, so changing it costs nothing.
+     */
+    onFramePainted?: (frame: number) => void;
+}
+/**
+ * One document, its transport, and the session driving it. No DOM.
+ *
+ * Hand it to a {@link MotionStage} to put pixels on screen. Two calls to
+ * {@link useMotionPlayer} produce two of these with nothing shared but the
+ * engine — separate playheads, clocks, audio devices and transports.
+ */
+export interface Player {
+    /** The live session, or `null` before the engine and a document arrive. */
+    readonly session: Session | null;
+    /** The playhead, read with `usePlayhead(player)`. Stable for the hook's life. */
+    readonly playhead: PlayheadStore;
+    /** Resolved from the document, else the engine, else 1920×1080. */
+    readonly viewport: Size2D;
+    /** Resolved from the document, else the engine, else 60. */
+    readonly fps: number;
+    readonly isPlaying: boolean;
+    readonly speed: number;
+    readonly muted: boolean;
+    readonly loop: boolean;
+    /** True while a seek or a document swap is in flight. */
+    readonly loading: boolean;
+    /** The project's length, known from the document before any track is discovered. */
+    readonly duration: number;
+    /** {@link duration} in frames, floored at 1. */
+    readonly totalFrames: number;
+    readonly errors: BuildError[];
+    readonly precomp: PrecompProgress;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Seek while paused. Clamped to the timeline. */
+    seek(frame: number): void;
+    /** Seek relative to where the playhead is now. */
+    step(delta: number): void;
+    /** Seek without interrupting playback. */
+    seekWhilePlaying(frame: number): void;
+    setSpeed(speed: number): void;
+    setMuted(muted: boolean): void;
+    setLoop(loop: boolean): void;
+    screenshot(): Promise<string | undefined>;
+    /** Re-layout and repaint the current frame — no re-evaluation. */
+    repaint(): void;
+    getTreeState(): TreeState | null;
+    getNodeProps(nodeId: string): NodeState | null;
+    /** Where each track sits on the timeline, in document order. */
+    getTrackSpans(): readonly TrackSpan[];
+    /**
+     * Resolves once the paint a document swap scheduled has landed. The swap
+     * does not paint before its assets have loaded, so await this before
+     * screenshotting or reading the tree.
+     */
+    whenReplaced(): Promise<void>;
+    getNodeBox(path: string): NodeBox | null;
+    getNodePropsAt(path: string): NodeState["properties"] | null;
+    getNodeBoxes(): NodeBox[];
+    projectNode3D(path: string, parentPoints: readonly Vector3[], localPoints: readonly Vector3[]): Node3DFrame | null;
+    /**
+     * Where `point` lands on the plane the node at `path` is positioned in, in
+     * that plane's own y-up frame. Two answers differ by the `x`/`y` change that
+     * moves the node between them — which a screen delta no longer is once the
+     * node sits in a 2.5D space.
+     */
+    parentPlanePoint(path: string, point: Vector2): Vector2 | null;
+    getTextLayout(path: string): NodeTextLayout | null;
+    /** `tolerance` is grab-slop in scene units. */
+    pickNode(point: Vector2, tolerance?: number): NodeBox | null;
+    /** Layer transient props over a node without rebuilding its track. */
+    setNodeOverride(path: string, props: NodeOverride): void;
+    clearNodeOverrides(path?: string): void;
+}
+/**
+ * Opens a session on `engine` and gives you the transport for it.
+ *
+ * ```tsx
+ * const player = useMotionPlayer({ engine, document: doc, loop: true });
+ * <MotionStage player={player} />
+ * ```
+ */
+export declare function useMotionPlayer(options: MotionPlayerOptions): Player;
+//# sourceMappingURL=use-motion-player.d.ts.map

package/dist/ui/use-motion-player.d.ts.map

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

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@motionscript/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "description": "React bindings for Motion Script.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/motionscript-dev/motionscript.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://motionscript.dev",
+  "bugs": {
+    "url": "https://github.com/motionscript-dev/motionscript/issues"
+  },
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "module": "./dist/motionscript-react.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/motionscript-react.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "@motionscript/core": "^0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^25.6.2",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "react": "^19.2.3",
+    "globals": "^16.5.0",
+    "react-dom": "^19.2.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^8.0.11",
+    "vite-plugin-dts": "5.0.0",
+    "@motionscript/core": "0.1.0-alpha.0",
+    "@motionscript/browser": "0.1.0-alpha.0",
+    "@motionscript/canvaskit": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "eslint . && tsc -p tsconfig.build.json && vite build && node ../../scripts/build-browser.mjs",
+    "lint": "eslint .",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf --glob dist .turbo *.tsbuildinfo",
+    "preview": "vite preview"
+  }
 }