@immediately-run/sdk 0.64.1 → 0.66.0

package/dist/boot.cjs

@@ -43,6 +43,7 @@ var import_sandboxUtils = require("./sandboxUtils");
 var import_TinkerableContext = require("./TinkerableContext");
 var import_urlUtils = require("./urlUtils");
 var import_protocol = require("./generated/protocol");
+var import_entryState = require("./entryState");
 const resolveMdxComponents = (mdxComponents) => mdxComponents === void 0 ? import_MDXComponents.DEFAULT_MDX_COMPONENTS : typeof mdxComponents === "function" ? mdxComponents(import_MDXComponents.DEFAULT_MDX_COMPONENTS) : { ...import_MDXComponents.DEFAULT_MDX_COMPONENTS, ...mdxComponents };
 const updateAlreadyApplied = (filesMetadata, update) => {
   for (let [key, value] of Object.entries(update)) {
@@ -55,7 +56,11 @@ const updateAlreadyApplied = (filesMetadata, update) => {
 const TinkerableApp = ({ routingSpec, children }) => {
   const [context, setContext] = (0, import_react.useState)((0, import_contextUtils.getInitialContext)(routingSpec));
   (0, import_react.useEffect)(() => {
-    const removeListener = (0, import_sandboxUtils.addListener)(import_protocol.URLCHANGE, ({ url }) => {
+    const removeListener = (0, import_sandboxUtils.addListener)(import_protocol.URLCHANGE, ({ url, entryState, back, forward }) => {
+      (0, import_entryState.receiveNavigation)({
+        state: entryState ?? void 0,
+        direction: back ? "back" : forward ? "forward" : "push"
+      });
       setContext((context2) => {
         const updatedContext = (0, import_contextUtils.updateContext)(context2, url);
         if (updatedContext !== context2) {

package/dist/boot.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, ReactNode, 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 { ScrollAfterNavigation } from './components/ScrollAfterNavigation';\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';\nimport { METADATA_UPDATE, URLCHANGE } from './generated/protocol';\n\n/** A map of MDX component overrides, or a function that receives the platform\n *  {@link DEFAULT_MDX_COMPONENTS} and returns the full map to use. */\nexport type MdxComponents = Record<string, FC> | ((defaults: Record<string, FC>) => Record<string, FC>);\n\n/**\n * Resolve the effective MDX component map from a {@link BootProps.mdxComponents}\n * value (MARKDOWN_SYNTAX_SPEC §11.3):\n * - `undefined` → the platform {@link DEFAULT_MDX_COMPONENTS} (same reference).\n * - a **function** → the full-replace escape hatch, handed the defaults.\n * - a **map** → merged *over* the defaults (`{ ...defaults, ...map }`), so\n *   overriding one component keeps the rest — the phantom-defaults invariant\n *   (§11.2) that stops the MDX missing-reference guard from firing.\n */\nexport const resolveMdxComponents = (mdxComponents?: MdxComponents): Record<string, FC> =>\n  mdxComponents === undefined\n    ? (DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : typeof mdxComponents === 'function'\n    ? mdxComponents(DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : { ...(DEFAULT_MDX_COMPONENTS as Record<string, FC>), ...mdxComponents };\n\n/** Options for {@link boot}: MDX overrides, a route table, or an app root. */\nexport type BootProps = {\n  /**\n   * MDX component overrides. A **map** is *merged over* the platform defaults\n   * ({@link DEFAULT_MDX_COMPONENTS}) — so overriding `WikiLink` alone keeps the\n   * default `a` and `Admonition` (MARKDOWN_SYNTAX_SPEC §11.3). Pass a **function**\n   * `(defaults) => map` as the full-replace escape hatch when you want complete\n   * control over the set.\n   */\n  mdxComponents?: MdxComponents;\n  routingSpec?: RoutingSpec;\n  /**\n   * App root rendered directly inside the providers (with full navigation\n   * context), instead of dispatching through a `routingSpec`. Render\n   * `<Routes>`/`<Route>` here for fully dynamic routing — no catch-all rule\n   * boilerplate. Takes precedence over `routingSpec` for what is rendered.\n   */\n  children?: ReactNode;\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\n/** The app shell {@link boot} renders: holds navigation state, subscribes to host\n *  URL + metadata pushes, and renders `children` or the route `<Router />`. */\nexport const TinkerableApp = ({ routingSpec, children }: { routingSpec: RoutingSpec; children?: ReactNode }) => {\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      {/* Capability C: lands cross-page `#fragment` deep-links on their section\n          after the destination tree mounts, uniform for every MDX app (§13.5). */}\n      <ScrollAfterNavigation />\n      {children ?? <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/** The default route table when `boot` is called with no `routingSpec`/`children`:\n *  `/` → main content, `/files/<path>` → the file router, else not-found.\n *  Re-expressed with path templates (SANDBOX_ROUTING_SPEC §7); the file path\n *  surfaces under the `*` wildcard. The catch-all stays a raw RegExp — the\n *  escape hatch — so it anchors `.+` (a non-empty path) exactly as before. */\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: '/', element: <MainContent /> },\n    { name: 'FileRouter', pattern: `${FILES_PREFIX}/*`, element: <FileRouter /> },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, element: <ErrorNotFound /> },\n  ],\n};\n\n/**\n * Matches any `sandboxPath` so navigation context can be built without a route\n * table. Used when {@link boot} is given `children` (the app owns dispatch via\n * `<Routes>`); the catch-all's `element` is never rendered (children are).\n */\nexport const CATCH_ALL_ROUTING_SPEC: RoutingSpec = {\n  routes: [{ name: 'AppRoot', pattern: /^.*$/, element: null }],\n};\n\n/**\n * Mount an immediately.run app into the sandbox `#root`. The entry point every\n * app calls from `index.tsx`: wires the MDX, module-cache, and navigation\n * providers, then renders the route table (`routingSpec`) or your `children`.\n */\nexport const boot = ({ mdxComponents, routingSpec, children }: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const resolvedComponents = resolveMdxComponents(mdxComponents);\n  // `children` own dispatch, so a catch-all keeps navigation working without a\n  // table; otherwise fall back to the default file/main-content routes.\n  const spec = routingSpec ?? (children ? CATCH_ALL_ROUTING_SPEC : DEFAULT_ROUTING_SPEC);\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={resolvedComponents}>\n          <BootMarkers />\n          <TinkerableApp routingSpec={spec}>{children}</TinkerableApp>\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>,\n  );\n};\n"],"mappings":"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","names":["context"]}
+{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, ReactNode, 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 { ScrollAfterNavigation } from './components/ScrollAfterNavigation';\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';\nimport { METADATA_UPDATE, URLCHANGE } from './generated/protocol';\nimport { receiveNavigation } from './entryState';\n\n/** A map of MDX component overrides, or a function that receives the platform\n *  {@link DEFAULT_MDX_COMPONENTS} and returns the full map to use. */\nexport type MdxComponents = Record<string, FC> | ((defaults: Record<string, FC>) => Record<string, FC>);\n\n/**\n * Resolve the effective MDX component map from a {@link BootProps.mdxComponents}\n * value (MARKDOWN_SYNTAX_SPEC §11.3):\n * - `undefined` → the platform {@link DEFAULT_MDX_COMPONENTS} (same reference).\n * - a **function** → the full-replace escape hatch, handed the defaults.\n * - a **map** → merged *over* the defaults (`{ ...defaults, ...map }`), so\n *   overriding one component keeps the rest — the phantom-defaults invariant\n *   (§11.2) that stops the MDX missing-reference guard from firing.\n */\nexport const resolveMdxComponents = (mdxComponents?: MdxComponents): Record<string, FC> =>\n  mdxComponents === undefined\n    ? (DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : typeof mdxComponents === 'function'\n    ? mdxComponents(DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : { ...(DEFAULT_MDX_COMPONENTS as Record<string, FC>), ...mdxComponents };\n\n/** Options for {@link boot}: MDX overrides, a route table, or an app root. */\nexport type BootProps = {\n  /**\n   * MDX component overrides. A **map** is *merged over* the platform defaults\n   * ({@link DEFAULT_MDX_COMPONENTS}) — so overriding `WikiLink` alone keeps the\n   * default `a` and `Admonition` (MARKDOWN_SYNTAX_SPEC §11.3). Pass a **function**\n   * `(defaults) => map` as the full-replace escape hatch when you want complete\n   * control over the set.\n   */\n  mdxComponents?: MdxComponents;\n  routingSpec?: RoutingSpec;\n  /**\n   * App root rendered directly inside the providers (with full navigation\n   * context), instead of dispatching through a `routingSpec`. Render\n   * `<Routes>`/`<Route>` here for fully dynamic routing — no catch-all rule\n   * boilerplate. Takes precedence over `routingSpec` for what is rendered.\n   */\n  children?: ReactNode;\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\n/** The app shell {@link boot} renders: holds navigation state, subscribes to host\n *  URL + metadata pushes, and renders `children` or the route `<Router />`. */\nexport const TinkerableApp = ({ routingSpec, children }: { routingSpec: RoutingSpec; children?: ReactNode }) => {\n  const [context, setContext] = useState<TinkerableState>(getInitialContext(routingSpec));\n  useEffect(() => {\n    const removeListener = addListener(URLCHANGE, ({ url, entryState, back, forward }) => {\n      // R3-627: record what the host says about this arrival BEFORE the route state\n      // updates, so a consumer reacting to the new route already sees the scratch\n      // and the direction that produced it.\n      receiveNavigation({\n        state: (entryState ?? undefined) as Record<string, unknown> | undefined,\n        direction: back ? 'back' : forward ? 'forward' : 'push',\n      });\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      {/* Capability C: lands cross-page `#fragment` deep-links on their section\n          after the destination tree mounts, uniform for every MDX app (§13.5). */}\n      <ScrollAfterNavigation />\n      {children ?? <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/** The default route table when `boot` is called with no `routingSpec`/`children`:\n *  `/` → main content, `/files/<path>` → the file router, else not-found.\n *  Re-expressed with path templates (SANDBOX_ROUTING_SPEC §7); the file path\n *  surfaces under the `*` wildcard. The catch-all stays a raw RegExp — the\n *  escape hatch — so it anchors `.+` (a non-empty path) exactly as before. */\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: '/', element: <MainContent /> },\n    { name: 'FileRouter', pattern: `${FILES_PREFIX}/*`, element: <FileRouter /> },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, element: <ErrorNotFound /> },\n  ],\n};\n\n/**\n * Matches any `sandboxPath` so navigation context can be built without a route\n * table. Used when {@link boot} is given `children` (the app owns dispatch via\n * `<Routes>`); the catch-all's `element` is never rendered (children are).\n */\nexport const CATCH_ALL_ROUTING_SPEC: RoutingSpec = {\n  routes: [{ name: 'AppRoot', pattern: /^.*$/, element: null }],\n};\n\n/**\n * Mount an immediately.run app into the sandbox `#root`. The entry point every\n * app calls from `index.tsx`: wires the MDX, module-cache, and navigation\n * providers, then renders the route table (`routingSpec`) or your `children`.\n */\nexport const boot = ({ mdxComponents, routingSpec, children }: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const resolvedComponents = resolveMdxComponents(mdxComponents);\n  // `children` own dispatch, so a catch-all keeps navigation working without a\n  // table; otherwise fall back to the default file/main-content routes.\n  const spec = routingSpec ?? (children ? CATCH_ALL_ROUTING_SPEC : DEFAULT_ROUTING_SPEC);\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={resolvedComponents}>\n          <BootMarkers />\n          <TinkerableApp routingSpec={spec}>{children}</TinkerableApp>\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>,\n  );\n};\n"],"mappings":"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","names":["context"]}

package/dist/boot.js

@@ -17,6 +17,7 @@ import { addListener } from "./sandboxUtils";
 import { TinkerableContext } from "./TinkerableContext";
 import { FILES_PREFIX } from "./urlUtils";
 import { METADATA_UPDATE, URLCHANGE } from "./generated/protocol";
+import { receiveNavigation } from "./entryState";
 const resolveMdxComponents = (mdxComponents) => mdxComponents === void 0 ? DEFAULT_MDX_COMPONENTS : typeof mdxComponents === "function" ? mdxComponents(DEFAULT_MDX_COMPONENTS) : { ...DEFAULT_MDX_COMPONENTS, ...mdxComponents };
 const updateAlreadyApplied = (filesMetadata, update) => {
   for (let [key, value] of Object.entries(update)) {
@@ -29,7 +30,11 @@ const updateAlreadyApplied = (filesMetadata, update) => {
 const TinkerableApp = ({ routingSpec, children }) => {
   const [context, setContext] = useState(getInitialContext(routingSpec));
   useEffect(() => {
-    const removeListener = addListener(URLCHANGE, ({ url }) => {
+    const removeListener = addListener(URLCHANGE, ({ url, entryState, back, forward }) => {
+      receiveNavigation({
+        state: entryState ?? void 0,
+        direction: back ? "back" : forward ? "forward" : "push"
+      });
       setContext((context2) => {
         const updatedContext = updateContext(context2, url);
         if (updatedContext !== context2) {

package/dist/boot.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, ReactNode, 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 { ScrollAfterNavigation } from './components/ScrollAfterNavigation';\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';\nimport { METADATA_UPDATE, URLCHANGE } from './generated/protocol';\n\n/** A map of MDX component overrides, or a function that receives the platform\n *  {@link DEFAULT_MDX_COMPONENTS} and returns the full map to use. */\nexport type MdxComponents = Record<string, FC> | ((defaults: Record<string, FC>) => Record<string, FC>);\n\n/**\n * Resolve the effective MDX component map from a {@link BootProps.mdxComponents}\n * value (MARKDOWN_SYNTAX_SPEC §11.3):\n * - `undefined` → the platform {@link DEFAULT_MDX_COMPONENTS} (same reference).\n * - a **function** → the full-replace escape hatch, handed the defaults.\n * - a **map** → merged *over* the defaults (`{ ...defaults, ...map }`), so\n *   overriding one component keeps the rest — the phantom-defaults invariant\n *   (§11.2) that stops the MDX missing-reference guard from firing.\n */\nexport const resolveMdxComponents = (mdxComponents?: MdxComponents): Record<string, FC> =>\n  mdxComponents === undefined\n    ? (DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : typeof mdxComponents === 'function'\n    ? mdxComponents(DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : { ...(DEFAULT_MDX_COMPONENTS as Record<string, FC>), ...mdxComponents };\n\n/** Options for {@link boot}: MDX overrides, a route table, or an app root. */\nexport type BootProps = {\n  /**\n   * MDX component overrides. A **map** is *merged over* the platform defaults\n   * ({@link DEFAULT_MDX_COMPONENTS}) — so overriding `WikiLink` alone keeps the\n   * default `a` and `Admonition` (MARKDOWN_SYNTAX_SPEC §11.3). Pass a **function**\n   * `(defaults) => map` as the full-replace escape hatch when you want complete\n   * control over the set.\n   */\n  mdxComponents?: MdxComponents;\n  routingSpec?: RoutingSpec;\n  /**\n   * App root rendered directly inside the providers (with full navigation\n   * context), instead of dispatching through a `routingSpec`. Render\n   * `<Routes>`/`<Route>` here for fully dynamic routing — no catch-all rule\n   * boilerplate. Takes precedence over `routingSpec` for what is rendered.\n   */\n  children?: ReactNode;\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\n/** The app shell {@link boot} renders: holds navigation state, subscribes to host\n *  URL + metadata pushes, and renders `children` or the route `<Router />`. */\nexport const TinkerableApp = ({ routingSpec, children }: { routingSpec: RoutingSpec; children?: ReactNode }) => {\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      {/* Capability C: lands cross-page `#fragment` deep-links on their section\n          after the destination tree mounts, uniform for every MDX app (§13.5). */}\n      <ScrollAfterNavigation />\n      {children ?? <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/** The default route table when `boot` is called with no `routingSpec`/`children`:\n *  `/` → main content, `/files/<path>` → the file router, else not-found.\n *  Re-expressed with path templates (SANDBOX_ROUTING_SPEC §7); the file path\n *  surfaces under the `*` wildcard. The catch-all stays a raw RegExp — the\n *  escape hatch — so it anchors `.+` (a non-empty path) exactly as before. */\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: '/', element: <MainContent /> },\n    { name: 'FileRouter', pattern: `${FILES_PREFIX}/*`, element: <FileRouter /> },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, element: <ErrorNotFound /> },\n  ],\n};\n\n/**\n * Matches any `sandboxPath` so navigation context can be built without a route\n * table. Used when {@link boot} is given `children` (the app owns dispatch via\n * `<Routes>`); the catch-all's `element` is never rendered (children are).\n */\nexport const CATCH_ALL_ROUTING_SPEC: RoutingSpec = {\n  routes: [{ name: 'AppRoot', pattern: /^.*$/, element: null }],\n};\n\n/**\n * Mount an immediately.run app into the sandbox `#root`. The entry point every\n * app calls from `index.tsx`: wires the MDX, module-cache, and navigation\n * providers, then renders the route table (`routingSpec`) or your `children`.\n */\nexport const boot = ({ mdxComponents, routingSpec, children }: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const resolvedComponents = resolveMdxComponents(mdxComponents);\n  // `children` own dispatch, so a catch-all keeps navigation working without a\n  // table; otherwise fall back to the default file/main-content routes.\n  const spec = routingSpec ?? (children ? CATCH_ALL_ROUTING_SPEC : DEFAULT_ROUTING_SPEC);\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={resolvedComponents}>\n          <BootMarkers />\n          <TinkerableApp routingSpec={spec}>{children}</TinkerableApp>\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>,\n  );\n};\n"],"mappings":";AAsHI,SAGE,KAHF;AAtHJ,SAAwB,YAAY,WAAW,iBAAiB,gBAAgB;AAChF,SAAS,kBAAkB;AAE3B,SAAS,sBAAsB;AAE/B,SAAS,qBAAqB;AAC9B,SAAS,kBAAkB;AAC3B,SAAS,mBAAmB;AAC5B,SAAS,8BAA8B;AACvC,SAAS,6BAA6B;AACtC,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;AAC7B,SAAS,iBAAiB,iBAAiB;AAepC,MAAM,uBAAuB,CAAC,kBACnC,kBAAkB,SACb,yBACD,OAAO,kBAAkB,aACzB,cAAc,sBAA4C,IAC1D,EAAE,GAAI,wBAA+C,GAAG,cAAc;AAsB5E,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;AAIO,MAAM,gBAAgB,CAAC,EAAE,aAAa,SAAS,MAA0D;AAC9G,QAAM,CAAC,SAAS,UAAU,IAAI,SAA0B,kBAAkB,WAAW,CAAC;AACtF,YAAU,MAAM;AACd,UAAM,iBAAiB,YAAY,WAAW,CAAC,EAAE,IAAI,MAAM;AACzD,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,qBAAC,qBAAkB,OAAO,SAGxB;AAAA,wBAAC,yBAAsB;AAAA,IACtB,YAAY,oBAAC,UAAO;AAAA,KACvB;AAEJ;AASA,MAAM,cAAc,MAAY;AAC9B,kBAAgB,MAAM;AACpB,mBAAe,QAAQ;AACvB,mBAAe,gBAAgB;AAAA,EACjC,GAAG,CAAC,CAAC;AACL,SAAO;AACT;AAOO,MAAM,uBAAoC;AAAA,EAC/C,QAAQ;AAAA,IACN,EAAE,MAAM,eAAe,SAAS,KAAK,SAAS,oBAAC,eAAY,EAAG;AAAA,IAC9D,EAAE,MAAM,cAAc,SAAS,GAAG,YAAY,MAAM,SAAS,oBAAC,cAAW,EAAG;AAAA,IAC5E,EAAE,MAAM,iBAAiB,SAAS,iBAAiB,SAAS,oBAAC,iBAAc,EAAG;AAAA,EAChF;AACF;AAOO,MAAM,yBAAsC;AAAA,EACjD,QAAQ,CAAC,EAAE,MAAM,WAAW,SAAS,QAAQ,SAAS,KAAK,CAAC;AAC9D;AAOO,MAAM,OAAO,CAAC,EAAE,eAAe,aAAa,SAAS,IAAe,CAAC,MAAM;AAChF,QAAM,cAAc,SAAS,eAAe,MAAM;AAClD,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,QAAM,qBAAqB,qBAAqB,aAAa;AAG7D,QAAM,OAAO,gBAAgB,WAAW,yBAAyB;AACjE,QAAM,cAAc,IAAI,YAAY;AACpC,QAAM,OAAO,WAAW,WAAW;AACnC,OAAK;AAAA,IACH,oBAAC,cACC,8BAAC,8BAA2B,aAC1B,+BAAC,eAAY,YAAY,oBACvB;AAAA,0BAAC,eAAY;AAAA,MACb,oBAAC,iBAAc,aAAa,MAAO,UAAS;AAAA,OAC9C,GACF,GACF;AAAA,EACF;AACF;","names":["context"]}
+{"version":3,"sources":["../src/boot.tsx"],"sourcesContent":["import { FC, ReactNode, 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 { ScrollAfterNavigation } from './components/ScrollAfterNavigation';\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';\nimport { METADATA_UPDATE, URLCHANGE } from './generated/protocol';\nimport { receiveNavigation } from './entryState';\n\n/** A map of MDX component overrides, or a function that receives the platform\n *  {@link DEFAULT_MDX_COMPONENTS} and returns the full map to use. */\nexport type MdxComponents = Record<string, FC> | ((defaults: Record<string, FC>) => Record<string, FC>);\n\n/**\n * Resolve the effective MDX component map from a {@link BootProps.mdxComponents}\n * value (MARKDOWN_SYNTAX_SPEC §11.3):\n * - `undefined` → the platform {@link DEFAULT_MDX_COMPONENTS} (same reference).\n * - a **function** → the full-replace escape hatch, handed the defaults.\n * - a **map** → merged *over* the defaults (`{ ...defaults, ...map }`), so\n *   overriding one component keeps the rest — the phantom-defaults invariant\n *   (§11.2) that stops the MDX missing-reference guard from firing.\n */\nexport const resolveMdxComponents = (mdxComponents?: MdxComponents): Record<string, FC> =>\n  mdxComponents === undefined\n    ? (DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : typeof mdxComponents === 'function'\n    ? mdxComponents(DEFAULT_MDX_COMPONENTS as Record<string, FC>)\n    : { ...(DEFAULT_MDX_COMPONENTS as Record<string, FC>), ...mdxComponents };\n\n/** Options for {@link boot}: MDX overrides, a route table, or an app root. */\nexport type BootProps = {\n  /**\n   * MDX component overrides. A **map** is *merged over* the platform defaults\n   * ({@link DEFAULT_MDX_COMPONENTS}) — so overriding `WikiLink` alone keeps the\n   * default `a` and `Admonition` (MARKDOWN_SYNTAX_SPEC §11.3). Pass a **function**\n   * `(defaults) => map` as the full-replace escape hatch when you want complete\n   * control over the set.\n   */\n  mdxComponents?: MdxComponents;\n  routingSpec?: RoutingSpec;\n  /**\n   * App root rendered directly inside the providers (with full navigation\n   * context), instead of dispatching through a `routingSpec`. Render\n   * `<Routes>`/`<Route>` here for fully dynamic routing — no catch-all rule\n   * boilerplate. Takes precedence over `routingSpec` for what is rendered.\n   */\n  children?: ReactNode;\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\n/** The app shell {@link boot} renders: holds navigation state, subscribes to host\n *  URL + metadata pushes, and renders `children` or the route `<Router />`. */\nexport const TinkerableApp = ({ routingSpec, children }: { routingSpec: RoutingSpec; children?: ReactNode }) => {\n  const [context, setContext] = useState<TinkerableState>(getInitialContext(routingSpec));\n  useEffect(() => {\n    const removeListener = addListener(URLCHANGE, ({ url, entryState, back, forward }) => {\n      // R3-627: record what the host says about this arrival BEFORE the route state\n      // updates, so a consumer reacting to the new route already sees the scratch\n      // and the direction that produced it.\n      receiveNavigation({\n        state: (entryState ?? undefined) as Record<string, unknown> | undefined,\n        direction: back ? 'back' : forward ? 'forward' : 'push',\n      });\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      {/* Capability C: lands cross-page `#fragment` deep-links on their section\n          after the destination tree mounts, uniform for every MDX app (§13.5). */}\n      <ScrollAfterNavigation />\n      {children ?? <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/** The default route table when `boot` is called with no `routingSpec`/`children`:\n *  `/` → main content, `/files/<path>` → the file router, else not-found.\n *  Re-expressed with path templates (SANDBOX_ROUTING_SPEC §7); the file path\n *  surfaces under the `*` wildcard. The catch-all stays a raw RegExp — the\n *  escape hatch — so it anchors `.+` (a non-empty path) exactly as before. */\nexport const DEFAULT_ROUTING_SPEC: RoutingSpec = {\n  routes: [\n    { name: 'MainContent', pattern: '/', element: <MainContent /> },\n    { name: 'FileRouter', pattern: `${FILES_PREFIX}/*`, element: <FileRouter /> },\n    { name: 'ErrorNotFound', pattern: /^(?<path>.+)$/, element: <ErrorNotFound /> },\n  ],\n};\n\n/**\n * Matches any `sandboxPath` so navigation context can be built without a route\n * table. Used when {@link boot} is given `children` (the app owns dispatch via\n * `<Routes>`); the catch-all's `element` is never rendered (children are).\n */\nexport const CATCH_ALL_ROUTING_SPEC: RoutingSpec = {\n  routes: [{ name: 'AppRoot', pattern: /^.*$/, element: null }],\n};\n\n/**\n * Mount an immediately.run app into the sandbox `#root`. The entry point every\n * app calls from `index.tsx`: wires the MDX, module-cache, and navigation\n * providers, then renders the route table (`routingSpec`) or your `children`.\n */\nexport const boot = ({ mdxComponents, routingSpec, children }: BootProps = {}) => {\n  const rootElement = document.getElementById('root');\n  if (!rootElement) {\n    throw new Error('boot requires root HTML element to exist');\n  }\n  const resolvedComponents = resolveMdxComponents(mdxComponents);\n  // `children` own dispatch, so a catch-all keeps navigation working without a\n  // table; otherwise fall back to the default file/main-content routes.\n  const spec = routingSpec ?? (children ? CATCH_ALL_ROUTING_SPEC : DEFAULT_ROUTING_SPEC);\n  const moduleCache = new ModuleCache();\n  const root = createRoot(rootElement);\n  root.render(\n    <StrictMode>\n      <ModuleCacheContextProvider moduleCache={moduleCache}>\n        <MDXProvider components={resolvedComponents}>\n          <BootMarkers />\n          <TinkerableApp routingSpec={spec}>{children}</TinkerableApp>\n        </MDXProvider>\n      </ModuleCacheContextProvider>\n    </StrictMode>,\n  );\n};\n"],"mappings":"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","names":["context"]}

package/dist/components/ScrollRestoration.cjs

@@ -0,0 +1,117 @@
+"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 ScrollRestoration_exports = {};
+__export(ScrollRestoration_exports, {
+  ScrollRestoration: () => ScrollRestoration
+});
+module.exports = __toCommonJS(ScrollRestoration_exports);
+var import_react = require("react");
+var import_entryState = require("../entryState");
+var import_scrollRestore = require("../scrollRestore");
+var import_TinkerableContext = require("../TinkerableContext");
+var import_useEntryState = require("../useEntryState");
+const SCROLL_KEY = "ir.scroll";
+const documentScroller = () => {
+  if (typeof document === "undefined" || typeof window === "undefined") return null;
+  const el = () => document.scrollingElement ?? document.documentElement;
+  return {
+    offset: () => window.scrollY,
+    scrollTo: (top) => window.scrollTo(0, top),
+    scrollHeight: () => el().scrollHeight,
+    clientHeight: () => window.innerHeight,
+    listen: (onScroll) => {
+      window.addEventListener("scroll", onScroll, { passive: true });
+      return () => window.removeEventListener("scroll", onScroll);
+    }
+  };
+};
+const elementScroller = (el) => ({
+  offset: () => el.scrollTop,
+  scrollTo: (top) => {
+    el.scrollTop = top;
+  },
+  scrollHeight: () => el.scrollHeight,
+  clientHeight: () => el.clientHeight,
+  listen: (onScroll) => {
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }
+});
+const ScrollRestoration = ({ scroller } = {}) => {
+  const { value: rememberedOffset } = (0, import_useEntryState.useEntryState)(SCROLL_KEY);
+  const direction = (0, import_useEntryState.useNavigationDirection)();
+  const { navigationState } = (0, import_react.use)(import_TinkerableContext.TinkerableContext);
+  const hasFragment = Boolean(navigationState.hash);
+  const scrollerRef = (0, import_react.useRef)(scroller);
+  scrollerRef.current = scroller;
+  const resolve = () => {
+    const el = scrollerRef.current?.current;
+    return el ? elementScroller(el) : documentScroller();
+  };
+  (0, import_react.useEffect)(() => {
+    return (0, import_entryState.registerEntryStateCollector)(SCROLL_KEY, () => {
+      const s = resolve();
+      const offset = s?.offset() ?? 0;
+      return offset > 0 ? Math.round(offset) : void 0;
+    });
+  }, []);
+  (0, import_react.useEffect)(() => {
+    if (direction === "push") return;
+    if (hasFragment) return;
+    if (typeof rememberedOffset !== "number") return;
+    const s = resolve();
+    if (!s) return;
+    const startedAt = Date.now();
+    let userScrolled = false;
+    let done = false;
+    const finish = () => {
+      done = true;
+      stopListening();
+      observer?.disconnect();
+      timers.forEach(clearTimeout);
+    };
+    const attempt = () => {
+      if (done) return;
+      const action = (0, import_scrollRestore.nextRestoreAction)({
+        target: rememberedOffset,
+        scrollHeight: s.scrollHeight(),
+        clientHeight: s.clientHeight(),
+        current: s.offset(),
+        elapsedMs: Date.now() - startedAt,
+        userScrolled
+      });
+      if (action === "wait") return;
+      if (action === "apply") s.scrollTo(rememberedOffset);
+      finish();
+    };
+    const stopListening = s.listen(() => {
+      if (!done) userScrolled = true;
+    });
+    const observer = typeof MutationObserver === "undefined" ? null : new MutationObserver(() => attempt());
+    observer?.observe(document.body, { childList: true, subtree: true });
+    const timers = [0, 120, 300, 600, import_scrollRestore.RESTORE_DEADLINE_MS].map((ms) => setTimeout(attempt, ms));
+    return finish;
+  }, [rememberedOffset, direction, hasFragment]);
+  return null;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ScrollRestoration
+});
+//# sourceMappingURL=ScrollRestoration.cjs.map

package/dist/components/ScrollRestoration.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/ScrollRestoration.tsx"],"sourcesContent":["// Remember where the reader was, and put them back there on Back (R3-627).\n//\n// Mount once, near the root, beside `ScrollAfterNavigation`. With no props it\n// remembers the document's scroll offset, which is right for an app whose page\n// scrolls; an app that scrolls its own container passes a ref to it.\n//\n// What it does NOT do: fight the reader, fight a deep link, or scroll a page the\n// reader arrived at by clicking a link. Only a history traversal restores, only if\n// the entry carries an offset, and only until the reader touches the scroller.\n\nimport { type RefObject, use, useEffect, useRef } from 'react';\n\nimport { registerEntryStateCollector } from '../entryState';\nimport { nextRestoreAction, RESTORE_DEADLINE_MS } from '../scrollRestore';\nimport { TinkerableContext } from '../TinkerableContext';\nimport { useEntryState, useNavigationDirection } from '../useEntryState';\n\n/** The key this component owns in the entry scratch. One owner per key. */\nconst SCROLL_KEY = 'ir.scroll';\n\n/** The geometry of whatever is scrolling, read uniformly for the document and for a\n *  container, so the decision module never has to care which it is. */\ninterface Scroller {\n  offset(): number;\n  scrollTo(top: number): void;\n  scrollHeight(): number;\n  clientHeight(): number;\n  listen(onScroll: () => void): () => void;\n}\n\nconst documentScroller = (): Scroller | null => {\n  if (typeof document === 'undefined' || typeof window === 'undefined') return null;\n  const el = () => document.scrollingElement ?? document.documentElement;\n  return {\n    offset: () => window.scrollY,\n    scrollTo: (top) => window.scrollTo(0, top),\n    scrollHeight: () => el().scrollHeight,\n    clientHeight: () => window.innerHeight,\n    listen: (onScroll) => {\n      window.addEventListener('scroll', onScroll, { passive: true });\n      return () => window.removeEventListener('scroll', onScroll);\n    },\n  };\n};\n\nconst elementScroller = (el: HTMLElement): Scroller => ({\n  offset: () => el.scrollTop,\n  scrollTo: (top) => {\n    el.scrollTop = top;\n  },\n  scrollHeight: () => el.scrollHeight,\n  clientHeight: () => el.clientHeight,\n  listen: (onScroll) => {\n    el.addEventListener('scroll', onScroll, { passive: true });\n    return () => el.removeEventListener('scroll', onScroll);\n  },\n});\n\nexport interface ScrollRestorationProps {\n  /** The element that scrolls. Omit when the document scrolls. */\n  scroller?: RefObject<HTMLElement | null>;\n}\n\n/**\n * Null-rendering. Remembers the scroller's offset on the entry being left, and\n * restores it when the reader returns to that entry.\n */\nexport const ScrollRestoration = ({ scroller }: ScrollRestorationProps = {}): null => {\n  const { value: rememberedOffset } = useEntryState<number>(SCROLL_KEY);\n  const direction = useNavigationDirection();\n  const { navigationState } = use(TinkerableContext);\n  const hasFragment = Boolean(navigationState.hash);\n  // Read through a ref so the collector registered below is stable for the life of\n  // the component: re-registering per render would churn the one-owner-per-key map.\n  const scrollerRef = useRef(scroller);\n  scrollerRef.current = scroller;\n\n  const resolve = (): Scroller | null => {\n    const el = scrollerRef.current?.current;\n    return el ? elementScroller(el) : documentScroller();\n  };\n\n  // Save: asked at navigation time, from inside `navigate()`.\n  useEffect(() => {\n    return registerEntryStateCollector(SCROLL_KEY, () => {\n      const s = resolve();\n      const offset = s?.offset() ?? 0;\n      // Nothing to remember about the top of a page; leaving the key out keeps the\n      // scratch empty in the common case, so most entries carry no state at all.\n      return offset > 0 ? Math.round(offset) : undefined;\n    });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  // Restore: only on a traversal, only with an offset, and never over a deep link.\n  useEffect(() => {\n    if (direction === 'push') return;\n    if (hasFragment) return; // an explicit #fragment outranks a remembered position\n    if (typeof rememberedOffset !== 'number') return;\n    const s = resolve();\n    if (!s) return;\n\n    const startedAt = Date.now();\n    let userScrolled = false;\n    let done = false;\n\n    const finish = () => {\n      done = true;\n      stopListening();\n      observer?.disconnect();\n      timers.forEach(clearTimeout);\n    };\n\n    const attempt = () => {\n      if (done) return;\n      const action = nextRestoreAction({\n        target: rememberedOffset,\n        scrollHeight: s.scrollHeight(),\n        clientHeight: s.clientHeight(),\n        current: s.offset(),\n        elapsedMs: Date.now() - startedAt,\n        userScrolled,\n      });\n      if (action === 'wait') return;\n      if (action === 'apply') s.scrollTo(rememberedOffset);\n      finish();\n    };\n\n    // The reader wins: the first scroll they make ends the attempt. Registered\n    // before the first attempt so a scroll during that frame is not missed.\n    const stopListening = s.listen(() => {\n      // Our own `scrollTo` fires this too; `done` is set before the event lands\n      // because `finish()` runs synchronously after `apply`.\n      if (!done) userScrolled = true;\n    });\n\n    // The content arrives asynchronously, so sample as it grows: on DOM changes, on\n    // the same ladder `ScrollAfterNavigation` uses, and once at the deadline.\n    const observer = typeof MutationObserver === 'undefined' ? null : new MutationObserver(() => attempt());\n    observer?.observe(document.body, { childList: true, subtree: true });\n    const timers = [0, 120, 300, 600, RESTORE_DEADLINE_MS].map((ms) => setTimeout(attempt, ms));\n\n    return finish;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [rememberedOffset, direction, hasFragment]);\n\n  return null;\n};\n"],"mappings":"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","names":[]}

package/dist/components/ScrollRestoration.d.cts

@@ -0,0 +1,13 @@
+import { RefObject } from 'react';
+
+interface ScrollRestorationProps {
+    /** The element that scrolls. Omit when the document scrolls. */
+    scroller?: RefObject<HTMLElement | null>;
+}
+/**
+ * Null-rendering. Remembers the scroller's offset on the entry being left, and
+ * restores it when the reader returns to that entry.
+ */
+declare const ScrollRestoration: ({ scroller }?: ScrollRestorationProps) => null;
+
+export { ScrollRestoration, type ScrollRestorationProps };

package/dist/components/ScrollRestoration.d.ts

@@ -0,0 +1,13 @@
+import { RefObject } from 'react';
+
+interface ScrollRestorationProps {
+    /** The element that scrolls. Omit when the document scrolls. */
+    scroller?: RefObject<HTMLElement | null>;
+}
+/**
+ * Null-rendering. Remembers the scroller's offset on the entry being left, and
+ * restores it when the reader returns to that entry.
+ */
+declare const ScrollRestoration: ({ scroller }?: ScrollRestorationProps) => null;
+
+export { ScrollRestoration, type ScrollRestorationProps };

package/dist/components/ScrollRestoration.js

@@ -0,0 +1,94 @@
+import "../chunk-VHAA22YE.js";
+import { use, useEffect, useRef } from "react";
+import { registerEntryStateCollector } from "../entryState";
+import { nextRestoreAction, RESTORE_DEADLINE_MS } from "../scrollRestore";
+import { TinkerableContext } from "../TinkerableContext";
+import { useEntryState, useNavigationDirection } from "../useEntryState";
+const SCROLL_KEY = "ir.scroll";
+const documentScroller = () => {
+  if (typeof document === "undefined" || typeof window === "undefined") return null;
+  const el = () => document.scrollingElement ?? document.documentElement;
+  return {
+    offset: () => window.scrollY,
+    scrollTo: (top) => window.scrollTo(0, top),
+    scrollHeight: () => el().scrollHeight,
+    clientHeight: () => window.innerHeight,
+    listen: (onScroll) => {
+      window.addEventListener("scroll", onScroll, { passive: true });
+      return () => window.removeEventListener("scroll", onScroll);
+    }
+  };
+};
+const elementScroller = (el) => ({
+  offset: () => el.scrollTop,
+  scrollTo: (top) => {
+    el.scrollTop = top;
+  },
+  scrollHeight: () => el.scrollHeight,
+  clientHeight: () => el.clientHeight,
+  listen: (onScroll) => {
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }
+});
+const ScrollRestoration = ({ scroller } = {}) => {
+  const { value: rememberedOffset } = useEntryState(SCROLL_KEY);
+  const direction = useNavigationDirection();
+  const { navigationState } = use(TinkerableContext);
+  const hasFragment = Boolean(navigationState.hash);
+  const scrollerRef = useRef(scroller);
+  scrollerRef.current = scroller;
+  const resolve = () => {
+    const el = scrollerRef.current?.current;
+    return el ? elementScroller(el) : documentScroller();
+  };
+  useEffect(() => {
+    return registerEntryStateCollector(SCROLL_KEY, () => {
+      const s = resolve();
+      const offset = s?.offset() ?? 0;
+      return offset > 0 ? Math.round(offset) : void 0;
+    });
+  }, []);
+  useEffect(() => {
+    if (direction === "push") return;
+    if (hasFragment) return;
+    if (typeof rememberedOffset !== "number") return;
+    const s = resolve();
+    if (!s) return;
+    const startedAt = Date.now();
+    let userScrolled = false;
+    let done = false;
+    const finish = () => {
+      done = true;
+      stopListening();
+      observer?.disconnect();
+      timers.forEach(clearTimeout);
+    };
+    const attempt = () => {
+      if (done) return;
+      const action = nextRestoreAction({
+        target: rememberedOffset,
+        scrollHeight: s.scrollHeight(),
+        clientHeight: s.clientHeight(),
+        current: s.offset(),
+        elapsedMs: Date.now() - startedAt,
+        userScrolled
+      });
+      if (action === "wait") return;
+      if (action === "apply") s.scrollTo(rememberedOffset);
+      finish();
+    };
+    const stopListening = s.listen(() => {
+      if (!done) userScrolled = true;
+    });
+    const observer = typeof MutationObserver === "undefined" ? null : new MutationObserver(() => attempt());
+    observer?.observe(document.body, { childList: true, subtree: true });
+    const timers = [0, 120, 300, 600, RESTORE_DEADLINE_MS].map((ms) => setTimeout(attempt, ms));
+    return finish;
+  }, [rememberedOffset, direction, hasFragment]);
+  return null;
+};
+export {
+  ScrollRestoration
+};
+//# sourceMappingURL=ScrollRestoration.js.map

package/dist/components/ScrollRestoration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/ScrollRestoration.tsx"],"sourcesContent":["// Remember where the reader was, and put them back there on Back (R3-627).\n//\n// Mount once, near the root, beside `ScrollAfterNavigation`. With no props it\n// remembers the document's scroll offset, which is right for an app whose page\n// scrolls; an app that scrolls its own container passes a ref to it.\n//\n// What it does NOT do: fight the reader, fight a deep link, or scroll a page the\n// reader arrived at by clicking a link. Only a history traversal restores, only if\n// the entry carries an offset, and only until the reader touches the scroller.\n\nimport { type RefObject, use, useEffect, useRef } from 'react';\n\nimport { registerEntryStateCollector } from '../entryState';\nimport { nextRestoreAction, RESTORE_DEADLINE_MS } from '../scrollRestore';\nimport { TinkerableContext } from '../TinkerableContext';\nimport { useEntryState, useNavigationDirection } from '../useEntryState';\n\n/** The key this component owns in the entry scratch. One owner per key. */\nconst SCROLL_KEY = 'ir.scroll';\n\n/** The geometry of whatever is scrolling, read uniformly for the document and for a\n *  container, so the decision module never has to care which it is. */\ninterface Scroller {\n  offset(): number;\n  scrollTo(top: number): void;\n  scrollHeight(): number;\n  clientHeight(): number;\n  listen(onScroll: () => void): () => void;\n}\n\nconst documentScroller = (): Scroller | null => {\n  if (typeof document === 'undefined' || typeof window === 'undefined') return null;\n  const el = () => document.scrollingElement ?? document.documentElement;\n  return {\n    offset: () => window.scrollY,\n    scrollTo: (top) => window.scrollTo(0, top),\n    scrollHeight: () => el().scrollHeight,\n    clientHeight: () => window.innerHeight,\n    listen: (onScroll) => {\n      window.addEventListener('scroll', onScroll, { passive: true });\n      return () => window.removeEventListener('scroll', onScroll);\n    },\n  };\n};\n\nconst elementScroller = (el: HTMLElement): Scroller => ({\n  offset: () => el.scrollTop,\n  scrollTo: (top) => {\n    el.scrollTop = top;\n  },\n  scrollHeight: () => el.scrollHeight,\n  clientHeight: () => el.clientHeight,\n  listen: (onScroll) => {\n    el.addEventListener('scroll', onScroll, { passive: true });\n    return () => el.removeEventListener('scroll', onScroll);\n  },\n});\n\nexport interface ScrollRestorationProps {\n  /** The element that scrolls. Omit when the document scrolls. */\n  scroller?: RefObject<HTMLElement | null>;\n}\n\n/**\n * Null-rendering. Remembers the scroller's offset on the entry being left, and\n * restores it when the reader returns to that entry.\n */\nexport const ScrollRestoration = ({ scroller }: ScrollRestorationProps = {}): null => {\n  const { value: rememberedOffset } = useEntryState<number>(SCROLL_KEY);\n  const direction = useNavigationDirection();\n  const { navigationState } = use(TinkerableContext);\n  const hasFragment = Boolean(navigationState.hash);\n  // Read through a ref so the collector registered below is stable for the life of\n  // the component: re-registering per render would churn the one-owner-per-key map.\n  const scrollerRef = useRef(scroller);\n  scrollerRef.current = scroller;\n\n  const resolve = (): Scroller | null => {\n    const el = scrollerRef.current?.current;\n    return el ? elementScroller(el) : documentScroller();\n  };\n\n  // Save: asked at navigation time, from inside `navigate()`.\n  useEffect(() => {\n    return registerEntryStateCollector(SCROLL_KEY, () => {\n      const s = resolve();\n      const offset = s?.offset() ?? 0;\n      // Nothing to remember about the top of a page; leaving the key out keeps the\n      // scratch empty in the common case, so most entries carry no state at all.\n      return offset > 0 ? Math.round(offset) : undefined;\n    });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  // Restore: only on a traversal, only with an offset, and never over a deep link.\n  useEffect(() => {\n    if (direction === 'push') return;\n    if (hasFragment) return; // an explicit #fragment outranks a remembered position\n    if (typeof rememberedOffset !== 'number') return;\n    const s = resolve();\n    if (!s) return;\n\n    const startedAt = Date.now();\n    let userScrolled = false;\n    let done = false;\n\n    const finish = () => {\n      done = true;\n      stopListening();\n      observer?.disconnect();\n      timers.forEach(clearTimeout);\n    };\n\n    const attempt = () => {\n      if (done) return;\n      const action = nextRestoreAction({\n        target: rememberedOffset,\n        scrollHeight: s.scrollHeight(),\n        clientHeight: s.clientHeight(),\n        current: s.offset(),\n        elapsedMs: Date.now() - startedAt,\n        userScrolled,\n      });\n      if (action === 'wait') return;\n      if (action === 'apply') s.scrollTo(rememberedOffset);\n      finish();\n    };\n\n    // The reader wins: the first scroll they make ends the attempt. Registered\n    // before the first attempt so a scroll during that frame is not missed.\n    const stopListening = s.listen(() => {\n      // Our own `scrollTo` fires this too; `done` is set before the event lands\n      // because `finish()` runs synchronously after `apply`.\n      if (!done) userScrolled = true;\n    });\n\n    // The content arrives asynchronously, so sample as it grows: on DOM changes, on\n    // the same ladder `ScrollAfterNavigation` uses, and once at the deadline.\n    const observer = typeof MutationObserver === 'undefined' ? null : new MutationObserver(() => attempt());\n    observer?.observe(document.body, { childList: true, subtree: true });\n    const timers = [0, 120, 300, 600, RESTORE_DEADLINE_MS].map((ms) => setTimeout(attempt, ms));\n\n    return finish;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [rememberedOffset, direction, hasFragment]);\n\n  return null;\n};\n"],"mappings":"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","names":[]}

package/dist/entryState.cjs

@@ -0,0 +1,99 @@
+"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 entryState_exports = {};
+__export(entryState_exports, {
+  ENTRY_STATE_MAX_BYTES: () => ENTRY_STATE_MAX_BYTES,
+  getArrivedNavigation: () => getArrivedNavigation,
+  receiveNavigation: () => receiveNavigation,
+  registerEntryStateCollector: () => registerEntryStateCollector,
+  resetEntryState: () => resetEntryState,
+  saveEntryState: () => saveEntryState,
+  subscribeNavigation: () => subscribeNavigation,
+  takeQueuedEntryState: () => takeQueuedEntryState
+});
+module.exports = __toCommonJS(entryState_exports);
+const ENTRY_STATE_MAX_BYTES = 4096;
+const collectors = /* @__PURE__ */ new Map();
+let queued = {};
+let arrived = { state: void 0, direction: "push" };
+const listeners = /* @__PURE__ */ new Set();
+const notify = () => {
+  for (const l of [...listeners]) l();
+};
+const saveEntryState = (key, value) => {
+  queued[key] = value;
+};
+const registerEntryStateCollector = (key, collect) => {
+  collectors.set(key, collect);
+  return () => {
+    if (collectors.get(key) === collect) collectors.delete(key);
+  };
+};
+const takeQueuedEntryState = () => {
+  const out = { ...queued };
+  queued = {};
+  for (const [key, collect] of collectors) {
+    try {
+      const value = collect();
+      if (value !== void 0) out[key] = value;
+    } catch {
+    }
+  }
+  if (Object.keys(out).length === 0) return void 0;
+  let size = 0;
+  try {
+    size = JSON.stringify(out).length;
+  } catch {
+    return void 0;
+  }
+  if (size > ENTRY_STATE_MAX_BYTES) {
+    console.warn(
+      `[Sandbox] entry state is ${size} bytes, over the ${ENTRY_STATE_MAX_BYTES}-byte cap \u2014 dropped. Keep per-entry scratch small (a scroll offset, a few ids), not a cache.`
+    );
+    return void 0;
+  }
+  return out;
+};
+const receiveNavigation = (next) => {
+  arrived = next;
+  notify();
+};
+const getArrivedNavigation = () => arrived;
+const subscribeNavigation = (listener) => {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+};
+const resetEntryState = () => {
+  collectors.clear();
+  queued = {};
+  arrived = { state: void 0, direction: "push" };
+  listeners.clear();
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ENTRY_STATE_MAX_BYTES,
+  getArrivedNavigation,
+  receiveNavigation,
+  registerEntryStateCollector,
+  resetEntryState,
+  saveEntryState,
+  subscribeNavigation,
+  takeQueuedEntryState
+});
+//# sourceMappingURL=entryState.cjs.map

package/dist/entryState.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entryState.ts"],"sourcesContent":["// Per-history-entry scratch (R3-627): a small opaque value an app attaches to the\n// history entry it is LEAVING, and reads back when the browser returns to that entry.\n//\n// Why this exists. The app frame's realm is replaced by an in-app navigation, so\n// nothing in app memory survives it; the host owns the history stack but is at an\n// opaque origin and cannot look inside the frame. So the only way an app can leave\n// itself a bookmark is to hand the host a value to hold against the entry. The host\n// never parses it — it is the app's own value coming back to the app, which is why\n// this does not weaken `EDITOR_AS_APP_SPEC §2` (\"view state … never crosses the\n// boundary\"): the host is a courier, not a reader.\n//\n// Collected at navigation time, not continuously. The app is the one calling\n// `navigate()`, so the scratch is gathered synchronously inside that call — no scroll\n// reporting channel, no throttling, no traffic for a value needed at one instant.\n\n/** How the browser reached the current entry. `push` is an ordinary forward\n *  navigation; `back`/`forward` are traversals, and only a traversal restores. */\nexport type NavigationDirection = 'push' | 'back' | 'forward';\n\n/** Serialized cap for the whole scratch. Past this the scratch is dropped with a\n *  dev-time warning rather than silently truncated: a half-written bookmark that\n *  restores to the wrong place is worse than no bookmark. */\nexport const ENTRY_STATE_MAX_BYTES = 4096;\n\nexport interface ArrivedNavigation {\n  /** The scratch the leaving app left on this entry, if any. */\n  readonly state: Readonly<Record<string, unknown>> | undefined;\n  /** How this entry was reached. */\n  readonly direction: NavigationDirection;\n}\n\ntype Collector = () => unknown;\n\nconst collectors = new Map<string, Collector>();\nlet queued: Record<string, unknown> = {};\nlet arrived: ArrivedNavigation = { state: undefined, direction: 'push' };\nconst listeners = new Set<() => void>();\n\nconst notify = (): void => {\n  for (const l of [...listeners]) l();\n};\n\n/**\n * Queue a value for the entry being left. The last call before a navigation wins.\n * Prefer {@link registerEntryStateCollector} for values that are only knowable at the\n * instant of navigating (a scroll offset is the motivating case).\n */\nexport const saveEntryState = (key: string, value: unknown): void => {\n  queued[key] = value;\n};\n\n/** Register a callback asked for its value at navigation time. Returns its remover.\n *  A second registration for the same key replaces the first — one owner per key. */\nexport const registerEntryStateCollector = (key: string, collect: Collector): (() => void) => {\n  collectors.set(key, collect);\n  return () => {\n    if (collectors.get(key) === collect) collectors.delete(key);\n  };\n};\n\n/**\n * Gather the scratch for the entry being left and clear the queue. Called by\n * `navigate()` — not part of the app-facing surface.\n *\n * A collector that throws is skipped: a bookmark is a convenience, and it must never\n * be able to break a navigation.\n */\nexport const takeQueuedEntryState = (): Record<string, unknown> | undefined => {\n  const out: Record<string, unknown> = { ...queued };\n  queued = {};\n  for (const [key, collect] of collectors) {\n    try {\n      const value = collect();\n      if (value !== undefined) out[key] = value;\n    } catch {\n      /* a collector must not break navigation */\n    }\n  }\n  if (Object.keys(out).length === 0) return undefined;\n  let size = 0;\n  try {\n    size = JSON.stringify(out).length;\n  } catch {\n    return undefined; // not serializable → nothing to hand the host\n  }\n  if (size > ENTRY_STATE_MAX_BYTES) {\n    console.warn(\n      `[Sandbox] entry state is ${size} bytes, over the ${ENTRY_STATE_MAX_BYTES}-byte cap — dropped. ` +\n        `Keep per-entry scratch small (a scroll offset, a few ids), not a cache.`,\n    );\n    return undefined;\n  }\n  return out;\n};\n\n/** Record what the host said about the entry just arrived at. Called by the boot\n *  shell's `urlchange` listener — not part of the app-facing surface. */\nexport const receiveNavigation = (next: ArrivedNavigation): void => {\n  arrived = next;\n  notify();\n};\n\n/** The current arrival, as one stable object so `useSyncExternalStore` can compare\n *  by identity. */\nexport const getArrivedNavigation = (): ArrivedNavigation => arrived;\n\nexport const subscribeNavigation = (listener: () => void): (() => void) => {\n  listeners.add(listener);\n  return () => listeners.delete(listener);\n};\n\n/** Test seam: forget every collector, queued value and arrival. */\nexport const resetEntryState = (): void => {\n  collectors.clear();\n  queued = {};\n  arrived = { state: undefined, direction: 'push' };\n  listeners.clear();\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBO,MAAM,wBAAwB;AAWrC,MAAM,aAAa,oBAAI,IAAuB;AAC9C,IAAI,SAAkC,CAAC;AACvC,IAAI,UAA6B,EAAE,OAAO,QAAW,WAAW,OAAO;AACvE,MAAM,YAAY,oBAAI,IAAgB;AAEtC,MAAM,SAAS,MAAY;AACzB,aAAW,KAAK,CAAC,GAAG,SAAS,EAAG,GAAE;AACpC;AAOO,MAAM,iBAAiB,CAAC,KAAa,UAAyB;AACnE,SAAO,GAAG,IAAI;AAChB;AAIO,MAAM,8BAA8B,CAAC,KAAa,YAAqC;AAC5F,aAAW,IAAI,KAAK,OAAO;AAC3B,SAAO,MAAM;AACX,QAAI,WAAW,IAAI,GAAG,MAAM,QAAS,YAAW,OAAO,GAAG;AAAA,EAC5D;AACF;AASO,MAAM,uBAAuB,MAA2C;AAC7E,QAAM,MAA+B,EAAE,GAAG,OAAO;AACjD,WAAS,CAAC;AACV,aAAW,CAAC,KAAK,OAAO,KAAK,YAAY;AACvC,QAAI;AACF,YAAM,QAAQ,QAAQ;AACtB,UAAI,UAAU,OAAW,KAAI,GAAG,IAAI;AAAA,IACtC,QAAQ;AAAA,IAER;AAAA,EACF;AACA,MAAI,OAAO,KAAK,GAAG,EAAE,WAAW,EAAG,QAAO;AAC1C,MAAI,OAAO;AACX,MAAI;AACF,WAAO,KAAK,UAAU,GAAG,EAAE;AAAA,EAC7B,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,OAAO,uBAAuB;AAChC,YAAQ;AAAA,MACN,4BAA4B,IAAI,oBAAoB,qBAAqB;AAAA,IAE3E;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAIO,MAAM,oBAAoB,CAAC,SAAkC;AAClE,YAAU;AACV,SAAO;AACT;AAIO,MAAM,uBAAuB,MAAyB;AAEtD,MAAM,sBAAsB,CAAC,aAAuC;AACzE,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM,UAAU,OAAO,QAAQ;AACxC;AAGO,MAAM,kBAAkB,MAAY;AACzC,aAAW,MAAM;AACjB,WAAS,CAAC;AACV,YAAU,EAAE,OAAO,QAAW,WAAW,OAAO;AAChD,YAAU,MAAM;AAClB;","names":[]}

package/dist/entryState.d.cts

@@ -0,0 +1,42 @@
+/** How the browser reached the current entry. `push` is an ordinary forward
+ *  navigation; `back`/`forward` are traversals, and only a traversal restores. */
+type NavigationDirection = 'push' | 'back' | 'forward';
+/** Serialized cap for the whole scratch. Past this the scratch is dropped with a
+ *  dev-time warning rather than silently truncated: a half-written bookmark that
+ *  restores to the wrong place is worse than no bookmark. */
+declare const ENTRY_STATE_MAX_BYTES = 4096;
+interface ArrivedNavigation {
+    /** The scratch the leaving app left on this entry, if any. */
+    readonly state: Readonly<Record<string, unknown>> | undefined;
+    /** How this entry was reached. */
+    readonly direction: NavigationDirection;
+}
+type Collector = () => unknown;
+/**
+ * Queue a value for the entry being left. The last call before a navigation wins.
+ * Prefer {@link registerEntryStateCollector} for values that are only knowable at the
+ * instant of navigating (a scroll offset is the motivating case).
+ */
+declare const saveEntryState: (key: string, value: unknown) => void;
+/** Register a callback asked for its value at navigation time. Returns its remover.
+ *  A second registration for the same key replaces the first — one owner per key. */
+declare const registerEntryStateCollector: (key: string, collect: Collector) => (() => void);
+/**
+ * Gather the scratch for the entry being left and clear the queue. Called by
+ * `navigate()` — not part of the app-facing surface.
+ *
+ * A collector that throws is skipped: a bookmark is a convenience, and it must never
+ * be able to break a navigation.
+ */
+declare const takeQueuedEntryState: () => Record<string, unknown> | undefined;
+/** Record what the host said about the entry just arrived at. Called by the boot
+ *  shell's `urlchange` listener — not part of the app-facing surface. */
+declare const receiveNavigation: (next: ArrivedNavigation) => void;
+/** The current arrival, as one stable object so `useSyncExternalStore` can compare
+ *  by identity. */
+declare const getArrivedNavigation: () => ArrivedNavigation;
+declare const subscribeNavigation: (listener: () => void) => (() => void);
+/** Test seam: forget every collector, queued value and arrival. */
+declare const resetEntryState: () => void;
+
+export { type ArrivedNavigation, ENTRY_STATE_MAX_BYTES, type NavigationDirection, getArrivedNavigation, receiveNavigation, registerEntryStateCollector, resetEntryState, saveEntryState, subscribeNavigation, takeQueuedEntryState };