@immediately-run/sdk 0.45.3 → 0.46.0

package/dist/hostAttention.cjs

@@ -0,0 +1,57 @@
+"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 hostAttention_exports = {};
+__export(hostAttention_exports, {
+  NO_HOST_ATTENTION: () => NO_HOST_ATTENTION,
+  getHostAttention: () => getHostAttention,
+  onHostAttentionChange: () => onHostAttentionChange,
+  useHostAttention: () => useHostAttention
+});
+module.exports = __toCommonJS(hostAttention_exports);
+var import_pushChannel = require("./pushChannel");
+var import_protocol = require("./generated/protocol");
+const NO_HOST_ATTENTION = { awaiting: false, kind: null, since: null };
+const KINDS = /* @__PURE__ */ new Set(["passkey", "consent", "picker", "confirmation"]);
+const parseHostAttention = (value) => {
+  const a = value;
+  if (!a || typeof a !== "object" || typeof a.awaiting !== "boolean") return void 0;
+  if (!a.awaiting) return NO_HOST_ATTENTION;
+  return {
+    awaiting: true,
+    kind: typeof a.kind === "string" && KINDS.has(a.kind) ? a.kind : null,
+    since: typeof a.since === "number" ? a.since : null
+  };
+};
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: import_protocol.HOST_ATTENTION,
+  requestType: import_protocol.REQUEST_HOST_ATTENTION,
+  initial: NO_HOST_ATTENTION,
+  parse: (msg) => parseHostAttention(msg.attention)
+});
+const getHostAttention = () => channel.get();
+const onHostAttentionChange = (listener) => channel.onChange(listener);
+const useHostAttention = () => channel.use();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NO_HOST_ATTENTION,
+  getHostAttention,
+  onHostAttentionChange,
+  useHostAttention
+});
+//# sourceMappingURL=hostAttention.cjs.map

package/dist/hostAttention.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hostAttention.ts"],"sourcesContent":["// The host-attention channel (R3-307) — what the host is waiting for, right now.\n//\n// THE GAP THIS CLOSES. R3-298 bounded every host protocol call and classified each as\n// `attended` or `unattended`, but classification is per `(scheme, method)` and\n// attendedness is really a property of a MOMENT: `spaces:mount` is unattended when the\n// grant is already held and attended on first use, because the host raises consent INSIDE\n// the request. A per-method table cannot tell those apart, so R3-298 put anything that MAY\n// prompt on the long (attended) bound — which means the common grant-held path also waits\n// ten minutes before it reports a fault, and a caller can only say \"still waiting on\n// something that may need you\", never \"tap your passkey\".\n//\n// Only the HOST knows a prompt is on screen right now and what it is. So it says so, on a\n// channel every app can read, and two things become possible:\n//\n//   1. A surface can name what it is waiting for. \"Waiting for your passkey…\" instead of a\n//      spinner is most of a user's ability to act — especially on the provider-setup\n//      wizard's Test-connection step, whose whole purpose is to prove setup worked.\n//   2. The attended bounds become a fact rather than a guess. A may-prompt call runs on the\n//      SHORT bound and is suspended only while the host says a person is being asked\n//      (`protocolDeadline.ts`, `sandboxUtils.withDeadline`).\n//\n// WHAT IT DELIBERATELY DOES NOT CARRY. No secret value, no secret id, no app key, no\n// capability, no resource name — nothing from which a held grant could be inferred. It is\n// readable by every app at the baseline principal, so it says only that the HOST is busy\n// and with what KIND of prompt. That is information the user is already looking at: a host\n// modal is visible chrome. (The residual it does leave — one app observing that some prompt\n// is up while another app's call is in flight — is the accepted low-bandwidth L0 signalling\n// class of the threat model §7.6, and carries no identifying detail to signal WITH.)\nimport { createPushChannel } from './pushChannel';\nimport { HOST_ATTENTION, REQUEST_HOST_ATTENTION } from './generated/protocol';\n\n/**\n * What kind of host prompt is up.\n *\n * A closed set on purpose: it is the coarsest vocabulary that still lets a surface write a\n * sentence a user can act on, and adding a finer kind would start to describe the specific\n * thing being asked about — which is the disclosure this channel refuses.\n *\n * - `passkey` — a WebAuthn assertion. The user must tap their authenticator.\n * - `consent` — a capability/consent decision (mount, create, share, import, reference).\n * - `picker` — a host-drawn chooser or entry surface (the powerbox, the add-secret modal).\n * - `confirmation` — a notice or confirm the user must dismiss.\n */\nexport type HostAttentionKind = 'passkey' | 'consent' | 'picker' | 'confirmation';\n\n/** Whether the host is waiting on the user right now, and for what. */\nexport interface HostAttention {\n  /** `true` while a host prompt is on screen awaiting the user. */\n  awaiting: boolean;\n  /** The kind of prompt on screen — the innermost one, when they nest (an add-secret modal\n   *  that reaches the passkey unlock reports `passkey`). `null` when not awaiting. */\n  kind: HostAttentionKind | null;\n  /** `Date.now()` when the current wait began — the start of the whole continuous span, not\n   *  of the innermost prompt. `null` when not awaiting. */\n  since: number | null;\n}\n\n/** Assumed before the host reports, and the value on a host that never pushes this channel\n *  at all: nobody is being asked. Defaulting the OTHER way would suspend every may-prompt\n *  deadline forever on an older host, which is the hang this whole line of work removes. */\nexport const NO_HOST_ATTENTION: HostAttention = { awaiting: false, kind: null, since: null };\n\nconst KINDS: ReadonlySet<string> = new Set(['passkey', 'consent', 'picker', 'confirmation']);\n\n/** Tolerant parse: a host that pushes a malformed payload is ignored, not believed. An\n *  `awaiting` frame with no valid `kind` still counts as awaiting — the wait is the\n *  load-bearing bit and the copy can fall back to a generic sentence. */\nconst parseHostAttention = (value: unknown): HostAttention | undefined => {\n  const a = value as Partial<HostAttention> | null | undefined;\n  if (!a || typeof a !== 'object' || typeof a.awaiting !== 'boolean') return undefined;\n  if (!a.awaiting) return NO_HOST_ATTENTION;\n  return {\n    awaiting: true,\n    kind: typeof a.kind === 'string' && KINDS.has(a.kind) ? (a.kind as HostAttentionKind) : null,\n    since: typeof a.since === 'number' ? a.since : null,\n  };\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `host-attention` and\n// answers `request-host-attention` (wire format: site-main channelBridge.ts). Read\n// DEFENSIVELY — a host that does not yet push it simply never answers, `initial` stands,\n// and every caller behaves exactly as it did before this channel existed.\nconst channel = createPushChannel<HostAttention>({\n  pushType: HOST_ATTENTION,\n  requestType: REQUEST_HOST_ATTENTION,\n  initial: NO_HOST_ATTENTION,\n  parse: (msg) => parseHostAttention(msg.attention),\n});\n\n/** Returns what the host is waiting for right now. Poll for a one-off read. */\nexport const getHostAttention = (): HostAttention => channel.get();\n\n/**\n * Subscribe to host-attention changes. The listener is invoked immediately with the current\n * value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostAttentionChange = (listener: (attention: HostAttention) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning what the host is waiting for, re-rendering on change. */\nexport const useHostAttention = (): HostAttention => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4BA,yBAAkC;AAClC,sBAAuD;AA+BhD,MAAM,oBAAmC,EAAE,UAAU,OAAO,MAAM,MAAM,OAAO,KAAK;AAE3F,MAAM,QAA6B,oBAAI,IAAI,CAAC,WAAW,WAAW,UAAU,cAAc,CAAC;AAK3F,MAAM,qBAAqB,CAAC,UAA8C;AACxE,QAAM,IAAI;AACV,MAAI,CAAC,KAAK,OAAO,MAAM,YAAY,OAAO,EAAE,aAAa,UAAW,QAAO;AAC3E,MAAI,CAAC,EAAE,SAAU,QAAO;AACxB,SAAO;AAAA,IACL,UAAU;AAAA,IACV,MAAM,OAAO,EAAE,SAAS,YAAY,MAAM,IAAI,EAAE,IAAI,IAAK,EAAE,OAA6B;AAAA,IACxF,OAAO,OAAO,EAAE,UAAU,WAAW,EAAE,QAAQ;AAAA,EACjD;AACF;AAMA,MAAM,cAAU,sCAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ,mBAAmB,IAAI,SAAS;AAClD,CAAC;AAGM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}

