@zaflun/lumio-sdk 0.6.6 → 0.11.1

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to `@zaflun/lumio-sdk` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.11.1
+
+### Changed
+
+- The package is built with tsup 9 (esbuild 0.28). The bundled Worker runtime
+  (`lumio-runtime.global.js`) differs only in generated helper code, and the
+  type declarations are unchanged for consumers.
+
+## 0.11.0
+
+### Added
+
+- The `IconPicker` Lucide tab offers 2,296 icons (Lucide 1.67, before: 2,022).
+  No icon name was removed or renamed, so stored icon names keep working.
+
+### Changed
+
+- **Breaking: React 19.3 or newer is required.** The peer dependencies are now
+  `react ^19.3.0` and `react-dom ^19.3.0` (before: `^18.0.0 || ^19.0.0`). The
+  renderer runs on `react-reconciler` 0.34, which requires React 19.3. To
+  upgrade, raise `react` (and `@types/react`) in your extension's
+  `package.json` to `^19.3.0` and reinstall. Code written against React 18 or
+  19 needs no other change. The Worker runtime (`@zaflun/lumio-sdk/runtime`)
+  bundles its own React, so deployed extensions are not affected.
+- The renderer reports itself to React DevTools as `@zaflun/lumio-sdk`.
+
+### Fixed
+
+- State updates wrapped in `startTransition` (or `useTransition`) commit
+  instead of failing in the renderer.
+- Updates scheduled outside React run at React's default priority.

package/README.md

@@ -44,14 +44,14 @@ Lumio.render(<MyWidget />, { target: "editor" });
 
 | Hook | Purpose |
 |------|---------|
-| `useExtensionStorage()` | Persistent key-value storage synced across surfaces |
+| `useExtensionStorage(key, initialValue)` | Persistent key-value storage, one key per call, synced across surfaces |
 | `useVisionState()` | Per-key state with real-time sync |
 | `useExtensionContext()` | Extension metadata (ID, target, overlay) |
 | `useLumioEvent()` | Subscribe to platform events (49 event types) |
 | `useLumioConfig()` | Read/write extension config |
 | `useLumioTheme()` | Active overlay/widget theme (colors, fonts) |
 | `useLumioIdentity()` | Current user/account context |
-| `useLumioAction()` | Trigger platform actions (21 action types) |
+| `useLumioAction()` | Run a Lumio action (`events:emit`, `overlay:update_layer`, …) through the host |
 | `useQuery()` | Call server query functions |
 | `useMutation()` | Call server mutation functions |
 
