@immediately-run/sdk 0.15.0 → 0.17.0

package/dist/routeMatch.d.ts

@@ -0,0 +1,19 @@
+import { RouteParams } from './RoutingSpec.js';
+import 'react';
+
+/**
+ * Compile a path template to an anchored RegExp with named groups:
+ *   `:name` → one non-slash segment   `*` → the rest (greedy)
+ * A template with neither token is a literal exact match. Raw RegExp patterns
+ * never reach here — they are the escape hatch, used as authored.
+ */
+declare const compileTemplate: (template: string) => RegExp;
+/** Resolve a pattern to a RegExp: templates are compiled (and cached), RegExp passes through. */
+declare const toRegExp: (pattern: string | RegExp) => RegExp;
+/**
+ * Match a `sandboxPath` against a route pattern. Returns the named params on a
+ * match (the `*` wildcard surfaces under the `'*'` key), or `null` otherwise.
+ */
+declare const matchRoute: (pattern: string | RegExp, path: string) => RouteParams | null;
+
+export { compileTemplate, matchRoute, toRegExp };

package/dist/routeMatch.js

@@ -0,0 +1,46 @@
+const escapeForRegexp = (str) => str.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&");
+const WILDCARD_GROUP = "wild";
+const compileTemplate = (template) => {
+  const token = /(:[A-Za-z_][A-Za-z0-9_]*)|\*/g;
+  let src = "";
+  let last = 0;
+  let m;
+  while ((m = token.exec(template)) !== null) {
+    src += escapeForRegexp(template.slice(last, m.index));
+    src += m[1] ? `(?<${m[1].slice(1)}>[^/]+)` : `(?<${WILDCARD_GROUP}>.*)`;
+    last = m.index + m[0].length;
+  }
+  src += escapeForRegexp(template.slice(last));
+  return new RegExp(`^${src}$`);
+};
+const templateCache = /* @__PURE__ */ new Map();
+const toRegExp = (pattern) => {
+  if (pattern instanceof RegExp) {
+    return pattern;
+  }
+  let compiled = templateCache.get(pattern);
+  if (!compiled) {
+    compiled = compileTemplate(pattern);
+    templateCache.set(pattern, compiled);
+  }
+  return compiled;
+};
+const matchRoute = (pattern, path) => {
+  const match = path.match(toRegExp(pattern));
+  if (!match) {
+    return null;
+  }
+  const params = {};
+  for (const [key, value] of Object.entries(match.groups ?? {})) {
+    if (value !== void 0) {
+      params[key === WILDCARD_GROUP ? "*" : key] = value;
+    }
+  }
+  return params;
+};
+export {
+  compileTemplate,
+  matchRoute,
+  toRegExp
+};
+//# sourceMappingURL=routeMatch.js.map

