@immediately-run/sdk 0.57.1 → 0.58.0

package/dist/agentSteering.d.ts

@@ -0,0 +1,80 @@
+/** How a steer applies. */
+type SteerMode = 
+/** Apply at the next turn boundary — the in-flight turn finishes first. */
+'queue'
+/** Abort the in-flight model turn now, then apply. Never interrupts a tool call. */
+ | 'interrupt';
+interface SteerMessage {
+    id: string;
+    text: string;
+    mode: SteerMode;
+}
+/** Prefix marking a `user` message as a STEER rather than something typed at the
+ *  start of a run — so a replayed conversation shows the interruption where it
+ *  happened, instead of reconstructing a history that never ran (scope 5). Mirrors
+ *  `COMPACTION_MARKER`/`NUDGE_TEXT`, which the transcript renderer already keys on. */
+declare const STEER_MARKER = "\u241F[steer]\n";
+/** As above, for a steer that ABORTED an in-flight turn. */
+declare const STEER_INTERRUPT_MARKER = "\u241F[steer:interrupt]\n";
+/** Text recorded in place of the assistant turn a steer cut short. The turn has to
+ *  appear in the transcript — dropping it would put two `user` messages back to back
+ *  and lose the fact that the model was mid-sentence when the user cut in. */
+declare const INTERRUPTED_TURN_TEXT = "(turn interrupted by the user)";
+/** Wrap a steer's text for the wire. */
+declare const steerWireText: (m: SteerMessage) => string;
+/** Recognise a steer on replay; returns the mode + text, or `null`. */
+declare function parseSteer(text: string): {
+    mode: SteerMode;
+    text: string;
+} | null;
+/** What the loop needs from a steering source (so it can be faked in tests). */
+interface SteerSource {
+    /** Remove and return everything pending, in arrival order. */
+    drain(): SteerMessage[];
+    /** Is anything waiting? Checked before the loop would otherwise END, so a
+     *  follow-up queued against a finishing run continues it instead. */
+    hasPending(): boolean;
+    /** Fires when an `interrupt`-mode steer arrives. The loop composes it with the
+     *  stop signal for the in-flight model call. */
+    readonly interrupt: AbortSignal;
+    /** Called by the loop once an interrupt has been consumed, so the next turn is
+     *  not aborted by a stale signal. */
+    rearm(): void;
+}
+/**
+ * The live steering queue. Owned by the UI (which enqueues and cancels) and read
+ * by the loop (which drains at a turn boundary).
+ */
+declare class SteerController implements SteerSource {
+    private queue;
+    private controller;
+    private listeners;
+    /** Queue a correction. Returns its id so the UI can cancel it while it waits. */
+    enqueue(text: string, mode?: SteerMode): SteerMessage | null;
+    /** Drop a queued steer that has not been applied yet. */
+    cancel(id: string): boolean;
+    /** Everything still waiting, for the UI's "queued" affordance. */
+    pending(): readonly SteerMessage[];
+    hasPending(): boolean;
+    drain(): SteerMessage[];
+    get interrupt(): AbortSignal;
+    rearm(): void;
+    /** Subscribe to queue changes (the UI re-renders its queued chips). */
+    onChange(listener: (pending: readonly SteerMessage[]) => void): () => void;
+    private emit;
+}
+/**
+ * Combine abort signals into one that fires when any of them does.
+ *
+ * `AbortSignal.any` exists in modern engines but not everywhere the sandbox runs,
+ * and a silent `undefined` here would mean the stop button quietly stops working —
+ * so this is explicit, and returns a disposer the caller uses to drop its listeners
+ * (a per-turn signal that stayed subscribed to a run-long controller would leak one
+ * listener per turn on a long run).
+ */
+declare function anySignal(signals: Array<AbortSignal | undefined>): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
+
+export { INTERRUPTED_TURN_TEXT, STEER_INTERRUPT_MARKER, STEER_MARKER, SteerController, type SteerMessage, type SteerMode, type SteerSource, anySignal, parseSteer, steerWireText };

package/dist/agentSteering.js

@@ -0,0 +1,98 @@
+import "./chunk-VHAA22YE.js";
+const STEER_MARKER = "\u241F[steer]\n";
+const STEER_INTERRUPT_MARKER = "\u241F[steer:interrupt]\n";
+const INTERRUPTED_TURN_TEXT = "(turn interrupted by the user)";
+const steerWireText = (m) => (m.mode === "interrupt" ? STEER_INTERRUPT_MARKER : STEER_MARKER) + m.text;
+function parseSteer(text) {
+  if (text.startsWith(STEER_INTERRUPT_MARKER)) {
+    return { mode: "interrupt", text: text.slice(STEER_INTERRUPT_MARKER.length) };
+  }
+  if (text.startsWith(STEER_MARKER)) return { mode: "queue", text: text.slice(STEER_MARKER.length) };
+  return null;
+}
+let seq = 0;
+const nextId = () => {
+  seq += 1;
+  return `steer-${Date.now().toString(36)}-${seq}`;
+};
+class SteerController {
+  constructor() {
+    this.queue = [];
+    this.controller = new AbortController();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /** Queue a correction. Returns its id so the UI can cancel it while it waits. */
+  enqueue(text, mode = "queue") {
+    const trimmed = text.trim();
+    if (!trimmed) return null;
+    const msg = { id: nextId(), text: trimmed, mode };
+    this.queue.push(msg);
+    if (mode === "interrupt") this.controller.abort();
+    this.emit();
+    return msg;
+  }
+  /** Drop a queued steer that has not been applied yet. */
+  cancel(id) {
+    const before = this.queue.length;
+    this.queue = this.queue.filter((m) => m.id !== id);
+    if (this.queue.length === before) return false;
+    if (!this.queue.some((m) => m.mode === "interrupt")) this.rearm();
+    this.emit();
+    return true;
+  }
+  /** Everything still waiting, for the UI's "queued" affordance. */
+  pending() {
+    return this.queue;
+  }
+  hasPending() {
+    return this.queue.length > 0;
+  }
+  drain() {
+    const out = this.queue;
+    this.queue = [];
+    if (out.length) this.emit();
+    return out;
+  }
+  get interrupt() {
+    return this.controller.signal;
+  }
+  rearm() {
+    if (this.controller.signal.aborted) this.controller = new AbortController();
+  }
+  /** Subscribe to queue changes (the UI re-renders its queued chips). */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  emit() {
+    for (const l of this.listeners) l(this.queue);
+  }
+}
+function anySignal(signals) {
+  const live = signals.filter((s) => !!s);
+  const controller = new AbortController();
+  const already = live.find((s) => s.aborted);
+  if (already) {
+    controller.abort(already.reason);
+    return { signal: controller.signal, dispose: () => {
+    } };
+  }
+  const onAbort = (e) => controller.abort(e.target.reason);
+  for (const s of live) s.addEventListener("abort", onAbort, { once: true });
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      for (const s of live) s.removeEventListener("abort", onAbort);
+    }
+  };
+}
+export {
+  INTERRUPTED_TURN_TEXT,
+  STEER_INTERRUPT_MARKER,
+  STEER_MARKER,
+  SteerController,
+  anySignal,
+  parseSteer,
+  steerWireText
+};
+//# sourceMappingURL=agentSteering.js.map