@@ -94,16 +94,17 @@ const scoreFont = localFont({
 });
 ```
 
-## Three Surfaces
+## Surfaces
 
 | Surface | File | Where it renders |
 |---------|------|-----------------|
 | `editor` | `src/editor.tsx` | Dashboard sidebar panel |
 | `layer` | `src/layer.tsx` | OBS overlay (transparent) |
-| `interactive` | `src/interactive.tsx` | Audience page |
 
 All surfaces share storage — changes in the editor propagate to the overlay in real time.
 
+Viewers interact through chat commands and channel point rewards (`twitch:reward`, `kick:reward`), handled by bot-module handlers that write `ctx.db` and call `ctx.realtime.push(topic, payload)`. The layer and editor pick that up with `useRealtime(topic, cb)`.
+
 ## Security
 
 Extensions run in a sandboxed Web Worker with zero DOM access. A custom React reconciler serializes the component tree to JSON, which the host renders. Extension code cannot access cookies, JWT tokens, localStorage, or any host resources.

package/dist/chunk-GVAYWB5X.js

@@ -0,0 +1,196 @@
+// src/bridge/WorkerBridge.ts
+var WorkerBridge = class {
+  notificationHandlers = /* @__PURE__ */ new Map();
+  requestHandlers = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  requestCounter = 0;
+  requestTimeout;
+  messageListener = null;
+  destroyed = false;
+  constructor(options) {
+    this.requestTimeout = options?.requestTimeout ?? 3e4;
+    this.messageListener = this.handleMessage.bind(this);
+    globalThis.addEventListener("message", this.messageListener);
+  }
+  notify(method, params) {
+    const msg = {
+      jsonrpc: "2.0",
+      method,
+      ...params !== void 0 ? { params } : {}
+    };
+    globalThis.postMessage(msg);
+  }
+  request(method, params) {
+    const id = `req_${++this.requestCounter}`;
+    const msg = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      ...params !== void 0 ? { params } : {}
+    };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error("Request timeout"));
+      }, this.requestTimeout);
+      this.pendingRequests.set(id, { resolve, reject, timer });
+      globalThis.postMessage(msg);
+    });
+  }
+  onNotification(method, handler) {
+    if (!this.notificationHandlers.has(method)) {
+      this.notificationHandlers.set(method, /* @__PURE__ */ new Set());
+    }
+    this.notificationHandlers.get(method).add(handler);
+    return () => {
+      this.notificationHandlers.get(method)?.delete(handler);
+    };
+  }
+  onRequest(method, handler) {
+    this.requestHandlers.set(method, handler);
+  }
+  destroy() {
+    this.destroyed = true;
+    if (this.messageListener) {
+      globalThis.removeEventListener("message", this.messageListener);
+      this.messageListener = null;
+    }
+    for (const { timer, reject } of this.pendingRequests.values()) {
+      if (timer) clearTimeout(timer);
+      reject(new Error("Bridge destroyed"));
+    }
+    this.pendingRequests.clear();
+    this.notificationHandlers.clear();
+    this.requestHandlers.clear();
+  }
+  handleMessage(event) {
+    if (this.destroyed) return;
+    const data = event.data;
+    if (!data || typeof data !== "object" || data.jsonrpc !== "2.0") return;
+    if ("id" in data && !("method" in data)) {
+      const pending = this.pendingRequests.get(data.id);
+      if (pending) {
+        this.pendingRequests.delete(data.id);
+        if (pending.timer) clearTimeout(pending.timer);
+        if (data.error) {
+          pending.reject(new Error(data.error.message));
+        } else {
+          pending.resolve(data.result);
+        }
+      }
+      return;
+    }
+    if ("id" in data && "method" in data) {
+      const handler = this.requestHandlers.get(data.method);
+      if (handler) {
+        handler(data.params).then((result) => {
+          const response = { jsonrpc: "2.0", id: data.id, result };
+          globalThis.postMessage(response);
+        }).catch((err) => {
+          const response = {
+            jsonrpc: "2.0",
+            id: data.id,
+            error: { code: -32603, message: err.message }
+          };
+          globalThis.postMessage(response);
+        });
+      }
+      return;
+    }
+    if ("method" in data && !("id" in data)) {
+      const handlers = this.notificationHandlers.get(data.method);
+      if (handlers) {
+        for (const handler of handlers) {
+          handler(data.params);
+        }
+      }
+    }
+  }
+};
+
+// src/renderer/callback-registry.ts
+var CallbackRegistry = class {
+  handlers = /* @__PURE__ */ new Map();
+  counter = 0;
+  register(fn) {
+    const id = `cb_${++this.counter}`;
+    this.handlers.set(id, fn);
+    return id;
+  }
+  invoke(id, args) {
+    const handler = this.handlers.get(id);
+    if (!handler) {
+      throw new Error(`CallbackRegistry: no handler for ID "${id}"`);
+    }
+    return handler(...args);
+  }
+  update(id, fn) {
+    if (!this.handlers.has(id)) {
+      throw new Error(`CallbackRegistry: cannot update non-existent handler "${id}"`);
+    }
+    this.handlers.set(id, fn);
+  }
+  remove(id) {
+    this.handlers.delete(id);
+  }
+  has(id) {
+    return this.handlers.has(id);
+  }
+  clear() {
+    this.handlers.clear();
+  }
+  get size() {
+    return this.handlers.size;
+  }
+};
+
+// src/renderer/bridge-context.ts
+var bridgeInstance = null;
+var registryInstance = null;
+var bridgeFactory = null;
+var initParams = null;
+function getBridge() {
+  if (!bridgeInstance) {
+    bridgeInstance = bridgeFactory ? bridgeFactory() : new WorkerBridge();
+  }
+  return bridgeInstance;
+}
+function getRegistry() {
+  if (!registryInstance) {
+    registryInstance = new CallbackRegistry();
+  }
+  return registryInstance;
+}
+function setInitParams(params) {
+  const rest = { ...params };
+  delete rest.bundleCode;
+  delete rest.bundleUrl;
+  initParams = rest;
+}
+function getInitParams() {
+  return initParams;
+}
+function setBridgeFactory(factory) {
+  bridgeFactory = factory;
+}
+function destroyBridgeContext() {
+  if (bridgeInstance) {
+    bridgeInstance.destroy();
+    bridgeInstance = null;
+  }
+  if (registryInstance) {
+    registryInstance.clear();
+    registryInstance = null;
+  }
+  initParams = null;
+}
+
+export {
+  WorkerBridge,
+  getBridge,
+  getRegistry,
+  setInitParams,
+  getInitParams,
+  setBridgeFactory,
+  destroyBridgeContext
+};

package/dist/host.d.ts

@@ -0,0 +1,73 @@
+import { LifecycleInitParams } from '@zaflun/lumio-protocol';
+import { ReactElement } from 'react';
+
+type AnyFunction = (...args: unknown[]) => unknown;
+declare class CallbackRegistry {
+    private handlers;
+    private counter;
+    register(fn: AnyFunction): string;
+    invoke(id: string, args: unknown[]): unknown;
+    update(id: string, fn: AnyFunction): void;
+    remove(id: string): void;
+    has(id: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * `lifecycle.init` as the host sent it, minus the bundle. Hosts may add fields
+ * beyond the protocol type (`settings`, `permissions`, …).
+ */
+type InitParams = Partial<LifecycleInitParams> & Record<string, unknown>;
+/**
+ * The JSON-RPC transport every hook talks to. In production it is the
+ * `WorkerBridge` (postMessage inside the extension Worker); the devkit's mock
+ * host plugs in an in-process transport through {@link setBridgeFactory}.
+ */
+interface LumioBridge {
+    notify(method: string, params?: unknown): void;
+    request(method: string, params?: unknown): Promise<unknown>;
+    onNotification(method: string, handler: (params: unknown) => void): () => void;
+    onRequest(method: string, handler: (params: unknown) => Promise<unknown>): void;
+    destroy(): void;
+}
+declare function getBridge(): LumioBridge;
+declare function getRegistry(): CallbackRegistry;
+/**
+ * Records the `lifecycle.init` params. The worker entry calls this before it
+ * evaluates the bundle: hooks subscribe in an effect, after the first render,
+ * so they would miss the one-shot notification and read it from here instead.
+ */
+declare function setInitParams(params: Partial<LifecycleInitParams>): void;
+/**
+ * Replaces the transport `getBridge()` creates; `null` restores the default
+ * `WorkerBridge`. Takes effect for the next bridge, so call it before
+ * anything renders or after {@link destroyBridgeContext}.
+ */
+declare function setBridgeFactory(factory: (() => LumioBridge) | null): void;
+declare function destroyBridgeContext(): void;
+
+interface MountRootOptions {
+    /**
+     * Commit updates from outside React in a microtask (see
+     * `HostConfigOptions.syncUpdates`). Used by the devkit's mock host.
+     */
+    syncUpdates?: boolean;
+}
+/** A rendered extension root on the current bridge. */
+interface MountedRoot {
+    /** Runs `fn` and commits the updates it schedules before returning. */
+    flushSync(fn: () => void): void;
+    /** Unmounts the tree and stops listening for `event.callback`. */
+    unmount(): void;
+}
+/**
+ * Renders `element` with the Lumio reconciler: every commit sends the
+ * serialized tree as `ui.render`, the first one is followed by `ui.ready`, and
+ * `event.callback` invokes the registered handler. `Lumio.render()` in the
+ * Worker runtime calls it once; the devkit mounts a fresh root per test.
+ */
+declare function mountRoot(element: ReactElement, options?: MountRootOptions): MountedRoot;
+
+export { destroyBridgeContext, getBridge, getRegistry, mountRoot, setBridgeFactory, setInitParams };
+export type { InitParams, LumioBridge, MountRootOptions, MountedRoot };

package/dist/host.js

@@ -0,0 +1,368 @@
+import {
+  destroyBridgeContext,
+  getBridge,
+  getRegistry,
+  setBridgeFactory,
+  setInitParams
+} from "./chunk-GVAYWB5X.js";
+
+// src/renderer/render.ts
+import { createElement } from "react";
+import Reconciler from "react-reconciler";
+import { HOST_METHODS } from "@zaflun/lumio-protocol";
+
+// src/renderer/host-config.ts
+import { createContext } from "react";
+
+// src/renderer/reconciler.ts
+var instanceCounter = 0;
+var STRIP_PROPS = /* @__PURE__ */ new Set(["children", "key", "ref", "__self", "__source"]);
+function sanitizeProps(rawProps, registry, existingHandlerIds) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(rawProps)) {
+    if (STRIP_PROPS.has(key)) continue;
+    if (typeof value === "symbol") continue;
+    if (typeof value === "function") {
+      const handlerKey = `__handler_${key}`;
+      const existingId = existingHandlerIds?.[key];
+      if (existingId && registry.has(existingId)) {
+        registry.update(existingId, value);
+        sanitized[handlerKey] = existingId;
+      } else {
+        const id = registry.register(value);
+        sanitized[handlerKey] = id;
+      }
+      continue;
+    }
+    sanitized[key] = value;
+  }
+  return sanitized;
+}
+function createLumioInstance(type, rawProps, registry) {
+  const sanitized = sanitizeProps(rawProps, registry);
+  const handlerIds = {};
+  for (const [key, value] of Object.entries(sanitized)) {
+    if (key.startsWith("__handler_")) {
+      const propName = key.slice("__handler_".length);
+      handlerIds[propName] = value;
+    }
+  }
+  return {
+    _id: `lumio_${++instanceCounter}`,
+    type,
+    props: sanitized,
+    children: [],
+    parent: null,
+    handlerIds
+  };
+}
+function serializeTree(instances) {
+  return instances.map((instance) => ({
+    _id: instance._id,
+    type: instance.type,
+    props: { ...instance.props },
+    children: serializeTree(instance.children)
+  }));
+}
+function treeFingerprint(nodes) {
+  return JSON.stringify(nodes, (key, value) => {
+    if (typeof key === "string" && key.startsWith("__handler_")) return void 0;
+    return value;
+  });
+}
+
+// src/renderer/host-config.ts
+var NoEventPriority = 0;
+var DiscreteEventPriority = 2;
+var DefaultEventPriority = 32;
+var LegacyRoot = 0;
+var RENDERER_PACKAGE_NAME = "@zaflun/lumio-sdk";
+var RENDERER_VERSION = "0.11.1";
+var HostTransitionContext = createContext(null);
+function createHostConfig(registry, options = {}) {
+  const syncUpdates = options.syncUpdates === true;
+  let currentUpdatePriority = NoEventPriority;
+  return {
+    rendererVersion: RENDERER_VERSION,
+    rendererPackageName: RENDERER_PACKAGE_NAME,
+    extraDevToolsConfig: null,
+    // Replays Server Component console logs; Lumio has no Server Components.
+    bindToConsole() {
+      return () => {
+      };
+    },
+    supportsMutation: true,
+    supportsPersistence: false,
+    supportsHydration: false,
+    isPrimaryRenderer: true,
+    warnsIfNotActing: false,
+    scheduleTimeout: setTimeout,
+    cancelTimeout: clearTimeout,
+    noTimeout: -1,
+    supportsMicrotasks: true,
+    scheduleMicrotask: queueMicrotask,
+    getRootHostContext() {
+      return {};
+    },
+    getChildHostContext(_parentCtx) {
+      return {};
+    },
+    getPublicInstance(instance) {
+      return instance;
+    },
+    createInstance(type, props) {
+      return createLumioInstance(type, props, registry);
+    },
+    createTextInstance(text) {
+      return createLumioInstance("Text", { content: text }, registry);
+    },
+    appendInitialChild(parent, child) {
+      child.parent = parent;
+      parent.children.push(child);
+    },
+    appendChild(parent, child) {
+      child.parent = parent;
+      parent.children.push(child);
+    },
+    appendChildToContainer(container, child) {
+      child.parent = null;
+      container.children.push(child);
+    },
+    removeChild(parent, child) {
+      const idx = parent.children.indexOf(child);
+      if (idx !== -1) {
+        parent.children.splice(idx, 1);
+      }
+      child.parent = null;
+      removeHandlersRecursive(child, registry);
+    },
+    removeChildFromContainer(container, child) {
+      const idx = container.children.indexOf(child);
+      if (idx !== -1) {
+        container.children.splice(idx, 1);
+      }
+      child.parent = null;
+      removeHandlersRecursive(child, registry);
+    },
+    insertBefore(parent, child, before) {
+      const idx = parent.children.indexOf(before);
+      if (idx !== -1) {
+        parent.children.splice(idx, 0, child);
+      } else {
+        parent.children.push(child);
+      }
+      child.parent = parent;
+    },
+    insertInContainerBefore(container, child, before) {
+      const idx = container.children.indexOf(before);
+      if (idx !== -1) {
+        container.children.splice(idx, 0, child);
+      } else {
+        container.children.push(child);
+      }
+      child.parent = null;
+    },
+    commitUpdate(instance, _type, _prevProps, nextProps) {
+      const sanitized = sanitizeProps(
+        nextProps,
+        registry,
+        instance.handlerIds
+      );
+      for (const [key, value] of Object.entries(sanitized)) {
+        if (key.startsWith("__handler_")) {
+          const propName = key.slice("__handler_".length);
+          instance.handlerIds[propName] = value;
+        }
+      }
+      instance.props = sanitized;
+    },
+    commitTextUpdate(instance, _oldText, newText) {
+      instance.props.content = newText;
+    },
+    finalizeInitialChildren() {
+      return false;
+    },
+    shouldSetTextContent() {
+      return false;
+    },
+    prepareForCommit() {
+      return null;
+    },
+    resetAfterCommit(container) {
+      container.onCommit();
+    },
+    clearContainer(container) {
+      container.children.length = 0;
+    },
+    preparePortalMount() {
+    },
+    detachDeletedInstance() {
+    },
+    getInstanceFromNode() {
+      return null;
+    },
+    beforeActiveInstanceBlur() {
+    },
+    afterActiveInstanceBlur() {
+    },
+    prepareScopeUpdate() {
+    },
+    getInstanceFromScope() {
+      return null;
+    },
+    // Update priorities. The Worker runtime resolves every update to the
+    // default priority; `syncUpdates` tracks React's priority and resolves
+    // updates from outside React to the discrete (sync) one.
+    setCurrentUpdatePriority(priority) {
+      if (syncUpdates) currentUpdatePriority = priority;
+    },
+    getCurrentUpdatePriority() {
+      return syncUpdates ? currentUpdatePriority : DefaultEventPriority;
+    },
+    resolveUpdatePriority() {
+      if (!syncUpdates) return DefaultEventPriority;
+      return currentUpdatePriority !== NoEventPriority ? currentUpdatePriority : DiscreteEventPriority;
+    },
+    // Form actions (not supported — the context only ever holds `null`)
+    NotPendingTransition: null,
+    HostTransitionContext,
+    // Form instance
+    resetFormInstance() {
+    },
+    // Post paint callback
+    requestPostPaintCallback() {
+    },
+    // Eager transition
+    shouldAttemptEagerTransition() {
+      return false;
+    },
+    // Suspensey commits. Lumio instances never suspend a commit, but React
+    // still calls `startSuspendingCommit` → `suspendOnActiveViewTransition` →
+    // `waitForCommitToBeReady` for every transition-lane commit.
+    maySuspendCommit() {
+      return false;
+    },
+    maySuspendCommitOnUpdate() {
+      return false;
+    },
+    maySuspendCommitInSyncRender() {
+      return false;
+    },
+    preloadInstance() {
+      return true;
+    },
+    startSuspendingCommit() {
+      return null;
+    },
+    suspendInstance() {
+    },
+    suspendOnActiveViewTransition() {
+    },
+    waitForCommitToBeReady() {
+      return null;
+    },
+    getSuspendedCommitReason() {
+      return null;
+    },
+    // Scheduler event tracking
+    trackSchedulerEvent() {
+    },
+    // Event resolution
+    resolveEventType() {
+      return null;
+    },
+    resolveEventTimeStamp() {
+      return Date.now();
+    }
+  };
+}
+function removeHandlersRecursive(instance, registry) {
+  for (const handlerId of Object.values(instance.handlerIds)) {
+    registry.remove(handlerId);
+  }
+  for (const child of instance.children) {
+    removeHandlersRecursive(child, registry);
+  }
+}
+
+// src/renderer/render.ts
+function mountRoot(element, options = {}) {
+  const registry = getRegistry();
+  const bridge = getBridge();
+  const hostConfig = createHostConfig(registry, { syncUpdates: options.syncUpdates });
+  const reconciler = Reconciler(hostConfig);
+  let lastFingerprint = "";
+  const container = {
+    children: [],
+    onCommit() {
+      const tree = serializeTree(container.children);
+      const fingerprint = treeFingerprint(tree);
+      if (fingerprint === lastFingerprint) return;
+      lastFingerprint = fingerprint;
+      bridge.notify("ui.render", { tree });
+    }
+  };
+  const root = reconciler.createContainer(
+    container,
+    LegacyRoot,
+    null,
+    // hydration callbacks
+    false,
+    // isStrictMode
+    null,
+    // concurrentUpdatesByDefaultOverride
+    "",
+    // identifierPrefix
+    (error) => {
+      console.error("[Lumio SDK] Uncaught error:", error);
+    },
+    (error) => {
+      console.error("[Lumio SDK] Caught error:", error);
+    },
+    (error) => {
+      console.error("[Lumio SDK] Recoverable error:", error);
+    },
+    () => {
+    },
+    // onDefaultTransitionIndicator
+    null
+    // transitionCallbacks (typed, but no longer read by 0.34)
+  );
+  const stopCallbacks = bridge.onNotification(HOST_METHODS.EVENT_CALLBACK, (params) => {
+    const { handlerId, args } = params;
+    try {
+      registry.invoke(handlerId, args);
+    } catch {
+    }
+  });
+  const flushSync = (fn) => {
+    if (options.syncUpdates) {
+      reconciler.flushSyncFromReconciler(fn);
+      reconciler.flushPassiveEffects();
+    } else {
+      fn();
+    }
+  };
+  flushSync(() => {
+    reconciler.updateContainer(element, root, null, () => {
+      bridge.notify("ui.ready", {});
+    });
+  });
+  return {
+    flushSync,
+    unmount() {
+      stopCallbacks();
+      flushSync(() => {
+        reconciler.updateContainer(null, root, null, null);
+      });
+    }
+  };
+}
+export {
+  destroyBridgeContext,
+  getBridge,
+  getRegistry,
+  mountRoot,
+  setBridgeFactory,
+  setInitParams
+};