@immediately-run/sdk 0.64.1 → 0.65.0

package/dist/entryState.d.ts

@@ -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 };

package/dist/entryState.js

@@ -0,0 +1,69 @@
+import "./chunk-VHAA22YE.js";
+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();
+};
+export {
+  ENTRY_STATE_MAX_BYTES,
+  getArrivedNavigation,
+  receiveNavigation,
+  registerEntryStateCollector,
+  resetEntryState,
+  saveEntryState,
+  subscribeNavigation,
+  takeQueuedEntryState
+};
+//# sourceMappingURL=entryState.js.map

package/dist/entryState.js.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":";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/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   SafeInclude: () => import_SafeInclude.SafeInclude,
+  ScrollRestoration: () => import_ScrollRestoration.ScrollRestoration,
   getInjectedMetadataEmitter: () => import_injectedBundler.getInjectedMetadataEmitter,
   getInjectedMetadataSnapshot: () => import_injectedBundler.getInjectedMetadataSnapshot
 });
@@ -84,9 +85,14 @@ __reExport(index_exports, require("./collectHeadings"), module.exports);
 __reExport(index_exports, require("./agentContext"), module.exports);
 __reExport(index_exports, require("./fence"), module.exports);
 __reExport(index_exports, require("./platformLink"), module.exports);
+__reExport(index_exports, require("./entryState"), module.exports);
+__reExport(index_exports, require("./useEntryState"), module.exports);
+__reExport(index_exports, require("./scrollRestore"), module.exports);
+var import_ScrollRestoration = require("./components/ScrollRestoration");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SafeInclude,
+  ScrollRestoration,
   getInjectedMetadataEmitter,
   getInjectedMetadataSnapshot,
   ...require("./MDXProvider"),
@@ -146,6 +152,9 @@ __reExport(index_exports, require("./platformLink"), module.exports);
   ...require("./collectHeadings"),
   ...require("./agentContext"),
   ...require("./fence"),
-  ...require("./platformLink")
+  ...require("./platformLink"),
+  ...require("./entryState"),
+  ...require("./useEntryState"),
+  ...require("./scrollRestore")
 });
 //# sourceMappingURL=index.cjs.map

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';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './openRepository'; // R3-476: host-mediated open-in-a-new-tab (route:read)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentPause';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\nexport * from './platformLink';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAQA,yBAA4B;AAC5B,0BAAc,0BATd;AAUA,0BAAc,uCAVd;AAWA,0BAAc,wBAXd;AAYA,0BAAc,qBAZd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,oCAfd;AAgBA,0BAAc,gCAhBd;AAiBA,0BAAc,oBAjBd;AAoBA,0BAAc,6BApBd;AAuBA,6BAAwE;AACxE,0BAAc,mBAxBd;AAyBA,0BAAc,oBAzBd;AA0BA,0BAAc,4BA1Bd;AA2BA,0BAAc,qBA3Bd;AA4BA,0BAAc,yBA5Bd;AA6BA,0BAAc,0BA7Bd;AA8BA,0BAAc,wBA9Bd;AA+BA,0BAAc,4BA/Bd;AAgCA,0BAAc,qBAhCd;AAiCA,0BAAc,qBAjCd;AAkCA,0BAAc,wBAlCd;AAmCA,0BAAc,yBAnCd;AAoCA,0BAAc,sBApCd;AAqCA,0BAAc,kBArCd;AAsCA,0BAAc,kBAtCd;AAuCA,0BAAc,uBAvCd;AAwCA,0BAAc,mBAxCd;AAyCA,0BAAc,sBAzCd;AA0CA,0BAAc,sBA1Cd;AA2CA,0BAAc,6BA3Cd;AA4CA,0BAAc,kBA5Cd;AA6CA,0BAAc,0BA7Cd;AA8CA,0BAAc,kBA9Cd;AA+CA,0BAAc,yBA/Cd;AAgDA,0BAAc,iBAhDd;AAiDA,0BAAc,oBAjDd;AAkDA,0BAAc,oBAlDd;AAmDA,0BAAc,qBAnDd;AAoDA,0BAAc,sBApDd;AAqDA,0BAAc,wBArDd;AAsDA,0BAAc,oBAtDd;AAuDA,0BAAc,sBAvDd;AAwDA,0BAAc,6BAxDd;AAyDA,0BAAc,+BAzDd;AA0DA,0BAAc,2BA1Dd;AA2DA,0BAAc,0BA3Dd;AAgEA,0BAAc,wBAhEd;AAiEA,0BAAc,4BAjEd;AAkEA,0BAAc,yBAlEd;AAmEA,0BAAc,8BAnEd;AAoEA,0BAAc,gCApEd;AAqEA,0BAAc,8BArEd;AAsEA,0BAAc,2BAtEd;AAuEA,0BAAc,oBAvEd;AAwEA,0BAAc,2BAxEd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './MDXProvider';\nexport * from './routing';\nexport * from './boot';\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './openRepository'; // R3-476: host-mediated open-in-a-new-tab (route:read)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentPause';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\nexport * from './platformLink';\n// R3-627: the per-history-entry scratch, and the scroll restoration built on it —\n// Back lands where the reader left, for however many entries deep they go.\nexport * from './entryState';\nexport * from './useEntryState';\nexport * from './scrollRestore';\nexport { ScrollRestoration, type ScrollRestorationProps } from './components/ScrollRestoration';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAQA,yBAA4B;AAC5B,0BAAc,0BATd;AAUA,0BAAc,uCAVd;AAWA,0BAAc,wBAXd;AAYA,0BAAc,qBAZd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,oCAfd;AAgBA,0BAAc,gCAhBd;AAiBA,0BAAc,oBAjBd;AAoBA,0BAAc,6BApBd;AAuBA,6BAAwE;AACxE,0BAAc,mBAxBd;AAyBA,0BAAc,oBAzBd;AA0BA,0BAAc,4BA1Bd;AA2BA,0BAAc,qBA3Bd;AA4BA,0BAAc,yBA5Bd;AA6BA,0BAAc,0BA7Bd;AA8BA,0BAAc,wBA9Bd;AA+BA,0BAAc,4BA/Bd;AAgCA,0BAAc,qBAhCd;AAiCA,0BAAc,qBAjCd;AAkCA,0BAAc,wBAlCd;AAmCA,0BAAc,yBAnCd;AAoCA,0BAAc,sBApCd;AAqCA,0BAAc,kBArCd;AAsCA,0BAAc,kBAtCd;AAuCA,0BAAc,uBAvCd;AAwCA,0BAAc,mBAxCd;AAyCA,0BAAc,sBAzCd;AA0CA,0BAAc,sBA1Cd;AA2CA,0BAAc,6BA3Cd;AA4CA,0BAAc,kBA5Cd;AA6CA,0BAAc,0BA7Cd;AA8CA,0BAAc,kBA9Cd;AA+CA,0BAAc,yBA/Cd;AAgDA,0BAAc,iBAhDd;AAiDA,0BAAc,oBAjDd;AAkDA,0BAAc,oBAlDd;AAmDA,0BAAc,qBAnDd;AAoDA,0BAAc,sBApDd;AAqDA,0BAAc,wBArDd;AAsDA,0BAAc,oBAtDd;AAuDA,0BAAc,sBAvDd;AAwDA,0BAAc,6BAxDd;AAyDA,0BAAc,+BAzDd;AA0DA,0BAAc,2BA1Dd;AA2DA,0BAAc,0BA3Dd;AAgEA,0BAAc,wBAhEd;AAiEA,0BAAc,4BAjEd;AAkEA,0BAAc,yBAlEd;AAmEA,0BAAc,8BAnEd;AAoEA,0BAAc,gCApEd;AAqEA,0BAAc,8BArEd;AAsEA,0BAAc,2BAtEd;AAuEA,0BAAc,oBAvEd;AAwEA,0BAAc,2BAxEd;AA2EA,0BAAc,yBA3Ed;AA4EA,0BAAc,4BA5Ed;AA6EA,0BAAc,4BA7Ed;AA8EA,+BAA+D;","names":[]}

