@lumencast/runtime 0.1.0

package/src/mount.ts

@@ -0,0 +1,169 @@
+// Public mount() entry — the only surface a host (browser, CEF, OBS plugin,
+// iframe) interacts with. Lifecycle and contract: see RUNTIME-API.md.
+
+import { signal } from "@preact/signals-react";
+import { createRoot, type Root } from "react-dom/client";
+import { createElement } from "react";
+import { LumencastApp } from "./app.js";
+import { applyDelta } from "./state/apply-delta.js";
+import { applySnapshot } from "./state/apply-snapshot.js";
+import { createStore } from "./state/store.js";
+import { createBundleFetcher, type BundleFetcher, type RenderBundle } from "./render/bundle.js";
+import { WsClient, type ConnectionStatus, type TransportError } from "./transport/ws.js";
+import { validateOptions } from "./internal/validate-options.js";
+import type { LumencastError, LumencastHandle, LumencastToken, MountOptions } from "./types.js";
+
+export function mount(options: MountOptions): LumencastHandle {
+  validateOptions(options);
+  options.onStatus?.("disconnected");
+
+  const store = createStore();
+  const baseUrl = deriveBaseUrl(options.serverUrl);
+  const bundleFetcher = createBundleFetcher({ baseUrl });
+
+  const bundleSignal = signal<RenderBundle | null>(null);
+  const statusSignal = signal<ConnectionStatus>("disconnected");
+  const crossfadeKeySignal = signal<string>("__initial__");
+
+  const setStatus = (status: ConnectionStatus): void => {
+    statusSignal.value = status;
+    options.onStatus?.(status);
+  };
+
+  const reportError = (err: LumencastError): void => {
+    options.onError?.(err);
+  };
+
+  let active = true;
+
+  const ws = new WsClient({
+    url: options.serverUrl,
+    token: options.token,
+    ...(options.scene !== undefined ? { scene: options.scene } : {}),
+    ...(options.testSession !== undefined ? { session: options.testSession } : {}),
+    onStatus: setStatus,
+    onSnapshot: (frame) => {
+      if (!active) return;
+      void onSnapshot(
+        bundleFetcher,
+        bundleSignal,
+        crossfadeKeySignal,
+        frame.scene_id,
+        frame.scene_version,
+        () => applySnapshot(store, frame),
+        reportError,
+      );
+      options.onMetric?.({
+        name: "snapshot_received",
+        scene_id: frame.scene_id,
+        path_count: Object.keys(frame.state).length,
+      });
+    },
+    onDelta: (frame) => {
+      if (!active) return;
+      const start = performance.now();
+      applyDelta(store, frame);
+      options.onMetric?.({
+        name: "delta_applied",
+        duration_ms: performance.now() - start,
+      });
+      options.onMetric?.({ name: "delta_received", count: 1, path_count: frame.patches.length });
+    },
+    onSceneChanged: (frame) => {
+      if (!active) return;
+      // The fresh snapshot that follows is the source of truth — it carries
+      // the new scene_version, drives the bundle fetch, and flips the
+      // crossfade key. Nothing eager to do here.
+      options.onMetric?.({
+        name: "scene_changed",
+        from: bundleSignal.value?.scene_version ?? null,
+        to: frame.scene_version,
+      });
+    },
+    onServerError: (frame) => {
+      reportError({
+        code: frame.code,
+        message: frame.message,
+        recoverable: frame.recoverable,
+      });
+    },
+    onTransportError: (err) => {
+      reportError(transportToLumencastError(err));
+    },
+  });
+
+  ws.start();
+
+  const root: Root = createRoot(options.target);
+  root.render(
+    createElement(LumencastApp, {
+      mode: options.mode,
+      store,
+      bundleSignal,
+      statusSignal,
+      crossfadeKeySignal,
+      sendInput: (patches) => ws.sendInput(patches),
+    }),
+  );
+
+  return {
+    disconnect() {
+      if (!active) return;
+      active = false;
+      ws.close();
+      root.unmount();
+    },
+    setToken(token: LumencastToken) {
+      if (!active) return;
+      ws.setToken(token);
+    },
+  };
+
+  // --- helpers ----------------------------------------------------------
+
+  async function onSnapshot(
+    fetcher: BundleFetcher,
+    bSignal: typeof bundleSignal,
+    cSignal: typeof crossfadeKeySignal,
+    sceneId: string,
+    sceneVersion: string,
+    applyState: () => void,
+    onErr: (err: LumencastError) => void,
+  ): Promise<void> {
+    let bundle: RenderBundle;
+    try {
+      bundle = await fetcher.get(sceneId, sceneVersion);
+    } catch (err) {
+      onErr({
+        code: "BUNDLE_FETCH_FAILED",
+        message: err instanceof Error ? err.message : "render bundle fetch failed",
+        recoverable: true,
+      });
+      return;
+    }
+    if (!active) return;
+    applyState();
+    bSignal.value = bundle;
+    cSignal.value = `${sceneId}::${sceneVersion}`;
+  }
+}
+
+function transportToLumencastError(err: TransportError): LumencastError {
+  return {
+    code: err.code,
+    message: err.message,
+    recoverable: err.recoverable,
+  };
+}
+
+function deriveBaseUrl(wsUrl: string): string {
+  // wss://<host>/lsdp/v1 → https://<host>
+  // ws://<host>/lsdp/v1  → http://<host>
+  try {
+    const u = new URL(wsUrl);
+    const httpScheme = u.protocol === "wss:" ? "https:" : "http:";
+    return `${httpScheme}//${u.host}`;
+  } catch {
+    return "";
+  }
+}