package/dist/routeMatch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/routeMatch.ts"],"sourcesContent":["import type { RouteParams } from './RoutingSpec';\n\n// from: https://stackoverflow.com/a/63838890\nconst escapeForRegexp = (str: string): string => str.replace(/[.*+\\-?^${}()|[\\]\\\\]/g, '\\\\$&');\n\n// Internal group name standing in for a `*` wildcard (which is not a valid JS\n// regex group identifier); remapped to the `*` param key after matching.\nconst WILDCARD_GROUP = 'wild';\n\n/**\n * Compile a path template to an anchored RegExp with named groups:\n *   `:name` → one non-slash segment   `*` → the rest (greedy)\n * A template with neither token is a literal exact match. Raw RegExp patterns\n * never reach here — they are the escape hatch, used as authored.\n */\nexport const compileTemplate = (template: string): RegExp => {\n  const token = /(:[A-Za-z_][A-Za-z0-9_]*)|\\*/g;\n  let src = '';\n  let last = 0;\n  let m: RegExpExecArray | null;\n  while ((m = token.exec(template)) !== null) {\n    src += escapeForRegexp(template.slice(last, m.index));\n    src += m[1] ? `(?<${m[1].slice(1)}>[^/]+)` : `(?<${WILDCARD_GROUP}>.*)`;\n    last = m.index + m[0].length;\n  }\n  src += escapeForRegexp(template.slice(last));\n  return new RegExp(`^${src}$`);\n};\n\nconst templateCache = new Map<string, RegExp>();\n\n/** Resolve a pattern to a RegExp: templates are compiled (and cached), RegExp passes through. */\nexport const toRegExp = (pattern: string | RegExp): RegExp => {\n  if (pattern instanceof RegExp) {\n    return pattern;\n  }\n  let compiled = templateCache.get(pattern);\n  if (!compiled) {\n    compiled = compileTemplate(pattern);\n    templateCache.set(pattern, compiled);\n  }\n  return compiled;\n};\n\n/**\n * Match a `sandboxPath` against a route pattern. Returns the named params on a\n * match (the `*` wildcard surfaces under the `'*'` key), or `null` otherwise.\n */\nexport const matchRoute = (pattern: string | RegExp, path: string): RouteParams | null => {\n  const match = path.match(toRegExp(pattern));\n  if (!match) {\n    return null;\n  }\n  const params: RouteParams = {};\n  for (const [key, value] of Object.entries(match.groups ?? {})) {\n    if (value !== undefined) {\n      params[key === WILDCARD_GROUP ? '*' : key] = value;\n    }\n  }\n  return params;\n};\n"],"mappings":"AAGA,MAAM,kBAAkB,CAAC,QAAwB,IAAI,QAAQ,yBAAyB,MAAM;AAI5F,MAAM,iBAAiB;AAQhB,MAAM,kBAAkB,CAAC,aAA6B;AAC3D,QAAM,QAAQ;AACd,MAAI,MAAM;AACV,MAAI,OAAO;AACX,MAAI;AACJ,UAAQ,IAAI,MAAM,KAAK,QAAQ,OAAO,MAAM;AAC1C,WAAO,gBAAgB,SAAS,MAAM,MAAM,EAAE,KAAK,CAAC;AACpD,WAAO,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,YAAY,MAAM,cAAc;AACjE,WAAO,EAAE,QAAQ,EAAE,CAAC,EAAE;AAAA,EACxB;AACA,SAAO,gBAAgB,SAAS,MAAM,IAAI,CAAC;AAC3C,SAAO,IAAI,OAAO,IAAI,GAAG,GAAG;AAC9B;AAEA,MAAM,gBAAgB,oBAAI,IAAoB;AAGvC,MAAM,WAAW,CAAC,YAAqC;AAC5D,MAAI,mBAAmB,QAAQ;AAC7B,WAAO;AAAA,EACT;AACA,MAAI,WAAW,cAAc,IAAI,OAAO;AACxC,MAAI,CAAC,UAAU;AACb,eAAW,gBAAgB,OAAO;AAClC,kBAAc,IAAI,SAAS,QAAQ;AAAA,EACrC;AACA,SAAO;AACT;AAMO,MAAM,aAAa,CAAC,SAA0B,SAAqC;AACxF,QAAM,QAAQ,KAAK,MAAM,SAAS,OAAO,CAAC;AAC1C,MAAI,CAAC,OAAO;AACV,WAAO;AAAA,EACT;AACA,QAAM,SAAsB,CAAC;AAC7B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,UAAU,CAAC,CAAC,GAAG;AAC7D,QAAI,UAAU,QAAW;AACvB,aAAO,QAAQ,iBAAiB,MAAM,GAAG,IAAI;AAAA,IAC/C;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/routing.cjs