package/dist/index.d.cts

@@ -57,6 +57,10 @@ export { collectHeadings } from './collectHeadings.cjs';
 export { AgentContextAppFields, AgentContextBlock, renderAgentContext, useAgentContext } from './agentContext.cjs';
 export { fenceUntrusted } from './fence.cjs';
 export { PlatformLink, PlatformLinkProps, usePlatformHref } from './platformLink.cjs';
+export { ArrivedNavigation, ENTRY_STATE_MAX_BYTES, NavigationDirection, getArrivedNavigation, receiveNavigation, registerEntryStateCollector, resetEntryState, saveEntryState, subscribeNavigation, takeQueuedEntryState } from './entryState.cjs';
+export { useEntryState, useNavigationDirection } from './useEntryState.cjs';
+export { RESTORE_DEADLINE_MS, RESTORE_EPSILON_PX, RestoreAction, RestoreSample, nextRestoreAction } from './scrollRestore.cjs';
+export { ScrollRestoration, ScrollRestorationProps } from './components/ScrollRestoration.cjs';
 export { Admonition, AdmonitionType } from './components/Admonition.cjs';
 export { FS_PREFIX, LinkSpace, ResolvedLinkTarget, normalizeAbsolute, resolveLinkTarget } from '@immediately-run/mdx-plugins';
 export { GrantRecord, Member, ResolvedUser, Role, SpaceInfo, getSpaceMembers, inviteToSpace, listAllSpaces, listGrants, listSpaces, lookupUser, revokeGrant, setSpaceRole, unshareSpace } from './generated/spaces.cjs';

package/dist/index.d.ts

@@ -57,6 +57,10 @@ export { collectHeadings } from './collectHeadings.js';
 export { AgentContextAppFields, AgentContextBlock, renderAgentContext, useAgentContext } from './agentContext.js';
 export { fenceUntrusted } from './fence.js';
 export { PlatformLink, PlatformLinkProps, usePlatformHref } from './platformLink.js';
+export { ArrivedNavigation, ENTRY_STATE_MAX_BYTES, NavigationDirection, getArrivedNavigation, receiveNavigation, registerEntryStateCollector, resetEntryState, saveEntryState, subscribeNavigation, takeQueuedEntryState } from './entryState.js';
+export { useEntryState, useNavigationDirection } from './useEntryState.js';
+export { RESTORE_DEADLINE_MS, RESTORE_EPSILON_PX, RestoreAction, RestoreSample, nextRestoreAction } from './scrollRestore.js';
+export { ScrollRestoration, ScrollRestorationProps } from './components/ScrollRestoration.js';
 export { Admonition, AdmonitionType } from './components/Admonition.js';
 export { FS_PREFIX, LinkSpace, ResolvedLinkTarget, normalizeAbsolute, resolveLinkTarget } from '@immediately-run/mdx-plugins';
 export { GrantRecord, Member, ResolvedUser, Role, SpaceInfo, getSpaceMembers, inviteToSpace, listAllSpaces, listGrants, listSpaces, lookupUser, revokeGrant, setSpaceRole, unshareSpace } from './generated/spaces.js';

package/dist/index.js

@@ -59,8 +59,13 @@ export * from "./collectHeadings";
 export * from "./agentContext";
 export * from "./fence";
 export * from "./platformLink";
+export * from "./entryState";
+export * from "./useEntryState";
+export * from "./scrollRestore";
+import { ScrollRestoration } from "./components/ScrollRestoration";
 export {
   SafeInclude,
+  ScrollRestoration,
   getInjectedMetadataEmitter,
   getInjectedMetadataSnapshot
 };

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';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './openRepository'; // R3-476: host-mediated open-in-a-new-tab (route:read)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentPause';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\nexport * from './platformLink';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,SAAS,4BAA4B,mCAAmC;AACxE,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,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';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './openRepository'; // R3-476: host-mediated open-in-a-new-tab (route:read)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentPause';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\nexport * from './platformLink';\n// R3-627: the per-history-entry scratch, and the scroll restoration built on it —\n// Back lands where the reader left, for however many entries deep they go.\nexport * from './entryState';\nexport * from './useEntryState';\nexport * from './scrollRestore';\nexport { ScrollRestoration, type ScrollRestorationProps } from './components/ScrollRestoration';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,SAAS,4BAA4B,mCAAmC;AACxE,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,yBAAsD;","names":[]}

package/dist/routing.cjs

@@ -35,6 +35,7 @@ var import_TinkerableContext = require("./TinkerableContext");
 var import_routeMatch = require("./routeMatch");
 var import_urlUtils = require("./urlUtils");
 var import_pathUtils = require("./pathUtils");
+var import_entryState = require("./entryState");
 var import_protocol = require("./generated/protocol");
 const useTinkerableLink = (newSandboxLocation) => {
   const { outerHref, navigationState: navigation } = (0, import_react.use)(import_TinkerableContext.TinkerableContext);
@@ -104,10 +105,12 @@ const navigate = (target, opts) => {
     } catch {
     }
   }
+  const entryState = (0, import_entryState.takeQueuedEntryState)();
   (0, import_sandboxUtils.sendMessage)(import_protocol.URLCHANGE, {
     url: target,
     back: false,
     forward: false,
+    ...entryState ? { entryState } : {},
     ...declared
   });
 };

