@immediately-run/sdk 0.35.0 → 0.37.0

package/dist/index.d.cts

@@ -12,10 +12,10 @@ export { EditorContext, getEditorContext, onEditorContextChange, useEditorContex
 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 { getRegion, useRegion } from './region.cjs';
-export { GrantRecord, Invite, Member, MountQuery, MountRemoveReason, MountRule, RemovedMount, ResolvedUser, Role, SandboxMount, SessionMount, SpaceError, SpaceInfo, acceptInvite, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.cjs';
+export { GrantRecord, Invite, Member, MountQuery, MountRemoveReason, MountRule, RemovedMount, ResolvedUser, Role, SandboxMount, SessionMount, SpaceError, SpaceInfo, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.cjs';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.cjs';
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.cjs';
-export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.cjs';
+export { RegionMessage, onRegionMessage, postToRegion, revealRegion, useRegionMessage } from './ipc.cjs';
 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';

package/dist/index.d.ts

@@ -12,10 +12,10 @@ export { EditorContext, getEditorContext, onEditorContextChange, useEditorContex
 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 { getRegion, useRegion } from './region.js';
-export { GrantRecord, Invite, Member, MountQuery, MountRemoveReason, MountRule, RemovedMount, ResolvedUser, Role, SandboxMount, SessionMount, SpaceError, SpaceInfo, acceptInvite, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.js';
+export { GrantRecord, Invite, Member, MountQuery, MountRemoveReason, MountRule, RemovedMount, ResolvedUser, Role, SandboxMount, SessionMount, SpaceError, SpaceInfo, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.js';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.js';
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.js';
-export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.js';
+export { RegionMessage, onRegionMessage, postToRegion, revealRegion, useRegionMessage } from './ipc.js';
 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';

package/dist/ipc.cjs

@@ -20,6 +20,7 @@ var ipc_exports = {};
 __export(ipc_exports, {
   onRegionMessage: () => onRegionMessage,
   postToRegion: () => postToRegion,
+  revealRegion: () => revealRegion,
   useRegionMessage: () => useRegionMessage
 });
 module.exports = __toCommonJS(ipc_exports);
@@ -33,6 +34,14 @@ const postToRegion = async (region, data) => {
     throw err;
   }
 };
+const revealRegion = async (region) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)("ipc", "reveal", [{ to: region }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "ipc reveal failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+};
 const onRegionMessage = (listener) => (0, import_sandboxUtils.addListener)(
   "region-message",
   (m) => listener({ from: m.from, data: m.data })
@@ -46,6 +55,7 @@ const useRegionMessage = () => {
 0 && (module.exports = {
   onRegionMessage,
   postToRegion,
+  revealRegion,
   useRegionMessage
 });
 //# sourceMappingURL=ipc.cjs.map

package/dist/ipc.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,mBAAoC;AACpC,0BAA6C;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,UAAM,qCAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,iBAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,QAAI,uBAA+B,IAAI;AACzD,8BAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to bring the user to `region` — the `reveal`-class method of\n * UI_AS_APPS_SPEC §4.1's focus model (R3-243). On mobile that is the column\n * transition (the panel's carousel advances to the main pane); on desktop a focus\n * move. Use it when a tap in your panel produces something to look at in another\n * column, right after the `postToRegion` that sends it there:\n *\n * ```ts\n * onClick={() => {                                   // a REAL user gesture\n *   void postToRegion('stage.conversation', { type: 'select-conversation', id });\n *   void revealRegion('stage.conversation');\n * }}\n * ```\n *\n * **Call it synchronously inside a user-gesture handler.** The host reads its own\n * transient user activation and refuses without one — an app flipping columns on a\n * timer is the attention-steal primitive §4.1 is written against. It reaches only\n * regions you already have a two-sided IPC edge to, and only within the active\n * activity, so it can neither jump the user into an unrelated surface nor pull\n * focus back to the caller's own column.\n *\n * Resolves once the host has *considered* the request — deliberately NOT reporting\n * whether focus actually moved. Whether the user is moved is the host's call\n * (activation, rate limit, already-there), and an app that could observe the\n * refusal would be tempted to retry, which is the behaviour the gate exists to\n * stop. Rejects only on a genuine authorization failure (`forbidden`): no `ipc`\n * capability, or no declared edge to `region`.\n */\nexport const revealRegion = async (region: string): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'reveal', [{ to: region }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc reveal failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,mBAAoC;AACpC,0BAA6C;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,UAAM,qCAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AA8BO,MAAM,eAAe,OAAO,WAAkC;AACnE,QAAM,MAAO,UAAM,qCAAgB,OAAO,UAAU,CAAC,EAAE,IAAI,OAAO,CAAC,CAAC;AAIpE,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,mBAAmB;AACzD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,iBAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,QAAI,uBAA+B,IAAI;AACzD,8BAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}

package/dist/ipc.d.cts

@@ -10,9 +10,38 @@ interface RegionMessage {
  * lacks the `ipc` capability.
  */
 declare const postToRegion: (region: string, data: unknown) => Promise<void>;
+/**
+ * Ask the host to bring the user to `region` — the `reveal`-class method of
+ * UI_AS_APPS_SPEC §4.1's focus model (R3-243). On mobile that is the column
+ * transition (the panel's carousel advances to the main pane); on desktop a focus
+ * move. Use it when a tap in your panel produces something to look at in another
+ * column, right after the `postToRegion` that sends it there:
+ *
+ * ```ts
+ * onClick={() => {                                   // a REAL user gesture
+ *   void postToRegion('stage.conversation', { type: 'select-conversation', id });
+ *   void revealRegion('stage.conversation');
+ * }}
+ * ```
+ *
+ * **Call it synchronously inside a user-gesture handler.** The host reads its own
+ * transient user activation and refuses without one — an app flipping columns on a
+ * timer is the attention-steal primitive §4.1 is written against. It reaches only
+ * regions you already have a two-sided IPC edge to, and only within the active
+ * activity, so it can neither jump the user into an unrelated surface nor pull
+ * focus back to the caller's own column.
+ *
+ * Resolves once the host has *considered* the request — deliberately NOT reporting
+ * whether focus actually moved. Whether the user is moved is the host's call
+ * (activation, rate limit, already-there), and an app that could observe the
+ * refusal would be tempted to retry, which is the behaviour the gate exists to
+ * stop. Rejects only on a genuine authorization failure (`forbidden`): no `ipc`
+ * capability, or no declared edge to `region`.
+ */
+declare const revealRegion: (region: string) => Promise<void>;
 /** Subscribe to inbound region messages. Returns an unsubscribe fn. */
 declare const onRegionMessage: (listener: (msg: RegionMessage) => void) => (() => void);
 /** React hook: the most recent inbound region message (or `null`). */
 declare const useRegionMessage: () => RegionMessage | null;
 
-export { type RegionMessage, onRegionMessage, postToRegion, useRegionMessage };
+export { type RegionMessage, onRegionMessage, postToRegion, revealRegion, useRegionMessage };

package/dist/ipc.d.ts

@@ -10,9 +10,38 @@ interface RegionMessage {
  * lacks the `ipc` capability.
  */
 declare const postToRegion: (region: string, data: unknown) => Promise<void>;
+/**
+ * Ask the host to bring the user to `region` — the `reveal`-class method of
+ * UI_AS_APPS_SPEC §4.1's focus model (R3-243). On mobile that is the column
+ * transition (the panel's carousel advances to the main pane); on desktop a focus
+ * move. Use it when a tap in your panel produces something to look at in another
+ * column, right after the `postToRegion` that sends it there:
+ *
+ * ```ts
+ * onClick={() => {                                   // a REAL user gesture
+ *   void postToRegion('stage.conversation', { type: 'select-conversation', id });
+ *   void revealRegion('stage.conversation');
+ * }}
+ * ```
+ *
+ * **Call it synchronously inside a user-gesture handler.** The host reads its own
+ * transient user activation and refuses without one — an app flipping columns on a
+ * timer is the attention-steal primitive §4.1 is written against. It reaches only
+ * regions you already have a two-sided IPC edge to, and only within the active
+ * activity, so it can neither jump the user into an unrelated surface nor pull
+ * focus back to the caller's own column.
+ *
+ * Resolves once the host has *considered* the request — deliberately NOT reporting
+ * whether focus actually moved. Whether the user is moved is the host's call
+ * (activation, rate limit, already-there), and an app that could observe the
+ * refusal would be tempted to retry, which is the behaviour the gate exists to
+ * stop. Rejects only on a genuine authorization failure (`forbidden`): no `ipc`
+ * capability, or no declared edge to `region`.
+ */
+declare const revealRegion: (region: string) => Promise<void>;
 /** Subscribe to inbound region messages. Returns an unsubscribe fn. */
 declare const onRegionMessage: (listener: (msg: RegionMessage) => void) => (() => void);
 /** React hook: the most recent inbound region message (or `null`). */
 declare const useRegionMessage: () => RegionMessage | null;
 
-export { type RegionMessage, onRegionMessage, postToRegion, useRegionMessage };
+export { type RegionMessage, onRegionMessage, postToRegion, revealRegion, useRegionMessage };

package/dist/ipc.js

@@ -9,6 +9,14 @@ const postToRegion = async (region, data) => {
     throw err;
   }
 };
+const revealRegion = async (region) => {
+  const res = await protocolRequest("ipc", "reveal", [{ to: region }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "ipc reveal failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+};
 const onRegionMessage = (listener) => addListener(
   "region-message",
   (m) => listener({ from: m.from, data: m.data })
@@ -21,6 +29,7 @@ const useRegionMessage = () => {
 export {
   onRegionMessage,
   postToRegion,
+  revealRegion,
   useRegionMessage
 };
 //# sourceMappingURL=ipc.js.map

package/dist/ipc.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":";AAIA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,mBAAmB;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,MAAM,gBAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,aAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,IAAI,SAA+B,IAAI;AACzD,YAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to bring the user to `region` — the `reveal`-class method of\n * UI_AS_APPS_SPEC §4.1's focus model (R3-243). On mobile that is the column\n * transition (the panel's carousel advances to the main pane); on desktop a focus\n * move. Use it when a tap in your panel produces something to look at in another\n * column, right after the `postToRegion` that sends it there:\n *\n * ```ts\n * onClick={() => {                                   // a REAL user gesture\n *   void postToRegion('stage.conversation', { type: 'select-conversation', id });\n *   void revealRegion('stage.conversation');\n * }}\n * ```\n *\n * **Call it synchronously inside a user-gesture handler.** The host reads its own\n * transient user activation and refuses without one — an app flipping columns on a\n * timer is the attention-steal primitive §4.1 is written against. It reaches only\n * regions you already have a two-sided IPC edge to, and only within the active\n * activity, so it can neither jump the user into an unrelated surface nor pull\n * focus back to the caller's own column.\n *\n * Resolves once the host has *considered* the request — deliberately NOT reporting\n * whether focus actually moved. Whether the user is moved is the host's call\n * (activation, rate limit, already-there), and an app that could observe the\n * refusal would be tempted to retry, which is the behaviour the gate exists to\n * stop. Rejects only on a genuine authorization failure (`forbidden`): no `ipc`\n * capability, or no declared edge to `region`.\n */\nexport const revealRegion = async (region: string): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'reveal', [{ to: region }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc reveal failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":";AAIA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,mBAAmB;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,MAAM,gBAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AA8BO,MAAM,eAAe,OAAO,WAAkC;AACnE,QAAM,MAAO,MAAM,gBAAgB,OAAO,UAAU,CAAC,EAAE,IAAI,OAAO,CAAC,CAAC;AAIpE,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,mBAAmB;AACzD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,aAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,IAAI,SAA+B,IAAI;AACzD,YAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}

package/dist/mounts.cjs

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var mounts_exports = {};
 __export(mounts_exports, {
   acceptInvite: () => acceptInvite,
+  awaitMatchingMount: () => awaitMatchingMount,
   createSpace: () => createSpace,
   declineInvite: () => declineInvite,
   findMount: () => findMount,
@@ -128,14 +129,35 @@ const onMountsChange = (listener) => {
   const disposable = mountService().onChange(listener);
   return () => disposable.dispose();
 };
-const waitForMount = (query) => new Promise((resolve) => {
-  const unsubscribe = onMountsChange((mounts) => {
+const waitForMount = (query, timeoutMs) => awaitMatchingMount(onMountsChange, query, timeoutMs);
+const awaitMatchingMount = (subscribe, query, timeoutMs) => new Promise((resolve, reject) => {
+  let unsubscribe;
+  let settled = false;
+  let timer;
+  const stop = () => {
+    settled = true;
+    if (timer !== void 0) clearTimeout(timer);
+    void Promise.resolve().then(() => unsubscribe?.());
+  };
+  unsubscribe = subscribe((mounts) => {
+    if (settled) return;
     const found = mounts.find((m) => matches(m, query));
     if (found) {
-      Promise.resolve().then(unsubscribe);
+      stop();
       resolve(found);
     }
   });
+  if (!settled && timeoutMs !== void 0) {
+    timer = setTimeout(() => {
+      if (settled) return;
+      stop();
+      const err = new Error(
+        `waitForMount timed out after ${timeoutMs}ms waiting for ${JSON.stringify(query)}`
+      );
+      err.code = "timeout";
+      reject(err);
+    }, timeoutMs);
+  }
 });
 const useMounts = () => {
   const [mounts, setMounts] = (0, import_react.useState)(getMounts);
@@ -188,8 +210,9 @@ const settingsRequest = async (method, query = {}) => {
 };
 const openSettings = async () => {
   const mount2 = await settingsRequest("open");
-  return waitForMount({ id: mount2.id ?? mount2.path });
+  return waitForMount({ id: mount2.id ?? mount2.path }, SETTINGS_MOUNT_TIMEOUT_MS);
 };
+const SETTINGS_MOUNT_TIMEOUT_MS = 15e3;
 const importSettingsFromParent = async () => {
   try {
     const data = await settingsRequest("importFromParent");
@@ -247,6 +270,7 @@ const revokeGrant = async (appKey, spaceId) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   acceptInvite,
+  awaitMatchingMount,
   createSpace,
   declineInvite,
   findMount,

package/dist/mounts.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { getHostRuntime } from './hostRuntime';\nimport { mountMatches } from './mountMatch';\n// Type-only: `tasks.ts` registers a host listener at module load, so we reuse the\n// FileCap SHAPE without pulling that side effect into every `mounts` importer.\nimport type { FileCap } from './tasks';\n\n/**\n * The absolute path where this app's own repository filesystem is mounted\n * (FILE_SHARING_SPEC §11.2). Prefer this over hardcoding `/app`: the repo is\n * dual-mounted at both `/app` (back-compat) and its canonical `/mnt/{hash}`\n * address, and this returns the canonical one the host reports. Falls back to\n * `/app` when the host hasn't reported a canonical path (older host / before the\n * report arrives) — both paths are live, so either resolves the same files.\n */\nexport const getAppMountPath = (): string => getHostRuntime()?.appMountPath ?? '/app';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openSettings} for this app's own settings,\n * or {@link mountSpace} / {@link requestMount} to mount a Firestore-backed \"space\".\n * Read or subscribe to the set, then access the files through the `fs` module at\n * the mount's `path`.\n */\nexport interface SandboxMount {\n  /** Absolute path where the mount is reachable (e.g. `/spaces/{id}`). */\n  path: string;\n  /** Backend kind, e.g. `'firestore'`. */\n  type: string;\n  /** Optional stable identifier (the spaceId, for spaces). */\n  id?: string;\n  /**\n   * Access mode of the granted view: `'rw'` (read-write) or `'ro'` (read-only).\n   * A live role downgrade re-announces the same mount with `mode: 'ro'`; apps\n   * observing `onMountsChange` see the change and writes start failing `EROFS`.\n   * Absent on the primary repo mount (treated as read-write).\n   */\n  mode?: \"ro\" | \"rw\";\n  /**\n   * Human-readable label for the mount — the space's display name, or the repo\n   * label for the primary working-tree mount (R3-69). Use this to show users and\n   * agents *what* a mount is: the `path` (`/mnt/{hash}`) and `id` (the spaceId)\n   * are opaque, and space names are not unique, so neither alone tells you which\n   * filesystem you're looking at. Absent when the host can't resolve a name\n   * (older host, or a name it never learned) — fall back to `id`/`path`.\n   */\n  name?: string;\n  /**\n   * The granted scopes of this mount (plan 12 §8.7 / §F): each `{subtree, mode}`\n   * is a path prefix you hold and at what access, at the mount's backend-natural\n   * paths. Use it to reason about per-path writability — which subtree is `rw` —\n   * WITHOUT probing `EROFS`. A single whole-mount grant is `[{ subtree: '/', mode }]`.\n   * Absent on the primary repo mount and on an older host that doesn't report it.\n   */\n  rules?: MountRule[];\n}\n\n/** One granted scope of a mount (plan 12 §F): a backend-natural path prefix and\n *  the access mode there. The most specific (longest) matching rule governs a path. */\nexport interface MountRule {\n  subtree: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Why a mounted filesystem was removed, surfaced on the removed descriptor so an\n * app can say *why* it vanished instead of failing mutely (auth-mount §\"mount-remove\"\n * / AM2-4):\n * - `revoked` — a durable grant was revoked (revokeGrant / consent withdrawal);\n * - `unshared` — the granting user's membership was removed (or downgraded out);\n * - `signed-out` — sign-out tore down every mount;\n * - `unmounted` — the app's own `unmountSpace` (or region teardown);\n * - `deleted` — the space was soft-deleted.\n * An older host that sends no reason is read as `'revoked'` (most conservative).\n */\nexport type MountRemoveReason =\n  | \"revoked\"\n  | \"unshared\"\n  | \"signed-out\"\n  | \"unmounted\"\n  | \"deleted\";\n\n/** A descriptor delivered as REMOVED to a mounts-change listener: the mount that\n *  went away, plus the `reason` it did. */\nexport interface RemovedMount extends SandboxMount {\n  reason: MountRemoveReason;\n}\n\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(\n    listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n  ): { dispose(): void };\n}\n\n// The stable key of a mount: its `id` (spaceId) when present, else its `path`.\n// Matches the sandbox `MountService.mountKey` so add/replace/remove agree on both\n// sides of the wire (a role downgrade re-announces the SAME key with `mode: 'ro'`).\nconst mountKey = (m: SandboxMount): string => m.id ?? m.path;\n\nconst MOUNT_REMOVE_REASONS: ReadonlySet<string> = new Set<MountRemoveReason>([\n  'revoked',\n  'unshared',\n  'signed-out',\n  'unmounted',\n  'deleted',\n]);\n\n// Normalize an over-the-wire `mount-remove` reason; an absent/unknown value (older\n// host) reads as `'revoked'`, the most conservative reading (mirrors the sandbox).\nconst asMountRemoveReason = (value: unknown): MountRemoveReason =>\n  typeof value === 'string' && MOUNT_REMOVE_REASONS.has(value)\n    ? (value as MountRemoveReason)\n    : 'revoked';\n\n// The injected sandbox-bundler mount service (`module.evaluation.module.bundler.mounts`),\n// or null when the SDK is npm-fetched with no injection — same dual-mode shape as\n// `sandboxUtils.transport()` and the metadata emitter (SDK_PACKAGING_SPEC §4/§8).\nconst injectedMountService = (): MountService | null => {\n  try {\n    // @ts-ignore - injected by the sandbox runtime\n    const svc = module?.evaluation?.module?.bundler?.mounts;\n    return svc && typeof svc.getMounts === 'function' ? svc : null;\n  } catch {\n    return null;\n  }\n};\n\n// Transport-backed descriptor cache (R3-51b): the npm-fetched fallback that builds\n// the same `getMounts()`/`onChange()` view the injected `bundler.mounts` provides,\n// directly from the host's `mount-add`/`mount-remove` messages over the §4 transport.\n// The host already posts these (it's how the in-iframe bundler service is populated);\n// the `MessagePort` a `mount-add` transfers is consumed by the sandbox runtime to wire\n// ZenFS and is irrelevant here — the SDK only mirrors the *descriptors*. A lazy\n// singleton so `getMounts`/`onMountsChange` share one cache, one subscription, and one\n// `request-mounts` replay (the host re-announces every current mount, like a poll).\nlet transportSvc: MountService | null = null;\n\nconst transportMountService = (): MountService => {\n  if (transportSvc) return transportSvc;\n  let mounts: SandboxMount[] = [];\n  const listeners = new Set<(m: SandboxMount[], r: RemovedMount[]) => void>();\n  const fire = (removed: RemovedMount[]) => {\n    for (const l of [...listeners]) l(mounts, removed);\n  };\n\n  addListener('mount-add', (msg: Record<string, any>) => {\n    const mount: SandboxMount | undefined = msg.mount;\n    if (!mount) return;\n    const key = mountKey(mount);\n    mounts = [...mounts.filter((m) => mountKey(m) !== key), mount];\n    fire([]);\n  });\n  addListener('mount-remove', (msg: Record<string, any>) => {\n    const key: string | undefined = msg.id ?? msg.path;\n    if (key == null) return;\n    const reason = asMountRemoveReason(msg.reason);\n    const removed = mounts.filter((m) => mountKey(m) === key).map((m) => ({ ...m, reason }));\n    if (removed.length === 0) return;\n    mounts = mounts.filter((m) => mountKey(m) !== key);\n    fire(removed);\n  });\n\n  // Ask the host to replay the current set (the matching `mount-add`s may have been\n  // sent before this SDK subscribed). Best-effort: a transport not yet ready throws.\n  try {\n    sendMessage('request-mounts');\n  } catch {\n    /* transport not ready — the live mount-add stream still populates the cache */\n  }\n\n  transportSvc = {\n    getMounts: () => mounts,\n    onChange: (listener) => {\n      listeners.add(listener);\n      listener(mounts, []); // immediate replay to the new subscriber\n      return { dispose: () => listeners.delete(listener) };\n    },\n  };\n  return transportSvc;\n};\n\n// Phase-5 dual mode: prefer the injected bundler service (the live path, behaviour\n// byte-for-byte unchanged); fall back to the transport-built cache when npm-fetched.\nconst mountService = (): MountService => injectedMountService() ?? transportMountService();\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. Any\n *  combination of coordinates; `name` matches the human-readable mount label. */\nexport type MountQuery = { type?: string; id?: string; path?: string; name?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  mountMatches(mount, query);\n\n/**\n * Returns the mounts currently available. Poll this whenever you need a one-off\n * read; use {@link onMountsChange} or {@link useMounts} to react to changes.\n * Each descriptor carries its `id` (the spaceId), `path` (`/mnt/{hash}`) and —\n * when the host can resolve it — a human-readable `name` (R3-69), so this doubles\n * as a queryable mount→space mapping for showing or locating a mount by name.\n */\nexport const getMounts = (): SandboxMount[] => mountService().getMounts();\n\n/** Returns the first mount matching `query`, or `undefined`. */\nexport const findMount = (query: MountQuery): SandboxMount | undefined =>\n  getMounts().find((m) => matches(m, query));\n\n/**\n * Subscribe to mount changes. The listener is invoked immediately with the\n * current mounts (and an empty `removed`), then again on every change. The second\n * argument carries the descriptors REMOVED by that change, each with its `reason`\n * (AM2-4) — so an app can react to *why* a mount vanished (e.g. tell the user a\n * shared space was `unshared` vs `deleted`). It is empty on adds and on the\n * initial replay. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (\n  listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n): (() => void) => {\n  const disposable = mountService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * Resolves once a mount matching `query` is present (immediately if it already\n * is). Handy for \"use it when it appears\" — e.g.\n * `await waitForMount({ type: 'firestore' })` before reading `/firestore`.\n */\nexport const waitForMount = (query: MountQuery): Promise<SandboxMount> =>\n  new Promise((resolve) => {\n    const unsubscribe = onMountsChange((mounts) => {\n      const found = mounts.find((m) => matches(m, query));\n      if (found) {\n        // Defer unsubscribe so we don't dispose during the initial replay call.\n        Promise.resolve().then(unsubscribe);\n        resolve(found);\n      }\n    });\n  });\n\n/** React hook returning the mounts currently available, re-rendering on change. */\nexport const useMounts = (): SandboxMount[] => {\n  const [mounts, setMounts] = useState<SandboxMount[]>(getMounts);\n  useEffect(() => onMountsChange(setMounts), []);\n  return mounts;\n};\n\n// ---------------------------------------------------------------------------\n// Session-scope mounts — the first-party \"App | Session\" lens (PRINCIPALS §9 B2).\n// ---------------------------------------------------------------------------\n\n/** A mount as seen through the first-party **Session** lens (PRINCIPALS_SPEC §9 B2):\n *  the session's mounts BEYOND this app's own (the editor/agent session's). This is\n *  a metadata view — no filesystem port — so it extends {@link SandboxMount} with only\n *  {@link forwardedToApp}. */\nexport interface SessionMount extends SandboxMount {\n  /** True iff this mount is ALSO in the app's own {@link useMounts} (the App lens);\n   *  `false` for a session-export-only mount visible only to the editor/agent + the\n   *  Session lens. */\n  forwardedToApp: boolean;\n}\n\n// The host pushes the session mount list ONLY to a FIRST-PARTY frame — the channel\n// is gated by the first-party-only `mounts:registry` capability (§8.9.1 / D-PRIN-4).\n// A URL-loaded/previewed app (or a fork of the File Explorer) never holds it, so the\n// push never arrives and `initial: []` stands — the Session lens is simply absent,\n// fail-closed. Mirrors the host's `session-mounts`/`request-session-mounts` wiring.\nconst sessionMountsChannel = createPushChannel<SessionMount[]>({\n  pushType: 'session-mounts',\n  requestType: 'request-session-mounts',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.mounts) ? (msg.mounts as SessionMount[]) : undefined),\n});\n\n/** The session's mounts (the \"Session\" lens superset), or `[]` when this frame is\n *  not first-party. One-off read; use {@link onSessionMountsChange}/{@link useSessionMounts}\n *  to react live. First-party only (`mounts:registry`) — a fork always sees `[]`. */\nexport const getSessionMounts = (): SessionMount[] => sessionMountsChannel.get();\n\n/** Subscribe to Session-lens mount changes. Invoked immediately with the current\n *  list (`[]` for a non-first-party frame), then on every change. Returns an\n *  unsubscribe. */\nexport const onSessionMountsChange = (\n  listener: (mounts: SessionMount[]) => void,\n): (() => void) => sessionMountsChannel.onChange(listener);\n\n/** React hook returning the live \"Session\" lens mount list, re-rendering on change.\n *  Empty for any non-first-party frame (the host withholds the channel), so a URL-\n *  loaded File Explorer fork renders no Session lens. */\nexport const useSessionMounts = (): SessionMount[] => sessionMountsChannel.use();\n\n// ---------------------------------------------------------------------------\n// Spaces — on-demand, shareable Firestore-backed filesystems.\n// The host owns all UX: if you aren't signed in, or the space doesn't exist or\n// isn't accessible, the parent window presents sign-in / create / request-access\n// and only then resolves these calls. See docs/specs/FILE_SHARING_SPEC.md.\n// ---------------------------------------------------------------------------\n\n/** Summary of a space, as returned by {@link listSpaces}. */\nexport interface SpaceInfo {\n  spaceId: string;\n  role?: 'owner' | 'writer' | 'reader';\n  owner?: string;\n  name?: string;\n}\n\n/** An error from a space operation, carrying a machine-readable `code`. */\nexport interface SpaceError extends Error {\n  code:\n    | 'auth-required'\n    | 'cancelled'\n    | 'forbidden'\n    | 'not-found'\n    | 'unsupported-scheme'\n    | 'unknown';\n}\n\ntype SpaceResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a spaces protocol request, unwrapping the host's {ok,data} envelope and\n// throwing a typed SpaceError on failure.\nconst request = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('spaces', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'space request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Request a space mount, then wait until the host actually registers it. The\n// host announces the mount (`mount-add`) separately from the protocol reply, so\n// an immediate read could otherwise race the mount.\nconst requestMountInternal = async (\n  method: string,\n  query: Record<string, unknown>,\n): Promise<SandboxMount> => {\n  const mount = await request<SandboxMount>(method, query);\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —\n * `scheme:locator`, e.g. `space:{spaceId}` or `github:owner/repo@ref`. Backend-blind:\n * the host resolves the scheme. A scheme with no resolver rejects with\n * {@link SpaceError} `unsupported-scheme`.\n */\nexport const mount = (mountId: string): Promise<SandboxMount> =>\n  requestMountInternal('mount', { mount: mountId });\n\n/** Mount a specific space by id (e.g. one shared with you, or from a link). A thin\n *  shim over {@link mount} with the `space:` scheme. */\nexport const mountSpace = (query: { spaceId: string }): Promise<SandboxMount> =>\n  mount(`space:${query.spaceId}`);\n\n/**\n * Ask the user to grant a filesystem to this app — the §8.6 powerbox. The app\n * asks; the HOST shows the user their spaces and, for the chosen one, its PROJECT\n * FOLDERS (§8.7). The user picks ONE project — so a shared space opens scoped to\n * just that project, never the whole space — and makes an EXPLICIT read-only vs\n * read-write decision (there is no default). The app never sees the list; it\n * resolves with the single granted mount, or rejects with a {@link SpaceError}\n * (`cancelled`) if declined. The granted scope is enforced host-side: the mount\n * is chroot'd to the project folder and `ro`-limited accordingly, so paths\n * outside the project are unnameable and writes on a `ro` grant fail `EROFS`.\n *\n * A project folder is the macOS-bundle-like unit an app works in inside a space;\n * the host records which app a folder belongs to (a `.immediately.run/` sidecar),\n * so the picker can surface the app's own projects or let the user create a new\n * one. Observe the granted access via {@link SandboxMount.mode}.\n *\n * Backend-general (§3.5): the picker offers whatever mounts the user has (today,\n * their spaces). Returns the granted mount by its universal id.\n */\nexport const requestMount = (): Promise<SandboxMount> =>\n  requestMountInternal('request', {});\n\n/** Prompt the user to grant a mount, returning the granted {@link SandboxMount}.\n *  @deprecated renamed to {@link requestMount} (backend-general, §3.5). */\nexport const requestSpace = requestMount;\n\n// ── content references (plan 12 §E / FILE_SHARING §7) ────────────────────────\n\n/**\n * Build a persisted CONTENT REFERENCE to a file in a mount — a `{mountId, relPath}`\n * pointer your app serializes into ITS OWN content (a board's JSON, an MDX file's\n * frontmatter, an album manifest — the platform doesn't dictate the container) so a\n * later viewer can resolve it. It is exactly the §5.7 {@link capFile} shape: ONE\n * capability, two delivery modes — runtime delegation (a task param, authorized by\n * the caller) vs a durable reference (authorized per-viewer by {@link resolveContentRef}).\n * `relPath` is BACKEND-NATURAL, so the reference resolves to the SAME path for every\n * viewer. Cross-app/cross-project references default to `ro`.\n *\n *   const ref = makeContentRef({ mountId: 'space:ACME', relPath: 'office-seating/desk.mdx' }, { mode: 'ro' });\n */\nexport const makeContentRef = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): FileCap => ({ $cap: 'file', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\n\n/**\n * Resolve a content reference your app found in content it ALREADY holds\n * (FILE_SHARING §7 / UI_AS_APPS §8.7; \"plan 12 §E\"). This is a RELAY, not a\n * fabrication: the host honors it ONLY when your app\n * already holds a grant to `ref.mountId` (else `forbidden`) — apps follow\n * writer-authored links inside granted content; they cannot name a space from\n * nothing (T27). The host runs a per-VIEWER consent prompt (named via the owning\n * app's project sidecar), and existence is never leaked — a decline and a\n * non-existent path are indistinguishable.\n *\n * On allow, the host APPENDS a read scope for the referenced path to your grant\n * (durable; same §8.15 lifecycle) and returns the STABLE absolute `path` the file\n * is mounted at — identical for every viewer, so a path the author stored resolves\n * the same for you. Read it through the `fs` module at that path. Rejects with a\n * {@link SpaceError}: `forbidden` (you don't hold the referenced mount) or\n * `cancelled` (the viewer declined / the path doesn't exist — no oracle).\n *\n *   const { path } = await resolveContentRef(ref);\n *   const text = await fs.promises.readFile(path, 'utf8');\n */\nexport const resolveContentRef = async (ref: FileCap): Promise<{ path: string }> => {\n  const path = await request<string>('resolveRef', { ref });\n  return { path };\n};\n\n/**\n * Resolve a BATCH of content references in ONE consent round (FILE_SHARING §7 /\n * UI_AS_APPS §8.7; \"plan 12 §E\"). When a\n * board opens with several embedded references, pass them all here: the host\n * coalesces them into a SINGLE consent prompt listing every target, instead of one\n * prompt per reference. Same relay gate and per-viewer semantics as\n * {@link resolveContentRef} (each ref's mount must already be held), applied to the\n * whole set — it is all-or-nothing: the user allows the batch or declines it.\n *\n * Resolves `{ paths }` with the STABLE absolute path of each ref, in input order.\n * Rejects with a {@link SpaceError}: `forbidden` (a referenced mount isn't held) or\n * `cancelled` (the viewer declined).\n *\n *   const { paths } = await resolveContentRefs(board.references);\n */\nexport const resolveContentRefs = async (refs: FileCap[]): Promise<{ paths: string[] }> => {\n  const paths = await request<string[]>('resolveRefs', { refs });\n  return { paths };\n};\n\n// ---------------------------------------------------------------------------\n// Settings — the per-user \"~/.config\"-style space (UI_AS_APPS_SPEC §3.3/§3.5/§8.2).\n// Each app gets its OWN settings subdir, auto-provisioned and chroot'd by the host\n// (no dialog, no powerbox). Read/write it through the returned mount's filesystem\n// port — there is deliberately no key/value get/set API; settings are just files.\n// ---------------------------------------------------------------------------\n\n// Issue a `protocol-settings` request, unwrapping {ok,data} and throwing a typed\n// SpaceError on failure (mirrors `request` for the spaces surface).\nconst settingsRequest = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('settings', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'settings request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Mount this app's per-user settings — a private `~/.config`-style filesystem,\n * auto-provisioned for the signed-in user and isolated to THIS app (the host\n * chroots it; a different app can never name it). Read/write config files through\n * the returned mount. Rejects with a {@link SpaceError} (`auth-required`) when\n * signed out. Capability: baseline `settings:app`.\n */\nexport const openSettings = async (): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('open');\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * One-time SEED of this app's settings from the parent it declares as `forkOf`\n * (its `package.json` `immediately.run.forkOf`) — so a fork inherits your\n * preferences from the original app (UI_AS_APPS_SPEC §3.4). The host asks the user\n * to confirm (a full consent when the apps have different owners, a light confirm\n * when the same owner publishes both) and copies the parent's settings into this\n * app's own subdir, skipping any file you already have. Non-throwing: resolves\n * `{ ok:false, code }` on decline (`cancelled`), no declared parent (`forbidden`),\n * or signed-out (`auth-required`). After `{ ok:true }`, read {@link openSettings}.\n * Capability: baseline `settings:fork`.\n */\nexport const importSettingsFromParent = async (): Promise<\n  { ok: true; copied: number } | { ok: false; code: string }\n> => {\n  try {\n    const data = await settingsRequest<{ copied: number }>('importFromParent');\n    return { ok: true, copied: data.copied };\n  } catch (e) {\n    return { ok: false, code: (e as SpaceError).code ?? 'unknown' };\n  }\n};\n\n/**\n * Mount ANOTHER app's per-user settings by its `appKey` — the elevated \"file\n * commander\" surface. Rejects `forbidden` unless this app holds the first-party-\n * only `settings:all` capability. Most apps want {@link openSettings} instead.\n */\nexport const openSettingsOf = async (appKey: string): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('openOf', { appKey });\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * List every app that has per-user settings — the elevated \"file commander\"\n * enumeration. Pair with {@link openSettingsOf} to mount any of them. Rejects\n * `forbidden` unless this app holds the first-party-only `settings:all`.\n */\nexport const listSettingsApps = (): Promise<string[]> =>\n  settingsRequest<string[]>('list');\n\n/** Create a brand-new, empty platform-hosted space. The app reaches it (or any\n *  other space) afterward through the {@link requestMount} powerbox or\n *  {@link mountSpace}; there is no implicit per-app binding. */\nexport const createSpace = (\n  opts: { name?: string } = {}\n): Promise<SandboxMount> => requestMountInternal('create', opts);\n\n/** List spaces you can access — all of them, or just those bound to this app. */\nexport const listSpaces = (opts: { app?: boolean } = {}): Promise<SpaceInfo[]> =>\n  request<SpaceInfo[]>('list', opts);\n\n/** Release a mounted space (stops its listener on the host). */\nexport const unmountSpace = async (query: { spaceId: string }): Promise<void> => {\n  await request('unmount', query);\n};\n\n// ---------------------------------------------------------------------------\n// Space management (the space-manager app) — UI_AS_APPS_SPEC §5.2. These are\n// ELEVATED: enumerating all the user's spaces is `spaces:user`; mutating\n// membership (share/unshare/setRole) and resolving handles is `spaces:admin`.\n// The host enforces the owner-lockout invariant (a space always keeps an owner,\n// T41) and rate-limits handle lookups (L1); the OAuth/identity token never\n// crosses to the app.\n// ---------------------------------------------------------------------------\n\n/** A collaborator's role on a shared space: full `owner`, read-write `writer`, or read-only `reader`. */\nexport type Role = 'owner' | 'writer' | 'reader';\n\n/** A member of a space (for the share/manage UI). */\nexport interface Member {\n  /**\n   * The **grantee** — `user:{uid}` | `group:{gid}`. This is the canonical name\n   * (core_concepts §4: \"principal\" is reserved for the authority context; a space\n   * member is a *grantee*). The host populates this on every member row.\n   */\n  grantee: string;\n  /**\n   * @deprecated Use {@link Member.grantee}. Kept as an alias (same value) for\n   * back-compat during the `principal`→`grantee` migration; will be removed in a\n   * future major. The host still populates both.\n   */\n  principal: string;\n  role: Role;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** A handle resolved to a principal (handle → who). */\nexport interface ResolvedUser {\n  uid: string;\n  login: string;\n  avatarUrl?: string;\n}\n\n/** A pending invitation to a space (pull-based sharing, FILE_SHARING_SPEC §6.4).\n *  It grants NO access until accepted — the recipient accepts it from their inbox\n *  ({@link listMyInvites} → {@link acceptInvite}), materializing membership. The\n *  display fields (`name`/`login`/`avatarUrl`) are untrusted for rendering. */\nexport interface Invite {\n  spaceId: string;\n  /** The invitee's uid — carried so the owner's pending list can\n   *  {@link revokeInvite}(spaceId, uid). */\n  uid: string;\n  role: Role;\n  owner: string;\n  name?: string;\n  invitedBy: string;\n  /** epoch ms (server-stamped); absent until the write settles. */\n  invitedAt?: number;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** Enumerate ALL the user's spaces (not just this app's) — `spaces:user`. */\nexport const listAllSpaces = (): Promise<SpaceInfo[]> => request<SpaceInfo[]>('listAll', {});\n\n/** Read a space's members one-shot — `spaces:admin`. */\nexport const getSpaceMembers = (spaceId: string): Promise<Member[]> =>\n  request<Member[]>('members', { spaceId });\n\n/** Invite a user (by provider handle) to a space at a role — `spaces:admin`. The\n *  host resolves the handle, so the app never sees other users' uids except the one\n *  it invited. Pull-based (FILE_SHARING_SPEC §6.4): this writes an INVITATION, not\n *  membership — the recipient must {@link acceptInvite}. Re-inviting an already-\n *  invited/member user is idempotent. */\nexport const inviteToSpace = async (spaceId: string, login: string, role: Role): Promise<void> => {\n  await request('invite', { spaceId, login, role });\n};\n\n/** The owner's outstanding invitations for a space — `spaces:admin`. */\nexport const listPendingInvites = (spaceId: string): Promise<Invite[]> =>\n  request<Invite[]>('pendingInvites', { spaceId });\n\n/** Withdraw a pending invitation (distinct from {@link unshareSpace}, which removes\n *  an ACCEPTED member) — `spaces:admin`. */\nexport const revokeInvite = async (spaceId: string, uid: string): Promise<void> => {\n  await request('revokeInvite', { spaceId, uid });\n};\n\n/** The caller's OWN invitation inbox — `spaces:user`. */\nexport const listMyInvites = (): Promise<Invite[]> => request<Invite[]>('listInvites', {});\n\n/** Accept an invitation: materialize your membership at the invited role and clear\n *  the invite — `spaces:user`. An invitation the caller doesn't hold rejects with\n *  `forbidden` (indistinguishable from a nonexistent space; no existence oracle). */\nexport const acceptInvite = async (spaceId: string): Promise<void> => {\n  await request('acceptInvite', { spaceId });\n};\n\n/** Decline (dismiss) an invitation from your inbox; writes no membership —\n *  `spaces:user`. */\nexport const declineInvite = async (spaceId: string): Promise<void> => {\n  await request('declineInvite', { spaceId });\n};\n\n// The live invitations inbox (FILE_SHARING §6.4/§9.8): the host pushes the caller's\n// current invitations on change and replays on register-frame; gated `spaces:user`.\n// So an invite that arrives (or an accepted/declined one leaving) reflects within one\n// snapshot — no poll. Mirrors the host's `invitations`/`request-invitations` wiring.\nconst invitesChannel = createPushChannel<Invite[]>({\n  pushType: 'invitations',\n  requestType: 'request-invitations',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.invites) ? (msg.invites as Invite[]) : undefined),\n});\n\n/** The caller's current invitations (`spaces:user`). One-off read; use\n *  {@link onInvitesChange}/{@link useInvites} to react live. */\nexport const getInvites = (): Invite[] => invitesChannel.get();\n\n/** Subscribe to invitation-inbox changes (arrived / accepted / declined). Invoked\n *  immediately with the current list, then on every change. Returns an unsubscribe. */\nexport const onInvitesChange = (listener: (invites: Invite[]) => void): (() => void) =>\n  invitesChannel.onChange(listener);\n\n/** React hook returning the caller's live invitation inbox, re-rendering on change\n *  (the space-manager Invitations inbox, §9.8). */\nexport const useInvites = (): Invite[] => invitesChannel.use();\n\n/** Remove a member from a space — `spaces:admin`. Refused if it would orphan the\n *  space (owner-lockout, T41). */\nexport const unshareSpace = async (spaceId: string, uid: string): Promise<void> => {\n  await request('unshare', { spaceId, uid });\n};\n\n/** Change a member's role — `spaces:admin`. Refused if it would drop the sole\n *  owner (owner-lockout, T41). */\nexport const setSpaceRole = async (spaceId: string, uid: string, role: Role): Promise<void> => {\n  await request('setRole', { spaceId, uid, role });\n};\n\n/** Resolve a provider handle to a principal (for the invite flow) — `spaces:admin`,\n *  rate-limited host-side. */\nexport const lookupUser = (login: string): Promise<ResolvedUser> =>\n  request<ResolvedUser>('lookupUser', { login });\n\n/** One durable grant an app holds, for the §8.11 capability audit view. */\nexport interface GrantRecord {\n  /** The app's provider-qualified identity (`provider__namespace__repository`). */\n  appKey: string;\n  spaceId: string;\n  /** Universal mount id (§3.5). */\n  mountId: string;\n  subtree?: string;\n  mode: 'ro' | 'rw';\n  name?: string;\n}\n\n/** Enumerate every (app, mount) grant the user holds — the audit view\n *  (§8.11). Elevated `spaces:admin`. */\nexport const listGrants = (): Promise<GrantRecord[]> => request<GrantRecord[]>('grants', {});\n\n/** Revoke one app's grant on a space — durable (the app can't re-mount) plus a\n *  best-effort live teardown. Elevated `spaces:admin`. */\nexport const revokeGrant = async (appKey: string, spaceId: string): Promise<void> => {\n  await request('revokeGrant', { appKey, spaceId });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AACpC,0BAA0D;AAC1D,yBAAkC;AAClC,yBAA+B;AAC/B,wBAA6B;AAatB,MAAM,kBAAkB,UAAc,mCAAe,GAAG,gBAAgB;AAoF/E,MAAM,WAAW,CAAC,MAA4B,EAAE,MAAM,EAAE;AAExD,MAAM,uBAA4C,oBAAI,IAAuB;AAAA,EAC3E;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAID,MAAM,sBAAsB,CAAC,UAC3B,OAAO,UAAU,YAAY,qBAAqB,IAAI,KAAK,IACtD,QACD;AAKN,MAAM,uBAAuB,MAA2B;AACtD,MAAI;AAEF,UAAM,MAAM,QAAQ,YAAY,QAAQ,SAAS;AACjD,WAAO,OAAO,OAAO,IAAI,cAAc,aAAa,MAAM;AAAA,EAC5D,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAUA,IAAI,eAAoC;AAExC,MAAM,wBAAwB,MAAoB;AAChD,MAAI,aAAc,QAAO;AACzB,MAAI,SAAyB,CAAC;AAC9B,QAAM,YAAY,oBAAI,IAAoD;AAC1E,QAAM,OAAO,CAAC,YAA4B;AACxC,eAAW,KAAK,CAAC,GAAG,SAAS,EAAG,GAAE,QAAQ,OAAO;AAAA,EACnD;AAEA,uCAAY,aAAa,CAAC,QAA6B;AACrD,UAAMA,SAAkC,IAAI;AAC5C,QAAI,CAACA,OAAO;AACZ,UAAM,MAAM,SAASA,MAAK;AAC1B,aAAS,CAAC,GAAG,OAAO,OAAO,CAAC,MAAM,SAAS,CAAC,MAAM,GAAG,GAAGA,MAAK;AAC7D,SAAK,CAAC,CAAC;AAAA,EACT,CAAC;AACD,uCAAY,gBAAgB,CAAC,QAA6B;AACxD,UAAM,MAA0B,IAAI,MAAM,IAAI;AAC9C,QAAI,OAAO,KAAM;AACjB,UAAM,SAAS,oBAAoB,IAAI,MAAM;AAC7C,UAAM,UAAU,OAAO,OAAO,CAAC,MAAM,SAAS,CAAC,MAAM,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,EAAE;AACvF,QAAI,QAAQ,WAAW,EAAG;AAC1B,aAAS,OAAO,OAAO,CAAC,MAAM,SAAS,CAAC,MAAM,GAAG;AACjD,SAAK,OAAO;AAAA,EACd,CAAC;AAID,MAAI;AACF,yCAAY,gBAAgB;AAAA,EAC9B,QAAQ;AAAA,EAER;AAEA,iBAAe;AAAA,IACb,WAAW,MAAM;AAAA,IACjB,UAAU,CAAC,aAAa;AACtB,gBAAU,IAAI,QAAQ;AACtB,eAAS,QAAQ,CAAC,CAAC;AACnB,aAAO,EAAE,SAAS,MAAM,UAAU,OAAO,QAAQ,EAAE;AAAA,IACrD;AAAA,EACF;AACA,SAAO;AACT;AAIA,MAAM,eAAe,MAAoB,qBAAqB,KAAK,sBAAsB;AAMzF,MAAM,UAAU,CAACA,QAAqB,cACpC,gCAAaA,QAAO,KAAK;AASpB,MAAM,YAAY,MAAsB,aAAa,EAAE,UAAU;AAGjE,MAAM,YAAY,CAAC,UACxB,UAAU,EAAE,KAAK,CAAC,MAAM,QAAQ,GAAG,KAAK,CAAC;AAUpC,MAAM,iBAAiB,CAC5B,aACiB;AACjB,QAAM,aAAa,aAAa,EAAE,SAAS,QAAQ;AACnD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,eAAe,CAAC,UAC3B,IAAI,QAAQ,CAAC,YAAY;AACvB,QAAM,cAAc,eAAe,CAAC,WAAW;AAC7C,UAAM,QAAQ,OAAO,KAAK,CAAC,MAAM,QAAQ,GAAG,KAAK,CAAC;AAClD,QAAI,OAAO;AAET,cAAQ,QAAQ,EAAE,KAAK,WAAW;AAClC,cAAQ,KAAK;AAAA,IACf;AAAA,EACF,CAAC;AACH,CAAC;AAGI,MAAM,YAAY,MAAsB;AAC7C,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAyB,SAAS;AAC9D,8BAAU,MAAM,eAAe,SAAS,GAAG,CAAC,CAAC;AAC7C,SAAO;AACT;AAsBA,MAAM,2BAAuB,sCAAkC;AAAA,EAC7D,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,MAAM,IAAK,IAAI,SAA4B;AAChF,CAAC;AAKM,MAAM,mBAAmB,MAAsB,qBAAqB,IAAI;AAKxE,MAAM,wBAAwB,CACnC,aACiB,qBAAqB,SAAS,QAAQ;AAKlD,MAAM,mBAAmB,MAAsB,qBAAqB,IAAI;AAkC/E,MAAM,UAAU,OACd,QACA,QAAiC,CAAC,MACnB;AACf,QAAM,MAAO,UAAM,qCAAgB,UAAU,QAAQ,CAAC,KAAK,CAAC;AAC5D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,sBAAsB;AAC5D,QAAI,OAAQ,KAAK,QAA+B;AAChD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAKA,MAAM,uBAAuB,OAC3B,QACA,UAC0B;AAC1B,QAAMA,SAAQ,MAAM,QAAsB,QAAQ,KAAK;AACvD,SAAO,aAAa,EAAE,IAAIA,OAAM,MAAMA,OAAM,KAAK,CAAC;AACpD;AAQO,MAAM,QAAQ,CAAC,YACpB,qBAAqB,SAAS,EAAE,OAAO,QAAQ,CAAC;AAI3C,MAAM,aAAa,CAAC,UACzB,MAAM,SAAS,MAAM,OAAO,EAAE;AAqBzB,MAAM,eAAe,MAC1B,qBAAqB,WAAW,CAAC,CAAC;AAI7B,MAAM,eAAe;AAgBrB,MAAM,iBAAiB,CAC5B,KACA,UACa,EAAE,MAAM,QAAQ,SAAS,IAAI,SAAS,SAAS,IAAI,SAAS,MAAM,KAAK,KAAK;AAsBpF,MAAM,oBAAoB,OAAO,QAA4C;AAClF,QAAM,OAAO,MAAM,QAAgB,cAAc,EAAE,IAAI,CAAC;AACxD,SAAO,EAAE,KAAK;AAChB;AAiBO,MAAM,qBAAqB,OAAO,SAAkD;AACzF,QAAM,QAAQ,MAAM,QAAkB,eAAe,EAAE,KAAK,CAAC;AAC7D,SAAO,EAAE,MAAM;AACjB;AAWA,MAAM,kBAAkB,OACtB,QACA,QAAiC,CAAC,MACnB;AACf,QAAM,MAAO,UAAM,qCAAgB,YAAY,QAAQ,CAAC,KAAK,CAAC;AAC9D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,yBAAyB;AAC/D,QAAI,OAAQ,KAAK,QAA+B;AAChD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AASO,MAAM,eAAe,YAAmC;AAC7D,QAAMA,SAAQ,MAAM,gBAA8B,MAAM;AACxD,SAAO,aAAa,EAAE,IAAIA,OAAM,MAAMA,OAAM,KAAK,CAAC;AACpD;AAaO,MAAM,2BAA2B,YAEnC;AACH,MAAI;AACF,UAAM,OAAO,MAAM,gBAAoC,kBAAkB;AACzE,WAAO,EAAE,IAAI,MAAM,QAAQ,KAAK,OAAO;AAAA,EACzC,SAAS,GAAG;AACV,WAAO,EAAE,IAAI,OAAO,MAAO,EAAiB,QAAQ,UAAU;AAAA,EAChE;AACF;AAOO,MAAM,iBAAiB,OAAO,WAA0C;AAC7E,QAAMA,SAAQ,MAAM,gBAA8B,UAAU,EAAE,OAAO,CAAC;AACtE,SAAO,aAAa,EAAE,IAAIA,OAAM,MAAMA,OAAM,KAAK,CAAC;AACpD;AAOO,MAAM,mBAAmB,MAC9B,gBAA0B,MAAM;AAK3B,MAAM,cAAc,CACzB,OAA0B,CAAC,MACD,qBAAqB,UAAU,IAAI;AAGxD,MAAM,aAAa,CAAC,OAA0B,CAAC,MACpD,QAAqB,QAAQ,IAAI;AAG5B,MAAM,eAAe,OAAO,UAA8C;AAC/E,QAAM,QAAQ,WAAW,KAAK;AAChC;AA4DO,MAAM,gBAAgB,MAA4B,QAAqB,WAAW,CAAC,CAAC;AAGpF,MAAM,kBAAkB,CAAC,YAC9B,QAAkB,WAAW,EAAE,QAAQ,CAAC;AAOnC,MAAM,gBAAgB,OAAO,SAAiB,OAAe,SAA8B;AAChG,QAAM,QAAQ,UAAU,EAAE,SAAS,OAAO,KAAK,CAAC;AAClD;AAGO,MAAM,qBAAqB,CAAC,YACjC,QAAkB,kBAAkB,EAAE,QAAQ,CAAC;AAI1C,MAAM,eAAe,OAAO,SAAiB,QAA+B;AACjF,QAAM,QAAQ,gBAAgB,EAAE,SAAS,IAAI,CAAC;AAChD;AAGO,MAAM,gBAAgB,MAAyB,QAAkB,eAAe,CAAC,CAAC;AAKlF,MAAM,eAAe,OAAO,YAAmC;AACpE,QAAM,QAAQ,gBAAgB,EAAE,QAAQ,CAAC;AAC3C;AAIO,MAAM,gBAAgB,OAAO,YAAmC;AACrE,QAAM,QAAQ,iBAAiB,EAAE,QAAQ,CAAC;AAC5C;AAMA,MAAM,qBAAiB,sCAA4B;AAAA,EACjD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAAuB;AAC5E,CAAC;AAIM,MAAM,aAAa,MAAgB,eAAe,IAAI;AAItD,MAAM,kBAAkB,CAAC,aAC9B,eAAe,SAAS,QAAQ;AAI3B,MAAM,aAAa,MAAgB,eAAe,IAAI;AAItD,MAAM,eAAe,OAAO,SAAiB,QAA+B;AACjF,QAAM,QAAQ,WAAW,EAAE,SAAS,IAAI,CAAC;AAC3C;AAIO,MAAM,eAAe,OAAO,SAAiB,KAAa,SAA8B;AAC7F,QAAM,QAAQ,WAAW,EAAE,SAAS,KAAK,KAAK,CAAC;AACjD;AAIO,MAAM,aAAa,CAAC,UACzB,QAAsB,cAAc,EAAE,MAAM,CAAC;AAgBxC,MAAM,aAAa,MAA8B,QAAuB,UAAU,CAAC,CAAC;AAIpF,MAAM,cAAc,OAAO,QAAgB,YAAmC;AACnF,QAAM,QAAQ,eAAe,EAAE,QAAQ,QAAQ,CAAC;AAClD;","names":["mount"]}
+{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { getHostRuntime } from './hostRuntime';\nimport { mountMatches } from './mountMatch';\n// Type-only: `tasks.ts` registers a host listener at module load, so we reuse the\n// FileCap SHAPE without pulling that side effect into every `mounts` importer.\nimport type { FileCap } from './tasks';\n\n/**\n * The absolute path where this app's own repository filesystem is mounted\n * (FILE_SHARING_SPEC §11.2). Prefer this over hardcoding `/app`: the repo is\n * dual-mounted at both `/app` (back-compat) and its canonical `/mnt/{hash}`\n * address, and this returns the canonical one the host reports. Falls back to\n * `/app` when the host hasn't reported a canonical path (older host / before the\n * report arrives) — both paths are live, so either resolves the same files.\n */\nexport const getAppMountPath = (): string => getHostRuntime()?.appMountPath ?? '/app';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openSettings} for this app's own settings,\n * or {@link mountSpace} / {@link requestMount} to mount a Firestore-backed \"space\".\n * Read or subscribe to the set, then access the files through the `fs` module at\n * the mount's `path`.\n */\nexport interface SandboxMount {\n  /** Absolute path where the mount is reachable (e.g. `/spaces/{id}`). */\n  path: string;\n  /** Backend kind, e.g. `'firestore'`. */\n  type: string;\n  /** Optional stable identifier (the spaceId, for spaces). */\n  id?: string;\n  /**\n   * Access mode of the granted view: `'rw'` (read-write) or `'ro'` (read-only).\n   * A live role downgrade re-announces the same mount with `mode: 'ro'`; apps\n   * observing `onMountsChange` see the change and writes start failing `EROFS`.\n   * Absent on the primary repo mount (treated as read-write).\n   */\n  mode?: \"ro\" | \"rw\";\n  /**\n   * Human-readable label for the mount — the space's display name, or the repo\n   * label for the primary working-tree mount (R3-69). Use this to show users and\n   * agents *what* a mount is: the `path` (`/mnt/{hash}`) and `id` (the spaceId)\n   * are opaque, and space names are not unique, so neither alone tells you which\n   * filesystem you're looking at. Absent when the host can't resolve a name\n   * (older host, or a name it never learned) — fall back to `id`/`path`.\n   */\n  name?: string;\n  /**\n   * The granted scopes of this mount (plan 12 §8.7 / §F): each `{subtree, mode}`\n   * is a path prefix you hold and at what access, at the mount's backend-natural\n   * paths. Use it to reason about per-path writability — which subtree is `rw` —\n   * WITHOUT probing `EROFS`. A single whole-mount grant is `[{ subtree: '/', mode }]`.\n   * Absent on the primary repo mount and on an older host that doesn't report it.\n   */\n  rules?: MountRule[];\n}\n\n/** One granted scope of a mount (plan 12 §F): a backend-natural path prefix and\n *  the access mode there. The most specific (longest) matching rule governs a path. */\nexport interface MountRule {\n  subtree: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Why a mounted filesystem was removed, surfaced on the removed descriptor so an\n * app can say *why* it vanished instead of failing mutely (auth-mount §\"mount-remove\"\n * / AM2-4):\n * - `revoked` — a durable grant was revoked (revokeGrant / consent withdrawal);\n * - `unshared` — the granting user's membership was removed (or downgraded out);\n * - `signed-out` — sign-out tore down every mount;\n * - `unmounted` — the app's own `unmountSpace` (or region teardown);\n * - `deleted` — the space was soft-deleted.\n * An older host that sends no reason is read as `'revoked'` (most conservative).\n */\nexport type MountRemoveReason =\n  | \"revoked\"\n  | \"unshared\"\n  | \"signed-out\"\n  | \"unmounted\"\n  | \"deleted\";\n\n/** A descriptor delivered as REMOVED to a mounts-change listener: the mount that\n *  went away, plus the `reason` it did. */\nexport interface RemovedMount extends SandboxMount {\n  reason: MountRemoveReason;\n}\n\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(\n    listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n  ): { dispose(): void };\n}\n\n// The stable key of a mount: its `id` (spaceId) when present, else its `path`.\n// Matches the sandbox `MountService.mountKey` so add/replace/remove agree on both\n// sides of the wire (a role downgrade re-announces the SAME key with `mode: 'ro'`).\nconst mountKey = (m: SandboxMount): string => m.id ?? m.path;\n\nconst MOUNT_REMOVE_REASONS: ReadonlySet<string> = new Set<MountRemoveReason>([\n  'revoked',\n  'unshared',\n  'signed-out',\n  'unmounted',\n  'deleted',\n]);\n\n// Normalize an over-the-wire `mount-remove` reason; an absent/unknown value (older\n// host) reads as `'revoked'`, the most conservative reading (mirrors the sandbox).\nconst asMountRemoveReason = (value: unknown): MountRemoveReason =>\n  typeof value === 'string' && MOUNT_REMOVE_REASONS.has(value)\n    ? (value as MountRemoveReason)\n    : 'revoked';\n\n// The injected sandbox-bundler mount service (`module.evaluation.module.bundler.mounts`),\n// or null when the SDK is npm-fetched with no injection — same dual-mode shape as\n// `sandboxUtils.transport()` and the metadata emitter (SDK_PACKAGING_SPEC §4/§8).\nconst injectedMountService = (): MountService | null => {\n  try {\n    // @ts-ignore - injected by the sandbox runtime\n    const svc = module?.evaluation?.module?.bundler?.mounts;\n    return svc && typeof svc.getMounts === 'function' ? svc : null;\n  } catch {\n    return null;\n  }\n};\n\n// Transport-backed descriptor cache (R3-51b): the npm-fetched fallback that builds\n// the same `getMounts()`/`onChange()` view the injected `bundler.mounts` provides,\n// directly from the host's `mount-add`/`mount-remove` messages over the §4 transport.\n// The host already posts these (it's how the in-iframe bundler service is populated);\n// the `MessagePort` a `mount-add` transfers is consumed by the sandbox runtime to wire\n// ZenFS and is irrelevant here — the SDK only mirrors the *descriptors*. A lazy\n// singleton so `getMounts`/`onMountsChange` share one cache, one subscription, and one\n// `request-mounts` replay (the host re-announces every current mount, like a poll).\nlet transportSvc: MountService | null = null;\n\nconst transportMountService = (): MountService => {\n  if (transportSvc) return transportSvc;\n  let mounts: SandboxMount[] = [];\n  const listeners = new Set<(m: SandboxMount[], r: RemovedMount[]) => void>();\n  const fire = (removed: RemovedMount[]) => {\n    for (const l of [...listeners]) l(mounts, removed);\n  };\n\n  addListener('mount-add', (msg: Record<string, any>) => {\n    const mount: SandboxMount | undefined = msg.mount;\n    if (!mount) return;\n    const key = mountKey(mount);\n    mounts = [...mounts.filter((m) => mountKey(m) !== key), mount];\n    fire([]);\n  });\n  addListener('mount-remove', (msg: Record<string, any>) => {\n    const key: string | undefined = msg.id ?? msg.path;\n    if (key == null) return;\n    const reason = asMountRemoveReason(msg.reason);\n    const removed = mounts.filter((m) => mountKey(m) === key).map((m) => ({ ...m, reason }));\n    if (removed.length === 0) return;\n    mounts = mounts.filter((m) => mountKey(m) !== key);\n    fire(removed);\n  });\n\n  // Ask the host to replay the current set (the matching `mount-add`s may have been\n  // sent before this SDK subscribed). Best-effort: a transport not yet ready throws.\n  try {\n    sendMessage('request-mounts');\n  } catch {\n    /* transport not ready — the live mount-add stream still populates the cache */\n  }\n\n  transportSvc = {\n    getMounts: () => mounts,\n    onChange: (listener) => {\n      listeners.add(listener);\n      listener(mounts, []); // immediate replay to the new subscriber\n      return { dispose: () => listeners.delete(listener) };\n    },\n  };\n  return transportSvc;\n};\n\n// Phase-5 dual mode: prefer the injected bundler service (the live path, behaviour\n// byte-for-byte unchanged); fall back to the transport-built cache when npm-fetched.\nconst mountService = (): MountService => injectedMountService() ?? transportMountService();\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. Any\n *  combination of coordinates; `name` matches the human-readable mount label. */\nexport type MountQuery = { type?: string; id?: string; path?: string; name?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  mountMatches(mount, query);\n\n/**\n * Returns the mounts currently available. Poll this whenever you need a one-off\n * read; use {@link onMountsChange} or {@link useMounts} to react to changes.\n * Each descriptor carries its `id` (the spaceId), `path` (`/mnt/{hash}`) and —\n * when the host can resolve it — a human-readable `name` (R3-69), so this doubles\n * as a queryable mount→space mapping for showing or locating a mount by name.\n */\nexport const getMounts = (): SandboxMount[] => mountService().getMounts();\n\n/** Returns the first mount matching `query`, or `undefined`. */\nexport const findMount = (query: MountQuery): SandboxMount | undefined =>\n  getMounts().find((m) => matches(m, query));\n\n/**\n * Subscribe to mount changes. The listener is invoked immediately with the\n * current mounts (and an empty `removed`), then again on every change. The second\n * argument carries the descriptors REMOVED by that change, each with its `reason`\n * (AM2-4) — so an app can react to *why* a mount vanished (e.g. tell the user a\n * shared space was `unshared` vs `deleted`). It is empty on adds and on the\n * initial replay. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (\n  listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n): (() => void) => {\n  const disposable = mountService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * Resolves once a mount matching `query` is present (immediately if it already\n * is). Handy for \"use it when it appears\" — e.g.\n * `await waitForMount({ type: 'firestore' })` before reading `/firestore`.\n *\n * `timeoutMs` (optional, additive) rejects with a `timeout`-coded error instead of\n * waiting forever. Omit it to keep the original unbounded behaviour — but prefer\n * setting it on any path whose caller would otherwise hang silently: a mount that\n * never arrives is indistinguishable from one that is merely slow, and an awaited\n * promise that never settles surfaces to the user as a feature that quietly does\n * nothing.\n *\n * **Hazard — `onMountsChange` calls its listener SYNCHRONOUSLY on subscribe** (the\n * documented initial replay). So when the mount is already present — the common\n * case, since callers typically `await` the host request that creates it first —\n * the callback below runs *during* the `onMountsChange(...)` call, before the\n * assignment to `unsubscribe` completes. `unsubscribe` is therefore declared with\n * `let` ABOVE the subscription and read only inside a deferred closure: writing\n * `const unsubscribe = onMountsChange(...)` and referencing it in the callback\n * throws `ReferenceError: Cannot access 'unsubscribe' before initialization` (a\n * temporal-dead-zone read) on exactly that path. That bug silently broke\n * `openSettings()` — and with it the agent's conversation memory.\n */\nexport const waitForMount = (\n  query: MountQuery,\n  timeoutMs?: number,\n): Promise<SandboxMount> => awaitMatchingMount(onMountsChange, query, timeoutMs);\n\n/** The framework-free core of {@link waitForMount}, with the subscription injected\n *  so a test can drive the synchronous-initial-replay case that broke it. */\nexport const awaitMatchingMount = (\n  subscribe: (listener: (mounts: SandboxMount[]) => void) => () => void,\n  query: MountQuery,\n  timeoutMs?: number,\n): Promise<SandboxMount> =>\n  new Promise((resolve, reject) => {\n    // `let`, declared BEFORE `subscribe(...)` — see the hazard note above. A\n    // `const` bound to the subscribe call is in its temporal dead zone while the\n    // synchronous initial replay runs, and any read of it from the listener\n    // throws.\n    let unsubscribe: (() => void) | undefined;\n    let settled = false;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    // Deferred so we never dispose the subscription from inside its own initial\n    // replay, and late enough that `unsubscribe` is always assigned.\n    const stop = (): void => {\n      settled = true;\n      if (timer !== undefined) clearTimeout(timer);\n      void Promise.resolve().then(() => unsubscribe?.());\n    };\n    unsubscribe = subscribe((mounts) => {\n      if (settled) return;\n      const found = mounts.find((m) => matches(m, query));\n      if (found) {\n        stop();\n        resolve(found);\n      }\n    });\n    // The initial replay may have settled us above, before `unsubscribe` existed;\n    // `stop()`'s deferred read picks it up, so nothing more is needed here.\n    if (!settled && timeoutMs !== undefined) {\n      timer = setTimeout(() => {\n        if (settled) return;\n        stop();\n        const err = new Error(\n          `waitForMount timed out after ${timeoutMs}ms waiting for ${JSON.stringify(query)}`,\n        ) as SpaceError;\n        err.code = 'timeout';\n        reject(err);\n      }, timeoutMs);\n    }\n  });\n\n/** React hook returning the mounts currently available, re-rendering on change. */\nexport const useMounts = (): SandboxMount[] => {\n  const [mounts, setMounts] = useState<SandboxMount[]>(getMounts);\n  useEffect(() => onMountsChange(setMounts), []);\n  return mounts;\n};\n\n// ---------------------------------------------------------------------------\n// Session-scope mounts — the first-party \"App | Session\" lens (PRINCIPALS §9 B2).\n// ---------------------------------------------------------------------------\n\n/** A mount as seen through the first-party **Session** lens (PRINCIPALS_SPEC §9 B2):\n *  the session's mounts BEYOND this app's own (the editor/agent session's). This is\n *  a metadata view — no filesystem port — so it extends {@link SandboxMount} with only\n *  {@link forwardedToApp}. */\nexport interface SessionMount extends SandboxMount {\n  /** True iff this mount is ALSO in the app's own {@link useMounts} (the App lens);\n   *  `false` for a session-export-only mount visible only to the editor/agent + the\n   *  Session lens. */\n  forwardedToApp: boolean;\n}\n\n// The host pushes the session mount list ONLY to a FIRST-PARTY frame — the channel\n// is gated by the first-party-only `mounts:registry` capability (§8.9.1 / D-PRIN-4).\n// A URL-loaded/previewed app (or a fork of the File Explorer) never holds it, so the\n// push never arrives and `initial: []` stands — the Session lens is simply absent,\n// fail-closed. Mirrors the host's `session-mounts`/`request-session-mounts` wiring.\nconst sessionMountsChannel = createPushChannel<SessionMount[]>({\n  pushType: 'session-mounts',\n  requestType: 'request-session-mounts',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.mounts) ? (msg.mounts as SessionMount[]) : undefined),\n});\n\n/** The session's mounts (the \"Session\" lens superset), or `[]` when this frame is\n *  not first-party. One-off read; use {@link onSessionMountsChange}/{@link useSessionMounts}\n *  to react live. First-party only (`mounts:registry`) — a fork always sees `[]`. */\nexport const getSessionMounts = (): SessionMount[] => sessionMountsChannel.get();\n\n/** Subscribe to Session-lens mount changes. Invoked immediately with the current\n *  list (`[]` for a non-first-party frame), then on every change. Returns an\n *  unsubscribe. */\nexport const onSessionMountsChange = (\n  listener: (mounts: SessionMount[]) => void,\n): (() => void) => sessionMountsChannel.onChange(listener);\n\n/** React hook returning the live \"Session\" lens mount list, re-rendering on change.\n *  Empty for any non-first-party frame (the host withholds the channel), so a URL-\n *  loaded File Explorer fork renders no Session lens. */\nexport const useSessionMounts = (): SessionMount[] => sessionMountsChannel.use();\n\n// ---------------------------------------------------------------------------\n// Spaces — on-demand, shareable Firestore-backed filesystems.\n// The host owns all UX: if you aren't signed in, or the space doesn't exist or\n// isn't accessible, the parent window presents sign-in / create / request-access\n// and only then resolves these calls. See docs/specs/FILE_SHARING_SPEC.md.\n// ---------------------------------------------------------------------------\n\n/** Summary of a space, as returned by {@link listSpaces}. */\nexport interface SpaceInfo {\n  spaceId: string;\n  role?: 'owner' | 'writer' | 'reader';\n  owner?: string;\n  name?: string;\n}\n\n/** An error from a space operation, carrying a machine-readable `code`. */\nexport interface SpaceError extends Error {\n  code:\n    | 'auth-required'\n    | 'cancelled'\n    | 'forbidden'\n    | 'not-found'\n    | 'unsupported-scheme'\n    // Client-side, never from the host: a bounded `waitForMount` gave up.\n    | 'timeout'\n    | 'unknown';\n}\n\ntype SpaceResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a spaces protocol request, unwrapping the host's {ok,data} envelope and\n// throwing a typed SpaceError on failure.\nconst request = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('spaces', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'space request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Request a space mount, then wait until the host actually registers it. The\n// host announces the mount (`mount-add`) separately from the protocol reply, so\n// an immediate read could otherwise race the mount.\nconst requestMountInternal = async (\n  method: string,\n  query: Record<string, unknown>,\n): Promise<SandboxMount> => {\n  const mount = await request<SandboxMount>(method, query);\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —\n * `scheme:locator`, e.g. `space:{spaceId}` or `github:owner/repo@ref`. Backend-blind:\n * the host resolves the scheme. A scheme with no resolver rejects with\n * {@link SpaceError} `unsupported-scheme`.\n */\nexport const mount = (mountId: string): Promise<SandboxMount> =>\n  requestMountInternal('mount', { mount: mountId });\n\n/** Mount a specific space by id (e.g. one shared with you, or from a link). A thin\n *  shim over {@link mount} with the `space:` scheme. */\nexport const mountSpace = (query: { spaceId: string }): Promise<SandboxMount> =>\n  mount(`space:${query.spaceId}`);\n\n/**\n * Ask the user to grant a filesystem to this app — the §8.6 powerbox. The app\n * asks; the HOST shows the user their spaces and, for the chosen one, its PROJECT\n * FOLDERS (§8.7). The user picks ONE project — so a shared space opens scoped to\n * just that project, never the whole space — and makes an EXPLICIT read-only vs\n * read-write decision (there is no default). The app never sees the list; it\n * resolves with the single granted mount, or rejects with a {@link SpaceError}\n * (`cancelled`) if declined. The granted scope is enforced host-side: the mount\n * is chroot'd to the project folder and `ro`-limited accordingly, so paths\n * outside the project are unnameable and writes on a `ro` grant fail `EROFS`.\n *\n * A project folder is the macOS-bundle-like unit an app works in inside a space;\n * the host records which app a folder belongs to (a `.immediately.run/` sidecar),\n * so the picker can surface the app's own projects or let the user create a new\n * one. Observe the granted access via {@link SandboxMount.mode}.\n *\n * Backend-general (§3.5): the picker offers whatever mounts the user has (today,\n * their spaces). Returns the granted mount by its universal id.\n */\nexport const requestMount = (): Promise<SandboxMount> =>\n  requestMountInternal('request', {});\n\n/** Prompt the user to grant a mount, returning the granted {@link SandboxMount}.\n *  @deprecated renamed to {@link requestMount} (backend-general, §3.5). */\nexport const requestSpace = requestMount;\n\n// ── content references (plan 12 §E / FILE_SHARING §7) ────────────────────────\n\n/**\n * Build a persisted CONTENT REFERENCE to a file in a mount — a `{mountId, relPath}`\n * pointer your app serializes into ITS OWN content (a board's JSON, an MDX file's\n * frontmatter, an album manifest — the platform doesn't dictate the container) so a\n * later viewer can resolve it. It is exactly the §5.7 {@link capFile} shape: ONE\n * capability, two delivery modes — runtime delegation (a task param, authorized by\n * the caller) vs a durable reference (authorized per-viewer by {@link resolveContentRef}).\n * `relPath` is BACKEND-NATURAL, so the reference resolves to the SAME path for every\n * viewer. Cross-app/cross-project references default to `ro`.\n *\n *   const ref = makeContentRef({ mountId: 'space:ACME', relPath: 'office-seating/desk.mdx' }, { mode: 'ro' });\n */\nexport const makeContentRef = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): FileCap => ({ $cap: 'file', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\n\n/**\n * Resolve a content reference your app found in content it ALREADY holds\n * (FILE_SHARING §7 / UI_AS_APPS §8.7; \"plan 12 §E\"). This is a RELAY, not a\n * fabrication: the host honors it ONLY when your app\n * already holds a grant to `ref.mountId` (else `forbidden`) — apps follow\n * writer-authored links inside granted content; they cannot name a space from\n * nothing (T27). The host runs a per-VIEWER consent prompt (named via the owning\n * app's project sidecar), and existence is never leaked — a decline and a\n * non-existent path are indistinguishable.\n *\n * On allow, the host APPENDS a read scope for the referenced path to your grant\n * (durable; same §8.15 lifecycle) and returns the STABLE absolute `path` the file\n * is mounted at — identical for every viewer, so a path the author stored resolves\n * the same for you. Read it through the `fs` module at that path. Rejects with a\n * {@link SpaceError}: `forbidden` (you don't hold the referenced mount) or\n * `cancelled` (the viewer declined / the path doesn't exist — no oracle).\n *\n *   const { path } = await resolveContentRef(ref);\n *   const text = await fs.promises.readFile(path, 'utf8');\n */\nexport const resolveContentRef = async (ref: FileCap): Promise<{ path: string }> => {\n  const path = await request<string>('resolveRef', { ref });\n  return { path };\n};\n\n/**\n * Resolve a BATCH of content references in ONE consent round (FILE_SHARING §7 /\n * UI_AS_APPS §8.7; \"plan 12 §E\"). When a\n * board opens with several embedded references, pass them all here: the host\n * coalesces them into a SINGLE consent prompt listing every target, instead of one\n * prompt per reference. Same relay gate and per-viewer semantics as\n * {@link resolveContentRef} (each ref's mount must already be held), applied to the\n * whole set — it is all-or-nothing: the user allows the batch or declines it.\n *\n * Resolves `{ paths }` with the STABLE absolute path of each ref, in input order.\n * Rejects with a {@link SpaceError}: `forbidden` (a referenced mount isn't held) or\n * `cancelled` (the viewer declined).\n *\n *   const { paths } = await resolveContentRefs(board.references);\n */\nexport const resolveContentRefs = async (refs: FileCap[]): Promise<{ paths: string[] }> => {\n  const paths = await request<string[]>('resolveRefs', { refs });\n  return { paths };\n};\n\n// ---------------------------------------------------------------------------\n// Settings — the per-user \"~/.config\"-style space (UI_AS_APPS_SPEC §3.3/§3.5/§8.2).\n// Each app gets its OWN settings subdir, auto-provisioned and chroot'd by the host\n// (no dialog, no powerbox). Read/write it through the returned mount's filesystem\n// port — there is deliberately no key/value get/set API; settings are just files.\n// ---------------------------------------------------------------------------\n\n// Issue a `protocol-settings` request, unwrapping {ok,data} and throwing a typed\n// SpaceError on failure (mirrors `request` for the spaces surface).\nconst settingsRequest = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('settings', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'settings request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Mount this app's per-user settings — a private `~/.config`-style filesystem,\n * auto-provisioned for the signed-in user and isolated to THIS app (the host\n * chroots it; a different app can never name it). Read/write config files through\n * the returned mount. Rejects with a {@link SpaceError} (`auth-required`) when\n * signed out. Capability: baseline `settings:app`.\n */\nexport const openSettings = async (): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('open');\n  // The host has already accepted the request and announced the mount, so this\n  // normally resolves on the initial replay. Bounded anyway: an unbounded wait\n  // here turns any delivery failure into a promise that never settles, and every\n  // caller of `openSettings()` is doing it to reach durable state — so the app\n  // just quietly loses that state with nothing to report.\n  return waitForMount({ id: mount.id ?? mount.path }, SETTINGS_MOUNT_TIMEOUT_MS);\n};\n\n/** How long `openSettings()` waits for the host to deliver the mount it just\n *  agreed to create. Generous — this is a hang-breaker, not a latency budget. */\nconst SETTINGS_MOUNT_TIMEOUT_MS = 15_000;\n\n/**\n * One-time SEED of this app's settings from the parent it declares as `forkOf`\n * (its `package.json` `immediately.run.forkOf`) — so a fork inherits your\n * preferences from the original app (UI_AS_APPS_SPEC §3.4). The host asks the user\n * to confirm (a full consent when the apps have different owners, a light confirm\n * when the same owner publishes both) and copies the parent's settings into this\n * app's own subdir, skipping any file you already have. Non-throwing: resolves\n * `{ ok:false, code }` on decline (`cancelled`), no declared parent (`forbidden`),\n * or signed-out (`auth-required`). After `{ ok:true }`, read {@link openSettings}.\n * Capability: baseline `settings:fork`.\n */\nexport const importSettingsFromParent = async (): Promise<\n  { ok: true; copied: number } | { ok: false; code: string }\n> => {\n  try {\n    const data = await settingsRequest<{ copied: number }>('importFromParent');\n    return { ok: true, copied: data.copied };\n  } catch (e) {\n    return { ok: false, code: (e as SpaceError).code ?? 'unknown' };\n  }\n};\n\n/**\n * Mount ANOTHER app's per-user settings by its `appKey` — the elevated \"file\n * commander\" surface. Rejects `forbidden` unless this app holds the first-party-\n * only `settings:all` capability. Most apps want {@link openSettings} instead.\n */\nexport const openSettingsOf = async (appKey: string): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('openOf', { appKey });\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * List every app that has per-user settings — the elevated \"file commander\"\n * enumeration. Pair with {@link openSettingsOf} to mount any of them. Rejects\n * `forbidden` unless this app holds the first-party-only `settings:all`.\n */\nexport const listSettingsApps = (): Promise<string[]> =>\n  settingsRequest<string[]>('list');\n\n/** Create a brand-new, empty platform-hosted space. The app reaches it (or any\n *  other space) afterward through the {@link requestMount} powerbox or\n *  {@link mountSpace}; there is no implicit per-app binding. */\nexport const createSpace = (\n  opts: { name?: string } = {}\n): Promise<SandboxMount> => requestMountInternal('create', opts);\n\n/** List spaces you can access — all of them, or just those bound to this app. */\nexport const listSpaces = (opts: { app?: boolean } = {}): Promise<SpaceInfo[]> =>\n  request<SpaceInfo[]>('list', opts);\n\n/** Release a mounted space (stops its listener on the host). */\nexport const unmountSpace = async (query: { spaceId: string }): Promise<void> => {\n  await request('unmount', query);\n};\n\n// ---------------------------------------------------------------------------\n// Space management (the space-manager app) — UI_AS_APPS_SPEC §5.2. These are\n// ELEVATED: enumerating all the user's spaces is `spaces:user`; mutating\n// membership (share/unshare/setRole) and resolving handles is `spaces:admin`.\n// The host enforces the owner-lockout invariant (a space always keeps an owner,\n// T41) and rate-limits handle lookups (L1); the OAuth/identity token never\n// crosses to the app.\n// ---------------------------------------------------------------------------\n\n/** A collaborator's role on a shared space: full `owner`, read-write `writer`, or read-only `reader`. */\nexport type Role = 'owner' | 'writer' | 'reader';\n\n/** A member of a space (for the share/manage UI). */\nexport interface Member {\n  /**\n   * The **grantee** — `user:{uid}` | `group:{gid}`. This is the canonical name\n   * (core_concepts §4: \"principal\" is reserved for the authority context; a space\n   * member is a *grantee*). The host populates this on every member row.\n   */\n  grantee: string;\n  /**\n   * @deprecated Use {@link Member.grantee}. Kept as an alias (same value) for\n   * back-compat during the `principal`→`grantee` migration; will be removed in a\n   * future major. The host still populates both.\n   */\n  principal: string;\n  role: Role;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** A handle resolved to a principal (handle → who). */\nexport interface ResolvedUser {\n  uid: string;\n  login: string;\n  avatarUrl?: string;\n}\n\n/** A pending invitation to a space (pull-based sharing, FILE_SHARING_SPEC §6.4).\n *  It grants NO access until accepted — the recipient accepts it from their inbox\n *  ({@link listMyInvites} → {@link acceptInvite}), materializing membership. The\n *  display fields (`name`/`login`/`avatarUrl`) are untrusted for rendering. */\nexport interface Invite {\n  spaceId: string;\n  /** The invitee's uid — carried so the owner's pending list can\n   *  {@link revokeInvite}(spaceId, uid). */\n  uid: string;\n  role: Role;\n  owner: string;\n  name?: string;\n  invitedBy: string;\n  /** epoch ms (server-stamped); absent until the write settles. */\n  invitedAt?: number;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** Enumerate ALL the user's spaces (not just this app's) — `spaces:user`. */\nexport const listAllSpaces = (): Promise<SpaceInfo[]> => request<SpaceInfo[]>('listAll', {});\n\n/** Read a space's members one-shot — `spaces:admin`. */\nexport const getSpaceMembers = (spaceId: string): Promise<Member[]> =>\n  request<Member[]>('members', { spaceId });\n\n/** Invite a user (by provider handle) to a space at a role — `spaces:admin`. The\n *  host resolves the handle, so the app never sees other users' uids except the one\n *  it invited. Pull-based (FILE_SHARING_SPEC §6.4): this writes an INVITATION, not\n *  membership — the recipient must {@link acceptInvite}. Re-inviting an already-\n *  invited/member user is idempotent. */\nexport const inviteToSpace = async (spaceId: string, login: string, role: Role): Promise<void> => {\n  await request('invite', { spaceId, login, role });\n};\n\n/** The owner's outstanding invitations for a space — `spaces:admin`. */\nexport const listPendingInvites = (spaceId: string): Promise<Invite[]> =>\n  request<Invite[]>('pendingInvites', { spaceId });\n\n/** Withdraw a pending invitation (distinct from {@link unshareSpace}, which removes\n *  an ACCEPTED member) — `spaces:admin`. */\nexport const revokeInvite = async (spaceId: string, uid: string): Promise<void> => {\n  await request('revokeInvite', { spaceId, uid });\n};\n\n/** The caller's OWN invitation inbox — `spaces:user`. */\nexport const listMyInvites = (): Promise<Invite[]> => request<Invite[]>('listInvites', {});\n\n/** Accept an invitation: materialize your membership at the invited role and clear\n *  the invite — `spaces:user`. An invitation the caller doesn't hold rejects with\n *  `forbidden` (indistinguishable from a nonexistent space; no existence oracle). */\nexport const acceptInvite = async (spaceId: string): Promise<void> => {\n  await request('acceptInvite', { spaceId });\n};\n\n/** Decline (dismiss) an invitation from your inbox; writes no membership —\n *  `spaces:user`. */\nexport const declineInvite = async (spaceId: string): Promise<void> => {\n  await request('declineInvite', { spaceId });\n};\n\n// The live invitations inbox (FILE_SHARING §6.4/§9.8): the host pushes the caller's\n// current invitations on change and replays on register-frame; gated `spaces:user`.\n// So an invite that arrives (or an accepted/declined one leaving) reflects within one\n// snapshot — no poll. Mirrors the host's `invitations`/`request-invitations` wiring.\nconst invitesChannel = createPushChannel<Invite[]>({\n  pushType: 'invitations',\n  requestType: 'request-invitations',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.invites) ? (msg.invites as Invite[]) : undefined),\n});\n\n/** The caller's current invitations (`spaces:user`). One-off read; use\n *  {@link onInvitesChange}/{@link useInvites} to react live. */\nexport const getInvites = (): Invite[] => invitesChannel.get();\n\n/** Subscribe to invitation-inbox changes (arrived / accepted / declined). Invoked\n *  immediately with the current list, then on every change. Returns an unsubscribe. */\nexport const onInvitesChange = (listener: (invites: Invite[]) => void): (() => void) =>\n  invitesChannel.onChange(listener);\n\n/** React hook returning the caller's live invitation inbox, re-rendering on change\n *  (the space-manager Invitations inbox, §9.8). */\nexport const useInvites = (): Invite[] => invitesChannel.use();\n\n/** Remove a member from a space — `spaces:admin`. Refused if it would orphan the\n *  space (owner-lockout, T41). */\nexport const unshareSpace = async (spaceId: string, uid: string): Promise<void> => {\n  await request('unshare', { spaceId, uid });\n};\n\n/** Change a member's role — `spaces:admin`. Refused if it would drop the sole\n *  owner (owner-lockout, T41). */\nexport const setSpaceRole = async (spaceId: string, uid: string, role: Role): Promise<void> => {\n  await request('setRole', { spaceId, uid, role });\n};\n\n/** Resolve a provider handle to a principal (for the invite flow) — `spaces:admin`,\n *  rate-limited host-side. */\nexport const lookupUser = (login: string): Promise<ResolvedUser> =>\n  request<ResolvedUser>('lookupUser', { login });\n\n/** One durable grant an app holds, for the §8.11 capability audit view. */\nexport interface GrantRecord {\n  /** The app's provider-qualified **program** identity (AA-01 `appKey`). The DEFAULT\n   *  program keys to the bare `provider__namespace__repository`; a NAMED mini-app\n   *  appends a fourth `enc()`-escaped component (`provider__namespace__repository__name`)\n   *  so its grants isolate from the repo's other programs. Host-supplied — the app\n   *  never builds this key. */\n  appKey: string;\n  spaceId: string;\n  /** Universal mount id (§3.5). */\n  mountId: string;\n  subtree?: string;\n  mode: 'ro' | 'rw';\n  name?: string;\n}\n\n/** Enumerate every (app, mount) grant the user holds — the audit view\n *  (§8.11). Elevated `spaces:admin`. */\nexport const listGrants = (): Promise<GrantRecord[]> => request<GrantRecord[]>('grants', {});\n\n/** Revoke one app's grant on a space — durable (the app can't re-mount) plus a\n *  best-effort live teardown. Elevated `spaces:admin`. */\nexport const revokeGrant = async (appKey: string, spaceId: string): Promise<void> => {\n  await request('revokeGrant', { appKey, spaceId });\n};\n"],"mappings":"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","names":["mount"]}

package/dist/mounts.d.cts

@@ -103,8 +103,29 @@ declare const onMountsChange: (listener: (mounts: SandboxMount[], removed: Remov
  * Resolves once a mount matching `query` is present (immediately if it already
  * is). Handy for "use it when it appears" — e.g.
  * `await waitForMount({ type: 'firestore' })` before reading `/firestore`.
+ *
+ * `timeoutMs` (optional, additive) rejects with a `timeout`-coded error instead of
+ * waiting forever. Omit it to keep the original unbounded behaviour — but prefer
+ * setting it on any path whose caller would otherwise hang silently: a mount that
+ * never arrives is indistinguishable from one that is merely slow, and an awaited
+ * promise that never settles surfaces to the user as a feature that quietly does
+ * nothing.
+ *
+ * **Hazard — `onMountsChange` calls its listener SYNCHRONOUSLY on subscribe** (the
+ * documented initial replay). So when the mount is already present — the common
+ * case, since callers typically `await` the host request that creates it first —
+ * the callback below runs *during* the `onMountsChange(...)` call, before the
+ * assignment to `unsubscribe` completes. `unsubscribe` is therefore declared with
+ * `let` ABOVE the subscription and read only inside a deferred closure: writing
+ * `const unsubscribe = onMountsChange(...)` and referencing it in the callback
+ * throws `ReferenceError: Cannot access 'unsubscribe' before initialization` (a
+ * temporal-dead-zone read) on exactly that path. That bug silently broke
+ * `openSettings()` — and with it the agent's conversation memory.
  */
-declare const waitForMount: (query: MountQuery) => Promise<SandboxMount>;
+declare const waitForMount: (query: MountQuery, timeoutMs?: number) => Promise<SandboxMount>;
+/** The framework-free core of {@link waitForMount}, with the subscription injected
+ *  so a test can drive the synchronous-initial-replay case that broke it. */
+declare const awaitMatchingMount: (subscribe: (listener: (mounts: SandboxMount[]) => void) => () => void, query: MountQuery, timeoutMs?: number) => Promise<SandboxMount>;
 /** React hook returning the mounts currently available, re-rendering on change. */
 declare const useMounts: () => SandboxMount[];
 /** A mount as seen through the first-party **Session** lens (PRINCIPALS_SPEC §9 B2):
@@ -138,7 +159,7 @@ interface SpaceInfo {
 }
 /** An error from a space operation, carrying a machine-readable `code`. */
 interface SpaceError extends Error {
-    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unsupported-scheme' | 'unknown';
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unsupported-scheme' | 'timeout' | 'unknown';
 }
 /**
  * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —
@@ -374,7 +395,11 @@ declare const setSpaceRole: (spaceId: string, uid: string, role: Role) => Promis
 declare const lookupUser: (login: string) => Promise<ResolvedUser>;
 /** One durable grant an app holds, for the §8.11 capability audit view. */
 interface GrantRecord {
-    /** The app's provider-qualified identity (`provider__namespace__repository`). */
+    /** The app's provider-qualified **program** identity (AA-01 `appKey`). The DEFAULT
+     *  program keys to the bare `provider__namespace__repository`; a NAMED mini-app
+     *  appends a fourth `enc()`-escaped component (`provider__namespace__repository__name`)
+     *  so its grants isolate from the repo's other programs. Host-supplied — the app
+     *  never builds this key. */
     appKey: string;
     spaceId: string;
     /** Universal mount id (§3.5). */
@@ -390,4 +415,4 @@ declare const listGrants: () => Promise<GrantRecord[]>;
  *  best-effort live teardown. Elevated `spaces:admin`. */
 declare const revokeGrant: (appKey: string, spaceId: string) => Promise<void>;
 
-export { type GrantRecord, type Invite, type Member, type MountQuery, type MountRemoveReason, type MountRule, type RemovedMount, type ResolvedUser, type Role, type SandboxMount, type SessionMount, type SpaceError, type SpaceInfo, acceptInvite, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount };
+export { type GrantRecord, type Invite, type Member, type MountQuery, type MountRemoveReason, type MountRule, type RemovedMount, type ResolvedUser, type Role, type SandboxMount, type SessionMount, type SpaceError, type SpaceInfo, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount };

package/dist/mounts.d.ts

@@ -103,8 +103,29 @@ declare const onMountsChange: (listener: (mounts: SandboxMount[], removed: Remov
  * Resolves once a mount matching `query` is present (immediately if it already
  * is). Handy for "use it when it appears" — e.g.
  * `await waitForMount({ type: 'firestore' })` before reading `/firestore`.
+ *
+ * `timeoutMs` (optional, additive) rejects with a `timeout`-coded error instead of
+ * waiting forever. Omit it to keep the original unbounded behaviour — but prefer
+ * setting it on any path whose caller would otherwise hang silently: a mount that
+ * never arrives is indistinguishable from one that is merely slow, and an awaited
+ * promise that never settles surfaces to the user as a feature that quietly does
+ * nothing.
+ *
+ * **Hazard — `onMountsChange` calls its listener SYNCHRONOUSLY on subscribe** (the
+ * documented initial replay). So when the mount is already present — the common
+ * case, since callers typically `await` the host request that creates it first —
+ * the callback below runs *during* the `onMountsChange(...)` call, before the
+ * assignment to `unsubscribe` completes. `unsubscribe` is therefore declared with
+ * `let` ABOVE the subscription and read only inside a deferred closure: writing
+ * `const unsubscribe = onMountsChange(...)` and referencing it in the callback
+ * throws `ReferenceError: Cannot access 'unsubscribe' before initialization` (a
+ * temporal-dead-zone read) on exactly that path. That bug silently broke
+ * `openSettings()` — and with it the agent's conversation memory.
  */
-declare const waitForMount: (query: MountQuery) => Promise<SandboxMount>;
+declare const waitForMount: (query: MountQuery, timeoutMs?: number) => Promise<SandboxMount>;
+/** The framework-free core of {@link waitForMount}, with the subscription injected
+ *  so a test can drive the synchronous-initial-replay case that broke it. */
+declare const awaitMatchingMount: (subscribe: (listener: (mounts: SandboxMount[]) => void) => () => void, query: MountQuery, timeoutMs?: number) => Promise<SandboxMount>;
 /** React hook returning the mounts currently available, re-rendering on change. */
 declare const useMounts: () => SandboxMount[];
 /** A mount as seen through the first-party **Session** lens (PRINCIPALS_SPEC §9 B2):
@@ -138,7 +159,7 @@ interface SpaceInfo {
 }
 /** An error from a space operation, carrying a machine-readable `code`. */
 interface SpaceError extends Error {
-    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unsupported-scheme' | 'unknown';
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unsupported-scheme' | 'timeout' | 'unknown';
 }
 /**
  * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —
@@ -374,7 +395,11 @@ declare const setSpaceRole: (spaceId: string, uid: string, role: Role) => Promis
 declare const lookupUser: (login: string) => Promise<ResolvedUser>;
 /** One durable grant an app holds, for the §8.11 capability audit view. */
 interface GrantRecord {
-    /** The app's provider-qualified identity (`provider__namespace__repository`). */
+    /** The app's provider-qualified **program** identity (AA-01 `appKey`). The DEFAULT
+     *  program keys to the bare `provider__namespace__repository`; a NAMED mini-app
+     *  appends a fourth `enc()`-escaped component (`provider__namespace__repository__name`)
+     *  so its grants isolate from the repo's other programs. Host-supplied — the app
+     *  never builds this key. */
     appKey: string;
     spaceId: string;
     /** Universal mount id (§3.5). */
@@ -390,4 +415,4 @@ declare const listGrants: () => Promise<GrantRecord[]>;
  *  best-effort live teardown. Elevated `spaces:admin`. */
 declare const revokeGrant: (appKey: string, spaceId: string) => Promise<void>;
 
-export { type GrantRecord, type Invite, type Member, type MountQuery, type MountRemoveReason, type MountRule, type RemovedMount, type ResolvedUser, type Role, type SandboxMount, type SessionMount, type SpaceError, type SpaceInfo, acceptInvite, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount };
+export { type GrantRecord, type Invite, type Member, type MountQuery, type MountRemoveReason, type MountRule, type RemovedMount, type ResolvedUser, type Role, type SandboxMount, type SessionMount, type SpaceError, type SpaceInfo, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, getSpaceMembers, importSettingsFromParent, inviteToSpace, listAllSpaces, listGrants, listMyInvites, listPendingInvites, listSettingsApps, listSpaces, lookupUser, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeGrant, revokeInvite, setSpaceRole, unmountSpace, unshareSpace, useInvites, useMounts, useSessionMounts, waitForMount };

package/dist/mounts.js

@@ -68,14 +68,35 @@ const onMountsChange = (listener) => {
   const disposable = mountService().onChange(listener);
   return () => disposable.dispose();
 };
-const waitForMount = (query) => new Promise((resolve) => {
-  const unsubscribe = onMountsChange((mounts) => {
+const waitForMount = (query, timeoutMs) => awaitMatchingMount(onMountsChange, query, timeoutMs);
+const awaitMatchingMount = (subscribe, query, timeoutMs) => new Promise((resolve, reject) => {
+  let unsubscribe;
+  let settled = false;
+  let timer;
+  const stop = () => {
+    settled = true;
+    if (timer !== void 0) clearTimeout(timer);
+    void Promise.resolve().then(() => unsubscribe?.());
+  };
+  unsubscribe = subscribe((mounts) => {
+    if (settled) return;
     const found = mounts.find((m) => matches(m, query));
     if (found) {
-      Promise.resolve().then(unsubscribe);
+      stop();
       resolve(found);
     }
   });
+  if (!settled && timeoutMs !== void 0) {
+    timer = setTimeout(() => {
+      if (settled) return;
+      stop();
+      const err = new Error(
+        `waitForMount timed out after ${timeoutMs}ms waiting for ${JSON.stringify(query)}`
+      );
+      err.code = "timeout";
+      reject(err);
+    }, timeoutMs);
+  }
 });
 const useMounts = () => {
   const [mounts, setMounts] = useState(getMounts);
@@ -128,8 +149,9 @@ const settingsRequest = async (method, query = {}) => {
 };
 const openSettings = async () => {
   const mount2 = await settingsRequest("open");
-  return waitForMount({ id: mount2.id ?? mount2.path });
+  return waitForMount({ id: mount2.id ?? mount2.path }, SETTINGS_MOUNT_TIMEOUT_MS);
 };
+const SETTINGS_MOUNT_TIMEOUT_MS = 15e3;
 const importSettingsFromParent = async () => {
   try {
     const data = await settingsRequest("importFromParent");
@@ -186,6 +208,7 @@ const revokeGrant = async (appKey, spaceId) => {
 };
 export {
   acceptInvite,
+  awaitMatchingMount,
   createSpace,
   declineInvite,
   findMount,

package/dist/mounts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { getHostRuntime } from './hostRuntime';\nimport { mountMatches } from './mountMatch';\n// Type-only: `tasks.ts` registers a host listener at module load, so we reuse the\n// FileCap SHAPE without pulling that side effect into every `mounts` importer.\nimport type { FileCap } from './tasks';\n\n/**\n * The absolute path where this app's own repository filesystem is mounted\n * (FILE_SHARING_SPEC §11.2). Prefer this over hardcoding `/app`: the repo is\n * dual-mounted at both `/app` (back-compat) and its canonical `/mnt/{hash}`\n * address, and this returns the canonical one the host reports. Falls back to\n * `/app` when the host hasn't reported a canonical path (older host / before the\n * report arrives) — both paths are live, so either resolves the same files.\n */\nexport const getAppMountPath = (): string => getHostRuntime()?.appMountPath ?? '/app';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openSettings} for this app's own settings,\n * or {@link mountSpace} / {@link requestMount} to mount a Firestore-backed \"space\".\n * Read or subscribe to the set, then access the files through the `fs` module at\n * the mount's `path`.\n */\nexport interface SandboxMount {\n  /** Absolute path where the mount is reachable (e.g. `/spaces/{id}`). */\n  path: string;\n  /** Backend kind, e.g. `'firestore'`. */\n  type: string;\n  /** Optional stable identifier (the spaceId, for spaces). */\n  id?: string;\n  /**\n   * Access mode of the granted view: `'rw'` (read-write) or `'ro'` (read-only).\n   * A live role downgrade re-announces the same mount with `mode: 'ro'`; apps\n   * observing `onMountsChange` see the change and writes start failing `EROFS`.\n   * Absent on the primary repo mount (treated as read-write).\n   */\n  mode?: \"ro\" | \"rw\";\n  /**\n   * Human-readable label for the mount — the space's display name, or the repo\n   * label for the primary working-tree mount (R3-69). Use this to show users and\n   * agents *what* a mount is: the `path` (`/mnt/{hash}`) and `id` (the spaceId)\n   * are opaque, and space names are not unique, so neither alone tells you which\n   * filesystem you're looking at. Absent when the host can't resolve a name\n   * (older host, or a name it never learned) — fall back to `id`/`path`.\n   */\n  name?: string;\n  /**\n   * The granted scopes of this mount (plan 12 §8.7 / §F): each `{subtree, mode}`\n   * is a path prefix you hold and at what access, at the mount's backend-natural\n   * paths. Use it to reason about per-path writability — which subtree is `rw` —\n   * WITHOUT probing `EROFS`. A single whole-mount grant is `[{ subtree: '/', mode }]`.\n   * Absent on the primary repo mount and on an older host that doesn't report it.\n   */\n  rules?: MountRule[];\n}\n\n/** One granted scope of a mount (plan 12 §F): a backend-natural path prefix and\n *  the access mode there. The most specific (longest) matching rule governs a path. */\nexport interface MountRule {\n  subtree: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Why a mounted filesystem was removed, surfaced on the removed descriptor so an\n * app can say *why* it vanished instead of failing mutely (auth-mount §\"mount-remove\"\n * / AM2-4):\n * - `revoked` — a durable grant was revoked (revokeGrant / consent withdrawal);\n * - `unshared` — the granting user's membership was removed (or downgraded out);\n * - `signed-out` — sign-out tore down every mount;\n * - `unmounted` — the app's own `unmountSpace` (or region teardown);\n * - `deleted` — the space was soft-deleted.\n * An older host that sends no reason is read as `'revoked'` (most conservative).\n */\nexport type MountRemoveReason =\n  | \"revoked\"\n  | \"unshared\"\n  | \"signed-out\"\n  | \"unmounted\"\n  | \"deleted\";\n\n/** A descriptor delivered as REMOVED to a mounts-change listener: the mount that\n *  went away, plus the `reason` it did. */\nexport interface RemovedMount extends SandboxMount {\n  reason: MountRemoveReason;\n}\n\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(\n    listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n  ): { dispose(): void };\n}\n\n// The stable key of a mount: its `id` (spaceId) when present, else its `path`.\n// Matches the sandbox `MountService.mountKey` so add/replace/remove agree on both\n// sides of the wire (a role downgrade re-announces the SAME key with `mode: 'ro'`).\nconst mountKey = (m: SandboxMount): string => m.id ?? m.path;\n\nconst MOUNT_REMOVE_REASONS: ReadonlySet<string> = new Set<MountRemoveReason>([\n  'revoked',\n  'unshared',\n  'signed-out',\n  'unmounted',\n  'deleted',\n]);\n\n// Normalize an over-the-wire `mount-remove` reason; an absent/unknown value (older\n// host) reads as `'revoked'`, the most conservative reading (mirrors the sandbox).\nconst asMountRemoveReason = (value: unknown): MountRemoveReason =>\n  typeof value === 'string' && MOUNT_REMOVE_REASONS.has(value)\n    ? (value as MountRemoveReason)\n    : 'revoked';\n\n// The injected sandbox-bundler mount service (`module.evaluation.module.bundler.mounts`),\n// or null when the SDK is npm-fetched with no injection — same dual-mode shape as\n// `sandboxUtils.transport()` and the metadata emitter (SDK_PACKAGING_SPEC §4/§8).\nconst injectedMountService = (): MountService | null => {\n  try {\n    // @ts-ignore - injected by the sandbox runtime\n    const svc = module?.evaluation?.module?.bundler?.mounts;\n    return svc && typeof svc.getMounts === 'function' ? svc : null;\n  } catch {\n    return null;\n  }\n};\n\n// Transport-backed descriptor cache (R3-51b): the npm-fetched fallback that builds\n// the same `getMounts()`/`onChange()` view the injected `bundler.mounts` provides,\n// directly from the host's `mount-add`/`mount-remove` messages over the §4 transport.\n// The host already posts these (it's how the in-iframe bundler service is populated);\n// the `MessagePort` a `mount-add` transfers is consumed by the sandbox runtime to wire\n// ZenFS and is irrelevant here — the SDK only mirrors the *descriptors*. A lazy\n// singleton so `getMounts`/`onMountsChange` share one cache, one subscription, and one\n// `request-mounts` replay (the host re-announces every current mount, like a poll).\nlet transportSvc: MountService | null = null;\n\nconst transportMountService = (): MountService => {\n  if (transportSvc) return transportSvc;\n  let mounts: SandboxMount[] = [];\n  const listeners = new Set<(m: SandboxMount[], r: RemovedMount[]) => void>();\n  const fire = (removed: RemovedMount[]) => {\n    for (const l of [...listeners]) l(mounts, removed);\n  };\n\n  addListener('mount-add', (msg: Record<string, any>) => {\n    const mount: SandboxMount | undefined = msg.mount;\n    if (!mount) return;\n    const key = mountKey(mount);\n    mounts = [...mounts.filter((m) => mountKey(m) !== key), mount];\n    fire([]);\n  });\n  addListener('mount-remove', (msg: Record<string, any>) => {\n    const key: string | undefined = msg.id ?? msg.path;\n    if (key == null) return;\n    const reason = asMountRemoveReason(msg.reason);\n    const removed = mounts.filter((m) => mountKey(m) === key).map((m) => ({ ...m, reason }));\n    if (removed.length === 0) return;\n    mounts = mounts.filter((m) => mountKey(m) !== key);\n    fire(removed);\n  });\n\n  // Ask the host to replay the current set (the matching `mount-add`s may have been\n  // sent before this SDK subscribed). Best-effort: a transport not yet ready throws.\n  try {\n    sendMessage('request-mounts');\n  } catch {\n    /* transport not ready — the live mount-add stream still populates the cache */\n  }\n\n  transportSvc = {\n    getMounts: () => mounts,\n    onChange: (listener) => {\n      listeners.add(listener);\n      listener(mounts, []); // immediate replay to the new subscriber\n      return { dispose: () => listeners.delete(listener) };\n    },\n  };\n  return transportSvc;\n};\n\n// Phase-5 dual mode: prefer the injected bundler service (the live path, behaviour\n// byte-for-byte unchanged); fall back to the transport-built cache when npm-fetched.\nconst mountService = (): MountService => injectedMountService() ?? transportMountService();\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. Any\n *  combination of coordinates; `name` matches the human-readable mount label. */\nexport type MountQuery = { type?: string; id?: string; path?: string; name?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  mountMatches(mount, query);\n\n/**\n * Returns the mounts currently available. Poll this whenever you need a one-off\n * read; use {@link onMountsChange} or {@link useMounts} to react to changes.\n * Each descriptor carries its `id` (the spaceId), `path` (`/mnt/{hash}`) and —\n * when the host can resolve it — a human-readable `name` (R3-69), so this doubles\n * as a queryable mount→space mapping for showing or locating a mount by name.\n */\nexport const getMounts = (): SandboxMount[] => mountService().getMounts();\n\n/** Returns the first mount matching `query`, or `undefined`. */\nexport const findMount = (query: MountQuery): SandboxMount | undefined =>\n  getMounts().find((m) => matches(m, query));\n\n/**\n * Subscribe to mount changes. The listener is invoked immediately with the\n * current mounts (and an empty `removed`), then again on every change. The second\n * argument carries the descriptors REMOVED by that change, each with its `reason`\n * (AM2-4) — so an app can react to *why* a mount vanished (e.g. tell the user a\n * shared space was `unshared` vs `deleted`). It is empty on adds and on the\n * initial replay. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (\n  listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n): (() => void) => {\n  const disposable = mountService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * Resolves once a mount matching `query` is present (immediately if it already\n * is). Handy for \"use it when it appears\" — e.g.\n * `await waitForMount({ type: 'firestore' })` before reading `/firestore`.\n */\nexport const waitForMount = (query: MountQuery): Promise<SandboxMount> =>\n  new Promise((resolve) => {\n    const unsubscribe = onMountsChange((mounts) => {\n      const found = mounts.find((m) => matches(m, query));\n      if (found) {\n        // Defer unsubscribe so we don't dispose during the initial replay call.\n        Promise.resolve().then(unsubscribe);\n        resolve(found);\n      }\n    });\n  });\n\n/** React hook returning the mounts currently available, re-rendering on change. */\nexport const useMounts = (): SandboxMount[] => {\n  const [mounts, setMounts] = useState<SandboxMount[]>(getMounts);\n  useEffect(() => onMountsChange(setMounts), []);\n  return mounts;\n};\n\n// ---------------------------------------------------------------------------\n// Session-scope mounts — the first-party \"App | Session\" lens (PRINCIPALS §9 B2).\n// ---------------------------------------------------------------------------\n\n/** A mount as seen through the first-party **Session** lens (PRINCIPALS_SPEC §9 B2):\n *  the session's mounts BEYOND this app's own (the editor/agent session's). This is\n *  a metadata view — no filesystem port — so it extends {@link SandboxMount} with only\n *  {@link forwardedToApp}. */\nexport interface SessionMount extends SandboxMount {\n  /** True iff this mount is ALSO in the app's own {@link useMounts} (the App lens);\n   *  `false` for a session-export-only mount visible only to the editor/agent + the\n   *  Session lens. */\n  forwardedToApp: boolean;\n}\n\n// The host pushes the session mount list ONLY to a FIRST-PARTY frame — the channel\n// is gated by the first-party-only `mounts:registry` capability (§8.9.1 / D-PRIN-4).\n// A URL-loaded/previewed app (or a fork of the File Explorer) never holds it, so the\n// push never arrives and `initial: []` stands — the Session lens is simply absent,\n// fail-closed. Mirrors the host's `session-mounts`/`request-session-mounts` wiring.\nconst sessionMountsChannel = createPushChannel<SessionMount[]>({\n  pushType: 'session-mounts',\n  requestType: 'request-session-mounts',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.mounts) ? (msg.mounts as SessionMount[]) : undefined),\n});\n\n/** The session's mounts (the \"Session\" lens superset), or `[]` when this frame is\n *  not first-party. One-off read; use {@link onSessionMountsChange}/{@link useSessionMounts}\n *  to react live. First-party only (`mounts:registry`) — a fork always sees `[]`. */\nexport const getSessionMounts = (): SessionMount[] => sessionMountsChannel.get();\n\n/** Subscribe to Session-lens mount changes. Invoked immediately with the current\n *  list (`[]` for a non-first-party frame), then on every change. Returns an\n *  unsubscribe. */\nexport const onSessionMountsChange = (\n  listener: (mounts: SessionMount[]) => void,\n): (() => void) => sessionMountsChannel.onChange(listener);\n\n/** React hook returning the live \"Session\" lens mount list, re-rendering on change.\n *  Empty for any non-first-party frame (the host withholds the channel), so a URL-\n *  loaded File Explorer fork renders no Session lens. */\nexport const useSessionMounts = (): SessionMount[] => sessionMountsChannel.use();\n\n// ---------------------------------------------------------------------------\n// Spaces — on-demand, shareable Firestore-backed filesystems.\n// The host owns all UX: if you aren't signed in, or the space doesn't exist or\n// isn't accessible, the parent window presents sign-in / create / request-access\n// and only then resolves these calls. See docs/specs/FILE_SHARING_SPEC.md.\n// ---------------------------------------------------------------------------\n\n/** Summary of a space, as returned by {@link listSpaces}. */\nexport interface SpaceInfo {\n  spaceId: string;\n  role?: 'owner' | 'writer' | 'reader';\n  owner?: string;\n  name?: string;\n}\n\n/** An error from a space operation, carrying a machine-readable `code`. */\nexport interface SpaceError extends Error {\n  code:\n    | 'auth-required'\n    | 'cancelled'\n    | 'forbidden'\n    | 'not-found'\n    | 'unsupported-scheme'\n    | 'unknown';\n}\n\ntype SpaceResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a spaces protocol request, unwrapping the host's {ok,data} envelope and\n// throwing a typed SpaceError on failure.\nconst request = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('spaces', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'space request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Request a space mount, then wait until the host actually registers it. The\n// host announces the mount (`mount-add`) separately from the protocol reply, so\n// an immediate read could otherwise race the mount.\nconst requestMountInternal = async (\n  method: string,\n  query: Record<string, unknown>,\n): Promise<SandboxMount> => {\n  const mount = await request<SandboxMount>(method, query);\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —\n * `scheme:locator`, e.g. `space:{spaceId}` or `github:owner/repo@ref`. Backend-blind:\n * the host resolves the scheme. A scheme with no resolver rejects with\n * {@link SpaceError} `unsupported-scheme`.\n */\nexport const mount = (mountId: string): Promise<SandboxMount> =>\n  requestMountInternal('mount', { mount: mountId });\n\n/** Mount a specific space by id (e.g. one shared with you, or from a link). A thin\n *  shim over {@link mount} with the `space:` scheme. */\nexport const mountSpace = (query: { spaceId: string }): Promise<SandboxMount> =>\n  mount(`space:${query.spaceId}`);\n\n/**\n * Ask the user to grant a filesystem to this app — the §8.6 powerbox. The app\n * asks; the HOST shows the user their spaces and, for the chosen one, its PROJECT\n * FOLDERS (§8.7). The user picks ONE project — so a shared space opens scoped to\n * just that project, never the whole space — and makes an EXPLICIT read-only vs\n * read-write decision (there is no default). The app never sees the list; it\n * resolves with the single granted mount, or rejects with a {@link SpaceError}\n * (`cancelled`) if declined. The granted scope is enforced host-side: the mount\n * is chroot'd to the project folder and `ro`-limited accordingly, so paths\n * outside the project are unnameable and writes on a `ro` grant fail `EROFS`.\n *\n * A project folder is the macOS-bundle-like unit an app works in inside a space;\n * the host records which app a folder belongs to (a `.immediately.run/` sidecar),\n * so the picker can surface the app's own projects or let the user create a new\n * one. Observe the granted access via {@link SandboxMount.mode}.\n *\n * Backend-general (§3.5): the picker offers whatever mounts the user has (today,\n * their spaces). Returns the granted mount by its universal id.\n */\nexport const requestMount = (): Promise<SandboxMount> =>\n  requestMountInternal('request', {});\n\n/** Prompt the user to grant a mount, returning the granted {@link SandboxMount}.\n *  @deprecated renamed to {@link requestMount} (backend-general, §3.5). */\nexport const requestSpace = requestMount;\n\n// ── content references (plan 12 §E / FILE_SHARING §7) ────────────────────────\n\n/**\n * Build a persisted CONTENT REFERENCE to a file in a mount — a `{mountId, relPath}`\n * pointer your app serializes into ITS OWN content (a board's JSON, an MDX file's\n * frontmatter, an album manifest — the platform doesn't dictate the container) so a\n * later viewer can resolve it. It is exactly the §5.7 {@link capFile} shape: ONE\n * capability, two delivery modes — runtime delegation (a task param, authorized by\n * the caller) vs a durable reference (authorized per-viewer by {@link resolveContentRef}).\n * `relPath` is BACKEND-NATURAL, so the reference resolves to the SAME path for every\n * viewer. Cross-app/cross-project references default to `ro`.\n *\n *   const ref = makeContentRef({ mountId: 'space:ACME', relPath: 'office-seating/desk.mdx' }, { mode: 'ro' });\n */\nexport const makeContentRef = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): FileCap => ({ $cap: 'file', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\n\n/**\n * Resolve a content reference your app found in content it ALREADY holds\n * (FILE_SHARING §7 / UI_AS_APPS §8.7; \"plan 12 §E\"). This is a RELAY, not a\n * fabrication: the host honors it ONLY when your app\n * already holds a grant to `ref.mountId` (else `forbidden`) — apps follow\n * writer-authored links inside granted content; they cannot name a space from\n * nothing (T27). The host runs a per-VIEWER consent prompt (named via the owning\n * app's project sidecar), and existence is never leaked — a decline and a\n * non-existent path are indistinguishable.\n *\n * On allow, the host APPENDS a read scope for the referenced path to your grant\n * (durable; same §8.15 lifecycle) and returns the STABLE absolute `path` the file\n * is mounted at — identical for every viewer, so a path the author stored resolves\n * the same for you. Read it through the `fs` module at that path. Rejects with a\n * {@link SpaceError}: `forbidden` (you don't hold the referenced mount) or\n * `cancelled` (the viewer declined / the path doesn't exist — no oracle).\n *\n *   const { path } = await resolveContentRef(ref);\n *   const text = await fs.promises.readFile(path, 'utf8');\n */\nexport const resolveContentRef = async (ref: FileCap): Promise<{ path: string }> => {\n  const path = await request<string>('resolveRef', { ref });\n  return { path };\n};\n\n/**\n * Resolve a BATCH of content references in ONE consent round (FILE_SHARING §7 /\n * UI_AS_APPS §8.7; \"plan 12 §E\"). When a\n * board opens with several embedded references, pass them all here: the host\n * coalesces them into a SINGLE consent prompt listing every target, instead of one\n * prompt per reference. Same relay gate and per-viewer semantics as\n * {@link resolveContentRef} (each ref's mount must already be held), applied to the\n * whole set — it is all-or-nothing: the user allows the batch or declines it.\n *\n * Resolves `{ paths }` with the STABLE absolute path of each ref, in input order.\n * Rejects with a {@link SpaceError}: `forbidden` (a referenced mount isn't held) or\n * `cancelled` (the viewer declined).\n *\n *   const { paths } = await resolveContentRefs(board.references);\n */\nexport const resolveContentRefs = async (refs: FileCap[]): Promise<{ paths: string[] }> => {\n  const paths = await request<string[]>('resolveRefs', { refs });\n  return { paths };\n};\n\n// ---------------------------------------------------------------------------\n// Settings — the per-user \"~/.config\"-style space (UI_AS_APPS_SPEC §3.3/§3.5/§8.2).\n// Each app gets its OWN settings subdir, auto-provisioned and chroot'd by the host\n// (no dialog, no powerbox). Read/write it through the returned mount's filesystem\n// port — there is deliberately no key/value get/set API; settings are just files.\n// ---------------------------------------------------------------------------\n\n// Issue a `protocol-settings` request, unwrapping {ok,data} and throwing a typed\n// SpaceError on failure (mirrors `request` for the spaces surface).\nconst settingsRequest = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('settings', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'settings request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Mount this app's per-user settings — a private `~/.config`-style filesystem,\n * auto-provisioned for the signed-in user and isolated to THIS app (the host\n * chroots it; a different app can never name it). Read/write config files through\n * the returned mount. Rejects with a {@link SpaceError} (`auth-required`) when\n * signed out. Capability: baseline `settings:app`.\n */\nexport const openSettings = async (): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('open');\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * One-time SEED of this app's settings from the parent it declares as `forkOf`\n * (its `package.json` `immediately.run.forkOf`) — so a fork inherits your\n * preferences from the original app (UI_AS_APPS_SPEC §3.4). The host asks the user\n * to confirm (a full consent when the apps have different owners, a light confirm\n * when the same owner publishes both) and copies the parent's settings into this\n * app's own subdir, skipping any file you already have. Non-throwing: resolves\n * `{ ok:false, code }` on decline (`cancelled`), no declared parent (`forbidden`),\n * or signed-out (`auth-required`). After `{ ok:true }`, read {@link openSettings}.\n * Capability: baseline `settings:fork`.\n */\nexport const importSettingsFromParent = async (): Promise<\n  { ok: true; copied: number } | { ok: false; code: string }\n> => {\n  try {\n    const data = await settingsRequest<{ copied: number }>('importFromParent');\n    return { ok: true, copied: data.copied };\n  } catch (e) {\n    return { ok: false, code: (e as SpaceError).code ?? 'unknown' };\n  }\n};\n\n/**\n * Mount ANOTHER app's per-user settings by its `appKey` — the elevated \"file\n * commander\" surface. Rejects `forbidden` unless this app holds the first-party-\n * only `settings:all` capability. Most apps want {@link openSettings} instead.\n */\nexport const openSettingsOf = async (appKey: string): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('openOf', { appKey });\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * List every app that has per-user settings — the elevated \"file commander\"\n * enumeration. Pair with {@link openSettingsOf} to mount any of them. Rejects\n * `forbidden` unless this app holds the first-party-only `settings:all`.\n */\nexport const listSettingsApps = (): Promise<string[]> =>\n  settingsRequest<string[]>('list');\n\n/** Create a brand-new, empty platform-hosted space. The app reaches it (or any\n *  other space) afterward through the {@link requestMount} powerbox or\n *  {@link mountSpace}; there is no implicit per-app binding. */\nexport const createSpace = (\n  opts: { name?: string } = {}\n): Promise<SandboxMount> => requestMountInternal('create', opts);\n\n/** List spaces you can access — all of them, or just those bound to this app. */\nexport const listSpaces = (opts: { app?: boolean } = {}): Promise<SpaceInfo[]> =>\n  request<SpaceInfo[]>('list', opts);\n\n/** Release a mounted space (stops its listener on the host). */\nexport const unmountSpace = async (query: { spaceId: string }): Promise<void> => {\n  await request('unmount', query);\n};\n\n// ---------------------------------------------------------------------------\n// Space management (the space-manager app) — UI_AS_APPS_SPEC §5.2. These are\n// ELEVATED: enumerating all the user's spaces is `spaces:user`; mutating\n// membership (share/unshare/setRole) and resolving handles is `spaces:admin`.\n// The host enforces the owner-lockout invariant (a space always keeps an owner,\n// T41) and rate-limits handle lookups (L1); the OAuth/identity token never\n// crosses to the app.\n// ---------------------------------------------------------------------------\n\n/** A collaborator's role on a shared space: full `owner`, read-write `writer`, or read-only `reader`. */\nexport type Role = 'owner' | 'writer' | 'reader';\n\n/** A member of a space (for the share/manage UI). */\nexport interface Member {\n  /**\n   * The **grantee** — `user:{uid}` | `group:{gid}`. This is the canonical name\n   * (core_concepts §4: \"principal\" is reserved for the authority context; a space\n   * member is a *grantee*). The host populates this on every member row.\n   */\n  grantee: string;\n  /**\n   * @deprecated Use {@link Member.grantee}. Kept as an alias (same value) for\n   * back-compat during the `principal`→`grantee` migration; will be removed in a\n   * future major. The host still populates both.\n   */\n  principal: string;\n  role: Role;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** A handle resolved to a principal (handle → who). */\nexport interface ResolvedUser {\n  uid: string;\n  login: string;\n  avatarUrl?: string;\n}\n\n/** A pending invitation to a space (pull-based sharing, FILE_SHARING_SPEC §6.4).\n *  It grants NO access until accepted — the recipient accepts it from their inbox\n *  ({@link listMyInvites} → {@link acceptInvite}), materializing membership. The\n *  display fields (`name`/`login`/`avatarUrl`) are untrusted for rendering. */\nexport interface Invite {\n  spaceId: string;\n  /** The invitee's uid — carried so the owner's pending list can\n   *  {@link revokeInvite}(spaceId, uid). */\n  uid: string;\n  role: Role;\n  owner: string;\n  name?: string;\n  invitedBy: string;\n  /** epoch ms (server-stamped); absent until the write settles. */\n  invitedAt?: number;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** Enumerate ALL the user's spaces (not just this app's) — `spaces:user`. */\nexport const listAllSpaces = (): Promise<SpaceInfo[]> => request<SpaceInfo[]>('listAll', {});\n\n/** Read a space's members one-shot — `spaces:admin`. */\nexport const getSpaceMembers = (spaceId: string): Promise<Member[]> =>\n  request<Member[]>('members', { spaceId });\n\n/** Invite a user (by provider handle) to a space at a role — `spaces:admin`. The\n *  host resolves the handle, so the app never sees other users' uids except the one\n *  it invited. Pull-based (FILE_SHARING_SPEC §6.4): this writes an INVITATION, not\n *  membership — the recipient must {@link acceptInvite}. Re-inviting an already-\n *  invited/member user is idempotent. */\nexport const inviteToSpace = async (spaceId: string, login: string, role: Role): Promise<void> => {\n  await request('invite', { spaceId, login, role });\n};\n\n/** The owner's outstanding invitations for a space — `spaces:admin`. */\nexport const listPendingInvites = (spaceId: string): Promise<Invite[]> =>\n  request<Invite[]>('pendingInvites', { spaceId });\n\n/** Withdraw a pending invitation (distinct from {@link unshareSpace}, which removes\n *  an ACCEPTED member) — `spaces:admin`. */\nexport const revokeInvite = async (spaceId: string, uid: string): Promise<void> => {\n  await request('revokeInvite', { spaceId, uid });\n};\n\n/** The caller's OWN invitation inbox — `spaces:user`. */\nexport const listMyInvites = (): Promise<Invite[]> => request<Invite[]>('listInvites', {});\n\n/** Accept an invitation: materialize your membership at the invited role and clear\n *  the invite — `spaces:user`. An invitation the caller doesn't hold rejects with\n *  `forbidden` (indistinguishable from a nonexistent space; no existence oracle). */\nexport const acceptInvite = async (spaceId: string): Promise<void> => {\n  await request('acceptInvite', { spaceId });\n};\n\n/** Decline (dismiss) an invitation from your inbox; writes no membership —\n *  `spaces:user`. */\nexport const declineInvite = async (spaceId: string): Promise<void> => {\n  await request('declineInvite', { spaceId });\n};\n\n// The live invitations inbox (FILE_SHARING §6.4/§9.8): the host pushes the caller's\n// current invitations on change and replays on register-frame; gated `spaces:user`.\n// So an invite that arrives (or an accepted/declined one leaving) reflects within one\n// snapshot — no poll. Mirrors the host's `invitations`/`request-invitations` wiring.\nconst invitesChannel = createPushChannel<Invite[]>({\n  pushType: 'invitations',\n  requestType: 'request-invitations',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.invites) ? (msg.invites as Invite[]) : undefined),\n});\n\n/** The caller's current invitations (`spaces:user`). One-off read; use\n *  {@link onInvitesChange}/{@link useInvites} to react live. */\nexport const getInvites = (): Invite[] => invitesChannel.get();\n\n/** Subscribe to invitation-inbox changes (arrived / accepted / declined). Invoked\n *  immediately with the current list, then on every change. Returns an unsubscribe. */\nexport const onInvitesChange = (listener: (invites: Invite[]) => void): (() => void) =>\n  invitesChannel.onChange(listener);\n\n/** React hook returning the caller's live invitation inbox, re-rendering on change\n *  (the space-manager Invitations inbox, §9.8). */\nexport const useInvites = (): Invite[] => invitesChannel.use();\n\n/** Remove a member from a space — `spaces:admin`. Refused if it would orphan the\n *  space (owner-lockout, T41). */\nexport const unshareSpace = async (spaceId: string, uid: string): Promise<void> => {\n  await request('unshare', { spaceId, uid });\n};\n\n/** Change a member's role — `spaces:admin`. Refused if it would drop the sole\n *  owner (owner-lockout, T41). */\nexport const setSpaceRole = async (spaceId: string, uid: string, role: Role): Promise<void> => {\n  await request('setRole', { spaceId, uid, role });\n};\n\n/** Resolve a provider handle to a principal (for the invite flow) — `spaces:admin`,\n *  rate-limited host-side. */\nexport const lookupUser = (login: string): Promise<ResolvedUser> =>\n  request<ResolvedUser>('lookupUser', { login });\n\n/** One durable grant an app holds, for the §8.11 capability audit view. */\nexport interface GrantRecord {\n  /** The app's provider-qualified identity (`provider__namespace__repository`). */\n  appKey: string;\n  spaceId: string;\n  /** Universal mount id (§3.5). */\n  mountId: string;\n  subtree?: string;\n  mode: 'ro' | 'rw';\n  name?: string;\n}\n\n/** Enumerate every (app, mount) grant the user holds — the audit view\n *  (§8.11). Elevated `spaces:admin`. */\nexport const listGrants = (): Promise<GrantRecord[]> => request<GrantRecord[]>('grants', {});\n\n/** Revoke one app's grant on a space — durable (the app can't re-mount) plus a\n *  best-effort live teardown. Elevated `spaces:admin`. */\nexport const revokeGrant = async (appKey: string, spaceId: string): Promise<void> => {\n  await request('revokeGrant', { appKey, spaceId });\n};\n"],"mappings":"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","names":["mount"]}
+{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\nimport { getHostRuntime } from './hostRuntime';\nimport { mountMatches } from './mountMatch';\n// Type-only: `tasks.ts` registers a host listener at module load, so we reuse the\n// FileCap SHAPE without pulling that side effect into every `mounts` importer.\nimport type { FileCap } from './tasks';\n\n/**\n * The absolute path where this app's own repository filesystem is mounted\n * (FILE_SHARING_SPEC §11.2). Prefer this over hardcoding `/app`: the repo is\n * dual-mounted at both `/app` (back-compat) and its canonical `/mnt/{hash}`\n * address, and this returns the canonical one the host reports. Falls back to\n * `/app` when the host hasn't reported a canonical path (older host / before the\n * report arrives) — both paths are live, so either resolves the same files.\n */\nexport const getAppMountPath = (): string => getHostRuntime()?.appMountPath ?? '/app';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openSettings} for this app's own settings,\n * or {@link mountSpace} / {@link requestMount} to mount a Firestore-backed \"space\".\n * Read or subscribe to the set, then access the files through the `fs` module at\n * the mount's `path`.\n */\nexport interface SandboxMount {\n  /** Absolute path where the mount is reachable (e.g. `/spaces/{id}`). */\n  path: string;\n  /** Backend kind, e.g. `'firestore'`. */\n  type: string;\n  /** Optional stable identifier (the spaceId, for spaces). */\n  id?: string;\n  /**\n   * Access mode of the granted view: `'rw'` (read-write) or `'ro'` (read-only).\n   * A live role downgrade re-announces the same mount with `mode: 'ro'`; apps\n   * observing `onMountsChange` see the change and writes start failing `EROFS`.\n   * Absent on the primary repo mount (treated as read-write).\n   */\n  mode?: \"ro\" | \"rw\";\n  /**\n   * Human-readable label for the mount — the space's display name, or the repo\n   * label for the primary working-tree mount (R3-69). Use this to show users and\n   * agents *what* a mount is: the `path` (`/mnt/{hash}`) and `id` (the spaceId)\n   * are opaque, and space names are not unique, so neither alone tells you which\n   * filesystem you're looking at. Absent when the host can't resolve a name\n   * (older host, or a name it never learned) — fall back to `id`/`path`.\n   */\n  name?: string;\n  /**\n   * The granted scopes of this mount (plan 12 §8.7 / §F): each `{subtree, mode}`\n   * is a path prefix you hold and at what access, at the mount's backend-natural\n   * paths. Use it to reason about per-path writability — which subtree is `rw` —\n   * WITHOUT probing `EROFS`. A single whole-mount grant is `[{ subtree: '/', mode }]`.\n   * Absent on the primary repo mount and on an older host that doesn't report it.\n   */\n  rules?: MountRule[];\n}\n\n/** One granted scope of a mount (plan 12 §F): a backend-natural path prefix and\n *  the access mode there. The most specific (longest) matching rule governs a path. */\nexport interface MountRule {\n  subtree: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Why a mounted filesystem was removed, surfaced on the removed descriptor so an\n * app can say *why* it vanished instead of failing mutely (auth-mount §\"mount-remove\"\n * / AM2-4):\n * - `revoked` — a durable grant was revoked (revokeGrant / consent withdrawal);\n * - `unshared` — the granting user's membership was removed (or downgraded out);\n * - `signed-out` — sign-out tore down every mount;\n * - `unmounted` — the app's own `unmountSpace` (or region teardown);\n * - `deleted` — the space was soft-deleted.\n * An older host that sends no reason is read as `'revoked'` (most conservative).\n */\nexport type MountRemoveReason =\n  | \"revoked\"\n  | \"unshared\"\n  | \"signed-out\"\n  | \"unmounted\"\n  | \"deleted\";\n\n/** A descriptor delivered as REMOVED to a mounts-change listener: the mount that\n *  went away, plus the `reason` it did. */\nexport interface RemovedMount extends SandboxMount {\n  reason: MountRemoveReason;\n}\n\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(\n    listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n  ): { dispose(): void };\n}\n\n// The stable key of a mount: its `id` (spaceId) when present, else its `path`.\n// Matches the sandbox `MountService.mountKey` so add/replace/remove agree on both\n// sides of the wire (a role downgrade re-announces the SAME key with `mode: 'ro'`).\nconst mountKey = (m: SandboxMount): string => m.id ?? m.path;\n\nconst MOUNT_REMOVE_REASONS: ReadonlySet<string> = new Set<MountRemoveReason>([\n  'revoked',\n  'unshared',\n  'signed-out',\n  'unmounted',\n  'deleted',\n]);\n\n// Normalize an over-the-wire `mount-remove` reason; an absent/unknown value (older\n// host) reads as `'revoked'`, the most conservative reading (mirrors the sandbox).\nconst asMountRemoveReason = (value: unknown): MountRemoveReason =>\n  typeof value === 'string' && MOUNT_REMOVE_REASONS.has(value)\n    ? (value as MountRemoveReason)\n    : 'revoked';\n\n// The injected sandbox-bundler mount service (`module.evaluation.module.bundler.mounts`),\n// or null when the SDK is npm-fetched with no injection — same dual-mode shape as\n// `sandboxUtils.transport()` and the metadata emitter (SDK_PACKAGING_SPEC §4/§8).\nconst injectedMountService = (): MountService | null => {\n  try {\n    // @ts-ignore - injected by the sandbox runtime\n    const svc = module?.evaluation?.module?.bundler?.mounts;\n    return svc && typeof svc.getMounts === 'function' ? svc : null;\n  } catch {\n    return null;\n  }\n};\n\n// Transport-backed descriptor cache (R3-51b): the npm-fetched fallback that builds\n// the same `getMounts()`/`onChange()` view the injected `bundler.mounts` provides,\n// directly from the host's `mount-add`/`mount-remove` messages over the §4 transport.\n// The host already posts these (it's how the in-iframe bundler service is populated);\n// the `MessagePort` a `mount-add` transfers is consumed by the sandbox runtime to wire\n// ZenFS and is irrelevant here — the SDK only mirrors the *descriptors*. A lazy\n// singleton so `getMounts`/`onMountsChange` share one cache, one subscription, and one\n// `request-mounts` replay (the host re-announces every current mount, like a poll).\nlet transportSvc: MountService | null = null;\n\nconst transportMountService = (): MountService => {\n  if (transportSvc) return transportSvc;\n  let mounts: SandboxMount[] = [];\n  const listeners = new Set<(m: SandboxMount[], r: RemovedMount[]) => void>();\n  const fire = (removed: RemovedMount[]) => {\n    for (const l of [...listeners]) l(mounts, removed);\n  };\n\n  addListener('mount-add', (msg: Record<string, any>) => {\n    const mount: SandboxMount | undefined = msg.mount;\n    if (!mount) return;\n    const key = mountKey(mount);\n    mounts = [...mounts.filter((m) => mountKey(m) !== key), mount];\n    fire([]);\n  });\n  addListener('mount-remove', (msg: Record<string, any>) => {\n    const key: string | undefined = msg.id ?? msg.path;\n    if (key == null) return;\n    const reason = asMountRemoveReason(msg.reason);\n    const removed = mounts.filter((m) => mountKey(m) === key).map((m) => ({ ...m, reason }));\n    if (removed.length === 0) return;\n    mounts = mounts.filter((m) => mountKey(m) !== key);\n    fire(removed);\n  });\n\n  // Ask the host to replay the current set (the matching `mount-add`s may have been\n  // sent before this SDK subscribed). Best-effort: a transport not yet ready throws.\n  try {\n    sendMessage('request-mounts');\n  } catch {\n    /* transport not ready — the live mount-add stream still populates the cache */\n  }\n\n  transportSvc = {\n    getMounts: () => mounts,\n    onChange: (listener) => {\n      listeners.add(listener);\n      listener(mounts, []); // immediate replay to the new subscriber\n      return { dispose: () => listeners.delete(listener) };\n    },\n  };\n  return transportSvc;\n};\n\n// Phase-5 dual mode: prefer the injected bundler service (the live path, behaviour\n// byte-for-byte unchanged); fall back to the transport-built cache when npm-fetched.\nconst mountService = (): MountService => injectedMountService() ?? transportMountService();\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. Any\n *  combination of coordinates; `name` matches the human-readable mount label. */\nexport type MountQuery = { type?: string; id?: string; path?: string; name?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  mountMatches(mount, query);\n\n/**\n * Returns the mounts currently available. Poll this whenever you need a one-off\n * read; use {@link onMountsChange} or {@link useMounts} to react to changes.\n * Each descriptor carries its `id` (the spaceId), `path` (`/mnt/{hash}`) and —\n * when the host can resolve it — a human-readable `name` (R3-69), so this doubles\n * as a queryable mount→space mapping for showing or locating a mount by name.\n */\nexport const getMounts = (): SandboxMount[] => mountService().getMounts();\n\n/** Returns the first mount matching `query`, or `undefined`. */\nexport const findMount = (query: MountQuery): SandboxMount | undefined =>\n  getMounts().find((m) => matches(m, query));\n\n/**\n * Subscribe to mount changes. The listener is invoked immediately with the\n * current mounts (and an empty `removed`), then again on every change. The second\n * argument carries the descriptors REMOVED by that change, each with its `reason`\n * (AM2-4) — so an app can react to *why* a mount vanished (e.g. tell the user a\n * shared space was `unshared` vs `deleted`). It is empty on adds and on the\n * initial replay. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (\n  listener: (mounts: SandboxMount[], removed: RemovedMount[]) => void,\n): (() => void) => {\n  const disposable = mountService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * Resolves once a mount matching `query` is present (immediately if it already\n * is). Handy for \"use it when it appears\" — e.g.\n * `await waitForMount({ type: 'firestore' })` before reading `/firestore`.\n *\n * `timeoutMs` (optional, additive) rejects with a `timeout`-coded error instead of\n * waiting forever. Omit it to keep the original unbounded behaviour — but prefer\n * setting it on any path whose caller would otherwise hang silently: a mount that\n * never arrives is indistinguishable from one that is merely slow, and an awaited\n * promise that never settles surfaces to the user as a feature that quietly does\n * nothing.\n *\n * **Hazard — `onMountsChange` calls its listener SYNCHRONOUSLY on subscribe** (the\n * documented initial replay). So when the mount is already present — the common\n * case, since callers typically `await` the host request that creates it first —\n * the callback below runs *during* the `onMountsChange(...)` call, before the\n * assignment to `unsubscribe` completes. `unsubscribe` is therefore declared with\n * `let` ABOVE the subscription and read only inside a deferred closure: writing\n * `const unsubscribe = onMountsChange(...)` and referencing it in the callback\n * throws `ReferenceError: Cannot access 'unsubscribe' before initialization` (a\n * temporal-dead-zone read) on exactly that path. That bug silently broke\n * `openSettings()` — and with it the agent's conversation memory.\n */\nexport const waitForMount = (\n  query: MountQuery,\n  timeoutMs?: number,\n): Promise<SandboxMount> => awaitMatchingMount(onMountsChange, query, timeoutMs);\n\n/** The framework-free core of {@link waitForMount}, with the subscription injected\n *  so a test can drive the synchronous-initial-replay case that broke it. */\nexport const awaitMatchingMount = (\n  subscribe: (listener: (mounts: SandboxMount[]) => void) => () => void,\n  query: MountQuery,\n  timeoutMs?: number,\n): Promise<SandboxMount> =>\n  new Promise((resolve, reject) => {\n    // `let`, declared BEFORE `subscribe(...)` — see the hazard note above. A\n    // `const` bound to the subscribe call is in its temporal dead zone while the\n    // synchronous initial replay runs, and any read of it from the listener\n    // throws.\n    let unsubscribe: (() => void) | undefined;\n    let settled = false;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    // Deferred so we never dispose the subscription from inside its own initial\n    // replay, and late enough that `unsubscribe` is always assigned.\n    const stop = (): void => {\n      settled = true;\n      if (timer !== undefined) clearTimeout(timer);\n      void Promise.resolve().then(() => unsubscribe?.());\n    };\n    unsubscribe = subscribe((mounts) => {\n      if (settled) return;\n      const found = mounts.find((m) => matches(m, query));\n      if (found) {\n        stop();\n        resolve(found);\n      }\n    });\n    // The initial replay may have settled us above, before `unsubscribe` existed;\n    // `stop()`'s deferred read picks it up, so nothing more is needed here.\n    if (!settled && timeoutMs !== undefined) {\n      timer = setTimeout(() => {\n        if (settled) return;\n        stop();\n        const err = new Error(\n          `waitForMount timed out after ${timeoutMs}ms waiting for ${JSON.stringify(query)}`,\n        ) as SpaceError;\n        err.code = 'timeout';\n        reject(err);\n      }, timeoutMs);\n    }\n  });\n\n/** React hook returning the mounts currently available, re-rendering on change. */\nexport const useMounts = (): SandboxMount[] => {\n  const [mounts, setMounts] = useState<SandboxMount[]>(getMounts);\n  useEffect(() => onMountsChange(setMounts), []);\n  return mounts;\n};\n\n// ---------------------------------------------------------------------------\n// Session-scope mounts — the first-party \"App | Session\" lens (PRINCIPALS §9 B2).\n// ---------------------------------------------------------------------------\n\n/** A mount as seen through the first-party **Session** lens (PRINCIPALS_SPEC §9 B2):\n *  the session's mounts BEYOND this app's own (the editor/agent session's). This is\n *  a metadata view — no filesystem port — so it extends {@link SandboxMount} with only\n *  {@link forwardedToApp}. */\nexport interface SessionMount extends SandboxMount {\n  /** True iff this mount is ALSO in the app's own {@link useMounts} (the App lens);\n   *  `false` for a session-export-only mount visible only to the editor/agent + the\n   *  Session lens. */\n  forwardedToApp: boolean;\n}\n\n// The host pushes the session mount list ONLY to a FIRST-PARTY frame — the channel\n// is gated by the first-party-only `mounts:registry` capability (§8.9.1 / D-PRIN-4).\n// A URL-loaded/previewed app (or a fork of the File Explorer) never holds it, so the\n// push never arrives and `initial: []` stands — the Session lens is simply absent,\n// fail-closed. Mirrors the host's `session-mounts`/`request-session-mounts` wiring.\nconst sessionMountsChannel = createPushChannel<SessionMount[]>({\n  pushType: 'session-mounts',\n  requestType: 'request-session-mounts',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.mounts) ? (msg.mounts as SessionMount[]) : undefined),\n});\n\n/** The session's mounts (the \"Session\" lens superset), or `[]` when this frame is\n *  not first-party. One-off read; use {@link onSessionMountsChange}/{@link useSessionMounts}\n *  to react live. First-party only (`mounts:registry`) — a fork always sees `[]`. */\nexport const getSessionMounts = (): SessionMount[] => sessionMountsChannel.get();\n\n/** Subscribe to Session-lens mount changes. Invoked immediately with the current\n *  list (`[]` for a non-first-party frame), then on every change. Returns an\n *  unsubscribe. */\nexport const onSessionMountsChange = (\n  listener: (mounts: SessionMount[]) => void,\n): (() => void) => sessionMountsChannel.onChange(listener);\n\n/** React hook returning the live \"Session\" lens mount list, re-rendering on change.\n *  Empty for any non-first-party frame (the host withholds the channel), so a URL-\n *  loaded File Explorer fork renders no Session lens. */\nexport const useSessionMounts = (): SessionMount[] => sessionMountsChannel.use();\n\n// ---------------------------------------------------------------------------\n// Spaces — on-demand, shareable Firestore-backed filesystems.\n// The host owns all UX: if you aren't signed in, or the space doesn't exist or\n// isn't accessible, the parent window presents sign-in / create / request-access\n// and only then resolves these calls. See docs/specs/FILE_SHARING_SPEC.md.\n// ---------------------------------------------------------------------------\n\n/** Summary of a space, as returned by {@link listSpaces}. */\nexport interface SpaceInfo {\n  spaceId: string;\n  role?: 'owner' | 'writer' | 'reader';\n  owner?: string;\n  name?: string;\n}\n\n/** An error from a space operation, carrying a machine-readable `code`. */\nexport interface SpaceError extends Error {\n  code:\n    | 'auth-required'\n    | 'cancelled'\n    | 'forbidden'\n    | 'not-found'\n    | 'unsupported-scheme'\n    // Client-side, never from the host: a bounded `waitForMount` gave up.\n    | 'timeout'\n    | 'unknown';\n}\n\ntype SpaceResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a spaces protocol request, unwrapping the host's {ok,data} envelope and\n// throwing a typed SpaceError on failure.\nconst request = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('spaces', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'space request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Request a space mount, then wait until the host actually registers it. The\n// host announces the mount (`mount-add`) separately from the protocol reply, so\n// an immediate read could otherwise race the mount.\nconst requestMountInternal = async (\n  method: string,\n  query: Record<string, unknown>,\n): Promise<SandboxMount> => {\n  const mount = await request<SandboxMount>(method, query);\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —\n * `scheme:locator`, e.g. `space:{spaceId}` or `github:owner/repo@ref`. Backend-blind:\n * the host resolves the scheme. A scheme with no resolver rejects with\n * {@link SpaceError} `unsupported-scheme`.\n */\nexport const mount = (mountId: string): Promise<SandboxMount> =>\n  requestMountInternal('mount', { mount: mountId });\n\n/** Mount a specific space by id (e.g. one shared with you, or from a link). A thin\n *  shim over {@link mount} with the `space:` scheme. */\nexport const mountSpace = (query: { spaceId: string }): Promise<SandboxMount> =>\n  mount(`space:${query.spaceId}`);\n\n/**\n * Ask the user to grant a filesystem to this app — the §8.6 powerbox. The app\n * asks; the HOST shows the user their spaces and, for the chosen one, its PROJECT\n * FOLDERS (§8.7). The user picks ONE project — so a shared space opens scoped to\n * just that project, never the whole space — and makes an EXPLICIT read-only vs\n * read-write decision (there is no default). The app never sees the list; it\n * resolves with the single granted mount, or rejects with a {@link SpaceError}\n * (`cancelled`) if declined. The granted scope is enforced host-side: the mount\n * is chroot'd to the project folder and `ro`-limited accordingly, so paths\n * outside the project are unnameable and writes on a `ro` grant fail `EROFS`.\n *\n * A project folder is the macOS-bundle-like unit an app works in inside a space;\n * the host records which app a folder belongs to (a `.immediately.run/` sidecar),\n * so the picker can surface the app's own projects or let the user create a new\n * one. Observe the granted access via {@link SandboxMount.mode}.\n *\n * Backend-general (§3.5): the picker offers whatever mounts the user has (today,\n * their spaces). Returns the granted mount by its universal id.\n */\nexport const requestMount = (): Promise<SandboxMount> =>\n  requestMountInternal('request', {});\n\n/** Prompt the user to grant a mount, returning the granted {@link SandboxMount}.\n *  @deprecated renamed to {@link requestMount} (backend-general, §3.5). */\nexport const requestSpace = requestMount;\n\n// ── content references (plan 12 §E / FILE_SHARING §7) ────────────────────────\n\n/**\n * Build a persisted CONTENT REFERENCE to a file in a mount — a `{mountId, relPath}`\n * pointer your app serializes into ITS OWN content (a board's JSON, an MDX file's\n * frontmatter, an album manifest — the platform doesn't dictate the container) so a\n * later viewer can resolve it. It is exactly the §5.7 {@link capFile} shape: ONE\n * capability, two delivery modes — runtime delegation (a task param, authorized by\n * the caller) vs a durable reference (authorized per-viewer by {@link resolveContentRef}).\n * `relPath` is BACKEND-NATURAL, so the reference resolves to the SAME path for every\n * viewer. Cross-app/cross-project references default to `ro`.\n *\n *   const ref = makeContentRef({ mountId: 'space:ACME', relPath: 'office-seating/desk.mdx' }, { mode: 'ro' });\n */\nexport const makeContentRef = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): FileCap => ({ $cap: 'file', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\n\n/**\n * Resolve a content reference your app found in content it ALREADY holds\n * (FILE_SHARING §7 / UI_AS_APPS §8.7; \"plan 12 §E\"). This is a RELAY, not a\n * fabrication: the host honors it ONLY when your app\n * already holds a grant to `ref.mountId` (else `forbidden`) — apps follow\n * writer-authored links inside granted content; they cannot name a space from\n * nothing (T27). The host runs a per-VIEWER consent prompt (named via the owning\n * app's project sidecar), and existence is never leaked — a decline and a\n * non-existent path are indistinguishable.\n *\n * On allow, the host APPENDS a read scope for the referenced path to your grant\n * (durable; same §8.15 lifecycle) and returns the STABLE absolute `path` the file\n * is mounted at — identical for every viewer, so a path the author stored resolves\n * the same for you. Read it through the `fs` module at that path. Rejects with a\n * {@link SpaceError}: `forbidden` (you don't hold the referenced mount) or\n * `cancelled` (the viewer declined / the path doesn't exist — no oracle).\n *\n *   const { path } = await resolveContentRef(ref);\n *   const text = await fs.promises.readFile(path, 'utf8');\n */\nexport const resolveContentRef = async (ref: FileCap): Promise<{ path: string }> => {\n  const path = await request<string>('resolveRef', { ref });\n  return { path };\n};\n\n/**\n * Resolve a BATCH of content references in ONE consent round (FILE_SHARING §7 /\n * UI_AS_APPS §8.7; \"plan 12 §E\"). When a\n * board opens with several embedded references, pass them all here: the host\n * coalesces them into a SINGLE consent prompt listing every target, instead of one\n * prompt per reference. Same relay gate and per-viewer semantics as\n * {@link resolveContentRef} (each ref's mount must already be held), applied to the\n * whole set — it is all-or-nothing: the user allows the batch or declines it.\n *\n * Resolves `{ paths }` with the STABLE absolute path of each ref, in input order.\n * Rejects with a {@link SpaceError}: `forbidden` (a referenced mount isn't held) or\n * `cancelled` (the viewer declined).\n *\n *   const { paths } = await resolveContentRefs(board.references);\n */\nexport const resolveContentRefs = async (refs: FileCap[]): Promise<{ paths: string[] }> => {\n  const paths = await request<string[]>('resolveRefs', { refs });\n  return { paths };\n};\n\n// ---------------------------------------------------------------------------\n// Settings — the per-user \"~/.config\"-style space (UI_AS_APPS_SPEC §3.3/§3.5/§8.2).\n// Each app gets its OWN settings subdir, auto-provisioned and chroot'd by the host\n// (no dialog, no powerbox). Read/write it through the returned mount's filesystem\n// port — there is deliberately no key/value get/set API; settings are just files.\n// ---------------------------------------------------------------------------\n\n// Issue a `protocol-settings` request, unwrapping {ok,data} and throwing a typed\n// SpaceError on failure (mirrors `request` for the spaces surface).\nconst settingsRequest = async <T = unknown>(\n  method: string,\n  query: Record<string, unknown> = {},\n): Promise<T> => {\n  const res = (await protocolRequest('settings', method, [query])) as SpaceResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'settings request failed') as SpaceError;\n    err.code = (res?.code as SpaceError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Mount this app's per-user settings — a private `~/.config`-style filesystem,\n * auto-provisioned for the signed-in user and isolated to THIS app (the host\n * chroots it; a different app can never name it). Read/write config files through\n * the returned mount. Rejects with a {@link SpaceError} (`auth-required`) when\n * signed out. Capability: baseline `settings:app`.\n */\nexport const openSettings = async (): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('open');\n  // The host has already accepted the request and announced the mount, so this\n  // normally resolves on the initial replay. Bounded anyway: an unbounded wait\n  // here turns any delivery failure into a promise that never settles, and every\n  // caller of `openSettings()` is doing it to reach durable state — so the app\n  // just quietly loses that state with nothing to report.\n  return waitForMount({ id: mount.id ?? mount.path }, SETTINGS_MOUNT_TIMEOUT_MS);\n};\n\n/** How long `openSettings()` waits for the host to deliver the mount it just\n *  agreed to create. Generous — this is a hang-breaker, not a latency budget. */\nconst SETTINGS_MOUNT_TIMEOUT_MS = 15_000;\n\n/**\n * One-time SEED of this app's settings from the parent it declares as `forkOf`\n * (its `package.json` `immediately.run.forkOf`) — so a fork inherits your\n * preferences from the original app (UI_AS_APPS_SPEC §3.4). The host asks the user\n * to confirm (a full consent when the apps have different owners, a light confirm\n * when the same owner publishes both) and copies the parent's settings into this\n * app's own subdir, skipping any file you already have. Non-throwing: resolves\n * `{ ok:false, code }` on decline (`cancelled`), no declared parent (`forbidden`),\n * or signed-out (`auth-required`). After `{ ok:true }`, read {@link openSettings}.\n * Capability: baseline `settings:fork`.\n */\nexport const importSettingsFromParent = async (): Promise<\n  { ok: true; copied: number } | { ok: false; code: string }\n> => {\n  try {\n    const data = await settingsRequest<{ copied: number }>('importFromParent');\n    return { ok: true, copied: data.copied };\n  } catch (e) {\n    return { ok: false, code: (e as SpaceError).code ?? 'unknown' };\n  }\n};\n\n/**\n * Mount ANOTHER app's per-user settings by its `appKey` — the elevated \"file\n * commander\" surface. Rejects `forbidden` unless this app holds the first-party-\n * only `settings:all` capability. Most apps want {@link openSettings} instead.\n */\nexport const openSettingsOf = async (appKey: string): Promise<SandboxMount> => {\n  const mount = await settingsRequest<SandboxMount>('openOf', { appKey });\n  return waitForMount({ id: mount.id ?? mount.path });\n};\n\n/**\n * List every app that has per-user settings — the elevated \"file commander\"\n * enumeration. Pair with {@link openSettingsOf} to mount any of them. Rejects\n * `forbidden` unless this app holds the first-party-only `settings:all`.\n */\nexport const listSettingsApps = (): Promise<string[]> =>\n  settingsRequest<string[]>('list');\n\n/** Create a brand-new, empty platform-hosted space. The app reaches it (or any\n *  other space) afterward through the {@link requestMount} powerbox or\n *  {@link mountSpace}; there is no implicit per-app binding. */\nexport const createSpace = (\n  opts: { name?: string } = {}\n): Promise<SandboxMount> => requestMountInternal('create', opts);\n\n/** List spaces you can access — all of them, or just those bound to this app. */\nexport const listSpaces = (opts: { app?: boolean } = {}): Promise<SpaceInfo[]> =>\n  request<SpaceInfo[]>('list', opts);\n\n/** Release a mounted space (stops its listener on the host). */\nexport const unmountSpace = async (query: { spaceId: string }): Promise<void> => {\n  await request('unmount', query);\n};\n\n// ---------------------------------------------------------------------------\n// Space management (the space-manager app) — UI_AS_APPS_SPEC §5.2. These are\n// ELEVATED: enumerating all the user's spaces is `spaces:user`; mutating\n// membership (share/unshare/setRole) and resolving handles is `spaces:admin`.\n// The host enforces the owner-lockout invariant (a space always keeps an owner,\n// T41) and rate-limits handle lookups (L1); the OAuth/identity token never\n// crosses to the app.\n// ---------------------------------------------------------------------------\n\n/** A collaborator's role on a shared space: full `owner`, read-write `writer`, or read-only `reader`. */\nexport type Role = 'owner' | 'writer' | 'reader';\n\n/** A member of a space (for the share/manage UI). */\nexport interface Member {\n  /**\n   * The **grantee** — `user:{uid}` | `group:{gid}`. This is the canonical name\n   * (core_concepts §4: \"principal\" is reserved for the authority context; a space\n   * member is a *grantee*). The host populates this on every member row.\n   */\n  grantee: string;\n  /**\n   * @deprecated Use {@link Member.grantee}. Kept as an alias (same value) for\n   * back-compat during the `principal`→`grantee` migration; will be removed in a\n   * future major. The host still populates both.\n   */\n  principal: string;\n  role: Role;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** A handle resolved to a principal (handle → who). */\nexport interface ResolvedUser {\n  uid: string;\n  login: string;\n  avatarUrl?: string;\n}\n\n/** A pending invitation to a space (pull-based sharing, FILE_SHARING_SPEC §6.4).\n *  It grants NO access until accepted — the recipient accepts it from their inbox\n *  ({@link listMyInvites} → {@link acceptInvite}), materializing membership. The\n *  display fields (`name`/`login`/`avatarUrl`) are untrusted for rendering. */\nexport interface Invite {\n  spaceId: string;\n  /** The invitee's uid — carried so the owner's pending list can\n   *  {@link revokeInvite}(spaceId, uid). */\n  uid: string;\n  role: Role;\n  owner: string;\n  name?: string;\n  invitedBy: string;\n  /** epoch ms (server-stamped); absent until the write settles. */\n  invitedAt?: number;\n  login?: string;\n  avatarUrl?: string;\n}\n\n/** Enumerate ALL the user's spaces (not just this app's) — `spaces:user`. */\nexport const listAllSpaces = (): Promise<SpaceInfo[]> => request<SpaceInfo[]>('listAll', {});\n\n/** Read a space's members one-shot — `spaces:admin`. */\nexport const getSpaceMembers = (spaceId: string): Promise<Member[]> =>\n  request<Member[]>('members', { spaceId });\n\n/** Invite a user (by provider handle) to a space at a role — `spaces:admin`. The\n *  host resolves the handle, so the app never sees other users' uids except the one\n *  it invited. Pull-based (FILE_SHARING_SPEC §6.4): this writes an INVITATION, not\n *  membership — the recipient must {@link acceptInvite}. Re-inviting an already-\n *  invited/member user is idempotent. */\nexport const inviteToSpace = async (spaceId: string, login: string, role: Role): Promise<void> => {\n  await request('invite', { spaceId, login, role });\n};\n\n/** The owner's outstanding invitations for a space — `spaces:admin`. */\nexport const listPendingInvites = (spaceId: string): Promise<Invite[]> =>\n  request<Invite[]>('pendingInvites', { spaceId });\n\n/** Withdraw a pending invitation (distinct from {@link unshareSpace}, which removes\n *  an ACCEPTED member) — `spaces:admin`. */\nexport const revokeInvite = async (spaceId: string, uid: string): Promise<void> => {\n  await request('revokeInvite', { spaceId, uid });\n};\n\n/** The caller's OWN invitation inbox — `spaces:user`. */\nexport const listMyInvites = (): Promise<Invite[]> => request<Invite[]>('listInvites', {});\n\n/** Accept an invitation: materialize your membership at the invited role and clear\n *  the invite — `spaces:user`. An invitation the caller doesn't hold rejects with\n *  `forbidden` (indistinguishable from a nonexistent space; no existence oracle). */\nexport const acceptInvite = async (spaceId: string): Promise<void> => {\n  await request('acceptInvite', { spaceId });\n};\n\n/** Decline (dismiss) an invitation from your inbox; writes no membership —\n *  `spaces:user`. */\nexport const declineInvite = async (spaceId: string): Promise<void> => {\n  await request('declineInvite', { spaceId });\n};\n\n// The live invitations inbox (FILE_SHARING §6.4/§9.8): the host pushes the caller's\n// current invitations on change and replays on register-frame; gated `spaces:user`.\n// So an invite that arrives (or an accepted/declined one leaving) reflects within one\n// snapshot — no poll. Mirrors the host's `invitations`/`request-invitations` wiring.\nconst invitesChannel = createPushChannel<Invite[]>({\n  pushType: 'invitations',\n  requestType: 'request-invitations',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.invites) ? (msg.invites as Invite[]) : undefined),\n});\n\n/** The caller's current invitations (`spaces:user`). One-off read; use\n *  {@link onInvitesChange}/{@link useInvites} to react live. */\nexport const getInvites = (): Invite[] => invitesChannel.get();\n\n/** Subscribe to invitation-inbox changes (arrived / accepted / declined). Invoked\n *  immediately with the current list, then on every change. Returns an unsubscribe. */\nexport const onInvitesChange = (listener: (invites: Invite[]) => void): (() => void) =>\n  invitesChannel.onChange(listener);\n\n/** React hook returning the caller's live invitation inbox, re-rendering on change\n *  (the space-manager Invitations inbox, §9.8). */\nexport const useInvites = (): Invite[] => invitesChannel.use();\n\n/** Remove a member from a space — `spaces:admin`. Refused if it would orphan the\n *  space (owner-lockout, T41). */\nexport const unshareSpace = async (spaceId: string, uid: string): Promise<void> => {\n  await request('unshare', { spaceId, uid });\n};\n\n/** Change a member's role — `spaces:admin`. Refused if it would drop the sole\n *  owner (owner-lockout, T41). */\nexport const setSpaceRole = async (spaceId: string, uid: string, role: Role): Promise<void> => {\n  await request('setRole', { spaceId, uid, role });\n};\n\n/** Resolve a provider handle to a principal (for the invite flow) — `spaces:admin`,\n *  rate-limited host-side. */\nexport const lookupUser = (login: string): Promise<ResolvedUser> =>\n  request<ResolvedUser>('lookupUser', { login });\n\n/** One durable grant an app holds, for the §8.11 capability audit view. */\nexport interface GrantRecord {\n  /** The app's provider-qualified **program** identity (AA-01 `appKey`). The DEFAULT\n   *  program keys to the bare `provider__namespace__repository`; a NAMED mini-app\n   *  appends a fourth `enc()`-escaped component (`provider__namespace__repository__name`)\n   *  so its grants isolate from the repo's other programs. Host-supplied — the app\n   *  never builds this key. */\n  appKey: string;\n  spaceId: string;\n  /** Universal mount id (§3.5). */\n  mountId: string;\n  subtree?: string;\n  mode: 'ro' | 'rw';\n  name?: string;\n}\n\n/** Enumerate every (app, mount) grant the user holds — the audit view\n *  (§8.11). Elevated `spaces:admin`. */\nexport const listGrants = (): Promise<GrantRecord[]> => request<GrantRecord[]>('grants', {});\n\n/** Revoke one app's grant on a space — durable (the app can't re-mount) plus a\n *  best-effort live teardown. Elevated `spaces:admin`. */\nexport const revokeGrant = async (appKey: string, spaceId: string): Promise<void> => {\n  await request('revokeGrant', { appKey, spaceId });\n};\n"],"mappings":"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","names":["mount"]}

package/dist/version.cjs

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

package/dist/version.cjs.map

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

package/dist/version.d.cts

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

package/dist/version.d.ts

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

package/dist/version.js

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

package/dist/version.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",