frameos-wasm 2026.7.3

package/dist/showIf.d.ts

@@ -0,0 +1,18 @@
+import type { ShowIfCondition, StateField } from './types';
+/**
+ * True when the field should be visible: no conditions, or at least one
+ * top-level condition matches (top level is OR-ed, `and` blocks are AND-ed).
+ */
+export declare function evaluateShowIf(conditions: ShowIfCondition[] | undefined, values: Record<string, unknown>, currentFieldName?: string | null): boolean;
+/**
+ * Coerce a raw form value (usually a string) to the field's type so showIf
+ * comparisons behave the same as on the frame itself.
+ */
+export declare function coerceStateFieldValue(field: Pick<StateField, 'type'>, value: unknown): unknown;
+/** The values map for showIf checks: field defaults overlaid with the sources. */
+export declare function stateFieldShowIfValues(fields: StateField[], ...valueSources: (Record<string, unknown> | null | undefined)[]): Record<string, unknown>;
+/**
+ * The public state fields visible in a control form given the current values
+ * (later sources win, defaults fill the gaps).
+ */
+export declare function visiblePublicStateFields(fields: StateField[], ...valueSources: (Record<string, unknown> | null | undefined)[]): StateField[];

package/dist/showIf.js

@@ -0,0 +1,99 @@
+function matchCondition(condition, values, currentFieldName) {
+    if ('and' in condition) {
+        return condition.and.every((cond) => matchCondition(cond, values, currentFieldName));
+    }
+    const { value, operator, field: fieldName } = condition;
+    const field = fieldName || currentFieldName || '';
+    const actualValue = values[field];
+    if (operator === 'eq') {
+        return actualValue === value;
+    }
+    else if (operator === 'ne') {
+        return actualValue !== value;
+    }
+    else if (operator === 'gt') {
+        return actualValue > value;
+    }
+    else if (operator === 'lt') {
+        return actualValue < value;
+    }
+    else if (operator === 'gte') {
+        return actualValue >= value;
+    }
+    else if (operator === 'lte') {
+        return actualValue <= value;
+    }
+    else if (operator === 'in') {
+        return !!value?.includes?.(actualValue);
+    }
+    else if (operator === 'notIn') {
+        return !value?.includes?.(actualValue);
+    }
+    else if (operator === 'empty') {
+        return !actualValue;
+    }
+    else if (operator === 'notEmpty') {
+        return !!actualValue;
+    }
+    return value !== undefined ? value === actualValue : !!actualValue;
+}
+/**
+ * True when the field should be visible: no conditions, or at least one
+ * top-level condition matches (top level is OR-ed, `and` blocks are AND-ed).
+ */
+export function evaluateShowIf(conditions, values, currentFieldName) {
+    if (!conditions || conditions.length === 0) {
+        return true;
+    }
+    return conditions.some((condition) => matchCondition(condition, values, currentFieldName ?? null));
+}
+/**
+ * Coerce a raw form value (usually a string) to the field's type so showIf
+ * comparisons behave the same as on the frame itself.
+ */
+export function coerceStateFieldValue(field, value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    if (field.type === 'boolean') {
+        return value === true || value === 'true';
+    }
+    if (field.type === 'integer') {
+        const parsed = typeof value === 'number' ? Math.trunc(value) : parseInt(String(value));
+        return isNaN(parsed) ? undefined : parsed;
+    }
+    if (field.type === 'float') {
+        const parsed = typeof value === 'number' ? value : parseFloat(String(value));
+        return isNaN(parsed) ? undefined : parsed;
+    }
+    return value;
+}
+/** The values map for showIf checks: field defaults overlaid with the sources. */
+export function stateFieldShowIfValues(fields, ...valueSources) {
+    const values = {};
+    for (const field of fields) {
+        if (!field.name) {
+            continue;
+        }
+        let value = field.value;
+        for (const source of valueSources) {
+            if (source && field.name in source && source[field.name] !== undefined) {
+                value = source[field.name];
+            }
+        }
+        const coerced = coerceStateFieldValue(field, value);
+        if (coerced !== undefined) {
+            values[field.name] = coerced;
+        }
+    }
+    return values;
+}
+/**
+ * The public state fields visible in a control form given the current values
+ * (later sources win, defaults fill the gaps).
+ */
+export function visiblePublicStateFields(fields, ...valueSources) {
+    const publicFields = fields.filter((field) => field.access === 'public');
+    const values = stateFieldShowIfValues(publicFields, ...valueSources);
+    return publicFields.filter((field) => evaluateShowIf(field.showIf, values, field.name ?? null));
+}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+/** One showIf condition: compare a (state) field's value against `value`. */
+export interface ConfigFieldCondition {
+    field?: string;
+    operator?: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'empty' | 'notEmpty' | 'in' | 'notIn' | null;
+    value?: unknown;
+}
+/** All conditions inside `and` must match; top-level conditions are OR-ed. */
+export interface ConfigFieldConditionAnd {
+    and: ConfigFieldCondition[];
+}
+export type ShowIfCondition = ConfigFieldCondition | ConfigFieldConditionAnd;
+/** A scene state field, as found in a scene JSON's `fields` array. */
+export interface StateField {
+    name: string;
+    label?: string;
+    type?: string;
+    value?: unknown;
+    options?: string[];
+    placeholder?: string;
+    required?: boolean;
+    secret?: boolean;
+    persist?: 'memory' | 'disk';
+    access?: 'private' | 'public';
+    showIf?: ShowIfCondition[];
+}
+export interface SceneNode {
+    id?: string;
+    type?: string;
+    data?: Record<string, unknown> & {
+        keyword?: string;
+        config?: Record<string, unknown>;
+    };
+}
+/** A FrameOS scene as exported in scenes.json / template zips. */
+export interface FrameOSScene {
+    id: string;
+    name?: string;
+    nodes?: SceneNode[];
+    edges?: unknown[];
+    fields?: StateField[];
+    settings?: Record<string, unknown>;
+    default?: boolean;
+    [key: string]: unknown;
+}
+/** frameos_wasm_scene_info() payload, sent with the worker's `ready` message. */
+export interface SceneInfo {
+    loaded: number;
+    currentSceneId: string;
+    currentSceneName: string;
+    defaultSceneId: string;
+    renderRequested: boolean;
+    scenes: {
+        id: string;
+        name: string;
+        refreshInterval: number;
+    }[];
+}
+export interface PreviewFrame {
+    width: number;
+    height: number;
+    renderMs: number;
+}
+/** An interactive scene event (custom `event` node) usable as a button. */
+export interface SceneEventButton {
+    keyword: string;
+    label: string | null;
+}
+/** Events every scene handles on its own; not useful as interactive buttons. */
+export declare const LIFECYCLE_EVENTS: Set<string>;
+/** The custom event nodes of a scene, deduplicated — render these as buttons. */
+export declare function sceneEventButtons(scene: FrameOSScene | undefined | null): SceneEventButton[];

