@immediately-run/sdk 0.8.1 → 0.9.0

package/dist/boot.cjs

@@ -31,6 +31,7 @@ var import_FileRouter = require("./components/FileRouter");
 var import_MainContent = require("./components/MainContent");
 var import_MDXComponents = require("./components/MDXComponents");
 var import_contextUtils = require("./contextUtils");
+var import_injectedBundler = require("./injectedBundler");
 var import_MDXProvider = require("./MDXProvider");
 var import_moduleCache = require("./moduleCache");
 var import_routing = require("./routing");
@@ -62,6 +63,7 @@ const TinkerableApp = ({ routingSpec }) => {
     return removeListener;
   }, [setContext]);
   (0, import_react.useEffect)(() => {
+    const source = (0, import_injectedBundler.resolveMetadataSource)((0, import_injectedBundler.getInjectedMetadataEmitter)());
     const dispose = (0, import_sandboxUtils.addListener)(
       "metadata-update",
       ({ update }) => {
@@ -76,10 +78,9 @@ const TinkerableApp = ({ routingSpec }) => {
           }
         );
       },
-      // @ts-ignore
-      module.evaluation.module.bundler.onMetadataChange
+      source.event
     );
-    module.evaluation.module.bundler.onMetadataChangeEmitter.enable();
+    source.enable();
     return dispose;
   }, [setContext]);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_TinkerableContext.TinkerableContext, { value: context, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_routing.Router, {}) });

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 { 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    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      // @ts-ignore\n      module.evaluation.module.bundler.onMetadataChange\n    );\n    // @ts-ignore\n    module.evaluation.module.bundler.onMetadataChangeEmitter.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;AA0EM;AA1EN,mBAAoD;AACpD,oBAA2B;AAE3B,oBAA8B;AAC9B,wBAA2B;AAC3B,yBAA4B;AAC5B,2BAAuC;AACvC,0BAAiD;AACjD,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;AACd,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;AAAA,MAEA,OAAO,WAAW,OAAO,QAAQ;AAAA,IACnC;AAEA,WAAO,WAAW,OAAO,QAAQ,wBAAwB,OAAO;AAChE,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, 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"]}

package/dist/boot.js

@@ -6,6 +6,7 @@ import { FileRouter } from "./components/FileRouter";
 import { MainContent } from "./components/MainContent";
 import { DEFAULT_MDX_COMPONENTS } from "./components/MDXComponents";
 import { getInitialContext, updateContext } from "./contextUtils";
+import { getInjectedMetadataEmitter, resolveMetadataSource } from "./injectedBundler";
 import { MDXProvider } from "./MDXProvider";
 import { ModuleCache, ModuleCacheContextProvider } from "./moduleCache";
 import { Router } from "./routing";
@@ -37,6 +38,7 @@ const TinkerableApp = ({ routingSpec }) => {
     return removeListener;
   }, [setContext]);
   useEffect(() => {
+    const source = resolveMetadataSource(getInjectedMetadataEmitter());
     const dispose = addListener(
       "metadata-update",
       ({ update }) => {
@@ -51,10 +53,9 @@ const TinkerableApp = ({ routingSpec }) => {
           }
         );
       },
-      // @ts-ignore
-      module.evaluation.module.bundler.onMetadataChange
+      source.event
     );
-    module.evaluation.module.bundler.onMetadataChangeEmitter.enable();
+    source.enable();
     return dispose;
   }, [setContext]);
   return /* @__PURE__ */ jsx(TinkerableContext, { value: context, children: /* @__PURE__ */ jsx(Router, {}) });

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 { 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    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      // @ts-ignore\n      module.evaluation.module.bundler.onMetadataChange\n    );\n    // @ts-ignore\n    module.evaluation.module.bundler.onMetadataChangeEmitter.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":"AA0EM;AA1EN,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,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;AACd,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;AAAA,MAEA,OAAO,WAAW,OAAO,QAAQ;AAAA,IACnC;AAEA,WAAO,WAAW,OAAO,QAAQ,wBAAwB,OAAO;AAChE,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, 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"]}

package/dist/editor.cjs

@@ -18,11 +18,14 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var editor_exports = {};
 __export(editor_exports, {
+  closeFile: () => closeFile,
   createFile: () => createFile,
   createFolder: () => createFolder,
   deleteEntry: () => deleteEntry,
   openInEditor: () => openInEditor,
   renameEntry: () => renameEntry,
+  requestEdit: () => requestEdit,
+  setActiveFile: () => setActiveFile,
   uploadFile: () => uploadFile
 });
 module.exports = __toCommonJS(editor_exports);
@@ -36,6 +39,9 @@ const editorRequest = async (method, arg) => {
   }
 };
 const openInEditor = (path) => editorRequest("open", { path });