package/dist/routing.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RouteParams, RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { matchRoute } from './routeMatch';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\nimport { URLCHANGE } from './generated/protocol';\n\n/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule;\n  pathParameters?: Record<string, string>;\n};\n\n/** Build the full outer href for an in-app target (absolute `sandboxPath` or a\n *  path relative to the current route), e.g. for an `href` attribute. */\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation);\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation;\n  }\n  return constructUrl(outerHref, newNavigationState);\n};\n\n/** Find the first rule in `routingSpec` whose pattern matches the current\n *  `sandboxPath`, returning it with the captured params (or `undefined`). */\nexport const applyRoutingRule = (\n  routingSpec: RoutingSpec,\n  navigationState: NavigationState,\n): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    const pathParameters = matchRoute(routingRule.pattern, sandboxPath);\n    if (pathParameters) {\n      return { routingRule, pathParameters };\n    }\n  }\n  return undefined;\n};\n\n/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */\nexport const renderRoute = (routingRule: RoutingRule, params: RouteParams): ReactNode => {\n  if (routingRule.component) {\n    const Component = routingRule.component;\n    return <Component params={params} />;\n  }\n  return routingRule.element ?? routingRule.reactNode ?? null;\n};\n\n/** Render the route matched for the current location (set up by `boot`'s route table). */\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {\n    navigationState: { routingRule, pathParameters },\n  } = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return renderRoute(routingRule, pathParameters ?? {});\n};\n\n/** Read the current route's matched params (`:name` segments and the `*` wildcard). */\nexport const useRouteParams = <T extends RouteParams = RouteParams>(): T =>\n  (use(TinkerableContext).navigationState.pathParameters ?? {}) as T;\n\n/**\n * Read the current route: the matched rule's `name`, its `params`, the app-owned\n * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,\n * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.\n */\nexport const useRoute = () => {\n  const { navigationState } = use(TinkerableContext);\n  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;\n  return {\n    name: routingRule?.name,\n    params: (pathParameters ?? {}) as RouteParams,\n    sandboxPath,\n    mode,\n    provider,\n    namespace,\n    repository,\n    ref,\n  };\n};\n\n/**\n * Navigate within the app. Messages the host to update the URL; the host then\n * pushes the new href back, which drives the actual route change.\n *\n * `opts.viewedDocument` (R3-268) optionally declares which WORKING-TREE file\n * this destination renders — a tri-state rider on the navigation event:\n *  - omit the option entirely → the host derives the hint from the URL's\n *    `files/` suffix convention (the zero-SDK default);\n *  - `null` → this view shows no file (clears the highlight — tag pages,\n *    search, home views);\n *  - a repo-relative path (the CORPUS path under dispatch — only the viewer\n *    can map its own key space) → the file explorer highlights it.\n * The hint is highlight-only by contract (it never scrolls, never moves focus\n * or panes, never switches the editor) and is validated host-side for\n * existence — a wrong path degrades to \"no highlight\", never an error. The\n * host remembers declarations per URL, so back/forward reproduces them\n * without re-announcement.\n */\n// R3-268: an app-registered rule mapping a navigation TARGET to its viewed\n// document, consulted by `navigate()` whenever the caller did not declare one\n// explicitly. Registered ONCE (e.g. at boot) so an app whose links all flow\n// through `<Link>`/`navigate` gets correct declarations everywhere without\n// threading an option through every call site. Return `undefined` for \"no\n// declaration\" (the host falls back to the URL convention), `null` for \"this\n// view shows no file\", or a working-tree repo-relative path.\nlet viewedDocumentResolver: ((targetHref: string) => string | null | undefined) | null = null;\n\n/** Register the app's route→viewed-document rule (R3-268); pass `null` to clear. */\nexport const setViewedDocumentResolver = (\n  resolver: ((targetHref: string) => string | null | undefined) | null,\n): void => {\n  viewedDocumentResolver = resolver;\n};\n\nexport const navigate = (target: string, opts?: { viewedDocument?: string | null }) => {\n  console.log(`[Sandbox] Navigating to ${target}`);\n  // Explicit option first; else the registered resolver; else nothing on the\n  // wire (the host derives from the URL convention). A resolver throw is\n  // swallowed to \"no declaration\" — a mapping bug must never break navigation.\n  let declared: { viewedDocument: string | null } | Record<string, never> = {};\n  if (opts && 'viewedDocument' in opts) {\n    declared = { viewedDocument: opts.viewedDocument ?? null };\n  } else if (viewedDocumentResolver) {\n    try {\n      const v = viewedDocumentResolver(target);\n      if (v !== undefined) declared = { viewedDocument: v };\n    } catch {\n      /* no declaration */\n    }\n  }\n  sendMessage(URLCHANGE, {\n    url: target,\n    back: false,\n    forward: false,\n    ...declared,\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkDW;AAjDX,mBAAgC;AAEhC,0BAA4B;AAC5B,+BAAmD;AAEnD,wBAA2B;AAC3B,sBAA0D;AAC1D,uBAA0B;AAC1B,sBAA0B;AAUnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,QAAI,kBAAI,0CAAiB;AACxE,MAAI,yBAAqB,6BAAY,oBAAoB,UAAU;AACnE,MAAI,KAAC,gCAAe,kBAAkB,GAAG;AACvC,uBAAmB,kBAAc,4BAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,aAAO,8BAAa,WAAW,kBAAkB;AACnD;AAIO,MAAM,mBAAmB,CAC9B,aACA,oBACmC;AACnC,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,UAAM,qBAAiB,8BAAW,YAAY,SAAS,WAAW;AAClE,QAAI,gBAAgB;AAClB,aAAO,EAAE,aAAa,eAAe;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAGO,MAAM,cAAc,CAAC,aAA0B,WAAmC;AACvF,MAAI,YAAY,WAAW;AACzB,UAAM,YAAY,YAAY;AAC9B,WAAO,4CAAC,aAAU,QAAgB;AAAA,EACpC;AACA,SAAO,YAAY,WAAW,YAAY,aAAa;AACzD;AAGO,MAAM,SAAS,MAAM;AAC1B,QAAM,cAAU,yBAAW,0CAAiB;AAC5C,QAAM;AAAA,IACJ,iBAAiB,EAAE,aAAa,eAAe;AAAA,EACjD,IAAI;AACJ,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY,aAAa,kBAAkB,CAAC,CAAC;AACtD;AAGO,MAAM,iBAAiB,UAC3B,kBAAI,0CAAiB,EAAE,gBAAgB,kBAAkB,CAAC;AAOtD,MAAM,WAAW,MAAM;AAC5B,QAAM,EAAE,gBAAgB,QAAI,kBAAI,0CAAiB;AACjD,QAAM,EAAE,aAAa,gBAAgB,aAAa,MAAM,UAAU,WAAW,YAAY,IAAI,IAAI;AACjG,SAAO;AAAA,IACL,MAAM,aAAa;AAAA,IACnB,QAAS,kBAAkB,CAAC;AAAA,IAC5B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AA2BA,IAAI,yBAAqF;AAGlF,MAAM,4BAA4B,CACvC,aACS;AACT,2BAAyB;AAC3B;AAEO,MAAM,WAAW,CAAC,QAAgB,SAA8C;AACrF,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAI/C,MAAI,WAAsE,CAAC;AAC3E,MAAI,QAAQ,oBAAoB,MAAM;AACpC,eAAW,EAAE,gBAAgB,KAAK,kBAAkB,KAAK;AAAA,EAC3D,WAAW,wBAAwB;AACjC,QAAI;AACF,YAAM,IAAI,uBAAuB,MAAM;AACvC,UAAI,MAAM,OAAW,YAAW,EAAE,gBAAgB,EAAE;AAAA,IACtD,QAAQ;AAAA,IAER;AAAA,EACF;AACA,uCAAY,2BAAW;AAAA,IACrB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,GAAG;AAAA,EACL,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RouteParams, RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { matchRoute } from './routeMatch';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\nimport { takeQueuedEntryState } from './entryState';\nimport { URLCHANGE } from './generated/protocol';\n\n/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule;\n  pathParameters?: Record<string, string>;\n};\n\n/** Build the full outer href for an in-app target (absolute `sandboxPath` or a\n *  path relative to the current route), e.g. for an `href` attribute. */\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation);\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation;\n  }\n  return constructUrl(outerHref, newNavigationState);\n};\n\n/** Find the first rule in `routingSpec` whose pattern matches the current\n *  `sandboxPath`, returning it with the captured params (or `undefined`). */\nexport const applyRoutingRule = (\n  routingSpec: RoutingSpec,\n  navigationState: NavigationState,\n): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    const pathParameters = matchRoute(routingRule.pattern, sandboxPath);\n    if (pathParameters) {\n      return { routingRule, pathParameters };\n    }\n  }\n  return undefined;\n};\n\n/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */\nexport const renderRoute = (routingRule: RoutingRule, params: RouteParams): ReactNode => {\n  if (routingRule.component) {\n    const Component = routingRule.component;\n    return <Component params={params} />;\n  }\n  return routingRule.element ?? routingRule.reactNode ?? null;\n};\n\n/** Render the route matched for the current location (set up by `boot`'s route table). */\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {\n    navigationState: { routingRule, pathParameters },\n  } = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return renderRoute(routingRule, pathParameters ?? {});\n};\n\n/** Read the current route's matched params (`:name` segments and the `*` wildcard). */\nexport const useRouteParams = <T extends RouteParams = RouteParams>(): T =>\n  (use(TinkerableContext).navigationState.pathParameters ?? {}) as T;\n\n/**\n * Read the current route: the matched rule's `name`, its `params`, the app-owned\n * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,\n * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.\n */\nexport const useRoute = () => {\n  const { navigationState } = use(TinkerableContext);\n  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;\n  return {\n    name: routingRule?.name,\n    params: (pathParameters ?? {}) as RouteParams,\n    sandboxPath,\n    mode,\n    provider,\n    namespace,\n    repository,\n    ref,\n  };\n};\n\n/**\n * Navigate within the app. Messages the host to update the URL; the host then\n * pushes the new href back, which drives the actual route change.\n *\n * `opts.viewedDocument` (R3-268) optionally declares which WORKING-TREE file\n * this destination renders — a tri-state rider on the navigation event:\n *  - omit the option entirely → the host derives the hint from the URL's\n *    `files/` suffix convention (the zero-SDK default);\n *  - `null` → this view shows no file (clears the highlight — tag pages,\n *    search, home views);\n *  - a repo-relative path (the CORPUS path under dispatch — only the viewer\n *    can map its own key space) → the file explorer highlights it.\n * The hint is highlight-only by contract (it never scrolls, never moves focus\n * or panes, never switches the editor) and is validated host-side for\n * existence — a wrong path degrades to \"no highlight\", never an error. The\n * host remembers declarations per URL, so back/forward reproduces them\n * without re-announcement.\n */\n// R3-268: an app-registered rule mapping a navigation TARGET to its viewed\n// document, consulted by `navigate()` whenever the caller did not declare one\n// explicitly. Registered ONCE (e.g. at boot) so an app whose links all flow\n// through `<Link>`/`navigate` gets correct declarations everywhere without\n// threading an option through every call site. Return `undefined` for \"no\n// declaration\" (the host falls back to the URL convention), `null` for \"this\n// view shows no file\", or a working-tree repo-relative path.\nlet viewedDocumentResolver: ((targetHref: string) => string | null | undefined) | null = null;\n\n/** Register the app's route→viewed-document rule (R3-268); pass `null` to clear. */\nexport const setViewedDocumentResolver = (\n  resolver: ((targetHref: string) => string | null | undefined) | null,\n): void => {\n  viewedDocumentResolver = resolver;\n};\n\nexport const navigate = (target: string, opts?: { viewedDocument?: string | null }) => {\n  console.log(`[Sandbox] Navigating to ${target}`);\n  // Explicit option first; else the registered resolver; else nothing on the\n  // wire (the host derives from the URL convention). A resolver throw is\n  // swallowed to \"no declaration\" — a mapping bug must never break navigation.\n  let declared: { viewedDocument: string | null } | Record<string, never> = {};\n  if (opts && 'viewedDocument' in opts) {\n    declared = { viewedDocument: opts.viewedDocument ?? null };\n  } else if (viewedDocumentResolver) {\n    try {\n      const v = viewedDocumentResolver(target);\n      if (v !== undefined) declared = { viewedDocument: v };\n    } catch {\n      /* no declaration */\n    }\n  }\n  // The scratch for the entry we are LEAVING, gathered synchronously here because\n  // this call is the one moment the app knows a navigation is happening (R3-627).\n  // The host stamps it on the current entry before pushing the target, and hands it\n  // back if the reader ever returns; it never parses it.\n  const entryState = takeQueuedEntryState();\n  sendMessage(URLCHANGE, {\n    url: target,\n    back: false,\n    forward: false,\n    ...(entryState ? { entryState } : {}),\n    ...declared,\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmDW;AAlDX,mBAAgC;AAEhC,0BAA4B;AAC5B,+BAAmD;AAEnD,wBAA2B;AAC3B,sBAA0D;AAC1D,uBAA0B;AAC1B,wBAAqC;AACrC,sBAA0B;AAUnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,QAAI,kBAAI,0CAAiB;AACxE,MAAI,yBAAqB,6BAAY,oBAAoB,UAAU;AACnE,MAAI,KAAC,gCAAe,kBAAkB,GAAG;AACvC,uBAAmB,kBAAc,4BAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,aAAO,8BAAa,WAAW,kBAAkB;AACnD;AAIO,MAAM,mBAAmB,CAC9B,aACA,oBACmC;AACnC,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,UAAM,qBAAiB,8BAAW,YAAY,SAAS,WAAW;AAClE,QAAI,gBAAgB;AAClB,aAAO,EAAE,aAAa,eAAe;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAGO,MAAM,cAAc,CAAC,aAA0B,WAAmC;AACvF,MAAI,YAAY,WAAW;AACzB,UAAM,YAAY,YAAY;AAC9B,WAAO,4CAAC,aAAU,QAAgB;AAAA,EACpC;AACA,SAAO,YAAY,WAAW,YAAY,aAAa;AACzD;AAGO,MAAM,SAAS,MAAM;AAC1B,QAAM,cAAU,yBAAW,0CAAiB;AAC5C,QAAM;AAAA,IACJ,iBAAiB,EAAE,aAAa,eAAe;AAAA,EACjD,IAAI;AACJ,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY,aAAa,kBAAkB,CAAC,CAAC;AACtD;AAGO,MAAM,iBAAiB,UAC3B,kBAAI,0CAAiB,EAAE,gBAAgB,kBAAkB,CAAC;AAOtD,MAAM,WAAW,MAAM;AAC5B,QAAM,EAAE,gBAAgB,QAAI,kBAAI,0CAAiB;AACjD,QAAM,EAAE,aAAa,gBAAgB,aAAa,MAAM,UAAU,WAAW,YAAY,IAAI,IAAI;AACjG,SAAO;AAAA,IACL,MAAM,aAAa;AAAA,IACnB,QAAS,kBAAkB,CAAC;AAAA,IAC5B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AA2BA,IAAI,yBAAqF;AAGlF,MAAM,4BAA4B,CACvC,aACS;AACT,2BAAyB;AAC3B;AAEO,MAAM,WAAW,CAAC,QAAgB,SAA8C;AACrF,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAI/C,MAAI,WAAsE,CAAC;AAC3E,MAAI,QAAQ,oBAAoB,MAAM;AACpC,eAAW,EAAE,gBAAgB,KAAK,kBAAkB,KAAK;AAAA,EAC3D,WAAW,wBAAwB;AACjC,QAAI;AACF,YAAM,IAAI,uBAAuB,MAAM;AACvC,UAAI,MAAM,OAAW,YAAW,EAAE,gBAAgB,EAAE;AAAA,IACtD,QAAQ;AAAA,IAER;AAAA,EACF;AAKA,QAAM,iBAAa,wCAAqB;AACxC,uCAAY,2BAAW;AAAA,IACrB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,GAAI,aAAa,EAAE,WAAW,IAAI,CAAC;AAAA,IACnC,GAAG;AAAA,EACL,CAAC;AACH;","names":[]}