package/dist/types.js

@@ -0,0 +1,30 @@
+// Types for the FrameOS scenes JSON and the preview worker protocol. These
+// mirror the FrameOS backend/frontend definitions (frontend/src/types.tsx and
+// frameos/src/frameos/types.nim) for the parts a browser preview needs.
+/** Events every scene handles on its own; not useful as interactive buttons. */
+export const LIFECYCLE_EVENTS = new Set(['render', 'init', 'open', 'close', 'setSceneState', 'setCurrentScene']);
+/** The custom event nodes of a scene, deduplicated — render these as buttons. */
+export function sceneEventButtons(scene) {
+    if (!scene) {
+        return [];
+    }
+    const events = [];
+    const seen = new Set();
+    for (const node of scene.nodes ?? []) {
+        if (node.type !== 'event') {
+            continue;
+        }
+        const data = (node.data ?? {});
+        const keyword = String(data.keyword ?? '');
+        if (!keyword || LIFECYCLE_EVENTS.has(keyword)) {
+            continue;
+        }
+        const label = (data.config?.label ?? data.label ?? null);
+        const dedupeKey = `${keyword}:${label ?? ''}`;
+        if (!seen.has(dedupeKey)) {
+            seen.add(dedupeKey);
+            events.push({ keyword, label: label ? String(label) : null });
+        }
+    }
+    return events;
+}

