@immediately-run/sdk 0.11.0 → 0.12.0

package/dist/boot.cjs

@@ -26,6 +26,7 @@ module.exports = __toCommonJS(boot_exports);
 var import_jsx_runtime = require("react/jsx-runtime");
 var import_react = require("react");
 var import_client = require("react-dom/client");
+var import_markers = require("./markers");
 var import_errors = require("./components/errors");
 var import_FileRouter = require("./components/FileRouter");
 var import_MainContent = require("./components/MainContent");
@@ -85,6 +86,13 @@ const TinkerableApp = ({ routingSpec }) => {
   }, [setContext]);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_TinkerableContext.TinkerableContext, { value: context, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_routing.Router, {}) });
 };
+const BootMarkers = () => {
+  (0, import_react.useLayoutEffect)(() => {
+    (0, import_markers.emitMarkerOnce)("ir.fmp");
+    (0, import_markers.emitMarkerOnce)("ir.interactive");
+  }, []);
+  return null;
+};
 const escapeForRegexp = (str) => str.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&");
 const DEFAULT_ROUTING_SPEC = {
   routes: [
@@ -108,7 +116,10 @@ const boot = ({
   const moduleCache = new import_moduleCache.ModuleCache();
   const root = (0, import_client.createRoot)(rootElement);
   root.render(
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react.StrictMode, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_moduleCache.ModuleCacheContextProvider, { moduleCache, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_MDXProvider.MDXProvider, { components: mdxComponents, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TinkerableApp, { routingSpec }) }) }) })
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react.StrictMode, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_moduleCache.ModuleCacheContextProvider, { moduleCache, children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_MDXProvider.MDXProvider, { components: mdxComponents, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(BootMarkers, {}),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TinkerableApp, { routingSpec })
+    ] }) }) })
   );
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/boot.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, StrictMode, useEffect, useState } from 'react';\nimport { createRoot } from 'react-dom/client';\n\nimport { ErrorNotFound } from './components/errors';\nimport { FileRouter } from './components/FileRouter';\nimport { MainContent } from './components/MainContent';\nimport { DEFAULT_MDX_COMPONENTS } from './components/MDXComponents';\nimport { getInitialContext, updateContext } from './contextUtils';\nimport { getInjectedMetadataEmitter, resolveMetadataSource } from './injectedBundler';\nimport { MDXProvider } from './MDXProvider';\nimport { ModuleCache, ModuleCacheContextProvider } from './moduleCache';\nimport { Router } from './routing';\nimport type { RoutingSpec } from './RoutingSpec';\nimport { FilesMetadata } from './sandboxTypes';\nimport { addListener } from './sandboxUtils';\nimport { TinkerableContext, TinkerableState } from './TinkerableContext';\nimport { FILES_PREFIX } from './urlUtils';\n\nexport type BootProps = {\n  mdxComponents?: Record<string, FC>;\n  routingSpec?: RoutingSpec;\n};\n\nconst updateAlreadyApplied = (filesMetadata: FilesMetadata, update: FilesMetadata) => {\n  for (let [key, value] of Object.entries(update)) {\n    if (filesMetadata[key] !== value) {\n      return false;\n    }\n  }\n  return true;\n};\n\nexport const TinkerableApp = ({ routingSpec }: { routingSpec: RoutingSpec }) => {\n  const [context, setContext] = useState<TinkerableState>(getInitialContext(routingSpec));\n  useEffect(() => {\n    const removeListener = addListener('urlchange', ({ url }) => {\n      setContext((context) => {\n        const updatedContext = updateContext(context, url);\n        if (updatedContext !== context) {\n          console.log(\n            `[Sandbox] Updating path from ${context.navigationState.sandboxPath} to ${updatedContext.navigationState.sandboxPath}`\n          );\n        }\n        return updatedContext;\n      });\n    });\n    return removeListener;\n  }, [setContext]);\n  useEffect(() => {\n    // Phase 5 dual-mode (SDK_PACKAGING_SPEC §4/§8): prefer the injected bundler's\n    // metadata emitter (the live path, byte-identical); when the SDK is npm-fetched\n    // with no injection, `event` is undefined so `addListener` receives\n    // 'metadata-update' over the §4 transport instead, and `enable` is a no-op.\n    const source = resolveMetadataSource(getInjectedMetadataEmitter());\n    const dispose = addListener(\n      'metadata-update',\n      ({ update }: Record<string, any>) => {\n        setContext((prevContext) =>\n          updateAlreadyApplied(prevContext.filesMetadata, update)\n            ? prevContext\n            : {\n                ...prevContext,\n                filesMetadata: {\n                  // TODO: file deletion!\n                  ...prevContext.filesMetadata,\n                  ...update,\n                },\n              }\n        );\n      },\n      source.event\n    );\n    source.enable();\n    return dispose;\n  }, [setContext]);\n\n  return (\n    <TinkerableContext value={context}>\n      <Router />\n    </TinkerableContext>\n  );\n};\n\n// from: https://stackoverflow.com/a/63838890\nconst escapeForRegexp = (str: string) => str.replace(/[.*+\\-?^${}()|[\\]\\\\]/g, '\\\\$&');\n\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: /^\\/$/, reactNode: <MainContent /> },\n    {\n      name: 'FileRouter',\n      pattern: new RegExp(`^${escapeForRegexp(FILES_PREFIX)}(?<filename>\\/.+)$`),\n      reactNode: <FileRouter />,\n    },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, reactNode: <ErrorNotFound /> },\n  ],\n};\n\nexport const boot = ({\n  mdxComponents = DEFAULT_MDX_COMPONENTS,\n  routingSpec = DEFAULT_ROUTING_SPEC,\n}: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={mdxComponents}>\n          <TinkerableApp routingSpec={routingSpec} />\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8EM;AA9EN,mBAAoD;AACpD,oBAA2B;AAE3B,oBAA8B;AAC9B,wBAA2B;AAC3B,yBAA4B;AAC5B,2BAAuC;AACvC,0BAAiD;AACjD,6BAAkE;AAClE,yBAA4B;AAC5B,yBAAwD;AACxD,qBAAuB;AAGvB,0BAA4B;AAC5B,+BAAmD;AACnD,sBAA6B;AAO7B,MAAM,uBAAuB,CAAC,eAA8B,WAA0B;AACpF,WAAS,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AAC/C,QAAI,cAAc,GAAG,MAAM,OAAO;AAChC,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,gBAAgB,CAAC,EAAE,YAAY,MAAoC;AAC9E,QAAM,CAAC,SAAS,UAAU,QAAI,2BAA0B,uCAAkB,WAAW,CAAC;AACtF,8BAAU,MAAM;AACd,UAAM,qBAAiB,iCAAY,aAAa,CAAC,EAAE,IAAI,MAAM;AAC3D,iBAAW,CAACA,aAAY;AACtB,cAAM,qBAAiB,mCAAcA,UAAS,GAAG;AACjD,YAAI,mBAAmBA,UAAS;AAC9B,kBAAQ;AAAA,YACN,gCAAgCA,SAAQ,gBAAgB,WAAW,OAAO,eAAe,gBAAgB,WAAW;AAAA,UACtH;AAAA,QACF;AACA,eAAO;AAAA,MACT,CAAC;AAAA,IACH,CAAC;AACD,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AACf,8BAAU,MAAM;AAKd,UAAM,aAAS,kDAAsB,mDAA2B,CAAC;AACjE,UAAM,cAAU;AAAA,MACd;AAAA,MACA,CAAC,EAAE,OAAO,MAA2B;AACnC;AAAA,UAAW,CAAC,gBACV,qBAAqB,YAAY,eAAe,MAAM,IAClD,cACA;AAAA,YACE,GAAG;AAAA,YACH,eAAe;AAAA;AAAA,cAEb,GAAG,YAAY;AAAA,cACf,GAAG;AAAA,YACL;AAAA,UACF;AAAA,QACN;AAAA,MACF;AAAA,MACA,OAAO;AAAA,IACT;AACA,WAAO,OAAO;AACd,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AAEf,SACE,4CAAC,8CAAkB,OAAO,SACxB,sDAAC,yBAAO,GACV;AAEJ;AAGA,MAAM,kBAAkB,CAAC,QAAgB,IAAI,QAAQ,yBAAyB,MAAM;AAE7E,MAAM,uBAAoC;AAAA,EAC/C,QAAQ;AAAA,IACN,EAAE,MAAM,eAAe,SAAS,QAAQ,WAAW,4CAAC,kCAAY,EAAG;AAAA,IACnE;AAAA,MACE,MAAM;AAAA,MACN,SAAS,IAAI,OAAO,IAAI,gBAAgB,4BAAY,CAAC,mBAAoB;AAAA,MACzE,WAAW,4CAAC,gCAAW;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,iBAAiB,SAAS,iBAAiB,WAAW,4CAAC,+BAAc,EAAG;AAAA,EAClF;AACF;AAEO,MAAM,OAAO,CAAC;AAAA,EACnB,gBAAgB;AAAA,EAChB,cAAc;AAChB,IAAe,CAAC,MAAM;AACpB,QAAM,cAAc,SAAS,eAAe,MAAM;AAClD,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,QAAM,cAAc,IAAI,+BAAY;AACpC,QAAM,WAAO,0BAAW,WAAW;AACnC,OAAK;AAAA,IACH,4CAAC,2BACC,sDAAC,iDAA2B,aAC1B,sDAAC,kCAAY,YAAY,eACvB,sDAAC,iBAAc,aAA0B,GAC3C,GACF,GACF;AAAA,EACF;AACF;","names":["context"]}
+{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, StrictMode, useEffect, useLayoutEffect, useState } from 'react';\nimport { createRoot } from 'react-dom/client';\n\nimport { emitMarkerOnce } from './markers';\n\nimport { ErrorNotFound } from './components/errors';\nimport { FileRouter } from './components/FileRouter';\nimport { MainContent } from './components/MainContent';\nimport { DEFAULT_MDX_COMPONENTS } from './components/MDXComponents';\nimport { getInitialContext, updateContext } from './contextUtils';\nimport { getInjectedMetadataEmitter, resolveMetadataSource } from './injectedBundler';\nimport { MDXProvider } from './MDXProvider';\nimport { ModuleCache, ModuleCacheContextProvider } from './moduleCache';\nimport { Router } from './routing';\nimport type { RoutingSpec } from './RoutingSpec';\nimport { FilesMetadata } from './sandboxTypes';\nimport { addListener } from './sandboxUtils';\nimport { TinkerableContext, TinkerableState } from './TinkerableContext';\nimport { FILES_PREFIX } from './urlUtils';\n\nexport type BootProps = {\n  mdxComponents?: Record<string, FC>;\n  routingSpec?: RoutingSpec;\n};\n\nconst updateAlreadyApplied = (filesMetadata: FilesMetadata, update: FilesMetadata) => {\n  for (let [key, value] of Object.entries(update)) {\n    if (filesMetadata[key] !== value) {\n      return false;\n    }\n  }\n  return true;\n};\n\nexport const TinkerableApp = ({ routingSpec }: { routingSpec: RoutingSpec }) => {\n  const [context, setContext] = useState<TinkerableState>(getInitialContext(routingSpec));\n  useEffect(() => {\n    const removeListener = addListener('urlchange', ({ url }) => {\n      setContext((context) => {\n        const updatedContext = updateContext(context, url);\n        if (updatedContext !== context) {\n          console.log(\n            `[Sandbox] Updating path from ${context.navigationState.sandboxPath} to ${updatedContext.navigationState.sandboxPath}`\n          );\n        }\n        return updatedContext;\n      });\n    });\n    return removeListener;\n  }, [setContext]);\n  useEffect(() => {\n    // Phase 5 dual-mode (SDK_PACKAGING_SPEC §4/§8): prefer the injected bundler's\n    // metadata emitter (the live path, byte-identical); when the SDK is npm-fetched\n    // with no injection, `event` is undefined so `addListener` receives\n    // 'metadata-update' over the §4 transport instead, and `enable` is a no-op.\n    const source = resolveMetadataSource(getInjectedMetadataEmitter());\n    const dispose = addListener(\n      'metadata-update',\n      ({ update }: Record<string, any>) => {\n        setContext((prevContext) =>\n          updateAlreadyApplied(prevContext.filesMetadata, update)\n            ? prevContext\n            : {\n                ...prevContext,\n                filesMetadata: {\n                  // TODO: file deletion!\n                  ...prevContext.filesMetadata,\n                  ...update,\n                },\n              }\n        );\n      },\n      source.event\n    );\n    source.enable();\n    return dispose;\n  }, [setContext]);\n\n  return (\n    <TinkerableContext value={context}>\n      <Router />\n    </TinkerableContext>\n  );\n};\n\n// Boot marker emitter (LOAD_PROFILING_SPEC §3, R3-46). Rendered at the top of the\n// app tree so its layout effect fires on the FIRST root-render commit: that instant\n// is `ir.fmp` (the content is in the DOM, about to paint) and the baseline for\n// `ir.interactive` (the host treats a forwarded `ir.interactive` as the root-commit\n// signal and resolves `max(commit, reportReady)` — LP2-3 — so this can only ever be\n// delayed by an app's `reportReady()`, never advanced). Emitted in canonical stream\n// order (fmp then interactive); idempotent per name (StrictMode-safe). Renders null.\nconst BootMarkers = (): null => {\n  useLayoutEffect(() => {\n    emitMarkerOnce('ir.fmp');\n    emitMarkerOnce('ir.interactive');\n  }, []);\n  return null;\n};\n\n// from: https://stackoverflow.com/a/63838890\nconst escapeForRegexp = (str: string) => str.replace(/[.*+\\-?^${}()|[\\]\\\\]/g, '\\\\$&');\n\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: /^\\/$/, reactNode: <MainContent /> },\n    {\n      name: 'FileRouter',\n      pattern: new RegExp(`^${escapeForRegexp(FILES_PREFIX)}(?<filename>\\/.+)$`),\n      reactNode: <FileRouter />,\n    },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, reactNode: <ErrorNotFound /> },\n  ],\n};\n\nexport const boot = ({\n  mdxComponents = DEFAULT_MDX_COMPONENTS,\n  routingSpec = DEFAULT_ROUTING_SPEC,\n}: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={mdxComponents}>\n          <BootMarkers />\n          <TinkerableApp routingSpec={routingSpec} />\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgFM;AAhFN,mBAAqE;AACrE,oBAA2B;AAE3B,qBAA+B;AAE/B,oBAA8B;AAC9B,wBAA2B;AAC3B,yBAA4B;AAC5B,2BAAuC;AACvC,0BAAiD;AACjD,6BAAkE;AAClE,yBAA4B;AAC5B,yBAAwD;AACxD,qBAAuB;AAGvB,0BAA4B;AAC5B,+BAAmD;AACnD,sBAA6B;AAO7B,MAAM,uBAAuB,CAAC,eAA8B,WAA0B;AACpF,WAAS,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AAC/C,QAAI,cAAc,GAAG,MAAM,OAAO;AAChC,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,gBAAgB,CAAC,EAAE,YAAY,MAAoC;AAC9E,QAAM,CAAC,SAAS,UAAU,QAAI,2BAA0B,uCAAkB,WAAW,CAAC;AACtF,8BAAU,MAAM;AACd,UAAM,qBAAiB,iCAAY,aAAa,CAAC,EAAE,IAAI,MAAM;AAC3D,iBAAW,CAACA,aAAY;AACtB,cAAM,qBAAiB,mCAAcA,UAAS,GAAG;AACjD,YAAI,mBAAmBA,UAAS;AAC9B,kBAAQ;AAAA,YACN,gCAAgCA,SAAQ,gBAAgB,WAAW,OAAO,eAAe,gBAAgB,WAAW;AAAA,UACtH;AAAA,QACF;AACA,eAAO;AAAA,MACT,CAAC;AAAA,IACH,CAAC;AACD,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AACf,8BAAU,MAAM;AAKd,UAAM,aAAS,kDAAsB,mDAA2B,CAAC;AACjE,UAAM,cAAU;AAAA,MACd;AAAA,MACA,CAAC,EAAE,OAAO,MAA2B;AACnC;AAAA,UAAW,CAAC,gBACV,qBAAqB,YAAY,eAAe,MAAM,IAClD,cACA;AAAA,YACE,GAAG;AAAA,YACH,eAAe;AAAA;AAAA,cAEb,GAAG,YAAY;AAAA,cACf,GAAG;AAAA,YACL;AAAA,UACF;AAAA,QACN;AAAA,MACF;AAAA,MACA,OAAO;AAAA,IACT;AACA,WAAO,OAAO;AACd,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AAEf,SACE,4CAAC,8CAAkB,OAAO,SACxB,sDAAC,yBAAO,GACV;AAEJ;AASA,MAAM,cAAc,MAAY;AAC9B,oCAAgB,MAAM;AACpB,uCAAe,QAAQ;AACvB,uCAAe,gBAAgB;AAAA,EACjC,GAAG,CAAC,CAAC;AACL,SAAO;AACT;AAGA,MAAM,kBAAkB,CAAC,QAAgB,IAAI,QAAQ,yBAAyB,MAAM;AAE7E,MAAM,uBAAoC;AAAA,EAC/C,QAAQ;AAAA,IACN,EAAE,MAAM,eAAe,SAAS,QAAQ,WAAW,4CAAC,kCAAY,EAAG;AAAA,IACnE;AAAA,MACE,MAAM;AAAA,MACN,SAAS,IAAI,OAAO,IAAI,gBAAgB,4BAAY,CAAC,mBAAoB;AAAA,MACzE,WAAW,4CAAC,gCAAW;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,iBAAiB,SAAS,iBAAiB,WAAW,4CAAC,+BAAc,EAAG;AAAA,EAClF;AACF;AAEO,MAAM,OAAO,CAAC;AAAA,EACnB,gBAAgB;AAAA,EAChB,cAAc;AAChB,IAAe,CAAC,MAAM;AACpB,QAAM,cAAc,SAAS,eAAe,MAAM;AAClD,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,QAAM,cAAc,IAAI,+BAAY;AACpC,QAAM,WAAO,0BAAW,WAAW;AACnC,OAAK;AAAA,IACH,4CAAC,2BACC,sDAAC,iDAA2B,aAC1B,uDAAC,kCAAY,YAAY,eACvB;AAAA,kDAAC,eAAY;AAAA,MACb,4CAAC,iBAAc,aAA0B;AAAA,OAC3C,GACF,GACF;AAAA,EACF;AACF;","names":["context"]}

package/dist/boot.js

@@ -1,6 +1,7 @@
-import { jsx } from "react/jsx-runtime";
-import { StrictMode, useEffect, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { StrictMode, useEffect, useLayoutEffect, useState } from "react";
 import { createRoot } from "react-dom/client";
+import { emitMarkerOnce } from "./markers";
 import { ErrorNotFound } from "./components/errors";
 import { FileRouter } from "./components/FileRouter";
 import { MainContent } from "./components/MainContent";
@@ -60,6 +61,13 @@ const TinkerableApp = ({ routingSpec }) => {
   }, [setContext]);
   return /* @__PURE__ */ jsx(TinkerableContext, { value: context, children: /* @__PURE__ */ jsx(Router, {}) });
 };
+const BootMarkers = () => {
+  useLayoutEffect(() => {
+    emitMarkerOnce("ir.fmp");
+    emitMarkerOnce("ir.interactive");
+  }, []);
+  return null;
+};
 const escapeForRegexp = (str) => str.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&");
 const DEFAULT_ROUTING_SPEC = {
   routes: [
@@ -83,7 +91,10 @@ const boot = ({
   const moduleCache = new ModuleCache();
   const root = createRoot(rootElement);
   root.render(
-    /* @__PURE__ */ jsx(StrictMode, { children: /* @__PURE__ */ jsx(ModuleCacheContextProvider, { moduleCache, children: /* @__PURE__ */ jsx(MDXProvider, { components: mdxComponents, children: /* @__PURE__ */ jsx(TinkerableApp, { routingSpec }) }) }) })
+    /* @__PURE__ */ jsx(StrictMode, { children: /* @__PURE__ */ jsx(ModuleCacheContextProvider, { moduleCache, children: /* @__PURE__ */ jsxs(MDXProvider, { components: mdxComponents, children: [
+      /* @__PURE__ */ jsx(BootMarkers, {}),
+      /* @__PURE__ */ jsx(TinkerableApp, { routingSpec })
+    ] }) }) })
   );
 };
 export {

package/dist/boot.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, StrictMode, useEffect, useState } from 'react';\nimport { createRoot } from 'react-dom/client';\n\nimport { ErrorNotFound } from './components/errors';\nimport { FileRouter } from './components/FileRouter';\nimport { MainContent } from './components/MainContent';\nimport { DEFAULT_MDX_COMPONENTS } from './components/MDXComponents';\nimport { getInitialContext, updateContext } from './contextUtils';\nimport { getInjectedMetadataEmitter, resolveMetadataSource } from './injectedBundler';\nimport { MDXProvider } from './MDXProvider';\nimport { ModuleCache, ModuleCacheContextProvider } from './moduleCache';\nimport { Router } from './routing';\nimport type { RoutingSpec } from './RoutingSpec';\nimport { FilesMetadata } from './sandboxTypes';\nimport { addListener } from './sandboxUtils';\nimport { TinkerableContext, TinkerableState } from './TinkerableContext';\nimport { FILES_PREFIX } from './urlUtils';\n\nexport type BootProps = {\n  mdxComponents?: Record<string, FC>;\n  routingSpec?: RoutingSpec;\n};\n\nconst updateAlreadyApplied = (filesMetadata: FilesMetadata, update: FilesMetadata) => {\n  for (let [key, value] of Object.entries(update)) {\n    if (filesMetadata[key] !== value) {\n      return false;\n    }\n  }\n  return true;\n};\n\nexport const TinkerableApp = ({ routingSpec }: { routingSpec: RoutingSpec }) => {\n  const [context, setContext] = useState<TinkerableState>(getInitialContext(routingSpec));\n  useEffect(() => {\n    const removeListener = addListener('urlchange', ({ url }) => {\n      setContext((context) => {\n        const updatedContext = updateContext(context, url);\n        if (updatedContext !== context) {\n          console.log(\n            `[Sandbox] Updating path from ${context.navigationState.sandboxPath} to ${updatedContext.navigationState.sandboxPath}`\n          );\n        }\n        return updatedContext;\n      });\n    });\n    return removeListener;\n  }, [setContext]);\n  useEffect(() => {\n    // Phase 5 dual-mode (SDK_PACKAGING_SPEC §4/§8): prefer the injected bundler's\n    // metadata emitter (the live path, byte-identical); when the SDK is npm-fetched\n    // with no injection, `event` is undefined so `addListener` receives\n    // 'metadata-update' over the §4 transport instead, and `enable` is a no-op.\n    const source = resolveMetadataSource(getInjectedMetadataEmitter());\n    const dispose = addListener(\n      'metadata-update',\n      ({ update }: Record<string, any>) => {\n        setContext((prevContext) =>\n          updateAlreadyApplied(prevContext.filesMetadata, update)\n            ? prevContext\n            : {\n                ...prevContext,\n                filesMetadata: {\n                  // TODO: file deletion!\n                  ...prevContext.filesMetadata,\n                  ...update,\n                },\n              }\n        );\n      },\n      source.event\n    );\n    source.enable();\n    return dispose;\n  }, [setContext]);\n\n  return (\n    <TinkerableContext value={context}>\n      <Router />\n    </TinkerableContext>\n  );\n};\n\n// from: https://stackoverflow.com/a/63838890\nconst escapeForRegexp = (str: string) => str.replace(/[.*+\\-?^${}()|[\\]\\\\]/g, '\\\\$&');\n\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: /^\\/$/, reactNode: <MainContent /> },\n    {\n      name: 'FileRouter',\n      pattern: new RegExp(`^${escapeForRegexp(FILES_PREFIX)}(?<filename>\\/.+)$`),\n      reactNode: <FileRouter />,\n    },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, reactNode: <ErrorNotFound /> },\n  ],\n};\n\nexport const boot = ({\n  mdxComponents = DEFAULT_MDX_COMPONENTS,\n  routingSpec = DEFAULT_ROUTING_SPEC,\n}: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={mdxComponents}>\n          <TinkerableApp routingSpec={routingSpec} />\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>\n  );\n};\n"],"mappings":"AA8EM;AA9EN,SAAa,YAAY,WAAW,gBAAgB;AACpD,SAAS,kBAAkB;AAE3B,SAAS,qBAAqB;AAC9B,SAAS,kBAAkB;AAC3B,SAAS,mBAAmB;AAC5B,SAAS,8BAA8B;AACvC,SAAS,mBAAmB,qBAAqB;AACjD,SAAS,4BAA4B,6BAA6B;AAClE,SAAS,mBAAmB;AAC5B,SAAS,aAAa,kCAAkC;AACxD,SAAS,cAAc;AAGvB,SAAS,mBAAmB;AAC5B,SAAS,yBAA0C;AACnD,SAAS,oBAAoB;AAO7B,MAAM,uBAAuB,CAAC,eAA8B,WAA0B;AACpF,WAAS,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AAC/C,QAAI,cAAc,GAAG,MAAM,OAAO;AAChC,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,gBAAgB,CAAC,EAAE,YAAY,MAAoC;AAC9E,QAAM,CAAC,SAAS,UAAU,IAAI,SAA0B,kBAAkB,WAAW,CAAC;AACtF,YAAU,MAAM;AACd,UAAM,iBAAiB,YAAY,aAAa,CAAC,EAAE,IAAI,MAAM;AAC3D,iBAAW,CAACA,aAAY;AACtB,cAAM,iBAAiB,cAAcA,UAAS,GAAG;AACjD,YAAI,mBAAmBA,UAAS;AAC9B,kBAAQ;AAAA,YACN,gCAAgCA,SAAQ,gBAAgB,WAAW,OAAO,eAAe,gBAAgB,WAAW;AAAA,UACtH;AAAA,QACF;AACA,eAAO;AAAA,MACT,CAAC;AAAA,IACH,CAAC;AACD,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AACf,YAAU,MAAM;AAKd,UAAM,SAAS,sBAAsB,2BAA2B,CAAC;AACjE,UAAM,UAAU;AAAA,MACd;AAAA,MACA,CAAC,EAAE,OAAO,MAA2B;AACnC;AAAA,UAAW,CAAC,gBACV,qBAAqB,YAAY,eAAe,MAAM,IAClD,cACA;AAAA,YACE,GAAG;AAAA,YACH,eAAe;AAAA;AAAA,cAEb,GAAG,YAAY;AAAA,cACf,GAAG;AAAA,YACL;AAAA,UACF;AAAA,QACN;AAAA,MACF;AAAA,MACA,OAAO;AAAA,IACT;AACA,WAAO,OAAO;AACd,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AAEf,SACE,oBAAC,qBAAkB,OAAO,SACxB,8BAAC,UAAO,GACV;AAEJ;AAGA,MAAM,kBAAkB,CAAC,QAAgB,IAAI,QAAQ,yBAAyB,MAAM;AAE7E,MAAM,uBAAoC;AAAA,EAC/C,QAAQ;AAAA,IACN,EAAE,MAAM,eAAe,SAAS,QAAQ,WAAW,oBAAC,eAAY,EAAG;AAAA,IACnE;AAAA,MACE,MAAM;AAAA,MACN,SAAS,IAAI,OAAO,IAAI,gBAAgB,YAAY,CAAC,mBAAoB;AAAA,MACzE,WAAW,oBAAC,cAAW;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,iBAAiB,SAAS,iBAAiB,WAAW,oBAAC,iBAAc,EAAG;AAAA,EAClF;AACF;AAEO,MAAM,OAAO,CAAC;AAAA,EACnB,gBAAgB;AAAA,EAChB,cAAc;AAChB,IAAe,CAAC,MAAM;AACpB,QAAM,cAAc,SAAS,eAAe,MAAM;AAClD,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,QAAM,cAAc,IAAI,YAAY;AACpC,QAAM,OAAO,WAAW,WAAW;AACnC,OAAK;AAAA,IACH,oBAAC,cACC,8BAAC,8BAA2B,aAC1B,8BAAC,eAAY,YAAY,eACvB,8BAAC,iBAAc,aAA0B,GAC3C,GACF,GACF;AAAA,EACF;AACF;","names":["context"]}
+{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, StrictMode, useEffect, useLayoutEffect, useState } from 'react';\nimport { createRoot } from 'react-dom/client';\n\nimport { emitMarkerOnce } from './markers';\n\nimport { ErrorNotFound } from './components/errors';\nimport { FileRouter } from './components/FileRouter';\nimport { MainContent } from './components/MainContent';\nimport { DEFAULT_MDX_COMPONENTS } from './components/MDXComponents';\nimport { getInitialContext, updateContext } from './contextUtils';\nimport { getInjectedMetadataEmitter, resolveMetadataSource } from './injectedBundler';\nimport { MDXProvider } from './MDXProvider';\nimport { ModuleCache, ModuleCacheContextProvider } from './moduleCache';\nimport { Router } from './routing';\nimport type { RoutingSpec } from './RoutingSpec';\nimport { FilesMetadata } from './sandboxTypes';\nimport { addListener } from './sandboxUtils';\nimport { TinkerableContext, TinkerableState } from './TinkerableContext';\nimport { FILES_PREFIX } from './urlUtils';\n\nexport type BootProps = {\n  mdxComponents?: Record<string, FC>;\n  routingSpec?: RoutingSpec;\n};\n\nconst updateAlreadyApplied = (filesMetadata: FilesMetadata, update: FilesMetadata) => {\n  for (let [key, value] of Object.entries(update)) {\n    if (filesMetadata[key] !== value) {\n      return false;\n    }\n  }\n  return true;\n};\n\nexport const TinkerableApp = ({ routingSpec }: { routingSpec: RoutingSpec }) => {\n  const [context, setContext] = useState<TinkerableState>(getInitialContext(routingSpec));\n  useEffect(() => {\n    const removeListener = addListener('urlchange', ({ url }) => {\n      setContext((context) => {\n        const updatedContext = updateContext(context, url);\n        if (updatedContext !== context) {\n          console.log(\n            `[Sandbox] Updating path from ${context.navigationState.sandboxPath} to ${updatedContext.navigationState.sandboxPath}`\n          );\n        }\n        return updatedContext;\n      });\n    });\n    return removeListener;\n  }, [setContext]);\n  useEffect(() => {\n    // Phase 5 dual-mode (SDK_PACKAGING_SPEC §4/§8): prefer the injected bundler's\n    // metadata emitter (the live path, byte-identical); when the SDK is npm-fetched\n    // with no injection, `event` is undefined so `addListener` receives\n    // 'metadata-update' over the §4 transport instead, and `enable` is a no-op.\n    const source = resolveMetadataSource(getInjectedMetadataEmitter());\n    const dispose = addListener(\n      'metadata-update',\n      ({ update }: Record<string, any>) => {\n        setContext((prevContext) =>\n          updateAlreadyApplied(prevContext.filesMetadata, update)\n            ? prevContext\n            : {\n                ...prevContext,\n                filesMetadata: {\n                  // TODO: file deletion!\n                  ...prevContext.filesMetadata,\n                  ...update,\n                },\n              }\n        );\n      },\n      source.event\n    );\n    source.enable();\n    return dispose;\n  }, [setContext]);\n\n  return (\n    <TinkerableContext value={context}>\n      <Router />\n    </TinkerableContext>\n  );\n};\n\n// Boot marker emitter (LOAD_PROFILING_SPEC §3, R3-46). Rendered at the top of the\n// app tree so its layout effect fires on the FIRST root-render commit: that instant\n// is `ir.fmp` (the content is in the DOM, about to paint) and the baseline for\n// `ir.interactive` (the host treats a forwarded `ir.interactive` as the root-commit\n// signal and resolves `max(commit, reportReady)` — LP2-3 — so this can only ever be\n// delayed by an app's `reportReady()`, never advanced). Emitted in canonical stream\n// order (fmp then interactive); idempotent per name (StrictMode-safe). Renders null.\nconst BootMarkers = (): null => {\n  useLayoutEffect(() => {\n    emitMarkerOnce('ir.fmp');\n    emitMarkerOnce('ir.interactive');\n  }, []);\n  return null;\n};\n\n// from: https://stackoverflow.com/a/63838890\nconst escapeForRegexp = (str: string) => str.replace(/[.*+\\-?^${}()|[\\]\\\\]/g, '\\\\$&');\n\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: /^\\/$/, reactNode: <MainContent /> },\n    {\n      name: 'FileRouter',\n      pattern: new RegExp(`^${escapeForRegexp(FILES_PREFIX)}(?<filename>\\/.+)$`),\n      reactNode: <FileRouter />,\n    },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, reactNode: <ErrorNotFound /> },\n  ],\n};\n\nexport const boot = ({\n  mdxComponents = DEFAULT_MDX_COMPONENTS,\n  routingSpec = DEFAULT_ROUTING_SPEC,\n}: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={mdxComponents}>\n          <BootMarkers />\n          <TinkerableApp routingSpec={routingSpec} />\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>\n  );\n};\n"],"mappings":"AAgFM,cAgDE,YAhDF;AAhFN,SAAa,YAAY,WAAW,iBAAiB,gBAAgB;AACrE,SAAS,kBAAkB;AAE3B,SAAS,sBAAsB;AAE/B,SAAS,qBAAqB;AAC9B,SAAS,kBAAkB;AAC3B,SAAS,mBAAmB;AAC5B,SAAS,8BAA8B;AACvC,SAAS,mBAAmB,qBAAqB;AACjD,SAAS,4BAA4B,6BAA6B;AAClE,SAAS,mBAAmB;AAC5B,SAAS,aAAa,kCAAkC;AACxD,SAAS,cAAc;AAGvB,SAAS,mBAAmB;AAC5B,SAAS,yBAA0C;AACnD,SAAS,oBAAoB;AAO7B,MAAM,uBAAuB,CAAC,eAA8B,WAA0B;AACpF,WAAS,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AAC/C,QAAI,cAAc,GAAG,MAAM,OAAO;AAChC,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,gBAAgB,CAAC,EAAE,YAAY,MAAoC;AAC9E,QAAM,CAAC,SAAS,UAAU,IAAI,SAA0B,kBAAkB,WAAW,CAAC;AACtF,YAAU,MAAM;AACd,UAAM,iBAAiB,YAAY,aAAa,CAAC,EAAE,IAAI,MAAM;AAC3D,iBAAW,CAACA,aAAY;AACtB,cAAM,iBAAiB,cAAcA,UAAS,GAAG;AACjD,YAAI,mBAAmBA,UAAS;AAC9B,kBAAQ;AAAA,YACN,gCAAgCA,SAAQ,gBAAgB,WAAW,OAAO,eAAe,gBAAgB,WAAW;AAAA,UACtH;AAAA,QACF;AACA,eAAO;AAAA,MACT,CAAC;AAAA,IACH,CAAC;AACD,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AACf,YAAU,MAAM;AAKd,UAAM,SAAS,sBAAsB,2BAA2B,CAAC;AACjE,UAAM,UAAU;AAAA,MACd;AAAA,MACA,CAAC,EAAE,OAAO,MAA2B;AACnC;AAAA,UAAW,CAAC,gBACV,qBAAqB,YAAY,eAAe,MAAM,IAClD,cACA;AAAA,YACE,GAAG;AAAA,YACH,eAAe;AAAA;AAAA,cAEb,GAAG,YAAY;AAAA,cACf,GAAG;AAAA,YACL;AAAA,UACF;AAAA,QACN;AAAA,MACF;AAAA,MACA,OAAO;AAAA,IACT;AACA,WAAO,OAAO;AACd,WAAO;AAAA,EACT,GAAG,CAAC,UAAU,CAAC;AAEf,SACE,oBAAC,qBAAkB,OAAO,SACxB,8BAAC,UAAO,GACV;AAEJ;AASA,MAAM,cAAc,MAAY;AAC9B,kBAAgB,MAAM;AACpB,mBAAe,QAAQ;AACvB,mBAAe,gBAAgB;AAAA,EACjC,GAAG,CAAC,CAAC;AACL,SAAO;AACT;AAGA,MAAM,kBAAkB,CAAC,QAAgB,IAAI,QAAQ,yBAAyB,MAAM;AAE7E,MAAM,uBAAoC;AAAA,EAC/C,QAAQ;AAAA,IACN,EAAE,MAAM,eAAe,SAAS,QAAQ,WAAW,oBAAC,eAAY,EAAG;AAAA,IACnE;AAAA,MACE,MAAM;AAAA,MACN,SAAS,IAAI,OAAO,IAAI,gBAAgB,YAAY,CAAC,mBAAoB;AAAA,MACzE,WAAW,oBAAC,cAAW;AAAA,IACzB;AAAA,IACA,EAAE,MAAM,iBAAiB,SAAS,iBAAiB,WAAW,oBAAC,iBAAc,EAAG;AAAA,EAClF;AACF;AAEO,MAAM,OAAO,CAAC;AAAA,EACnB,gBAAgB;AAAA,EAChB,cAAc;AAChB,IAAe,CAAC,MAAM;AACpB,QAAM,cAAc,SAAS,eAAe,MAAM;AAClD,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,QAAM,cAAc,IAAI,YAAY;AACpC,QAAM,OAAO,WAAW,WAAW;AACnC,OAAK;AAAA,IACH,oBAAC,cACC,8BAAC,8BAA2B,aAC1B,+BAAC,eAAY,YAAY,eACvB;AAAA,0BAAC,eAAY;AAAA,MACb,oBAAC,iBAAc,aAA0B;AAAA,OAC3C,GACF,GACF;AAAA,EACF;AACF;","names":["context"]}

package/dist/diagnostics.cjs

@@ -0,0 +1,51 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var diagnostics_exports = {};
+__export(diagnostics_exports, {
+  getDiagnostics: () => getDiagnostics,
+  onDiagnosticsChange: () => onDiagnosticsChange,
+  useDiagnostics: () => useDiagnostics
+});
+module.exports = __toCommonJS(diagnostics_exports);
+var import_pushChannel = require("./pushChannel");
+const EMPTY = { buildErrors: [], consoleEntries: [], provenance: null };
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "diagnostics",
+  requestType: "request-diagnostics",
+  initial: EMPTY,
+  parse: (msg) => {
+    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return void 0;
+    const provenance = msg.provenance && typeof msg.provenance === "object" ? msg.provenance : null;
+    return {
+      buildErrors: msg.buildErrors,
+      consoleEntries: msg.consoleEntries,
+      provenance
+    };
+  }
+});
+const getDiagnostics = () => channel.get();
+const onDiagnosticsChange = (listener) => channel.onChange(listener);
+const useDiagnostics = () => channel.use();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getDiagnostics,
+  onDiagnosticsChange,
+  useDiagnostics
+});
+//# sourceMappingURL=diagnostics.cjs.map

package/dist/diagnostics.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,yBAAkC;AAyClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,cAAU,sCAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}

package/dist/diagnostics.d.cts

@@ -0,0 +1,43 @@
+/** One build/transpile error from the sandbox bundler's compile of the previewed
+ *  app. `path` is repo-relative (leading slash) when the error is file-located. */
+interface BuildError {
+    message: string;
+    path?: string;
+    line?: number;
+    column?: number;
+}
+type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+/** One captured `console.*` entry from the previewed app. The host renders the
+ *  console arguments to text host-side — the agent never receives live object
+ *  handles across the boundary. */
+interface ConsoleEntry {
+    level: ConsoleLevel;
+    text: string;
+    /** Host-side timestamp (ms) at capture. */
+    at: number;
+}
+/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this
+ *  snapshot describes, so a consumer can tell stale output from fresh and never
+ *  conflates two apps' diagnostics. `null` until a first compile is observed. */
+interface DiagnosticsProvenance {
+    /** The previewed app's stable key (`provider/ns/repo`). */
+    appKey?: string;
+    /** Monotonic id of the compile that produced these build errors. */
+    compileId?: string;
+}
+interface Diagnostics {
+    buildErrors: BuildError[];
+    consoleEntries: ConsoleEntry[];
+    provenance: DiagnosticsProvenance | null;
+}
+/** One-off read of the previewed app's current diagnostics. Returns the empty
+ *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use
+ *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */
+declare const getDiagnostics: () => Diagnostics;
+/** Subscribe to diagnostics. Invoked immediately with the current value, then on
+ *  every host push. Returns an unsubscribe. */
+declare const onDiagnosticsChange: (listener: (d: Diagnostics) => void) => (() => void);
+/** React hook: the current diagnostics, re-rendering on every change. */
+declare const useDiagnostics: () => Diagnostics;
+
+export { type BuildError, type ConsoleEntry, type ConsoleLevel, type Diagnostics, type DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics };

package/dist/diagnostics.d.ts

@@ -0,0 +1,43 @@
+/** One build/transpile error from the sandbox bundler's compile of the previewed
+ *  app. `path` is repo-relative (leading slash) when the error is file-located. */
+interface BuildError {
+    message: string;
+    path?: string;
+    line?: number;
+    column?: number;
+}
+type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+/** One captured `console.*` entry from the previewed app. The host renders the
+ *  console arguments to text host-side — the agent never receives live object
+ *  handles across the boundary. */
+interface ConsoleEntry {
+    level: ConsoleLevel;
+    text: string;
+    /** Host-side timestamp (ms) at capture. */
+    at: number;
+}
+/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this
+ *  snapshot describes, so a consumer can tell stale output from fresh and never
+ *  conflates two apps' diagnostics. `null` until a first compile is observed. */
+interface DiagnosticsProvenance {
+    /** The previewed app's stable key (`provider/ns/repo`). */
+    appKey?: string;
+    /** Monotonic id of the compile that produced these build errors. */
+    compileId?: string;
+}
+interface Diagnostics {
+    buildErrors: BuildError[];
+    consoleEntries: ConsoleEntry[];
+    provenance: DiagnosticsProvenance | null;
+}
+/** One-off read of the previewed app's current diagnostics. Returns the empty
+ *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use
+ *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */
+declare const getDiagnostics: () => Diagnostics;
+/** Subscribe to diagnostics. Invoked immediately with the current value, then on
+ *  every host push. Returns an unsubscribe. */
+declare const onDiagnosticsChange: (listener: (d: Diagnostics) => void) => (() => void);
+/** React hook: the current diagnostics, re-rendering on every change. */
+declare const useDiagnostics: () => Diagnostics;
+
+export { type BuildError, type ConsoleEntry, type ConsoleLevel, type Diagnostics, type DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics };

package/dist/diagnostics.js

@@ -0,0 +1,25 @@
+import { createPushChannel } from "./pushChannel";
+const EMPTY = { buildErrors: [], consoleEntries: [], provenance: null };
+const channel = createPushChannel({
+  pushType: "diagnostics",
+  requestType: "request-diagnostics",
+  initial: EMPTY,
+  parse: (msg) => {
+    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return void 0;
+    const provenance = msg.provenance && typeof msg.provenance === "object" ? msg.provenance : null;
+    return {
+      buildErrors: msg.buildErrors,
+      consoleEntries: msg.consoleEntries,
+      provenance
+    };
+  }
+});
+const getDiagnostics = () => channel.get();
+const onDiagnosticsChange = (listener) => channel.onChange(listener);
+const useDiagnostics = () => channel.use();
+export {
+  getDiagnostics,
+  onDiagnosticsChange,
+  useDiagnostics
+};
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":"AAgBA,SAAS,yBAAyB;AAyClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,UAAU,kBAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}

package/dist/hostRuntime.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hostRuntime.ts"],"sourcesContent":["// Runtime-discovery global (SDK_PACKAGING_SPEC §4) — a LEAF module that imports\n// nothing, so it can be read by both `sandboxUtils` (transport resolver) and\n// `runtime` (handshake) without forming an import cycle. `sandboxUtils → runtime`\n// + `runtime → sandboxUtils` was a cycle the sandbox bundler cannot evaluate\n// (infinite re-require → \"Maximum call stack size exceeded\"); routing the shared\n// `getHostRuntime` through this leaf breaks it.\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n  /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);\n   *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */\n  appMountPath?: string;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../src/hostRuntime.ts"],"sourcesContent":["// Runtime-discovery global (SDK_PACKAGING_SPEC §4) — a LEAF module that imports\n// nothing, so it can be read by both `sandboxUtils` (transport resolver) and\n// `runtime` (handshake) without forming an import cycle. `sandboxUtils → runtime`\n// + `runtime → sandboxUtils` was a cycle the sandbox bundler cannot evaluate\n// (infinite re-require → \"Maximum call stack size exceeded\"); routing the shared\n// `getHostRuntime` through this leaf breaks it.\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n  /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);\n   *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */\n  appMountPath?: string;\n  /** The chrome region this app instance occupies, e.g. `\"panel.agent\"` or\n   *  `\"stage.conversation\"` (UI_AS_APPS_SPEC §4.1); surfaced via `getRegion()`.\n   *  Absent for a standalone app, in local dev, or on a host that doesn't report\n   *  it. Descriptive only — it grants nothing. */\n  region?: string;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgCO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/hostRuntime.d.cts

@@ -11,6 +11,11 @@ interface ImmediatelyRunGlobal {
     /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);
      *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */
     appMountPath?: string;
+    /** The chrome region this app instance occupies, e.g. `"panel.agent"` or
+     *  `"stage.conversation"` (UI_AS_APPS_SPEC §4.1); surfaced via `getRegion()`.
+     *  Absent for a standalone app, in local dev, or on a host that doesn't report
+     *  it. Descriptive only — it grants nothing. */
+    region?: string;
 }
 /**
  * Read the sandbox runtime's discovery global (§4), or null when absent — in which

package/dist/hostRuntime.d.ts

@@ -11,6 +11,11 @@ interface ImmediatelyRunGlobal {
     /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);
      *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */
     appMountPath?: string;
+    /** The chrome region this app instance occupies, e.g. `"panel.agent"` or
+     *  `"stage.conversation"` (UI_AS_APPS_SPEC §4.1); surfaced via `getRegion()`.
+     *  Absent for a standalone app, in local dev, or on a host that doesn't report
+     *  it. Descriptive only — it grants nothing. */
+    region?: string;
 }
 /**
  * Read the sandbox runtime's discovery global (§4), or null when absent — in which

package/dist/hostRuntime.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hostRuntime.ts"],"sourcesContent":["// Runtime-discovery global (SDK_PACKAGING_SPEC §4) — a LEAF module that imports\n// nothing, so it can be read by both `sandboxUtils` (transport resolver) and\n// `runtime` (handshake) without forming an import cycle. `sandboxUtils → runtime`\n// + `runtime → sandboxUtils` was a cycle the sandbox bundler cannot evaluate\n// (infinite re-require → \"Maximum call stack size exceeded\"); routing the shared\n// `getHostRuntime` through this leaf breaks it.\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n  /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);\n   *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */\n  appMountPath?: string;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":"AA2BO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../src/hostRuntime.ts"],"sourcesContent":["// Runtime-discovery global (SDK_PACKAGING_SPEC §4) — a LEAF module that imports\n// nothing, so it can be read by both `sandboxUtils` (transport resolver) and\n// `runtime` (handshake) without forming an import cycle. `sandboxUtils → runtime`\n// + `runtime → sandboxUtils` was a cycle the sandbox bundler cannot evaluate\n// (infinite re-require → \"Maximum call stack size exceeded\"); routing the shared\n// `getHostRuntime` through this leaf breaks it.\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n  /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);\n   *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */\n  appMountPath?: string;\n  /** The chrome region this app instance occupies, e.g. `\"panel.agent\"` or\n   *  `\"stage.conversation\"` (UI_AS_APPS_SPEC §4.1); surfaced via `getRegion()`.\n   *  Absent for a standalone app, in local dev, or on a host that doesn't report\n   *  it. Descriptive only — it grants nothing. */\n  region?: string;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":"AAgCO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/index.cjs

@@ -26,6 +26,7 @@ __reExport(index_exports, require("./theme"), module.exports);
 __reExport(index_exports, require("./editorContext"), module.exports);
 __reExport(index_exports, require("./editor"), module.exports);
 __reExport(index_exports, require("./formFactor"), module.exports);
+__reExport(index_exports, require("./region"), module.exports);
 __reExport(index_exports, require("./mounts"), module.exports);
 __reExport(index_exports, require("./contribute"), module.exports);
 __reExport(index_exports, require("./catalog"), module.exports);
@@ -33,6 +34,7 @@ __reExport(index_exports, require("./ipc"), module.exports);
 __reExport(index_exports, require("./dnd"), module.exports);
 __reExport(index_exports, require("./netFetch"), module.exports);
 __reExport(index_exports, require("./secrets"), module.exports);
+__reExport(index_exports, require("./diagnostics"), module.exports);
 __reExport(index_exports, require("./tasks"), module.exports);
 __reExport(index_exports, require("./runtime"), module.exports);
 __reExport(index_exports, require("./irMarkers"), module.exports);
@@ -52,6 +54,7 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./editorContext"),
   ...require("./editor"),
   ...require("./formFactor"),
+  ...require("./region"),
   ...require("./mounts"),
   ...require("./contribute"),
   ...require("./catalog"),
@@ -59,6 +62,7 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./dnd"),
   ...require("./netFetch"),
   ...require("./secrets"),
+  ...require("./diagnostics"),
   ...require("./tasks"),
   ...require("./runtime"),
   ...require("./irMarkers"),

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,4BARd;AASA,0BAAc,qBATd;AAUA,0BAAc,yBAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,yBAZd;AAaA,0BAAc,sBAbd;AAcA,0BAAc,kBAdd;AAeA,0BAAc,kBAfd;AAgBA,0BAAc,uBAhBd;AAiBA,0BAAc,sBAjBd;AAkBA,0BAAc,oBAlBd;AAmBA,0BAAc,sBAnBd;AAoBA,0BAAc,wBApBd;AAqBA,0BAAc,oBArBd;AAsBA,0BAAc,6BAtBd;AAuBA,0BAAc,2BAvBd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './diagnostics';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,4BARd;AASA,0BAAc,qBATd;AAUA,0BAAc,yBAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,qBAZd;AAaA,0BAAc,yBAbd;AAcA,0BAAc,sBAdd;AAeA,0BAAc,kBAfd;AAgBA,0BAAc,kBAhBd;AAiBA,0BAAc,uBAjBd;AAkBA,0BAAc,sBAlBd;AAmBA,0BAAc,0BAnBd;AAoBA,0BAAc,oBApBd;AAqBA,0BAAc,sBArBd;AAsBA,0BAAc,wBAtBd;AAuBA,0BAAc,oBAvBd;AAwBA,0BAAc,6BAxBd;AAyBA,0BAAc,2BAzBd;","names":[]}

package/dist/index.d.cts

@@ -9,6 +9,7 @@ export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.cjs';
 export { EditTarget, EditorOpenError, EditorSessionError, EditorWriteError, RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile } from './editor.cjs';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.cjs';
+export { getRegion, useRegion } from './region.cjs';
 export { GrantRecord, Member, MountQuery, MountRemoveReason, MountRule, RemovedMount, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getAppMountPath, getMounts, getSpaceMembers, importSettingsFromParent, listAllSpaces, listGrants, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.cjs';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.cjs';
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.cjs';
@@ -16,6 +17,7 @@ export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from '
 export { DraggableItem, DroppedItem, ItemDragError, cancelItemDrag, onItemDrop, startItemDrag, useDroppedItem } from './dnd.cjs';
 export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStreamResult, hostFetch, hostFetchStream } from './netFetch.cjs';
 export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.cjs';
+export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.cjs';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.cjs';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.cjs';
 export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMarkerName, resolveInteractive, validateMarker } from './irMarkers.cjs';

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.js';
 export { EditTarget, EditorOpenError, EditorSessionError, EditorWriteError, RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile } from './editor.js';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.js';
+export { getRegion, useRegion } from './region.js';
 export { GrantRecord, Member, MountQuery, MountRemoveReason, MountRule, RemovedMount, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getAppMountPath, getMounts, getSpaceMembers, importSettingsFromParent, listAllSpaces, listGrants, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.js';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.js';
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.js';
@@ -16,6 +17,7 @@ export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from '
 export { DraggableItem, DroppedItem, ItemDragError, cancelItemDrag, onItemDrop, startItemDrag, useDroppedItem } from './dnd.js';
 export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStreamResult, hostFetch, hostFetchStream } from './netFetch.js';
 export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.js';
+export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.js';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.js';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.js';
 export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMarkerName, resolveInteractive, validateMarker } from './irMarkers.js';

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./theme";
 export * from "./editorContext";
 export * from "./editor";
 export * from "./formFactor";
+export * from "./region";
 export * from "./mounts";
 export * from "./contribute";
 export * from "./catalog";
@@ -16,6 +17,7 @@ export * from "./ipc";
 export * from "./dnd";
 export * from "./netFetch";
 export * from "./secrets";
+export * from "./diagnostics";
 export * from "./tasks";
 export * from "./runtime";
 export * from "./irMarkers";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './diagnostics';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/markers.cjs

@@ -0,0 +1,59 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var markers_exports = {};
+__export(markers_exports, {
+  __resetMarkers: () => __resetMarkers,
+  __setMarkerDeps: () => __setMarkerDeps,
+  emitMarker: () => emitMarker,
+  emitMarkerOnce: () => emitMarkerOnce
+});
+module.exports = __toCommonJS(markers_exports);
+var import_sandboxUtils = require("./sandboxUtils");
+var import_irMarkers = require("./irMarkers");
+const realNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+const defaultDeps = { send: import_sandboxUtils.sendMessage, now: realNow };
+let deps = defaultDeps;
+const emitted = /* @__PURE__ */ new Set();
+function emitMarker(name, attrs) {
+  if (!(0, import_irMarkers.isIrMarkerName)(name)) return;
+  try {
+    deps.send("ir-marker", { name, at: deps.now(), ...attrs !== void 0 ? { attrs } : {} });
+  } catch {
+  }
+}
+function emitMarkerOnce(name, attrs) {
+  if (emitted.has(name)) return;
+  emitted.add(name);
+  emitMarker(name, attrs);
+}
+function __setMarkerDeps(d) {
+  deps = { ...defaultDeps, ...d };
+}
+function __resetMarkers() {
+  deps = defaultDeps;
+  emitted.clear();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  __resetMarkers,
+  __setMarkerDeps,
+  emitMarker,
+  emitMarkerOnce
+});
+//# sourceMappingURL=markers.cjs.map

package/dist/markers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/markers.ts"],"sourcesContent":["// Runtime emission of the boot `ir.*` markers (LOAD_PROFILING_SPEC §3/§3.2, R3-46).\n//\n// The host already MERGED the receive end: it validates a forwarded\n// `{ type:'ir-marker', name, at, attrs? }` against the LP-5 allowlist\n// (`irMarkers.ts`) and brackets request→interactive, treating an accepted\n// `ir.interactive` as the root-render-commit signal (site-main\n// `routePerfMessage`/`perfTimeline`). This module is the SANDBOX-side emitter for\n// the boot marks the SDK owns — `ir.fmp` (first meaningful paint) and\n// `ir.interactive` (root render commit) — forwarded over the same transport as\n// `reportReady()` (`ready.ts`). The per-marker timestamp is the sandbox-relative\n// `performance.now()` at emission (§3.2).\n//\n// Mirrors `ready.ts`'s dependency seam so the emission is unit-testable without a\n// host transport, and is idempotent per name so React StrictMode's double-invoke\n// (or any re-commit) can't mint a boot mark twice.\nimport { sendMessage as defaultSend } from './sandboxUtils';\nimport { isIrMarkerName, type IrMarkerName } from './irMarkers';\n\ninterface MarkerDeps {\n  send: (type: string, data?: Record<string, unknown>) => void;\n  now: () => number;\n}\n\nconst realNow = (): number =>\n  typeof performance !== 'undefined' && typeof performance.now === 'function'\n    ? performance.now()\n    : Date.now();\n\nconst defaultDeps: MarkerDeps = { send: defaultSend, now: realNow };\n\nlet deps: MarkerDeps = defaultDeps;\nconst emitted = new Set<string>();\n\n/**\n * Forward one `ir.*` marker to the host (`ir-marker`). The host re-validates against\n * the allowlist, so a bad name/attr is dropped there; we only emit names the SDK\n * itself owns. A transport that isn't ready yet is swallowed — a missing boot mark\n * must never break the app's boot.\n */\nexport function emitMarker(name: IrMarkerName, attrs?: Record<string, unknown>): void {\n  if (!isIrMarkerName(name)) return;\n  try {\n    deps.send('ir-marker', { name, at: deps.now(), ...(attrs !== undefined ? { attrs } : {}) });\n  } catch {\n    /* transport not ready — boot continues; the host simply lacks this mark */\n  }\n}\n\n/** Emit a boot one-shot at most once per name (idempotent across StrictMode/re-commit). */\nexport function emitMarkerOnce(name: IrMarkerName, attrs?: Record<string, unknown>): void {\n  if (emitted.has(name)) return;\n  emitted.add(name);\n  emitMarker(name, attrs);\n}\n\n/** Test seam: override the transport/clock. */\nexport function __setMarkerDeps(d: Partial<MarkerDeps>): void {\n  deps = { ...defaultDeps, ...d };\n}\n\n/** Test seam: reset module state (the once-guard + deps) between cases. */\nexport function __resetMarkers(): void {\n  deps = defaultDeps;\n  emitted.clear();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,0BAA2C;AAC3C,uBAAkD;AAOlD,MAAM,UAAU,MACd,OAAO,gBAAgB,eAAe,OAAO,YAAY,QAAQ,aAC7D,YAAY,IAAI,IAChB,KAAK,IAAI;AAEf,MAAM,cAA0B,EAAE,MAAM,oBAAAA,aAAa,KAAK,QAAQ;AAElE,IAAI,OAAmB;AACvB,MAAM,UAAU,oBAAI,IAAY;AAQzB,SAAS,WAAW,MAAoB,OAAuC;AACpF,MAAI,KAAC,iCAAe,IAAI,EAAG;AAC3B,MAAI;AACF,SAAK,KAAK,aAAa,EAAE,MAAM,IAAI,KAAK,IAAI,GAAG,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC,EAAG,CAAC;AAAA,EAC5F,QAAQ;AAAA,EAER;AACF;AAGO,SAAS,eAAe,MAAoB,OAAuC;AACxF,MAAI,QAAQ,IAAI,IAAI,EAAG;AACvB,UAAQ,IAAI,IAAI;AAChB,aAAW,MAAM,KAAK;AACxB;AAGO,SAAS,gBAAgB,GAA8B;AAC5D,SAAO,EAAE,GAAG,aAAa,GAAG,EAAE;AAChC;AAGO,SAAS,iBAAuB;AACrC,SAAO;AACP,UAAQ,MAAM;AAChB;","names":["defaultSend"]}

package/dist/markers.d.cts

@@ -0,0 +1,21 @@
+import { IrMarkerName } from './irMarkers.cjs';
+
+interface MarkerDeps {
+    send: (type: string, data?: Record<string, unknown>) => void;
+    now: () => number;
+}
+/**
+ * Forward one `ir.*` marker to the host (`ir-marker`). The host re-validates against
+ * the allowlist, so a bad name/attr is dropped there; we only emit names the SDK
+ * itself owns. A transport that isn't ready yet is swallowed — a missing boot mark
+ * must never break the app's boot.
+ */
+declare function emitMarker(name: IrMarkerName, attrs?: Record<string, unknown>): void;
+/** Emit a boot one-shot at most once per name (idempotent across StrictMode/re-commit). */
+declare function emitMarkerOnce(name: IrMarkerName, attrs?: Record<string, unknown>): void;
+/** Test seam: override the transport/clock. */
+declare function __setMarkerDeps(d: Partial<MarkerDeps>): void;
+/** Test seam: reset module state (the once-guard + deps) between cases. */
+declare function __resetMarkers(): void;
+
+export { __resetMarkers, __setMarkerDeps, emitMarker, emitMarkerOnce };

package/dist/markers.d.ts

@@ -0,0 +1,21 @@
+import { IrMarkerName } from './irMarkers.js';
+
+interface MarkerDeps {
+    send: (type: string, data?: Record<string, unknown>) => void;
+    now: () => number;
+}
+/**
+ * Forward one `ir.*` marker to the host (`ir-marker`). The host re-validates against
+ * the allowlist, so a bad name/attr is dropped there; we only emit names the SDK
+ * itself owns. A transport that isn't ready yet is swallowed — a missing boot mark
+ * must never break the app's boot.
+ */
+declare function emitMarker(name: IrMarkerName, attrs?: Record<string, unknown>): void;
+/** Emit a boot one-shot at most once per name (idempotent across StrictMode/re-commit). */
+declare function emitMarkerOnce(name: IrMarkerName, attrs?: Record<string, unknown>): void;
+/** Test seam: override the transport/clock. */
+declare function __setMarkerDeps(d: Partial<MarkerDeps>): void;
+/** Test seam: reset module state (the once-guard + deps) between cases. */
+declare function __resetMarkers(): void;
+
+export { __resetMarkers, __setMarkerDeps, emitMarker, emitMarkerOnce };

package/dist/markers.js

@@ -0,0 +1,32 @@
+import { sendMessage as defaultSend } from "./sandboxUtils";
+import { isIrMarkerName } from "./irMarkers";
+const realNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+const defaultDeps = { send: defaultSend, now: realNow };
+let deps = defaultDeps;
+const emitted = /* @__PURE__ */ new Set();
+function emitMarker(name, attrs) {
+  if (!isIrMarkerName(name)) return;
+  try {
+    deps.send("ir-marker", { name, at: deps.now(), ...attrs !== void 0 ? { attrs } : {} });
+  } catch {
+  }
+}
+function emitMarkerOnce(name, attrs) {
+  if (emitted.has(name)) return;
+  emitted.add(name);
+  emitMarker(name, attrs);
+}
+function __setMarkerDeps(d) {
+  deps = { ...defaultDeps, ...d };
+}
+function __resetMarkers() {
+  deps = defaultDeps;
+  emitted.clear();
+}
+export {
+  __resetMarkers,
+  __setMarkerDeps,
+  emitMarker,
+  emitMarkerOnce
+};
+//# sourceMappingURL=markers.js.map

package/dist/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/markers.ts"],"sourcesContent":["// Runtime emission of the boot `ir.*` markers (LOAD_PROFILING_SPEC §3/§3.2, R3-46).\n//\n// The host already MERGED the receive end: it validates a forwarded\n// `{ type:'ir-marker', name, at, attrs? }` against the LP-5 allowlist\n// (`irMarkers.ts`) and brackets request→interactive, treating an accepted\n// `ir.interactive` as the root-render-commit signal (site-main\n// `routePerfMessage`/`perfTimeline`). This module is the SANDBOX-side emitter for\n// the boot marks the SDK owns — `ir.fmp` (first meaningful paint) and\n// `ir.interactive` (root render commit) — forwarded over the same transport as\n// `reportReady()` (`ready.ts`). The per-marker timestamp is the sandbox-relative\n// `performance.now()` at emission (§3.2).\n//\n// Mirrors `ready.ts`'s dependency seam so the emission is unit-testable without a\n// host transport, and is idempotent per name so React StrictMode's double-invoke\n// (or any re-commit) can't mint a boot mark twice.\nimport { sendMessage as defaultSend } from './sandboxUtils';\nimport { isIrMarkerName, type IrMarkerName } from './irMarkers';\n\ninterface MarkerDeps {\n  send: (type: string, data?: Record<string, unknown>) => void;\n  now: () => number;\n}\n\nconst realNow = (): number =>\n  typeof performance !== 'undefined' && typeof performance.now === 'function'\n    ? performance.now()\n    : Date.now();\n\nconst defaultDeps: MarkerDeps = { send: defaultSend, now: realNow };\n\nlet deps: MarkerDeps = defaultDeps;\nconst emitted = new Set<string>();\n\n/**\n * Forward one `ir.*` marker to the host (`ir-marker`). The host re-validates against\n * the allowlist, so a bad name/attr is dropped there; we only emit names the SDK\n * itself owns. A transport that isn't ready yet is swallowed — a missing boot mark\n * must never break the app's boot.\n */\nexport function emitMarker(name: IrMarkerName, attrs?: Record<string, unknown>): void {\n  if (!isIrMarkerName(name)) return;\n  try {\n    deps.send('ir-marker', { name, at: deps.now(), ...(attrs !== undefined ? { attrs } : {}) });\n  } catch {\n    /* transport not ready — boot continues; the host simply lacks this mark */\n  }\n}\n\n/** Emit a boot one-shot at most once per name (idempotent across StrictMode/re-commit). */\nexport function emitMarkerOnce(name: IrMarkerName, attrs?: Record<string, unknown>): void {\n  if (emitted.has(name)) return;\n  emitted.add(name);\n  emitMarker(name, attrs);\n}\n\n/** Test seam: override the transport/clock. */\nexport function __setMarkerDeps(d: Partial<MarkerDeps>): void {\n  deps = { ...defaultDeps, ...d };\n}\n\n/** Test seam: reset module state (the once-guard + deps) between cases. */\nexport function __resetMarkers(): void {\n  deps = defaultDeps;\n  emitted.clear();\n}\n"],"mappings":"AAeA,SAAS,eAAe,mBAAmB;AAC3C,SAAS,sBAAyC;AAOlD,MAAM,UAAU,MACd,OAAO,gBAAgB,eAAe,OAAO,YAAY,QAAQ,aAC7D,YAAY,IAAI,IAChB,KAAK,IAAI;AAEf,MAAM,cAA0B,EAAE,MAAM,aAAa,KAAK,QAAQ;AAElE,IAAI,OAAmB;AACvB,MAAM,UAAU,oBAAI,IAAY;AAQzB,SAAS,WAAW,MAAoB,OAAuC;AACpF,MAAI,CAAC,eAAe,IAAI,EAAG;AAC3B,MAAI;AACF,SAAK,KAAK,aAAa,EAAE,MAAM,IAAI,KAAK,IAAI,GAAG,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC,EAAG,CAAC;AAAA,EAC5F,QAAQ;AAAA,EAER;AACF;AAGO,SAAS,eAAe,MAAoB,OAAuC;AACxF,MAAI,QAAQ,IAAI,IAAI,EAAG;AACvB,UAAQ,IAAI,IAAI;AAChB,aAAW,MAAM,KAAK;AACxB;AAGO,SAAS,gBAAgB,GAA8B;AAC5D,SAAO,EAAE,GAAG,aAAa,GAAG,EAAE;AAChC;AAGO,SAAS,iBAAuB;AACrC,SAAO;AACP,UAAQ,MAAM;AAChB;","names":[]}

package/dist/region.cjs

@@ -0,0 +1,47 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var region_exports = {};
+__export(region_exports, {
+  getRegion: () => getRegion,
+  useRegion: () => useRegion
+});
+module.exports = __toCommonJS(region_exports);
+var import_react = require("react");
+var import_hostRuntime = require("./hostRuntime");
+const getRegion = () => (0, import_hostRuntime.getHostRuntime)()?.region ?? null;
+const useRegion = () => {
+  const [region, setRegion] = (0, import_react.useState)(getRegion);
+  (0, import_react.useEffect)(() => {
+    if (region !== null) return;
+    let live = true;
+    void (0, import_hostRuntime.getHostRuntime)()?.ready?.then(() => {
+      if (live) setRegion(getRegion());
+    });
+    return () => {
+      live = false;
+    };
+  }, [region]);
+  return region;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getRegion,
+  useRegion
+});
+//# sourceMappingURL=region.cjs.map

package/dist/region.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/region.ts"],"sourcesContent":["// Region-awareness (UI_AS_APPS_SPEC §4.1). The host can mount the SAME app in more\n// than one chrome region — e.g. the agents activity puts one app in BOTH the panel\n// slot (`panel.agent`, the conversation list) and the stage slot\n// (`stage.conversation`, the selected conversation). `getRegion()` lets that one app\n// tell the slots apart and render the right view.\n//\n// This is descriptive only: the region id is a non-secret string the host already\n// knows. It grants nothing and gates nothing — it just names where the app is\n// mounted. The host reports it on the §4 discovery global beside `appMountPath`.\n\nimport { useEffect, useState } from 'react';\nimport { getHostRuntime } from './hostRuntime';\n\n/**\n * The chrome region this app instance is mounted in (e.g. `\"panel.agent\"`,\n * `\"stage.conversation\"`), or `null` when unknown — a standalone app, local\n * `vite dev`, or an older host that doesn't report it.\n */\nexport const getRegion = (): string | null => getHostRuntime()?.region ?? null;\n\n/**\n * React hook form of {@link getRegion}. The region is fixed for an app instance's\n * lifetime, but the discovery global can arrive just after first paint, so this\n * re-reads once the host runtime's `ready` promise resolves.\n */\nexport const useRegion = (): string | null => {\n  const [region, setRegion] = useState<string | null>(getRegion);\n  useEffect(() => {\n    if (region !== null) return;\n    let live = true;\n    void getHostRuntime()?.ready?.then(() => {\n      if (live) setRegion(getRegion());\n    });\n    return () => {\n      live = false;\n    };\n  }, [region]);\n  return region;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,mBAAoC;AACpC,yBAA+B;AAOxB,MAAM,YAAY,UAAqB,mCAAe,GAAG,UAAU;AAOnE,MAAM,YAAY,MAAqB;AAC5C,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAwB,SAAS;AAC7D,8BAAU,MAAM;AACd,QAAI,WAAW,KAAM;AACrB,QAAI,OAAO;AACX,aAAK,mCAAe,GAAG,OAAO,KAAK,MAAM;AACvC,UAAI,KAAM,WAAU,UAAU,CAAC;AAAA,IACjC,CAAC;AACD,WAAO,MAAM;AACX,aAAO;AAAA,IACT;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AACX,SAAO;AACT;","names":[]}

package/dist/region.d.cts

@@ -0,0 +1,14 @@
+/**
+ * The chrome region this app instance is mounted in (e.g. `"panel.agent"`,
+ * `"stage.conversation"`), or `null` when unknown — a standalone app, local
+ * `vite dev`, or an older host that doesn't report it.
+ */
+declare const getRegion: () => string | null;
+/**
+ * React hook form of {@link getRegion}. The region is fixed for an app instance's
+ * lifetime, but the discovery global can arrive just after first paint, so this
+ * re-reads once the host runtime's `ready` promise resolves.
+ */
+declare const useRegion: () => string | null;
+
+export { getRegion, useRegion };

package/dist/region.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The chrome region this app instance is mounted in (e.g. `"panel.agent"`,
+ * `"stage.conversation"`), or `null` when unknown — a standalone app, local
+ * `vite dev`, or an older host that doesn't report it.
+ */
+declare const getRegion: () => string | null;
+/**
+ * React hook form of {@link getRegion}. The region is fixed for an app instance's
+ * lifetime, but the discovery global can arrive just after first paint, so this
+ * re-reads once the host runtime's `ready` promise resolves.
+ */
+declare const useRegion: () => string | null;
+
+export { getRegion, useRegion };

package/dist/region.js

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+import { getHostRuntime } from "./hostRuntime";
+const getRegion = () => getHostRuntime()?.region ?? null;
+const useRegion = () => {
+  const [region, setRegion] = useState(getRegion);
+  useEffect(() => {
+    if (region !== null) return;
+    let live = true;
+    void getHostRuntime()?.ready?.then(() => {
+      if (live) setRegion(getRegion());
+    });
+    return () => {
+      live = false;
+    };
+  }, [region]);
+  return region;
+};
+export {
+  getRegion,
+  useRegion
+};
+//# sourceMappingURL=region.js.map

package/dist/region.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/region.ts"],"sourcesContent":["// Region-awareness (UI_AS_APPS_SPEC §4.1). The host can mount the SAME app in more\n// than one chrome region — e.g. the agents activity puts one app in BOTH the panel\n// slot (`panel.agent`, the conversation list) and the stage slot\n// (`stage.conversation`, the selected conversation). `getRegion()` lets that one app\n// tell the slots apart and render the right view.\n//\n// This is descriptive only: the region id is a non-secret string the host already\n// knows. It grants nothing and gates nothing — it just names where the app is\n// mounted. The host reports it on the §4 discovery global beside `appMountPath`.\n\nimport { useEffect, useState } from 'react';\nimport { getHostRuntime } from './hostRuntime';\n\n/**\n * The chrome region this app instance is mounted in (e.g. `\"panel.agent\"`,\n * `\"stage.conversation\"`), or `null` when unknown — a standalone app, local\n * `vite dev`, or an older host that doesn't report it.\n */\nexport const getRegion = (): string | null => getHostRuntime()?.region ?? null;\n\n/**\n * React hook form of {@link getRegion}. The region is fixed for an app instance's\n * lifetime, but the discovery global can arrive just after first paint, so this\n * re-reads once the host runtime's `ready` promise resolves.\n */\nexport const useRegion = (): string | null => {\n  const [region, setRegion] = useState<string | null>(getRegion);\n  useEffect(() => {\n    if (region !== null) return;\n    let live = true;\n    void getHostRuntime()?.ready?.then(() => {\n      if (live) setRegion(getRegion());\n    });\n    return () => {\n      live = false;\n    };\n  }, [region]);\n  return region;\n};\n"],"mappings":"AAUA,SAAS,WAAW,gBAAgB;AACpC,SAAS,sBAAsB;AAOxB,MAAM,YAAY,MAAqB,eAAe,GAAG,UAAU;AAOnE,MAAM,YAAY,MAAqB;AAC5C,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAwB,SAAS;AAC7D,YAAU,MAAM;AACd,QAAI,WAAW,KAAM;AACrB,QAAI,OAAO;AACX,SAAK,eAAe,GAAG,OAAO,KAAK,MAAM;AACvC,UAAI,KAAM,WAAU,UAAU,CAAC;AAAA,IACjC,CAAC;AACD,WAAO,MAAM;AACX,aAAO;AAAA,IACT;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AACX,SAAO;AACT;","names":[]}

package/dist/testing.cjs

@@ -0,0 +1,74 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var testing_exports = {};
+__export(testing_exports, {
+  createMockHost: () => createMockHost
+});
+module.exports = __toCommonJS(testing_exports);
+const GLOBAL_KEY = "__immediatelyRun__";
+function createMockHost() {
+  const handlers = /* @__PURE__ */ new Set();
+  const sent = [];
+  const protocolCalls = [];
+  const responders = /* @__PURE__ */ new Map();
+  const key = (protocol, method) => `${protocol}::${method}`;
+  const transport = {
+    sendMessage(type, data = {}) {
+      sent.push({ type, data });
+    },
+    protocolRequest(protocol, method, params) {
+      protocolCalls.push({ protocol, method, params });
+      const responder = responders.get(key(protocol, method));
+      if (!responder) {
+        return Promise.reject(
+          new Error(`mockHost: no stub for protocolRequest('${protocol}', '${method}')`)
+        );
+      }
+      return Promise.resolve().then(() => responder(params));
+    },
+    onMessage(handler) {
+      handlers.add(handler);
+      return { dispose: () => handlers.delete(handler) };
+    }
+  };
+  const g = globalThis;
+  return {
+    transport,
+    install(extras = {}) {
+      g[GLOBAL_KEY] = { ...extras, transport };
+    },
+    uninstall() {
+      delete g[GLOBAL_KEY];
+    },
+    emit(msg) {
+      for (const handler of [...handlers]) handler(msg);
+    },
+    stubProtocol(protocol, method, responder) {
+      responders.set(key(protocol, method), responder);
+    },
+    sent,
+    protocolCalls,
+    handlerCount: () => handlers.size
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createMockHost
+});
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["// Public testing utility — `@immediately-run/sdk/testing` (TESTING_AUTOMATION_SPEC\n// §3/§7). A mock host transport so apps built on this SDK can unit-test their host\n// interaction in CI, with no live bundler/host: drive the SDK's REAL transport path\n// by installing this at the §4 discovery global, then `emit()` host→app pushes and\n// assert your app reacts.\n//\n//   import { createMockHost } from '@immediately-run/sdk/testing';\n//   const host = createMockHost();\n//   host.install();                       // SDK now resolves this transport\n//   host.stubProtocol('spaces', 'list', () => ({ ok: true, data: [] }));\n//   // …render your app / call SDK functions…\n//   host.emit({ type: 'mount-add', mount: { path: '/spaces/a', type: 'firestore', id: 'a' } });\n//   expect(host.sent).toContainEqual({ type: 'request-mounts', data: {} });\n//   host.uninstall();\n//\n// It implements the `sandboxUtils` host transport (sendMessage / protocolRequest /\n// onMessage), so tests exercise the actual `transport()` resolution, the\n// `addListener` type-filter, and `protocolRequest` round-trips — higher fidelity\n// than mocking `./sandboxUtils` wholesale.\n\n/** A message pushed host → app, as it arrives on `onMessage`. */\nexport interface HostMessage {\n  type: string;\n  [k: string]: unknown;\n}\n\n/** An outbound `sendMessage` captured by the mock. */\nexport interface SentMessage {\n  type: string;\n  data: Record<string, unknown>;\n}\n\n/** An outbound `protocolRequest` captured by the mock. */\nexport interface ProtocolCall {\n  protocol: string;\n  method: string;\n  params: unknown[];\n}\n\n/** Responder stub for a `protocolRequest(protocol, method, …)`. */\nexport type ProtocolResponder = (params: unknown[]) => unknown;\n\n/** Extra §4 discovery-global fields to publish alongside `transport` on install. */\nexport interface MockHostGlobalExtras {\n  runtimeVersion?: string;\n  protocolVersion?: string;\n  appMountPath?: string;\n}\n\ninterface ImmediatelyRunGlobal extends MockHostGlobalExtras {\n  transport?: unknown;\n}\n\n/** The controllable mock host returned by {@link createMockHost}. */\nexport interface MockHost {\n  /** The §4 host transport object (also published on the global by `install`). */\n  transport: {\n    sendMessage(type: string, data?: Record<string, unknown>): void;\n    protocolRequest(protocol: string, method: string, params: unknown[]): Promise<unknown>;\n    onMessage(handler: (msg: HostMessage) => void): { dispose(): void };\n  };\n  /** Publish the transport at `globalThis.__immediatelyRun__` (npm-fetched path). */\n  install(extras?: MockHostGlobalExtras): void;\n  /** Remove the discovery global (call in `afterEach`). */\n  uninstall(): void;\n  /** Simulate a host → app push; delivered to every live `onMessage` handler. */\n  emit(msg: HostMessage): void;\n  /** Register a response for a `protocolRequest`; unstubbed calls reject. */\n  stubProtocol(protocol: string, method: string, responder: ProtocolResponder): void;\n  /** Every `sendMessage` the SDK made, in order. */\n  readonly sent: SentMessage[];\n  /** Every `protocolRequest` the SDK made, in order. */\n  readonly protocolCalls: ProtocolCall[];\n  /** Count of live `onMessage` listeners (leak checks). */\n  handlerCount(): number;\n}\n\nconst GLOBAL_KEY = '__immediatelyRun__';\n\n/** Build a controllable mock host. Nothing is global until you call `install()`. */\nexport function createMockHost(): MockHost {\n  const handlers = new Set<(msg: HostMessage) => void>();\n  const sent: SentMessage[] = [];\n  const protocolCalls: ProtocolCall[] = [];\n  const responders = new Map<string, ProtocolResponder>();\n  const key = (protocol: string, method: string) => `${protocol}::${method}`;\n\n  const transport: MockHost['transport'] = {\n    sendMessage(type, data = {}) {\n      sent.push({ type, data });\n    },\n    protocolRequest(protocol, method, params) {\n      protocolCalls.push({ protocol, method, params });\n      const responder = responders.get(key(protocol, method));\n      if (!responder) {\n        return Promise.reject(\n          new Error(`mockHost: no stub for protocolRequest('${protocol}', '${method}')`),\n        );\n      }\n      // Resolve async so callers observe real microtask ordering.\n      return Promise.resolve().then(() => responder(params));\n    },\n    onMessage(handler) {\n      handlers.add(handler);\n      return { dispose: () => handlers.delete(handler) };\n    },\n  };\n\n  const g = globalThis as { [GLOBAL_KEY]?: ImmediatelyRunGlobal };\n\n  return {\n    transport,\n    install(extras = {}) {\n      g[GLOBAL_KEY] = { ...extras, transport };\n    },\n    uninstall() {\n      delete g[GLOBAL_KEY];\n    },\n    emit(msg) {\n      // Copy so a handler that unsubscribes mid-emit doesn't mutate the live set.\n      for (const handler of [...handlers]) handler(msg);\n    },\n    stubProtocol(protocol, method, responder) {\n      responders.set(key(protocol, method), responder);\n    },\n    sent,\n    protocolCalls,\n    handlerCount: () => handlers.size,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA6EA,MAAM,aAAa;AAGZ,SAAS,iBAA2B;AACzC,QAAM,WAAW,oBAAI,IAAgC;AACrD,QAAM,OAAsB,CAAC;AAC7B,QAAM,gBAAgC,CAAC;AACvC,QAAM,aAAa,oBAAI,IAA+B;AACtD,QAAM,MAAM,CAAC,UAAkB,WAAmB,GAAG,QAAQ,KAAK,MAAM;AAExE,QAAM,YAAmC;AAAA,IACvC,YAAY,MAAM,OAAO,CAAC,GAAG;AAC3B,WAAK,KAAK,EAAE,MAAM,KAAK,CAAC;AAAA,IAC1B;AAAA,IACA,gBAAgB,UAAU,QAAQ,QAAQ;AACxC,oBAAc,KAAK,EAAE,UAAU,QAAQ,OAAO,CAAC;AAC/C,YAAM,YAAY,WAAW,IAAI,IAAI,UAAU,MAAM,CAAC;AACtD,UAAI,CAAC,WAAW;AACd,eAAO,QAAQ;AAAA,UACb,IAAI,MAAM,0CAA0C,QAAQ,OAAO,MAAM,IAAI;AAAA,QAC/E;AAAA,MACF;AAEA,aAAO,QAAQ,QAAQ,EAAE,KAAK,MAAM,UAAU,MAAM,CAAC;AAAA,IACvD;AAAA,IACA,UAAU,SAAS;AACjB,eAAS,IAAI,OAAO;AACpB,aAAO,EAAE,SAAS,MAAM,SAAS,OAAO,OAAO,EAAE;AAAA,IACnD;AAAA,EACF;AAEA,QAAM,IAAI;AAEV,SAAO;AAAA,IACL;AAAA,IACA,QAAQ,SAAS,CAAC,GAAG;AACnB,QAAE,UAAU,IAAI,EAAE,GAAG,QAAQ,UAAU;AAAA,IACzC;AAAA,IACA,YAAY;AACV,aAAO,EAAE,UAAU;AAAA,IACrB;AAAA,IACA,KAAK,KAAK;AAER,iBAAW,WAAW,CAAC,GAAG,QAAQ,EAAG,SAAQ,GAAG;AAAA,IAClD;AAAA,IACA,aAAa,UAAU,QAAQ,WAAW;AACxC,iBAAW,IAAI,IAAI,UAAU,MAAM,GAAG,SAAS;AAAA,IACjD;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc,MAAM,SAAS;AAAA,EAC/B;AACF;","names":[]}

package/dist/testing.d.cts

@@ -0,0 +1,53 @@
+/** A message pushed host → app, as it arrives on `onMessage`. */
+interface HostMessage {
+    type: string;
+    [k: string]: unknown;
+}
+/** An outbound `sendMessage` captured by the mock. */
+interface SentMessage {
+    type: string;
+    data: Record<string, unknown>;
+}
+/** An outbound `protocolRequest` captured by the mock. */
+interface ProtocolCall {
+    protocol: string;
+    method: string;
+    params: unknown[];
+}
+/** Responder stub for a `protocolRequest(protocol, method, …)`. */
+type ProtocolResponder = (params: unknown[]) => unknown;
+/** Extra §4 discovery-global fields to publish alongside `transport` on install. */
+interface MockHostGlobalExtras {
+    runtimeVersion?: string;
+    protocolVersion?: string;
+    appMountPath?: string;
+}
+/** The controllable mock host returned by {@link createMockHost}. */
+interface MockHost {
+    /** The §4 host transport object (also published on the global by `install`). */
+    transport: {
+        sendMessage(type: string, data?: Record<string, unknown>): void;
+        protocolRequest(protocol: string, method: string, params: unknown[]): Promise<unknown>;
+        onMessage(handler: (msg: HostMessage) => void): {
+            dispose(): void;
+        };
+    };
+    /** Publish the transport at `globalThis.__immediatelyRun__` (npm-fetched path). */
+    install(extras?: MockHostGlobalExtras): void;
+    /** Remove the discovery global (call in `afterEach`). */
+    uninstall(): void;
+    /** Simulate a host → app push; delivered to every live `onMessage` handler. */
+    emit(msg: HostMessage): void;
+    /** Register a response for a `protocolRequest`; unstubbed calls reject. */
+    stubProtocol(protocol: string, method: string, responder: ProtocolResponder): void;
+    /** Every `sendMessage` the SDK made, in order. */
+    readonly sent: SentMessage[];
+    /** Every `protocolRequest` the SDK made, in order. */
+    readonly protocolCalls: ProtocolCall[];
+    /** Count of live `onMessage` listeners (leak checks). */
+    handlerCount(): number;
+}
+/** Build a controllable mock host. Nothing is global until you call `install()`. */
+declare function createMockHost(): MockHost;
+
+export { type HostMessage, type MockHost, type MockHostGlobalExtras, type ProtocolCall, type ProtocolResponder, type SentMessage, createMockHost };

package/dist/testing.d.ts

@@ -0,0 +1,53 @@
+/** A message pushed host → app, as it arrives on `onMessage`. */
+interface HostMessage {
+    type: string;
+    [k: string]: unknown;
+}
+/** An outbound `sendMessage` captured by the mock. */
+interface SentMessage {
+    type: string;
+    data: Record<string, unknown>;
+}
+/** An outbound `protocolRequest` captured by the mock. */
+interface ProtocolCall {
+    protocol: string;
+    method: string;
+    params: unknown[];
+}
+/** Responder stub for a `protocolRequest(protocol, method, …)`. */
+type ProtocolResponder = (params: unknown[]) => unknown;
+/** Extra §4 discovery-global fields to publish alongside `transport` on install. */
+interface MockHostGlobalExtras {
+    runtimeVersion?: string;
+    protocolVersion?: string;
+    appMountPath?: string;
+}
+/** The controllable mock host returned by {@link createMockHost}. */
+interface MockHost {
+    /** The §4 host transport object (also published on the global by `install`). */
+    transport: {
+        sendMessage(type: string, data?: Record<string, unknown>): void;
+        protocolRequest(protocol: string, method: string, params: unknown[]): Promise<unknown>;
+        onMessage(handler: (msg: HostMessage) => void): {
+            dispose(): void;
+        };
+    };
+    /** Publish the transport at `globalThis.__immediatelyRun__` (npm-fetched path). */
+    install(extras?: MockHostGlobalExtras): void;
+    /** Remove the discovery global (call in `afterEach`). */
+    uninstall(): void;
+    /** Simulate a host → app push; delivered to every live `onMessage` handler. */
+    emit(msg: HostMessage): void;
+    /** Register a response for a `protocolRequest`; unstubbed calls reject. */
+    stubProtocol(protocol: string, method: string, responder: ProtocolResponder): void;
+    /** Every `sendMessage` the SDK made, in order. */
+    readonly sent: SentMessage[];
+    /** Every `protocolRequest` the SDK made, in order. */
+    readonly protocolCalls: ProtocolCall[];
+    /** Count of live `onMessage` listeners (leak checks). */
+    handlerCount(): number;
+}
+/** Build a controllable mock host. Nothing is global until you call `install()`. */
+declare function createMockHost(): MockHost;
+
+export { type HostMessage, type MockHost, type MockHostGlobalExtras, type ProtocolCall, type ProtocolResponder, type SentMessage, createMockHost };

package/dist/testing.js

@@ -0,0 +1,50 @@
+const GLOBAL_KEY = "__immediatelyRun__";
+function createMockHost() {
+  const handlers = /* @__PURE__ */ new Set();
+  const sent = [];
+  const protocolCalls = [];
+  const responders = /* @__PURE__ */ new Map();
+  const key = (protocol, method) => `${protocol}::${method}`;
+  const transport = {
+    sendMessage(type, data = {}) {
+      sent.push({ type, data });
+    },
+    protocolRequest(protocol, method, params) {
+      protocolCalls.push({ protocol, method, params });
+      const responder = responders.get(key(protocol, method));
+      if (!responder) {
+        return Promise.reject(
+          new Error(`mockHost: no stub for protocolRequest('${protocol}', '${method}')`)
+        );
+      }
+      return Promise.resolve().then(() => responder(params));
+    },
+    onMessage(handler) {
+      handlers.add(handler);
+      return { dispose: () => handlers.delete(handler) };
+    }
+  };
+  const g = globalThis;
+  return {
+    transport,
+    install(extras = {}) {
+      g[GLOBAL_KEY] = { ...extras, transport };
+    },
+    uninstall() {
+      delete g[GLOBAL_KEY];
+    },
+    emit(msg) {
+      for (const handler of [...handlers]) handler(msg);
+    },
+    stubProtocol(protocol, method, responder) {
+      responders.set(key(protocol, method), responder);
+    },
+    sent,
+    protocolCalls,
+    handlerCount: () => handlers.size
+  };
+}
+export {
+  createMockHost
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["// Public testing utility — `@immediately-run/sdk/testing` (TESTING_AUTOMATION_SPEC\n// §3/§7). A mock host transport so apps built on this SDK can unit-test their host\n// interaction in CI, with no live bundler/host: drive the SDK's REAL transport path\n// by installing this at the §4 discovery global, then `emit()` host→app pushes and\n// assert your app reacts.\n//\n//   import { createMockHost } from '@immediately-run/sdk/testing';\n//   const host = createMockHost();\n//   host.install();                       // SDK now resolves this transport\n//   host.stubProtocol('spaces', 'list', () => ({ ok: true, data: [] }));\n//   // …render your app / call SDK functions…\n//   host.emit({ type: 'mount-add', mount: { path: '/spaces/a', type: 'firestore', id: 'a' } });\n//   expect(host.sent).toContainEqual({ type: 'request-mounts', data: {} });\n//   host.uninstall();\n//\n// It implements the `sandboxUtils` host transport (sendMessage / protocolRequest /\n// onMessage), so tests exercise the actual `transport()` resolution, the\n// `addListener` type-filter, and `protocolRequest` round-trips — higher fidelity\n// than mocking `./sandboxUtils` wholesale.\n\n/** A message pushed host → app, as it arrives on `onMessage`. */\nexport interface HostMessage {\n  type: string;\n  [k: string]: unknown;\n}\n\n/** An outbound `sendMessage` captured by the mock. */\nexport interface SentMessage {\n  type: string;\n  data: Record<string, unknown>;\n}\n\n/** An outbound `protocolRequest` captured by the mock. */\nexport interface ProtocolCall {\n  protocol: string;\n  method: string;\n  params: unknown[];\n}\n\n/** Responder stub for a `protocolRequest(protocol, method, …)`. */\nexport type ProtocolResponder = (params: unknown[]) => unknown;\n\n/** Extra §4 discovery-global fields to publish alongside `transport` on install. */\nexport interface MockHostGlobalExtras {\n  runtimeVersion?: string;\n  protocolVersion?: string;\n  appMountPath?: string;\n}\n\ninterface ImmediatelyRunGlobal extends MockHostGlobalExtras {\n  transport?: unknown;\n}\n\n/** The controllable mock host returned by {@link createMockHost}. */\nexport interface MockHost {\n  /** The §4 host transport object (also published on the global by `install`). */\n  transport: {\n    sendMessage(type: string, data?: Record<string, unknown>): void;\n    protocolRequest(protocol: string, method: string, params: unknown[]): Promise<unknown>;\n    onMessage(handler: (msg: HostMessage) => void): { dispose(): void };\n  };\n  /** Publish the transport at `globalThis.__immediatelyRun__` (npm-fetched path). */\n  install(extras?: MockHostGlobalExtras): void;\n  /** Remove the discovery global (call in `afterEach`). */\n  uninstall(): void;\n  /** Simulate a host → app push; delivered to every live `onMessage` handler. */\n  emit(msg: HostMessage): void;\n  /** Register a response for a `protocolRequest`; unstubbed calls reject. */\n  stubProtocol(protocol: string, method: string, responder: ProtocolResponder): void;\n  /** Every `sendMessage` the SDK made, in order. */\n  readonly sent: SentMessage[];\n  /** Every `protocolRequest` the SDK made, in order. */\n  readonly protocolCalls: ProtocolCall[];\n  /** Count of live `onMessage` listeners (leak checks). */\n  handlerCount(): number;\n}\n\nconst GLOBAL_KEY = '__immediatelyRun__';\n\n/** Build a controllable mock host. Nothing is global until you call `install()`. */\nexport function createMockHost(): MockHost {\n  const handlers = new Set<(msg: HostMessage) => void>();\n  const sent: SentMessage[] = [];\n  const protocolCalls: ProtocolCall[] = [];\n  const responders = new Map<string, ProtocolResponder>();\n  const key = (protocol: string, method: string) => `${protocol}::${method}`;\n\n  const transport: MockHost['transport'] = {\n    sendMessage(type, data = {}) {\n      sent.push({ type, data });\n    },\n    protocolRequest(protocol, method, params) {\n      protocolCalls.push({ protocol, method, params });\n      const responder = responders.get(key(protocol, method));\n      if (!responder) {\n        return Promise.reject(\n          new Error(`mockHost: no stub for protocolRequest('${protocol}', '${method}')`),\n        );\n      }\n      // Resolve async so callers observe real microtask ordering.\n      return Promise.resolve().then(() => responder(params));\n    },\n    onMessage(handler) {\n      handlers.add(handler);\n      return { dispose: () => handlers.delete(handler) };\n    },\n  };\n\n  const g = globalThis as { [GLOBAL_KEY]?: ImmediatelyRunGlobal };\n\n  return {\n    transport,\n    install(extras = {}) {\n      g[GLOBAL_KEY] = { ...extras, transport };\n    },\n    uninstall() {\n      delete g[GLOBAL_KEY];\n    },\n    emit(msg) {\n      // Copy so a handler that unsubscribes mid-emit doesn't mutate the live set.\n      for (const handler of [...handlers]) handler(msg);\n    },\n    stubProtocol(protocol, method, responder) {\n      responders.set(key(protocol, method), responder);\n    },\n    sent,\n    protocolCalls,\n    handlerCount: () => handlers.size,\n  };\n}\n"],"mappings":"AA6EA,MAAM,aAAa;AAGZ,SAAS,iBAA2B;AACzC,QAAM,WAAW,oBAAI,IAAgC;AACrD,QAAM,OAAsB,CAAC;AAC7B,QAAM,gBAAgC,CAAC;AACvC,QAAM,aAAa,oBAAI,IAA+B;AACtD,QAAM,MAAM,CAAC,UAAkB,WAAmB,GAAG,QAAQ,KAAK,MAAM;AAExE,QAAM,YAAmC;AAAA,IACvC,YAAY,MAAM,OAAO,CAAC,GAAG;AAC3B,WAAK,KAAK,EAAE,MAAM,KAAK,CAAC;AAAA,IAC1B;AAAA,IACA,gBAAgB,UAAU,QAAQ,QAAQ;AACxC,oBAAc,KAAK,EAAE,UAAU,QAAQ,OAAO,CAAC;AAC/C,YAAM,YAAY,WAAW,IAAI,IAAI,UAAU,MAAM,CAAC;AACtD,UAAI,CAAC,WAAW;AACd,eAAO,QAAQ;AAAA,UACb,IAAI,MAAM,0CAA0C,QAAQ,OAAO,MAAM,IAAI;AAAA,QAC/E;AAAA,MACF;AAEA,aAAO,QAAQ,QAAQ,EAAE,KAAK,MAAM,UAAU,MAAM,CAAC;AAAA,IACvD;AAAA,IACA,UAAU,SAAS;AACjB,eAAS,IAAI,OAAO;AACpB,aAAO,EAAE,SAAS,MAAM,SAAS,OAAO,OAAO,EAAE;AAAA,IACnD;AAAA,EACF;AAEA,QAAM,IAAI;AAEV,SAAO;AAAA,IACL;AAAA,IACA,QAAQ,SAAS,CAAC,GAAG;AACnB,QAAE,UAAU,IAAI,EAAE,GAAG,QAAQ,UAAU;AAAA,IACzC;AAAA,IACA,YAAY;AACV,aAAO,EAAE,UAAU;AAAA,IACrB;AAAA,IACA,KAAK,KAAK;AAER,iBAAW,WAAW,CAAC,GAAG,QAAQ,EAAG,SAAQ,GAAG;AAAA,IAClD;AAAA,IACA,aAAa,UAAU,QAAQ,WAAW;AACxC,iBAAW,IAAI,IAAI,UAAU,MAAM,GAAG,SAAS;AAAA,IACjD;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc,MAAM,SAAS;AAAA,EAC/B;AACF;","names":[]}

package/dist/version.cjs

@@ -21,7 +21,7 @@ __export(version_exports, {
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const SDK_VERSION = "0.11.0";
+const SDK_VERSION = "0.12.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.11.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.12.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.11.0";
+declare const SDK_VERSION = "0.12.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.11.0";
+declare const SDK_VERSION = "0.12.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,4 +1,4 @@
-const SDK_VERSION = "0.11.0";
+const SDK_VERSION = "0.12.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.11.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.12.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",