@ethisyscore/extension-runtime 1.6.0

package/README.md

@@ -0,0 +1,42 @@
+# @ethisyscore/extension-runtime
+
+Host + plugin runtime for EthisysCore extension contracts:
+
+- **Contract A** — host-rendered SDUI extensions. Plugins return a closed-vocabulary `SduiNode` tree from a `ResourceHandler`; the host's declarative interpreter mounts it directly.
+- **Contract B** — worker remote-runtime extensions. Plugin code runs in a sandboxed Web Worker; UI mutations flow via Remote DOM into the host's semantic primitive registry. The capability token never crosses the worker boundary.
+
+Built on top of `@ethisyscore/protocol` (canonical bridge / manifest / SDUI / capability / theme types).
+
+## Subpath exports
+
+| Entry | Use | Surface |
+| ----- | --- | ------- |
+| `@ethisyscore/extension-runtime` | Root re-exports | Stable consumer-facing types and helpers. |
+| `@ethisyscore/extension-runtime/host` | Host integration | `WorkerRemoteDomTransport`, declarative interpreter, semantic component registry, offscreen-canvas helpers. |
+| `@ethisyscore/extension-runtime/plugin` | Plugin side | `ExtensionRuntimeProvider`, `useMcpResource`, `useMcpTool`, transport abstraction. |
+| `@ethisyscore/extension-runtime/mock-host` | Local dev | `DeclarativeMockHost` and the `mock-host` CLI entry. |
+
+The `mock-host` bin (`npx mock-host <dir>`) is shipped — boots a Vite dev page that mounts the declarative interpreter against a directory of SDUI JSON resources. Run `--render-mode remote-runtime <bundle>` for the Contract B variant.
+
+## Local development
+
+This package consumes `@ethisyscore/protocol` via `npm link`. The protocol package is registered globally in E1.S8:
+
+```powershell
+cd <repo>/sdk/extension-runtime
+npm install
+npm link @ethisyscore/protocol
+```
+
+## Scripts
+
+| Script           | Purpose                            |
+| ---------------- | ---------------------------------- |
+| `npm run build`  | Build ESM + CJS + `.d.ts` via tsup |
+| `npm test`       | Run unit tests (Vitest, jsdom)     |
+| `npm run lint`   | Type-check only (`tsc --noEmit`)   |
+
+## Targets
+
+- Node.js >= 20
+- React >= 18 (peer dep, required by `./host` and `./plugin` subpaths in later tasks)

package/bin/mock-host.cjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Thin CJS shim for the `mock-host` bin. Requires the tsup-built CJS bundle
+// and dispatches to `run(argv)` so the dual ESM/CJS package layout doesn't
+// fight with `#!/usr/bin/env node`. Hand-written and committed; tsup is
+// configured to produce `dist/mock-host/cli.cjs` which this loads.
+"use strict";
+
+const { run } = require("../dist/mock-host/cli.cjs");
+
+run(process.argv.slice(2)).catch(err =>
+{
+    process.stderr.write(`mock-host: ${err && err.message ? err.message : err}\n`);
+    process.exit(1);
+});

package/dist/host/index.cjs