package/index.html

@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>frameos-wasm — scene preview</title>
+    <style>
+      body { margin: 0 auto; max-width: 860px; padding: 24px; font: 15px/1.5 system-ui, sans-serif; color: #0f172a; }
+      h1 { font-size: 22px; }
+      .setup { display: flex; flex-direction: column; gap: 8px; margin-bottom: 20px; }
+      .setup label { font-weight: 600; font-size: 13px; }
+      .setup input, .setup textarea { padding: 8px 10px; border: 1px solid #cbd5e1; border-radius: 8px; font: inherit; }
+      .setup textarea { font-family: ui-monospace, monospace; font-size: 12px; }
+      .setup .dims { display: flex; gap: 8px; }
+      .setup .dims input { width: 110px; }
+      button.start { align-self: flex-start; padding: 8px 16px; border: 0; border-radius: 8px; background: #2563eb; color: #fff; font: inherit; cursor: pointer; }
+      button.start:hover { background: #1d4ed8; }
+      .hint { font-size: 13px; color: #475569; }
+    </style>
+  </head>
+  <body>
+    <h1>frameos-wasm scene preview</h1>
+    <p class="hint">
+      Runs a FrameOS scene in your browser through the WebAssembly runtime, with the same state fields, event
+      buttons, and logs the frame itself exposes. Paste the contents of a <code>scenes.json</code> (from a template
+      zip, a backup, or an export) and press start. Serve this file over HTTP with the runtime assets next to it —
+      for example: <code>npx serve node_modules/frameos-wasm</code> and open <code>/index.html</code>.
+    </p>
+    <div class="setup">
+      <label for="scenes">scenes.json</label>
+      <textarea id="scenes" rows="8" placeholder='[{"id": "...", "nodes": [...], "fields": [...]}]'></textarea>
+      <label>Dimensions</label>
+      <div class="dims">
+        <input id="width" type="number" value="800" /> ×
+        <input id="height" type="number" value="480" />
+      </div>
+      <button class="start" id="start">Start preview</button>
+    </div>
+    <div id="manager"></div>
+    <script type="module">
+      import { mountFrameOSManager } from './dist/index.js'
+
+      let handle = null
+      document.getElementById('start').onclick = () => {
+        let scenes
+        try {
+          scenes = JSON.parse(document.getElementById('scenes').value)
+        } catch (error) {
+          alert('scenes.json did not parse: ' + error)
+          return
+        }
+        if (!Array.isArray(scenes) || scenes.length === 0) {
+          alert('Expected a non-empty JSON array of scenes.')
+          return
+        }
+        handle?.destroy()
+        handle = mountFrameOSManager(document.getElementById('manager'), {
+          workerUrl: new URL('./dist/assets/preview-worker.js', import.meta.url),
+          width: parseInt(document.getElementById('width').value) || 800,
+          height: parseInt(document.getElementById('height').value) || 480,
+          scenes,
+        })
+      }
+    </script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "frameos-wasm",
+  "version": "2026.7.3",
+  "description": "Run FrameOS scenes in the browser via WebAssembly: a typed live-preview runtime plus a minimal showIf-aware management interface.",
+  "keywords": [
+    "frameos",
+    "wasm",
+    "webassembly",
+    "e-ink",
+    "smart-frame"
+  ],
+  "homepage": "https://frameos.net",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FrameOS/frameos.git",
+    "directory": "frameos/wasm"
+  },
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./assets/*": "./dist/assets/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "index.html",
+    "README.md"
+  ],
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "sync-version": "node scripts/sync-version.mjs"
+  }
+}