package/dist/routing.js

@@ -6,6 +6,7 @@ import { TinkerableContext } from "./TinkerableContext";
 import { matchRoute } from "./routeMatch";
 import { constructUrl, isAbsolutePath, parseTarget } from "./urlUtils";
 import { joinPaths } from "./pathUtils";
+import { takeQueuedEntryState } from "./entryState";
 import { URLCHANGE } from "./generated/protocol";
 const useTinkerableLink = (newSandboxLocation) => {
   const { outerHref, navigationState: navigation } = use(TinkerableContext);
@@ -75,10 +76,12 @@ const navigate = (target, opts) => {
     } catch {
     }
   }
+  const entryState = takeQueuedEntryState();
   sendMessage(URLCHANGE, {
     url: target,
     back: false,
     forward: false,
+    ...entryState ? { entryState } : {},
     ...declared
   });
 };

package/dist/routing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RouteParams, RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { matchRoute } from './routeMatch';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\nimport { URLCHANGE } from './generated/protocol';\n\n/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule;\n  pathParameters?: Record<string, string>;\n};\n\n/** Build the full outer href for an in-app target (absolute `sandboxPath` or a\n *  path relative to the current route), e.g. for an `href` attribute. */\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation);\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation;\n  }\n  return constructUrl(outerHref, newNavigationState);\n};\n\n/** Find the first rule in `routingSpec` whose pattern matches the current\n *  `sandboxPath`, returning it with the captured params (or `undefined`). */\nexport const applyRoutingRule = (\n  routingSpec: RoutingSpec,\n  navigationState: NavigationState,\n): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    const pathParameters = matchRoute(routingRule.pattern, sandboxPath);\n    if (pathParameters) {\n      return { routingRule, pathParameters };\n    }\n  }\n  return undefined;\n};\n\n/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */\nexport const renderRoute = (routingRule: RoutingRule, params: RouteParams): ReactNode => {\n  if (routingRule.component) {\n    const Component = routingRule.component;\n    return <Component params={params} />;\n  }\n  return routingRule.element ?? routingRule.reactNode ?? null;\n};\n\n/** Render the route matched for the current location (set up by `boot`'s route table). */\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {\n    navigationState: { routingRule, pathParameters },\n  } = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return renderRoute(routingRule, pathParameters ?? {});\n};\n\n/** Read the current route's matched params (`:name` segments and the `*` wildcard). */\nexport const useRouteParams = <T extends RouteParams = RouteParams>(): T =>\n  (use(TinkerableContext).navigationState.pathParameters ?? {}) as T;\n\n/**\n * Read the current route: the matched rule's `name`, its `params`, the app-owned\n * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,\n * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.\n */\nexport const useRoute = () => {\n  const { navigationState } = use(TinkerableContext);\n  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;\n  return {\n    name: routingRule?.name,\n    params: (pathParameters ?? {}) as RouteParams,\n    sandboxPath,\n    mode,\n    provider,\n    namespace,\n    repository,\n    ref,\n  };\n};\n\n/**\n * Navigate within the app. Messages the host to update the URL; the host then\n * pushes the new href back, which drives the actual route change.\n *\n * `opts.viewedDocument` (R3-268) optionally declares which WORKING-TREE file\n * this destination renders — a tri-state rider on the navigation event:\n *  - omit the option entirely → the host derives the hint from the URL's\n *    `files/` suffix convention (the zero-SDK default);\n *  - `null` → this view shows no file (clears the highlight — tag pages,\n *    search, home views);\n *  - a repo-relative path (the CORPUS path under dispatch — only the viewer\n *    can map its own key space) → the file explorer highlights it.\n * The hint is highlight-only by contract (it never scrolls, never moves focus\n * or panes, never switches the editor) and is validated host-side for\n * existence — a wrong path degrades to \"no highlight\", never an error. The\n * host remembers declarations per URL, so back/forward reproduces them\n * without re-announcement.\n */\n// R3-268: an app-registered rule mapping a navigation TARGET to its viewed\n// document, consulted by `navigate()` whenever the caller did not declare one\n// explicitly. Registered ONCE (e.g. at boot) so an app whose links all flow\n// through `<Link>`/`navigate` gets correct declarations everywhere without\n// threading an option through every call site. Return `undefined` for \"no\n// declaration\" (the host falls back to the URL convention), `null` for \"this\n// view shows no file\", or a working-tree repo-relative path.\nlet viewedDocumentResolver: ((targetHref: string) => string | null | undefined) | null = null;\n\n/** Register the app's route→viewed-document rule (R3-268); pass `null` to clear. */\nexport const setViewedDocumentResolver = (\n  resolver: ((targetHref: string) => string | null | undefined) | null,\n): void => {\n  viewedDocumentResolver = resolver;\n};\n\nexport const navigate = (target: string, opts?: { viewedDocument?: string | null }) => {\n  console.log(`[Sandbox] Navigating to ${target}`);\n  // Explicit option first; else the registered resolver; else nothing on the\n  // wire (the host derives from the URL convention). A resolver throw is\n  // swallowed to \"no declaration\" — a mapping bug must never break navigation.\n  let declared: { viewedDocument: string | null } | Record<string, never> = {};\n  if (opts && 'viewedDocument' in opts) {\n    declared = { viewedDocument: opts.viewedDocument ?? null };\n  } else if (viewedDocumentResolver) {\n    try {\n      const v = viewedDocumentResolver(target);\n      if (v !== undefined) declared = { viewedDocument: v };\n    } catch {\n      /* no declaration */\n    }\n  }\n  sendMessage(URLCHANGE, {\n    url: target,\n    back: false,\n    forward: false,\n    ...declared,\n  });\n};\n"],"mappings":";AAkDW;AAjDX,SAAS,KAAK,kBAAkB;AAEhC,SAAS,mBAAmB;AAC5B,SAA0B,yBAAyB;AAEnD,SAAS,kBAAkB;AAC3B,SAAS,cAAc,gBAAgB,mBAAmB;AAC1D,SAAS,iBAAiB;AAC1B,SAAS,iBAAiB;AAUnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,IAAI,IAAI,iBAAiB;AACxE,MAAI,qBAAqB,YAAY,oBAAoB,UAAU;AACnE,MAAI,CAAC,eAAe,kBAAkB,GAAG;AACvC,uBAAmB,cAAc,UAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,SAAO,aAAa,WAAW,kBAAkB;AACnD;AAIO,MAAM,mBAAmB,CAC9B,aACA,oBACmC;AACnC,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,UAAM,iBAAiB,WAAW,YAAY,SAAS,WAAW;AAClE,QAAI,gBAAgB;AAClB,aAAO,EAAE,aAAa,eAAe;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAGO,MAAM,cAAc,CAAC,aAA0B,WAAmC;AACvF,MAAI,YAAY,WAAW;AACzB,UAAM,YAAY,YAAY;AAC9B,WAAO,oBAAC,aAAU,QAAgB;AAAA,EACpC;AACA,SAAO,YAAY,WAAW,YAAY,aAAa;AACzD;AAGO,MAAM,SAAS,MAAM;AAC1B,QAAM,UAAU,WAAW,iBAAiB;AAC5C,QAAM;AAAA,IACJ,iBAAiB,EAAE,aAAa,eAAe;AAAA,EACjD,IAAI;AACJ,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY,aAAa,kBAAkB,CAAC,CAAC;AACtD;AAGO,MAAM,iBAAiB,MAC3B,IAAI,iBAAiB,EAAE,gBAAgB,kBAAkB,CAAC;AAOtD,MAAM,WAAW,MAAM;AAC5B,QAAM,EAAE,gBAAgB,IAAI,IAAI,iBAAiB;AACjD,QAAM,EAAE,aAAa,gBAAgB,aAAa,MAAM,UAAU,WAAW,YAAY,IAAI,IAAI;AACjG,SAAO;AAAA,IACL,MAAM,aAAa;AAAA,IACnB,QAAS,kBAAkB,CAAC;AAAA,IAC5B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AA2BA,IAAI,yBAAqF;AAGlF,MAAM,4BAA4B,CACvC,aACS;AACT,2BAAyB;AAC3B;AAEO,MAAM,WAAW,CAAC,QAAgB,SAA8C;AACrF,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAI/C,MAAI,WAAsE,CAAC;AAC3E,MAAI,QAAQ,oBAAoB,MAAM;AACpC,eAAW,EAAE,gBAAgB,KAAK,kBAAkB,KAAK;AAAA,EAC3D,WAAW,wBAAwB;AACjC,QAAI;AACF,YAAM,IAAI,uBAAuB,MAAM;AACvC,UAAI,MAAM,OAAW,YAAW,EAAE,gBAAgB,EAAE;AAAA,IACtD,QAAQ;AAAA,IAER;AAAA,EACF;AACA,cAAY,WAAW;AAAA,IACrB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,GAAG;AAAA,EACL,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RouteParams, RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { matchRoute } from './routeMatch';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\nimport { takeQueuedEntryState } from './entryState';\nimport { URLCHANGE } from './generated/protocol';\n\n/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule;\n  pathParameters?: Record<string, string>;\n};\n\n/** Build the full outer href for an in-app target (absolute `sandboxPath` or a\n *  path relative to the current route), e.g. for an `href` attribute. */\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation);\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation;\n  }\n  return constructUrl(outerHref, newNavigationState);\n};\n\n/** Find the first rule in `routingSpec` whose pattern matches the current\n *  `sandboxPath`, returning it with the captured params (or `undefined`). */\nexport const applyRoutingRule = (\n  routingSpec: RoutingSpec,\n  navigationState: NavigationState,\n): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    const pathParameters = matchRoute(routingRule.pattern, sandboxPath);\n    if (pathParameters) {\n      return { routingRule, pathParameters };\n    }\n  }\n  return undefined;\n};\n\n/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */\nexport const renderRoute = (routingRule: RoutingRule, params: RouteParams): ReactNode => {\n  if (routingRule.component) {\n    const Component = routingRule.component;\n    return <Component params={params} />;\n  }\n  return routingRule.element ?? routingRule.reactNode ?? null;\n};\n\n/** Render the route matched for the current location (set up by `boot`'s route table). */\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {\n    navigationState: { routingRule, pathParameters },\n  } = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return renderRoute(routingRule, pathParameters ?? {});\n};\n\n/** Read the current route's matched params (`:name` segments and the `*` wildcard). */\nexport const useRouteParams = <T extends RouteParams = RouteParams>(): T =>\n  (use(TinkerableContext).navigationState.pathParameters ?? {}) as T;\n\n/**\n * Read the current route: the matched rule's `name`, its `params`, the app-owned\n * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,\n * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.\n */\nexport const useRoute = () => {\n  const { navigationState } = use(TinkerableContext);\n  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;\n  return {\n    name: routingRule?.name,\n    params: (pathParameters ?? {}) as RouteParams,\n    sandboxPath,\n    mode,\n    provider,\n    namespace,\n    repository,\n    ref,\n  };\n};\n\n/**\n * Navigate within the app. Messages the host to update the URL; the host then\n * pushes the new href back, which drives the actual route change.\n *\n * `opts.viewedDocument` (R3-268) optionally declares which WORKING-TREE file\n * this destination renders — a tri-state rider on the navigation event:\n *  - omit the option entirely → the host derives the hint from the URL's\n *    `files/` suffix convention (the zero-SDK default);\n *  - `null` → this view shows no file (clears the highlight — tag pages,\n *    search, home views);\n *  - a repo-relative path (the CORPUS path under dispatch — only the viewer\n *    can map its own key space) → the file explorer highlights it.\n * The hint is highlight-only by contract (it never scrolls, never moves focus\n * or panes, never switches the editor) and is validated host-side for\n * existence — a wrong path degrades to \"no highlight\", never an error. The\n * host remembers declarations per URL, so back/forward reproduces them\n * without re-announcement.\n */\n// R3-268: an app-registered rule mapping a navigation TARGET to its viewed\n// document, consulted by `navigate()` whenever the caller did not declare one\n// explicitly. Registered ONCE (e.g. at boot) so an app whose links all flow\n// through `<Link>`/`navigate` gets correct declarations everywhere without\n// threading an option through every call site. Return `undefined` for \"no\n// declaration\" (the host falls back to the URL convention), `null` for \"this\n// view shows no file\", or a working-tree repo-relative path.\nlet viewedDocumentResolver: ((targetHref: string) => string | null | undefined) | null = null;\n\n/** Register the app's route→viewed-document rule (R3-268); pass `null` to clear. */\nexport const setViewedDocumentResolver = (\n  resolver: ((targetHref: string) => string | null | undefined) | null,\n): void => {\n  viewedDocumentResolver = resolver;\n};\n\nexport const navigate = (target: string, opts?: { viewedDocument?: string | null }) => {\n  console.log(`[Sandbox] Navigating to ${target}`);\n  // Explicit option first; else the registered resolver; else nothing on the\n  // wire (the host derives from the URL convention). A resolver throw is\n  // swallowed to \"no declaration\" — a mapping bug must never break navigation.\n  let declared: { viewedDocument: string | null } | Record<string, never> = {};\n  if (opts && 'viewedDocument' in opts) {\n    declared = { viewedDocument: opts.viewedDocument ?? null };\n  } else if (viewedDocumentResolver) {\n    try {\n      const v = viewedDocumentResolver(target);\n      if (v !== undefined) declared = { viewedDocument: v };\n    } catch {\n      /* no declaration */\n    }\n  }\n  // The scratch for the entry we are LEAVING, gathered synchronously here because\n  // this call is the one moment the app knows a navigation is happening (R3-627).\n  // The host stamps it on the current entry before pushing the target, and hands it\n  // back if the reader ever returns; it never parses it.\n  const entryState = takeQueuedEntryState();\n  sendMessage(URLCHANGE, {\n    url: target,\n    back: false,\n    forward: false,\n    ...(entryState ? { entryState } : {}),\n    ...declared,\n  });\n};\n"],"mappings":";AAmDW;AAlDX,SAAS,KAAK,kBAAkB;AAEhC,SAAS,mBAAmB;AAC5B,SAA0B,yBAAyB;AAEnD,SAAS,kBAAkB;AAC3B,SAAS,cAAc,gBAAgB,mBAAmB;AAC1D,SAAS,iBAAiB;AAC1B,SAAS,4BAA4B;AACrC,SAAS,iBAAiB;AAUnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,IAAI,IAAI,iBAAiB;AACxE,MAAI,qBAAqB,YAAY,oBAAoB,UAAU;AACnE,MAAI,CAAC,eAAe,kBAAkB,GAAG;AACvC,uBAAmB,cAAc,UAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,SAAO,aAAa,WAAW,kBAAkB;AACnD;AAIO,MAAM,mBAAmB,CAC9B,aACA,oBACmC;AACnC,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,UAAM,iBAAiB,WAAW,YAAY,SAAS,WAAW;AAClE,QAAI,gBAAgB;AAClB,aAAO,EAAE,aAAa,eAAe;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAGO,MAAM,cAAc,CAAC,aAA0B,WAAmC;AACvF,MAAI,YAAY,WAAW;AACzB,UAAM,YAAY,YAAY;AAC9B,WAAO,oBAAC,aAAU,QAAgB;AAAA,EACpC;AACA,SAAO,YAAY,WAAW,YAAY,aAAa;AACzD;AAGO,MAAM,SAAS,MAAM;AAC1B,QAAM,UAAU,WAAW,iBAAiB;AAC5C,QAAM;AAAA,IACJ,iBAAiB,EAAE,aAAa,eAAe;AAAA,EACjD,IAAI;AACJ,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY,aAAa,kBAAkB,CAAC,CAAC;AACtD;AAGO,MAAM,iBAAiB,MAC3B,IAAI,iBAAiB,EAAE,gBAAgB,kBAAkB,CAAC;AAOtD,MAAM,WAAW,MAAM;AAC5B,QAAM,EAAE,gBAAgB,IAAI,IAAI,iBAAiB;AACjD,QAAM,EAAE,aAAa,gBAAgB,aAAa,MAAM,UAAU,WAAW,YAAY,IAAI,IAAI;AACjG,SAAO;AAAA,IACL,MAAM,aAAa;AAAA,IACnB,QAAS,kBAAkB,CAAC;AAAA,IAC5B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AA2BA,IAAI,yBAAqF;AAGlF,MAAM,4BAA4B,CACvC,aACS;AACT,2BAAyB;AAC3B;AAEO,MAAM,WAAW,CAAC,QAAgB,SAA8C;AACrF,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAI/C,MAAI,WAAsE,CAAC;AAC3E,MAAI,QAAQ,oBAAoB,MAAM;AACpC,eAAW,EAAE,gBAAgB,KAAK,kBAAkB,KAAK;AAAA,EAC3D,WAAW,wBAAwB;AACjC,QAAI;AACF,YAAM,IAAI,uBAAuB,MAAM;AACvC,UAAI,MAAM,OAAW,YAAW,EAAE,gBAAgB,EAAE;AAAA,IACtD,QAAQ;AAAA,IAER;AAAA,EACF;AAKA,QAAM,aAAa,qBAAqB;AACxC,cAAY,WAAW;AAAA,IACrB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,GAAI,aAAa,EAAE,WAAW,IAAI,CAAC;AAAA,IACnC,GAAG;AAAA,EACL,CAAC;AACH;","names":[]}

