@immediately-run/sdk 0.13.0 → 0.16.0

package/dist/routing.js

@@ -1,6 +1,8 @@
+import { jsx } from "react/jsx-runtime";
 import { use, useContext } from "react";
 import { sendMessage } from "./sandboxUtils";
 import { TinkerableContext } from "./TinkerableContext";
+import { matchRoute } from "./routeMatch";
 import { constructUrl, isAbsolutePath, parseTarget } from "./urlUtils";
 import { joinPaths } from "./pathUtils";
 const useTinkerableLink = (newSandboxLocation) => {
@@ -16,29 +18,42 @@ const useTinkerableLink = (newSandboxLocation) => {
 const applyRoutingRule = (routingSpec, navigationState) => {
   const { sandboxPath } = navigationState;
   for (const routingRule of routingSpec.routes) {
-    if (typeof routingRule.pattern === "string") {
-      if (routingRule.pattern === sandboxPath) {
-        return { routingRule };
-      }
-    } else {
-      const match = sandboxPath.match(routingRule.pattern);
-      if (routingRule.pattern.test(sandboxPath)) {
-        return {
-          routingRule,
-          pathParameters: match?.groups
-        };
-      }
+    const pathParameters = matchRoute(routingRule.pattern, sandboxPath);
+    if (pathParameters) {
+      return { routingRule, pathParameters };
     }
   }
   return void 0;
 };
+const renderRoute = (routingRule, params) => {
+  if (routingRule.component) {
+    const Component = routingRule.component;
+    return /* @__PURE__ */ jsx(Component, { params });
+  }
+  return routingRule.element ?? routingRule.reactNode ?? null;
+};
 const Router = () => {
   const context = useContext(TinkerableContext);
-  const { navigationState: { routingRule } } = context;
+  const { navigationState: { routingRule, pathParameters } } = context;
   if (!routingRule) {
     throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);
   }
-  return routingRule.reactNode;
+  return renderRoute(routingRule, pathParameters ?? {});
+};
+const useRouteParams = () => use(TinkerableContext).navigationState.pathParameters ?? {};
+const useRoute = () => {
+  const { navigationState } = use(TinkerableContext);
+  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;
+  return {
+    name: routingRule?.name,
+    params: pathParameters ?? {},
+    sandboxPath,
+    mode,
+    provider,
+    namespace,
+    repository,
+    ref
+  };
 };
 const navigate = (target) => {
   console.log(`[Sandbox] Navigating to ${target}`);
@@ -52,6 +67,9 @@ export {
   Router,
   applyRoutingRule,
   navigate,
+  renderRoute,
+  useRoute,
+  useRouteParams,
   useTinkerableLink
 };
 //# sourceMappingURL=routing.js.map

package/dist/routing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\n\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule,\n  pathParameters?: Record<string, string>;\n}\n\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation)\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation\n  }\n  return constructUrl(outerHref, newNavigationState);\n}\n\nexport const applyRoutingRule = (routingSpec:RoutingSpec, navigationState: NavigationState): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    if (typeof routingRule.pattern === 'string') {\n      if (routingRule.pattern === sandboxPath) {\n        return {routingRule};\n      }\n    } else {\n      const match = sandboxPath.match(routingRule.pattern);\n      if (routingRule.pattern.test(sandboxPath)) {\n        return {\n          routingRule,\n          pathParameters: match?.groups\n        }\n      }\n    }\n  }\n  return undefined;\n}\n\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {navigationState: {routingRule}} = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return routingRule.reactNode;\n};\n\n\n// Perform in-site navigation.\n// Top level frame is messaged to updated URL, after which a message will be\n// sent wit the new href, triggering the actual navigation.\nexport const navigate = (target: string) => {\n  console.log(`[Sandbox] Navigating to ${target}`)\n  sendMessage('urlchange', {\n    url: target,\n    back: false,\n    forward: false,\n  });\n};\n"],"mappings":"AAAA,SAAS,KAAK,kBAAkB;AAEhC,SAAS,mBAAmB;AAC5B,SAA0B,yBAAyB;AAEnD,SAAS,cAAc,gBAAgB,mBAAmB;AAC1D,SAAS,iBAAiB;AAOnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,IAAI,IAAI,iBAAiB;AACxE,MAAI,qBAAqB,YAAY,oBAAoB,UAAU;AACnE,MAAI,CAAC,eAAe,kBAAkB,GAAG;AACvC,uBAAmB,cAAc,UAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,SAAO,aAAa,WAAW,kBAAkB;AACnD;AAEO,MAAM,mBAAmB,CAAC,aAAyB,oBAAqE;AAC7H,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,QAAI,OAAO,YAAY,YAAY,UAAU;AAC3C,UAAI,YAAY,YAAY,aAAa;AACvC,eAAO,EAAC,YAAW;AAAA,MACrB;AAAA,IACF,OAAO;AACL,YAAM,QAAQ,YAAY,MAAM,YAAY,OAAO;AACnD,UAAI,YAAY,QAAQ,KAAK,WAAW,GAAG;AACzC,eAAO;AAAA,UACL;AAAA,UACA,gBAAgB,OAAO;AAAA,QACzB;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,SAAS,MAAM;AAC1B,QAAM,UAAU,WAAW,iBAAiB;AAC5C,QAAM,EAAC,iBAAiB,EAAC,YAAW,EAAC,IAAI;AACzC,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY;AACrB;AAMO,MAAM,WAAW,CAAC,WAAmB;AAC1C,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAC/C,cAAY,aAAa;AAAA,IACvB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RouteParams, RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { matchRoute } from './routeMatch';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\n\n/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule,\n  pathParameters?: Record<string, string>;\n}\n\n/** Build the full outer href for an in-app target (absolute `sandboxPath` or a\n *  path relative to the current route), e.g. for an `href` attribute. */\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation)\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation\n  }\n  return constructUrl(outerHref, newNavigationState);\n}\n\n/** Find the first rule in `routingSpec` whose pattern matches the current\n *  `sandboxPath`, returning it with the captured params (or `undefined`). */\nexport const applyRoutingRule = (routingSpec:RoutingSpec, navigationState: NavigationState): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    const pathParameters = matchRoute(routingRule.pattern, sandboxPath);\n    if (pathParameters) {\n      return { routingRule, pathParameters };\n    }\n  }\n  return undefined;\n}\n\n/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */\nexport const renderRoute = (routingRule: RoutingRule, params: RouteParams): ReactNode => {\n  if (routingRule.component) {\n    const Component = routingRule.component;\n    return <Component params={params} />;\n  }\n  return routingRule.element ?? routingRule.reactNode ?? null;\n};\n\n/** Render the route matched for the current location (set up by `boot`'s route table). */\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {navigationState: {routingRule, pathParameters}} = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return renderRoute(routingRule, pathParameters ?? {});\n};\n\n/** Read the current route's matched params (`:name` segments and the `*` wildcard). */\nexport const useRouteParams = <T extends RouteParams = RouteParams>(): T =>\n  (use(TinkerableContext).navigationState.pathParameters ?? {}) as T;\n\n/**\n * Read the current route: the matched rule's `name`, its `params`, the app-owned\n * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,\n * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.\n */\nexport const useRoute = () => {\n  const { navigationState } = use(TinkerableContext);\n  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;\n  return {\n    name: routingRule?.name,\n    params: (pathParameters ?? {}) as RouteParams,\n    sandboxPath,\n    mode,\n    provider,\n    namespace,\n    repository,\n    ref,\n  };\n};\n\n\n/**\n * Navigate within the app. Messages the host to update the URL; the host then\n * pushes the new href back, which drives the actual route change.\n */\nexport const navigate = (target: string) => {\n  console.log(`[Sandbox] Navigating to ${target}`)\n  sendMessage('urlchange', {\n    url: target,\n    back: false,\n    forward: false,\n  });\n};\n"],"mappings":"AA8CW;AA7CX,SAAS,KAAK,kBAAkB;AAEhC,SAAS,mBAAmB;AAC5B,SAA0B,yBAAyB;AAEnD,SAAS,kBAAkB;AAC3B,SAAS,cAAc,gBAAgB,mBAAmB;AAC1D,SAAS,iBAAiB;AAUnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,IAAI,IAAI,iBAAiB;AACxE,MAAI,qBAAqB,YAAY,oBAAoB,UAAU;AACnE,MAAI,CAAC,eAAe,kBAAkB,GAAG;AACvC,uBAAmB,cAAc,UAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,SAAO,aAAa,WAAW,kBAAkB;AACnD;AAIO,MAAM,mBAAmB,CAAC,aAAyB,oBAAqE;AAC7H,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,UAAM,iBAAiB,WAAW,YAAY,SAAS,WAAW;AAClE,QAAI,gBAAgB;AAClB,aAAO,EAAE,aAAa,eAAe;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAGO,MAAM,cAAc,CAAC,aAA0B,WAAmC;AACvF,MAAI,YAAY,WAAW;AACzB,UAAM,YAAY,YAAY;AAC9B,WAAO,oBAAC,aAAU,QAAgB;AAAA,EACpC;AACA,SAAO,YAAY,WAAW,YAAY,aAAa;AACzD;AAGO,MAAM,SAAS,MAAM;AAC1B,QAAM,UAAU,WAAW,iBAAiB;AAC5C,QAAM,EAAC,iBAAiB,EAAC,aAAa,eAAc,EAAC,IAAI;AACzD,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY,aAAa,kBAAkB,CAAC,CAAC;AACtD;AAGO,MAAM,iBAAiB,MAC3B,IAAI,iBAAiB,EAAE,gBAAgB,kBAAkB,CAAC;AAOtD,MAAM,WAAW,MAAM;AAC5B,QAAM,EAAE,gBAAgB,IAAI,IAAI,iBAAiB;AACjD,QAAM,EAAE,aAAa,gBAAgB,aAAa,MAAM,UAAU,WAAW,YAAY,IAAI,IAAI;AACjG,SAAO;AAAA,IACL,MAAM,aAAa;AAAA,IACnB,QAAS,kBAAkB,CAAC;AAAA,IAC5B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAOO,MAAM,WAAW,CAAC,WAAmB;AAC1C,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAC/C,cAAY,aAAa;AAAA,IACvB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}

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';\nimport { SDK_VERSION } from './version';\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, baked from package.json at build (SP2-6,\n *  `scripts/gen-version.mjs`). Re-exported so the public surface is unchanged\n *  (`@immediately-run/sdk` → `SDK_VERSION`); imported above for the handshake. */\nexport { SDK_VERSION };\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;AACzC,qBAA4B;AAO5B,yBAA+B;AAKxB,MAAM,uBAAuB;AAa7B,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';\nimport { SDK_VERSION } from './version';\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, baked from package.json at build (SP2-6,\n *  `scripts/gen-version.mjs`). Re-exported so the public surface is unchanged\n *  (`@immediately-run/sdk` → `SDK_VERSION`); imported above for the handshake. */\nexport { SDK_VERSION };\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}\n/** Build this SDK's handshake payload (version + protocol) for the host to record. */\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;AACzC,qBAA4B;AAO5B,yBAA+B;AAKxB,MAAM,uBAAuB;AAc7B,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