package/dist/hostAttention.d.cts

@@ -0,0 +1,39 @@
+/**
+ * What kind of host prompt is up.
+ *
+ * A closed set on purpose: it is the coarsest vocabulary that still lets a surface write a
+ * sentence a user can act on, and adding a finer kind would start to describe the specific
+ * thing being asked about — which is the disclosure this channel refuses.
+ *
+ * - `passkey` — a WebAuthn assertion. The user must tap their authenticator.
+ * - `consent` — a capability/consent decision (mount, create, share, import, reference).
+ * - `picker` — a host-drawn chooser or entry surface (the powerbox, the add-secret modal).
+ * - `confirmation` — a notice or confirm the user must dismiss.
+ */
+type HostAttentionKind = 'passkey' | 'consent' | 'picker' | 'confirmation';
+/** Whether the host is waiting on the user right now, and for what. */
+interface HostAttention {
+    /** `true` while a host prompt is on screen awaiting the user. */
+    awaiting: boolean;
+    /** The kind of prompt on screen — the innermost one, when they nest (an add-secret modal
+     *  that reaches the passkey unlock reports `passkey`). `null` when not awaiting. */
+    kind: HostAttentionKind | null;
+    /** `Date.now()` when the current wait began — the start of the whole continuous span, not
+     *  of the innermost prompt. `null` when not awaiting. */
+    since: number | null;
+}
+/** Assumed before the host reports, and the value on a host that never pushes this channel
+ *  at all: nobody is being asked. Defaulting the OTHER way would suspend every may-prompt
+ *  deadline forever on an older host, which is the hang this whole line of work removes. */
+declare const NO_HOST_ATTENTION: HostAttention;
+/** Returns what the host is waiting for right now. Poll for a one-off read. */
+declare const getHostAttention: () => HostAttention;
+/**
+ * Subscribe to host-attention changes. The listener is invoked immediately with the current
+ * value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onHostAttentionChange: (listener: (attention: HostAttention) => void) => (() => void);
+/** React hook returning what the host is waiting for, re-rendering on change. */
+declare const useHostAttention: () => HostAttention;
+
+export { type HostAttention, type HostAttentionKind, NO_HOST_ATTENTION, getHostAttention, onHostAttentionChange, useHostAttention };

package/dist/hostAttention.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What kind of host prompt is up.
+ *
+ * A closed set on purpose: it is the coarsest vocabulary that still lets a surface write a
+ * sentence a user can act on, and adding a finer kind would start to describe the specific
+ * thing being asked about — which is the disclosure this channel refuses.
+ *
+ * - `passkey` — a WebAuthn assertion. The user must tap their authenticator.
+ * - `consent` — a capability/consent decision (mount, create, share, import, reference).
+ * - `picker` — a host-drawn chooser or entry surface (the powerbox, the add-secret modal).
+ * - `confirmation` — a notice or confirm the user must dismiss.
+ */
+type HostAttentionKind = 'passkey' | 'consent' | 'picker' | 'confirmation';
+/** Whether the host is waiting on the user right now, and for what. */
+interface HostAttention {
+    /** `true` while a host prompt is on screen awaiting the user. */
+    awaiting: boolean;
+    /** The kind of prompt on screen — the innermost one, when they nest (an add-secret modal
+     *  that reaches the passkey unlock reports `passkey`). `null` when not awaiting. */
+    kind: HostAttentionKind | null;
+    /** `Date.now()` when the current wait began — the start of the whole continuous span, not
+     *  of the innermost prompt. `null` when not awaiting. */
+    since: number | null;
+}
+/** Assumed before the host reports, and the value on a host that never pushes this channel
+ *  at all: nobody is being asked. Defaulting the OTHER way would suspend every may-prompt
+ *  deadline forever on an older host, which is the hang this whole line of work removes. */
+declare const NO_HOST_ATTENTION: HostAttention;
+/** Returns what the host is waiting for right now. Poll for a one-off read. */
+declare const getHostAttention: () => HostAttention;
+/**
+ * Subscribe to host-attention changes. The listener is invoked immediately with the current
+ * value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onHostAttentionChange: (listener: (attention: HostAttention) => void) => (() => void);
+/** React hook returning what the host is waiting for, re-rendering on change. */
+declare const useHostAttention: () => HostAttention;
+
+export { type HostAttention, type HostAttentionKind, NO_HOST_ATTENTION, getHostAttention, onHostAttentionChange, useHostAttention };

package/dist/hostAttention.js

@@ -0,0 +1,31 @@
+import "./chunk-VHAA22YE.js";
+import { createPushChannel } from "./pushChannel";
+import { HOST_ATTENTION, REQUEST_HOST_ATTENTION } from "./generated/protocol";
+const NO_HOST_ATTENTION = { awaiting: false, kind: null, since: null };
+const KINDS = /* @__PURE__ */ new Set(["passkey", "consent", "picker", "confirmation"]);
+const parseHostAttention = (value) => {
+  const a = value;
+  if (!a || typeof a !== "object" || typeof a.awaiting !== "boolean") return void 0;
+  if (!a.awaiting) return NO_HOST_ATTENTION;
+  return {
+    awaiting: true,
+    kind: typeof a.kind === "string" && KINDS.has(a.kind) ? a.kind : null,
+    since: typeof a.since === "number" ? a.since : null
+  };
+};
+const channel = createPushChannel({
+  pushType: HOST_ATTENTION,
+  requestType: REQUEST_HOST_ATTENTION,
+  initial: NO_HOST_ATTENTION,
+  parse: (msg) => parseHostAttention(msg.attention)
+});
+const getHostAttention = () => channel.get();
+const onHostAttentionChange = (listener) => channel.onChange(listener);
+const useHostAttention = () => channel.use();
+export {
+  NO_HOST_ATTENTION,
+  getHostAttention,
+  onHostAttentionChange,
+  useHostAttention
+};
+//# sourceMappingURL=hostAttention.js.map