package/dist/scrollRestore.cjs

@@ -0,0 +1,43 @@
+"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 scrollRestore_exports = {};
+__export(scrollRestore_exports, {
+  RESTORE_DEADLINE_MS: () => RESTORE_DEADLINE_MS,
+  RESTORE_EPSILON_PX: () => RESTORE_EPSILON_PX,
+  nextRestoreAction: () => nextRestoreAction
+});
+module.exports = __toCommonJS(scrollRestore_exports);
+const RESTORE_DEADLINE_MS = 900;
+const RESTORE_EPSILON_PX = 2;
+const nextRestoreAction = (sample) => {
+  const { target, scrollHeight, clientHeight, current, elapsedMs, userScrolled } = sample;
+  if (!Number.isFinite(target) || target <= 0) return "abandon";
+  if (userScrolled) return "abandon";
+  if (Math.abs(current - target) <= RESTORE_EPSILON_PX) return "apply";
+  if (elapsedMs >= RESTORE_DEADLINE_MS) return "abandon";
+  const reachable = Math.max(0, scrollHeight - clientHeight);
+  return reachable >= target ? "apply" : "wait";
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RESTORE_DEADLINE_MS,
+  RESTORE_EPSILON_PX,
+  nextRestoreAction
+});
+//# sourceMappingURL=scrollRestore.cjs.map

