@immediately-run/sdk 0.2.7 → 0.3.0

package/dist/hostRuntime.js

@@ -0,0 +1,11 @@
+function getHostRuntime() {
+  try {
+    return globalThis.__immediatelyRun__ ?? null;
+  } catch {
+    return null;
+  }
+}
+export {
+  getHostRuntime
+};
+//# sourceMappingURL=hostRuntime.js.map

package/dist/hostRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hostRuntime.ts"],"sourcesContent":["// Runtime-discovery global (SDK_PACKAGING_SPEC §4) — a LEAF module that imports\n// nothing, so it can be read by both `sandboxUtils` (transport resolver) and\n// `runtime` (handshake) without forming an import cycle. `sandboxUtils → runtime`\n// + `runtime → sandboxUtils` was a cycle the sandbox bundler cannot evaluate\n// (infinite re-require → \"Maximum call stack size exceeded\"); routing the shared\n// `getHostRuntime` through this leaf breaks it.\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":"AAwBO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/index.d.cts

@@ -13,9 +13,10 @@ export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResul
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.cjs';
 export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.cjs';
 export { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.cjs';
-export { ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake } from './runtime.cjs';
+export { SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.cjs';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.cjs';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
+export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.cjs';
 import 'react';
 import './TinkerableContext.cjs';
 import './RoutingSpec.cjs';

package/dist/index.d.ts

@@ -13,9 +13,10 @@ export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResul
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.js';
 export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.js';
 export { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.js';
-export { ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake } from './runtime.js';
+export { SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.js';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.js';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
+export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.js';
 import 'react';
 import './TinkerableContext.js';
 import './RoutingSpec.js';

package/dist/pushChannel.cjs

@@ -0,0 +1,70 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pushChannel_exports = {};
+__export(pushChannel_exports, {
+  createPushChannel: () => createPushChannel
+});
+module.exports = __toCommonJS(pushChannel_exports);
+var import_react = require("react");
+var import_sandboxUtils = require("./sandboxUtils");
+function createPushChannel(opts, transport = { sendMessage: import_sandboxUtils.sendMessage, addListener: import_sandboxUtils.addListener }) {
+  let current = opts.initial;
+  const listeners = /* @__PURE__ */ new Set();
+  let started = false;
+  const start = () => {
+    if (started) return;
+    started = true;
+    transport.addListener(opts.pushType, (msg) => {
+      const next = opts.parse(msg);
+      if (next !== void 0) {
+        current = next;
+        listeners.forEach((l) => l(current));
+      }
+    });
+    if (opts.requestType) {
+      try {
+        transport.sendMessage(opts.requestType);
+      } catch {
+      }
+    }
+  };
+  const get = () => {
+    start();
+    return current;
+  };
+  const onChange = (listener) => {
+    start();
+    listeners.add(listener);
+    listener(current);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+  const use = () => {
+    const [value, setValue] = (0, import_react.useState)(get);
+    (0, import_react.useEffect)(() => onChange(setValue), []);
+    return value;
+  };
+  return { get, onChange, use };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPushChannel
+});
+//# sourceMappingURL=pushChannel.cjs.map

package/dist/pushChannel.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pushChannel.ts"],"sourcesContent":["// Generic host→sandbox state channel read over the TRANSPORT\n// (SDK_PACKAGING_SPEC §4, expose-transport). The host pushes a `pushType`\n// message whenever the value changes and answers a `requestType` poll with the\n// current value — gated per-frame by the read ACL (site-main channelBridge.ts /\n// channelRouter). Historically the SDK read these values off injected sandbox\n// service objects (`module.evaluation.module.bundler.auth` etc.); this caches\n// the latest value SDK-side instead, so the SDK is self-contained and the\n// bundler services can eventually be retired.\n//\n// Every state helper (formFactor, auth, editorContext, theme, catalog) is a thin\n// wrapper over one of these — the get / onChange / use trio is identical.\nimport { useEffect, useState } from 'react';\nimport { sendMessage as defaultSend, addListener as defaultAddListener } from './sandboxUtils';\n\nexport interface PushChannel<T> {\n  /** Pollable snapshot of the current value. */\n  get(): T;\n  /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */\n  onChange(listener: (value: T) => void): () => void;\n  /** React hook returning the current value, re-rendering on change. */\n  use(): T;\n}\n\n/** Injectable transport — defaults to the real one; overridden in tests. */\nexport interface ChannelTransport {\n  sendMessage: (type: string, data?: Record<string, unknown>) => void;\n  addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;\n}\n\nexport function createPushChannel<T>(\n  opts: {\n    /** Host→sandbox push message type (e.g. `form-factor`). */\n    pushType: string;\n    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */\n    requestType?: string;\n    /** Value assumed before the host answers — also the value when the app may not read the channel. */\n    initial: T;\n    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */\n    parse: (msg: Record<string, unknown>) => T | undefined;\n  },\n  transport: ChannelTransport = { sendMessage: defaultSend, addListener: defaultAddListener },\n): PushChannel<T> {\n  let current = opts.initial;\n  const listeners = new Set<(value: T) => void>();\n  let started = false;\n\n  // Lazily start on first read: register the push listener + send one poll, so a\n  // late-mounting app still gets the current value. A channel the app may not\n  // read is simply never answered → `initial` stands.\n  const start = () => {\n    if (started) return;\n    started = true;\n    transport.addListener(opts.pushType, (msg) => {\n      const next = opts.parse(msg);\n      if (next !== undefined) {\n        current = next;\n        listeners.forEach((l) => l(current));\n      }\n    });\n    if (opts.requestType) {\n      try {\n        transport.sendMessage(opts.requestType);\n      } catch {\n        /* transport not ready — a proactive push will still arrive */\n      }\n    }\n  };\n\n  const get = (): T => {\n    start();\n    return current;\n  };\n\n  const onChange = (listener: (value: T) => void): (() => void) => {\n    start();\n    listeners.add(listener);\n    listener(current);\n    return () => {\n      listeners.delete(listener);\n    };\n  };\n\n  const use = (): T => {\n    const [value, setValue] = useState<T>(get);\n    useEffect(() => onChange(setValue), []);\n    return value;\n  };\n\n  return { get, onChange, use };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,mBAAoC;AACpC,0BAA8E;AAiBvE,SAAS,kBACd,MAUA,YAA8B,EAAE,aAAa,oBAAAA,aAAa,aAAa,oBAAAC,YAAmB,GAC1E;AAChB,MAAI,UAAU,KAAK;AACnB,QAAM,YAAY,oBAAI,IAAwB;AAC9C,MAAI,UAAU;AAKd,QAAM,QAAQ,MAAM;AAClB,QAAI,QAAS;AACb,cAAU;AACV,cAAU,YAAY,KAAK,UAAU,CAAC,QAAQ;AAC5C,YAAM,OAAO,KAAK,MAAM,GAAG;AAC3B,UAAI,SAAS,QAAW;AACtB,kBAAU;AACV,kBAAU,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;AAAA,MACrC;AAAA,IACF,CAAC;AACD,QAAI,KAAK,aAAa;AACpB,UAAI;AACF,kBAAU,YAAY,KAAK,WAAW;AAAA,MACxC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM;AACN,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,CAAC,aAA+C;AAC/D,UAAM;AACN,cAAU,IAAI,QAAQ;AACtB,aAAS,OAAO;AAChB,WAAO,MAAM;AACX,gBAAU,OAAO,QAAQ;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM,CAAC,OAAO,QAAQ,QAAI,uBAAY,GAAG;AACzC,gCAAU,MAAM,SAAS,QAAQ,GAAG,CAAC,CAAC;AACtC,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,KAAK,UAAU,IAAI;AAC9B;","names":["defaultSend","defaultAddListener"]}

package/dist/pushChannel.d.cts

@@ -0,0 +1,25 @@
+interface PushChannel<T> {
+    /** Pollable snapshot of the current value. */
+    get(): T;
+    /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */
+    onChange(listener: (value: T) => void): () => void;
+    /** React hook returning the current value, re-rendering on change. */
+    use(): T;
+}
+/** Injectable transport — defaults to the real one; overridden in tests. */
+interface ChannelTransport {
+    sendMessage: (type: string, data?: Record<string, unknown>) => void;
+    addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;
+}
+declare function createPushChannel<T>(opts: {
+    /** Host→sandbox push message type (e.g. `form-factor`). */
+    pushType: string;
+    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */
+    requestType?: string;
+    /** Value assumed before the host answers — also the value when the app may not read the channel. */
+    initial: T;
+    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */
+    parse: (msg: Record<string, unknown>) => T | undefined;
+}, transport?: ChannelTransport): PushChannel<T>;
+
+export { type ChannelTransport, type PushChannel, createPushChannel };

package/dist/pushChannel.d.ts

@@ -0,0 +1,25 @@
+interface PushChannel<T> {
+    /** Pollable snapshot of the current value. */
+    get(): T;
+    /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */
+    onChange(listener: (value: T) => void): () => void;
+    /** React hook returning the current value, re-rendering on change. */
+    use(): T;
+}
+/** Injectable transport — defaults to the real one; overridden in tests. */
+interface ChannelTransport {
+    sendMessage: (type: string, data?: Record<string, unknown>) => void;
+    addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;
+}
+declare function createPushChannel<T>(opts: {
+    /** Host→sandbox push message type (e.g. `form-factor`). */
+    pushType: string;
+    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */
+    requestType?: string;
+    /** Value assumed before the host answers — also the value when the app may not read the channel. */
+    initial: T;
+    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */
+    parse: (msg: Record<string, unknown>) => T | undefined;
+}, transport?: ChannelTransport): PushChannel<T>;
+
+export { type ChannelTransport, type PushChannel, createPushChannel };

package/dist/pushChannel.js

@@ -0,0 +1,46 @@
+import { useEffect, useState } from "react";
+import { sendMessage as defaultSend, addListener as defaultAddListener } from "./sandboxUtils";
+function createPushChannel(opts, transport = { sendMessage: defaultSend, addListener: defaultAddListener }) {
+  let current = opts.initial;
+  const listeners = /* @__PURE__ */ new Set();
+  let started = false;
+  const start = () => {
+    if (started) return;
+    started = true;
+    transport.addListener(opts.pushType, (msg) => {
+      const next = opts.parse(msg);
+      if (next !== void 0) {
+        current = next;
+        listeners.forEach((l) => l(current));
+      }
+    });
+    if (opts.requestType) {
+      try {
+        transport.sendMessage(opts.requestType);
+      } catch {
+      }
+    }
+  };
+  const get = () => {
+    start();
+    return current;
+  };
+  const onChange = (listener) => {
+    start();
+    listeners.add(listener);
+    listener(current);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+  const use = () => {
+    const [value, setValue] = useState(get);
+    useEffect(() => onChange(setValue), []);
+    return value;
+  };
+  return { get, onChange, use };
+}
+export {
+  createPushChannel
+};
+//# sourceMappingURL=pushChannel.js.map

package/dist/pushChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pushChannel.ts"],"sourcesContent":["// Generic host→sandbox state channel read over the TRANSPORT\n// (SDK_PACKAGING_SPEC §4, expose-transport). The host pushes a `pushType`\n// message whenever the value changes and answers a `requestType` poll with the\n// current value — gated per-frame by the read ACL (site-main channelBridge.ts /\n// channelRouter). Historically the SDK read these values off injected sandbox\n// service objects (`module.evaluation.module.bundler.auth` etc.); this caches\n// the latest value SDK-side instead, so the SDK is self-contained and the\n// bundler services can eventually be retired.\n//\n// Every state helper (formFactor, auth, editorContext, theme, catalog) is a thin\n// wrapper over one of these — the get / onChange / use trio is identical.\nimport { useEffect, useState } from 'react';\nimport { sendMessage as defaultSend, addListener as defaultAddListener } from './sandboxUtils';\n\nexport interface PushChannel<T> {\n  /** Pollable snapshot of the current value. */\n  get(): T;\n  /** Subscribe; invoked immediately with the current value, then on every change. Returns unsubscribe. */\n  onChange(listener: (value: T) => void): () => void;\n  /** React hook returning the current value, re-rendering on change. */\n  use(): T;\n}\n\n/** Injectable transport — defaults to the real one; overridden in tests. */\nexport interface ChannelTransport {\n  sendMessage: (type: string, data?: Record<string, unknown>) => void;\n  addListener: (type: string, handler: (msg: Record<string, unknown>) => void) => () => void;\n}\n\nexport function createPushChannel<T>(\n  opts: {\n    /** Host→sandbox push message type (e.g. `form-factor`). */\n    pushType: string;\n    /** Poll message type the SDK sends to pull the current value (e.g. `request-form-factor`). */\n    requestType?: string;\n    /** Value assumed before the host answers — also the value when the app may not read the channel. */\n    initial: T;\n    /** Extract + validate the value from a push message; return `undefined` to ignore the message. */\n    parse: (msg: Record<string, unknown>) => T | undefined;\n  },\n  transport: ChannelTransport = { sendMessage: defaultSend, addListener: defaultAddListener },\n): PushChannel<T> {\n  let current = opts.initial;\n  const listeners = new Set<(value: T) => void>();\n  let started = false;\n\n  // Lazily start on first read: register the push listener + send one poll, so a\n  // late-mounting app still gets the current value. A channel the app may not\n  // read is simply never answered → `initial` stands.\n  const start = () => {\n    if (started) return;\n    started = true;\n    transport.addListener(opts.pushType, (msg) => {\n      const next = opts.parse(msg);\n      if (next !== undefined) {\n        current = next;\n        listeners.forEach((l) => l(current));\n      }\n    });\n    if (opts.requestType) {\n      try {\n        transport.sendMessage(opts.requestType);\n      } catch {\n        /* transport not ready — a proactive push will still arrive */\n      }\n    }\n  };\n\n  const get = (): T => {\n    start();\n    return current;\n  };\n\n  const onChange = (listener: (value: T) => void): (() => void) => {\n    start();\n    listeners.add(listener);\n    listener(current);\n    return () => {\n      listeners.delete(listener);\n    };\n  };\n\n  const use = (): T => {\n    const [value, setValue] = useState<T>(get);\n    useEffect(() => onChange(setValue), []);\n    return value;\n  };\n\n  return { get, onChange, use };\n}\n"],"mappings":"AAWA,SAAS,WAAW,gBAAgB;AACpC,SAAS,eAAe,aAAa,eAAe,0BAA0B;AAiBvE,SAAS,kBACd,MAUA,YAA8B,EAAE,aAAa,aAAa,aAAa,mBAAmB,GAC1E;AAChB,MAAI,UAAU,KAAK;AACnB,QAAM,YAAY,oBAAI,IAAwB;AAC9C,MAAI,UAAU;AAKd,QAAM,QAAQ,MAAM;AAClB,QAAI,QAAS;AACb,cAAU;AACV,cAAU,YAAY,KAAK,UAAU,CAAC,QAAQ;AAC5C,YAAM,OAAO,KAAK,MAAM,GAAG;AAC3B,UAAI,SAAS,QAAW;AACtB,kBAAU;AACV,kBAAU,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;AAAA,MACrC;AAAA,IACF,CAAC;AACD,QAAI,KAAK,aAAa;AACpB,UAAI;AACF,kBAAU,YAAY,KAAK,WAAW;AAAA,MACxC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM;AACN,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,CAAC,aAA+C;AAC/D,UAAM;AACN,cAAU,IAAI,QAAQ;AACtB,aAAS,OAAO;AAChB,WAAO,MAAM;AACX,gBAAU,OAAO,QAAQ;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,MAAM,MAAS;AACnB,UAAM,CAAC,OAAO,QAAQ,IAAI,SAAY,GAAG;AACzC,cAAU,MAAM,SAAS,QAAQ,GAAG,CAAC,CAAC;AACtC,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,KAAK,UAAU,IAAI;AAC9B;","names":[]}

package/dist/runtime.cjs

@@ -21,20 +21,14 @@ __export(runtime_exports, {
   SDK_PROTOCOL_VERSION: () => SDK_PROTOCOL_VERSION,
   SDK_VERSION: () => SDK_VERSION,
   announceHandshake: () => announceHandshake,
-  getHostRuntime: () => getHostRuntime,
+  getHostRuntime: () => import_hostRuntime.getHostRuntime,
   sdkHandshake: () => sdkHandshake
 });
 module.exports = __toCommonJS(runtime_exports);
 var import_sandboxUtils = require("./sandboxUtils");
+var import_hostRuntime = require("./hostRuntime");
 const SDK_PROTOCOL_VERSION = "1.0.0";
-const SDK_VERSION = "0.2.7";
-function getHostRuntime() {
-  try {
-    return globalThis.__immediatelyRun__ ?? null;
-  } catch {
-    return null;
-  }
-}
+const SDK_VERSION = "0.3.0";
 const sdkHandshake = () => ({
   sdkVersion: SDK_VERSION,
   protocolVersion: SDK_PROTOCOL_VERSION

package/dist/runtime.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version. Kept in step with package.json (a build step can\n *  inject it later; a constant is fine while versions are still effectively fixed). */\nexport const SDK_VERSION = '0.2.7';\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,0BAAyC;AAIlC,MAAM,uBAAuB;AAI7B,MAAM,cAAc;AAmBpB,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQO,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,2CAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,aAAO,iCAAY,qBAAqB,IAAI;AAC9C;","names":[]}
+{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\n\n// `getHostRuntime` + `ImmediatelyRunGlobal` live in the leaf `hostRuntime` module\n// (imports nothing) and are re-exported here for a stable public API. This breaks\n// the sandboxUtils↔runtime import cycle: sandboxUtils reads `getHostRuntime` from\n// the leaf, while runtime still imports sandboxUtils for the handshake — one\n// direction only, no cycle.\nexport { getHostRuntime } from './hostRuntime';\nexport type { ImmediatelyRunGlobal } from './hostRuntime';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version. Kept in step with package.json (a build step can\n *  inject it later; a constant is fine while versions are still effectively fixed). */\nexport const SDK_VERSION = '0.3.0';\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,0BAAyC;AAOzC,yBAA+B;AAKxB,MAAM,uBAAuB;AAI7B,MAAM,cAAc;AAQpB,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,2CAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,aAAO,iCAAY,qBAAqB,IAAI;AAC9C;","names":[]}

package/dist/runtime.d.cts

@@ -1,26 +1,11 @@
+export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.cjs';
+
 /** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.
  *  Additive-only (§9); bump only for a backwards-compatible extension. */
 declare const SDK_PROTOCOL_VERSION = "1.0.0";
 /** This SDK's package version. Kept in step with package.json (a build step can
  *  inject it later; a constant is fine while versions are still effectively fixed). */
-declare const SDK_VERSION = "0.2.7";
-/** The sandbox runtime's pre-evaluation discovery global (§4). */
-interface ImmediatelyRunGlobal {
-    /** Sandbox-runtime protocol version (semver). */
-    runtimeVersion?: string;
-    /** postMessage envelope/protocol version. */
-    protocolVersion?: string;
-    /** The host channel the SDK talks over (MessagePort | message bus). */
-    transport?: unknown;
-    /** Resolves when ports arrive, if they arrive async after register-frame. */
-    ready?: Promise<void>;
-}
-/**
- * Read the sandbox runtime's discovery global (§4), or null when absent — in which
- * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK
- * detect a host too old/new and fail closed (§6) once the global ships.
- */
-declare function getHostRuntime(): ImmediatelyRunGlobal | null;
+declare const SDK_VERSION = "0.3.0";
 /** This SDK's handshake payload — the version + protocol the host records + checks
  *  against `HOST_PROTOCOL_VERSION` (§6/T45). */
 interface SdkHandshake {
@@ -36,4 +21,4 @@ declare const sdkHandshake: () => SdkHandshake;
  */
 declare function announceHandshake(): () => void;
 
-export { type ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, type SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake };
+export { SDK_PROTOCOL_VERSION, SDK_VERSION, type SdkHandshake, announceHandshake, sdkHandshake };

package/dist/runtime.d.ts

@@ -1,26 +1,11 @@
+export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.js';
+
 /** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.
  *  Additive-only (§9); bump only for a backwards-compatible extension. */
 declare const SDK_PROTOCOL_VERSION = "1.0.0";
 /** This SDK's package version. Kept in step with package.json (a build step can
  *  inject it later; a constant is fine while versions are still effectively fixed). */
-declare const SDK_VERSION = "0.2.7";
-/** The sandbox runtime's pre-evaluation discovery global (§4). */
-interface ImmediatelyRunGlobal {
-    /** Sandbox-runtime protocol version (semver). */
-    runtimeVersion?: string;
-    /** postMessage envelope/protocol version. */
-    protocolVersion?: string;
-    /** The host channel the SDK talks over (MessagePort | message bus). */
-    transport?: unknown;
-    /** Resolves when ports arrive, if they arrive async after register-frame. */
-    ready?: Promise<void>;
-}
-/**
- * Read the sandbox runtime's discovery global (§4), or null when absent — in which
- * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK
- * detect a host too old/new and fail closed (§6) once the global ships.
- */
-declare function getHostRuntime(): ImmediatelyRunGlobal | null;
+declare const SDK_VERSION = "0.3.0";
 /** This SDK's handshake payload — the version + protocol the host records + checks
  *  against `HOST_PROTOCOL_VERSION` (§6/T45). */
 interface SdkHandshake {
@@ -36,4 +21,4 @@ declare const sdkHandshake: () => SdkHandshake;
  */
 declare function announceHandshake(): () => void;
 
-export { type ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, type SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake };
+export { SDK_PROTOCOL_VERSION, SDK_VERSION, type SdkHandshake, announceHandshake, sdkHandshake };

package/dist/runtime.js

@@ -1,13 +1,7 @@
 import { sendMessage, addListener } from "./sandboxUtils";
+import { getHostRuntime } from "./hostRuntime";
 const SDK_PROTOCOL_VERSION = "1.0.0";
-const SDK_VERSION = "0.2.7";
-function getHostRuntime() {
-  try {
-    return globalThis.__immediatelyRun__ ?? null;
-  } catch {
-    return null;
-  }
-}
+const SDK_VERSION = "0.3.0";
 const sdkHandshake = () => ({
   sdkVersion: SDK_VERSION,
   protocolVersion: SDK_PROTOCOL_VERSION

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version. Kept in step with package.json (a build step can\n *  inject it later; a constant is fine while versions are still effectively fixed). */\nexport const SDK_VERSION = '0.2.7';\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":"AAcA,SAAS,aAAa,mBAAmB;AAIlC,MAAM,uBAAuB;AAI7B,MAAM,cAAc;AAmBpB,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQO,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,kBAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,SAAO,YAAY,qBAAqB,IAAI;AAC9C;","names":[]}
+{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\n\n// `getHostRuntime` + `ImmediatelyRunGlobal` live in the leaf `hostRuntime` module\n// (imports nothing) and are re-exported here for a stable public API. This breaks\n// the sandboxUtils↔runtime import cycle: sandboxUtils reads `getHostRuntime` from\n// the leaf, while runtime still imports sandboxUtils for the handshake — one\n// direction only, no cycle.\nexport { getHostRuntime } from './hostRuntime';\nexport type { ImmediatelyRunGlobal } from './hostRuntime';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version. Kept in step with package.json (a build step can\n *  inject it later; a constant is fine while versions are still effectively fixed). */\nexport const SDK_VERSION = '0.3.0';\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":"AAcA,SAAS,aAAa,mBAAmB;AAOzC,SAAS,sBAAsB;AAKxB,MAAM,uBAAuB;AAI7B,MAAM,cAAc;AAQpB,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,kBAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,SAAO,YAAY,qBAAqB,IAAI;AAC9C;","names":[]}

package/dist/sandboxUtils.cjs

@@ -23,14 +23,14 @@ __export(sandboxUtils_exports, {
   sendMessage: () => sendMessage
 });
 module.exports = __toCommonJS(sandboxUtils_exports);
-var import_runtime = require("./runtime");
+var import_hostRuntime = require("./hostRuntime");
 function transport() {
   try {
     const injected = module?.evaluation?.module?.bundler?.messageBus;
     if (injected && typeof injected.sendMessage === "function") return injected;
   } catch {
   }
-  const t = (0, import_runtime.getHostRuntime)()?.transport;
+  const t = (0, import_hostRuntime.getHostRuntime)()?.transport;
   if (t && typeof t.sendMessage === "function") return t;
   throw new Error("immediately.run: no host transport (neither injected nor __immediatelyRun__)");
 }

package/dist/sandboxUtils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Host transport access (SDK_PACKAGING_SPEC §4, expose-transport). All host comms\n// (sendMessage / protocolRequest / onMessage) go through ONE resolver so the SDK is\n// transport-agnostic: it works whether it was INJECTED into the bundler's evaluation\n// context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands\n// it the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is\n// byte-for-byte preserved; the global is the fallback the npm-fetched SDK uses. When\n// injection is removed (phase 3), only the global path remains — `bundler.*` stops\n// being API, which is the whole point.\nimport { getHostRuntime } from './runtime';\n\ninterface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nfunction transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n): Promise<any> => transport().protocolRequest(protocolName, method, params);\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,qBAA+B;AAQ/B,SAAS,YAA2B;AAElC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,QAAI,+BAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,kBAAkB,CAC7B,cACA,QACA,WACiB,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAEpE,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}
+{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Host transport access (SDK_PACKAGING_SPEC §4, expose-transport). All host comms\n// (sendMessage / protocolRequest / onMessage) go through ONE resolver so the SDK is\n// transport-agnostic: it works whether it was INJECTED into the bundler's evaluation\n// context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands\n// it the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is\n// byte-for-byte preserved; the global is the fallback the npm-fetched SDK uses. When\n// injection is removed (phase 3), only the global path remains — `bundler.*` stops\n// being API, which is the whole point.\nimport { getHostRuntime } from './hostRuntime';\n\ninterface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nfunction transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n): Promise<any> => transport().protocolRequest(protocolName, method, params);\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,yBAA+B;AAQ/B,SAAS,YAA2B;AAElC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,QAAI,mCAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,kBAAkB,CAC7B,cACA,QACA,WACiB,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAEpE,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}

package/dist/sandboxUtils.js

@@ -1,4 +1,4 @@
-import { getHostRuntime } from "./runtime";
+import { getHostRuntime } from "./hostRuntime";
 function transport() {
   try {
     const injected = module?.evaluation?.module?.bundler?.messageBus;

package/dist/sandboxUtils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Host transport access (SDK_PACKAGING_SPEC §4, expose-transport). All host comms\n// (sendMessage / protocolRequest / onMessage) go through ONE resolver so the SDK is\n// transport-agnostic: it works whether it was INJECTED into the bundler's evaluation\n// context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands\n// it the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is\n// byte-for-byte preserved; the global is the fallback the npm-fetched SDK uses. When\n// injection is removed (phase 3), only the global path remains — `bundler.*` stops\n// being API, which is the whole point.\nimport { getHostRuntime } from './runtime';\n\ninterface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nfunction transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n): Promise<any> => transport().protocolRequest(protocolName, method, params);\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":"AAWA,SAAS,sBAAsB;AAQ/B,SAAS,YAA2B;AAElC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,IAAI,eAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,kBAAkB,CAC7B,cACA,QACA,WACiB,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAEpE,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}
+{"version":3,"sources":["../src/sandboxUtils.ts"],"sourcesContent":["// Host transport access (SDK_PACKAGING_SPEC §4, expose-transport). All host comms\n// (sendMessage / protocolRequest / onMessage) go through ONE resolver so the SDK is\n// transport-agnostic: it works whether it was INJECTED into the bundler's evaluation\n// context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands\n// it the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is\n// byte-for-byte preserved; the global is the fallback the npm-fetched SDK uses. When\n// injection is removed (phase 3), only the global path remains — `bundler.*` stops\n// being API, which is the whole point.\nimport { getHostRuntime } from './hostRuntime';\n\ninterface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nfunction transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const protocolRequest = (\n  protocolName: string,\n  method: string,\n  params: Array<any>,\n): Promise<any> => transport().protocolRequest(protocolName, method, params);\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":"AAWA,SAAS,sBAAsB;AAQ/B,SAAS,YAA2B;AAElC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,IAAI,eAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,kBAAkB,CAC7B,cACA,QACA,WACiB,UAAU,EAAE,gBAAgB,cAAc,QAAQ,MAAM;AAEpE,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}

package/dist/theme.cjs

@@ -24,21 +24,17 @@ __export(theme_exports, {
   useHostTheme: () => useHostTheme
 });
 module.exports = __toCommonJS(theme_exports);
-var import_react = require("react");
+var import_pushChannel = require("./pushChannel");
 var import_sandboxUtils = require("./sandboxUtils");
-const themeService = () => {
-  return module.evaluation.module.bundler.theme;
-};
-const getHostTheme = () => themeService().getTheme();
-const onHostThemeChange = (listener) => {
-  const disposable = themeService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useHostTheme = () => {
-  const [theme, setTheme] = (0, import_react.useState)(getHostTheme);
-  (0, import_react.useEffect)(() => onHostThemeChange(setTheme), []);
-  return theme;
-};
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "theme",
+  requestType: "request-theme",
+  initial: "dark",
+  parse: (msg) => msg.theme === "light" || msg.theme === "dark" ? msg.theme : void 0
+});
+const getHostTheme = () => channel.get();
+const onHostThemeChange = (listener) => channel.onChange(listener);
+const useHostTheme = () => channel.use();
 const setHostTheme = async (theme) => {
   const res = await (0, import_sandboxUtils.protocolRequest)("theme", "set", [{ theme }]);
   if (!res || res.ok !== true) {

package/dist/theme.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * The host UI theme, mirrored from the immediately.run host window into the\n * sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n */\nexport type HostTheme = 'light' | 'dark';\n\ninterface ThemeService {\n  getTheme(): HostTheme;\n  onChange(listener: (theme: HostTheme) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.theme` is the sandbox bundler injected into\n// the evaluation context (same path the other SDK helpers use for `auth`).\nconst themeService = (): ThemeService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.theme;\n};\n\n/**\n * Returns the current host theme. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => themeService().getTheme();\n\n/**\n * Subscribe to host theme changes. The listener is invoked immediately with the\n * current theme, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (\n  listener: (theme: HostTheme) => void,\n): (() => void) => {\n  const disposable = themeService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * React hook returning the current host theme, re-rendering when it changes.\n * The recommended way to implement an app's own `useTheme`: follow the host,\n * allow a local override.\n */\nexport const useHostTheme = (): HostTheme => {\n  const [theme, setTheme] = useState<HostTheme>(getHostTheme);\n  useEffect(() => onHostThemeChange(setTheme), []);\n  return theme;\n};\n\n/**\n * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host\n * applies it and re-pushes the new value to every `theme:read` iframe, so your\n * own {@link useHostTheme} confirms the change (the loop closes with no special\n * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may\n * call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims. Update\n * optimistically and let the re-push confirm.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  const res = (await protocolRequest('theme', 'set', [{ theme }])) as\n    | { ok: true; data?: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AACpC,0BAAgC;AAoBhC,MAAM,eAAe,MAAoB;AAEvC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,eAAe,MAAiB,aAAa,EAAE,SAAS;AAM9D,MAAM,oBAAoB,CAC/B,aACiB;AACjB,QAAM,aAAa,aAAa,EAAE,SAAS,QAAQ;AACnD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,eAAe,MAAiB;AAC3C,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAAoB,YAAY;AAC1D,8BAAU,MAAM,kBAAkB,QAAQ,GAAG,CAAC,CAAC;AAC/C,SAAO;AACT;AAWO,MAAM,eAAe,OAAO,UAAoC;AACrE,QAAM,MAAO,UAAM,qCAAgB,SAAS,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AAI9D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,qBAAqB;AAG3D,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACF;","names":[]}
+{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * The host UI theme, mirrored from the immediately.run host window into the\n * sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n */\nexport type HostTheme = 'light' | 'dark';\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `theme` and\n// answers `request-theme` (wire format: site-main channelBridge.ts). The host's\n// default before it reports is `dark` (sandbox themeState.DEFAULT_THEME).\nconst channel = createPushChannel<HostTheme>({\n  pushType: 'theme',\n  requestType: 'request-theme',\n  initial: 'dark',\n  parse: (msg) => (msg.theme === 'light' || msg.theme === 'dark' ? msg.theme : undefined),\n});\n\n/**\n * Returns the current host theme. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => channel.get();\n\n/**\n * Subscribe to host theme changes. The listener is invoked immediately with the\n * current theme, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (listener: (theme: HostTheme) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current host theme, re-rendering when it changes.\n * The recommended way to implement an app's own `useTheme`: follow the host,\n * allow a local override.\n */\nexport const useHostTheme = (): HostTheme => channel.use();\n\n/**\n * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host\n * applies it and re-pushes the new value to every `theme:read` iframe, so your\n * own {@link useHostTheme} confirms the change (the loop closes with no special\n * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may\n * call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims. Update\n * optimistically and let the re-push confirm.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  const res = (await protocolRequest('theme', 'set', [{ theme }])) as\n    | { ok: true; data?: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAClC,0BAAgC;AAgBhC,MAAM,cAAU,sCAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,IAAI,UAAU,WAAW,IAAI,UAAU,SAAS,IAAI,QAAQ;AAC/E,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,oBAAoB,CAAC,aAChC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAWlD,MAAM,eAAe,OAAO,UAAoC;AACrE,QAAM,MAAO,UAAM,qCAAgB,SAAS,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AAI9D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,qBAAqB;AAG3D,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACF;","names":[]}

package/dist/theme.js

@@ -1,18 +1,14 @@
-import { useEffect, useState } from "react";
+import { createPushChannel } from "./pushChannel";
 import { protocolRequest } from "./sandboxUtils";
-const themeService = () => {
-  return module.evaluation.module.bundler.theme;
-};
-const getHostTheme = () => themeService().getTheme();
-const onHostThemeChange = (listener) => {
-  const disposable = themeService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useHostTheme = () => {
-  const [theme, setTheme] = useState(getHostTheme);
-  useEffect(() => onHostThemeChange(setTheme), []);
-  return theme;
-};
+const channel = createPushChannel({
+  pushType: "theme",
+  requestType: "request-theme",
+  initial: "dark",
+  parse: (msg) => msg.theme === "light" || msg.theme === "dark" ? msg.theme : void 0
+});
+const getHostTheme = () => channel.get();
+const onHostThemeChange = (listener) => channel.onChange(listener);
+const useHostTheme = () => channel.use();
 const setHostTheme = async (theme) => {
   const res = await protocolRequest("theme", "set", [{ theme }]);
   if (!res || res.ok !== true) {

package/dist/theme.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * The host UI theme, mirrored from the immediately.run host window into the\n * sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n */\nexport type HostTheme = 'light' | 'dark';\n\ninterface ThemeService {\n  getTheme(): HostTheme;\n  onChange(listener: (theme: HostTheme) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.theme` is the sandbox bundler injected into\n// the evaluation context (same path the other SDK helpers use for `auth`).\nconst themeService = (): ThemeService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.theme;\n};\n\n/**\n * Returns the current host theme. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => themeService().getTheme();\n\n/**\n * Subscribe to host theme changes. The listener is invoked immediately with the\n * current theme, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (\n  listener: (theme: HostTheme) => void,\n): (() => void) => {\n  const disposable = themeService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * React hook returning the current host theme, re-rendering when it changes.\n * The recommended way to implement an app's own `useTheme`: follow the host,\n * allow a local override.\n */\nexport const useHostTheme = (): HostTheme => {\n  const [theme, setTheme] = useState<HostTheme>(getHostTheme);\n  useEffect(() => onHostThemeChange(setTheme), []);\n  return theme;\n};\n\n/**\n * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host\n * applies it and re-pushes the new value to every `theme:read` iframe, so your\n * own {@link useHostTheme} confirms the change (the loop closes with no special\n * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may\n * call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims. Update\n * optimistically and let the re-push confirm.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  const res = (await protocolRequest('theme', 'set', [{ theme }])) as\n    | { ok: true; data?: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AACpC,SAAS,uBAAuB;AAoBhC,MAAM,eAAe,MAAoB;AAEvC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,eAAe,MAAiB,aAAa,EAAE,SAAS;AAM9D,MAAM,oBAAoB,CAC/B,aACiB;AACjB,QAAM,aAAa,aAAa,EAAE,SAAS,QAAQ;AACnD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,eAAe,MAAiB;AAC3C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAoB,YAAY;AAC1D,YAAU,MAAM,kBAAkB,QAAQ,GAAG,CAAC,CAAC;AAC/C,SAAO;AACT;AAWO,MAAM,eAAe,OAAO,UAAoC;AACrE,QAAM,MAAO,MAAM,gBAAgB,SAAS,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AAI9D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,qBAAqB;AAG3D,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACF;","names":[]}
+{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * The host UI theme, mirrored from the immediately.run host window into the\n * sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n */\nexport type HostTheme = 'light' | 'dark';\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `theme` and\n// answers `request-theme` (wire format: site-main channelBridge.ts). The host's\n// default before it reports is `dark` (sandbox themeState.DEFAULT_THEME).\nconst channel = createPushChannel<HostTheme>({\n  pushType: 'theme',\n  requestType: 'request-theme',\n  initial: 'dark',\n  parse: (msg) => (msg.theme === 'light' || msg.theme === 'dark' ? msg.theme : undefined),\n});\n\n/**\n * Returns the current host theme. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => channel.get();\n\n/**\n * Subscribe to host theme changes. The listener is invoked immediately with the\n * current theme, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (listener: (theme: HostTheme) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current host theme, re-rendering when it changes.\n * The recommended way to implement an app's own `useTheme`: follow the host,\n * allow a local override.\n */\nexport const useHostTheme = (): HostTheme => channel.use();\n\n/**\n * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host\n * applies it and re-pushes the new value to every `theme:read` iframe, so your\n * own {@link useHostTheme} confirms the change (the loop closes with no special\n * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may\n * call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims. Update\n * optimistically and let the re-push confirm.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  const res = (await protocolRequest('theme', 'set', [{ theme }])) as\n    | { ok: true; data?: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":"AAAA,SAAS,yBAAyB;AAClC,SAAS,uBAAuB;AAgBhC,MAAM,UAAU,kBAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,IAAI,UAAU,WAAW,IAAI,UAAU,SAAS,IAAI,QAAQ;AAC/E,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,oBAAoB,CAAC,aAChC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAWlD,MAAM,eAAe,OAAO,UAAoC;AACrE,QAAM,MAAO,MAAM,gBAAgB,SAAS,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AAI9D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,qBAAqB;AAG3D,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -27,8 +27,11 @@
   "scripts": {
     "build": "tsup",
     "test": "jest",
+    "check:circular": "node scripts/check-circular.mjs",
+    "api:check": "node scripts/check-api-stability.mjs",
+    "api:update": "node scripts/check-api-stability.mjs --update",
     "docs": "typedoc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run check:circular && npm run build && npm run api:check"
   },
   "peerDependencies": {
     "react": "^19.0.0",