frameos-wasm

Run FrameOS scenes in the browser through WebAssembly. The package wraps the emscripten-built FrameOS scene runtime with a typed API and ships a minimal management interface: a live canvas, scene switching, showIf-aware state fields, event buttons, and logs — the same control surface a frame exposes on-device.

The package version always equals the FrameOS release the runtime was built from.

Install

npm install frameos-wasm

The runtime assets (frameos.js, frameos.wasm, preview-worker.js) live in frameos-wasm/dist/assets/. They must be served same-origin (the runtime runs in a module Web Worker and uses synchronous XHR): copy that directory into your static assets, e.g. to /frameos-wasm/.

Quick start — management interface

import { mountFrameOSManager } from 'frameos-wasm'

const handle = mountFrameOSManager(document.getElementById('preview')!, {
  workerUrl: '/frameos-wasm/preview-worker.js',
  width: 800,
  height: 480,
  scenes, // parsed scenes.json (from a template zip, backup, or export)
})
// later: handle.preview.sendEvent('myButton'), handle.destroy()

Lower level — just the runtime

import { createFrameOSPreview } from 'frameos-wasm'

const preview = createFrameOSPreview({
  workerUrl: '/frameos-wasm/preview-worker.js',
  width: 800,
  height: 480,
  scenes,
  canvas: document.querySelector('canvas'),
  onLog: (line) => console.log(line),
  onState: (state) => console.log('scene state', state),
})
preview.setSceneState({ message: 'Hello' })
preview.sendEvent('button', { label: 'a' })
preview.selectScene('sceneId')
preview.destroy()

Render pacing

Renders are throttled to one per second. A scene that asks for more (a 24 fps slideshow with refreshInterval: 0.04) triggers onFastRenderRequest(intervalMs) once per runtime start — ask the visitor, then preview.setFastMode(true) to let the scene run at its own pace (setFastMode(false) restores the throttle). Pass fastMode: true to start unthrottled.

Browser asset folder

The runtime's /srv/assets — where a real frame keeps its assets — is a folder that lives in the visitor's browser (IndexedDB, via emscripten's IDBFS). It is shared by every preview on the same origin, survives reloads, and never leaves the browser. A fresh folder gets a few generated sample photos so image scenes render something at once. Scenes read from it (data/localImage, fonts, …) and, with saveAssets on (the default here), write into it.

const entries = await preview.listAssets() // [{path, size, mtime, isDir}]
await preview.writeAsset('photos/beach.jpg', file) // File/Blob/ArrayBuffer; parents created
const bytes = await preview.readAsset('photos/beach.jpg')
await preview.createAssetFolder('photos/2026')
await preview.deleteAsset('photos') // recursive
await preview.resetAssets() // wipe + regenerate the samples

onAssetsChanged fires when a scene writes into the folder (or an op completes); onReady(sceneInfo, assets) reports whether the folder is persistent or in-memory. Pass browserAssets: false for an empty in-memory folder instead.

Helpers for building your own UI are exported too: evaluateShowIf, visiblePublicStateFields, coerceStateFieldValue, sceneEventButtons, and the StateField/FrameOSScene types.

Notes

• Scenes that fetch external URLs are subject to browser CORS unless you pass proxyUrl (a same-origin endpoint that forwards {method, url, headers, bodyBase64, timeoutMs} — see FrameOS's /api/frames/{id}/scene_preview_proxy).
• Apps that need host processes are not in the wasm build: data/chromiumScreenshot, data/rstpSnapshot. data/localImage reads the browser asset folder (see above).
• index.html in the package root is a standalone demo page: npx serve node_modules/frameos-wasm and paste a scenes.json.

Development (FrameOS repo)

The runtime assets are built by frameos/tools/build_wasm.sh into frontend/public/frameos-wasm (plus a version.json stamp: the FrameOS version the interpreter is, the release it belongs to, and the commit) and copied into dist/assets by npm run build. Without a runtime build npm run build still produces the TypeScript half and warns; publishing sets FRAMEOS_WASM_REQUIRE_RUNTIME=1 and fails instead. npm run sync-version copies the FrameOS version out of the repo's versions.json; publishing refuses to run when the two disagree.

Every FrameOS release also attaches the same three files as frameos-<version>-wasm.tar.gz (+ a minisign .minisig from the firmware signing key) — the runtime is a release artifact, and FrameOS Cloud installs that signed bundle rather than building from main, so its preview renders with the interpreter frames actually run. The bundle reports which version it is through frameos_wasm_version() (runtimeInfo.version / the third onReady argument here).