package/dist/agentSteering.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agentSteering.ts"],"sourcesContent":["// Steering + follow-up queue (R3-333 / AHG-T2-3).\n//\n// WHY. R3-224 resolved the hard half — `ChatRequest.signal`, per-message abort in\n// the host that stops the upstream generator and the billing with it, and\n// `runAgent(signal)` behind the stop button. What sits on top of it was never\n// built: the human's vocabulary was still START and KILL. There was no way to say\n// \"yes, but not that file\" or \"stop and do this instead\", or to queue a follow-up\n// while a turn is in flight. Correction meant restart — which discards the\n// transcript's accumulated understanding and pays for it again.\n//\n// This is the app-layer half: a queue the loop drains at a turn boundary, plus an\n// INTERRUPT signal that aborts the in-flight model turn without ending the run.\n//\n// THE TWO VERBS ARE NOT THE SAME.\n//   * STOP  — `RunAgentOptions.signal`. Ends the run. The transcript so far is kept.\n//   * STEER — this controller. Ends the current TURN (or waits for the next\n//             boundary), injects the user's correction, and CONTINUES.\n// They are distinguishable in the transcript (`STEER_MARKER`) and in the UI, which\n// exit criterion 3 requires.\n//\n// WHY A STEER NEVER INTERRUPTS TOOL EXECUTION. A turn's `tool_use` blocks must each\n// get a matching `tool_result`, or the next request is malformed and the provider\n// rejects the whole conversation. So the interrupt signal only ever aborts the\n// in-flight MODEL call; a steer that arrives while tools are running is applied at\n// the boundary after the batch completes. That is exit criterion 5, and it is a\n// property of the design rather than a race the loop has to win.\n\n/** How a steer applies. */\nexport type SteerMode =\n  /** Apply at the next turn boundary — the in-flight turn finishes first. */\n  | 'queue'\n  /** Abort the in-flight model turn now, then apply. Never interrupts a tool call. */\n  | 'interrupt';\n\nexport interface SteerMessage {\n  id: string;\n  text: string;\n  mode: SteerMode;\n}\n\n/** Prefix marking a `user` message as a STEER rather than something typed at the\n *  start of a run — so a replayed conversation shows the interruption where it\n *  happened, instead of reconstructing a history that never ran (scope 5). Mirrors\n *  `COMPACTION_MARKER`/`NUDGE_TEXT`, which the transcript renderer already keys on. */\nexport const STEER_MARKER = '␟[steer]\\n';\n/** As above, for a steer that ABORTED an in-flight turn. */\nexport const STEER_INTERRUPT_MARKER = '␟[steer:interrupt]\\n';\n\n/** Text recorded in place of the assistant turn a steer cut short. The turn has to\n *  appear in the transcript — dropping it would put two `user` messages back to back\n *  and lose the fact that the model was mid-sentence when the user cut in. */\nexport const INTERRUPTED_TURN_TEXT = '(turn interrupted by the user)';\n\n/** Wrap a steer's text for the wire. */\nexport const steerWireText = (m: SteerMessage): string =>\n  (m.mode === 'interrupt' ? STEER_INTERRUPT_MARKER : STEER_MARKER) + m.text;\n\n/** Recognise a steer on replay; returns the mode + text, or `null`. */\nexport function parseSteer(text: string): { mode: SteerMode; text: string } | null {\n  if (text.startsWith(STEER_INTERRUPT_MARKER)) {\n    return { mode: 'interrupt', text: text.slice(STEER_INTERRUPT_MARKER.length) };\n  }\n  if (text.startsWith(STEER_MARKER)) return { mode: 'queue', text: text.slice(STEER_MARKER.length) };\n  return null;\n}\n\n/** What the loop needs from a steering source (so it can be faked in tests). */\nexport interface SteerSource {\n  /** Remove and return everything pending, in arrival order. */\n  drain(): SteerMessage[];\n  /** Is anything waiting? Checked before the loop would otherwise END, so a\n   *  follow-up queued against a finishing run continues it instead. */\n  hasPending(): boolean;\n  /** Fires when an `interrupt`-mode steer arrives. The loop composes it with the\n   *  stop signal for the in-flight model call. */\n  readonly interrupt: AbortSignal;\n  /** Called by the loop once an interrupt has been consumed, so the next turn is\n   *  not aborted by a stale signal. */\n  rearm(): void;\n}\n\nlet seq = 0;\nconst nextId = (): string => {\n  // `crypto.randomUUID` is not available in every host the app runs in; the id only\n  // has to be unique within one run, so a counter + timestamp is enough.\n  seq += 1;\n  return `steer-${Date.now().toString(36)}-${seq}`;\n};\n\n/**\n * The live steering queue. Owned by the UI (which enqueues and cancels) and read\n * by the loop (which drains at a turn boundary).\n */\nexport class SteerController implements SteerSource {\n  private queue: SteerMessage[] = [];\n  private controller = new AbortController();\n  private listeners = new Set<(pending: readonly SteerMessage[]) => void>();\n\n  /** Queue a correction. Returns its id so the UI can cancel it while it waits. */\n  enqueue(text: string, mode: SteerMode = 'queue'): SteerMessage | null {\n    const trimmed = text.trim();\n    if (!trimmed) return null;\n    const msg: SteerMessage = { id: nextId(), text: trimmed, mode };\n    this.queue.push(msg);\n    if (mode === 'interrupt') this.controller.abort();\n    this.emit();\n    return msg;\n  }\n\n  /** Drop a queued steer that has not been applied yet. */\n  cancel(id: string): boolean {\n    const before = this.queue.length;\n    this.queue = this.queue.filter((m) => m.id !== id);\n    if (this.queue.length === before) return false;\n    // Cancelling the only interrupt leaves a fired signal behind; re-arm so the\n    // next turn is not aborted by a correction the user took back.\n    if (!this.queue.some((m) => m.mode === 'interrupt')) this.rearm();\n    this.emit();\n    return true;\n  }\n\n  /** Everything still waiting, for the UI's \"queued\" affordance. */\n  pending(): readonly SteerMessage[] {\n    return this.queue;\n  }\n\n  hasPending(): boolean {\n    return this.queue.length > 0;\n  }\n\n  drain(): SteerMessage[] {\n    const out = this.queue;\n    this.queue = [];\n    if (out.length) this.emit();\n    return out;\n  }\n\n  get interrupt(): AbortSignal {\n    return this.controller.signal;\n  }\n\n  rearm(): void {\n    if (this.controller.signal.aborted) this.controller = new AbortController();\n  }\n\n  /** Subscribe to queue changes (the UI re-renders its queued chips). */\n  onChange(listener: (pending: readonly SteerMessage[]) => void): () => void {\n    this.listeners.add(listener);\n    return () => this.listeners.delete(listener);\n  }\n\n  private emit(): void {\n    for (const l of this.listeners) l(this.queue);\n  }\n}\n\n/**\n * Combine abort signals into one that fires when any of them does.\n *\n * `AbortSignal.any` exists in modern engines but not everywhere the sandbox runs,\n * and a silent `undefined` here would mean the stop button quietly stops working —\n * so this is explicit, and returns a disposer the caller uses to drop its listeners\n * (a per-turn signal that stayed subscribed to a run-long controller would leak one\n * listener per turn on a long run).\n */\nexport function anySignal(signals: Array<AbortSignal | undefined>): {\n  signal: AbortSignal;\n  dispose: () => void;\n} {\n  const live = signals.filter((s): s is AbortSignal => !!s);\n  const controller = new AbortController();\n  const already = live.find((s) => s.aborted);\n  if (already) {\n    controller.abort(already.reason);\n    return { signal: controller.signal, dispose: () => {} };\n  }\n  const onAbort = (e: Event): void => controller.abort((e.target as AbortSignal).reason);\n  for (const s of live) s.addEventListener('abort', onAbort, { once: true });\n  return {\n    signal: controller.signal,\n    dispose: () => {\n      for (const s of live) s.removeEventListener('abort', onAbort);\n    },\n  };\n}\n"],"mappings":";AA4CO,MAAM,eAAe;AAErB,MAAM,yBAAyB;AAK/B,MAAM,wBAAwB;AAG9B,MAAM,gBAAgB,CAAC,OAC3B,EAAE,SAAS,cAAc,yBAAyB,gBAAgB,EAAE;AAGhE,SAAS,WAAW,MAAwD;AACjF,MAAI,KAAK,WAAW,sBAAsB,GAAG;AAC3C,WAAO,EAAE,MAAM,aAAa,MAAM,KAAK,MAAM,uBAAuB,MAAM,EAAE;AAAA,EAC9E;AACA,MAAI,KAAK,WAAW,YAAY,EAAG,QAAO,EAAE,MAAM,SAAS,MAAM,KAAK,MAAM,aAAa,MAAM,EAAE;AACjG,SAAO;AACT;AAiBA,IAAI,MAAM;AACV,MAAM,SAAS,MAAc;AAG3B,SAAO;AACP,SAAO,SAAS,KAAK,IAAI,EAAE,SAAS,EAAE,CAAC,IAAI,GAAG;AAChD;AAMO,MAAM,gBAAuC;AAAA,EAA7C;AACL,SAAQ,QAAwB,CAAC;AACjC,SAAQ,aAAa,IAAI,gBAAgB;AACzC,SAAQ,YAAY,oBAAI,IAAgD;AAAA;AAAA;AAAA,EAGxE,QAAQ,MAAc,OAAkB,SAA8B;AACpE,UAAM,UAAU,KAAK,KAAK;AAC1B,QAAI,CAAC,QAAS,QAAO;AACrB,UAAM,MAAoB,EAAE,IAAI,OAAO,GAAG,MAAM,SAAS,KAAK;AAC9D,SAAK,MAAM,KAAK,GAAG;AACnB,QAAI,SAAS,YAAa,MAAK,WAAW,MAAM;AAChD,SAAK,KAAK;AACV,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,OAAO,IAAqB;AAC1B,UAAM,SAAS,KAAK,MAAM;AAC1B,SAAK,QAAQ,KAAK,MAAM,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE;AACjD,QAAI,KAAK,MAAM,WAAW,OAAQ,QAAO;AAGzC,QAAI,CAAC,KAAK,MAAM,KAAK,CAAC,MAAM,EAAE,SAAS,WAAW,EAAG,MAAK,MAAM;AAChE,SAAK,KAAK;AACV,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,UAAmC;AACjC,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,aAAsB;AACpB,WAAO,KAAK,MAAM,SAAS;AAAA,EAC7B;AAAA,EAEA,QAAwB;AACtB,UAAM,MAAM,KAAK;AACjB,SAAK,QAAQ,CAAC;AACd,QAAI,IAAI,OAAQ,MAAK,KAAK;AAC1B,WAAO;AAAA,EACT;AAAA,EAEA,IAAI,YAAyB;AAC3B,WAAO,KAAK,WAAW;AAAA,EACzB;AAAA,EAEA,QAAc;AACZ,QAAI,KAAK,WAAW,OAAO,QAAS,MAAK,aAAa,IAAI,gBAAgB;AAAA,EAC5E;AAAA;AAAA,EAGA,SAAS,UAAkE;AACzE,SAAK,UAAU,IAAI,QAAQ;AAC3B,WAAO,MAAM,KAAK,UAAU,OAAO,QAAQ;AAAA,EAC7C;AAAA,EAEQ,OAAa;AACnB,eAAW,KAAK,KAAK,UAAW,GAAE,KAAK,KAAK;AAAA,EAC9C;AACF;AAWO,SAAS,UAAU,SAGxB;AACA,QAAM,OAAO,QAAQ,OAAO,CAAC,MAAwB,CAAC,CAAC,CAAC;AACxD,QAAM,aAAa,IAAI,gBAAgB;AACvC,QAAM,UAAU,KAAK,KAAK,CAAC,MAAM,EAAE,OAAO;AAC1C,MAAI,SAAS;AACX,eAAW,MAAM,QAAQ,MAAM;AAC/B,WAAO,EAAE,QAAQ,WAAW,QAAQ,SAAS,MAAM;AAAA,IAAC,EAAE;AAAA,EACxD;AACA,QAAM,UAAU,CAAC,MAAmB,WAAW,MAAO,EAAE,OAAuB,MAAM;AACrF,aAAW,KAAK,KAAM,GAAE,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;AACzE,SAAO;AAAA,IACL,QAAQ,WAAW;AAAA,IACnB,SAAS,MAAM;AACb,iBAAW,KAAK,KAAM,GAAE,oBAAoB,SAAS,OAAO;AAAA,IAC9D;AAAA,EACF;AACF;","names":[]}

