@machinal/scenes 0.0.0-stage → 0.1.1

package/dist/runtime/bridge.js

@@ -0,0 +1,76 @@
+const COMMAND = 'scene-engine:command';
+const RESPONSE = 'scene-engine:response';
+export function exposeScene(controller, view = window) {
+    view.__scene = controller;
+    const receive = async (event) => {
+        const command = event.data;
+        if (event.source !== view.parent || event.origin !== view.location.origin)
+            return;
+        if (command?.type !== COMMAND || typeof command.id !== 'string')
+            return;
+        try {
+            if (command.method === 'seek')
+                await controller.seek(command.frame);
+            else if (command.method === 'ready')
+                await controller.ready();
+            else
+                throw new Error('Unknown scene command');
+            view.parent.postMessage({ type: RESPONSE, id: command.id, manifest: controller.manifest }, event.origin);
+        }
+        catch (error) {
+            view.parent.postMessage({ type: RESPONSE, id: command.id, error: error instanceof Error ? error.message : String(error) }, event.origin);
+        }
+    };
+    view.addEventListener('message', receive);
+    return () => {
+        view.removeEventListener('message', receive);
+        if (view.__scene === controller)
+            delete view.__scene;
+    };
+}
+export function connectScene(iframe, timeoutMs = 30_000) {
+    const view = iframe.ownerDocument.defaultView;
+    const origin = new URL(iframe.src, view.location.href).origin;
+    const pending = new Map();
+    let disposed = false;
+    const receive = (event) => {
+        if (event.source !== iframe.contentWindow || event.origin !== origin || event.data?.type !== RESPONSE)
+            return;
+        const entry = pending.get(event.data.id);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        pending.delete(event.data.id);
+        if (event.data.error)
+            entry.reject(new Error(event.data.error));
+        else
+            entry.resolve(event.data.manifest);
+    };
+    const send = (method, frame) => {
+        if (disposed)
+            return Promise.reject(new Error('Scene connection disposed'));
+        return new Promise((resolve, reject) => {
+            const id = crypto.randomUUID();
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new Error(`Scene ${method} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            pending.set(id, { resolve, reject, timer });
+            iframe.contentWindow.postMessage({ type: COMMAND, id, method, frame }, origin);
+        });
+    };
+    view.addEventListener('message', receive);
+    return {
+        ready: () => send('ready'),
+        seek: (frame) => send('seek', frame),
+        dispose() {
+            disposed = true;
+            view.removeEventListener('message', receive);
+            for (const entry of pending.values()) {
+                clearTimeout(entry.timer);
+                entry.reject(new Error('Scene connection disposed'));
+            }
+            pending.clear();
+        },
+    };
+}

package/dist/runtime/choreography.d.ts

@@ -0,0 +1,32 @@
+export type Easing = (progress: number) => number;
+export declare const easing: {
+    linear: (p: number) => number;
+    inOutCubic: (p: number) => number;
+    outQuint: (p: number) => number;
+    smooth: (p: number) => number;
+};
+export interface Cue {
+    id: string;
+    start: number;
+    duration: number;
+}
+export interface CueState {
+    start: number;
+    end: number;
+    progress: number;
+    active: boolean;
+}
+export declare function progressAt(time: number, start: number, duration: number, curve?: Easing): number;
+export declare function stagger(index: number, interval: number, start?: number): number;
+/** Times are scene-local seconds; evaluation never depends on previous seeks. */
+export declare function createChoreography(cues: readonly Cue[]): Readonly<{
+    marker(id: string, edge?: "start" | "end"): number;
+    at(id: string, time: number, curve?: Easing): CueState;
+}>;
+export interface SpringOptions {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+}
+/** Analytic unit-step response: safe for backward/out-of-order frame evaluation. */
+export declare function springAt(time: number, { stiffness, damping, mass }?: SpringOptions): number;

package/dist/runtime/choreography.js

@@ -0,0 +1,81 @@
+import { clamp } from './math.js';
+export const easing = {
+    linear: (p) => clamp(p),
+    inOutCubic: (p) => { const t = clamp(p); return t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2; },
+    outQuint: (p) => 1 - (1 - clamp(p)) ** 5,
+    smooth: (p) => { const t = clamp(p); return t * t * (3 - 2 * t); },
+};
+function finite(value, name) {
+    if (!Number.isFinite(value))
+        throw new Error(`${name} must be finite`);
+    return value;
+}
+export function progressAt(time, start, duration, curve = easing.linear) {
+    finite(time, 'time');
+    finite(start, 'start');
+    finite(duration, 'duration');
+    if (duration < 0)
+        throw new Error('duration must not be negative');
+    return curve(duration === 0 ? Number(time >= start) : clamp((time - start) / duration));
+}
+export function stagger(index, interval, start = 0) {
+    if (!Number.isSafeInteger(index) || index < 0)
+        throw new Error('index must be a nonnegative integer');
+    finite(interval, 'interval');
+    finite(start, 'start');
+    if (interval < 0)
+        throw new Error('interval must not be negative');
+    return finite(start + index * interval, 'stagger result');
+}
+/** Times are scene-local seconds; evaluation never depends on previous seeks. */
+export function createChoreography(cues) {
+    const events = new Map();
+    for (const cue of cues) {
+        if (!cue.id.trim() || events.has(cue.id))
+            throw new Error('Cue IDs must be nonempty and unique');
+        finite(cue.start, 'start');
+        finite(cue.duration, 'duration');
+        if (cue.start < 0 || cue.duration < 0)
+            throw new Error('Cue times must not be negative');
+        finite(cue.start + cue.duration, 'cue end');
+        events.set(cue.id, Object.freeze({ ...cue }));
+    }
+    const get = (id) => {
+        const cue = events.get(id);
+        if (!cue)
+            throw new Error(`Unknown cue: ${id}`);
+        return cue;
+    };
+    return Object.freeze({
+        marker(id, edge = 'start') {
+            const cue = get(id);
+            return cue.start + (edge === 'end' ? cue.duration : 0);
+        },
+        at(id, time, curve = easing.linear) {
+            const cue = get(id);
+            return { start: cue.start, end: cue.start + cue.duration, progress: progressAt(time, cue.start, cue.duration, curve), active: time >= cue.start && time < cue.start + cue.duration };
+        },
+    });
+}
+/** Analytic unit-step response: safe for backward/out-of-order frame evaluation. */
+export function springAt(time, { stiffness = 170, damping = 26, mass = 1 } = {}) {
+    finite(time, 'time');
+    for (const [name, value] of Object.entries({ stiffness, damping, mass })) {
+        if (finite(value, name) <= 0)
+            throw new Error(`${name} must be positive`);
+    }
+    if (time <= 0)
+        return 0;
+    const omega = Math.sqrt(stiffness / mass);
+    const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+    if (Math.abs(zeta - 1) < 1e-6)
+        return 1 - Math.exp(-omega * time) * (1 + omega * time);
+    if (zeta < 1) {
+        const wd = omega * Math.sqrt(1 - zeta * zeta);
+        return 1 - Math.exp(-zeta * omega * time) * (Math.cos(wd * time) + zeta * omega / wd * Math.sin(wd * time));
+    }
+    const root = Math.sqrt(zeta * zeta - 1);
+    const r1 = -omega / (zeta + root);
+    const r2 = -omega * (zeta + root);
+    return 1 - (r2 * Math.exp(r1 * time) - r1 * Math.exp(r2 * time)) / (r2 - r1);
+}

package/dist/runtime/controller.d.ts

@@ -0,0 +1,5 @@
+import { type SceneController, type SceneDefinition, type SceneProps, type SceneRenderOptions, type SceneRequest } from './types.js';
+export interface MountOptions extends SceneRenderOptions {
+    settle?: (target: HTMLElement) => Promise<void>;
+}
+export declare function mountScene<P extends SceneProps>(definition: SceneDefinition<P>, target: HTMLElement, request: SceneRequest, options?: MountOptions): SceneController;

package/dist/runtime/controller.js

@@ -0,0 +1,93 @@
+import { seededRandom } from './math.js';
+import { abortable, createResourceScope, seekCssAnimations, waitForVisualResources } from './resources.js';
+import { PROTOCOL_VERSION } from './types.js';
+import { validateFrame, validateRequest } from './validation.js';
+import { presentSceneVideos, seekSceneVideos } from './media.js';
+import { createObjectRegistry } from './objects.js';
+export function mountScene(definition, target, request, options = {}) {
+    validateRequest(request);
+    if (request.sceneId !== definition.id)
+        throw new Error(`Unknown scene: ${request.sceneId}`);
+    const config = Object.freeze({ ...request.config });
+    const props = structuredClone({ ...definition.defaults, ...request.props });
+    const seed = request.seed ?? 'scene-engine';
+    const manifest = { version: PROTOCOL_VERSION, sceneId: definition.id, props, seed, config };
+    const abort = new AbortController();
+    const resources = createResourceScope(abort.signal);
+    const objects = createObjectRegistry();
+    let currentFrame = frameContext(0, config, seed, options);
+    const instance = Promise.resolve().then(() => definition.create({ target, props, config, resources, objects }));
+    let queue = Promise.resolve();
+    let disposed = false;
+    let disposal;
+    const settle = async (time) => {
+        await resources.wait();
+        await seekSceneVideos(target, time, abort.signal);
+        await abortable((options.settle ?? waitForVisualResources)(target), abort.signal);
+        await resources.wait();
+    };
+    const initialReady = instance.then(async (created) => {
+        await abortable(Promise.resolve(created.update(currentFrame)), abort.signal);
+        seekCssAnimations(target, 0);
+        await settle(0);
+    });
+    void initialReady.catch(() => undefined);
+    return {
+        version: PROTOCOL_VERSION,
+        manifest,
+        async ready() {
+            assertActive(disposed);
+            await initialReady;
+        },
+        seek(frame, seekOptions) {
+            assertActive(disposed);
+            validateFrame(frame, config);
+            const operation = queue.then(async () => {
+                assertActive(disposed);
+                await initialReady;
+                const created = await instance;
+                currentFrame = frameContext(frame, config, seed, { ...options, ...seekOptions });
+                await abortable(Promise.resolve(created.update(currentFrame)), abort.signal);
+                seekCssAnimations(target, frame / config.fps);
+                if (seekOptions?.realtime) {
+                    presentSceneVideos(target, frame / config.fps, seekOptions.playbackRate ?? 1);
+                }
+                else
+                    await settle(frame / config.fps);
+                assertActive(disposed);
+            });
+            queue = operation.catch(() => undefined);
+            return operation;
+        },
+        dispose() {
+            if (disposal)
+                return disposal;
+            disposed = true;
+            abort.abort(new Error('Scene disposed'));
+            disposal = queue.then(async () => {
+                const created = await instance;
+                await created.dispose();
+            }).finally(() => objects.clear());
+            return disposal;
+        },
+        snapshotObjects() {
+            assertActive(disposed);
+            return objects.snapshot(currentFrame);
+        },
+    };
+}
+function assertActive(disposed) {
+    if (disposed)
+        throw new Error('Scene disposed');
+}
+function frameContext(frame, config, seed, options) {
+    return {
+        frame,
+        time: frame / config.fps,
+        progress: config.durationInFrames === 1 ? 0 : frame / (config.durationInFrames - 1),
+        config,
+        renderScale: options.renderScale && Number.isFinite(options.renderScale) && options.renderScale > 0 ? Math.min(1, options.renderScale) : 1,
+        capture: options.capture ?? true,
+        random: (key) => seededRandom(seed, key),
+    };
+}

package/dist/runtime/geometry.d.ts

@@ -0,0 +1,20 @@
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Bounds extends Point {
+    width: number;
+    height: number;
+}
+export interface Pose2D extends Point {
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+}
+export type Anchor = 'center' | 'top' | 'right' | 'bottom' | 'left';
+export declare function anchorPoint(bounds: Bounds, anchor?: Anchor): Point;
+/** Rotation is in radians, around the subject's local origin. */
+export declare function transformPoint(point: Point, pose: Pose2D): Point;
+export declare function bezierPoint(points: readonly [Point, Point, Point, Point], progress: number): Point;
+export declare function connectorPath(from: Point, to: Point, bend?: number): string;
+export declare function interpolatePose(from: Pose2D, to: Pose2D, progress: number): Pose2D;

package/dist/runtime/geometry.js

@@ -0,0 +1,34 @@
+import { clamp } from './math.js';
+export function anchorPoint(bounds, anchor = 'center') {
+    const x = bounds.x + bounds.width / 2;
+    const y = bounds.y + bounds.height / 2;
+    switch (anchor) {
+        case 'top': return { x, y: bounds.y };
+        case 'right': return { x: bounds.x + bounds.width, y };
+        case 'bottom': return { x, y: bounds.y + bounds.height };
+        case 'left': return { x: bounds.x, y };
+        default: return { x, y };
+    }
+}
+/** Rotation is in radians, around the subject's local origin. */
+export function transformPoint(point, pose) {
+    const x = point.x * pose.scaleX;
+    const y = point.y * pose.scaleY;
+    const cos = Math.cos(pose.rotation), sin = Math.sin(pose.rotation);
+    return { x: pose.x + x * cos - y * sin, y: pose.y + x * sin + y * cos };
+}
+export function bezierPoint(points, progress) {
+    const t = clamp(progress), u = 1 - t;
+    const [a, b, c, d] = points;
+    const sample = (key) => u ** 3 * a[key] + 3 * u * u * t * b[key] + 3 * u * t * t * c[key] + t ** 3 * d[key];
+    return { x: sample('x'), y: sample('y') };
+}
+export function connectorPath(from, to, bend = 0.5) {
+    const middle = from.x + (to.x - from.x) * clamp(bend);
+    return `M ${from.x} ${from.y} C ${middle} ${from.y}, ${middle} ${to.y}, ${to.x} ${to.y}`;
+}
+export function interpolatePose(from, to, progress) {
+    const t = clamp(progress);
+    const mix = (a, b) => a + (b - a) * t;
+    return { x: mix(from.x, to.x), y: mix(from.y, to.y), rotation: mix(from.rotation, to.rotation), scaleX: mix(from.scaleX, to.scaleX), scaleY: mix(from.scaleY, to.scaleY) };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './validation.js';
+export * from './math.js';
+export * from './resources.js';
+export * from './controller.js';
+export * from './bridge.js';
+export * from './artifact.js';
+export * from './video.js';
+export * from './choreography.js';
+export * from './geometry.js';
+export * from './parameters.js';
+export * from './models.js';
+export * from './objects.js';
+export * from './layout.js';

package/dist/runtime/index.js

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './validation.js';
+export * from './math.js';
+export * from './resources.js';
+export * from './controller.js';
+export * from './bridge.js';
+export * from './artifact.js';
+export * from './video.js';
+export * from './choreography.js';
+export * from './geometry.js';
+export * from './parameters.js';
+export * from './models.js';
+export * from './objects.js';
+export * from './layout.js';

package/dist/runtime/layout.d.ts

@@ -0,0 +1,17 @@
+import { type Anchor, type Bounds, type Point } from './geometry.js';
+export interface LabelPlacement {
+    bounds: Bounds;
+    side: Anchor;
+    anchor: Point;
+    fits: boolean;
+    collisions: number;
+}
+/** Deterministic candidate placement, not a DOM/physics solver or caption reflow. */
+export declare function placeAnchoredLabel(subject: Bounds, size: {
+    width: number;
+    height: number;
+}, stage: Bounds, options?: {
+    sides?: readonly Anchor[];
+    gap?: number;
+    obstacles?: readonly Bounds[];
+}): LabelPlacement;

package/dist/runtime/layout.js

@@ -0,0 +1,48 @@
+import { anchorPoint } from './geometry.js';
+function intersects(a, b) {
+    return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+function validateBounds(bounds) {
+    if (![bounds.x, bounds.y, bounds.width, bounds.height].every(Number.isFinite) || bounds.width < 0 || bounds.height < 0)
+        throw new Error('Layout needs finite nonnegative bounds');
+}
+/** Deterministic candidate placement, not a DOM/physics solver or caption reflow. */
+export function placeAnchoredLabel(subject, size, stage, options = {}) {
+    validateBounds(subject);
+    validateBounds(stage);
+    validateBounds({ x: 0, y: 0, width: size.width, height: size.height });
+    const gap = options.gap ?? 16;
+    const sides = options.sides ?? ['right', 'left', 'top', 'bottom'];
+    const obstacles = options.obstacles ?? [];
+    if (!Number.isFinite(gap) || gap < 0 || !sides.length || sides.length > 5 || obstacles.length > 64)
+        throw new Error('Invalid anchored-layout limits');
+    if (sides.some(side => !['center', 'top', 'right', 'bottom', 'left'].includes(side)))
+        throw new Error('Invalid anchored-layout side');
+    obstacles.forEach(validateBounds);
+    let best;
+    let bestScore = Infinity;
+    for (const side of sides) {
+        const anchor = anchorPoint(subject, side);
+        let x = anchor.x - size.width / 2, y = anchor.y - size.height / 2;
+        if (side === 'right')
+            x = anchor.x + gap;
+        if (side === 'left')
+            x = anchor.x - gap - size.width;
+        if (side === 'top')
+            y = anchor.y - gap - size.height;
+        if (side === 'bottom')
+            y = anchor.y + gap;
+        const bounds = { x, y, width: size.width, height: size.height };
+        const inside = x >= stage.x && y >= stage.y && x + size.width <= stage.x + stage.width && y + size.height <= stage.y + stage.height;
+        const collisions = obstacles.filter(obstacle => intersects(bounds, obstacle)).length + Number(side !== 'center' && intersects(bounds, subject));
+        const candidate = { bounds, side, anchor, fits: inside && collisions === 0, collisions };
+        const score = collisions + (inside ? 0 : 1000);
+        if (score < bestScore) {
+            best = candidate;
+            bestScore = score;
+        }
+        if (candidate.fits)
+            break;
+    }
+    return best;
+}

package/dist/runtime/math.d.ts

@@ -0,0 +1,4 @@
+export declare function clamp(value: number, min?: number, max?: number): number;
+export declare function interpolate(value: number, input: readonly [number, number], output: readonly [number, number]): number;
+export declare function easeOutCubic(progress: number): number;
+export declare function seededRandom(seed: string, key: string): number;

package/dist/runtime/math.js

@@ -0,0 +1,23 @@
+export function clamp(value, min = 0, max = 1) {
+    return Math.min(max, Math.max(min, value));
+}
+export function interpolate(value, input, output) {
+    if (input[1] <= input[0])
+        throw new Error('Interpolation input must be increasing');
+    const progress = clamp((value - input[0]) / (input[1] - input[0]));
+    return output[0] + (output[1] - output[0]) * progress;
+}
+export function easeOutCubic(progress) {
+    return 1 - (1 - clamp(progress)) ** 3;
+}
+export function seededRandom(seed, key) {
+    let hash = 2166136261;
+    const input = `${seed}\0${key}`;
+    for (let index = 0; index < input.length; index++) {
+        hash = Math.imul(hash ^ input.charCodeAt(index), 16777619);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x85ebca6b);
+    hash ^= hash >>> 13;
+    return (hash >>> 0) / 4294967296;
+}

package/dist/runtime/media.d.ts

@@ -0,0 +1,2 @@
+export declare function presentSceneVideos(target: HTMLElement, time: number, playbackRate: number): void;
+export declare function seekSceneVideos(target: HTMLElement, time: number, signal: AbortSignal): Promise<void>;

package/dist/runtime/media.js

@@ -0,0 +1,69 @@
+const MEDIA_TIMEOUT_MS = 10000;
+const PLAYBACK_DRIFT_SECONDS = 0.15;
+const pendingPlayback = new WeakSet();
+export function presentSceneVideos(target, time, playbackRate) {
+    for (const video of target.querySelectorAll('video')) {
+        if ((!video.src && !video.currentSrc) || video.readyState < 2)
+            continue;
+        video.muted = true;
+        const desired = Number(video.dataset.sceneVideoTime ?? time);
+        const rate = Number(video.dataset.sceneVideoRate ?? 1) * playbackRate;
+        if (!Number.isFinite(desired) || !Number.isFinite(rate))
+            continue;
+        const position = Math.max(0, Math.min(video.duration - 0.000001, desired));
+        const tolerance = rate > 0 ? PLAYBACK_DRIFT_SECONDS : 0.000001;
+        if (!video.seeking && Math.abs(video.currentTime - position) > tolerance)
+            video.currentTime = position;
+        if (rate <= 0 || rate > 16) {
+            video.pause();
+            continue;
+        }
+        if (video.playbackRate !== rate)
+            video.playbackRate = rate;
+        if (video.paused && !pendingPlayback.has(video)) {
+            pendingPlayback.add(video);
+            void video.play().catch(() => { }).finally(() => pendingPlayback.delete(video));
+        }
+    }
+}
+function waitForMedia(video, event, ready, signal) {
+    signal.throwIfAborted();
+    if (video.error)
+        return Promise.reject(new Error(`Scene video could not decode: ${video.error.message}`));
+    if (ready())
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            video.removeEventListener(event, complete);
+            video.removeEventListener('error', failed);
+            signal.removeEventListener('abort', aborted);
+        };
+        const complete = () => { if (ready()) {
+            cleanup();
+            resolve();
+        } };
+        const failed = () => { cleanup(); reject(new Error('Scene video could not decode. Choose H.264 MP4 or VP8/VP9 WebM.')); };
+        const aborted = () => { cleanup(); reject(signal.reason); };
+        const timer = setTimeout(() => { cleanup(); reject(new Error('Scene video frame timed out.')); }, MEDIA_TIMEOUT_MS);
+        video.addEventListener(event, complete);
+        video.addEventListener('error', failed);
+        signal.addEventListener('abort', aborted, { once: true });
+    });
+}
+export async function seekSceneVideos(target, time, signal) {
+    await Promise.all([...target.querySelectorAll('video')].map(async (video) => {
+        if (!video.src && !video.currentSrc)
+            return;
+        video.pause();
+        video.muted = true;
+        await waitForMedia(video, 'loadeddata', () => video.readyState >= 2, signal);
+        const desired = Number(video.dataset.sceneVideoTime ?? time);
+        if (!Number.isFinite(desired))
+            throw new Error('Scene video time must be finite');
+        const position = Math.max(0, Math.min(video.duration - 0.000001, desired));
+        if (Math.abs(video.currentTime - position) > 0.000001)
+            video.currentTime = position;
+        await waitForMedia(video, 'seeked', () => !video.seeking && video.readyState >= 2, signal);
+    }));
+}

package/dist/runtime/models.d.ts

@@ -0,0 +1,14 @@
+export declare const MODEL_DATA_PREFIX = "data:model/gltf-binary;base64,";
+export declare const MAX_MODEL_BYTES: number;
+export declare const MAX_MODEL_PIXELS = 4000000;
+export declare function decodeModelData(source: string): Uint8Array;
+export declare function pngDimensions(bytes: Uint8Array): {
+    width: number;
+    height: number;
+};
+export declare function validateGLB(bytes: Uint8Array): {
+    nodes: number;
+    meshes: number;
+    textures: number;
+};
+export declare function validateSceneModels(models: unknown): void;