@machinal/scenes 0.0.0-stage → 0.1.1

package/dist/runtime/models.js

@@ -0,0 +1,370 @@
+export const MODEL_DATA_PREFIX = 'data:model/gltf-binary;base64,';
+export const MAX_MODEL_BYTES = 4 * 1024 * 1024;
+export const MAX_MODEL_PIXELS = 4_000_000;
+const unsupportedFeatures = ['extensions', 'extensionsUsed', 'extensionsRequired', 'animations', 'skins', 'targets', 'sparse'];
+function record(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Invalid GLB ${label}`);
+    return value;
+}
+function integer(value, min, max, label) {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new Error(`Invalid GLB ${label}`);
+    return value;
+}
+function list(value, max, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > max)
+        throw new Error(`GLB ${label} exceeds supported limits`);
+    return value;
+}
+function noExternalResources(value, depth = 0) {
+    if (depth > 32)
+        throw new Error('GLB structure is too deeply nested');
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value) && value.length > 512)
+        throw new Error('GLB metadata array exceeds limits');
+    for (const [key, child] of Object.entries(value)) {
+        if (key === 'uri')
+            throw new Error('GLB must embed all resources; URI references are unsupported');
+        if (['__proto__', 'prototype', 'constructor'].includes(key))
+            throw new Error('Unsupported GLB metadata key');
+        if (unsupportedFeatures.includes(key) && child !== undefined && child !== null &&
+            (typeof child !== 'object' || Object.keys(child).length > 0))
+            throw new Error(`Unsupported GLB feature: ${key}`);
+        noExternalResources(child, depth + 1);
+    }
+}
+export function decodeModelData(source) {
+    if (typeof source !== 'string' || !source.startsWith(MODEL_DATA_PREFIX) || source.length > MODEL_DATA_PREFIX.length + Math.ceil(MAX_MODEL_BYTES / 3) * 4)
+        throw new Error('Use an approved embedded GLB of at most 4 MiB');
+    const encoded = source.slice(MODEL_DATA_PREFIX.length);
+    if (encoded.length % 4 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded))
+        throw new Error('Invalid GLB base64 encoding');
+    const decoded = atob(encoded);
+    if (decoded.length === 0 || decoded.length > MAX_MODEL_BYTES)
+        throw new Error('GLB exceeds its byte limit');
+    return Uint8Array.from(decoded, character => character.charCodeAt(0));
+}
+export function pngDimensions(bytes) {
+    const signature = [137, 80, 78, 71, 13, 10, 26, 10];
+    if (bytes.length < 33 || !signature.every((value, i) => bytes[i] === value) || String.fromCharCode(...bytes.subarray(12, 16)) !== 'IHDR')
+        throw new Error('Model textures must be embedded PNG images');
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const width = view.getUint32(16), height = view.getUint32(20);
+    if (!width || !height || width * height > MAX_MODEL_PIXELS)
+        throw new Error('Model texture exceeds 4 million pixels');
+    if (view.getUint32(8) !== 13)
+        throw new Error('Invalid PNG header');
+    let imageData = false, ended = false, chunks = 0;
+    for (let offset = 8; offset < bytes.length;) {
+        if (++chunks > 1024 || offset + 12 > bytes.length)
+            throw new Error('Invalid PNG chunk limits');
+        const length = view.getUint32(offset);
+        if (length > bytes.length - offset - 12)
+            throw new Error('Invalid PNG chunk size');
+        const type = String.fromCharCode(...bytes.subarray(offset + 4, offset + 8));
+        if (['acTL', 'fcTL', 'fdAT'].includes(type))
+            throw new Error('Animated PNG textures are unsupported');
+        if (type === 'IHDR' && offset !== 8)
+            throw new Error('Duplicate PNG header');
+        if (type === 'IDAT')
+            imageData = true;
+        offset += length + 12;
+        if (type === 'IEND') {
+            if (length !== 0 || offset !== bytes.length)
+                throw new Error('Invalid PNG end');
+            ended = true;
+        }
+    }
+    if (!imageData || !ended)
+        throw new Error('PNG texture needs complete image data');
+    return { width, height };
+}
+function finiteVector(value, length, label) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value) || value.length !== length || value.some(item => typeof item !== 'number' || !Number.isFinite(item) || Math.abs(item) > 1e6))
+        throw new Error(`Invalid GLB ${label}`);
+}
+function scalar(value, min, max, label) {
+    if (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max))
+        throw new Error(`Invalid GLB ${label}`);
+}
+function boolean(value, label) {
+    if (value !== undefined && typeof value !== 'boolean')
+        throw new Error(`Invalid GLB ${label}`);
+}
+function choice(value, choices, label) {
+    if (value !== undefined && !choices.includes(value))
+        throw new Error(`Unsupported GLB ${label}`);
+}
+function color(value, length, label) {
+    finiteVector(value, length, label);
+    if (value !== undefined)
+        value.forEach(component => scalar(component, 0, 1, label));
+}
+function validateMaterials(doc, imageCount) {
+    const samplers = list(doc.samplers, 16, 'samplers').map(item => record(item, 'sampler'));
+    for (const sampler of samplers) {
+        choice(sampler.magFilter, [9728, 9729], 'magnification filter');
+        choice(sampler.minFilter, [9728, 9729, 9984, 9985, 9986, 9987], 'minification filter');
+        choice(sampler.wrapS, [33071, 33648, 10497], 'sampler wrap');
+        choice(sampler.wrapT, [33071, 33648, 10497], 'sampler wrap');
+    }
+    const textures = list(doc.textures, 8, 'textures').map(item => record(item, 'texture'));
+    for (const texture of textures) {
+        integer(texture.source, 0, imageCount - 1, 'texture source');
+        if (texture.sampler !== undefined)
+            integer(texture.sampler, 0, samplers.length - 1, 'texture sampler');
+    }
+    const textureInfo = (value) => {
+        if (value === undefined)
+            return;
+        const info = record(value, 'texture info');
+        integer(info.index, 0, textures.length - 1, 'material texture');
+        if (info.texCoord !== undefined)
+            integer(info.texCoord, 0, 1, 'texture coordinates');
+    };
+    const materials = list(doc.materials, 64, 'materials').map(item => record(item, 'material'));
+    for (const material of materials) {
+        const pbr = material.pbrMetallicRoughness === undefined ? {} : record(material.pbrMetallicRoughness, 'PBR material');
+        color(pbr.baseColorFactor, 4, 'base color');
+        scalar(pbr.metallicFactor, 0, 1, 'metallic factor');
+        scalar(pbr.roughnessFactor, 0, 1, 'roughness factor');
+        color(material.emissiveFactor, 3, 'emissive color');
+        choice(material.alphaMode, ['OPAQUE', 'MASK', 'BLEND'], 'alpha mode');
+        scalar(material.alphaCutoff, 0, 1, 'alpha cutoff');
+        boolean(material.doubleSided, 'double sided');
+        for (const info of [pbr.baseColorTexture, pbr.metallicRoughnessTexture, material.normalTexture, material.occlusionTexture, material.emissiveTexture])
+            textureInfo(info);
+        if (material.normalTexture !== undefined)
+            scalar(material.normalTexture.scale, -100, 100, 'normal scale');
+        if (material.occlusionTexture !== undefined)
+            scalar(material.occlusionTexture.strength, 0, 1, 'occlusion strength');
+    }
+    return { materials, textures };
+}
+export function validateGLB(bytes) {
+    if (bytes.byteLength < 28 || bytes.byteLength > MAX_MODEL_BYTES)
+        throw new Error('Invalid GLB length');
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(0, true) !== 0x46546c67 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.length)
+        throw new Error('Use a valid GLB version 2 container');
+    const jsonLength = view.getUint32(12, true);
+    const binaryHeader = 20 + jsonLength;
+    if (!jsonLength || jsonLength > 256 * 1024 || jsonLength % 4 || view.getUint32(16, true) !== 0x4e4f534a || binaryHeader + 8 > bytes.length)
+        throw new Error('Invalid GLB JSON chunk');
+    const binaryLength = view.getUint32(binaryHeader, true);
+    if (binaryLength % 4 || view.getUint32(binaryHeader + 4, true) !== 0x004e4942 || binaryHeader + 8 + binaryLength !== bytes.length)
+        throw new Error('GLB needs exactly one embedded binary chunk');
+    const doc = record(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(20, binaryHeader))), 'document');
+    noExternalResources(doc);
+    if (record(doc.asset, 'asset').version !== '2.0')
+        throw new Error('Unsupported GLB asset version');
+    const buffers = list(doc.buffers, 1, 'buffers');
+    if (buffers.length !== 1)
+        throw new Error('GLB needs one embedded buffer');
+    const bufferLength = integer(record(buffers[0], 'buffer').byteLength, 1, binaryLength, 'buffer size');
+    if (binaryLength - bufferLength > 3)
+        throw new Error('Invalid GLB buffer padding');
+    const views = list(doc.bufferViews, 256, 'buffer views').map(item => {
+        const entry = record(item, 'buffer view');
+        if (entry.buffer !== 0)
+            throw new Error('Invalid GLB buffer reference');
+        const offset = integer(entry.byteOffset ?? 0, 0, bufferLength, 'view offset');
+        const length = integer(entry.byteLength, 1, bufferLength - offset, 'view length');
+        const stride = entry.byteStride === undefined ? undefined : integer(entry.byteStride, 4, 252, 'view stride');
+        if (stride && stride % 4)
+            throw new Error('Invalid GLB byte stride');
+        choice(entry.target, [34962, 34963], 'buffer target');
+        return { offset, length, stride };
+    });
+    let accessorValues = 0;
+    const binaryStart = binaryHeader + 8;
+    const accessors = list(doc.accessors, 256, 'accessors').map(item => {
+        const entry = record(item, 'accessor');
+        const source = views[integer(entry.bufferView, 0, views.length - 1, 'accessor view')];
+        const sizes = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };
+        const formats = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4 };
+        const size = sizes[integer(entry.componentType, 5120, 5126, 'component type')];
+        const components = typeof entry.type === 'string' && Object.hasOwn(formats, entry.type) ? formats[entry.type] : 0;
+        if (!size || !components)
+            throw new Error('Unsupported GLB accessor format');
+        boolean(entry.normalized, 'normalized accessor');
+        if (entry.normalized === true && [5125, 5126].includes(entry.componentType))
+            throw new Error('GLB float/uint32 accessors cannot be normalized');
+        const count = integer(entry.count, 1, 100000, 'accessor count');
+        accessorValues += count * components;
+        if (accessorValues > 1_000_000)
+            throw new Error('GLB accessor budget exceeded');
+        const offset = integer(entry.byteOffset ?? 0, 0, source.length, 'accessor offset');
+        const stride = source.stride ?? size * components;
+        if (stride < size * components || offset % size || source.offset % size || offset + (count - 1) * stride + size * components > source.length)
+            throw new Error('GLB accessor exceeds its buffer view');
+        finiteVector(entry.min, components, 'accessor minimum');
+        finiteVector(entry.max, components, 'accessor maximum');
+        if (entry.min && entry.max && entry.min.some((min, i) => min > entry.max[i]))
+            throw new Error('Invalid GLB accessor bounds');
+        if (entry.componentType === 5126) {
+            for (let i = 0; i < count; i++)
+                for (let component = 0; component < components; component++) {
+                    const value = view.getFloat32(binaryStart + source.offset + offset + i * stride + component * size, true);
+                    if (!Number.isFinite(value) || Math.abs(value) > 1e6)
+                        throw new Error('GLB contains invalid floating-point vertex data');
+                }
+        }
+        return { type: entry.type, componentType: entry.componentType, count,
+            min: entry.min, max: entry.max,
+            normalized: entry.normalized,
+            offset: binaryStart + source.offset + offset, stride, sourceStride: source.stride };
+    });
+    const images = list(doc.images, 8, 'images');
+    let pixels = 0;
+    for (const item of images) {
+        const image = record(item, 'image');
+        if (image.mimeType !== 'image/png')
+            throw new Error('GLB supports embedded PNG textures only');
+        const source = views[integer(image.bufferView, 0, views.length - 1, 'image view')];
+        if (source.stride !== undefined)
+            throw new Error('GLB image views cannot be interleaved');
+        const dimensions = pngDimensions(bytes.subarray(binaryHeader + 8 + source.offset, binaryHeader + 8 + source.offset + source.length));
+        pixels += dimensions.width * dimensions.height;
+    }
+    if (pixels > MAX_MODEL_PIXELS * 2)
+        throw new Error('GLB total texture pixel budget exceeded');
+    const { materials, textures } = validateMaterials(doc, images.length);
+    const meshes = list(doc.meshes, 64, 'meshes');
+    let primitives = 0;
+    const meshCosts = meshes.map(item => {
+        const mesh = record(item, 'mesh');
+        if (mesh.weights !== undefined)
+            throw new Error('GLB morph weights are unsupported');
+        const entries = list(mesh.primitives, 64, 'primitives');
+        if (!entries.length)
+            throw new Error('GLB mesh needs triangle primitives');
+        let vertices = 0;
+        for (const item of entries) {
+            const primitive = record(item, 'primitive');
+            primitives++;
+            if (primitives > 128)
+                throw new Error('GLB primitive budget exceeded');
+            if ((primitive.mode ?? 4) !== 4)
+                throw new Error('GLB supports triangle primitives only');
+            const attributes = record(primitive.attributes, 'attributes');
+            if (attributes.POSITION === undefined)
+                throw new Error('GLB mesh needs positions');
+            const position = accessors[integer(attributes.POSITION, 0, accessors.length - 1, 'position accessor')];
+            if (position.type !== 'VEC3' || position.componentType !== 5126 || !position.min || !position.max)
+                throw new Error('GLB positions need float VEC3 data and bounds');
+            for (const [name, index] of Object.entries(attributes)) {
+                if (!['POSITION', 'NORMAL', 'TEXCOORD_0', 'TEXCOORD_1', 'COLOR_0', 'TANGENT'].includes(name))
+                    throw new Error('Unsupported GLB mesh attribute');
+                const accessor = accessors[integer(index, 0, accessors.length - 1, 'mesh accessor')];
+                const format = name.startsWith('TEXCOORD_') ? ['VEC2'] : name === 'TANGENT' ? ['VEC4'] : name === 'COLOR_0' ? ['VEC3', 'VEC4'] : ['VEC3'];
+                const integerAttribute = name.startsWith('TEXCOORD_') || name === 'COLOR_0';
+                if (!format.includes(accessor.type) || accessor.count !== position.count ||
+                    accessor.componentType !== 5126 && !(integerAttribute && [5121, 5123].includes(accessor.componentType) && accessor.normalized === true))
+                    throw new Error('Unsupported GLB vertex attribute format/count');
+            }
+            let count = position.count;
+            if (primitive.indices !== undefined) {
+                const indices = accessors[integer(primitive.indices, 0, accessors.length - 1, 'indices')];
+                if (indices.type !== 'SCALAR' || ![5121, 5123, 5125].includes(indices.componentType) || indices.normalized || indices.sourceStride !== undefined)
+                    throw new Error('GLB indices need packed unsigned scalars');
+                const restart = indices.componentType === 5121 ? 255 : indices.componentType === 5123 ? 65535 : 4294967295;
+                for (let i = 0; i < indices.count; i++) {
+                    const offset = indices.offset + i * indices.stride;
+                    const value = indices.componentType === 5121 ? view.getUint8(offset) : indices.componentType === 5123 ? view.getUint16(offset, true) : view.getUint32(offset, true);
+                    if (value >= position.count || value === restart)
+                        throw new Error('GLB index exceeds vertex bounds');
+                }
+                count = indices.count;
+            }
+            if (count % 3)
+                throw new Error('GLB triangle vertex/index count must be divisible by three');
+            vertices += count;
+            if (primitive.material !== undefined) {
+                const material = materials[integer(primitive.material, 0, materials.length - 1, 'material')];
+                const pbr = material.pbrMetallicRoughness ?? {};
+                for (const info of [pbr.baseColorTexture, pbr.metallicRoughnessTexture, material.normalTexture, material.occlusionTexture, material.emissiveTexture]) {
+                    if (info && attributes[`TEXCOORD_${info.texCoord ?? 0}`] === undefined)
+                        throw new Error('GLB material references missing texture coordinates');
+                }
+            }
+        }
+        return { vertices, primitives: entries.length };
+    });
+    if (!primitives || primitives > 128)
+        throw new Error('GLB primitive budget exceeded');
+    const nodes = list(doc.nodes, 128, 'nodes');
+    const parents = new Set();
+    let renderedVertices = 0, renderedPrimitives = 0;
+    const edges = nodes.map(item => {
+        const node = record(item, 'node');
+        if (node.skin !== undefined || node.weights !== undefined || node.camera !== undefined)
+            throw new Error('GLB skins, morphs and cameras are unsupported');
+        if (node.mesh !== undefined) {
+            const cost = meshCosts[integer(node.mesh, 0, meshes.length - 1, 'node mesh')];
+            renderedVertices += cost.vertices;
+            renderedPrimitives += cost.primitives;
+        }
+        if (renderedVertices > 500_000 || renderedPrimitives > 256)
+            throw new Error('GLB expanded instance geometry budget exceeded');
+        for (const [key, length] of Object.entries({ translation: 3, rotation: 4, scale: 3, matrix: 16 }))
+            finiteVector(node[key], length, `node ${key}`);
+        if (node.matrix !== undefined && [node.translation, node.rotation, node.scale].some(value => value !== undefined))
+            throw new Error('GLB nodes cannot mix matrix and TRS');
+        if (node.rotation && Math.abs(Math.hypot(...node.rotation) - 1) > 0.0001)
+            throw new Error('GLB rotations need unit quaternions');
+        return list(node.children, 128, 'children').map(child => {
+            const id = integer(child, 0, nodes.length - 1, 'child node');
+            if (parents.has(id))
+                throw new Error('GLB nodes must have a single parent');
+            parents.add(id);
+            return id;
+        });
+    });
+    const visited = new Set(), visiting = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            throw new Error('Cyclic GLB node hierarchy');
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        edges[id].forEach(visit);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    nodes.forEach((_, id) => visit(id));
+    const scenes = list(doc.scenes, 1, 'scenes');
+    if (!scenes.length)
+        throw new Error('GLB needs an explicit scene');
+    if (doc.scene !== undefined)
+        integer(doc.scene, 0, scenes.length - 1, 'default scene');
+    for (const item of scenes) {
+        const scene = record(item, 'scene');
+        const roots = new Set();
+        for (const node of list(scene.nodes, 128, 'scene nodes')) {
+            const id = integer(node, 0, nodes.length - 1, 'scene node');
+            if (parents.has(id) || roots.has(id))
+                throw new Error('GLB scene roots must be distinct parentless nodes');
+            roots.add(id);
+        }
+    }
+    return { nodes: nodes.length, meshes: meshes.length, textures: textures.length };
+}
+export function validateSceneModels(models) {
+    if (models === undefined)
+        return;
+    const entries = Object.entries(record(models, 'attachments'));
+    if (entries.length > 2)
+        throw new Error('Attach at most two GLB models');
+    for (const [id, source] of entries) {
+        if (!/^model_[12]$/.test(id) || typeof source !== 'string')
+            throw new Error('Invalid scene model attachment');
+        validateGLB(decodeModelData(source));
+    }
+}

package/dist/runtime/objects.d.ts

@@ -0,0 +1,8 @@
+import { type SceneObjectParameters, type SceneParameters } from './parameters.js';
+import type { FrameContext } from './types.js';
+export interface SceneObjectRegistry {
+    register(id: string, read: (frame: FrameContext) => SceneObjectParameters): () => void;
+    snapshot(frame: FrameContext): SceneParameters;
+    clear(): void;
+}
+export declare function createObjectRegistry(): SceneObjectRegistry;

package/dist/runtime/objects.js

@@ -0,0 +1,24 @@
+import { validateSceneParameters } from './parameters.js';
+export function createObjectRegistry() {
+    const readers = new Map();
+    return {
+        register(id, read) {
+            validateSceneParameters({ [id]: {} });
+            if (readers.has(id) || readers.size >= 32 || typeof read !== 'function')
+                throw new Error('Object readers need unique IDs; at most 32 can be registered');
+            readers.set(id, read);
+            return () => { if (readers.get(id) === read)
+                readers.delete(id); };
+        },
+        snapshot(frame) {
+            const states = Object.fromEntries([...readers].map(([id, read]) => {
+                const state = read(frame);
+                validateSceneParameters({ [id]: state });
+                return [id, { ...state }];
+            }));
+            validateSceneParameters(states);
+            return states;
+        },
+        clear() { readers.clear(); },
+    };
+}

package/dist/runtime/parameters.d.ts

@@ -0,0 +1,17 @@
+export interface SceneObjectParameters {
+    x?: number;
+    y?: number;
+    z?: number;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    opacity?: number;
+    delay?: number;
+    duration?: number;
+    color?: string;
+}
+export type SceneParameters = Record<string, SceneObjectParameters>;
+export type ResolvedSceneObject = Required<SceneObjectParameters>;
+export declare function validateSceneParameters(parameters: unknown): asserts parameters is SceneParameters | undefined;
+/** Components opt into stable object parameters; arbitrary Svelte is never rewritten. */
+export declare function resolveSceneObject(parameters: SceneParameters, id: string, defaults?: SceneObjectParameters): ResolvedSceneObject;

package/dist/runtime/parameters.js

@@ -0,0 +1,35 @@
+const bounds = {
+    x: [-19200, 19200], y: [-19200, 19200], z: [-19200, 19200], rotation: [-Math.PI * 100, Math.PI * 100],
+    scaleX: [-100, 100], scaleY: [-100, 100], opacity: [0, 1], delay: [0, 60], duration: [0, 60],
+};
+export function validateSceneParameters(parameters) {
+    if (parameters === undefined)
+        return;
+    if (!parameters || typeof parameters !== 'object' || Array.isArray(parameters))
+        throw new Error('Invalid scene parameters');
+    const objects = Object.entries(parameters);
+    if (objects.length > 32)
+        throw new Error('Expose at most 32 scene parameter objects');
+    for (const [id, object] of objects) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(id) || !object || typeof object !== 'object' || Array.isArray(object))
+            throw new Error('Invalid scene parameter object');
+        for (const [key, value] of Object.entries(object)) {
+            if (key === 'color') {
+                if (typeof value !== 'string' || !/^#[a-fA-F0-9]{6}$/.test(value))
+                    throw new Error('Scene color must be a six-digit hex color');
+            }
+            else {
+                const range = Object.hasOwn(bounds, key) ? bounds[key] : undefined;
+                if (!range || typeof value !== 'number' || !Number.isFinite(value) || value < range[0] || value > range[1])
+                    throw new Error(`Invalid scene parameter: ${key}`);
+            }
+        }
+    }
+}
+/** Components opt into stable object parameters; arbitrary Svelte is never rewritten. */
+export function resolveSceneObject(parameters, id, defaults = {}) {
+    const override = Object.hasOwn(parameters, id) ? parameters[id] : {};
+    const object = { x: 0, y: 0, z: 0, rotation: 0, scaleX: 1, scaleY: 1, opacity: 1, delay: 0, duration: 1, color: '#ffffff', ...defaults, ...override };
+    validateSceneParameters({ [id]: object });
+    return object;
+}

package/dist/runtime/resources.d.ts

@@ -0,0 +1,5 @@
+import type { ResourceScope } from './types.js';
+export declare function createResourceScope(signal: AbortSignal): ResourceScope;
+export declare function abortable<T>(operation: Promise<T>, signal: AbortSignal): Promise<T>;
+export declare function waitForVisualResources(target: HTMLElement): Promise<void>;
+export declare function seekCssAnimations(target: HTMLElement, time: number): void;

package/dist/runtime/resources.js

@@ -0,0 +1,63 @@
+export function createResourceScope(signal) {
+    const pending = new Set();
+    let failure;
+    let failed = false;
+    return {
+        signal,
+        track(resource) {
+            signal.throwIfAborted();
+            const tracked = resource.then((value) => { pending.delete(tracked); return value; }, (error) => { pending.delete(tracked); failed = true; failure = error; throw error; });
+            pending.add(tracked);
+            // A tracked resource may finish before ready()/seek() starts awaiting it.
+            void tracked.catch(() => undefined);
+            return tracked;
+        },
+        async wait() {
+            signal.throwIfAborted();
+            while (pending.size > 0) {
+                await abortable(Promise.all([...pending]), signal);
+                signal.throwIfAborted();
+            }
+            if (failed)
+                throw failure;
+        },
+    };
+}
+export function abortable(operation, signal) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const aborted = () => reject(signal.reason);
+        signal.addEventListener('abort', aborted, { once: true });
+        operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted));
+    });
+}
+const decodedImages = new WeakMap();
+async function waitForImage(image) {
+    if (!image.currentSrc && !image.src)
+        return;
+    const source = { currentSrc: image.currentSrc, src: image.src, srcset: image.srcset, sizes: image.sizes };
+    const cached = decodedImages.get(image);
+    if (image.complete && image.naturalWidth > 0 && cached?.currentSrc === source.currentSrc
+        && cached.src === source.src && cached.srcset === source.srcset && cached.sizes === source.sizes)
+        return;
+    // decode() can wait for a compositor tick even for an unchanged image.
+    // Retain only successful decodes; source changes and failures must still wait.
+    await image.decode();
+    decodedImages.set(image, source);
+}
+export async function waitForVisualResources(target) {
+    // Font requests can start only after layout. Awaiting fonts.ready before
+    // discovering the used faces can capture fallback metrics on a fresh worker.
+    target.getBoundingClientRect();
+    if (target.ownerDocument.fonts) {
+        await Promise.all([...target.ownerDocument.fonts].map(face => face.status === 'loaded' ? undefined : face.load()));
+    }
+    await target.ownerDocument.fonts?.ready;
+    await Promise.all([...target.querySelectorAll('img')].map(waitForImage));
+}
+export function seekCssAnimations(target, time) {
+    for (const animation of target.getAnimations({ subtree: true })) {
+        animation.pause();
+        animation.currentTime = time * 1000;
+    }
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,76 @@
+import type { SceneObjectRegistry } from './objects.js';
+import type { SceneParameters } from './parameters.js';
+export declare const PROTOCOL_VERSION: 1;
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type SceneProps = Record<string, JsonValue>;
+export interface SceneConfig {
+    width: number;
+    height: number;
+    fps: number;
+    durationInFrames: number;
+    transparent?: boolean;
+    captionSafeBottom?: number;
+}
+export interface SceneRequest {
+    version: typeof PROTOCOL_VERSION;
+    sceneId: string;
+    props?: SceneProps;
+    seed?: string;
+    config: SceneConfig;
+}
+export interface SceneManifest extends SceneRequest {
+    props: SceneProps;
+    seed: string;
+}
+export interface SceneRenderOptions {
+    renderScale?: number;
+    capture?: boolean;
+}
+export interface FrameContext extends SceneRenderOptions {
+    frame: number;
+    time: number;
+    progress: number;
+    config: Readonly<SceneConfig>;
+    random: (key: string) => number;
+}
+export interface SceneInstance {
+    update: (context: FrameContext) => void | Promise<void>;
+    dispose: () => void | Promise<void>;
+}
+export interface ResourceScope {
+    track: <T>(resource: Promise<T>) => Promise<T>;
+    wait: () => Promise<void>;
+    readonly signal: AbortSignal;
+}
+export interface SceneMountContext<P extends SceneProps = SceneProps> {
+    target: HTMLElement;
+    props: P;
+    config: Readonly<SceneConfig>;
+    resources: ResourceScope;
+    objects: SceneObjectRegistry;
+}
+export interface SceneDefinition<P extends SceneProps = SceneProps> {
+    id: string;
+    defaults: P;
+    create: (context: SceneMountContext<P>) => SceneInstance | Promise<SceneInstance>;
+}
+export interface SceneController {
+    readonly version: typeof PROTOCOL_VERSION;
+    readonly manifest: SceneManifest;
+    ready: () => Promise<void>;
+    seek: (frame: number, options?: SceneRenderOptions & {
+        realtime?: boolean;
+        playbackRate?: number;
+    }) => Promise<void>;
+    dispose: () => Promise<void>;
+    snapshotObjects?: () => SceneParameters;
+}
+declare global {
+    interface Window {
+        __scene?: SceneController;
+        __sceneRequest?: SceneRequest;
+        __sceneError?: string;
+    }
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export const PROTOCOL_VERSION = 1;

package/dist/runtime/validation.d.ts

@@ -0,0 +1,4 @@
+import { type SceneConfig, type SceneRequest } from './types.js';
+export declare function validateConfig(config: SceneConfig): void;
+export declare function validateRequest(request: SceneRequest): void;
+export declare function validateFrame(frame: number, config: SceneConfig): void;

package/dist/runtime/validation.js

@@ -0,0 +1,37 @@
+import { PROTOCOL_VERSION } from './types.js';
+export function validateConfig(config) {
+    for (const key of ['width', 'height', 'durationInFrames']) {
+        if (!Number.isSafeInteger(config?.[key]) || config[key] <= 0) {
+            throw new Error(`${key} must be a positive safe integer`);
+        }
+    }
+    if (!Number.isFinite(config.fps) || config.fps <= 0 || config.fps > 240) {
+        throw new Error('fps must be between 0 and 240');
+    }
+    if (config.transparent !== undefined && typeof config.transparent !== 'boolean') {
+        throw new Error('transparent must be a boolean');
+    }
+    if (config.captionSafeBottom !== undefined && (!Number.isFinite(config.captionSafeBottom) || config.captionSafeBottom < 0 || config.captionSafeBottom > 0.5)) {
+        throw new Error('captionSafeBottom must be between 0 and 0.5');
+    }
+    const duration = config.durationInFrames / config.fps;
+    if (!Number.isFinite(duration) || duration > 24 * 60 * 60)
+        throw new Error('Scene duration must not exceed 24 hours');
+}
+export function validateRequest(request) {
+    if (request?.version !== PROTOCOL_VERSION)
+        throw new Error('Unsupported scene protocol version');
+    if (typeof request.sceneId !== 'string' || !request.sceneId.trim())
+        throw new Error('sceneId is required');
+    if (request.seed !== undefined && typeof request.seed !== 'string')
+        throw new Error('seed must be a string');
+    if (request.props !== undefined && (!request.props || Array.isArray(request.props) || typeof request.props !== 'object')) {
+        throw new Error('props must be an object');
+    }
+    validateConfig(request.config);
+}
+export function validateFrame(frame, config) {
+    if (!Number.isSafeInteger(frame) || frame < 0 || frame >= config.durationInFrames) {
+        throw new Error(`Frame must be an integer between 0 and ${config.durationInFrames - 1}`);
+    }
+}