@@ -11,6 +11,7 @@ interface SdkHandshake {
     sdkVersion: string;
     protocolVersion: string;
 }
+/** Build this SDK's handshake payload (version + protocol) for the host to record. */
 declare const sdkHandshake: () => SdkHandshake;
 /**
  * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly

package/dist/runtime.d.ts

@@ -11,6 +11,7 @@ interface SdkHandshake {
     sdkVersion: string;
     protocolVersion: string;
 }
+/** Build this SDK's handshake payload (version + protocol) for the host to record. */
 declare const sdkHandshake: () => SdkHandshake;
 /**
  * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly

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';\nimport { SDK_VERSION } from './version';\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, baked from package.json at build (SP2-6,\n *  `scripts/gen-version.mjs`). Re-exported so the public surface is unchanged\n *  (`@immediately-run/sdk` → `SDK_VERSION`); imported above for the handshake. */\nexport { SDK_VERSION };\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;AACzC,SAAS,mBAAmB;AAO5B,SAAS,sBAAsB;AAKxB,MAAM,uBAAuB;AAa7B,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';\nimport { SDK_VERSION } from './version';\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, baked from package.json at build (SP2-6,\n *  `scripts/gen-version.mjs`). Re-exported so the public surface is unchanged\n *  (`@immediately-run/sdk` → `SDK_VERSION`); imported above for the handshake. */\nexport { SDK_VERSION };\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}\n/** Build this SDK's handshake payload (version + protocol) for the host to record. */\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;AACzC,SAAS,mBAAmB;AAO5B,SAAS,sBAAsB;AAKxB,MAAM,uBAAuB;AAc7B,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/sandboxTypes.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sandboxTypes.ts"],"sourcesContent":["export type ModuleExports = any\n\n// The real type is EvaluationContext from src/bundler/module/Evaluation.ts:6\nexport type EvaluationContext = {\n  exports: ModuleExports;\n  dynamicImport: (moduleToImport: string, symbolToImport:string) => Promise<ModuleExports>;\n  getModuleEvaluationContext: (moduleName: string) =>  Promise<EvaluationContext>;\n  resolve: (moduleName: string) => Promise<string>;\n  evaluation: {\n    module: {\n      source: string;\n      filepath: string;\n    }\n  }\n}\n\nexport type Metadata = Record<string, any>;\nexport type FilesMetadata = Record<string, Metadata>;\nexport type FileQueryResult = string[]\nexport type MetadataQueryFunction = (filesMetadata:FilesMetadata) => FileQueryResult;\nexport type MetadataQueryResult = {result: FileQueryResult} | {error: any}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/sandboxTypes.ts"],"sourcesContent":["/** The exports object of an evaluated sandbox module (untyped — shape depends on the module). */\nexport type ModuleExports = any\n\n/** The sandbox runtime's per-module evaluation context: a module's exports plus the\n *  helpers to dynamically import, resolve, and re-evaluate other modules.\n *  (The real type is `EvaluationContext` from `src/bundler/module/Evaluation.ts`.) */\nexport type EvaluationContext = {\n  exports: ModuleExports;\n  dynamicImport: (moduleToImport: string, symbolToImport:string) => Promise<ModuleExports>;\n  getModuleEvaluationContext: (moduleName: string) =>  Promise<EvaluationContext>;\n  resolve: (moduleName: string) => Promise<string>;\n  evaluation: {\n    module: {\n      source: string;\n      filepath: string;\n    }\n  }\n}\n\n/**\n * The parsed frontmatter of a single file. Apps can supply their own shape as the\n * `T` type parameter on the metadata hooks for typed field access; it defaults to\n * an open record.\n */\nexport type Metadata = Record<string, any>;\n\n/** The whole metadata store: a map from repo-relative file path to its frontmatter. */\nexport type FilesMetadata<T = Metadata> = Record<string, T>;\n\n/** The paths a {@link MetadataQueryFunction} selected. */\nexport type FileQueryResult = string[]\n\n/**\n * A query over the metadata store: receive every file's frontmatter keyed by path\n * and return the paths that match. Plain JS — `Object.entries(...).filter(...)` —\n * no query language to learn.\n */\nexport type MetadataQueryFunction<T = Metadata> = (filesMetadata: FilesMetadata<T>) => FileQueryResult;\n\n/** One match from {@link MetadataQueryFunction}: the file path paired with its frontmatter. */\nexport type MetadataQueryEntry<T = Metadata> = { path: string; meta: T };\n\n/**\n * The result of running a metadata query: the matched entries (path + frontmatter),\n * or the error a throwing query produced.\n */\nexport type MetadataQueryResult<T = Metadata> = MetadataQueryEntry<T>[] | { error: unknown }\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/sandboxTypes.d.cts