package/dist/hostAttention.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hostAttention.ts"],"sourcesContent":["// The host-attention channel (R3-307) — what the host is waiting for, right now.\n//\n// THE GAP THIS CLOSES. R3-298 bounded every host protocol call and classified each as\n// `attended` or `unattended`, but classification is per `(scheme, method)` and\n// attendedness is really a property of a MOMENT: `spaces:mount` is unattended when the\n// grant is already held and attended on first use, because the host raises consent INSIDE\n// the request. A per-method table cannot tell those apart, so R3-298 put anything that MAY\n// prompt on the long (attended) bound — which means the common grant-held path also waits\n// ten minutes before it reports a fault, and a caller can only say \"still waiting on\n// something that may need you\", never \"tap your passkey\".\n//\n// Only the HOST knows a prompt is on screen right now and what it is. So it says so, on a\n// channel every app can read, and two things become possible:\n//\n//   1. A surface can name what it is waiting for. \"Waiting for your passkey…\" instead of a\n//      spinner is most of a user's ability to act — especially on the provider-setup\n//      wizard's Test-connection step, whose whole purpose is to prove setup worked.\n//   2. The attended bounds become a fact rather than a guess. A may-prompt call runs on the\n//      SHORT bound and is suspended only while the host says a person is being asked\n//      (`protocolDeadline.ts`, `sandboxUtils.withDeadline`).\n//\n// WHAT IT DELIBERATELY DOES NOT CARRY. No secret value, no secret id, no app key, no\n// capability, no resource name — nothing from which a held grant could be inferred. It is\n// readable by every app at the baseline principal, so it says only that the HOST is busy\n// and with what KIND of prompt. That is information the user is already looking at: a host\n// modal is visible chrome. (The residual it does leave — one app observing that some prompt\n// is up while another app's call is in flight — is the accepted low-bandwidth L0 signalling\n// class of the threat model §7.6, and carries no identifying detail to signal WITH.)\nimport { createPushChannel } from './pushChannel';\nimport { HOST_ATTENTION, REQUEST_HOST_ATTENTION } from './generated/protocol';\n\n/**\n * What kind of host prompt is up.\n *\n * A closed set on purpose: it is the coarsest vocabulary that still lets a surface write a\n * sentence a user can act on, and adding a finer kind would start to describe the specific\n * thing being asked about — which is the disclosure this channel refuses.\n *\n * - `passkey` — a WebAuthn assertion. The user must tap their authenticator.\n * - `consent` — a capability/consent decision (mount, create, share, import, reference).\n * - `picker` — a host-drawn chooser or entry surface (the powerbox, the add-secret modal).\n * - `confirmation` — a notice or confirm the user must dismiss.\n */\nexport type HostAttentionKind = 'passkey' | 'consent' | 'picker' | 'confirmation';\n\n/** Whether the host is waiting on the user right now, and for what. */\nexport interface HostAttention {\n  /** `true` while a host prompt is on screen awaiting the user. */\n  awaiting: boolean;\n  /** The kind of prompt on screen — the innermost one, when they nest (an add-secret modal\n   *  that reaches the passkey unlock reports `passkey`). `null` when not awaiting. */\n  kind: HostAttentionKind | null;\n  /** `Date.now()` when the current wait began — the start of the whole continuous span, not\n   *  of the innermost prompt. `null` when not awaiting. */\n  since: number | null;\n}\n\n/** Assumed before the host reports, and the value on a host that never pushes this channel\n *  at all: nobody is being asked. Defaulting the OTHER way would suspend every may-prompt\n *  deadline forever on an older host, which is the hang this whole line of work removes. */\nexport const NO_HOST_ATTENTION: HostAttention = { awaiting: false, kind: null, since: null };\n\nconst KINDS: ReadonlySet<string> = new Set(['passkey', 'consent', 'picker', 'confirmation']);\n\n/** Tolerant parse: a host that pushes a malformed payload is ignored, not believed. An\n *  `awaiting` frame with no valid `kind` still counts as awaiting — the wait is the\n *  load-bearing bit and the copy can fall back to a generic sentence. */\nconst parseHostAttention = (value: unknown): HostAttention | undefined => {\n  const a = value as Partial<HostAttention> | null | undefined;\n  if (!a || typeof a !== 'object' || typeof a.awaiting !== 'boolean') return undefined;\n  if (!a.awaiting) return NO_HOST_ATTENTION;\n  return {\n    awaiting: true,\n    kind: typeof a.kind === 'string' && KINDS.has(a.kind) ? (a.kind as HostAttentionKind) : null,\n    since: typeof a.since === 'number' ? a.since : null,\n  };\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `host-attention` and\n// answers `request-host-attention` (wire format: site-main channelBridge.ts). Read\n// DEFENSIVELY — a host that does not yet push it simply never answers, `initial` stands,\n// and every caller behaves exactly as it did before this channel existed.\nconst channel = createPushChannel<HostAttention>({\n  pushType: HOST_ATTENTION,\n  requestType: REQUEST_HOST_ATTENTION,\n  initial: NO_HOST_ATTENTION,\n  parse: (msg) => parseHostAttention(msg.attention),\n});\n\n/** Returns what the host is waiting for right now. Poll for a one-off read. */\nexport const getHostAttention = (): HostAttention => channel.get();\n\n/**\n * Subscribe to host-attention changes. The listener is invoked immediately with the current\n * value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostAttentionChange = (listener: (attention: HostAttention) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning what the host is waiting for, re-rendering on change. */\nexport const useHostAttention = (): HostAttention => channel.use();\n"],"mappings":";AA4BA,SAAS,yBAAyB;AAClC,SAAS,gBAAgB,8BAA8B;AA+BhD,MAAM,oBAAmC,EAAE,UAAU,OAAO,MAAM,MAAM,OAAO,KAAK;AAE3F,MAAM,QAA6B,oBAAI,IAAI,CAAC,WAAW,WAAW,UAAU,cAAc,CAAC;AAK3F,MAAM,qBAAqB,CAAC,UAA8C;AACxE,QAAM,IAAI;AACV,MAAI,CAAC,KAAK,OAAO,MAAM,YAAY,OAAO,EAAE,aAAa,UAAW,QAAO;AAC3E,MAAI,CAAC,EAAE,SAAU,QAAO;AACxB,SAAO;AAAA,IACL,UAAU;AAAA,IACV,MAAM,OAAO,EAAE,SAAS,YAAY,MAAM,IAAI,EAAE,IAAI,IAAK,EAAE,OAA6B;AAAA,IACxF,OAAO,OAAO,EAAE,UAAU,WAAW,EAAE,QAAQ;AAAA,EACjD;AACF;AAMA,MAAM,UAAU,kBAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ,mBAAmB,IAAI,SAAS;AAClD,CAAC;AAGM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}

package/dist/hostTransport.cjs

@@ -0,0 +1,55 @@
+"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 hostTransport_exports = {};
+__export(hostTransport_exports, {
+  addListener: () => addListener,
+  sendMessage: () => sendMessage,
+  transport: () => transport
+});
+module.exports = __toCommonJS(hostTransport_exports);
+var import_hostRuntime = require("./hostRuntime");
+function transport() {
+  try {
+    const injected = module?.evaluation?.module?.bundler?.messageBus;
+    if (injected && typeof injected.sendMessage === "function") return injected;
+  } catch {
+  }
+  const t = (0, import_hostRuntime.getHostRuntime)()?.transport;
+  if (t && typeof t.sendMessage === "function") return t;
+  throw new Error("immediately.run: no host transport (neither injected nor __immediatelyRun__)");
+}
+const sendMessage = (type, data = {}) => {
+  transport().sendMessage(type, data);
+};
+const addListener = (msgType, handler, event) => {
+  const onMessage = event ?? transport().onMessage;
+  const disposable = onMessage((msg) => {
+    if (msg.type === msgType) {
+      handler(msg);
+    }
+  });
+  return () => disposable.dispose();
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  addListener,
+  sendMessage,
+  transport
+});
+//# sourceMappingURL=hostTransport.cjs.map