@@ -0,0 +1,600 @@
+'use strict';
+
+var protocol = require('@ethisyscore/protocol');
+var react = require('react');
+var receivers = require('@remote-dom/core/receivers');
+var host = require('@remote-dom/react/host');
+
+// src/host/declarative/evaluator.ts
+var KNOWN_OPERATOR_SET = new Set(protocol.KNOWN_OPERATORS);
+function evaluate(expr, context) {
+  if (expr === null) {
+    return null;
+  }
+  const t = typeof expr;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return expr;
+  }
+  if (t === "function") {
+    throw new Error("Function-typed values are not allowed in expressions.");
+  }
+  if (Array.isArray(expr)) {
+    return expr.map((e) => evaluate(e, context));
+  }
+  if (t !== "object") {
+    throw new Error(`Unsupported expression type: ${t}.`);
+  }
+  const obj = expr;
+  const keys = Object.keys(obj);
+  if (keys.length !== 1) {
+    throw new Error(
+      `Expression object must have exactly one operator key (got ${keys.length}).`
+    );
+  }
+  const op = keys[0];
+  if (!KNOWN_OPERATOR_SET.has(op)) {
+    throw new Error(`Unknown operator: ${op}.`);
+  }
+  const rawArgs = obj[op];
+  if (op === "var") {
+    const path = typeof rawArgs === "string" ? rawArgs : Array.isArray(rawArgs) && typeof rawArgs[0] === "string" ? rawArgs[0] : "";
+    return resolveVar(path, context);
+  }
+  const evaluatedArgs = Array.isArray(rawArgs) ? rawArgs.map((a) => evaluate(a, context)) : [evaluate(rawArgs, context)];
+  switch (op) {
+    case "==":
+      return evaluatedArgs[0] === evaluatedArgs[1];
+    case "!=":
+      return evaluatedArgs[0] !== evaluatedArgs[1];
+    case ">":
+      return evaluatedArgs[0] > evaluatedArgs[1];
+    case "<":
+      return evaluatedArgs[0] < evaluatedArgs[1];
+    case ">=":
+      return evaluatedArgs[0] >= evaluatedArgs[1];
+    case "<=":
+      return evaluatedArgs[0] <= evaluatedArgs[1];
+    case "and":
+      return evaluatedArgs.every(Boolean);
+    case "or":
+      return evaluatedArgs.some(Boolean);
+    case "not":
+      return !evaluatedArgs[0];
+    case "+":
+      return evaluatedArgs.reduce((acc, n) => acc + n, 0);
+    case "-":
+      return evaluatedArgs[0] - evaluatedArgs[1];
+    case "*":
+      return evaluatedArgs.reduce((acc, n) => acc * n, 1);
+    case "/":
+      return safeDivide(evaluatedArgs[0], evaluatedArgs[1]);
+    case "%":
+      return safeModulo(evaluatedArgs[0], evaluatedArgs[1]);
+    default:
+      throw new Error(`Unknown operator: ${op}.`);
+  }
+}
+function safeDivide(a, b) {
+  if (b === 0 || !Number.isFinite(b)) {
+    throw new Error(
+      `Division by ${b === 0 ? "zero" : String(b)} is not allowed in the closed evaluator.`
+    );
+  }
+  return a / b;
+}
+function safeModulo(a, b) {
+  if (b === 0 || !Number.isFinite(b)) {
+    throw new Error(
+      `Modulo by ${b === 0 ? "zero" : String(b)} is not allowed in the closed evaluator.`
+    );
+  }
+  return a % b;
+}
+function resolveVar(path, context) {
+  if (path === "") {
+    return void 0;
+  }
+  const parts = path.split(".");
+  let curr = context;
+  for (const part of parts) {
+    if (curr === null || typeof curr !== "object") {
+      return void 0;
+    }
+    curr = curr[part];
+  }
+  return curr;
+}
+function interpret(node, registry) {
+  const Component = registry[node.type];
+  if (!Component) {
+    throw new Error(`Unknown SDUI primitive: ${String(node.type)}`);
+  }
+  const children = node.children?.map(
+    (child, index) => interpretChild(child, registry, index)
+  );
+  return react.createElement(Component, { props: node.props }, children);
+}
+function interpretChild(node, registry, index) {
+  const Component = registry[node.type];
+  if (!Component) {
+    throw new Error(`Unknown SDUI primitive: ${String(node.type)}`);
+  }
+  const children = node.children?.map(
+    (child, childIndex) => interpretChild(child, registry, childIndex)
+  );
+  return react.createElement(Component, { props: node.props, key: index }, children);
+}
+
+// src/host/worker/component-registry.ts
+var CONTRACT_B_PRIMITIVES = [
+  "Button",
+  "DataTable",
+  "Form",
+  "EntityPicker",
+  "CommandBar",
+  "Drawer",
+  "Modal",
+  "CanvasSurface",
+  "WebGLSurface"
+];
+var KNOWN_PRIMITIVE_SET = new Set(CONTRACT_B_PRIMITIVES);
+var SemanticComponentRegistry = class _SemanticComponentRegistry {
+  entries = /* @__PURE__ */ new Map();
+  /**
+   * Register a primitive → component binding.
+   *
+   * Throws if `name` is not in {@link CONTRACT_B_PRIMITIVES} (drift prevention)
+   * or if `name` is already registered (silent-override prevention).
+   */
+  register(name, component) {
+    if (!KNOWN_PRIMITIVE_SET.has(name)) {
+      throw new Error(
+        `[component-registry] unknown semantic primitive '${name}'. Allowed: ${CONTRACT_B_PRIMITIVES.join(", ")}.`
+      );
+    }
+    if (this.entries.has(name)) {
+      throw new Error(
+        `[component-registry] primitive '${name}' is already registered. Construct a new registry instead of overriding a binding.`
+      );
+    }
+    this.entries.set(name, component);
+  }
+  /**
+   * Resolve a primitive name to its concrete component. Throws if the name is
+   * outside the Contract B vocabulary OR if the registry has no binding —
+   * silent fallthrough would let typos render blank components, which is
+   * worse than a fast failure for plugin authors.
+   */
+  resolve(name) {
+    if (!KNOWN_PRIMITIVE_SET.has(name)) {
+      throw new Error(
+        `[component-registry] unknown semantic primitive '${name}'. Allowed: ${CONTRACT_B_PRIMITIVES.join(", ")}.`
+      );
+    }
+    const found = this.entries.get(name);
+    if (found === void 0) {
+      const registered = this.listRegistered().join(", ") || "<none>";
+      throw new Error(
+        `[component-registry] primitive '${name}' is not registered. Registered primitives: ${registered}.`
+      );
+    }
+    return found;
+  }
+  /**
+   * Cheap presence probe — never throws. Use this when callers want to
+   * fall back to a default component instead of erroring.
+   */
+  has(name) {
+    return this.entries.has(name);
+  }
+  /**
+   * Sorted list of registered primitive names. Stable output makes registry
+   * diagnostics and snapshot tests deterministic.
+   */
+  listRegistered() {
+    return [...this.entries.keys()].sort();
+  }
+  /**
+   * Build a registry from a complete `Record<SemanticPrimitiveName, T>` map.
+   *
+   * The `Record` type forces TypeScript to refuse incomplete literals at
+   * compile time, AND we re-check at runtime so callers who type-erase the
+   * record (e.g., via `as any`) still get a fast failure.
+   */
+  static fromMap(map) {
+    const registry = new _SemanticComponentRegistry();
+    const missing = [];
+    for (const name of CONTRACT_B_PRIMITIVES) {
+      const component = map[name];
+      if (component === void 0) {
+        missing.push(name);
+        continue;
+      }
+      registry.register(name, component);
+    }
+    if (missing.length > 0) {
+      throw new Error(
+        `[component-registry] fromMap is missing semantic primitive(s): ${missing.join(", ")}.`
+      );
+    }
+    return registry;
+  }
+};
+
+// src/host/worker/offscreen.ts
+var DEFAULT_OFFSCREEN_COALESCE_MS = 16;
+var transferredCanvases = /* @__PURE__ */ new WeakSet();
+function createOffscreenCanvasTransfer(options) {
+  const { canvas, surfaceId, postMessage } = options;
+  const proto = HTMLCanvasElement.prototype;
+  if (typeof proto.transferControlToOffscreen !== "function") {
+    throw new Error(
+      "[offscreen-canvas] OffscreenCanvas is not supported in this environment. Contract B canvas surfaces require a browser with HTMLCanvasElement.transferControlToOffscreen."
+    );
+  }
+  if (transferredCanvases.has(canvas)) {
+    throw new Error(
+      `[offscreen-canvas] canvas already transferred (surfaceId='${surfaceId}'). Create a fresh <canvas> for each surface instead of re-transferring.`
+    );
+  }
+  const offscreen = canvas.transferControlToOffscreen();
+  transferredCanvases.add(canvas);
+  const envelope = {
+    type: "ethisys:offscreen:transfer",
+    surfaceId,
+    width: canvas.width,
+    height: canvas.height,
+    offscreen
+  };
+  postMessage(envelope, [offscreen]);
+  return { offscreen };
+}
+function createInputEventCoalescer(sink, options = {}) {
+  if (options.discrete === true) {
+    return (payload) => {
+      sink(payload);
+    };
+  }
+  const coalesceMs = options.coalesceMs ?? DEFAULT_OFFSCREEN_COALESCE_MS;
+  let pending;
+  let pendingSet = false;
+  let timer;
+  const flush = () => {
+    timer = void 0;
+    if (!pendingSet) {
+      return;
+    }
+    const value = pending;
+    pending = void 0;
+    pendingSet = false;
+    sink(value);
+  };
+  return (payload) => {
+    pending = payload;
+    pendingSet = true;
+    if (timer === void 0) {
+      timer = setTimeout(flush, coalesceMs);
+    }
+  };
+}
+
+// src/host/worker/transport.ts
+var WORKER_TRANSPORT_PROTOCOL = "ethisys.worker.remotedom.v1";
+var DEFAULT_MAX_CONCURRENT_MCP_REQUESTS = 8;
+var WorkerRemoteDomTransport = class {
+  worker;
+  hostPort;
+  workerPort;
+  mcpClient;
+  capabilityTokenProvider;
+  coalesceMs;
+  maxConcurrentMcpRequests;
+  abortController;
+  inFlightMcpRequests = 0;
+  remoteDomConsumer;
+  disposed = false;
+  connected = false;
+  constructor(options) {
+    const WorkerCtor = options.workerCtor ?? globalThis.Worker;
+    if (!WorkerCtor) {
+      throw new Error("WorkerRemoteDomTransport: no Worker constructor available");
+    }
+    this.mcpClient = options.mcpClient;
+    this.capabilityTokenProvider = options.capabilityToken;
+    this.coalesceMs = options.coalesceMs ?? 16;
+    this.maxConcurrentMcpRequests = Math.max(
+      1,
+      options.maxConcurrentMcpRequests ?? DEFAULT_MAX_CONCURRENT_MCP_REQUESTS
+    );
+    this.abortController = new AbortController();
+    this.worker = new WorkerCtor(options.bootstrapUrl, { type: "module" });
+    const channel = new MessageChannel();
+    this.hostPort = channel.port1;
+    this.workerPort = channel.port2;
+    this.hostPort.onmessage = (ev) => this.handlePortMessage(ev.data);
+    this.hostPort.start();
+    this.worker.onerror = (ev) => {
+    };
+  }
+  /**
+   * Post the handshake to the worker. Idempotent — only the FIRST call
+   * transfers the {@link MessagePort} and posts the handshake payload;
+   * subsequent calls are silent no-ops. Splitting this off from the
+   * constructor lets the host mount fetch the per-plugin
+   * `worker-bundle.import-map.json` (and resolve the bundle's module URL)
+   * before the bootstrap script consumes them.
+   *
+   * Wire shape: {@link WorkerHandshakePayload}. The capability token NEVER
+   * appears in the payload — it's bound on the host side via the
+   * {@link WorkerRemoteDomTransportOptions.capabilityToken} provider.
+   *
+   * The `moduleUrl` and `importMap` are forwarded to the worker so the
+   * bootstrap script (served from the host-pinned
+   * `/extensions/runtime/worker-bootstrap.js`) can:
+   *   1. Compose the frozen, same-origin-validated `IMPORT_MAP` from the
+   *      handshake payload (rejecting any cross-origin entries).
+   *   2. `safeImport(moduleUrl)` the plugin's entry module.
+   *
+   * Same-origin enforcement is the bootstrap's job — this transport is
+   * structurally agnostic to the host origin and only forwards what it's
+   * handed.
+   */
+  connect(moduleUrl, importMap) {
+    if (this.connected) {
+      return;
+    }
+    this.connected = true;
+    const handshake = Object.freeze({
+      type: "ethisys:worker:handshake",
+      protocol: WORKER_TRANSPORT_PROTOCOL,
+      moduleUrl,
+      importMap: Object.freeze({ ...importMap })
+    });
+    this.worker.postMessage(handshake, [this.workerPort]);
+  }
+  /**
+   * Bind a consumer for Remote DOM mutation payloads emitted by the worker.
+   * The Remote DOM receiver wiring is owned by the caller (typically a host
+   * React component); this method exposes the raw stream so the receiver
+   * can integrate cleanly without a circular package import.
+   */
+  onRemoteDom(consumer) {
+    this.remoteDomConsumer = consumer;
+  }
+  /**
+   * Transfer control of a host-owned `<canvas>` to the worker so plugin code
+   * can render via `OffscreenCanvas`. The host retains the `<canvas>` for
+   * layout / accessibility purposes only — every pixel is produced inside the
+   * worker, so the main thread is never blocked per frame.
+   *
+   * The transfer rides the established MessagePort (not the worker global
+   * `postMessage`) so it is multiplexed with the rest of the host ↔ worker
+   * traffic on the same channel. The `OffscreenCanvas` handle is the sole
+   * `Transferable` in the envelope; no capability token, MCP context, or
+   * other host-only data crosses the boundary.
+   *
+   * Throws if the environment lacks `transferControlToOffscreen()` or if the
+   * canvas has already been transferred — see {@link createOffscreenCanvasTransfer}
+   * for the exact diagnostics.
+   */
+  transferCanvas(canvas, options) {
+    return createOffscreenCanvasTransfer({
+      canvas,
+      surfaceId: options.surfaceId,
+      postMessage: (message, transfer) => {
+        this.hostPort.postMessage(message, transfer);
+      }
+    });
+  }
+  /**
+   * Forward a host-sourced input event to the worker over the port. The
+   * payload shape is opaque to the transport — pointer / wheel / keyboard
+   * envelopes share the same wire type. Callers are expected to wrap
+   * high-frequency (pointer-move, wheel, scroll) events in
+   * {@link createCoalescer} or {@link createInputEventCoalescer} BEFORE
+   * calling this method so the port never sees the un-coalesced flood.
+   *
+   * Keyboard / pointer-down / pointer-up events are discrete and should be
+   * delivered without coalescing — pass them straight through.
+   */
+  postInputEvent(payload) {
+    this.hostPort.postMessage({
+      type: "ethisys:input:event",
+      payload
+    });
+  }
+  /**
+   * Build a trailing-edge coalescer keyed to {@link WorkerRemoteDomTransportOptions.coalesceMs}.
+   *
+   * Use it to wrap pointer-move / scroll / resize callbacks **before**
+   * they cross the port. The last payload in any coalescing window is the
+   * one that wins.
+   */
+  createCoalescer(consumer) {
+    let pending;
+    let timer;
+    const flush = () => {
+      timer = void 0;
+      const value = pending;
+      pending = void 0;
+      if (value !== void 0) {
+        consumer(value);
+      }
+    };
+    return (payload) => {
+      pending = payload;
+      if (timer === void 0) {
+        timer = setTimeout(flush, this.coalesceMs);
+      }
+    };
+  }
+  /**
+   * Tear down the worker and port. Idempotent.
+   *
+   * Order matters: we abort BEFORE closing the port so any in-flight
+   * `mcpClient.fetch` that observes the signal short-circuits and the
+   * subsequent attempt to post a reply lands in the disposed-guard branch
+   * (which silently drops the post) instead of throwing on a closed port.
+   */
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    try {
+      this.abortController.abort();
+    } catch {
+    }
+    try {
+      this.hostPort.close();
+    } catch {
+    }
+    try {
+      this.worker.terminate();
+    } catch {
+    }
+  }
+  /**
+   * Best-effort wrapper around `hostPort.postMessage` that tolerates posts
+   * arriving after {@link dispose}. The browser throws on a closed port and
+   * the async handlers below can race dispose, so any post initiated by an
+   * awaited continuation must be guarded.
+   */
+  safePostMessage(message) {
+    if (this.disposed) {
+      return;
+    }
+    try {
+      this.hostPort.postMessage(message);
+    } catch {
+    }
+  }
+  // ─── Port message handling ──────────────────────────────────────────────
+  handlePortMessage(message) {
+    if (this.disposed) {
+      return;
+    }
+    switch (message.type) {
+      case "ethisys:mcp:invokeTool":
+        this.dispatchMcp(message, "ethisys:mcp:invokeTool:result", (m) => this.handleInvokeTool(m));
+        return;
+      case "ethisys:mcp:getResource":
+        this.dispatchMcp(message, "ethisys:mcp:getResource:result", (m) => this.handleGetResource(m));
+        return;
+      case "ethisys:remotedom":
+        this.remoteDomConsumer?.(message.payload);
+        return;
+      default:
+        return;
+    }
+  }
+  /**
+   * Gate inbound MCP requests through the bounded concurrency window,
+   * reject with a deterministic error reply when the cap is exceeded, and
+   * decrement the counter unconditionally when the underlying handler
+   * settles (regardless of resolution/rejection shape).
+   */
+  dispatchMcp(message, resultType, handler) {
+    if (this.inFlightMcpRequests >= this.maxConcurrentMcpRequests) {
+      this.safePostMessage({
+        id: message.id,
+        type: resultType,
+        ok: false,
+        error: `MCP back-pressure: in-flight cap of ${this.maxConcurrentMcpRequests} reached.`
+      });
+      return;
+    }
+    this.inFlightMcpRequests++;
+    handler(message).finally(() => {
+      this.inFlightMcpRequests = Math.max(0, this.inFlightMcpRequests - 1);
+    });
+  }
+  async handleInvokeTool(message) {
+    let token;
+    try {
+      token = await this.capabilityTokenProvider();
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:invokeTool:result", err);
+      return;
+    }
+    if (this.disposed) {
+      return;
+    }
+    try {
+      const result = await this.mcpClient.fetch({
+        kind: "invokeTool",
+        name: message.name,
+        args: message.args,
+        capabilityToken: token,
+        signal: this.abortController.signal
+      });
+      this.safePostMessage({
+        id: message.id,
+        type: "ethisys:mcp:invokeTool:result",
+        ok: result.ok,
+        data: result.data,
+        error: result.error
+      });
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:invokeTool:result", err);
+    }
+  }
+  async handleGetResource(message) {
+    let token;
+    try {
+      token = await this.capabilityTokenProvider();
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:getResource:result", err);
+      return;
+    }
+    if (this.disposed) {
+      return;
+    }
+    try {
+      const result = await this.mcpClient.fetch({
+        kind: "getResource",
+        uri: message.uri,
+        capabilityToken: token,
+        signal: this.abortController.signal
+      });
+      this.safePostMessage({
+        id: message.id,
+        type: "ethisys:mcp:getResource:result",
+        ok: result.ok,
+        data: result.data,
+        error: result.error
+      });
+    } catch (err) {
+      this.replyError(message.id, "ethisys:mcp:getResource:result", err);
+    }
+  }
+  replyError(id, type, err) {
+    const message = err instanceof Error ? err.message : "MCP request failed";
+    this.safePostMessage({ id, type, ok: false, error: message });
+  }
+};
+
+Object.defineProperty(exports, "RemoteReceiver", {
+  enumerable: true,
+  get: function () { return receivers.RemoteReceiver; }
+});
+Object.defineProperty(exports, "RemoteRootRenderer", {
+  enumerable: true,
+  get: function () { return host.RemoteRootRenderer; }
+});
+Object.defineProperty(exports, "createRemoteComponentRenderer", {
+  enumerable: true,
+  get: function () { return host.createRemoteComponentRenderer; }
+});
+exports.CONTRACT_B_PRIMITIVES = CONTRACT_B_PRIMITIVES;
+exports.DEFAULT_MAX_CONCURRENT_MCP_REQUESTS = DEFAULT_MAX_CONCURRENT_MCP_REQUESTS;
+exports.DEFAULT_OFFSCREEN_COALESCE_MS = DEFAULT_OFFSCREEN_COALESCE_MS;
+exports.SemanticComponentRegistry = SemanticComponentRegistry;
+exports.WORKER_TRANSPORT_PROTOCOL = WORKER_TRANSPORT_PROTOCOL;
+exports.WorkerRemoteDomTransport = WorkerRemoteDomTransport;
+exports.createInputEventCoalescer = createInputEventCoalescer;
+exports.createOffscreenCanvasTransfer = createOffscreenCanvasTransfer;
+exports.evaluate = evaluate;
+exports.interpret = interpret;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map