package/dist/scrollRestore.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scrollRestore.ts"],"sourcesContent":["// Deciding WHEN a remembered scroll offset may be applied after a back/forward\n// traversal (R3-627). Pure: no DOM, no React, no timers — the caller samples the\n// geometry and this says what to do with the sample.\n//\n// The failure this exists to prevent: an app's document grows as it renders, so an\n// offset applied on arrival is clamped to whatever height exists at that instant and\n// the reader lands near the top — the very defect the feature is meant to remove. So\n// the restore waits until the content is tall enough to hold the offset, and gives up\n// rather than fighting either the clock or the reader.\n\n/** A geometry sample of the scroller, plus how the attempt is going. */\nexport interface RestoreSample {\n  /** The remembered offset we are trying to reach. */\n  target: number;\n  /** The scroller's full scrollable height right now. */\n  scrollHeight: number;\n  /** The scroller's visible height right now. */\n  clientHeight: number;\n  /** Where the scroller is right now. */\n  current: number;\n  /** Milliseconds since the restore began. */\n  elapsedMs: number;\n  /** Whether the reader has scrolled since the restore began. */\n  userScrolled: boolean;\n}\n\n/** What the caller should do with this sample. */\nexport type RestoreAction = 'apply' | 'wait' | 'abandon';\n\n/** How long to keep waiting for the content to grow before giving up. Matches the\n *  give-up window `ScrollAfterNavigation` already uses for fragments, so the two\n *  navigation-scroll behaviours settle on the same timescale. */\nexport const RESTORE_DEADLINE_MS = 900;\n\n/** How close counts as arrived. Sub-pixel differences and fractional device pixels\n *  must not keep a restore looping. */\nexport const RESTORE_EPSILON_PX = 2;\n\n/**\n * The one decision, given a sample.\n *\n * - `abandon` — the reader has taken over, or the deadline passed. Never fight a\n *   user, and never scroll a page they have already started reading.\n * - `apply` — the content can hold the offset (or the offset is already reached,\n *   within {@link RESTORE_EPSILON_PX}); scroll and finish.\n * - `wait` — the content is still too short; sample again.\n *\n * A non-finite or negative target is treated as nothing to restore (`abandon`), so a\n * corrupt scratch value can never move the page.\n */\nexport const nextRestoreAction = (sample: RestoreSample): RestoreAction => {\n  const { target, scrollHeight, clientHeight, current, elapsedMs, userScrolled } = sample;\n  if (!Number.isFinite(target) || target <= 0) return 'abandon';\n  if (userScrolled) return 'abandon';\n  if (Math.abs(current - target) <= RESTORE_EPSILON_PX) return 'apply';\n  if (elapsedMs >= RESTORE_DEADLINE_MS) return 'abandon';\n  // The furthest this scroller can currently reach. Applying before the content is\n  // this tall is what clamps the reader to the top.\n  const reachable = Math.max(0, scrollHeight - clientHeight);\n  return reachable >= target ? 'apply' : 'wait';\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgCO,MAAM,sBAAsB;AAI5B,MAAM,qBAAqB;AAc3B,MAAM,oBAAoB,CAAC,WAAyC;AACzE,QAAM,EAAE,QAAQ,cAAc,cAAc,SAAS,WAAW,aAAa,IAAI;AACjF,MAAI,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,EAAG,QAAO;AACpD,MAAI,aAAc,QAAO;AACzB,MAAI,KAAK,IAAI,UAAU,MAAM,KAAK,mBAAoB,QAAO;AAC7D,MAAI,aAAa,oBAAqB,QAAO;AAG7C,QAAM,YAAY,KAAK,IAAI,GAAG,eAAe,YAAY;AACzD,SAAO,aAAa,SAAS,UAAU;AACzC;","names":[]}