package/src/overlay/control.tsx

@@ -0,0 +1,239 @@
+import { useSignals } from "@preact/signals-react/runtime";
+import type { OperatorInput } from "../render/bundle";
+import { useLumencastRuntime } from "./runtime-context";
+
+const PANEL_STYLE: React.CSSProperties = {
+  position: "fixed",
+  bottom: 12,
+  left: 12,
+  zIndex: 100_000,
+  width: 320,
+  maxHeight: "70vh",
+  overflowY: "auto",
+  padding: 12,
+  fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, sans-serif",
+  fontSize: 12,
+  color: "#e5e7eb",
+  background: "rgba(17, 24, 39, 0.92)",
+  border: "1px solid rgba(75, 85, 99, 0.6)",
+  borderRadius: 10,
+  boxShadow: "0 8px 32px rgba(0, 0, 0, 0.45)",
+};
+
+const ROW_STYLE: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: 4,
+  padding: "6px 0",
+  borderBottom: "1px solid rgba(75, 85, 99, 0.35)",
+};
+
+const LABEL_STYLE: React.CSSProperties = {
+  color: "#9ca3af",
+  fontSize: 10.5,
+  letterSpacing: "0.02em",
+  textTransform: "uppercase",
+};
+
+const INPUT_STYLE: React.CSSProperties = {
+  background: "rgba(31, 41, 55, 0.8)",
+  border: "1px solid rgba(75, 85, 99, 0.6)",
+  borderRadius: 6,
+  color: "#f9fafb",
+  padding: "4px 6px",
+  fontSize: 12,
+  width: "100%",
+};
+
+export function ControlPanel() {
+  const { bundle, store, sendInput } = useLumencastRuntime();
+  useSignals();
+
+  const inputs = bundle.operator_inputs ?? [];
+  if (inputs.length === 0) return null;
+
+  // Group entries by `group` field for readability.
+  const groups = new Map<string, OperatorInput[]>();
+  for (const entry of inputs) {
+    const g = entry.group ?? "General";
+    const list = groups.get(g) ?? [];
+    list.push(entry);
+    groups.set(g, list);
+  }
+
+  return (
+    <div style={PANEL_STYLE} data-testid="lumencast-control-panel">
+      <div
+        style={{
+          fontWeight: 600,
+          fontSize: 11,
+          letterSpacing: "0.06em",
+          color: "#9ca3af",
+          textTransform: "uppercase",
+          marginBottom: 6,
+        }}
+      >
+        Operator inputs
+      </div>
+      {[...groups.entries()].map(([group, entries]) => (
+        <div key={group} style={{ marginBottom: 8 }}>
+          <div
+            style={{
+              color: "#6b7280",
+              fontSize: 10,
+              letterSpacing: "0.04em",
+              textTransform: "uppercase",
+              padding: "4px 0",
+            }}
+          >
+            {group}
+          </div>
+          {entries.map((entry) => (
+            <InputRow
+              key={entry.path}
+              entry={entry}
+              currentValue={store.signal(entry.path).value}
+              onCommit={(v) =>
+                // Operator-control values come from form widgets typed per
+                // OperatorInput.type; coerce to LeafValue at the boundary.
+                sendInput([
+                  {
+                    path: entry.path,
+                    value: v as Parameters<typeof sendInput>[0][number]["value"],
+                  },
+                ])
+              }
+            />
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function InputRow({
+  entry,
+  currentValue,
+  onCommit,
+}: {
+  entry: OperatorInput;
+  currentValue: unknown;
+  onCommit: (value: unknown) => void;
+}) {
+  return (
+    <div style={ROW_STYLE}>
+      <span style={LABEL_STYLE}>{entry.label}</span>
+      <Editor entry={entry} currentValue={currentValue} onCommit={onCommit} />
+    </div>
+  );
+}
+
+function Editor({
+  entry,
+  currentValue,
+  onCommit,
+}: {
+  entry: OperatorInput;
+  currentValue: unknown;
+  onCommit: (value: unknown) => void;
+}) {
+  switch (entry.type) {
+    case "boolean": {
+      const checked = currentValue === true;
+      return (
+        <label style={{ display: "flex", alignItems: "center", gap: 6 }}>
+          <input type="checkbox" checked={checked} onChange={(e) => onCommit(e.target.checked)} />
+          <span style={{ fontSize: 11, color: "#d1d5db" }}>{checked ? "on" : "off"}</span>
+        </label>
+      );
+    }
+    case "number": {
+      const min = entry.min as number | undefined;
+      const max = entry.max as number | undefined;
+      const step = entry.step as number | undefined;
+      return (
+        <input
+          type="number"
+          style={INPUT_STYLE}
+          value={typeof currentValue === "number" ? currentValue : ""}
+          min={min}
+          max={max}
+          step={step}
+          onChange={(e) => {
+            const n = Number(e.target.value);
+            if (Number.isFinite(n)) onCommit(n);
+          }}
+        />
+      );
+    }
+    case "text": {
+      const max = entry.max_length as number | undefined;
+      return (
+        <input
+          type="text"
+          style={INPUT_STYLE}
+          value={typeof currentValue === "string" ? currentValue : ""}
+          maxLength={max}
+          onChange={(e) => onCommit(e.target.value)}
+        />
+      );
+    }
+    case "colour": {
+      return (
+        <input
+          type="color"
+          style={INPUT_STYLE}
+          value={typeof currentValue === "string" ? currentValue : "#000000"}
+          onChange={(e) => onCommit(e.target.value)}
+        />
+      );
+    }
+    case "duration": {
+      return (
+        <input
+          type="number"
+          style={INPUT_STYLE}
+          value={typeof currentValue === "number" ? currentValue : ""}
+          min={0}
+          step={100}
+          onChange={(e) => {
+            const n = Number(e.target.value);
+            if (Number.isFinite(n) && n >= 0) onCommit(n);
+          }}
+        />
+      );
+    }
+    case "select":
+    case "enum": {
+      const options =
+        (entry.enum_values as string[] | undefined) ??
+        (entry.options as string[] | undefined) ??
+        [];
+      return (
+        <select
+          style={INPUT_STYLE}
+          value={typeof currentValue === "string" ? currentValue : ""}
+          onChange={(e) => onCommit(e.target.value)}
+        >
+          {options.map((opt) => (
+            <option key={opt} value={opt}>
+              {opt}
+            </option>
+          ))}
+        </select>
+      );
+    }
+    case "path-ref":
+    default:
+      // FIXME (v2) — `path-ref` UX is deferred ; for now show a plain
+      // text entry so the value is still editable.
+      return (
+        <input
+          type="text"
+          style={INPUT_STYLE}
+          value={typeof currentValue === "string" ? currentValue : ""}
+          onChange={(e) => onCommit(e.target.value)}
+        />
+      );
+  }
+}

package/src/overlay/runtime-context.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { Patch } from "@lumencast/protocol";
+import type { Store } from "../state/store";
+import type { RenderBundle } from "../render/bundle";
+import type { ConnectionStatus } from "../transport/ws";
+import type { LumencastMode } from "../types";
+
+export interface LumencastRuntime {
+  mode: LumencastMode;
+  store: Store;
+  bundle: RenderBundle;
+  status: ConnectionStatus;
+  /** Send LSDP/1 input patches to the server. */
+  sendInput: (patches: Patch[]) => void;
+}
+
+const Ctx = createContext<LumencastRuntime | null>(null);
+
+export function LumencastRuntimeProvider({
+  value,
+  children,
+}: {
+  value: LumencastRuntime;
+  children: ReactNode;
+}) {
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useLumencastRuntime(): LumencastRuntime {
+  const v = useContext(Ctx);
+  if (!v) {
+    throw new Error(
+      "Lumencast overlay components must be rendered inside LumencastRuntimeProvider",
+    );
+  }
+  return v;
+}

package/src/overlay/status-pill.tsx

@@ -0,0 +1,37 @@
+import { useLumencastRuntime } from "./runtime-context";
+
+const COLOURS: Record<string, string> = {
+  live: "rgba(34, 197, 94, 0.85)",
+  connecting: "rgba(234, 179, 8, 0.85)",
+  disconnected: "rgba(239, 68, 68, 0.85)",
+};
+
+const LABELS: Record<string, string> = {
+  live: "live",
+  connecting: "reconnecting",
+  disconnected: "disconnected",
+};
+
+export function StatusPill() {
+  const { status } = useLumencastRuntime();
+  return (
+    <div
+      data-testid="lumencast-status-pill"
+      style={{
+        position: "fixed",
+        top: 12,
+        right: 12,
+        padding: "4px 10px",
+        fontSize: 11,
+        fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, sans-serif",
+        color: "white",
+        background: COLOURS[status] ?? "#444",
+        borderRadius: 999,
+        userSelect: "none",
+        pointerEvents: "none",
+      }}
+    >
+      {LABELS[status] ?? status}
+    </div>
+  );
+}

package/src/overlay/test.tsx

@@ -0,0 +1,213 @@
+import { useSignals } from "@preact/signals-react/runtime";
+import { useState } from "react";
+import { useLumencastRuntime } from "./runtime-context";
+
+const PANEL_STYLE: React.CSSProperties = {
+  position: "fixed",
+  bottom: 12,
+  right: 12,
+  zIndex: 100_001,
+  width: 360,
+  maxHeight: "70vh",
+  overflowY: "auto",
+  padding: 12,
+  fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, sans-serif",
+  fontSize: 12,
+  color: "#e5e7eb",
+  background: "rgba(8, 47, 73, 0.92)",
+  border: "1px solid rgba(56, 189, 248, 0.4)",
+  borderRadius: 10,
+  boxShadow: "0 8px 32px rgba(0, 0, 0, 0.45)",
+};
+
+const SECTION_TITLE: React.CSSProperties = {
+  fontWeight: 600,
+  fontSize: 11,
+  letterSpacing: "0.06em",
+  color: "#7dd3fc",
+  textTransform: "uppercase",
+  marginBottom: 6,
+};
+
+const BUTTON_STYLE: React.CSSProperties = {
+  background: "rgba(14, 165, 233, 0.4)",
+  border: "1px solid rgba(125, 211, 252, 0.5)",
+  borderRadius: 6,
+  color: "#f0f9ff",
+  padding: "3px 8px",
+  fontSize: 11,
+  cursor: "pointer",
+};
+
+const ADAPTER_ROW: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: 4,
+  padding: "6px 0",
+  borderBottom: "1px solid rgba(56, 189, 248, 0.2)",
+};
+
+/** Test-mode overlay : adapter mocker + state inspector + time
+ *  controls. Drives the server's __test.* family via the same `sendInput`
+ *  channel. */
+export function TestPanel() {
+  const { bundle, store, sendInput } = useLumencastRuntime();
+  useSignals();
+  const [filter, setFilter] = useState("");
+
+  const adapters = bundle.external_adapters ?? [];
+  const stateRecord = store.toRecord();
+  const filteredEntries = Object.entries(stateRecord).filter(
+    ([k]) => filter === "" || k.includes(filter),
+  );
+
+  return (
+    <div style={PANEL_STYLE} data-testid="lumencast-test-panel">
+      {/* Time controls */}
+      <div style={SECTION_TITLE}>Time</div>
+      <div style={{ display: "flex", gap: 6, marginBottom: 8 }}>
+        <button
+          type="button"
+          style={BUTTON_STYLE}
+          onClick={() => sendInput([{ path: "__test.tick", value: 100 }])}
+        >
+          tick +100ms
+        </button>
+        <button
+          type="button"
+          style={BUTTON_STYLE}
+          onClick={() => sendInput([{ path: "__test.tick", value: 1_000 }])}
+        >
+          tick +1s
+        </button>
+        <button
+          type="button"
+          style={BUTTON_STYLE}
+          onClick={() => sendInput([{ path: "__test.reset", value: true }])}
+        >
+          reset
+        </button>
+      </div>
+
+      {/* Adapter mocker */}
+      <div style={SECTION_TITLE}>External adapters</div>
+      {adapters.length === 0 && (
+        <div style={{ color: "#94a3b8", fontStyle: "italic", fontSize: 11 }}>
+          No external adapters declared in this scene.
+        </div>
+      )}
+      {adapters.map((adapter) => (
+        <AdapterRow
+          key={adapter.key}
+          adapter={adapter}
+          onMock={(payload) =>
+            // LSDP/1 patch values must be leaf — JSON-encode the structured payload.
+            sendInput([
+              {
+                path: "__test.mock_adapter",
+                value: JSON.stringify({ key: adapter.key, payload }),
+              },
+            ])
+          }
+        />
+      ))}
+
+      {/* State inspector */}
+      <div style={{ ...SECTION_TITLE, marginTop: 12 }}>State</div>
+      <input
+        type="text"
+        placeholder="filter paths…"
+        value={filter}
+        onChange={(e) => setFilter(e.target.value)}
+        style={{
+          background: "rgba(8, 47, 73, 0.6)",
+          border: "1px solid rgba(125, 211, 252, 0.4)",
+          borderRadius: 6,
+          color: "#e0f2fe",
+          padding: "4px 6px",
+          fontSize: 11,
+          width: "100%",
+          marginBottom: 6,
+        }}
+      />
+      <div style={{ fontFamily: "monospace", fontSize: 10.5 }}>
+        {filteredEntries.map(([path, value]) => (
+          <div
+            key={path}
+            style={{
+              display: "grid",
+              gridTemplateColumns: "1fr auto",
+              gap: 8,
+              padding: "2px 0",
+              borderBottom: "1px dashed rgba(125, 211, 252, 0.15)",
+            }}
+          >
+            <span style={{ color: "#bae6fd" }}>{path}</span>
+            <span style={{ color: "#fef3c7" }}>{formatValue(value)}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function AdapterRow({
+  adapter,
+  onMock,
+}: {
+  adapter: { key: string; label: string; kind: string };
+  onMock: (payload: unknown) => void;
+}) {
+  const [draft, setDraft] = useState("{}");
+  return (
+    <div style={ADAPTER_ROW}>
+      <div
+        style={{
+          display: "flex",
+          justifyContent: "space-between",
+          alignItems: "center",
+        }}
+      >
+        <span style={{ color: "#e0f2fe" }}>{adapter.label}</span>
+        <span style={{ color: "#94a3b8", fontSize: 10 }}>{adapter.kind}</span>
+      </div>
+      <textarea
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        rows={2}
+        style={{
+          fontFamily: "monospace",
+          fontSize: 10.5,
+          background: "rgba(8, 47, 73, 0.6)",
+          color: "#e0f2fe",
+          border: "1px solid rgba(125, 211, 252, 0.3)",
+          borderRadius: 4,
+          padding: 4,
+          resize: "vertical",
+        }}
+      />
+      <button
+        type="button"
+        style={BUTTON_STYLE}
+        onClick={() => {
+          try {
+            const parsed = JSON.parse(draft);
+            onMock(parsed);
+          } catch {
+            onMock(draft);
+          }
+        }}
+      >
+        fire
+      </button>
+    </div>
+  );
+}
+
+function formatValue(value: unknown): string {
+  if (value === undefined) return "—";
+  if (value === null) return "null";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}