@@ -1,4 +1,8 @@
+/** The exports object of an evaluated sandbox module (untyped — shape depends on the module). */
 type ModuleExports = any;
+/** The sandbox runtime's per-module evaluation context: a module's exports plus the
+ *  helpers to dynamically import, resolve, and re-evaluate other modules.
+ *  (The real type is `EvaluationContext` from `src/bundler/module/Evaluation.ts`.) */
 type EvaluationContext = {
     exports: ModuleExports;
     dynamicImport: (moduleToImport: string, symbolToImport: string) => Promise<ModuleExports>;
@@ -11,14 +15,33 @@ type EvaluationContext = {
         };
     };
 };
+/**
+ * The parsed frontmatter of a single file. Apps can supply their own shape as the
+ * `T` type parameter on the metadata hooks for typed field access; it defaults to
+ * an open record.
+ */
 type Metadata = Record<string, any>;
-type FilesMetadata = Record<string, Metadata>;
+/** The whole metadata store: a map from repo-relative file path to its frontmatter. */
+type FilesMetadata<T = Metadata> = Record<string, T>;
+/** The paths a {@link MetadataQueryFunction} selected. */
 type FileQueryResult = string[];
-type MetadataQueryFunction = (filesMetadata: FilesMetadata) => FileQueryResult;
-type MetadataQueryResult = {
-    result: FileQueryResult;
-} | {
-    error: any;
+/**
+ * A query over the metadata store: receive every file's frontmatter keyed by path
+ * and return the paths that match. Plain JS — `Object.entries(...).filter(...)` —
+ * no query language to learn.
+ */
+type MetadataQueryFunction<T = Metadata> = (filesMetadata: FilesMetadata<T>) => FileQueryResult;
+/** One match from {@link MetadataQueryFunction}: the file path paired with its frontmatter. */
+type MetadataQueryEntry<T = Metadata> = {
+    path: string;
+    meta: T;
+};
+/**
+ * The result of running a metadata query: the matched entries (path + frontmatter),
+ * or the error a throwing query produced.
+ */
+type MetadataQueryResult<T = Metadata> = MetadataQueryEntry<T>[] | {
+    error: unknown;
 };
 
-export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports };
+export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryResult, ModuleExports };