package/dist/hostTransport.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hostTransport.ts"],"sourcesContent":["// The host transport resolver (SDK_PACKAGING_SPEC §4, expose-transport) — the ONE place\n// that answers \"how do I reach the host from here\".\n//\n// All host comms (sendMessage / protocolRequest / onMessage) go through this resolver so\n// the SDK is transport-agnostic: it works whether it was INJECTED into the bundler's\n// evaluation context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands it\n// the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is byte-for-byte\n// preserved; the global is the fallback the npm-fetched SDK uses. When injection is removed\n// (phase 3), only the global path remains — `bundler.*` stops being API, which is the whole\n// point.\n//\n// WHY THIS IS ITS OWN MODULE (R3-307). It was the bottom half of `sandboxUtils.ts` until\n// the deadline machinery grew a dependency on the host-attention push channel. A push\n// channel needs the transport, and `withDeadline` needs the channel, so leaving both in one\n// module made `sandboxUtils → hostAttention → pushChannel → sandboxUtils` — a cycle, and\n// this package's import graph is CI-enforced acyclic (`check:circular`; a circular SDK\n// import once made the bundler infinite-loop). Splitting the *primitives* out puts\n// `sandboxUtils` at the TOP of the graph instead of in the middle of it. `sandboxUtils`\n// re-exports `sendMessage`/`addListener`, so every existing import site is unchanged and\n// the api-snapshot entry for that module keeps all four of its names.\nimport { getHostRuntime } from './hostRuntime';\n\nexport interface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nexport function transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBA,yBAA+B;AAQxB,SAAS,YAA2B;AAEzC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,QAAI,mCAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}

package/dist/hostTransport.d.cts

@@ -0,0 +1,12 @@
+interface HostTransport {
+    sendMessage(type: string, data?: Record<string, any>): void;
+    protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;
+    onMessage(handler: (msg: any) => void): {
+        dispose(): void;
+    };
+}
+declare function transport(): HostTransport;
+declare const sendMessage: (type: string, data?: Record<string, any>) => void;
+declare const addListener: (msgType: string, handler: (msg: any) => void, event?: any) => (() => void);
+
+export { type HostTransport, addListener, sendMessage, transport };

package/dist/hostTransport.d.ts

@@ -0,0 +1,12 @@
+interface HostTransport {
+    sendMessage(type: string, data?: Record<string, any>): void;
+    protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;
+    onMessage(handler: (msg: any) => void): {
+        dispose(): void;
+    };
+}
+declare function transport(): HostTransport;
+declare const sendMessage: (type: string, data?: Record<string, any>) => void;
+declare const addListener: (msgType: string, handler: (msg: any) => void, event?: any) => (() => void);
+
+export { type HostTransport, addListener, sendMessage, transport };

package/dist/hostTransport.js

@@ -0,0 +1,30 @@
+import "./chunk-VHAA22YE.js";
+import { getHostRuntime } from "./hostRuntime";
+function transport() {
+  try {
+    const injected = module?.evaluation?.module?.bundler?.messageBus;
+    if (injected && typeof injected.sendMessage === "function") return injected;
+  } catch {
+  }
+  const t = getHostRuntime()?.transport;
+  if (t && typeof t.sendMessage === "function") return t;
+  throw new Error("immediately.run: no host transport (neither injected nor __immediatelyRun__)");
+}
+const sendMessage = (type, data = {}) => {
+  transport().sendMessage(type, data);
+};
+const addListener = (msgType, handler, event) => {
+  const onMessage = event ?? transport().onMessage;
+  const disposable = onMessage((msg) => {
+    if (msg.type === msgType) {
+      handler(msg);
+    }
+  });
+  return () => disposable.dispose();
+};
+export {
+  addListener,
+  sendMessage,
+  transport
+};
+//# sourceMappingURL=hostTransport.js.map

package/dist/hostTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hostTransport.ts"],"sourcesContent":["// The host transport resolver (SDK_PACKAGING_SPEC §4, expose-transport) — the ONE place\n// that answers \"how do I reach the host from here\".\n//\n// All host comms (sendMessage / protocolRequest / onMessage) go through this resolver so\n// the SDK is transport-agnostic: it works whether it was INJECTED into the bundler's\n// evaluation context (the current path — `module.evaluation.module.bundler.messageBus`) OR\n// fetched from npm as an ordinary dependency, in which case the sandbox runtime hands it\n// the transport via the §4 discovery global (`globalThis.__immediatelyRun__`).\n//\n// Dual-mode (§8): injection wins while it's active, so existing behaviour is byte-for-byte\n// preserved; the global is the fallback the npm-fetched SDK uses. When injection is removed\n// (phase 3), only the global path remains — `bundler.*` stops being API, which is the whole\n// point.\n//\n// WHY THIS IS ITS OWN MODULE (R3-307). It was the bottom half of `sandboxUtils.ts` until\n// the deadline machinery grew a dependency on the host-attention push channel. A push\n// channel needs the transport, and `withDeadline` needs the channel, so leaving both in one\n// module made `sandboxUtils → hostAttention → pushChannel → sandboxUtils` — a cycle, and\n// this package's import graph is CI-enforced acyclic (`check:circular`; a circular SDK\n// import once made the bundler infinite-loop). Splitting the *primitives* out puts\n// `sandboxUtils` at the TOP of the graph instead of in the middle of it. `sandboxUtils`\n// re-exports `sendMessage`/`addListener`, so every existing import site is unchanged and\n// the api-snapshot entry for that module keeps all four of its names.\nimport { getHostRuntime } from './hostRuntime';\n\nexport interface HostTransport {\n  sendMessage(type: string, data?: Record<string, any>): void;\n  protocolRequest(protocolName: string, method: string, params: Array<any>): Promise<any>;\n  onMessage(handler: (msg: any) => void): { dispose(): void };\n}\n\nexport function transport(): HostTransport {\n  // Injected bundler messageBus first — the current path, unchanged.\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    const injected = module?.evaluation?.module?.bundler?.messageBus;\n    if (injected && typeof injected.sendMessage === 'function') return injected;\n  } catch {\n    /* no injection in this realm — fall through to the §4 global */\n  }\n  // §4 runtime-discovery transport (the npm-fetched SDK path).\n  const t = getHostRuntime()?.transport as HostTransport | undefined;\n  if (t && typeof t.sendMessage === 'function') return t;\n  throw new Error('immediately.run: no host transport (neither injected nor __immediatelyRun__)');\n}\n\nexport const sendMessage = (type: string, data: Record<string, any> = {}) => {\n  transport().sendMessage(type, data);\n};\n\nexport const addListener = (\n  msgType: string,\n  handler: (msg: any) => void,\n  event?: any,\n): (() => void) => {\n  const onMessage = event ?? transport().onMessage;\n  const disposable = onMessage((msg: any) => {\n    if (msg.type === msgType) {\n      handler(msg);\n    }\n  });\n  return () => disposable.dispose();\n};\n"],"mappings":";AAuBA,SAAS,sBAAsB;AAQxB,SAAS,YAA2B;AAEzC,MAAI;AAEF,UAAM,WAAW,QAAQ,YAAY,QAAQ,SAAS;AACtD,QAAI,YAAY,OAAO,SAAS,gBAAgB,WAAY,QAAO;AAAA,EACrE,QAAQ;AAAA,EAER;AAEA,QAAM,IAAI,eAAe,GAAG;AAC5B,MAAI,KAAK,OAAO,EAAE,gBAAgB,WAAY,QAAO;AACrD,QAAM,IAAI,MAAM,8EAA8E;AAChG;AAEO,MAAM,cAAc,CAAC,MAAc,OAA4B,CAAC,MAAM;AAC3E,YAAU,EAAE,YAAY,MAAM,IAAI;AACpC;AAEO,MAAM,cAAc,CACzB,SACA,SACA,UACiB;AACjB,QAAM,YAAY,SAAS,UAAU,EAAE;AACvC,QAAM,aAAa,UAAU,CAAC,QAAa;AACzC,QAAI,IAAI,SAAS,SAAS;AACxB,cAAQ,GAAG;AAAA,IACb;AAAA,EACF,CAAC;AACD,SAAO,MAAM,WAAW,QAAQ;AAClC;","names":[]}

package/dist/index.cjs

@@ -39,6 +39,7 @@ __reExport(index_exports, require("./theme"), module.exports);
 __reExport(index_exports, require("./editorContext"), module.exports);
 __reExport(index_exports, require("./editor"), module.exports);
 __reExport(index_exports, require("./formFactor"), module.exports);