@@ -21,12 +21,17 @@ __export(routing_exports, {
   Router: () => Router,
   applyRoutingRule: () => applyRoutingRule,
   navigate: () => navigate,
+  renderRoute: () => renderRoute,
+  useRoute: () => useRoute,
+  useRouteParams: () => useRouteParams,
   useTinkerableLink: () => useTinkerableLink
 });
 module.exports = __toCommonJS(routing_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
 var import_react = require("react");
 var import_sandboxUtils = require("./sandboxUtils");
 var import_TinkerableContext = require("./TinkerableContext");
+var import_routeMatch = require("./routeMatch");
 var import_urlUtils = require("./urlUtils");
 var import_pathUtils = require("./pathUtils");
 const useTinkerableLink = (newSandboxLocation) => {
@@ -42,29 +47,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 = (0, import_routeMatch.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__ */ (0, import_jsx_runtime.jsx)(Component, { params });
+  }
+  return routingRule.element ?? routingRule.reactNode ?? null;
+};
 const Router = () => {
   const context = (0, import_react.useContext)(import_TinkerableContext.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 = () => (0, import_react.use)(import_TinkerableContext.TinkerableContext).navigationState.pathParameters ?? {};
+const useRoute = () => {
+  const { navigationState } = (0, import_react.use)(import_TinkerableContext.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}`);
@@ -79,6 +97,9 @@ const navigate = (target) => {
   Router,
   applyRoutingRule,
   navigate,
+  renderRoute,
+  useRoute,
+  useRouteParams,
   useTinkerableLink
 });
 //# sourceMappingURL=routing.cjs.map

package/dist/routing.cjs.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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAgC;AAEhC,0BAA4B;AAC5B,+BAAmD;AAEnD,sBAA0D;AAC1D,uBAA0B;AAOnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,QAAI,kBAAI,0CAAiB;AACxE,MAAI,yBAAqB,6BAAY,oBAAoB,UAAU;AACnE,MAAI,KAAC,gCAAe,kBAAkB,GAAG;AACvC,uBAAmB,kBAAc,4BAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,aAAO,8BAAa,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,cAAU,yBAAW,0CAAiB;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,uCAAY,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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8CW;AA7CX,mBAAgC;AAEhC,0BAA4B;AAC5B,+BAAmD;AAEnD,wBAA2B;AAC3B,sBAA0D;AAC1D,uBAA0B;AAUnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,QAAI,kBAAI,0CAAiB;AACxE,MAAI,yBAAqB,6BAAY,oBAAoB,UAAU;AACnE,MAAI,KAAC,gCAAe,kBAAkB,GAAG;AACvC,uBAAmB,kBAAc,4BAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,aAAO,8BAAa,WAAW,kBAAkB;AACnD;AAIO,MAAM,mBAAmB,CAAC,aAAyB,oBAAqE;AAC7H,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,UAAM,qBAAiB,8BAAW,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,4CAAC,aAAU,QAAgB;AAAA,EACpC;AACA,SAAO,YAAY,WAAW,YAAY,aAAa;AACzD;AAGO,MAAM,SAAS,MAAM;AAC1B,QAAM,cAAU,yBAAW,0CAAiB;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,UAC3B,kBAAI,0CAAiB,EAAE,gBAAgB,kBAAkB,CAAC;AAOtD,MAAM,WAAW,MAAM;AAC5B,QAAM,EAAE,gBAAgB,QAAI,kBAAI,0CAAiB;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,uCAAY,aAAa;AAAA,IACvB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}

package/dist/routing.d.cts

@@ -1,15 +1,44 @@
-import * as react from 'react';
+import { ReactNode } from 'react';
 import { NavigationState } from './TinkerableContext.cjs';
-import { RoutingRule, RoutingSpec } from './RoutingSpec.cjs';
+import { RoutingRule, RoutingSpec, RouteParams } from './RoutingSpec.cjs';
 import './sandboxTypes.cjs';
 
+/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */
 type AppliedRoutingRule = {
     routingRule: RoutingRule;
     pathParameters?: Record<string, string>;
 };
+/** Build the full outer href for an in-app target (absolute `sandboxPath` or a
+ *  path relative to the current route), e.g. for an `href` attribute. */
 declare const useTinkerableLink: (newSandboxLocation: string) => string;
+/** Find the first rule in `routingSpec` whose pattern matches the current
+ *  `sandboxPath`, returning it with the captured params (or `undefined`). */
 declare const applyRoutingRule: (routingSpec: RoutingSpec, navigationState: NavigationState) => AppliedRoutingRule | undefined;
-declare const Router: () => react.ReactNode;
+/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */
+declare const renderRoute: (routingRule: RoutingRule, params: RouteParams) => ReactNode;
+/** Render the route matched for the current location (set up by `boot`'s route table). */
+declare const Router: () => ReactNode;
+/** Read the current route's matched params (`:name` segments and the `*` wildcard). */
+declare const useRouteParams: <T extends RouteParams = RouteParams>() => T;
+/**
+ * Read the current route: the matched rule's `name`, its `params`, the app-owned
+ * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,
+ * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.
+ */
+declare const useRoute: () => {
+    name: string | undefined;
+    params: RouteParams;
+    sandboxPath: string;
+    mode: string;
+    provider: string;
+    namespace: string;
+    repository: string;
+    ref: string;
+};
+/**
+ * Navigate within the app. Messages the host to update the URL; the host then
+ * pushes the new href back, which drives the actual route change.
+ */
 declare const navigate: (target: string) => void;
 
-export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, useTinkerableLink };
+export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, renderRoute, useRoute, useRouteParams, useTinkerableLink };

package/dist/routing.d.ts

@@ -1,15 +1,44 @@
-import * as react from 'react';
+import { ReactNode } from 'react';
 import { NavigationState } from './TinkerableContext.js';
-import { RoutingRule, RoutingSpec } from './RoutingSpec.js';
+import { RoutingRule, RoutingSpec, RouteParams } from './RoutingSpec.js';
 import './sandboxTypes.js';
 
+/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */
 type AppliedRoutingRule = {
     routingRule: RoutingRule;
     pathParameters?: Record<string, string>;
 };
+/** Build the full outer href for an in-app target (absolute `sandboxPath` or a
+ *  path relative to the current route), e.g. for an `href` attribute. */
 declare const useTinkerableLink: (newSandboxLocation: string) => string;
+/** Find the first rule in `routingSpec` whose pattern matches the current
+ *  `sandboxPath`, returning it with the captured params (or `undefined`). */
 declare const applyRoutingRule: (routingSpec: RoutingSpec, navigationState: NavigationState) => AppliedRoutingRule | undefined;
-declare const Router: () => react.ReactNode;
+/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */
+declare const renderRoute: (routingRule: RoutingRule, params: RouteParams) => ReactNode;
+/** Render the route matched for the current location (set up by `boot`'s route table). */
+declare const Router: () => ReactNode;
+/** Read the current route's matched params (`:name` segments and the `*` wildcard). */
+declare const useRouteParams: <T extends RouteParams = RouteParams>() => T;
+/**
+ * Read the current route: the matched rule's `name`, its `params`, the app-owned
+ * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,
+ * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.
+ */
+declare const useRoute: () => {
+    name: string | undefined;
+    params: RouteParams;
+    sandboxPath: string;
+    mode: string;
+    provider: string;
+    namespace: string;
+    repository: string;
+    ref: string;
+};
+/**
+ * Navigate within the app. Messages the host to update the URL; the host then
+ * pushes the new href back, which drives the actual route change.
+ */
 declare const navigate: (target: string) => void;
 
-export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, useTinkerableLink };
+export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, renderRoute, useRoute, useRouteParams, useTinkerableLink };

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.15.0";
+const SDK_VERSION = "0.17.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.15.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.17.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.15.0";
+declare const SDK_VERSION = "0.17.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.15.0";
+declare const SDK_VERSION = "0.17.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,4 +1,4 @@
-const SDK_VERSION = "0.15.0";
+const SDK_VERSION = "0.17.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.15.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.17.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}