package/dist/sandboxTypes.d.ts

@@ -1,4 +1,8 @@
+/** The exports object of an evaluated sandbox module (untyped — shape depends on the module). */
 type ModuleExports = any;
+/** The sandbox runtime's per-module evaluation context: a module's exports plus the
+ *  helpers to dynamically import, resolve, and re-evaluate other modules.
+ *  (The real type is `EvaluationContext` from `src/bundler/module/Evaluation.ts`.) */
 type EvaluationContext = {
     exports: ModuleExports;
     dynamicImport: (moduleToImport: string, symbolToImport: string) => Promise<ModuleExports>;
@@ -11,14 +15,33 @@ type EvaluationContext = {
         };
     };
 };
+/**
+ * The parsed frontmatter of a single file. Apps can supply their own shape as the
+ * `T` type parameter on the metadata hooks for typed field access; it defaults to
+ * an open record.
+ */
 type Metadata = Record<string, any>;
-type FilesMetadata = Record<string, Metadata>;
+/** The whole metadata store: a map from repo-relative file path to its frontmatter. */
+type FilesMetadata<T = Metadata> = Record<string, T>;
+/** The paths a {@link MetadataQueryFunction} selected. */
 type FileQueryResult = string[];
-type MetadataQueryFunction = (filesMetadata: FilesMetadata) => FileQueryResult;
-type MetadataQueryResult = {
-    result: FileQueryResult;
-} | {
-    error: any;
+/**
+ * A query over the metadata store: receive every file's frontmatter keyed by path
+ * and return the paths that match. Plain JS — `Object.entries(...).filter(...)` —
+ * no query language to learn.
+ */
+type MetadataQueryFunction<T = Metadata> = (filesMetadata: FilesMetadata<T>) => FileQueryResult;
+/** One match from {@link MetadataQueryFunction}: the file path paired with its frontmatter. */
+type MetadataQueryEntry<T = Metadata> = {
+    path: string;
+    meta: T;
+};
+/**
+ * The result of running a metadata query: the matched entries (path + frontmatter),
+ * or the error a throwing query produced.
+ */
+type MetadataQueryResult<T = Metadata> = MetadataQueryEntry<T>[] | {
+    error: unknown;
 };
 
-export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports };
+export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryResult, ModuleExports };

package/dist/version.cjs

@@ -21,7 +21,7 @@ __export(version_exports, {
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const SDK_VERSION = "0.13.0";
+const SDK_VERSION = "0.16.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SDK_VERSION

package/dist/version.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.13.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.16.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}

package/dist/version.d.cts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.13.0";
+declare const SDK_VERSION = "0.16.0";
 
 export { SDK_VERSION };

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.13.0";
+declare const SDK_VERSION = "0.16.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,4 +1,4 @@
-const SDK_VERSION = "0.13.0";
+const SDK_VERSION = "0.16.0";
 export {
   SDK_VERSION
 };

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.13.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.16.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -32,7 +32,7 @@
     "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",
+    "docs": "typedoc --json docs/api.json && node scripts/gen-llms.mjs",
     "prepublishOnly": "npm run check:circular && npm run build && npm run api:check"
   },
   "peerDependencies": {
@@ -43,10 +43,14 @@
     "react-error-boundary": "^6.0.0"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/jest": "^29.5.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdom": "^25.0.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "ts-jest": "^29.1.0",