+__reExport(index_exports, require("./hostAttention"), module.exports);
 __reExport(index_exports, require("./region"), module.exports);
 __reExport(index_exports, require("./mounts"), module.exports);
 __reExport(index_exports, require("./contribute"), module.exports);
@@ -60,6 +61,7 @@ __reExport(index_exports, require("./irMarkers"), module.exports);
 __reExport(index_exports, require("./ready"), module.exports);
 __reExport(index_exports, require("./loading"), module.exports);
 __reExport(index_exports, require("./protocolStream"), module.exports);
+__reExport(index_exports, require("./protocolDeadline"), module.exports);
 __reExport(index_exports, require("./sandboxTypes"), module.exports);
 __reExport(index_exports, require("./safeContent"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
@@ -81,6 +83,7 @@ __reExport(index_exports, require("./safeContent"), module.exports);
   ...require("./editorContext"),
   ...require("./editor"),
   ...require("./formFactor"),
+  ...require("./hostAttention"),
   ...require("./region"),
   ...require("./mounts"),
   ...require("./contribute"),
@@ -102,6 +105,7 @@ __reExport(index_exports, require("./safeContent"), module.exports);
   ...require("./ready"),
   ...require("./loading"),
   ...require("./protocolStream"),
+  ...require("./protocolDeadline"),
   ...require("./sandboxTypes"),
   ...require("./safeContent")
 });

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAQA,yBAA4B;AAC5B,0BAAc,0BATd;AAUA,0BAAc,uCAVd;AAWA,0BAAc,wBAXd;AAYA,0BAAc,oCAZd;AAaA,0BAAc,gCAbd;AAcA,0BAAc,oBAdd;AAiBA,0BAAc,6BAjBd;AAkBA,0BAAc,mBAlBd;AAmBA,0BAAc,oBAnBd;AAoBA,0BAAc,4BApBd;AAqBA,0BAAc,qBArBd;AAsBA,0BAAc,yBAtBd;AAuBA,0BAAc,qBAvBd;AAwBA,0BAAc,qBAxBd;AAyBA,0BAAc,yBAzBd;AA0BA,0BAAc,sBA1Bd;AA2BA,0BAAc,kBA3Bd;AA4BA,0BAAc,kBA5Bd;AA6BA,0BAAc,uBA7Bd;AA8BA,0BAAc,sBA9Bd;AA+BA,0BAAc,kBA/Bd;AAgCA,0BAAc,0BAhCd;AAiCA,0BAAc,kBAjCd;AAkCA,0BAAc,yBAlCd;AAmCA,0BAAc,iBAnCd;AAoCA,0BAAc,oBApCd;AAqCA,0BAAc,oBArCd;AAsCA,0BAAc,qBAtCd;AAuCA,0BAAc,sBAvCd;AAwCA,0BAAc,wBAxCd;AAyCA,0BAAc,oBAzCd;AA0CA,0BAAc,sBA1Cd;AA2CA,0BAAc,6BA3Cd;AA4CA,0BAAc,2BA5Cd;AA6CA,0BAAc,0BA7Cd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAQA,yBAA4B;AAC5B,0BAAc,0BATd;AAUA,0BAAc,uCAVd;AAWA,0BAAc,wBAXd;AAYA,0BAAc,oCAZd;AAaA,0BAAc,gCAbd;AAcA,0BAAc,oBAdd;AAiBA,0BAAc,6BAjBd;AAkBA,0BAAc,mBAlBd;AAmBA,0BAAc,oBAnBd;AAoBA,0BAAc,4BApBd;AAqBA,0BAAc,qBArBd;AAsBA,0BAAc,yBAtBd;AAuBA,0BAAc,4BAvBd;AAwBA,0BAAc,qBAxBd;AAyBA,0BAAc,qBAzBd;AA0BA,0BAAc,yBA1Bd;AA2BA,0BAAc,sBA3Bd;AA4BA,0BAAc,kBA5Bd;AA6BA,0BAAc,kBA7Bd;AA8BA,0BAAc,uBA9Bd;AA+BA,0BAAc,sBA/Bd;AAgCA,0BAAc,kBAhCd;AAiCA,0BAAc,0BAjCd;AAkCA,0BAAc,kBAlCd;AAmCA,0BAAc,yBAnCd;AAoCA,0BAAc,iBApCd;AAqCA,0BAAc,oBArCd;AAsCA,0BAAc,oBAtCd;AAuCA,0BAAc,qBAvCd;AAwCA,0BAAc,sBAxCd;AAyCA,0BAAc,wBAzCd;AA0CA,0BAAc,oBA1Cd;AA2CA,0BAAc,sBA3Cd;AA4CA,0BAAc,6BA5Cd;AA6CA,0BAAc,+BA7Cd;AA8CA,0BAAc,2BA9Cd;AA+CA,0BAAc,0BA/Cd;","names":[]}

package/dist/index.d.cts

@@ -15,6 +15,7 @@ export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.cjs';
 export { EditTarget, EditorOpenError, EditorSessionError, EditorWriteError, RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile } from './editor.cjs';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.cjs';
+export { HostAttention, HostAttentionKind, NO_HOST_ATTENTION, getHostAttention, onHostAttentionChange, useHostAttention } from './hostAttention.cjs';
 export { getRegion, useRegion } from './region.cjs';
 export { Invite, MountQuery, MountRemoveReason, MountRule, RemovedMount, SandboxMount, SessionMount, SpaceError, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, importSettingsFromParent, listMyInvites, listPendingInvites, listSettingsApps, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeInvite, unmountSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.cjs';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.cjs';
@@ -23,7 +24,7 @@ export { RegionMessage, onRegionMessage, postToRegion, revealRegion, useRegionMe
 export { DraggableItem, DroppedItem, ItemDragError, cancelItemDrag, onItemDrop, startItemDrag, useDroppedItem } from './dnd.cjs';
 export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStreamResult, hostFetch, hostFetchStream } from './netFetch.cjs';
 export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.cjs';
-export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.cjs';
+export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatProviderState, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, describeChatState, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState } from './llm.cjs';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.cjs';
 export { VcsActionError, VcsBranch, VcsChange, VcsPR, VcsState, getVcsState, onVcsStateChange, refreshDiff, refreshPRs, resetWorkingTree, useVcsState } from './vcs.cjs';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.cjs';
@@ -36,6 +37,7 @@ export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMar
 export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.cjs';
 export { LOADING_TIMINGS, LoadingRegion, Skeleton, SkeletonArchetype, SkeletonRow, Spinner } from './loading.cjs';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.cjs';
+export { ATTENDED_FIRST_FRAME_MS, ATTENDED_TIMEOUT_MS, Attendance, BoundedCallOptions, CallBounds, DeadlineBound, NETWORK_TIMEOUT_MS, PENDING_NOTICE_MS, PendingAttention, PendingState, ProtocolCancelledError, ProtocolTimeoutError, STREAM_IDLE_TIMEOUT_MS, SuspendableDeadline, UNATTENDED_TIMEOUT_MS, attendanceOf, attendanceReason, boundsFor, createSuspendableDeadline, firstFrameBoundsFor, firstFrameTimeoutFor, timeoutFor } from './protocolDeadline.cjs';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryRecord, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
 export { SafeContent, SafeContentProps } from './safeContent/SafeContent.cjs';
 export { RenderMdastOptions, SafeContentComponents, renderMdast } from './safeContent/renderMdast.cjs';

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.js';
 export { EditTarget, EditorOpenError, EditorSessionError, EditorWriteError, RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile } from './editor.js';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.js';