package/dist/auth.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { AUTH_STATE, REQUEST_AUTH_STATE } from './generated/protocol';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\n/** The signed-in immediately.run user, as seen by the sandbox (no token, ever). */\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\n/** The user's login / account state: a `status` plus the `user` when signed in. */\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\nconst isAuthState = (v: unknown): v is AuthState => {\n  const s = v as Partial<AuthState> | null;\n  return (\n    !!s &&\n    (s.status === 'unknown' || s.status === 'signed-in' || s.status === 'signed-out') &&\n    (s.user === null || (typeof s.user === 'object' && typeof (s.user as SandboxUser).login === 'string'))\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `auth-state`\n// and answers `request-auth-state` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<AuthState>({\n  pushType: AUTH_STATE,\n  requestType: REQUEST_AUTH_STATE,\n  initial: { status: 'unknown', user: null },\n  parse: (msg) => (isAuthState(msg.state) ? (msg.state as AuthState) : undefined),\n});\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n */\nexport const getAuthState = (): AuthState => channel.get();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) => channel.onChange(listener);\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n */\nexport const useAuth = (): AuthState => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAClC,sBAA+C;AAuB/C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,WAAW,aAAa,EAAE,WAAW,eAAe,EAAE,WAAW,kBACnE,EAAE,SAAS,QAAS,OAAO,EAAE,SAAS,YAAY,OAAQ,EAAE,KAAqB,UAAU;AAEhG;AAIA,MAAM,cAAU,sCAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,QAAQ,WAAW,MAAM,KAAK;AAAA,EACzC,OAAO,CAAC,QAAS,YAAY,IAAI,KAAK,IAAK,IAAI,QAAsB;AACvE,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,eAAe,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAMtG,MAAM,UAAU,MAAiB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { AUTH_STATE, REQUEST_AUTH_STATE } from './generated/protocol';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\n/**\n * The signed-in immediately.run user, as seen by the sandbox (no token, ever).\n *\n * Identity is gated by the `auth:identity` capability (elevated): the host\n * redacts `user` to `null` for any frame not holding it, while the baseline\n * `auth:status` still reports whether *a* session exists. A stage app therefore\n * sees `{ status: 'signed-in', user: null }` unless it declares `auth:identity`\n * under `immediately.run.capabilities` in its `package.json` and the user\n * consents once (a durable per-(app, user) grant). First-party / elevated\n * frames receive it via their region binding.\n */\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\n/**\n * The user's login / account state: a `status` plus the `user` when signed in.\n *\n * `user` is `null` for any frame not granted `auth:identity` — even when\n * `status` is `'signed-in'`. See {@link SandboxUser} for how an app earns it.\n */\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\nconst isAuthState = (v: unknown): v is AuthState => {\n  const s = v as Partial<AuthState> | null;\n  return (\n    !!s &&\n    (s.status === 'unknown' || s.status === 'signed-in' || s.status === 'signed-out') &&\n    (s.user === null || (typeof s.user === 'object' && typeof (s.user as SandboxUser).login === 'string'))\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `auth-state`\n// and answers `request-auth-state` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<AuthState>({\n  pushType: AUTH_STATE,\n  requestType: REQUEST_AUTH_STATE,\n  initial: { status: 'unknown', user: null },\n  parse: (msg) => (isAuthState(msg.state) ? (msg.state as AuthState) : undefined),\n});\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n *\n * `user` is `null` unless this frame holds `auth:identity` (see\n * {@link SandboxUser}); `status` alone is baseline and always available.\n *\n * Off-host (plain `vite dev` — no host to report a session) `status` stays\n * `'unknown'` FOREVER — it never settles to `'signed-out'`. Code that waits for a\n * settled status before proceeding (e.g. attributing authorship) hangs locally:\n * gate such flows on `status === 'signed-in'` combined with a timeout or an\n * explicit local fallback, never on \"status is no longer 'unknown'\".\n */\nexport const getAuthState = (): AuthState => channel.get();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) => channel.onChange(listener);\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n *\n * `user` is `null` unless this frame holds `auth:identity` (see\n * {@link SandboxUser}); `status` alone is baseline and always available.\n *\n * Off-host (plain `vite dev`) `status` stays `'unknown'` forever — see\n * {@link getAuthState} for why \"wait until it settles\" hangs locally and how to\n * gate on it safely (signed-in check plus a timeout/fallback).\n */\nexport const useAuth = (): AuthState => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAClC,sBAA+C;AAsC/C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,WAAW,aAAa,EAAE,WAAW,eAAe,EAAE,WAAW,kBACnE,EAAE,SAAS,QAAS,OAAO,EAAE,SAAS,YAAY,OAAQ,EAAE,KAAqB,UAAU;AAEhG;AAIA,MAAM,cAAU,sCAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,QAAQ,WAAW,MAAM,KAAK;AAAA,EACzC,OAAO,CAAC,QAAS,YAAY,IAAI,KAAK,IAAK,IAAI,QAAsB;AACvE,CAAC;AAeM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,eAAe,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAatG,MAAM,UAAU,MAAiB,QAAQ,IAAI;","names":[]}

package/dist/auth.d.cts

@@ -6,12 +6,27 @@
  * distinguish "still loading" from a confirmed signed-out session).
  */
 type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';
-/** The signed-in immediately.run user, as seen by the sandbox (no token, ever). */
+/**
+ * The signed-in immediately.run user, as seen by the sandbox (no token, ever).
+ *
+ * Identity is gated by the `auth:identity` capability (elevated): the host
+ * redacts `user` to `null` for any frame not holding it, while the baseline
+ * `auth:status` still reports whether *a* session exists. A stage app therefore
+ * sees `{ status: 'signed-in', user: null }` unless it declares `auth:identity`
+ * under `immediately.run.capabilities` in its `package.json` and the user
+ * consents once (a durable per-(app, user) grant). First-party / elevated
+ * frames receive it via their region binding.
+ */
 interface SandboxUser {
     /** GitHub login (handle) of the signed-in user. */
     login: string;
 }
-/** The user's login / account state: a `status` plus the `user` when signed in. */
+/**
+ * The user's login / account state: a `status` plus the `user` when signed in.
+ *
+ * `user` is `null` for any frame not granted `auth:identity` — even when
+ * `status` is `'signed-in'`. See {@link SandboxUser} for how an app earns it.
+ */
 interface AuthState {
     status: AuthStatus;
     user: SandboxUser | null;
@@ -19,6 +34,15 @@ interface AuthState {
 /**
  * Returns the current login / account state. Poll this whenever you need a
  * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.
+ *
+ * `user` is `null` unless this frame holds `auth:identity` (see
+ * {@link SandboxUser}); `status` alone is baseline and always available.
+ *
+ * Off-host (plain `vite dev` — no host to report a session) `status` stays
+ * `'unknown'` FOREVER — it never settles to `'signed-out'`. Code that waits for a
+ * settled status before proceeding (e.g. attributing authorship) hangs locally:
+ * gate such flows on `status === 'signed-in'` combined with a timeout or an
+ * explicit local fallback, never on "status is no longer 'unknown'".
  */
 declare const getAuthState: () => AuthState;
 /**
@@ -29,6 +53,13 @@ declare const onAuthChange: (listener: (state: AuthState) => void) => (() => voi
 /**
  * React hook returning the current login / account state, re-rendering on
  * login / logout.
+ *
+ * `user` is `null` unless this frame holds `auth:identity` (see
+ * {@link SandboxUser}); `status` alone is baseline and always available.
+ *
+ * Off-host (plain `vite dev`) `status` stays `'unknown'` forever — see
+ * {@link getAuthState} for why "wait until it settles" hangs locally and how to
+ * gate on it safely (signed-in check plus a timeout/fallback).
  */
 declare const useAuth: () => AuthState;
 

package/dist/auth.d.ts

@@ -6,12 +6,27 @@
  * distinguish "still loading" from a confirmed signed-out session).
  */
 type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';
-/** The signed-in immediately.run user, as seen by the sandbox (no token, ever). */
+/**
+ * The signed-in immediately.run user, as seen by the sandbox (no token, ever).
+ *
+ * Identity is gated by the `auth:identity` capability (elevated): the host
+ * redacts `user` to `null` for any frame not holding it, while the baseline
+ * `auth:status` still reports whether *a* session exists. A stage app therefore
+ * sees `{ status: 'signed-in', user: null }` unless it declares `auth:identity`
+ * under `immediately.run.capabilities` in its `package.json` and the user
+ * consents once (a durable per-(app, user) grant). First-party / elevated
+ * frames receive it via their region binding.
+ */
 interface SandboxUser {
     /** GitHub login (handle) of the signed-in user. */
     login: string;
 }
-/** The user's login / account state: a `status` plus the `user` when signed in. */
+/**
+ * The user's login / account state: a `status` plus the `user` when signed in.
+ *
+ * `user` is `null` for any frame not granted `auth:identity` — even when
+ * `status` is `'signed-in'`. See {@link SandboxUser} for how an app earns it.
+ */
 interface AuthState {
     status: AuthStatus;
     user: SandboxUser | null;
@@ -19,6 +34,15 @@ interface AuthState {
 /**
  * Returns the current login / account state. Poll this whenever you need a
  * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.
+ *
+ * `user` is `null` unless this frame holds `auth:identity` (see
+ * {@link SandboxUser}); `status` alone is baseline and always available.
+ *
+ * Off-host (plain `vite dev` — no host to report a session) `status` stays
+ * `'unknown'` FOREVER — it never settles to `'signed-out'`. Code that waits for a
+ * settled status before proceeding (e.g. attributing authorship) hangs locally:
+ * gate such flows on `status === 'signed-in'` combined with a timeout or an
+ * explicit local fallback, never on "status is no longer 'unknown'".
  */
 declare const getAuthState: () => AuthState;
 /**
@@ -29,6 +53,13 @@ declare const onAuthChange: (listener: (state: AuthState) => void) => (() => voi
 /**
  * React hook returning the current login / account state, re-rendering on
  * login / logout.
+ *
+ * `user` is `null` unless this frame holds `auth:identity` (see
+ * {@link SandboxUser}); `status` alone is baseline and always available.
+ *
+ * Off-host (plain `vite dev`) `status` stays `'unknown'` forever — see
+ * {@link getAuthState} for why "wait until it settles" hangs locally and how to
+ * gate on it safely (signed-in check plus a timeout/fallback).
  */
 declare const useAuth: () => AuthState;
 

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { AUTH_STATE, REQUEST_AUTH_STATE } from './generated/protocol';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\n/** The signed-in immediately.run user, as seen by the sandbox (no token, ever). */\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\n/** The user's login / account state: a `status` plus the `user` when signed in. */\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\nconst isAuthState = (v: unknown): v is AuthState => {\n  const s = v as Partial<AuthState> | null;\n  return (\n    !!s &&\n    (s.status === 'unknown' || s.status === 'signed-in' || s.status === 'signed-out') &&\n    (s.user === null || (typeof s.user === 'object' && typeof (s.user as SandboxUser).login === 'string'))\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `auth-state`\n// and answers `request-auth-state` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<AuthState>({\n  pushType: AUTH_STATE,\n  requestType: REQUEST_AUTH_STATE,\n  initial: { status: 'unknown', user: null },\n  parse: (msg) => (isAuthState(msg.state) ? (msg.state as AuthState) : undefined),\n});\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n */\nexport const getAuthState = (): AuthState => channel.get();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) => channel.onChange(listener);\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n */\nexport const useAuth = (): AuthState => channel.use();\n"],"mappings":";AAAA,SAAS,yBAAyB;AAClC,SAAS,YAAY,0BAA0B;AAuB/C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,WAAW,aAAa,EAAE,WAAW,eAAe,EAAE,WAAW,kBACnE,EAAE,SAAS,QAAS,OAAO,EAAE,SAAS,YAAY,OAAQ,EAAE,KAAqB,UAAU;AAEhG;AAIA,MAAM,UAAU,kBAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,QAAQ,WAAW,MAAM,KAAK;AAAA,EACzC,OAAO,CAAC,QAAS,YAAY,IAAI,KAAK,IAAK,IAAI,QAAsB;AACvE,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,eAAe,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAMtG,MAAM,UAAU,MAAiB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { AUTH_STATE, REQUEST_AUTH_STATE } from './generated/protocol';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\n/**\n * The signed-in immediately.run user, as seen by the sandbox (no token, ever).\n *\n * Identity is gated by the `auth:identity` capability (elevated): the host\n * redacts `user` to `null` for any frame not holding it, while the baseline\n * `auth:status` still reports whether *a* session exists. A stage app therefore\n * sees `{ status: 'signed-in', user: null }` unless it declares `auth:identity`\n * under `immediately.run.capabilities` in its `package.json` and the user\n * consents once (a durable per-(app, user) grant). First-party / elevated\n * frames receive it via their region binding.\n */\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\n/**\n * The user's login / account state: a `status` plus the `user` when signed in.\n *\n * `user` is `null` for any frame not granted `auth:identity` — even when\n * `status` is `'signed-in'`. See {@link SandboxUser} for how an app earns it.\n */\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\nconst isAuthState = (v: unknown): v is AuthState => {\n  const s = v as Partial<AuthState> | null;\n  return (\n    !!s &&\n    (s.status === 'unknown' || s.status === 'signed-in' || s.status === 'signed-out') &&\n    (s.user === null || (typeof s.user === 'object' && typeof (s.user as SandboxUser).login === 'string'))\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `auth-state`\n// and answers `request-auth-state` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<AuthState>({\n  pushType: AUTH_STATE,\n  requestType: REQUEST_AUTH_STATE,\n  initial: { status: 'unknown', user: null },\n  parse: (msg) => (isAuthState(msg.state) ? (msg.state as AuthState) : undefined),\n});\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n *\n * `user` is `null` unless this frame holds `auth:identity` (see\n * {@link SandboxUser}); `status` alone is baseline and always available.\n *\n * Off-host (plain `vite dev` — no host to report a session) `status` stays\n * `'unknown'` FOREVER — it never settles to `'signed-out'`. Code that waits for a\n * settled status before proceeding (e.g. attributing authorship) hangs locally:\n * gate such flows on `status === 'signed-in'` combined with a timeout or an\n * explicit local fallback, never on \"status is no longer 'unknown'\".\n */\nexport const getAuthState = (): AuthState => channel.get();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) => channel.onChange(listener);\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n *\n * `user` is `null` unless this frame holds `auth:identity` (see\n * {@link SandboxUser}); `status` alone is baseline and always available.\n *\n * Off-host (plain `vite dev`) `status` stays `'unknown'` forever — see\n * {@link getAuthState} for why \"wait until it settles\" hangs locally and how to\n * gate on it safely (signed-in check plus a timeout/fallback).\n */\nexport const useAuth = (): AuthState => channel.use();\n"],"mappings":";AAAA,SAAS,yBAAyB;AAClC,SAAS,YAAY,0BAA0B;AAsC/C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,WAAW,aAAa,EAAE,WAAW,eAAe,EAAE,WAAW,kBACnE,EAAE,SAAS,QAAS,OAAO,EAAE,SAAS,YAAY,OAAQ,EAAE,KAAqB,UAAU;AAEhG;AAIA,MAAM,UAAU,kBAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,QAAQ,WAAW,MAAM,KAAK;AAAA,EACzC,OAAO,CAAC,QAAS,YAAY,IAAI,KAAK,IAAK,IAAI,QAAsB;AACvE,CAAC;AAeM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,eAAe,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAatG,MAAM,UAAU,MAAiB,QAAQ,IAAI;","names":[]}

package/dist/bundle.cjs

@@ -0,0 +1,91 @@
+"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 bundle_exports = {};
+__export(bundle_exports, {
+  BundleContext: () => BundleContext,
+  fromBundlePath: () => fromBundlePath,
+  toBundlePath: () => toBundlePath,
+  useBundle: () => useBundle,
+  useBundleEntries: () => useBundleEntries,
+  useBundleEntry: () => useBundleEntry,
+  useCurrentEntry: () => useCurrentEntry
+});
+module.exports = __toCommonJS(bundle_exports);
+var import_react = require("react");
+var import_metadataSource = require("./metadataSource");
+const EMPTY_SCOPE = { root: null, entry: null, toHref: (p) => p };
+const BundleContext = (0, import_react.createContext)(EMPTY_SCOPE);
+const useBundle = () => (0, import_react.use)(BundleContext);
+const toBundlePath = (absolute, root) => {
+  if (root === null) return null;
+  const base = root.replace(/\/+$/, "");
+  if (base === "") return absolute;
+  if (!absolute.startsWith(`${base}/`)) return null;
+  return absolute.slice(base.length);
+};
+const fromBundlePath = (bundlePath, root) => {
+  if (root === null) return null;
+  const base = root.replace(/\/+$/, "");
+  return `${base}${bundlePath.startsWith("/") ? "" : "/"}${bundlePath}`;
+};
+const useBundleEntries = () => {
+  const files = (0, import_metadataSource.useMetadataStore)();
+  const { root, toHref } = useBundle();
+  return (0, import_react.useMemo)(() => {
+    if (root === null) return [];
+    const out = [];
+    for (const [absolute, meta] of Object.entries(files)) {
+      const path = toBundlePath(absolute, root);
+      if (path === null) continue;
+      out.push({ path, href: toHref(path), meta });
+    }
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+  }, [files, root, toHref]);
+};
+const useBundleEntry = (bundlePath) => {
+  const files = (0, import_metadataSource.useMetadataStore)();
+  const { root } = useBundle();
+  return (0, import_react.useMemo)(() => {
+    const absolute = fromBundlePath(bundlePath, root);
+    return absolute === null ? void 0 : files[absolute];
+  }, [bundlePath, files, root]);
+};
+const useCurrentEntry = () => {
+  const files = (0, import_metadataSource.useMetadataStore)();
+  const { root, entry, toHref } = useBundle();
+  return (0, import_react.useMemo)(() => {
+    if (root === null || entry === null) return null;
+    const absolute = fromBundlePath(entry, root);
+    const meta = absolute === null ? void 0 : files[absolute];
+    if (meta === void 0) return null;
+    return { path: entry, href: toHref(entry), meta };
+  }, [files, root, entry, toHref]);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BundleContext,
+  fromBundlePath,
+  toBundlePath,
+  useBundle,
+  useBundleEntries,
+  useBundleEntry,
+  useCurrentEntry
+});
+//# sourceMappingURL=bundle.cjs.map

package/dist/bundle.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bundle.ts"],"sourcesContent":["// The bundle scope — what a component rendered INSIDE a bundle may know about it\n// (R3-174; MDX_FROM_MOUNT_SPEC §2, §7 1a).\n//\n// A bundle viewer can register components the bundle itself ships, so an entry writes\n// `<ProjectIndex/>` and the viewer resolves it — no engine fork, no import line\n// (`MDX_FROM_MOUNT_SPEC` §2's \"provider composition is consumer policy\"). Those components\n// live in the CONTENT filesystem and the viewer lives in its own, and the seam between\n// them is this package: a content component cannot import the viewer (it would resolve a\n// second copy from the registry, with its own module state, and read the wrong bundle), so\n// anything the viewer must tell it has to arrive through a surface both sides already\n// share. This is that surface.\n//\n// **Why paths here are bundle-absolute, not filesystem-absolute.** The metadata store is\n// keyed by absolute module path, which under dispatch means `/mnt/<hash>/roadmap/x.mdx` —\n// the host-minted chroot. That prefix is host knowledge a viewer may read THROUGH but must\n// never publish (the property `grove/src/components/DirectoryList.test.tsx` pins with\n// `expect(el.innerHTML).not.toContain('mnt')`), and it is not stable across loads. A\n// content component that saw it would embed it in hrefs and keys. So the bundle scope\n// rebases every path it hands out to the bundle root (`/roadmap/x.mdx`), which is the same\n// address under fork, library and dispatch composition — `PLATFORM_LAYERING_SPEC` §1.1's\n// mode-invariance rule, applied to metadata rather than to links.\n//\n// **Why the href mapping is injected rather than derived.** Bundle path → in-app URL is\n// VIEWER policy, and the two packagings genuinely disagree (a fork's URLs are anchored at\n// its app root and are already published and cited; a dispatched viewer's are bundle-\n// relative). A content component must not have to know which it is in, and the SDK must\n// not guess — so the viewer supplies `toHref` and content never computes a URL itself.\n\nimport { createContext, use, useMemo } from 'react';\nimport { useMetadataStore } from './metadataSource';\nimport type { Metadata } from './sandboxTypes';\n\n/** What a bundle viewer declares about the bundle it is rendering. */\nexport interface BundleScope {\n  /**\n   * Absolute filesystem path of the bundle root, WITHOUT a trailing slash\n   * (`/app/content` in a fork, `/mnt/<hash>` under dispatch), or `null` when the\n   * surrounding app is not rendering a bundle — the default, which leaves every hook here\n   * returning the empty result rather than guessing a root.\n   */\n  root: string | null;\n  /** Bundle-absolute path of the entry currently being read (`/roadmap/R3-174.mdx`), or\n   *  `null` when nothing is. This is the entry, NOT the file being rendered: a component\n   *  in a `_layout.mdx` wrapping that entry sees the entry, which is what makes furniture\n   *  in the layout chain (a status line, a dependency rail) able to describe the page. */\n  entry: string | null;\n  /** Bundle-absolute path → the href to navigate to it. Supplied by the viewer; the\n   *  identity function by default, which is correct for a viewer whose URL space IS the\n   *  bundle space. */\n  toHref: (bundlePath: string) => string;\n}\n\nconst EMPTY_SCOPE: BundleScope = { root: null, entry: null, toHref: (p) => p };\n\n/** Ambient bundle scope. A bundle-rendering app wraps its content tree in\n *  `<BundleContext value={{ root, entry, toHref }}>`; nesting a second provider inside a\n *  rendered sub-bundle makes the innermost win, as with {@link LinkSpaceContext}. */\nexport const BundleContext = createContext<BundleScope>(EMPTY_SCOPE);\n\n/** Read the ambient bundle scope. Every hook below is a convenience over this. */\nexport const useBundle = (): BundleScope => use(BundleContext);\n\n/**\n * Filesystem-absolute path → bundle-absolute, or `null` when the path is not inside the\n * bundle. Exact-root and separator-boundary aware, so `/mnt/hash2/x` is not treated as\n * living under `/mnt/hash`.\n */\nexport const toBundlePath = (absolute: string, root: string | null): string | null => {\n  if (root === null) return null;\n  const base = root.replace(/\\/+$/, '');\n  if (base === '') return absolute;\n  if (!absolute.startsWith(`${base}/`)) return null;\n  return absolute.slice(base.length);\n};\n\n/** Bundle-absolute path → filesystem-absolute, or `null` without a root. The inverse of\n *  {@link toBundlePath}, for the rare content component that must read raw bytes. */\nexport const fromBundlePath = (bundlePath: string, root: string | null): string | null => {\n  if (root === null) return null;\n  const base = root.replace(/\\/+$/, '');\n  return `${base}${bundlePath.startsWith('/') ? '' : '/'}${bundlePath}`;\n};\n\n/** One entry as content sees it: where it is, where it links, and its frontmatter. */\nexport interface BundleEntry<T = Metadata> {\n  /** Bundle-absolute path (`/roadmap/R3-174.mdx`). */\n  path: string;\n  /** The href that navigates to it, per the viewer's mapping. */\n  href: string;\n  meta: T;\n}\n\n/**\n * Every entry in the surrounding bundle, with bundle-absolute paths and viewer-supplied\n * hrefs — the surface a content component queries instead of {@link useMetadataQuery},\n * whose keys are filesystem-absolute and therefore carry the mount prefix.\n *\n * Returns an empty array outside a bundle, so a component written for a bundle renders\n * nothing rather than throwing when someone drops it elsewhere. The array keeps its\n * identity while the store and root are unchanged, so it is safe in dependency arrays.\n */\nexport const useBundleEntries = <T = Metadata>(): BundleEntry<T>[] => {\n  const files = useMetadataStore<T>();\n  const { root, toHref } = useBundle();\n  return useMemo(() => {\n    if (root === null) return [];\n    const out: BundleEntry<T>[] = [];\n    for (const [absolute, meta] of Object.entries(files)) {\n      const path = toBundlePath(absolute, root);\n      if (path === null) continue;\n      out.push({ path, href: toHref(path), meta: meta as T });\n    }\n    // Path order, so a consumer that does not sort still renders deterministically\n    // (object key order is insertion order, which is scan order, which is not stable).\n    out.sort((a, b) => a.path.localeCompare(b.path));\n    return out;\n  }, [files, root, toHref]);\n};\n\n/** One entry's frontmatter by bundle-absolute path, or `undefined`. */\nexport const useBundleEntry = <T = Metadata>(bundlePath: string): T | undefined => {\n  const files = useMetadataStore<T>();\n  const { root } = useBundle();\n  return useMemo(() => {\n    const absolute = fromBundlePath(bundlePath, root);\n    return absolute === null ? undefined : files[absolute];\n  }, [bundlePath, files, root]);\n};\n\n/** The entry currently being read — `null` outside a bundle, or when the viewer declares\n *  no entry (a directory listing, a 404). See {@link BundleScope.entry} for why this is\n *  the entry rather than the file the component happens to be written in. */\nexport const useCurrentEntry = <T = Metadata>(): BundleEntry<T> | null => {\n  const files = useMetadataStore<T>();\n  const { root, entry, toHref } = useBundle();\n  return useMemo(() => {\n    if (root === null || entry === null) return null;\n    const absolute = fromBundlePath(entry, root);\n    const meta = absolute === null ? undefined : files[absolute];\n    if (meta === undefined) return null;\n    return { path: entry, href: toHref(entry), meta: meta as T };\n  }, [files, root, entry, toHref]);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4BA,mBAA4C;AAC5C,4BAAiC;AAuBjC,MAAM,cAA2B,EAAE,MAAM,MAAM,OAAO,MAAM,QAAQ,CAAC,MAAM,EAAE;AAKtE,MAAM,oBAAgB,4BAA2B,WAAW;AAG5D,MAAM,YAAY,UAAmB,kBAAI,aAAa;AAOtD,MAAM,eAAe,CAAC,UAAkB,SAAuC;AACpF,MAAI,SAAS,KAAM,QAAO;AAC1B,QAAM,OAAO,KAAK,QAAQ,QAAQ,EAAE;AACpC,MAAI,SAAS,GAAI,QAAO;AACxB,MAAI,CAAC,SAAS,WAAW,GAAG,IAAI,GAAG,EAAG,QAAO;AAC7C,SAAO,SAAS,MAAM,KAAK,MAAM;AACnC;AAIO,MAAM,iBAAiB,CAAC,YAAoB,SAAuC;AACxF,MAAI,SAAS,KAAM,QAAO;AAC1B,QAAM,OAAO,KAAK,QAAQ,QAAQ,EAAE;AACpC,SAAO,GAAG,IAAI,GAAG,WAAW,WAAW,GAAG,IAAI,KAAK,GAAG,GAAG,UAAU;AACrE;AAoBO,MAAM,mBAAmB,MAAsC;AACpE,QAAM,YAAQ,wCAAoB;AAClC,QAAM,EAAE,MAAM,OAAO,IAAI,UAAU;AACnC,aAAO,sBAAQ,MAAM;AACnB,QAAI,SAAS,KAAM,QAAO,CAAC;AAC3B,UAAM,MAAwB,CAAC;AAC/B,eAAW,CAAC,UAAU,IAAI,KAAK,OAAO,QAAQ,KAAK,GAAG;AACpD,YAAM,OAAO,aAAa,UAAU,IAAI;AACxC,UAAI,SAAS,KAAM;AACnB,UAAI,KAAK,EAAE,MAAM,MAAM,OAAO,IAAI,GAAG,KAAgB,CAAC;AAAA,IACxD;AAGA,QAAI,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC;AAC/C,WAAO;AAAA,EACT,GAAG,CAAC,OAAO,MAAM,MAAM,CAAC;AAC1B;AAGO,MAAM,iBAAiB,CAAe,eAAsC;AACjF,QAAM,YAAQ,wCAAoB;AAClC,QAAM,EAAE,KAAK,IAAI,UAAU;AAC3B,aAAO,sBAAQ,MAAM;AACnB,UAAM,WAAW,eAAe,YAAY,IAAI;AAChD,WAAO,aAAa,OAAO,SAAY,MAAM,QAAQ;AAAA,EACvD,GAAG,CAAC,YAAY,OAAO,IAAI,CAAC;AAC9B;AAKO,MAAM,kBAAkB,MAA2C;AACxE,QAAM,YAAQ,wCAAoB;AAClC,QAAM,EAAE,MAAM,OAAO,OAAO,IAAI,UAAU;AAC1C,aAAO,sBAAQ,MAAM;AACnB,QAAI,SAAS,QAAQ,UAAU,KAAM,QAAO;AAC5C,UAAM,WAAW,eAAe,OAAO,IAAI;AAC3C,UAAM,OAAO,aAAa,OAAO,SAAY,MAAM,QAAQ;AAC3D,QAAI,SAAS,OAAW,QAAO;AAC/B,WAAO,EAAE,MAAM,OAAO,MAAM,OAAO,KAAK,GAAG,KAAgB;AAAA,EAC7D,GAAG,CAAC,OAAO,MAAM,OAAO,MAAM,CAAC;AACjC;","names":[]}

package/dist/bundle.d.cts

@@ -0,0 +1,63 @@
+import * as react from 'react';
+import { Metadata } from './sandboxTypes.cjs';
+
+/** What a bundle viewer declares about the bundle it is rendering. */
+interface BundleScope {
+    /**
+     * Absolute filesystem path of the bundle root, WITHOUT a trailing slash
+     * (`/app/content` in a fork, `/mnt/<hash>` under dispatch), or `null` when the
+     * surrounding app is not rendering a bundle — the default, which leaves every hook here
+     * returning the empty result rather than guessing a root.
+     */
+    root: string | null;
+    /** Bundle-absolute path of the entry currently being read (`/roadmap/R3-174.mdx`), or
+     *  `null` when nothing is. This is the entry, NOT the file being rendered: a component
+     *  in a `_layout.mdx` wrapping that entry sees the entry, which is what makes furniture
+     *  in the layout chain (a status line, a dependency rail) able to describe the page. */
+    entry: string | null;
+    /** Bundle-absolute path → the href to navigate to it. Supplied by the viewer; the
+     *  identity function by default, which is correct for a viewer whose URL space IS the
+     *  bundle space. */
+    toHref: (bundlePath: string) => string;
+}
+/** Ambient bundle scope. A bundle-rendering app wraps its content tree in
+ *  `<BundleContext value={{ root, entry, toHref }}>`; nesting a second provider inside a
+ *  rendered sub-bundle makes the innermost win, as with {@link LinkSpaceContext}. */
+declare const BundleContext: react.Context<BundleScope>;
+/** Read the ambient bundle scope. Every hook below is a convenience over this. */
+declare const useBundle: () => BundleScope;
+/**
+ * Filesystem-absolute path → bundle-absolute, or `null` when the path is not inside the
+ * bundle. Exact-root and separator-boundary aware, so `/mnt/hash2/x` is not treated as
+ * living under `/mnt/hash`.
+ */
+declare const toBundlePath: (absolute: string, root: string | null) => string | null;
+/** Bundle-absolute path → filesystem-absolute, or `null` without a root. The inverse of
+ *  {@link toBundlePath}, for the rare content component that must read raw bytes. */
+declare const fromBundlePath: (bundlePath: string, root: string | null) => string | null;
+/** One entry as content sees it: where it is, where it links, and its frontmatter. */
+interface BundleEntry<T = Metadata> {
+    /** Bundle-absolute path (`/roadmap/R3-174.mdx`). */
+    path: string;
+    /** The href that navigates to it, per the viewer's mapping. */
+    href: string;
+    meta: T;
+}
+/**
+ * Every entry in the surrounding bundle, with bundle-absolute paths and viewer-supplied
+ * hrefs — the surface a content component queries instead of {@link useMetadataQuery},
+ * whose keys are filesystem-absolute and therefore carry the mount prefix.
+ *
+ * Returns an empty array outside a bundle, so a component written for a bundle renders
+ * nothing rather than throwing when someone drops it elsewhere. The array keeps its
+ * identity while the store and root are unchanged, so it is safe in dependency arrays.
+ */
+declare const useBundleEntries: <T = Metadata>() => BundleEntry<T>[];
+/** One entry's frontmatter by bundle-absolute path, or `undefined`. */
+declare const useBundleEntry: <T = Metadata>(bundlePath: string) => T | undefined;
+/** The entry currently being read — `null` outside a bundle, or when the viewer declares
+ *  no entry (a directory listing, a 404). See {@link BundleScope.entry} for why this is
+ *  the entry rather than the file the component happens to be written in. */
+declare const useCurrentEntry: <T = Metadata>() => BundleEntry<T> | null;
+
+export { BundleContext, type BundleEntry, type BundleScope, fromBundlePath, toBundlePath, useBundle, useBundleEntries, useBundleEntry, useCurrentEntry };

package/dist/bundle.d.ts

@@ -0,0 +1,63 @@
+import * as react from 'react';
+import { Metadata } from './sandboxTypes.js';
+
+/** What a bundle viewer declares about the bundle it is rendering. */
+interface BundleScope {
+    /**
+     * Absolute filesystem path of the bundle root, WITHOUT a trailing slash
+     * (`/app/content` in a fork, `/mnt/<hash>` under dispatch), or `null` when the
+     * surrounding app is not rendering a bundle — the default, which leaves every hook here
+     * returning the empty result rather than guessing a root.
+     */
+    root: string | null;
+    /** Bundle-absolute path of the entry currently being read (`/roadmap/R3-174.mdx`), or
+     *  `null` when nothing is. This is the entry, NOT the file being rendered: a component
+     *  in a `_layout.mdx` wrapping that entry sees the entry, which is what makes furniture
+     *  in the layout chain (a status line, a dependency rail) able to describe the page. */
+    entry: string | null;
+    /** Bundle-absolute path → the href to navigate to it. Supplied by the viewer; the
+     *  identity function by default, which is correct for a viewer whose URL space IS the
+     *  bundle space. */
+    toHref: (bundlePath: string) => string;
+}
+/** Ambient bundle scope. A bundle-rendering app wraps its content tree in
+ *  `<BundleContext value={{ root, entry, toHref }}>`; nesting a second provider inside a
+ *  rendered sub-bundle makes the innermost win, as with {@link LinkSpaceContext}. */
+declare const BundleContext: react.Context<BundleScope>;
+/** Read the ambient bundle scope. Every hook below is a convenience over this. */
+declare const useBundle: () => BundleScope;
+/**
+ * Filesystem-absolute path → bundle-absolute, or `null` when the path is not inside the
+ * bundle. Exact-root and separator-boundary aware, so `/mnt/hash2/x` is not treated as
+ * living under `/mnt/hash`.
+ */
+declare const toBundlePath: (absolute: string, root: string | null) => string | null;
+/** Bundle-absolute path → filesystem-absolute, or `null` without a root. The inverse of
+ *  {@link toBundlePath}, for the rare content component that must read raw bytes. */
+declare const fromBundlePath: (bundlePath: string, root: string | null) => string | null;
+/** One entry as content sees it: where it is, where it links, and its frontmatter. */
+interface BundleEntry<T = Metadata> {
+    /** Bundle-absolute path (`/roadmap/R3-174.mdx`). */
+    path: string;
+    /** The href that navigates to it, per the viewer's mapping. */
+    href: string;
+    meta: T;
+}
+/**
+ * Every entry in the surrounding bundle, with bundle-absolute paths and viewer-supplied
+ * hrefs — the surface a content component queries instead of {@link useMetadataQuery},
+ * whose keys are filesystem-absolute and therefore carry the mount prefix.
+ *
+ * Returns an empty array outside a bundle, so a component written for a bundle renders
+ * nothing rather than throwing when someone drops it elsewhere. The array keeps its
+ * identity while the store and root are unchanged, so it is safe in dependency arrays.
+ */
+declare const useBundleEntries: <T = Metadata>() => BundleEntry<T>[];
+/** One entry's frontmatter by bundle-absolute path, or `undefined`. */
+declare const useBundleEntry: <T = Metadata>(bundlePath: string) => T | undefined;
+/** The entry currently being read — `null` outside a bundle, or when the viewer declares
+ *  no entry (a directory listing, a 404). See {@link BundleScope.entry} for why this is
+ *  the entry rather than the file the component happens to be written in. */
+declare const useCurrentEntry: <T = Metadata>() => BundleEntry<T> | null;
+
+export { BundleContext, type BundleEntry, type BundleScope, fromBundlePath, toBundlePath, useBundle, useBundleEntries, useBundleEntry, useCurrentEntry };