package/dist/scrollRestore.d.cts

@@ -0,0 +1,39 @@
+/** A geometry sample of the scroller, plus how the attempt is going. */
+interface RestoreSample {
+    /** The remembered offset we are trying to reach. */
+    target: number;
+    /** The scroller's full scrollable height right now. */
+    scrollHeight: number;
+    /** The scroller's visible height right now. */
+    clientHeight: number;
+    /** Where the scroller is right now. */
+    current: number;
+    /** Milliseconds since the restore began. */
+    elapsedMs: number;
+    /** Whether the reader has scrolled since the restore began. */
+    userScrolled: boolean;
+}
+/** What the caller should do with this sample. */
+type RestoreAction = 'apply' | 'wait' | 'abandon';
+/** How long to keep waiting for the content to grow before giving up. Matches the
+ *  give-up window `ScrollAfterNavigation` already uses for fragments, so the two
+ *  navigation-scroll behaviours settle on the same timescale. */
+declare const RESTORE_DEADLINE_MS = 900;
+/** How close counts as arrived. Sub-pixel differences and fractional device pixels
+ *  must not keep a restore looping. */
+declare const RESTORE_EPSILON_PX = 2;
+/**
+ * The one decision, given a sample.
+ *
+ * - `abandon` — the reader has taken over, or the deadline passed. Never fight a
+ *   user, and never scroll a page they have already started reading.
+ * - `apply` — the content can hold the offset (or the offset is already reached,
+ *   within {@link RESTORE_EPSILON_PX}); scroll and finish.
+ * - `wait` — the content is still too short; sample again.
+ *
+ * A non-finite or negative target is treated as nothing to restore (`abandon`), so a
+ * corrupt scratch value can never move the page.
+ */
+declare const nextRestoreAction: (sample: RestoreSample) => RestoreAction;
+
+export { RESTORE_DEADLINE_MS, RESTORE_EPSILON_PX, type RestoreAction, type RestoreSample, nextRestoreAction };

package/dist/scrollRestore.d.ts

@@ -0,0 +1,39 @@
+/** A geometry sample of the scroller, plus how the attempt is going. */
+interface RestoreSample {
+    /** The remembered offset we are trying to reach. */
+    target: number;
+    /** The scroller's full scrollable height right now. */
+    scrollHeight: number;
+    /** The scroller's visible height right now. */
+    clientHeight: number;
+    /** Where the scroller is right now. */
+    current: number;
+    /** Milliseconds since the restore began. */
+    elapsedMs: number;
+    /** Whether the reader has scrolled since the restore began. */
+    userScrolled: boolean;
+}
+/** What the caller should do with this sample. */
+type RestoreAction = 'apply' | 'wait' | 'abandon';
+/** How long to keep waiting for the content to grow before giving up. Matches the
+ *  give-up window `ScrollAfterNavigation` already uses for fragments, so the two
+ *  navigation-scroll behaviours settle on the same timescale. */
+declare const RESTORE_DEADLINE_MS = 900;
+/** How close counts as arrived. Sub-pixel differences and fractional device pixels
+ *  must not keep a restore looping. */
+declare const RESTORE_EPSILON_PX = 2;
+/**
+ * The one decision, given a sample.
+ *
+ * - `abandon` — the reader has taken over, or the deadline passed. Never fight a
+ *   user, and never scroll a page they have already started reading.
+ * - `apply` — the content can hold the offset (or the offset is already reached,
+ *   within {@link RESTORE_EPSILON_PX}); scroll and finish.
+ * - `wait` — the content is still too short; sample again.
+ *
+ * A non-finite or negative target is treated as nothing to restore (`abandon`), so a
+ * corrupt scratch value can never move the page.
+ */
+declare const nextRestoreAction: (sample: RestoreSample) => RestoreAction;
+
+export { RESTORE_DEADLINE_MS, RESTORE_EPSILON_PX, type RestoreAction, type RestoreSample, nextRestoreAction };

package/dist/scrollRestore.js