+export { HostAttention, HostAttentionKind, NO_HOST_ATTENTION, getHostAttention, onHostAttentionChange, useHostAttention } from './hostAttention.js';
 export { getRegion, useRegion } from './region.js';
 export { Invite, MountQuery, MountRemoveReason, MountRule, RemovedMount, SandboxMount, SessionMount, SpaceError, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, importSettingsFromParent, listMyInvites, listPendingInvites, listSettingsApps, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeInvite, unmountSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.js';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.js';
@@ -23,7 +24,7 @@ export { RegionMessage, onRegionMessage, postToRegion, revealRegion, useRegionMe
 export { DraggableItem, DroppedItem, ItemDragError, cancelItemDrag, onItemDrop, startItemDrag, useDroppedItem } from './dnd.js';
 export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStreamResult, hostFetch, hostFetchStream } from './netFetch.js';
 export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.js';
-export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.js';
+export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatProviderState, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, describeChatState, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState } from './llm.js';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.js';
 export { VcsActionError, VcsBranch, VcsChange, VcsPR, VcsState, getVcsState, onVcsStateChange, refreshDiff, refreshPRs, resetWorkingTree, useVcsState } from './vcs.js';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.js';
@@ -36,6 +37,7 @@ export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMar
 export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.js';
 export { LOADING_TIMINGS, LoadingRegion, Skeleton, SkeletonArchetype, SkeletonRow, Spinner } from './loading.js';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.js';
+export { ATTENDED_FIRST_FRAME_MS, ATTENDED_TIMEOUT_MS, Attendance, BoundedCallOptions, CallBounds, DeadlineBound, NETWORK_TIMEOUT_MS, PENDING_NOTICE_MS, PendingAttention, PendingState, ProtocolCancelledError, ProtocolTimeoutError, STREAM_IDLE_TIMEOUT_MS, SuspendableDeadline, UNATTENDED_TIMEOUT_MS, attendanceOf, attendanceReason, boundsFor, createSuspendableDeadline, firstFrameBoundsFor, firstFrameTimeoutFor, timeoutFor } from './protocolDeadline.js';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryRecord, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
 export { SafeContent, SafeContentProps } from './safeContent/SafeContent.js';
 export { RenderMdastOptions, SafeContentComponents, renderMdast } from './safeContent/renderMdast.js';

package/dist/index.js

@@ -16,6 +16,7 @@ export * from "./theme";
 export * from "./editorContext";
 export * from "./editor";
 export * from "./formFactor";
+export * from "./hostAttention";
 export * from "./region";
 export * from "./mounts";
 export * from "./contribute";
@@ -37,6 +38,7 @@ export * from "./irMarkers";
 export * from "./ready";
 export * from "./loading";
 export * from "./protocolStream";
