@immediately-run/sdk 0.64.1 → 0.66.0

package/dist/protocolSchemes.js

@@ -10,6 +10,7 @@ import {
   PROTOCOL_LAUNCH,
   PROTOCOL_LLM,
   PROTOCOL_LOCALSTORE,
+  PROTOCOL_OPENLINK,
   PROTOCOL_OPENREPO,
   PROTOCOL_RECENTS,
   PROTOCOL_SECRETS,
@@ -32,6 +33,7 @@ const SCHEMES = {
   [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),
   [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),
   [PROTOCOL_LOCALSTORE]: schemeOf(PROTOCOL_LOCALSTORE),
+  [PROTOCOL_OPENLINK]: schemeOf(PROTOCOL_OPENLINK),
   [PROTOCOL_OPENREPO]: schemeOf(PROTOCOL_OPENREPO),
   [PROTOCOL_RECENTS]: schemeOf(PROTOCOL_RECENTS),
   [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),

package/dist/protocolSchemes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocolSchemes.ts"],"sourcesContent":["// The `protocol-<scheme>` SCHEMES, derived from the wire names.\n//\n// `protocolRequest(scheme, method, params)` takes the scheme — `'theme'` — while the\n// wire name the frame dispatches on is `'protocol-theme'`; the frame adds the prefix.\n// So the typed service wrappers cannot pass the published `PROTOCOL_*` constant\n// directly, and spelling the scheme inline would put a second, unguarded copy of the\n// name back in the tree — exactly what R3-274c removes.\n//\n// Instead the schemes are *derived* from the wire names, keyed BY the wire name:\n//\n//   protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])\n//\n// Keying by the constant is what makes the derivation unfalsifiable — there is no\n// second place to name the family, so there is no pair to get wrong. `schemeOf`\n// returns a template-literal conditional, so each value has a literal type (`'theme'`),\n// which buys two more things:\n//\n//   - a wire name that stops matching `protocol-*` stops compiling here, rather than\n//     silently producing an empty scheme at runtime;\n//   - `check-protocol-snapshot.mjs` resolves `SCHEMES[PROTOCOL_THEME]` through the type\n//     checker exactly like a plain literal, so the call sites stay visible to the gate.\n//\n// One export, deliberately: `./*` is a public subpath, so every name added here is\n// public API forever (ways_of_working §6, additive-only).\n//\n// This module is NOT generated — the derivation is the content — so it lives outside\n// `src/generated/`.\nimport {\n  PROTOCOL_ANALYTICS,\n  PROTOCOL_CONTRIBUTE,\n  PROTOCOL_DND,\n  PROTOCOL_EDITOR,\n  PROTOCOL_FEED,\n  PROTOCOL_FETCH,\n  PROTOCOL_IPC,\n  PROTOCOL_LAUNCH,\n  PROTOCOL_LLM,\n  PROTOCOL_LOCALSTORE,\n  PROTOCOL_OPENREPO,\n  PROTOCOL_RECENTS,\n  PROTOCOL_SECRETS,\n  PROTOCOL_SETTINGS,\n  PROTOCOL_SPACES,\n  PROTOCOL_TASK,\n  PROTOCOL_THEME,\n  PROTOCOL_VCS,\n} from './generated/protocol';\n\nconst PREFIX = 'protocol-';\n\n/** The scheme half of a `protocol-<scheme>` wire name. */\ntype SchemeOf<N extends string> = N extends `${typeof PREFIX}${infer S}` ? S : never;\n\n/**\n * `'protocol-theme'` → `'theme'`, as a literal type.\n *\n * The cast is the only place the derivation is asserted rather than computed; the\n * `N extends \\`protocol-${string}\\`` bound is what makes it sound — a wire name that is\n * not scheme-shaped is a compile error at the call, not a `never` at runtime.\n */\nconst schemeOf = <N extends `${typeof PREFIX}${string}`>(name: N): SchemeOf<N> =>\n  name.slice(PREFIX.length) as SchemeOf<N>;\n\n/** Every `protocol-*` scheme the SDK speaks, keyed by its wire name. */\nexport const SCHEMES = {\n  [PROTOCOL_ANALYTICS]: schemeOf(PROTOCOL_ANALYTICS),\n  [PROTOCOL_CONTRIBUTE]: schemeOf(PROTOCOL_CONTRIBUTE),\n  [PROTOCOL_DND]: schemeOf(PROTOCOL_DND),\n  [PROTOCOL_EDITOR]: schemeOf(PROTOCOL_EDITOR),\n  [PROTOCOL_FEED]: schemeOf(PROTOCOL_FEED),\n  [PROTOCOL_FETCH]: schemeOf(PROTOCOL_FETCH),\n  [PROTOCOL_IPC]: schemeOf(PROTOCOL_IPC),\n  [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),\n  [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),\n  [PROTOCOL_LOCALSTORE]: schemeOf(PROTOCOL_LOCALSTORE),\n  [PROTOCOL_OPENREPO]: schemeOf(PROTOCOL_OPENREPO),\n  [PROTOCOL_RECENTS]: schemeOf(PROTOCOL_RECENTS),\n  [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),\n  [PROTOCOL_SETTINGS]: schemeOf(PROTOCOL_SETTINGS),\n  [PROTOCOL_SPACES]: schemeOf(PROTOCOL_SPACES),\n  [PROTOCOL_TASK]: schemeOf(PROTOCOL_TASK),\n  [PROTOCOL_THEME]: schemeOf(PROTOCOL_THEME),\n  [PROTOCOL_VCS]: schemeOf(PROTOCOL_VCS),\n} as const;\n"],"mappings":";AA2BA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,MAAM,SAAS;AAYf,MAAM,WAAW,CAAwC,SACvD,KAAK,MAAM,OAAO,MAAM;AAGnB,MAAM,UAAU;AAAA,EACrB,CAAC,kBAAkB,GAAG,SAAS,kBAAkB;AAAA,EACjD,CAAC,mBAAmB,GAAG,SAAS,mBAAmB;AAAA,EACnD,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,mBAAmB,GAAG,SAAS,mBAAmB;AAAA,EACnD,CAAC,iBAAiB,GAAG,SAAS,iBAAiB;AAAA,EAC/C,CAAC,gBAAgB,GAAG,SAAS,gBAAgB;AAAA,EAC7C,CAAC,gBAAgB,GAAG,SAAS,gBAAgB;AAAA,EAC7C,CAAC,iBAAiB,GAAG,SAAS,iBAAiB;AAAA,EAC/C,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AACvC;","names":[]}
+{"version":3,"sources":["../src/protocolSchemes.ts"],"sourcesContent":["// The `protocol-<scheme>` SCHEMES, derived from the wire names.\n//\n// `protocolRequest(scheme, method, params)` takes the scheme — `'theme'` — while the\n// wire name the frame dispatches on is `'protocol-theme'`; the frame adds the prefix.\n// So the typed service wrappers cannot pass the published `PROTOCOL_*` constant\n// directly, and spelling the scheme inline would put a second, unguarded copy of the\n// name back in the tree — exactly what R3-274c removes.\n//\n// Instead the schemes are *derived* from the wire names, keyed BY the wire name:\n//\n//   protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])\n//\n// Keying by the constant is what makes the derivation unfalsifiable — there is no\n// second place to name the family, so there is no pair to get wrong. `schemeOf`\n// returns a template-literal conditional, so each value has a literal type (`'theme'`),\n// which buys two more things:\n//\n//   - a wire name that stops matching `protocol-*` stops compiling here, rather than\n//     silently producing an empty scheme at runtime;\n//   - `check-protocol-snapshot.mjs` resolves `SCHEMES[PROTOCOL_THEME]` through the type\n//     checker exactly like a plain literal, so the call sites stay visible to the gate.\n//\n// One export, deliberately: `./*` is a public subpath, so every name added here is\n// public API forever (ways_of_working §6, additive-only).\n//\n// This module is NOT generated — the derivation is the content — so it lives outside\n// `src/generated/`.\nimport {\n  PROTOCOL_ANALYTICS,\n  PROTOCOL_CONTRIBUTE,\n  PROTOCOL_DND,\n  PROTOCOL_EDITOR,\n  PROTOCOL_FEED,\n  PROTOCOL_FETCH,\n  PROTOCOL_IPC,\n  PROTOCOL_LAUNCH,\n  PROTOCOL_LLM,\n  PROTOCOL_LOCALSTORE,\n  PROTOCOL_OPENLINK,\n  PROTOCOL_OPENREPO,\n  PROTOCOL_RECENTS,\n  PROTOCOL_SECRETS,\n  PROTOCOL_SETTINGS,\n  PROTOCOL_SPACES,\n  PROTOCOL_TASK,\n  PROTOCOL_THEME,\n  PROTOCOL_VCS,\n} from './generated/protocol';\n\nconst PREFIX = 'protocol-';\n\n/** The scheme half of a `protocol-<scheme>` wire name. */\ntype SchemeOf<N extends string> = N extends `${typeof PREFIX}${infer S}` ? S : never;\n\n/**\n * `'protocol-theme'` → `'theme'`, as a literal type.\n *\n * The cast is the only place the derivation is asserted rather than computed; the\n * `N extends \\`protocol-${string}\\`` bound is what makes it sound — a wire name that is\n * not scheme-shaped is a compile error at the call, not a `never` at runtime.\n */\nconst schemeOf = <N extends `${typeof PREFIX}${string}`>(name: N): SchemeOf<N> =>\n  name.slice(PREFIX.length) as SchemeOf<N>;\n\n/** Every `protocol-*` scheme the SDK speaks, keyed by its wire name. */\nexport const SCHEMES = {\n  [PROTOCOL_ANALYTICS]: schemeOf(PROTOCOL_ANALYTICS),\n  [PROTOCOL_CONTRIBUTE]: schemeOf(PROTOCOL_CONTRIBUTE),\n  [PROTOCOL_DND]: schemeOf(PROTOCOL_DND),\n  [PROTOCOL_EDITOR]: schemeOf(PROTOCOL_EDITOR),\n  [PROTOCOL_FEED]: schemeOf(PROTOCOL_FEED),\n  [PROTOCOL_FETCH]: schemeOf(PROTOCOL_FETCH),\n  [PROTOCOL_IPC]: schemeOf(PROTOCOL_IPC),\n  [PROTOCOL_LAUNCH]: schemeOf(PROTOCOL_LAUNCH),\n  [PROTOCOL_LLM]: schemeOf(PROTOCOL_LLM),\n  [PROTOCOL_LOCALSTORE]: schemeOf(PROTOCOL_LOCALSTORE),\n  [PROTOCOL_OPENLINK]: schemeOf(PROTOCOL_OPENLINK),\n  [PROTOCOL_OPENREPO]: schemeOf(PROTOCOL_OPENREPO),\n  [PROTOCOL_RECENTS]: schemeOf(PROTOCOL_RECENTS),\n  [PROTOCOL_SECRETS]: schemeOf(PROTOCOL_SECRETS),\n  [PROTOCOL_SETTINGS]: schemeOf(PROTOCOL_SETTINGS),\n  [PROTOCOL_SPACES]: schemeOf(PROTOCOL_SPACES),\n  [PROTOCOL_TASK]: schemeOf(PROTOCOL_TASK),\n  [PROTOCOL_THEME]: schemeOf(PROTOCOL_THEME),\n  [PROTOCOL_VCS]: schemeOf(PROTOCOL_VCS),\n} as const;\n"],"mappings":";AA2BA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,MAAM,SAAS;AAYf,MAAM,WAAW,CAAwC,SACvD,KAAK,MAAM,OAAO,MAAM;AAGnB,MAAM,UAAU;AAAA,EACrB,CAAC,kBAAkB,GAAG,SAAS,kBAAkB;AAAA,EACjD,CAAC,mBAAmB,GAAG,SAAS,mBAAmB;AAAA,EACnD,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,YAAY,GAAG,SAAS,YAAY;AAAA,EACrC,CAAC,mBAAmB,GAAG,SAAS,mBAAmB;AAAA,EACnD,CAAC,iBAAiB,GAAG,SAAS,iBAAiB;AAAA,EAC/C,CAAC,iBAAiB,GAAG,SAAS,iBAAiB;AAAA,EAC/C,CAAC,gBAAgB,GAAG,SAAS,gBAAgB;AAAA,EAC7C,CAAC,gBAAgB,GAAG,SAAS,gBAAgB;AAAA,EAC7C,CAAC,iBAAiB,GAAG,SAAS,iBAAiB;AAAA,EAC/C,CAAC,eAAe,GAAG,SAAS,eAAe;AAAA,EAC3C,CAAC,aAAa,GAAG,SAAS,aAAa;AAAA,EACvC,CAAC,cAAc,GAAG,SAAS,cAAc;AAAA,EACzC,CAAC,YAAY,GAAG,SAAS,YAAY;AACvC;","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":[]}

package/dist/useEntryState.d.cts

@@ -0,0 +1,28 @@
+import { NavigationDirection } from './entryState.cjs';
+
+/**
+ * Read the value this app left on the current history entry, and queue the value to
+ * leave on the entry the next navigation departs from.
+ *
+ * `value` is `undefined` on an ordinary forward navigation — there is no bookmark for
+ * a page being visited for the first time — and on a traversal to an entry that was
+ * stamped by nothing (a navigation the app did not initiate).
+ *
+ * `save` queues; it does not send. The queued value travels with the next
+ * `navigate()`, which is the only moment the app knows an entry is being left.
+ */
+declare const useEntryState: <T>(key: string) => {
+    value: T | undefined;
+    save: (value: T) => void;
+};
+/**
+ * How the browser reached the page being rendered: `push` for an ordinary
+ * navigation, `back`/`forward` for a history traversal.
+ *
+ * An app that resets its own view on arrival — scrolling a container to the top is
+ * the usual one — should stand down on a traversal, so a restored position is not
+ * immediately thrown away.
+ */
+declare const useNavigationDirection: () => NavigationDirection;
+
+export { useEntryState, useNavigationDirection };

package/dist/useEntryState.d.ts

@@ -0,0 +1,28 @@
+import { NavigationDirection } from './entryState.js';
+
+/**
+ * Read the value this app left on the current history entry, and queue the value to
+ * leave on the entry the next navigation departs from.
+ *
+ * `value` is `undefined` on an ordinary forward navigation — there is no bookmark for
+ * a page being visited for the first time — and on a traversal to an entry that was
+ * stamped by nothing (a navigation the app did not initiate).
+ *
+ * `save` queues; it does not send. The queued value travels with the next
+ * `navigate()`, which is the only moment the app knows an entry is being left.
+ */
+declare const useEntryState: <T>(key: string) => {
+    value: T | undefined;
+    save: (value: T) => void;
+};
+/**
+ * How the browser reached the page being rendered: `push` for an ordinary
+ * navigation, `back`/`forward` for a history traversal.
+ *
+ * An app that resets its own view on arrival — scrolling a container to the top is
+ * the usual one — should stand down on a traversal, so a restored position is not
+ * immediately thrown away.
+ */
+declare const useNavigationDirection: () => NavigationDirection;
+
+export { useEntryState, useNavigationDirection };

package/dist/useEntryState.js

@@ -0,0 +1,17 @@
+import "./chunk-VHAA22YE.js";
+import { useCallback, useSyncExternalStore } from "react";
+import { getArrivedNavigation, saveEntryState, subscribeNavigation } from "./entryState";
+const useEntryState = (key) => {
+  const arrived = useSyncExternalStore(subscribeNavigation, getArrivedNavigation, getArrivedNavigation);
+  const save = useCallback((value) => saveEntryState(key, value), [key]);
+  return { value: arrived.state?.[key], save };
+};
+const useNavigationDirection = () => {
+  const arrived = useSyncExternalStore(subscribeNavigation, getArrivedNavigation, getArrivedNavigation);
+  return arrived.direction;
+};
+export {
+  useEntryState,
+  useNavigationDirection
+};
+//# sourceMappingURL=useEntryState.js.map

package/dist/useEntryState.js.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":";AAIA,SAAS,aAAa,4BAA4B;AAElD,SAAS,sBAAsB,gBAAgB,2BAAqD;AAa7F,MAAM,gBAAgB,CAAI,QAAoE;AACnG,QAAM,UAAU,qBAAqB,qBAAqB,sBAAsB,oBAAoB;AACpG,QAAM,OAAO,YAAY,CAAC,UAAa,eAAe,KAAK,KAAK,GAAG,CAAC,GAAG,CAAC;AACxE,SAAO,EAAE,OAAO,QAAQ,QAAQ,GAAG,GAAoB,KAAK;AAC9D;AAUO,MAAM,yBAAyB,MAA2B;AAC/D,QAAM,UAAU,qBAAqB,qBAAqB,sBAAsB,oBAAoB;AACpG,SAAO,QAAQ;AACjB;","names":[]}

package/dist/version.cjs

@@ -21,7 +21,7 @@ __export(version_exports, {
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const SDK_VERSION = "0.64.1";
+const SDK_VERSION = "0.66.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SDK_VERSION

package/dist/version.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.64.1';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.66.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}

package/dist/version.d.cts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.64.1";
+declare const SDK_VERSION = "0.66.0";
 
 export { SDK_VERSION };

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.64.1";
+declare const SDK_VERSION = "0.66.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,5 +1,5 @@
 import "./chunk-VHAA22YE.js";
-const SDK_VERSION = "0.64.1";
+const SDK_VERSION = "0.66.0";
 export {
   SDK_VERSION
 };

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.64.1';\n"],"mappings":";AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.66.0';\n"],"mappings":";AAIO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.64.1",
+  "version": "0.66.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -67,12 +67,12 @@
     "@immediately-run/mdx-plugins": "0.5.0",
     "@immediately-run/platform-constants": "0.2.0",
     "@immediately-run/safe-content": "0.1.0",
-    "@immediately-run/sandbox-protocol": "0.10.1",
+    "@immediately-run/sandbox-protocol": "0.10.2",
     "react-error-boundary": "^6.0.0"
   },
   "devDependencies": {
     "@immediately-run/prettier-config": "0.1.0",
-    "@immediately-run/verify-checks": "0.2.0",
+    "@immediately-run/verify-checks": "0.3.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^29.5.0",