@@ -0,0 +1,18 @@
+import "./chunk-VHAA22YE.js";
+const RESTORE_DEADLINE_MS = 900;
+const RESTORE_EPSILON_PX = 2;
+const nextRestoreAction = (sample) => {
+  const { target, scrollHeight, clientHeight, current, elapsedMs, userScrolled } = sample;
+  if (!Number.isFinite(target) || target <= 0) return "abandon";
+  if (userScrolled) return "abandon";
+  if (Math.abs(current - target) <= RESTORE_EPSILON_PX) return "apply";
+  if (elapsedMs >= RESTORE_DEADLINE_MS) return "abandon";
+  const reachable = Math.max(0, scrollHeight - clientHeight);
+  return reachable >= target ? "apply" : "wait";
+};
+export {
+  RESTORE_DEADLINE_MS,
+  RESTORE_EPSILON_PX,
+  nextRestoreAction
+};
+//# sourceMappingURL=scrollRestore.js.map

package/dist/scrollRestore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scrollRestore.ts"],"sourcesContent":["// Deciding WHEN a remembered scroll offset may be applied after a back/forward\n// traversal (R3-627). Pure: no DOM, no React, no timers — the caller samples the\n// geometry and this says what to do with the sample.\n//\n// The failure this exists to prevent: an app's document grows as it renders, so an\n// offset applied on arrival is clamped to whatever height exists at that instant and\n// the reader lands near the top — the very defect the feature is meant to remove. So\n// the restore waits until the content is tall enough to hold the offset, and gives up\n// rather than fighting either the clock or the reader.\n\n/** A geometry sample of the scroller, plus how the attempt is going. */\nexport interface RestoreSample {\n  /** The remembered offset we are trying to reach. */\n  target: number;\n  /** The scroller's full scrollable height right now. */\n  scrollHeight: number;\n  /** The scroller's visible height right now. */\n  clientHeight: number;\n  /** Where the scroller is right now. */\n  current: number;\n  /** Milliseconds since the restore began. */\n  elapsedMs: number;\n  /** Whether the reader has scrolled since the restore began. */\n  userScrolled: boolean;\n}\n\n/** What the caller should do with this sample. */\nexport type RestoreAction = 'apply' | 'wait' | 'abandon';\n\n/** How long to keep waiting for the content to grow before giving up. Matches the\n *  give-up window `ScrollAfterNavigation` already uses for fragments, so the two\n *  navigation-scroll behaviours settle on the same timescale. */\nexport const RESTORE_DEADLINE_MS = 900;\n\n/** How close counts as arrived. Sub-pixel differences and fractional device pixels\n *  must not keep a restore looping. */\nexport const RESTORE_EPSILON_PX = 2;\n\n/**\n * The one decision, given a sample.\n *\n * - `abandon` — the reader has taken over, or the deadline passed. Never fight a\n *   user, and never scroll a page they have already started reading.\n * - `apply` — the content can hold the offset (or the offset is already reached,\n *   within {@link RESTORE_EPSILON_PX}); scroll and finish.\n * - `wait` — the content is still too short; sample again.\n *\n * A non-finite or negative target is treated as nothing to restore (`abandon`), so a\n * corrupt scratch value can never move the page.\n */\nexport const nextRestoreAction = (sample: RestoreSample): RestoreAction => {\n  const { target, scrollHeight, clientHeight, current, elapsedMs, userScrolled } = sample;\n  if (!Number.isFinite(target) || target <= 0) return 'abandon';\n  if (userScrolled) return 'abandon';\n  if (Math.abs(current - target) <= RESTORE_EPSILON_PX) return 'apply';\n  if (elapsedMs >= RESTORE_DEADLINE_MS) return 'abandon';\n  // The furthest this scroller can currently reach. Applying before the content is\n  // this tall is what clamps the reader to the top.\n  const reachable = Math.max(0, scrollHeight - clientHeight);\n  return reachable >= target ? 'apply' : 'wait';\n};\n"],"mappings":";AAgCO,MAAM,sBAAsB;AAI5B,MAAM,qBAAqB;AAc3B,MAAM,oBAAoB,CAAC,WAAyC;AACzE,QAAM,EAAE,QAAQ,cAAc,cAAc,SAAS,WAAW,aAAa,IAAI;AACjF,MAAI,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,EAAG,QAAO;AACpD,MAAI,aAAc,QAAO;AACzB,MAAI,KAAK,IAAI,UAAU,MAAM,KAAK,mBAAoB,QAAO;AAC7D,MAAI,aAAa,oBAAqB,QAAO;AAG7C,QAAM,YAAY,KAAK,IAAI,GAAG,eAAe,YAAY;AACzD,SAAO,aAAa,SAAS,UAAU;AACzC;","names":[]}

package/dist/useEntryState.cjs

@@ -0,0 +1,41 @@
+"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 useEntryState_exports = {};
+__export(useEntryState_exports, {
+  useEntryState: () => useEntryState,
+  useNavigationDirection: () => useNavigationDirection
+});
+module.exports = __toCommonJS(useEntryState_exports);
+var import_react = require("react");
+var import_entryState = require("./entryState");
+const useEntryState = (key) => {
+  const arrived = (0, import_react.useSyncExternalStore)(import_entryState.subscribeNavigation, import_entryState.getArrivedNavigation, import_entryState.getArrivedNavigation);
+  const save = (0, import_react.useCallback)((value) => (0, import_entryState.saveEntryState)(key, value), [key]);
+  return { value: arrived.state?.[key], save };
+};
+const useNavigationDirection = () => {
+  const arrived = (0, import_react.useSyncExternalStore)(import_entryState.subscribeNavigation, import_entryState.getArrivedNavigation, import_entryState.getArrivedNavigation);
+  return arrived.direction;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useEntryState,
+  useNavigationDirection
+});
+//# sourceMappingURL=useEntryState.cjs.map

package/dist/useEntryState.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useEntryState.ts"],"sourcesContent":["// React surface over the per-history-entry scratch (R3-627). The store itself is in\n// `entryState.ts` and is framework-free; this file is the thin binding so a component\n// re-renders when the host tells the frame which entry it just arrived at.\n\nimport { useCallback, useSyncExternalStore } from 'react';\n\nimport { getArrivedNavigation, saveEntryState, subscribeNavigation, type NavigationDirection } from './entryState';\n\n/**\n * Read the value this app left on the current history entry, and queue the value to\n * leave on the entry the next navigation departs from.\n *\n * `value` is `undefined` on an ordinary forward navigation — there is no bookmark for\n * a page being visited for the first time — and on a traversal to an entry that was\n * stamped by nothing (a navigation the app did not initiate).\n *\n * `save` queues; it does not send. The queued value travels with the next\n * `navigate()`, which is the only moment the app knows an entry is being left.\n */\nexport const useEntryState = <T>(key: string): { value: T | undefined; save: (value: T) => void } => {\n  const arrived = useSyncExternalStore(subscribeNavigation, getArrivedNavigation, getArrivedNavigation);\n  const save = useCallback((value: T) => saveEntryState(key, value), [key]);\n  return { value: arrived.state?.[key] as T | undefined, save };\n};\n\n/**\n * How the browser reached the page being rendered: `push` for an ordinary\n * navigation, `back`/`forward` for a history traversal.\n *\n * An app that resets its own view on arrival — scrolling a container to the top is\n * the usual one — should stand down on a traversal, so a restored position is not\n * immediately thrown away.\n */\nexport const useNavigationDirection = (): NavigationDirection => {\n  const arrived = useSyncExternalStore(subscribeNavigation, getArrivedNavigation, getArrivedNavigation);\n  return arrived.direction;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,mBAAkD;AAElD,wBAAoG;AAa7F,MAAM,gBAAgB,CAAI,QAAoE;AACnG,QAAM,cAAU,mCAAqB,uCAAqB,wCAAsB,sCAAoB;AACpG,QAAM,WAAO,0BAAY,CAAC,cAAa,kCAAe,KAAK,KAAK,GAAG,CAAC,GAAG,CAAC;AACxE,SAAO,EAAE,OAAO,QAAQ,QAAQ,GAAG,GAAoB,KAAK;AAC9D;AAUO,MAAM,yBAAyB,MAA2B;AAC/D,QAAM,cAAU,mCAAqB,uCAAqB,wCAAsB,sCAAoB;AACpG,SAAO,QAAQ;AACjB;","names":[]}