frameos-wasm 2026.7.3

package/dist/assets/preview-worker.js

@@ -0,0 +1,198 @@
+// FrameOS live-preview worker.
+//
+// Loads the emscripten-built scene runtime (frameos.js/frameos.wasm, built by
+// frameos/tools/build_wasm.sh) and drives it for the frontend's live-preview
+// modal. Runs in a Web Worker so the runtime's synchronous HTTP hook (sync
+// XHR) is allowed and long renders never block the page.
+//
+// Messages in:
+//   {type: 'init', width, height, timeZone, scenesJson, sceneId, settingsJson, proxyUrl}
+//   {type: 'render'}                       force a render now
+//   {type: 'event', name, payload}         dispatch a scene event
+//   {type: 'selectScene', sceneId}
+// Messages out:
+//   {type: 'ready', sceneInfo}
+//   {type: 'frame', width, height, buffer, renderMs}   buffer: transferred ArrayBuffer (RGBA)
+//   {type: 'state', state}
+//   {type: 'log', message}
+//   {type: 'sceneEvent', name, payload}
+//   {type: 'error', message}
+
+let Module = null
+let renderTimer = null
+let rendering = false
+
+function post(msg, transfer) {
+  self.postMessage(msg, transfer || [])
+}
+
+function call(name, ret, argTypes, args) {
+  return Module.ccall(name, ret, argTypes, args)
+}
+
+function lastError() {
+  try {
+    return call('frameos_wasm_last_error', 'string', [], [])
+  } catch (e) {
+    return String(e)
+  }
+}
+
+function postState() {
+  try {
+    const state = call('frameos_wasm_scene_state', 'string', [], [])
+    post({ type: 'state', state: JSON.parse(state) })
+  } catch (e) {
+    // state is informational; ignore
+  }
+}
+
+function renderNow() {
+  if (!Module || rendering) {
+    return
+  }
+  rendering = true
+  try {
+    const started = Date.now()
+    const rc = call('frameos_wasm_render', 'number', [], [])
+    const width = call('frameos_wasm_width', 'number', [], [])
+    const height = call('frameos_wasm_height', 'number', [], [])
+    const ptr = call('frameos_wasm_buffer', 'number', [], [])
+    const len = call('frameos_wasm_buffer_len', 'number', [], [])
+    if (rc === 2 || !ptr || !len) {
+      post({ type: 'error', message: 'render failed: ' + lastError() })
+      return
+    }
+    // Copy out of the wasm heap; the buffer is transferred to the page.
+    const buffer = Module.HEAPU8.buffer.slice(ptr, ptr + len)
+    post({ type: 'frame', width, height, buffer, renderMs: Date.now() - started }, [buffer])
+    postState()
+  } catch (e) {
+    post({ type: 'error', message: 'render crashed: ' + e })
+  } finally {
+    rendering = false
+    scheduleNextRender()
+  }
+}
+
+function scheduleNextRender() {
+  if (!Module) {
+    return
+  }
+  if (renderTimer) {
+    clearTimeout(renderTimer)
+    renderTimer = null
+  }
+  let seconds = 0
+  try {
+    const interval = call('frameos_wasm_scene_interval', 'number', [], [])
+    const nextSleep = call('frameos_wasm_next_sleep', 'number', [], [])
+    seconds = interval > 0 ? interval : 300
+    if (nextSleep >= 0 && nextSleep < seconds) {
+      seconds = nextSleep
+    }
+  } catch (e) {
+    seconds = 300
+  }
+  // Keep the preview responsive but sane: at least 1 fps worth of delay,
+  // at most 15 minutes between refreshes.
+  const delayMs = Math.min(Math.max(seconds * 1000, 1000), 15 * 60 * 1000)
+  renderTimer = setTimeout(renderNow, delayMs)
+}
+
+function renderSoonIfRequested() {
+  try {
+    if (call('frameos_wasm_render_requested', 'boolean', [], [])) {
+      renderNow()
+    } else {
+      postState()
+    }
+  } catch (e) {
+    post({ type: 'error', message: String(e) })
+  }
+}
+
+async function init(msg) {
+  try {
+    const createFrameOS = (await import('./frameos.js')).default
+    Module = await createFrameOS({
+      locateFile: (path) => new URL(path, import.meta.url).href,
+      onFrameosLog: (message) => post({ type: 'log', message }),
+      onFrameosEvent: (name, payload) => {
+        let parsed = {}
+        try {
+          parsed = JSON.parse(payload)
+        } catch (e) {}
+        post({ type: 'sceneEvent', name, payload: parsed })
+      },
+    })
+    // Route the runtime's HTTP requests through the backend proxy (same-origin,
+    // no CORS) so data apps that fetch external URLs work like on the device.
+    if (msg.proxyUrl) {
+      Module['frameosProxyUrl'] = msg.proxyUrl
+    }
+
+    const ok = call(
+      'frameos_wasm_init',
+      'boolean',
+      ['number', 'number', 'string', 'string', 'string'],
+      [
+        msg.width,
+        msg.height,
+        msg.name || 'live preview',
+        msg.timeZone || 'UTC',
+        msg.settingsJson || '{}',
+      ]
+    )
+    if (!ok) {
+      throw new Error('init failed: ' + lastError())
+    }
+    const loaded = call('frameos_wasm_load_scenes', 'number', ['string'], [msg.scenesJson])
+    if (!loaded) {
+      throw new Error('no scenes loaded: ' + lastError())
+    }
+    if (msg.sceneId) {
+      call('frameos_wasm_select_scene', 'boolean', ['string'], [msg.sceneId])
+    }
+    const sceneInfo = JSON.parse(call('frameos_wasm_scene_info', 'string', [], []))
+    post({ type: 'ready', sceneInfo })
+    renderNow()
+  } catch (e) {
+    post({ type: 'error', message: String(e && e.message ? e.message : e) })
+  }
+}
+
+self.onmessage = (ev) => {
+  const msg = ev.data || {}
+  switch (msg.type) {
+    case 'init':
+      init(msg)
+      break
+    case 'render':
+      renderNow()
+      break
+    case 'event':
+      if (Module) {
+        try {
+          call(
+            'frameos_wasm_event',
+            'boolean',
+            ['string', 'string'],
+            [msg.name, JSON.stringify(msg.payload || {})]
+          )
+        } catch (e) {
+          post({ type: 'error', message: 'event failed: ' + e })
+        }
+        renderSoonIfRequested()
+      }
+      break
+    case 'selectScene':
+      if (Module) {
+        call('frameos_wasm_select_scene', 'boolean', ['string'], [msg.sceneId])
+        renderNow()
+      }
+      break
+    default:
+      break
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FrameOSPreview, createFrameOSPreview, type FrameOSPreviewOptions } from './preview';
+export { mountFrameOSManager, type FrameOSManagerHandle, type FrameOSManagerOptions } from './manager';
+export { coerceStateFieldValue, evaluateShowIf, stateFieldShowIfValues, visiblePublicStateFields, } from './showIf';
+export { LIFECYCLE_EVENTS, sceneEventButtons, type ConfigFieldCondition, type ConfigFieldConditionAnd, type FrameOSScene, type PreviewFrame, type SceneEventButton, type SceneInfo, type SceneNode, type ShowIfCondition, type StateField, } from './types';

package/dist/index.js

@@ -0,0 +1,10 @@
+// frameos-wasm: run FrameOS scenes in the browser via WebAssembly.
+//
+// The runtime assets (frameos.js, frameos.wasm, preview-worker.js) ship in
+// this package under ./assets — serve that directory same-origin and pass
+// `workerUrl: '<mount>/preview-worker.js'`. Version tracks the FrameOS
+// release the runtime was built from (versions.json in the FrameOS repo).
+export { FrameOSPreview, createFrameOSPreview } from './preview';
+export { mountFrameOSManager } from './manager';
+export { coerceStateFieldValue, evaluateShowIf, stateFieldShowIfValues, visiblePublicStateFields, } from './showIf';
+export { LIFECYCLE_EVENTS, sceneEventButtons, } from './types';

package/dist/manager.d.ts

@@ -0,0 +1,16 @@
+import { FrameOSPreview, type FrameOSPreviewOptions } from './preview';
+export interface FrameOSManagerOptions extends Omit<FrameOSPreviewOptions, 'canvas'> {
+    /** Show the log pane (default true). */
+    showLogs?: boolean;
+    /** Max log lines kept (default 200). */
+    maxLogLines?: number;
+}
+export interface FrameOSManagerHandle {
+    preview: FrameOSPreview;
+    destroy: () => void;
+}
+/**
+ * Mount a self-contained preview + control surface into `container`.
+ * Returns the underlying FrameOSPreview for programmatic control.
+ */
+export declare function mountFrameOSManager(container: HTMLElement, options: FrameOSManagerOptions): FrameOSManagerHandle;

package/dist/manager.js

@@ -0,0 +1,258 @@
+// A minimal, dependency-free management interface for a FrameOS preview:
+// canvas, scene switcher, showIf-aware state fields, event buttons, and a log
+// pane. Mirrors the device's own /control page (frameos/assets/web/control.html)
+// but runs entirely in the browser against the wasm runtime.
+import { FrameOSPreview } from './preview';
+import { coerceStateFieldValue, evaluateShowIf, stateFieldShowIfValues } from './showIf';
+import { sceneEventButtons } from './types';
+/**
+ * Mount a self-contained preview + control surface into `container`.
+ * Returns the underlying FrameOSPreview for programmatic control.
+ */
+export function mountFrameOSManager(container, options) {
+    const showLogs = options.showLogs !== false;
+    const maxLogLines = options.maxLogLines ?? 200;
+    container.classList.add('frameos-manager');
+    container.innerHTML = '';
+    injectStyles();
+    const stage = el('div', 'frameos-manager__stage');
+    const canvas = document.createElement('canvas');
+    canvas.className = 'frameos-manager__canvas';
+    canvas.width = options.width;
+    canvas.height = options.height;
+    stage.appendChild(canvas);
+    const status = el('div', 'frameos-manager__status', 'Loading FrameOS runtime…');
+    const controls = el('div', 'frameos-manager__controls');
+    const logPane = el('pre', 'frameos-manager__logs');
+    logPane.style.display = showLogs ? '' : 'none';
+    container.appendChild(stage);
+    container.appendChild(status);
+    container.appendChild(controls);
+    container.appendChild(logPane);
+    // Values the user typed, overriding the runtime's reported state until the
+    // runtime confirms them via a state message.
+    let editedValues = {};
+    let destroyed = false;
+    const logLines = [];
+    const appendLog = (line) => {
+        logLines.push(line);
+        if (logLines.length > maxLogLines) {
+            logLines.splice(0, logLines.length - maxLogLines);
+        }
+        logPane.textContent = logLines.join('\n');
+        logPane.scrollTop = logPane.scrollHeight;
+    };
+    const sceneById = new Map();
+    for (const scene of options.scenes) {
+        sceneById.set(scene.id, scene);
+    }
+    const preview = new FrameOSPreview({
+        ...options,
+        canvas,
+        onReady: (sceneInfo) => {
+            status.textContent = '';
+            renderControls();
+            options.onReady?.(sceneInfo);
+        },
+        onFrame: (frame) => {
+            status.textContent = `Rendered ${frame.width}×${frame.height} in ${frame.renderMs} ms`;
+            options.onFrame?.(frame);
+        },
+        onState: (state) => {
+            editedValues = {};
+            renderControls();
+            options.onState?.(state);
+        },
+        onLog: (message) => {
+            appendLog(message);
+            options.onLog?.(message);
+        },
+        onSceneEvent: (name, payload) => {
+            appendLog(`event: ${name} ${JSON.stringify(payload)}`);
+            options.onSceneEvent?.(name, payload);
+        },
+        onError: (message) => {
+            status.textContent = message;
+            status.classList.add('frameos-manager__status--error');
+            appendLog(`error: ${message}`);
+            options.onError?.(message);
+        },
+    });
+    function currentScene() {
+        return (preview.currentSceneId && sceneById.get(preview.currentSceneId)) || options.scenes[0];
+    }
+    function publicFields(scene) {
+        return (scene?.fields ?? []).filter((field) => field.access === 'public' && field.name);
+    }
+    function fieldValues(scene) {
+        return stateFieldShowIfValues(publicFields(scene), preview.state, editedValues);
+    }
+    function renderControls() {
+        if (destroyed) {
+            return;
+        }
+        controls.innerHTML = '';
+        const scene = currentScene();
+        // Scene switcher, when more than one scene is loaded.
+        const scenes = preview.sceneInfo?.scenes ?? [];
+        if (scenes.length > 1) {
+            const row = el('div', 'frameos-manager__row');
+            row.appendChild(el('label', 'frameos-manager__label', 'Scene'));
+            const select = document.createElement('select');
+            select.className = 'frameos-manager__input';
+            for (const item of scenes) {
+                const option = document.createElement('option');
+                option.value = item.id;
+                option.textContent = item.name || item.id;
+                option.selected = item.id === preview.currentSceneId;
+                select.appendChild(option);
+            }
+            select.onchange = () => {
+                editedValues = {};
+                preview.selectScene(select.value);
+                renderControls();
+            };
+            row.appendChild(select);
+            controls.appendChild(row);
+        }
+        // State fields, filtered by showIf against current + edited values.
+        const fields = publicFields(scene);
+        const values = fieldValues(scene);
+        const visible = fields.filter((field) => evaluateShowIf(field.showIf, values, field.name));
+        for (const field of visible) {
+            controls.appendChild(fieldRow(field, values[field.name]));
+        }
+        if (visible.length > 0) {
+            const apply = document.createElement('button');
+            apply.type = 'button';
+            apply.className = 'frameos-manager__button frameos-manager__button--primary';
+            apply.textContent = 'Apply & render';
+            apply.onclick = () => {
+                const state = {};
+                for (const field of visible) {
+                    const value = field.name in editedValues ? editedValues[field.name] : values[field.name];
+                    if (value !== undefined) {
+                        state[field.name] = coerceStateFieldValue(field, value);
+                    }
+                }
+                preview.setSceneState(state);
+            };
+            controls.appendChild(apply);
+        }
+        // Custom event nodes as buttons.
+        const buttonRow = el('div', 'frameos-manager__row frameos-manager__row--buttons');
+        for (const event of sceneEventButtons(scene)) {
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.className = 'frameos-manager__button';
+            button.textContent = event.label || event.keyword;
+            button.onclick = () => preview.sendEvent(event.keyword, {});
+            buttonRow.appendChild(button);
+        }
+        const render = document.createElement('button');
+        render.type = 'button';
+        render.className = 'frameos-manager__button';
+        render.textContent = 'Render';
+        render.onclick = () => preview.render();
+        buttonRow.appendChild(render);
+        controls.appendChild(buttonRow);
+    }
+    function fieldRow(field, value) {
+        const row = el('div', 'frameos-manager__row');
+        row.appendChild(el('label', 'frameos-manager__label', field.label || field.name));
+        const update = (next) => {
+            editedValues = { ...editedValues, [field.name]: next };
+            // showIf conditions may depend on this field: re-render the form (a
+            // fresh element keeps focus handling simple — apply happens on click).
+            renderControls();
+        };
+        if (field.type === 'select' || field.type === 'boolean' || field.type === 'font') {
+            const select = document.createElement('select');
+            select.className = 'frameos-manager__input';
+            const opts = field.type === 'boolean' ? ['true', 'false'] : field.options ?? [];
+            for (const opt of opts) {
+                const option = document.createElement('option');
+                option.value = opt;
+                option.textContent = opt;
+                option.selected = String(value ?? '') === opt;
+                select.appendChild(option);
+            }
+            select.onchange = () => update(select.value);
+            row.appendChild(select);
+        }
+        else if (field.type === 'text') {
+            const textarea = document.createElement('textarea');
+            textarea.className = 'frameos-manager__input';
+            textarea.rows = 3;
+            textarea.value = value === undefined || value === null ? '' : String(value);
+            textarea.onchange = () => update(textarea.value);
+            row.appendChild(textarea);
+        }
+        else {
+            const input = document.createElement('input');
+            input.className = 'frameos-manager__input';
+            input.type =
+                field.type === 'integer' || field.type === 'float'
+                    ? 'number'
+                    : field.type === 'date'
+                        ? 'date'
+                        : field.type === 'color'
+                            ? 'color'
+                            : 'text';
+            if (field.type === 'float') {
+                input.step = 'any';
+            }
+            if (field.placeholder) {
+                input.placeholder = field.placeholder;
+            }
+            input.value = value === undefined || value === null ? '' : String(value);
+            input.onchange = () => update(input.value);
+            row.appendChild(input);
+        }
+        return row;
+    }
+    return {
+        preview,
+        destroy: () => {
+            destroyed = true;
+            preview.destroy();
+            container.innerHTML = '';
+            container.classList.remove('frameos-manager');
+        },
+    };
+}
+function el(tag, className, text) {
+    const node = document.createElement(tag);
+    node.className = className;
+    if (text) {
+        node.textContent = text;
+    }
+    return node;
+}
+let stylesInjected = false;
+function injectStyles() {
+    if (stylesInjected || typeof document === 'undefined') {
+        return;
+    }
+    stylesInjected = true;
+    const style = document.createElement('style');
+    style.setAttribute('data-frameos-manager', '');
+    style.textContent = `
+.frameos-manager { display: flex; flex-direction: column; gap: 12px; font: 14px/1.4 system-ui, sans-serif; }
+.frameos-manager__stage { display: flex; justify-content: center; background: #0f172a; border-radius: 12px; padding: 12px; }
+.frameos-manager__canvas { max-width: 100%; max-height: min(60vh, 480px); width: auto; height: auto; border-radius: 6px; background: #fff; }
+.frameos-manager__status { min-height: 1.2em; font-size: 12px; opacity: 0.7; }
+.frameos-manager__status--error { color: #dc2626; opacity: 1; }
+.frameos-manager__controls { display: flex; flex-direction: column; gap: 8px; }
+.frameos-manager__row { display: flex; align-items: center; gap: 8px; }
+.frameos-manager__row--buttons { flex-wrap: wrap; }
+.frameos-manager__label { min-width: 120px; font-weight: 600; }
+.frameos-manager__input { flex: 1; padding: 6px 8px; border: 1px solid #cbd5e1; border-radius: 8px; background: inherit; color: inherit; }
+.frameos-manager__button { padding: 6px 12px; border: 1px solid #cbd5e1; border-radius: 8px; background: transparent; color: inherit; cursor: pointer; }
+.frameos-manager__button:hover { background: rgba(100, 116, 139, 0.1); }
+.frameos-manager__button--primary { background: #2563eb; border-color: #2563eb; color: #fff; align-self: flex-start; }
+.frameos-manager__button--primary:hover { background: #1d4ed8; }
+.frameos-manager__logs { max-height: 200px; overflow: auto; margin: 0; padding: 8px 10px; background: rgba(15, 23, 42, 0.05); border-radius: 8px; font-size: 11px; }
+`;
+    document.head.appendChild(style);
+}

package/dist/preview.d.ts

@@ -0,0 +1,60 @@
+import type { FrameOSScene, PreviewFrame, SceneInfo } from './types';
+export interface FrameOSPreviewOptions {
+    /** URL of the module worker script: `<assets>/preview-worker.js`. The
+     * frameos.js/frameos.wasm files must live next to it (same directory) —
+     * copy the package's `dist/assets/` folder somewhere same-origin. */
+    workerUrl: string | URL;
+    /** Render width/height in pixels (the frame's dimensions). */
+    width: number;
+    height: number;
+    /** The scenes to load — the parsed contents of a scenes.json. */
+    scenes: FrameOSScene[];
+    /** Scene to select initially; defaults to the runtime's default scene. */
+    sceneId?: string;
+    /** Frame name shown in logs. */
+    name?: string;
+    /** IANA time zone for the simulated frame; defaults to the browser's. */
+    timeZone?: string;
+    /** Frame settings (app API keys etc.); most previews run fine without. */
+    settings?: Record<string, unknown>;
+    /** Same-origin proxy endpoint for the runtime's HTTP requests. Without it,
+     * scenes fetching external data hit browser CORS limits. */
+    proxyUrl?: string;
+    /** Canvas to paint frames onto; can also be attached later. */
+    canvas?: HTMLCanvasElement | null;
+    onReady?: (sceneInfo: SceneInfo) => void;
+    onFrame?: (frame: PreviewFrame) => void;
+    onState?: (state: Record<string, unknown>) => void;
+    onLog?: (message: string) => void;
+    onSceneEvent?: (name: string, payload: Record<string, unknown>) => void;
+    onError?: (message: string) => void;
+}
+export declare class FrameOSPreview {
+    readonly options: FrameOSPreviewOptions;
+    private worker;
+    private canvas;
+    private pendingFrame;
+    private destroyed;
+    /** Latest scene info from the runtime (set once `ready` fires). */
+    sceneInfo: SceneInfo | null;
+    /** Latest public state of the current scene. */
+    state: Record<string, unknown>;
+    /** The scene currently selected in the runtime. */
+    currentSceneId: string | null;
+    constructor(options: FrameOSPreviewOptions);
+    private handleMessage;
+    /** Attach (or replace) the canvas frames are painted onto. */
+    attachCanvas(canvas: HTMLCanvasElement | null): void;
+    private paint;
+    /** Force a render now. */
+    render(): void;
+    /** Dispatch a scene event (a custom event node's keyword, "button", ...). */
+    sendEvent(name: string, payload?: Record<string, unknown>): void;
+    /** Update the current scene's state fields; renders by default. */
+    setSceneState(state: Record<string, unknown>, render?: boolean): void;
+    /** Switch the runtime to another loaded scene. */
+    selectScene(sceneId: string): void;
+    /** Terminate the worker; the instance cannot be reused afterwards. */
+    destroy(): void;
+}
+export declare function createFrameOSPreview(options: FrameOSPreviewOptions): FrameOSPreview;

package/dist/preview.js

@@ -0,0 +1,116 @@
+export class FrameOSPreview {
+    constructor(options) {
+        this.worker = null;
+        this.canvas = null;
+        this.pendingFrame = null;
+        this.destroyed = false;
+        /** Latest scene info from the runtime (set once `ready` fires). */
+        this.sceneInfo = null;
+        /** Latest public state of the current scene. */
+        this.state = {};
+        /** The scene currently selected in the runtime. */
+        this.currentSceneId = null;
+        this.options = options;
+        this.canvas = options.canvas ?? null;
+        this.currentSceneId = options.sceneId ?? null;
+        this.worker = new Worker(options.workerUrl, { type: 'module' });
+        this.worker.onerror = (event) => {
+            options.onError?.(event.message || 'FrameOS preview worker failed to load');
+        };
+        this.worker.onmessage = (event) => this.handleMessage(event.data ?? {});
+        this.worker.postMessage({
+            type: 'init',
+            width: options.width,
+            height: options.height,
+            name: options.name || 'frameos-wasm preview',
+            timeZone: options.timeZone || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC',
+            scenesJson: JSON.stringify(options.scenes),
+            settingsJson: JSON.stringify(options.settings ?? {}),
+            proxyUrl: options.proxyUrl || '',
+            sceneId: options.sceneId || '',
+        });
+    }
+    handleMessage(msg) {
+        if (this.destroyed) {
+            return;
+        }
+        switch (msg.type) {
+            case 'ready':
+                this.sceneInfo = msg.sceneInfo ?? null;
+                if (this.sceneInfo?.currentSceneId) {
+                    this.currentSceneId = this.sceneInfo.currentSceneId;
+                }
+                this.options.onReady?.(msg.sceneInfo);
+                break;
+            case 'frame':
+                this.pendingFrame = { width: msg.width, height: msg.height, buffer: msg.buffer };
+                this.paint();
+                this.options.onFrame?.({ width: msg.width, height: msg.height, renderMs: msg.renderMs });
+                break;
+            case 'state':
+                this.state = msg.state ?? {};
+                this.options.onState?.(this.state);
+                break;
+            case 'log':
+                this.options.onLog?.(String(msg.message ?? ''));
+                break;
+            case 'sceneEvent':
+                this.options.onSceneEvent?.(String(msg.name ?? ''), msg.payload ?? {});
+                break;
+            case 'error':
+                this.options.onError?.(String(msg.message ?? 'Unknown FrameOS preview error'));
+                break;
+        }
+    }
+    /** Attach (or replace) the canvas frames are painted onto. */
+    attachCanvas(canvas) {
+        this.canvas = canvas;
+        this.paint();
+    }
+    paint() {
+        const canvas = this.canvas;
+        const frame = this.pendingFrame;
+        if (!canvas || !frame || !frame.buffer.byteLength) {
+            return;
+        }
+        if (canvas.width !== frame.width) {
+            canvas.width = frame.width;
+        }
+        if (canvas.height !== frame.height) {
+            canvas.height = frame.height;
+        }
+        const context = canvas.getContext('2d');
+        if (!context) {
+            return;
+        }
+        context.putImageData(new ImageData(new Uint8ClampedArray(frame.buffer), frame.width, frame.height), 0, 0);
+    }
+    /** Force a render now. */
+    render() {
+        this.worker?.postMessage({ type: 'render' });
+    }
+    /** Dispatch a scene event (a custom event node's keyword, "button", ...). */
+    sendEvent(name, payload = {}) {
+        this.worker?.postMessage({ type: 'event', name, payload });
+    }
+    /** Update the current scene's state fields; renders by default. */
+    setSceneState(state, render = true) {
+        this.sendEvent('setSceneState', { state, render });
+    }
+    /** Switch the runtime to another loaded scene. */
+    selectScene(sceneId) {
+        this.currentSceneId = sceneId;
+        this.worker?.postMessage({ type: 'selectScene', sceneId });
+    }
+    /** Terminate the worker; the instance cannot be reused afterwards. */
+    destroy() {
+        this.destroyed = true;
+        this.worker?.terminate();
+        this.worker = null;
+        this.pendingFrame = null;
+        this.canvas = null;
+    }
+}
+export function createFrameOSPreview(options) {
+    return new FrameOSPreview(options);
+}