+export * from "./protocolDeadline";
 export * from "./sandboxTypes";
 export * from "./safeContent";
 export {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/linkSpace.cjs

@@ -26,7 +26,10 @@ __export(linkSpace_exports, {
 module.exports = __toCommonJS(linkSpace_exports);
 var import_react = require("react");
 const FS_PREFIX = "$fs:";
-const LinkSpaceContext = (0, import_react.createContext)({ corpusRoot: null });
+const LinkSpaceContext = (0, import_react.createContext)({
+  corpusRoot: null,
+  bundleChrooted: false
+});
 const normalizeAbsolute = (path) => {
   const out = [];
   for (const seg of path.split("/")) {
@@ -36,16 +39,22 @@ const normalizeAbsolute = (path) => {
   }
   return "/" + out.join("/");
 };
+function resolveCorpusAbsolute(path, corpusRoot) {
+  const inner = normalizeAbsolute(path);
+  if (corpusRoot === null || corpusRoot === "/") return { state: "resolved", path: inner };
+  return { state: "resolved", path: normalizeAbsolute(corpusRoot + inner) };
+}
 function resolveLinkTarget(raw, opts = {}) {
   if (raw.startsWith(FS_PREFIX)) {
     const rest = raw.slice(FS_PREFIX.length);
     if (!rest.startsWith("/")) return { state: "invalid" };
+    if (opts.bundleChrooted) return resolveCorpusAbsolute(rest, opts.corpusRoot ?? null);
     return { state: "resolved", path: normalizeAbsolute(rest) };
   }
   if (raw.startsWith("/")) {
     const corpusRoot = opts.corpusRoot ?? null;
     if (corpusRoot !== null) {
-      return { state: "resolved", path: normalizeAbsolute(corpusRoot + normalizeAbsolute(raw)) };
+      return resolveCorpusAbsolute(raw, corpusRoot);
     }
     return { state: "resolved", path: normalizeAbsolute(raw) };
   }

package/dist/linkSpace.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/linkSpace.ts"],"sourcesContent":["// Link path spaces (R3-273; REPO_CONTENT_DISPATCH_SPEC §9 decision, 2026-08-17).\n//\n// A document link's target resolves in one of two spaces:\n//\n// - DEFAULT — the enclosing corpus's virtual filesystem. RELATIVE targets resolve\n//   against the authoring file (identical in both spaces); ABSOLUTE targets\n//   (`/x/y.mdx`) resolve from the corpus root when an enclosing `LinkSpaceContext`\n//   declares one, else from the filesystem root. A non-corpus app declares nothing\n//   and keeps today's behavior bit-for-bit (its fs root IS its only root).\n//\n// - `$fs:` — the explicit filesystem space: `$fs:/content/x.mdx` resolves from the\n//   root of the filesystem the app reads, escaping corpus-relative addressing.\n//\n// `$fs:` changes ADDRESSING, never REACH: resolution is pure path arithmetic and\n// existence is checked against the same in-mount metadata the default space uses —\n// nothing is fetched, and a link can never name what the app cannot already read.\n// A malformed `$fs:` target (anything not mount-absolute — which also catches\n// scheme smuggling like `$fs:javascript:…`) is INVALID and must render as a broken\n// link, never an anchor.\n//\n// Corpus nesting: `LinkSpaceContext` providers nest, and the NEAREST one wins —\n// which is exactly the innermost-enclosing-corpus rule (bundle encapsulation): a\n// document rendered inside a nested corpus resolves against the nested corpus.\n\nimport { createContext } from 'react';\n\nexport const FS_PREFIX = '$fs:';\n\nexport interface LinkSpace {\n  /** Absolute filesystem path of the enclosing corpus's root (e.g. `/app/content`),\n   *  or `null` when the document is not corpus-hosted (default). */\n  corpusRoot: string | null;\n}\n\n/** Ambient link space. A corpus-rendering app wraps its document tree in\n *  `<LinkSpaceContext value={{ corpusRoot }}>`; nesting a second provider inside a\n *  rendered sub-corpus makes the innermost root win. */\nexport const LinkSpaceContext = createContext<LinkSpace>({ corpusRoot: null });\n\n/** Collapse `.`/`..`/empty segments into a clean absolute path. `..` can never\n *  climb above the root — a (virtual) root's parent is itself, which is what keeps\n *  both the mount space and the corpus space closed under traversal. */\nexport const normalizeAbsolute = (path: string): string => {\n  const out: string[] = [];\n  for (const seg of path.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') out.pop();\n    else out.push(seg);\n  }\n  return '/' + out.join('/');\n};\n\nexport type ResolvedLinkTarget =\n  /** Resolved to an absolute filesystem path (existence NOT checked here). */\n  | { state: 'resolved'; path: string }\n  /** A relative target with no known authoring file — the caller may route\n   *  optimistically (it cannot check existence or self-ness generically). */\n  | { state: 'unresolvable' }\n  /** A malformed `$fs:` target (not mount-absolute; includes scheme smuggling).\n   *  Callers MUST render this broken/inert — never as an anchor. */\n  | { state: 'invalid' };\n\n/**\n * Resolve a raw link target (a wikilink target or an in-app href's path half —\n * fragment already split off) to an absolute filesystem path. THE shared resolver:\n * the default `WikiLink`, the markdown `a` override, and safe-content consumers\n * all route through this one function so the two render pipelines cannot drift.\n */\nexport function resolveLinkTarget(\n  raw: string,\n  opts: { currentFile?: string; corpusRoot?: string | null } = {},\n): ResolvedLinkTarget {\n  if (raw.startsWith(FS_PREFIX)) {\n    const rest = raw.slice(FS_PREFIX.length);\n    // Must be mount-absolute. This single rule also fails `$fs:javascript:…`,\n    // `$fs:https://…`, and every other smuggled scheme closed.\n    if (!rest.startsWith('/')) return { state: 'invalid' };\n    return { state: 'resolved', path: normalizeAbsolute(rest) };\n  }\n  if (raw.startsWith('/')) {\n    const corpusRoot = opts.corpusRoot ?? null;\n    if (corpusRoot !== null) {\n      // Clamp the corpus-relative half FIRST (the virtual FS is closed — `/../x`\n      // stays inside the corpus), THEN anchor it at the corpus root.\n      return { state: 'resolved', path: normalizeAbsolute(corpusRoot + normalizeAbsolute(raw)) };\n    }\n    return { state: 'resolved', path: normalizeAbsolute(raw) };\n  }\n  // Relative: against the authoring file's directory — the same in both spaces.\n  if (!opts.currentFile) return { state: 'unresolvable' };\n  const dir = opts.currentFile.slice(0, opts.currentFile.lastIndexOf('/'));\n  return { state: 'resolved', path: normalizeAbsolute(`${dir}/${raw}`) };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwBA,mBAA8B;AAEvB,MAAM,YAAY;AAWlB,MAAM,uBAAmB,4BAAyB,EAAE,YAAY,KAAK,CAAC;AAKtE,MAAM,oBAAoB,CAAC,SAAyB;AACzD,QAAM,MAAgB,CAAC;AACvB,aAAW,OAAO,KAAK,MAAM,GAAG,GAAG;AACjC,QAAI,QAAQ,MAAM,QAAQ,IAAK;AAC/B,QAAI,QAAQ,KAAM,KAAI,IAAI;AAAA,QACrB,KAAI,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,MAAM,IAAI,KAAK,GAAG;AAC3B;AAkBO,SAAS,kBACd,KACA,OAA6D,CAAC,GAC1C;AACpB,MAAI,IAAI,WAAW,SAAS,GAAG;AAC7B,UAAM,OAAO,IAAI,MAAM,UAAU,MAAM;AAGvC,QAAI,CAAC,KAAK,WAAW,GAAG,EAAG,QAAO,EAAE,OAAO,UAAU;AACrD,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,IAAI,EAAE;AAAA,EAC5D;AACA,MAAI,IAAI,WAAW,GAAG,GAAG;AACvB,UAAM,aAAa,KAAK,cAAc;AACtC,QAAI,eAAe,MAAM;AAGvB,aAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,aAAa,kBAAkB,GAAG,CAAC,EAAE;AAAA,IAC3F;AACA,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,EAAE;AAAA,EAC3D;AAEA,MAAI,CAAC,KAAK,YAAa,QAAO,EAAE,OAAO,eAAe;AACtD,QAAM,MAAM,KAAK,YAAY,MAAM,GAAG,KAAK,YAAY,YAAY,GAAG,CAAC;AACvE,SAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE;AACvE;","names":[]}
+{"version":3,"sources":["../src/linkSpace.ts"],"sourcesContent":["// Link path spaces (R3-273; REPO_CONTENT_DISPATCH_SPEC §9 decision, 2026-08-17).\n//\n// A document link's target resolves in one of two spaces:\n//\n// - DEFAULT — the enclosing corpus's virtual filesystem. RELATIVE targets resolve\n//   against the authoring file (identical in both spaces); ABSOLUTE targets\n//   (`/x/y.mdx`) resolve from the corpus root when an enclosing `LinkSpaceContext`\n//   declares one, else from the filesystem root. A non-corpus app declares nothing\n//   and keeps today's behavior bit-for-bit (its fs root IS its only root).\n//\n// - `$fs:` — the explicit filesystem space: `$fs:/content/x.mdx` resolves from the\n//   root of the filesystem the app reads, escaping corpus-relative addressing.\n//\n// `$fs:` changes ADDRESSING, never REACH: resolution is pure path arithmetic and\n// existence is checked against the same in-mount metadata the default space uses —\n// nothing is fetched, and a link can never name what the app cannot already read.\n// A malformed `$fs:` target (anything not mount-absolute — which also catches\n// scheme smuggling like `$fs:javascript:…`) is INVALID and must render as a broken\n// link, never an anchor.\n//\n// Corpus nesting: `LinkSpaceContext` providers nest, and the NEAREST one wins —\n// which is exactly the innermost-enclosing-corpus rule (bundle encapsulation): a\n// document rendered inside a nested corpus resolves against the nested corpus.\n\nimport { createContext } from 'react';\n\nexport const FS_PREFIX = '$fs:';\n\nexport interface LinkSpace {\n  /** Absolute filesystem path of the enclosing corpus's root (e.g. `/app/content`),\n   *  or `null` when the document is not corpus-hosted (default). */\n  corpusRoot: string | null;\n  /**\n   * True when the filesystem this document resolves against is **chroot'd to the\n   * bundle** — i.e. the port the app holds was scoped to the bundle's subtree, so\n   * the mount root and the bundle root are the same directory\n   * (`BUNDLE_LAYERS_SPEC §9`; the `T2`/`T4` wrapper, R3-319 / BL-2).\n   *\n   * Under that grant `$fs:` **collapses to the scoped root**: `$fs:/p` and `/p`\n   * name the same byte, because there is no longer any \"mount-absolute\" space\n   * outside the bundle for `$fs:` to reach into. Without this flag the resolver\n   * would hand back a mount-absolute path that the chroot then re-roots anyway —\n   * a link that renders as valid and resolves somewhere the author did not mean.\n   *\n   * **This is an invariant to CREATE, not one to inherit** (`BUNDLE_LAYERS_SPEC\n   * §11`): the shipped resolver reads `{currentFile, corpusRoot}` and nothing\n   * else, so `$fs:` is bundle-anchored only if something says so. It lives here,\n   * in the resolver, rather than as a rule each caller applies by passing\n   * `corpusRoot: '/'` — an invariant the arithmetic carries cannot be forgotten\n   * at one call site out of five.\n   */\n  bundleChrooted?: boolean;\n}\n\n/** Ambient link space. A corpus-rendering app wraps its document tree in\n *  `<LinkSpaceContext value={{ corpusRoot }}>`; nesting a second provider inside a\n *  rendered sub-corpus makes the innermost root win. */\nexport const LinkSpaceContext = createContext<LinkSpace>({\n  corpusRoot: null,\n  bundleChrooted: false,\n});\n\n/** Collapse `.`/`..`/empty segments into a clean absolute path. `..` can never\n *  climb above the root — a (virtual) root's parent is itself, which is what keeps\n *  both the mount space and the corpus space closed under traversal. */\nexport const normalizeAbsolute = (path: string): string => {\n  const out: string[] = [];\n  for (const seg of path.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') out.pop();\n    else out.push(seg);\n  }\n  return '/' + out.join('/');\n};\n\nexport type ResolvedLinkTarget =\n  /** Resolved to an absolute filesystem path (existence NOT checked here). */\n  | { state: 'resolved'; path: string }\n  /** A relative target with no known authoring file — the caller may route\n   *  optimistically (it cannot check existence or self-ness generically). */\n  | { state: 'unresolvable' }\n  /** A malformed `$fs:` target (not mount-absolute; includes scheme smuggling).\n   *  Callers MUST render this broken/inert — never as an anchor. */\n  | { state: 'invalid' };\n\n/** Anchor a corpus-absolute path at `corpusRoot`, clamping the corpus-relative\n *  half FIRST so the virtual corpus space stays closed under traversal. Shared by\n *  the `/p` branch and — under a bundle chroot — the `$fs:/p` branch, so the two\n *  spellings cannot drift into resolving differently. */\nfunction resolveCorpusAbsolute(path: string, corpusRoot: string | null): ResolvedLinkTarget {\n  const inner = normalizeAbsolute(path);\n  if (corpusRoot === null || corpusRoot === '/') return { state: 'resolved', path: inner };\n  return { state: 'resolved', path: normalizeAbsolute(corpusRoot + inner) };\n}\n\n/**\n * Resolve a raw link target (a wikilink target or an in-app href's path half —\n * fragment already split off) to an absolute filesystem path. THE shared resolver:\n * the default `WikiLink`, the markdown `a` override, and safe-content consumers\n * all route through this one function so the two render pipelines cannot drift.\n */\nexport function resolveLinkTarget(\n  raw: string,\n  opts: {\n    currentFile?: string;\n    corpusRoot?: string | null;\n    /** See `LinkSpace.bundleChrooted`. Under a bundle-chroot'd grant `$fs:`\n     *  resolves in the corpus space, because they are the same space. */\n    bundleChrooted?: boolean;\n  } = {},\n): ResolvedLinkTarget {\n  if (raw.startsWith(FS_PREFIX)) {\n    const rest = raw.slice(FS_PREFIX.length);\n    // Must be mount-absolute. This single rule also fails `$fs:javascript:…`,\n    // `$fs:https://…`, and every other smuggled scheme closed.\n    if (!rest.startsWith('/')) return { state: 'invalid' };\n    // Under a bundle chroot the mount root IS the bundle root, so `$fs:` has\n    // nowhere outside to name: it takes the corpus-absolute branch below and the\n    // two spellings collapse. `normalizeAbsolute` clamps `..` at the root either\n    // way, so neither spelling can climb out — the collapse changes WHERE a\n    // `$fs:` link points, never whether it can escape.\n    if (opts.bundleChrooted) return resolveCorpusAbsolute(rest, opts.corpusRoot ?? null);\n    return { state: 'resolved', path: normalizeAbsolute(rest) };\n  }\n  if (raw.startsWith('/')) {\n    const corpusRoot = opts.corpusRoot ?? null;\n    if (corpusRoot !== null) {\n      // Clamp the corpus-relative half FIRST (the virtual FS is closed — `/../x`\n      // stays inside the corpus), THEN anchor it at the corpus root.\n      return resolveCorpusAbsolute(raw, corpusRoot);\n    }\n    return { state: 'resolved', path: normalizeAbsolute(raw) };\n  }\n  // Relative: against the authoring file's directory — the same in both spaces.\n  if (!opts.currentFile) return { state: 'unresolvable' };\n  const dir = opts.currentFile.slice(0, opts.currentFile.lastIndexOf('/'));\n  return { state: 'resolved', path: normalizeAbsolute(`${dir}/${raw}`) };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwBA,mBAA8B;AAEvB,MAAM,YAAY;AA+BlB,MAAM,uBAAmB,4BAAyB;AAAA,EACvD,YAAY;AAAA,EACZ,gBAAgB;AAClB,CAAC;AAKM,MAAM,oBAAoB,CAAC,SAAyB;AACzD,QAAM,MAAgB,CAAC;AACvB,aAAW,OAAO,KAAK,MAAM,GAAG,GAAG;AACjC,QAAI,QAAQ,MAAM,QAAQ,IAAK;AAC/B,QAAI,QAAQ,KAAM,KAAI,IAAI;AAAA,QACrB,KAAI,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,MAAM,IAAI,KAAK,GAAG;AAC3B;AAgBA,SAAS,sBAAsB,MAAc,YAA+C;AAC1F,QAAM,QAAQ,kBAAkB,IAAI;AACpC,MAAI,eAAe,QAAQ,eAAe,IAAK,QAAO,EAAE,OAAO,YAAY,MAAM,MAAM;AACvF,SAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,aAAa,KAAK,EAAE;AAC1E;AAQO,SAAS,kBACd,KACA,OAMI,CAAC,GACe;AACpB,MAAI,IAAI,WAAW,SAAS,GAAG;AAC7B,UAAM,OAAO,IAAI,MAAM,UAAU,MAAM;AAGvC,QAAI,CAAC,KAAK,WAAW,GAAG,EAAG,QAAO,EAAE,OAAO,UAAU;AAMrD,QAAI,KAAK,eAAgB,QAAO,sBAAsB,MAAM,KAAK,cAAc,IAAI;AACnF,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,IAAI,EAAE;AAAA,EAC5D;AACA,MAAI,IAAI,WAAW,GAAG,GAAG;AACvB,UAAM,aAAa,KAAK,cAAc;AACtC,QAAI,eAAe,MAAM;AAGvB,aAAO,sBAAsB,KAAK,UAAU;AAAA,IAC9C;AACA,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,EAAE;AAAA,EAC3D;AAEA,MAAI,CAAC,KAAK,YAAa,QAAO,EAAE,OAAO,eAAe;AACtD,QAAM,MAAM,KAAK,YAAY,MAAM,GAAG,KAAK,YAAY,YAAY,GAAG,CAAC;AACvE,SAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE;AACvE;","names":[]}

package/dist/linkSpace.d.cts

@@ -5,6 +5,26 @@ interface LinkSpace {
     /** Absolute filesystem path of the enclosing corpus's root (e.g. `/app/content`),
      *  or `null` when the document is not corpus-hosted (default). */
     corpusRoot: string | null;
+    /**
+     * True when the filesystem this document resolves against is **chroot'd to the
+     * bundle** — i.e. the port the app holds was scoped to the bundle's subtree, so
+     * the mount root and the bundle root are the same directory
+     * (`BUNDLE_LAYERS_SPEC §9`; the `T2`/`T4` wrapper, R3-319 / BL-2).
+     *
+     * Under that grant `$fs:` **collapses to the scoped root**: `$fs:/p` and `/p`
+     * name the same byte, because there is no longer any "mount-absolute" space
+     * outside the bundle for `$fs:` to reach into. Without this flag the resolver
+     * would hand back a mount-absolute path that the chroot then re-roots anyway —
+     * a link that renders as valid and resolves somewhere the author did not mean.
+     *
+     * **This is an invariant to CREATE, not one to inherit** (`BUNDLE_LAYERS_SPEC
+     * §11`): the shipped resolver reads `{currentFile, corpusRoot}` and nothing
+     * else, so `$fs:` is bundle-anchored only if something says so. It lives here,
+     * in the resolver, rather than as a rule each caller applies by passing
+     * `corpusRoot: '/'` — an invariant the arithmetic carries cannot be forgotten
+     * at one call site out of five.
+     */
+    bundleChrooted?: boolean;
 }
 /** Ambient link space. A corpus-rendering app wraps its document tree in
  *  `<LinkSpaceContext value={{ corpusRoot }}>`; nesting a second provider inside a
@@ -39,6 +59,9 @@ type ResolvedLinkTarget =
 declare function resolveLinkTarget(raw: string, opts?: {
     currentFile?: string;
     corpusRoot?: string | null;
+    /** See `LinkSpace.bundleChrooted`. Under a bundle-chroot'd grant `$fs:`
+     *  resolves in the corpus space, because they are the same space. */
+    bundleChrooted?: boolean;
 }): ResolvedLinkTarget;
 
 export { FS_PREFIX, type LinkSpace, LinkSpaceContext, type ResolvedLinkTarget, normalizeAbsolute, resolveLinkTarget };