+const requestEdit = (target) => editorRequest("requestEdit", target ? { ...target } : {});
+const setActiveFile = (path) => editorRequest("setActive", { path });
+const closeFile = (path) => editorRequest("close", { path });
 const createFile = (path) => editorRequest("createFile", { path });
 const createFolder = (path) => editorRequest("createFolder", { path });
 const deleteEntry = (path) => editorRequest("deleteEntry", { path });
@@ -43,11 +49,14 @@ const renameEntry = (from, to) => editorRequest("rename", { from, to });
 const uploadFile = (path, bytes) => editorRequest("upload", { path, bytes });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  closeFile,
   createFile,
   createFolder,
   deleteEntry,
   openInEditor,
   renameEntry,
+  requestEdit,
+  setActiveFile,
   uploadFile
 });
 //# sourceMappingURL=editor.cjs.map

package/dist/editor.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAgC;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,UAAM,qCAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyBpF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}
+{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n/**\n * Where to land when entering the edit experience (EDITOR_FIRST_EDITING_SPEC §6\n * Delta A). v1 supports only an optional repo-relative `path` in the CURRENT repo\n * (self-scoped — the app you are already running; the host navigates within the\n * current route, never to another repo). A URI or `..` path is refused\n * `invalid-params`. Editing a file in one of your *mounts* (a space) is the\n * `edit-file` task, not this.\n */\nexport interface EditTarget {\n  /** A repo-relative working-tree path in the current repo to focus once in edit\n   *  mode (e.g. `src/App.tsx`). Omit to edit the current route's entry. */\n  path?: string;\n}\n\n/** An error from {@link requestEdit}, carrying a machine-readable `.code`. */\nexport interface RequestEditError extends Error {\n  code:\n    | 'read-only' // editing isn't possible here (a `ro` mount / anonymous viewer) — HIDE the affordance\n    | 'forbidden' // the host refuses (e.g. a cross-repo / out-of-scope target)\n    | 'invalid-params' // the target was malformed (URI / `..` / a non-current repo)\n    | 'no-target' // there is no host editor session to enter\n    | 'unknown';\n}\n\n/**\n * Ask the host to enter the **edit experience** for the app you are running —\n * the present→edit transition (`/present/...` → `/edit/...`) an app cannot make\n * itself. This is an INTENT (§2 recursion boundary): the app asks, the HOST\n * performs the visible, user-observable navigation and draws all editor chrome;\n * the app never navigates or paints chrome.\n *\n * Use it to offer an \"edit this\" affordance from a run/present-mode app that opens\n * the app's own source in the platform editor — instead of shipping a bespoke\n * in-app editor (EDITOR_FIRST_EDITING_SPEC §1).\n *\n * Resolves once the host begins the transition; rejects with a\n * {@link RequestEditError} (`.code`). Treat `read-only`/`forbidden` as \"editing is\n * not available — hide the affordance,\" never as an error to surface to the user.\n */\nexport const requestEdit = (target?: EditTarget): Promise<void> =>\n  editorRequest('requestEdit', target ? { ...target } : {});\n\n// ---------------------------------------------------------------------------\n// Editor SESSION management (EDITOR_AS_APP_SPEC §5.1; editor-as-app plan Phase\n// 03). Unlike `openInEditor` (the explorer's cross-app intent, `editor:open`),\n// these drive the editor's OWN open-tab set + active file, so they are gated by\n// the editor app's `editor:document` capability — a file explorer holding only\n// `editor:open` cannot call them. The host re-validates the path against the live\n// working tree; the editor itself stays host-owned (§2 recursion boundary).\n// ---------------------------------------------------------------------------\n\n/** An error from a session intent ({@link setActiveFile} / {@link closeFile}),\n *  carrying a machine-readable `.code`. */\nexport interface EditorSessionError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:document`\n    | 'not-found' // no such file in the live working tree\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Switch the editor's active file to `path`, opening it (adding a tab) if it is\n *  not already open — native `setActiveFile` parity. Rejects with an\n *  {@link EditorSessionError} (`.code`) if the path is missing/invalid or this app\n *  lacks `editor:document`. */\nexport const setActiveFile = (path: string): Promise<void> =>\n  editorRequest('setActive', { path });\n\n/** Close `path`'s tab in the editor (remove it from the open set) — native\n *  `closeFile` parity. Rejects with an {@link EditorSessionError} (`.code`). */\nexport const closeFile = (path: string): Promise<void> => editorRequest('close', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAgC;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,UAAM,qCAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyCpF,MAAM,cAAc,CAAC,WAC1B,cAAc,eAAe,SAAS,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC;AA0BnD,MAAM,gBAAgB,CAAC,SAC5B,cAAc,aAAa,EAAE,KAAK,CAAC;AAI9B,MAAM,YAAY,CAAC,SAAgC,cAAc,SAAS,EAAE,KAAK,CAAC;AAyBlF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}

package/dist/editor.d.cts

@@ -20,6 +20,52 @@ interface EditorOpenError extends Error {
  * app may not open files.
  */
 declare const openInEditor: (path: string) => Promise<void>;
+/**
+ * Where to land when entering the edit experience (EDITOR_FIRST_EDITING_SPEC §6
+ * Delta A). v1 supports only an optional repo-relative `path` in the CURRENT repo
+ * (self-scoped — the app you are already running; the host navigates within the
+ * current route, never to another repo). A URI or `..` path is refused
+ * `invalid-params`. Editing a file in one of your *mounts* (a space) is the
+ * `edit-file` task, not this.
+ */
+interface EditTarget {
+    /** A repo-relative working-tree path in the current repo to focus once in edit
+     *  mode (e.g. `src/App.tsx`). Omit to edit the current route's entry. */
+    path?: string;
+}
+/** An error from {@link requestEdit}, carrying a machine-readable `.code`. */
+interface RequestEditError extends Error {
+    code: 'read-only' | 'forbidden' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/**
+ * Ask the host to enter the **edit experience** for the app you are running —
+ * the present→edit transition (`/present/...` → `/edit/...`) an app cannot make
+ * itself. This is an INTENT (§2 recursion boundary): the app asks, the HOST
+ * performs the visible, user-observable navigation and draws all editor chrome;
+ * the app never navigates or paints chrome.
+ *
+ * Use it to offer an "edit this" affordance from a run/present-mode app that opens
+ * the app's own source in the platform editor — instead of shipping a bespoke
+ * in-app editor (EDITOR_FIRST_EDITING_SPEC §1).
+ *
+ * Resolves once the host begins the transition; rejects with a
+ * {@link RequestEditError} (`.code`). Treat `read-only`/`forbidden` as "editing is
+ * not available — hide the affordance," never as an error to surface to the user.
+ */
+declare const requestEdit: (target?: EditTarget) => Promise<void>;
+/** An error from a session intent ({@link setActiveFile} / {@link closeFile}),
+ *  carrying a machine-readable `.code`. */
+interface EditorSessionError extends Error {
+    code: 'forbidden' | 'not-found' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/** Switch the editor's active file to `path`, opening it (adding a tab) if it is
+ *  not already open — native `setActiveFile` parity. Rejects with an
+ *  {@link EditorSessionError} (`.code`) if the path is missing/invalid or this app
+ *  lacks `editor:document`. */
+declare const setActiveFile: (path: string) => Promise<void>;
+/** Close `path`'s tab in the editor (remove it from the open set) — native
+ *  `closeFile` parity. Rejects with an {@link EditorSessionError} (`.code`). */
+declare const closeFile: (path: string) => Promise<void>;
 /** An error from a working-tree mutation, carrying a machine-readable `.code`. */
 interface EditorWriteError extends Error {
     code: 'forbidden' | 'not-found' | 'exists' | 'protected' | 'too-large' | 'invalid-params' | 'no-target' | 'unknown';
@@ -39,4 +85,4 @@ declare const renameEntry: (from: string, to: string) => Promise<void>;
  *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */
 declare const uploadFile: (path: string, bytes: Uint8Array) => Promise<void>;
 
-export { type EditorOpenError, type EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile };
+export { type EditTarget, type EditorOpenError, type EditorSessionError, type EditorWriteError, type RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile };

package/dist/editor.d.ts

@@ -20,6 +20,52 @@ interface EditorOpenError extends Error {
  * app may not open files.
  */
 declare const openInEditor: (path: string) => Promise<void>;
+/**
+ * Where to land when entering the edit experience (EDITOR_FIRST_EDITING_SPEC §6
+ * Delta A). v1 supports only an optional repo-relative `path` in the CURRENT repo
+ * (self-scoped — the app you are already running; the host navigates within the
+ * current route, never to another repo). A URI or `..` path is refused
+ * `invalid-params`. Editing a file in one of your *mounts* (a space) is the
+ * `edit-file` task, not this.
+ */
+interface EditTarget {
+    /** A repo-relative working-tree path in the current repo to focus once in edit
+     *  mode (e.g. `src/App.tsx`). Omit to edit the current route's entry. */
+    path?: string;
+}
+/** An error from {@link requestEdit}, carrying a machine-readable `.code`. */
+interface RequestEditError extends Error {
+    code: 'read-only' | 'forbidden' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/**
+ * Ask the host to enter the **edit experience** for the app you are running —
+ * the present→edit transition (`/present/...` → `/edit/...`) an app cannot make
+ * itself. This is an INTENT (§2 recursion boundary): the app asks, the HOST
+ * performs the visible, user-observable navigation and draws all editor chrome;
+ * the app never navigates or paints chrome.
+ *
+ * Use it to offer an "edit this" affordance from a run/present-mode app that opens
+ * the app's own source in the platform editor — instead of shipping a bespoke
+ * in-app editor (EDITOR_FIRST_EDITING_SPEC §1).
+ *
+ * Resolves once the host begins the transition; rejects with a
+ * {@link RequestEditError} (`.code`). Treat `read-only`/`forbidden` as "editing is
+ * not available — hide the affordance," never as an error to surface to the user.
+ */
+declare const requestEdit: (target?: EditTarget) => Promise<void>;
+/** An error from a session intent ({@link setActiveFile} / {@link closeFile}),
+ *  carrying a machine-readable `.code`. */
+interface EditorSessionError extends Error {
+    code: 'forbidden' | 'not-found' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/** Switch the editor's active file to `path`, opening it (adding a tab) if it is
+ *  not already open — native `setActiveFile` parity. Rejects with an
+ *  {@link EditorSessionError} (`.code`) if the path is missing/invalid or this app
+ *  lacks `editor:document`. */
+declare const setActiveFile: (path: string) => Promise<void>;
+/** Close `path`'s tab in the editor (remove it from the open set) — native
+ *  `closeFile` parity. Rejects with an {@link EditorSessionError} (`.code`). */
+declare const closeFile: (path: string) => Promise<void>;
 /** An error from a working-tree mutation, carrying a machine-readable `.code`. */
 interface EditorWriteError extends Error {
     code: 'forbidden' | 'not-found' | 'exists' | 'protected' | 'too-large' | 'invalid-params' | 'no-target' | 'unknown';
@@ -39,4 +85,4 @@ declare const renameEntry: (from: string, to: string) => Promise<void>;
  *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */
 declare const uploadFile: (path: string, bytes: Uint8Array) => Promise<void>;
 
-export { type EditorOpenError, type EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile };
+export { type EditTarget, type EditorOpenError, type EditorSessionError, type EditorWriteError, type RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile };

package/dist/editor.js

@@ -8,17 +8,23 @@ const editorRequest = async (method, arg) => {
   }
 };
 const openInEditor = (path) => editorRequest("open", { path });
+const requestEdit = (target) => editorRequest("requestEdit", target ? { ...target } : {});
+const setActiveFile = (path) => editorRequest("setActive", { path });
+const closeFile = (path) => editorRequest("close", { path });
 const createFile = (path) => editorRequest("createFile", { path });
 const createFolder = (path) => editorRequest("createFolder", { path });
 const deleteEntry = (path) => editorRequest("deleteEntry", { path });
 const renameEntry = (from, to) => editorRequest("rename", { from, to });
 const uploadFile = (path, bytes) => editorRequest("upload", { path, bytes });
 export {
+  closeFile,
   createFile,
   createFolder,
   deleteEntry,
   openInEditor,
   renameEntry,
+  requestEdit,
+  setActiveFile,
   uploadFile
 };
 //# sourceMappingURL=editor.js.map

package/dist/editor.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":"AAAA,SAAS,uBAAuB;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,MAAM,gBAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyBpF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}
+{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n/**\n * Where to land when entering the edit experience (EDITOR_FIRST_EDITING_SPEC §6\n * Delta A). v1 supports only an optional repo-relative `path` in the CURRENT repo\n * (self-scoped — the app you are already running; the host navigates within the\n * current route, never to another repo). A URI or `..` path is refused\n * `invalid-params`. Editing a file in one of your *mounts* (a space) is the\n * `edit-file` task, not this.\n */\nexport interface EditTarget {\n  /** A repo-relative working-tree path in the current repo to focus once in edit\n   *  mode (e.g. `src/App.tsx`). Omit to edit the current route's entry. */\n  path?: string;\n}\n\n/** An error from {@link requestEdit}, carrying a machine-readable `.code`. */\nexport interface RequestEditError extends Error {\n  code:\n    | 'read-only' // editing isn't possible here (a `ro` mount / anonymous viewer) — HIDE the affordance\n    | 'forbidden' // the host refuses (e.g. a cross-repo / out-of-scope target)\n    | 'invalid-params' // the target was malformed (URI / `..` / a non-current repo)\n    | 'no-target' // there is no host editor session to enter\n    | 'unknown';\n}\n\n/**\n * Ask the host to enter the **edit experience** for the app you are running —\n * the present→edit transition (`/present/...` → `/edit/...`) an app cannot make\n * itself. This is an INTENT (§2 recursion boundary): the app asks, the HOST\n * performs the visible, user-observable navigation and draws all editor chrome;\n * the app never navigates or paints chrome.\n *\n * Use it to offer an \"edit this\" affordance from a run/present-mode app that opens\n * the app's own source in the platform editor — instead of shipping a bespoke\n * in-app editor (EDITOR_FIRST_EDITING_SPEC §1).\n *\n * Resolves once the host begins the transition; rejects with a\n * {@link RequestEditError} (`.code`). Treat `read-only`/`forbidden` as \"editing is\n * not available — hide the affordance,\" never as an error to surface to the user.\n */\nexport const requestEdit = (target?: EditTarget): Promise<void> =>\n  editorRequest('requestEdit', target ? { ...target } : {});\n\n// ---------------------------------------------------------------------------\n// Editor SESSION management (EDITOR_AS_APP_SPEC §5.1; editor-as-app plan Phase\n// 03). Unlike `openInEditor` (the explorer's cross-app intent, `editor:open`),\n// these drive the editor's OWN open-tab set + active file, so they are gated by\n// the editor app's `editor:document` capability — a file explorer holding only\n// `editor:open` cannot call them. The host re-validates the path against the live\n// working tree; the editor itself stays host-owned (§2 recursion boundary).\n// ---------------------------------------------------------------------------\n\n/** An error from a session intent ({@link setActiveFile} / {@link closeFile}),\n *  carrying a machine-readable `.code`. */\nexport interface EditorSessionError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:document`\n    | 'not-found' // no such file in the live working tree\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Switch the editor's active file to `path`, opening it (adding a tab) if it is\n *  not already open — native `setActiveFile` parity. Rejects with an\n *  {@link EditorSessionError} (`.code`) if the path is missing/invalid or this app\n *  lacks `editor:document`. */\nexport const setActiveFile = (path: string): Promise<void> =>\n  editorRequest('setActive', { path });\n\n/** Close `path`'s tab in the editor (remove it from the open set) — native\n *  `closeFile` parity. Rejects with an {@link EditorSessionError} (`.code`). */\nexport const closeFile = (path: string): Promise<void> => editorRequest('close', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":"AAAA,SAAS,uBAAuB;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,MAAM,gBAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyCpF,MAAM,cAAc,CAAC,WAC1B,cAAc,eAAe,SAAS,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC;AA0BnD,MAAM,gBAAgB,CAAC,SAC5B,cAAc,aAAa,EAAE,KAAK,CAAC;AAI9B,MAAM,YAAY,CAAC,SAAgC,cAAc,SAAS,EAAE,KAAK,CAAC;AAyBlF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}

package/dist/index.cjs

@@ -34,6 +34,8 @@ __reExport(index_exports, require("./netFetch"), module.exports);
 __reExport(index_exports, require("./secrets"), module.exports);
 __reExport(index_exports, require("./tasks"), module.exports);
 __reExport(index_exports, require("./runtime"), module.exports);
+__reExport(index_exports, require("./irMarkers"), module.exports);
+__reExport(index_exports, require("./ready"), module.exports);
 __reExport(index_exports, require("./protocolStream"), module.exports);
 __reExport(index_exports, require("./sandboxTypes"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
@@ -57,6 +59,8 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./secrets"),
   ...require("./tasks"),
   ...require("./runtime"),
+  ...require("./irMarkers"),
+  ...require("./ready"),
   ...require("./protocolStream"),
   ...require("./sandboxTypes")
 });

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 './netFetch';\nexport * from './secrets';\nexport * from './tasks';\nexport * from './runtime';\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,uBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,oBAjBd;AAkBA,0BAAc,sBAlBd;AAmBA,0BAAc,6BAnBd;AAoBA,0BAAc,2BApBd;","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 './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\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,uBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,oBAjBd;AAkBA,0BAAc,sBAlBd;AAmBA,0BAAc,wBAnBd;AAoBA,0BAAc,oBApBd;AAqBA,0BAAc,6BArBd;AAsBA,0BAAc,2BAtBd;","names":[]}

package/dist/index.d.cts

@@ -7,16 +7,18 @@ export { useFileMetadata, useMetadataQuery } from './hooks.cjs';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.cjs';
 export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.cjs';
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.cjs';
-export { EditorOpenError, EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile } from './editor.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 { GrantRecord, Member, MountQuery, MountRemoveReason, RemovedMount, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getAppMountPath, getMounts, getSpaceMembers, listAllSpaces, listGrants, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.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';
 export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.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 { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.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';
+export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.cjs';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.cjs';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
 export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.cjs';

package/dist/index.d.ts

@@ -7,16 +7,18 @@ export { useFileMetadata, useMetadataQuery } from './hooks.js';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.js';
 export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.js';
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.js';
-export { EditorOpenError, EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile } from './editor.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 { GrantRecord, Member, MountQuery, MountRemoveReason, RemovedMount, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getAppMountPath, getMounts, getSpaceMembers, listAllSpaces, listGrants, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.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';
 export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.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 { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.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';
+export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.js';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.js';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
 export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.js';

package/dist/index.js

@@ -17,6 +17,8 @@ export * from "./netFetch";
 export * from "./secrets";
 export * from "./tasks";
 export * from "./runtime";
+export * from "./irMarkers";
+export * from "./ready";
 export * from "./protocolStream";
 export * from "./sandboxTypes";
 //# sourceMappingURL=index.js.map

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 './netFetch';\nexport * from './secrets';\nexport * from './tasks';\nexport * from './runtime';\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;","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 './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\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;","names":[]}

package/dist/injectedBundler.cjs

@@ -0,0 +1,49 @@
+"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 injectedBundler_exports = {};
+__export(injectedBundler_exports, {
+  getInjectedMetadataEmitter: () => getInjectedMetadataEmitter,
+  resolveMetadataSource: () => resolveMetadataSource
+});
+module.exports = __toCommonJS(injectedBundler_exports);
+const injectedBundler = () => {
+  try {
+    return module?.evaluation?.module?.bundler ?? null;
+  } catch {
+    return null;
+  }
+};
+const getInjectedMetadataEmitter = () => {
+  const b = injectedBundler();
+  if (b && typeof b.onMetadataChange === "function" && b.onMetadataChangeEmitter) {
+    return {
+      onMetadataChange: b.onMetadataChange,
+      enable: () => b.onMetadataChangeEmitter.enable()
+    };
+  }
+  return null;
+};
+const resolveMetadataSource = (injected) => injected ? { event: injected.onMetadataChange, enable: () => injected.enable() } : { event: void 0, enable: () => {
+} };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getInjectedMetadataEmitter,
+  resolveMetadataSource
+});
+//# sourceMappingURL=injectedBundler.cjs.map

package/dist/injectedBundler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/injectedBundler.ts"],"sourcesContent":["// Injected sandbox-bundler access (SDK_PACKAGING_SPEC §4/§8, Phase 5). The SDK was\n// historically wired straight to the injected bundler service objects\n// (`module.evaluation.module.bundler.<x>`). Phase 5 makes the SDK transport-agnostic\n// so those services can eventually be retired: every reader PREFERS the injection\n// (so the current, live path stays byte-for-byte unchanged) and FALLS BACK to the\n// §4 transport when the SDK is fetched from npm with no injection present.\n//\n// This module centralizes the `module.evaluation.module.bundler.*` reads (the same\n// philosophy as `sandboxUtils`' transport resolver) and exposes a PURE resolver for\n// the metadata-update subscription so the dual-mode decision is unit-tested without\n// a live bundler. The ambient reads themselves are thin (untestable without the\n// sandbox realm, exactly like `sandboxUtils.transport()`).\n\n/** vscode-style Event source: subscribe with a listener, get a disposable back. */\nexport type EventSource = (listener: (msg: any) => void) => { dispose(): void };\n\n/** The injected bundler's metadata emitter — fires `{type:'metadata-update', update}`\n *  as files (re)compile. Absent when the SDK is npm-fetched (no injection). */\nexport interface InjectedMetadataEmitter {\n  onMetadataChange: EventSource;\n  /** Start the DelayedEmitter once a subscriber is attached (injected path only). */\n  enable(): void;\n}\n\n/** The injected bundler object, or null when there is no injection (npm-fetched). */\nconst injectedBundler = (): any | null => {\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    return module?.evaluation?.module?.bundler ?? null;\n  } catch {\n    return null;\n  }\n};\n\n/** The injected bundler's metadata emitter, or null when npm-fetched. */\nexport const getInjectedMetadataEmitter = (): InjectedMetadataEmitter | null => {\n  const b = injectedBundler();\n  if (b && typeof b.onMetadataChange === 'function' && b.onMetadataChangeEmitter) {\n    return {\n      onMetadataChange: b.onMetadataChange,\n      enable: () => b.onMetadataChangeEmitter.enable(),\n    };\n  }\n  return null;\n};\n\n/** What `boot` needs to subscribe to metadata updates: the `event` source to hand\n *  `addListener` (the injected emitter, or `undefined` → listen over the transport)\n *  and an `enable` to start the injected DelayedEmitter (a no-op off-injection). */\nexport interface MetadataSource {\n  event?: EventSource;\n  enable(): void;\n}\n\n/**\n * Resolve the metadata-update subscription source (PURE — the dual-mode decision).\n * With the injected emitter: use it and arm it, so the live path is byte-identical.\n * Without it (npm-fetched): return no `event`, so the caller's `addListener` falls\n * back to the §4 transport's `onMessage`, and `enable` is a no-op.\n */\nexport const resolveMetadataSource = (\n  injected: InjectedMetadataEmitter | null,\n): MetadataSource =>\n  injected\n    ? { event: injected.onMetadataChange, enable: () => injected.enable() }\n    : { event: undefined, enable: () => {} };\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,MAAM,kBAAkB,MAAkB;AACxC,MAAI;AAEF,WAAO,QAAQ,YAAY,QAAQ,WAAW;AAAA,EAChD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGO,MAAM,6BAA6B,MAAsC;AAC9E,QAAM,IAAI,gBAAgB;AAC1B,MAAI,KAAK,OAAO,EAAE,qBAAqB,cAAc,EAAE,yBAAyB;AAC9E,WAAO;AAAA,MACL,kBAAkB,EAAE;AAAA,MACpB,QAAQ,MAAM,EAAE,wBAAwB,OAAO;AAAA,IACjD;AAAA,EACF;AACA,SAAO;AACT;AAgBO,MAAM,wBAAwB,CACnC,aAEA,WACI,EAAE,OAAO,SAAS,kBAAkB,QAAQ,MAAM,SAAS,OAAO,EAAE,IACpE,EAAE,OAAO,QAAW,QAAQ,MAAM;AAAC,EAAE;","names":[]}

package/dist/injectedBundler.d.cts

@@ -0,0 +1,29 @@
+/** vscode-style Event source: subscribe with a listener, get a disposable back. */
+type EventSource = (listener: (msg: any) => void) => {
+    dispose(): void;
+};
+/** The injected bundler's metadata emitter — fires `{type:'metadata-update', update}`
+ *  as files (re)compile. Absent when the SDK is npm-fetched (no injection). */
+interface InjectedMetadataEmitter {
+    onMetadataChange: EventSource;
+    /** Start the DelayedEmitter once a subscriber is attached (injected path only). */
+    enable(): void;
+}
+/** The injected bundler's metadata emitter, or null when npm-fetched. */
+declare const getInjectedMetadataEmitter: () => InjectedMetadataEmitter | null;
+/** What `boot` needs to subscribe to metadata updates: the `event` source to hand
+ *  `addListener` (the injected emitter, or `undefined` → listen over the transport)
+ *  and an `enable` to start the injected DelayedEmitter (a no-op off-injection). */
+interface MetadataSource {
+    event?: EventSource;
+    enable(): void;
+}
+/**
+ * Resolve the metadata-update subscription source (PURE — the dual-mode decision).
+ * With the injected emitter: use it and arm it, so the live path is byte-identical.
+ * Without it (npm-fetched): return no `event`, so the caller's `addListener` falls
+ * back to the §4 transport's `onMessage`, and `enable` is a no-op.
+ */
+declare const resolveMetadataSource: (injected: InjectedMetadataEmitter | null) => MetadataSource;
+
+export { type EventSource, type InjectedMetadataEmitter, type MetadataSource, getInjectedMetadataEmitter, resolveMetadataSource };

package/dist/injectedBundler.d.ts

@@ -0,0 +1,29 @@
+/** vscode-style Event source: subscribe with a listener, get a disposable back. */
+type EventSource = (listener: (msg: any) => void) => {
+    dispose(): void;
+};
+/** The injected bundler's metadata emitter — fires `{type:'metadata-update', update}`
+ *  as files (re)compile. Absent when the SDK is npm-fetched (no injection). */
+interface InjectedMetadataEmitter {
+    onMetadataChange: EventSource;
+    /** Start the DelayedEmitter once a subscriber is attached (injected path only). */
+    enable(): void;
+}
+/** The injected bundler's metadata emitter, or null when npm-fetched. */
+declare const getInjectedMetadataEmitter: () => InjectedMetadataEmitter | null;
+/** What `boot` needs to subscribe to metadata updates: the `event` source to hand
+ *  `addListener` (the injected emitter, or `undefined` → listen over the transport)
+ *  and an `enable` to start the injected DelayedEmitter (a no-op off-injection). */
+interface MetadataSource {
+    event?: EventSource;
+    enable(): void;
+}
+/**
+ * Resolve the metadata-update subscription source (PURE — the dual-mode decision).
+ * With the injected emitter: use it and arm it, so the live path is byte-identical.
+ * Without it (npm-fetched): return no `event`, so the caller's `addListener` falls
+ * back to the §4 transport's `onMessage`, and `enable` is a no-op.
+ */
+declare const resolveMetadataSource: (injected: InjectedMetadataEmitter | null) => MetadataSource;
+
+export { type EventSource, type InjectedMetadataEmitter, type MetadataSource, getInjectedMetadataEmitter, resolveMetadataSource };