@immediately-run/sdk 0.1.5 → 0.2.1

package/dist/mounts.cjs

@@ -21,11 +21,20 @@ __export(mounts_exports, {
   createSpace: () => createSpace,
   findMount: () => findMount,
   getMounts: () => getMounts,
+  getSpaceMembers: () => getSpaceMembers,
+  listAllSpaces: () => listAllSpaces,
   listSpaces: () => listSpaces,
+  lookupUser: () => lookupUser,
+  mount: () => mount,
   mountSpace: () => mountSpace,
   onMountsChange: () => onMountsChange,
   openAppSpace: () => openAppSpace,
+  requestMount: () => requestMount,
+  requestSpace: () => requestSpace,
+  setSpaceRole: () => setSpaceRole,
+  shareSpace: () => shareSpace,
   unmountSpace: () => unmountSpace,
+  unshareSpace: () => unshareSpace,
   useMounts: () => useMounts,
   waitForMount: () => waitForMount
 });
@@ -35,7 +44,7 @@ var import_sandboxUtils = require("./sandboxUtils");
 const mountService = () => {
   return module.evaluation.module.bundler.mounts;
 };
-const matches = (mount, query) => (query.type === void 0 || mount.type === query.type) && (query.id === void 0 || mount.id === query.id) && (query.path === void 0 || mount.path === query.path);
+const matches = (mount2, query) => (query.type === void 0 || mount2.type === query.type) && (query.id === void 0 || mount2.id === query.id) && (query.path === void 0 || mount2.path === query.path);
 const getMounts = () => mountService().getMounts();
 const findMount = (query) => getMounts().find((m) => matches(m, query));
 const onMountsChange = (listener) => {
@@ -65,24 +74,51 @@ const request = async (method, query = {}) => {
   }
   return res.data;
 };
-const awaitReady = (descriptor) => waitForMount({ id: descriptor.id ?? descriptor.path });
-const openAppSpace = async (slot = "default") => awaitReady(await request("open", { slot }));
-const mountSpace = async (query) => awaitReady(await request("mount", query));
-const createSpace = async (opts = {}) => awaitReady(await request("create", opts));
-const listSpaces = async (opts = {}) => await request("list", opts);
+const requestMountInternal = async (method, query) => {
+  const mount2 = await request(method, query);
+  return waitForMount({ id: mount2.id ?? mount2.path });
+};
+const openAppSpace = (slot = "default") => requestMountInternal("open", { slot });
+const mount = (mountId) => requestMountInternal("mount", { mount: mountId });
+const mountSpace = (query) => mount(`space:${query.spaceId}`);
+const requestMount = () => requestMountInternal("request", {});
+const requestSpace = requestMount;
+const createSpace = (opts = {}) => requestMountInternal("create", opts);
+const listSpaces = (opts = {}) => request("list", opts);
 const unmountSpace = async (query) => {
   await request("unmount", query);
 };
+const listAllSpaces = () => request("listAll", {});
+const getSpaceMembers = (spaceId) => request("members", { spaceId });
+const shareSpace = async (spaceId, login, role) => {
+  await request("share", { spaceId, login, role });
+};
+const unshareSpace = async (spaceId, uid) => {
+  await request("unshare", { spaceId, uid });
+};
+const setSpaceRole = async (spaceId, uid, role) => {
+  await request("setRole", { spaceId, uid, role });
+};
+const lookupUser = (login) => request("lookupUser", { login });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createSpace,
   findMount,
   getMounts,
+  getSpaceMembers,
+  listAllSpaces,
   listSpaces,
+  lookupUser,
+  mount,
   mountSpace,
   onMountsChange,
   openAppSpace,
+  requestMount,
+  requestSpace,
+  setSpaceRole,
+  shareSpace,
   unmountSpace,
+  unshareSpace,
   useMounts,
   waitForMount
 });

package/dist/mounts.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openAppSpace} / {@link mountSpace} to ask\n * the host to mount a Firestore-backed \"space\"; it appears at `/spaces/{id}`.\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\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(listener: (mounts: SandboxMount[]) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler` is the sandbox bundler injected into the\n// evaluation context (same path the other SDK helpers reach for `messageBus`).\nconst mountService = (): MountService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.mounts;\n};\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. */\nexport type MountQuery = { type?: string; id?: string; path?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  (query.type === undefined || mount.type === query.type) &&\n  (query.id === undefined || mount.id === query.id) &&\n  (query.path === undefined || mount.path === query.path);\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 */\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, then again on every change. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (listener: (mounts: SandboxMount[]) => void): (() => 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// 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: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unknown';\n}\n\ntype SpaceResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst request = async (method: string, query: Record<string, unknown> = {}): Promise<unknown> => {\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;\n};\n\n// The host announces the mount (`mount-add`) separately from the protocol reply,\n// so wait until the ZenFS port mount is actually registered before returning —\n// otherwise an immediate read could race the mount.\nconst awaitReady = (descriptor: SandboxMount): Promise<SandboxMount> =>\n  waitForMount({ id: descriptor.id ?? descriptor.path });\n\n/**\n * Open this app's workspace for the signed-in user (the zero-config path). The\n * `slot` names which workspace (default `'default'`); pass distinct slots for\n * multiple filesystems in one app. On a missing slot the host shows a\n * create-or-pick dialog. Rejects with a {@link SpaceError} (`.code`) on cancel.\n */\nexport const openAppSpace = async (slot = 'default'): Promise<SandboxMount> =>\n  awaitReady((await request('open', { slot })) as SandboxMount);\n\n/** Mount a specific space by id (e.g. one shared with you, or from a link). */\nexport const mountSpace = async (query: { spaceId: string }): Promise<SandboxMount> =>\n  awaitReady((await request('mount', query)) as SandboxMount);\n\n/** Create a brand-new space, optionally binding it to this app (a slot). */\nexport const createSpace = async (\n  opts: { name?: string; slot?: string; bindToApp?: boolean } = {}\n): Promise<SandboxMount> => awaitReady((await request('create', opts)) as SandboxMount);\n\n/** List spaces you can access — all of them, or just those bound to this app. */\nexport const listSpaces = async (opts: { app?: boolean } = {}): Promise<SpaceInfo[]> =>\n  (await request('list', opts)) as SpaceInfo[];\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"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AACpC,0BAAgC;AA0BhC,MAAM,eAAe,MAAoB;AAEvC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAKA,MAAM,UAAU,CAAC,OAAqB,WACnC,MAAM,SAAS,UAAa,MAAM,SAAS,MAAM,UACjD,MAAM,OAAO,UAAa,MAAM,OAAO,MAAM,QAC7C,MAAM,SAAS,UAAa,MAAM,SAAS,MAAM;AAM7C,MAAM,YAAY,MAAsB,aAAa,EAAE,UAAU;AAGjE,MAAM,YAAY,CAAC,UACxB,UAAU,EAAE,KAAK,CAAC,MAAM,QAAQ,GAAG,KAAK,CAAC;AAMpC,MAAM,iBAAiB,CAAC,aAA6D;AAC1F,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;AA0BA,MAAM,UAAU,OAAO,QAAgB,QAAiC,CAAC,MAAwB;AAC/F,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,aAAa,CAAC,eAClB,aAAa,EAAE,IAAI,WAAW,MAAM,WAAW,KAAK,CAAC;AAQhD,MAAM,eAAe,OAAO,OAAO,cACxC,WAAY,MAAM,QAAQ,QAAQ,EAAE,KAAK,CAAC,CAAkB;AAGvD,MAAM,aAAa,OAAO,UAC/B,WAAY,MAAM,QAAQ,SAAS,KAAK,CAAkB;AAGrD,MAAM,cAAc,OACzB,OAA8D,CAAC,MACrC,WAAY,MAAM,QAAQ,UAAU,IAAI,CAAkB;AAG/E,MAAM,aAAa,OAAO,OAA0B,CAAC,MACzD,MAAM,QAAQ,QAAQ,IAAI;AAGtB,MAAM,eAAe,OAAO,UAA8C;AAC/E,QAAM,QAAQ,WAAW,KAAK;AAChC;","names":[]}
+{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openAppSpace} / {@link mountSpace} to ask\n * the host to mount a Firestore-backed \"space\"; it appears at `/spaces/{id}`.\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\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(listener: (mounts: SandboxMount[]) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler` is the sandbox bundler injected into the\n// evaluation context (same path the other SDK helpers reach for `messageBus`).\nconst mountService = (): MountService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.mounts;\n};\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. */\nexport type MountQuery = { type?: string; id?: string; path?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  (query.type === undefined || mount.type === query.type) &&\n  (query.id === undefined || mount.id === query.id) &&\n  (query.path === undefined || mount.path === query.path);\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 */\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, then again on every change. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (listener: (mounts: SandboxMount[]) => void): (() => 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// 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 * Open this app's workspace for the signed-in user (the zero-config path). The\n * `slot` names which workspace (default `'default'`); pass distinct slots for\n * multiple filesystems in one app. On a missing slot the host shows a\n * create-or-pick dialog. Rejects with a {@link SpaceError} (`.code`) on cancel.\n */\nexport const openAppSpace = (slot = 'default'): Promise<SandboxMount> =>\n  requestMountInternal('open', { slot });\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 mounts and the access choice (which mount,\n * an optional subtree, read-only vs read-write); the USER picks or declines. The\n * app never sees the list — it resolves with the single granted mount, or rejects\n * with a {@link SpaceError} (`cancelled`) if declined. The granted scope is\n * enforced host-side: the mount is chroot'd / `ro`-limited accordingly.\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/** @deprecated renamed to {@link requestMount} (backend-general, §3.5). */\nexport const requestSpace = requestMount;\n\n/** Create a brand-new space, optionally binding it to this app (a slot). */\nexport const createSpace = (\n  opts: { name?: string; slot?: string; bindToApp?: boolean } = {}\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\nexport type Role = 'owner' | 'writer' | 'reader';\n\n/** A member of a space (for the share/manage UI). */\nexport interface Member {\n  /** `user:{uid}` | `group:{gid}`. */\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/** 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\n *  one it invited. */\nexport const shareSpace = async (spaceId: string, login: string, role: Role): Promise<void> => {\n  await request('share', { spaceId, login, role });\n};\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"],"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,mBAAoC;AACpC,0BAAgC;AA0BhC,MAAM,eAAe,MAAoB;AAEvC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAKA,MAAM,UAAU,CAACA,QAAqB,WACnC,MAAM,SAAS,UAAaA,OAAM,SAAS,MAAM,UACjD,MAAM,OAAO,UAAaA,OAAM,OAAO,MAAM,QAC7C,MAAM,SAAS,UAAaA,OAAM,SAAS,MAAM;AAM7C,MAAM,YAAY,MAAsB,aAAa,EAAE,UAAU;AAGjE,MAAM,YAAY,CAAC,UACxB,UAAU,EAAE,KAAK,CAAC,MAAM,QAAQ,GAAG,KAAK,CAAC;AAMpC,MAAM,iBAAiB,CAAC,aAA6D;AAC1F,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;AAkCA,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,eAAe,CAAC,OAAO,cAClC,qBAAqB,QAAQ,EAAE,KAAK,CAAC;AAQhC,MAAM,QAAQ,CAAC,YACpB,qBAAqB,SAAS,EAAE,OAAO,QAAQ,CAAC;AAI3C,MAAM,aAAa,CAAC,UACzB,MAAM,SAAS,MAAM,OAAO,EAAE;AAazB,MAAM,eAAe,MAC1B,qBAAqB,WAAW,CAAC,CAAC;AAG7B,MAAM,eAAe;AAGrB,MAAM,cAAc,CACzB,OAA8D,CAAC,MACrC,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;AA8BO,MAAM,gBAAgB,MAA4B,QAAqB,WAAW,CAAC,CAAC;AAGpF,MAAM,kBAAkB,CAAC,YAC9B,QAAkB,WAAW,EAAE,QAAQ,CAAC;AAKnC,MAAM,aAAa,OAAO,SAAiB,OAAe,SAA8B;AAC7F,QAAM,QAAQ,SAAS,EAAE,SAAS,OAAO,KAAK,CAAC;AACjD;AAIO,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;","names":["mount"]}

package/dist/mounts.d.cts

@@ -49,7 +49,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' | 'unknown';
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unsupported-scheme' | 'unknown';
 }
 /**
  * Open this app's workspace for the signed-in user (the zero-config path). The
@@ -58,10 +58,32 @@ interface SpaceError extends Error {
  * create-or-pick dialog. Rejects with a {@link SpaceError} (`.code`) on cancel.
  */
 declare const openAppSpace: (slot?: string) => Promise<SandboxMount>;
-/** Mount a specific space by id (e.g. one shared with you, or from a link). */
+/**
+ * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —
+ * `scheme:locator`, e.g. `space:{spaceId}` or `github:owner/repo@ref`. Backend-blind:
+ * the host resolves the scheme. A scheme with no resolver rejects with
+ * {@link SpaceError} `unsupported-scheme`.
+ */
+declare const mount: (mountId: string) => Promise<SandboxMount>;
+/** Mount a specific space by id (e.g. one shared with you, or from a link). A thin
+ *  shim over {@link mount} with the `space:` scheme. */
 declare const mountSpace: (query: {
     spaceId: string;
 }) => Promise<SandboxMount>;
+/**
+ * Ask the user to grant a filesystem to this app — the §8.6 powerbox. The app
+ * asks; the HOST shows the user their mounts and the access choice (which mount,
+ * an optional subtree, read-only vs read-write); the USER picks or declines. The
+ * app never sees the list — it resolves with the single granted mount, or rejects
+ * with a {@link SpaceError} (`cancelled`) if declined. The granted scope is
+ * enforced host-side: the mount is chroot'd / `ro`-limited accordingly.
+ *
+ * Backend-general (§3.5): the picker offers whatever mounts the user has (today,
+ * their spaces). Returns the granted mount by its universal id.
+ */
+declare const requestMount: () => Promise<SandboxMount>;
+/** @deprecated renamed to {@link requestMount} (backend-general, §3.5). */
+declare const requestSpace: () => Promise<SandboxMount>;
 /** Create a brand-new space, optionally binding it to this app (a slot). */
 declare const createSpace: (opts?: {
     name?: string;
@@ -76,5 +98,37 @@ declare const listSpaces: (opts?: {
 declare const unmountSpace: (query: {
     spaceId: string;
 }) => Promise<void>;
+type Role = 'owner' | 'writer' | 'reader';
+/** A member of a space (for the share/manage UI). */
+interface Member {
+    /** `user:{uid}` | `group:{gid}`. */
+    principal: string;
+    role: Role;
+    login?: string;
+    avatarUrl?: string;
+}
+/** A handle resolved to a principal (handle → who). */
+interface ResolvedUser {
+    uid: string;
+    login: string;
+    avatarUrl?: string;
+}
+/** Enumerate ALL the user's spaces (not just this app's) — `spaces:user`. */
+declare const listAllSpaces: () => Promise<SpaceInfo[]>;
+/** Read a space's members one-shot — `spaces:admin`. */
+declare const getSpaceMembers: (spaceId: string) => Promise<Member[]>;
+/** Invite a user (by provider handle) to a space at a role — `spaces:admin`. The
+ *  host resolves the handle, so the app never sees other users' uids except the
+ *  one it invited. */
+declare const shareSpace: (spaceId: string, login: string, role: Role) => Promise<void>;
+/** Remove a member from a space — `spaces:admin`. Refused if it would orphan the
+ *  space (owner-lockout, T41). */
+declare const unshareSpace: (spaceId: string, uid: string) => Promise<void>;
+/** Change a member's role — `spaces:admin`. Refused if it would drop the sole
+ *  owner (owner-lockout, T41). */
+declare const setSpaceRole: (spaceId: string, uid: string, role: Role) => Promise<void>;
+/** Resolve a provider handle to a principal (for the invite flow) — `spaces:admin`,
+ *  rate-limited host-side. */
+declare const lookupUser: (login: string) => Promise<ResolvedUser>;
 
-export { type MountQuery, type SandboxMount, type SpaceError, type SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount };
+export { type Member, type MountQuery, type ResolvedUser, type Role, type SandboxMount, type SpaceError, type SpaceInfo, createSpace, findMount, getMounts, getSpaceMembers, listAllSpaces, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount };

package/dist/mounts.d.ts

@@ -49,7 +49,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' | 'unknown';
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unsupported-scheme' | 'unknown';
 }
 /**
  * Open this app's workspace for the signed-in user (the zero-config path). The
@@ -58,10 +58,32 @@ interface SpaceError extends Error {
  * create-or-pick dialog. Rejects with a {@link SpaceError} (`.code`) on cancel.
  */
 declare const openAppSpace: (slot?: string) => Promise<SandboxMount>;
-/** Mount a specific space by id (e.g. one shared with you, or from a link). */
+/**
+ * Mount a filesystem by its **universal mount id** (UI_AS_APPS_SPEC §3.5) —
+ * `scheme:locator`, e.g. `space:{spaceId}` or `github:owner/repo@ref`. Backend-blind:
+ * the host resolves the scheme. A scheme with no resolver rejects with
+ * {@link SpaceError} `unsupported-scheme`.
+ */
+declare const mount: (mountId: string) => Promise<SandboxMount>;
+/** Mount a specific space by id (e.g. one shared with you, or from a link). A thin
+ *  shim over {@link mount} with the `space:` scheme. */
 declare const mountSpace: (query: {
     spaceId: string;
 }) => Promise<SandboxMount>;
+/**
+ * Ask the user to grant a filesystem to this app — the §8.6 powerbox. The app
+ * asks; the HOST shows the user their mounts and the access choice (which mount,
+ * an optional subtree, read-only vs read-write); the USER picks or declines. The
+ * app never sees the list — it resolves with the single granted mount, or rejects
+ * with a {@link SpaceError} (`cancelled`) if declined. The granted scope is
+ * enforced host-side: the mount is chroot'd / `ro`-limited accordingly.
+ *
+ * Backend-general (§3.5): the picker offers whatever mounts the user has (today,
+ * their spaces). Returns the granted mount by its universal id.
+ */
+declare const requestMount: () => Promise<SandboxMount>;
+/** @deprecated renamed to {@link requestMount} (backend-general, §3.5). */
+declare const requestSpace: () => Promise<SandboxMount>;
 /** Create a brand-new space, optionally binding it to this app (a slot). */
 declare const createSpace: (opts?: {
     name?: string;
@@ -76,5 +98,37 @@ declare const listSpaces: (opts?: {
 declare const unmountSpace: (query: {
     spaceId: string;
 }) => Promise<void>;
+type Role = 'owner' | 'writer' | 'reader';
+/** A member of a space (for the share/manage UI). */
+interface Member {
+    /** `user:{uid}` | `group:{gid}`. */
+    principal: string;
+    role: Role;
+    login?: string;
+    avatarUrl?: string;
+}
+/** A handle resolved to a principal (handle → who). */
+interface ResolvedUser {
+    uid: string;
+    login: string;
+    avatarUrl?: string;
+}
+/** Enumerate ALL the user's spaces (not just this app's) — `spaces:user`. */
+declare const listAllSpaces: () => Promise<SpaceInfo[]>;
+/** Read a space's members one-shot — `spaces:admin`. */
+declare const getSpaceMembers: (spaceId: string) => Promise<Member[]>;
+/** Invite a user (by provider handle) to a space at a role — `spaces:admin`. The
+ *  host resolves the handle, so the app never sees other users' uids except the
+ *  one it invited. */
+declare const shareSpace: (spaceId: string, login: string, role: Role) => Promise<void>;
+/** Remove a member from a space — `spaces:admin`. Refused if it would orphan the
+ *  space (owner-lockout, T41). */
+declare const unshareSpace: (spaceId: string, uid: string) => Promise<void>;
+/** Change a member's role — `spaces:admin`. Refused if it would drop the sole
+ *  owner (owner-lockout, T41). */
+declare const setSpaceRole: (spaceId: string, uid: string, role: Role) => Promise<void>;
+/** Resolve a provider handle to a principal (for the invite flow) — `spaces:admin`,
+ *  rate-limited host-side. */
+declare const lookupUser: (login: string) => Promise<ResolvedUser>;
 
-export { type MountQuery, type SandboxMount, type SpaceError, type SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount };
+export { type Member, type MountQuery, type ResolvedUser, type Role, type SandboxMount, type SpaceError, type SpaceInfo, createSpace, findMount, getMounts, getSpaceMembers, listAllSpaces, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount };

package/dist/mounts.js

@@ -3,7 +3,7 @@ import { protocolRequest } from "./sandboxUtils";
 const mountService = () => {
   return module.evaluation.module.bundler.mounts;
 };
-const matches = (mount, query) => (query.type === void 0 || mount.type === query.type) && (query.id === void 0 || mount.id === query.id) && (query.path === void 0 || mount.path === query.path);
+const matches = (mount2, query) => (query.type === void 0 || mount2.type === query.type) && (query.id === void 0 || mount2.id === query.id) && (query.path === void 0 || mount2.path === query.path);
 const getMounts = () => mountService().getMounts();
 const findMount = (query) => getMounts().find((m) => matches(m, query));
 const onMountsChange = (listener) => {
@@ -33,23 +33,50 @@ const request = async (method, query = {}) => {
   }
   return res.data;
 };
-const awaitReady = (descriptor) => waitForMount({ id: descriptor.id ?? descriptor.path });
-const openAppSpace = async (slot = "default") => awaitReady(await request("open", { slot }));
-const mountSpace = async (query) => awaitReady(await request("mount", query));
-const createSpace = async (opts = {}) => awaitReady(await request("create", opts));
-const listSpaces = async (opts = {}) => await request("list", opts);
+const requestMountInternal = async (method, query) => {
+  const mount2 = await request(method, query);
+  return waitForMount({ id: mount2.id ?? mount2.path });
+};
+const openAppSpace = (slot = "default") => requestMountInternal("open", { slot });
+const mount = (mountId) => requestMountInternal("mount", { mount: mountId });
+const mountSpace = (query) => mount(`space:${query.spaceId}`);
+const requestMount = () => requestMountInternal("request", {});
+const requestSpace = requestMount;
+const createSpace = (opts = {}) => requestMountInternal("create", opts);
+const listSpaces = (opts = {}) => request("list", opts);
 const unmountSpace = async (query) => {
   await request("unmount", query);
 };
+const listAllSpaces = () => request("listAll", {});
+const getSpaceMembers = (spaceId) => request("members", { spaceId });
+const shareSpace = async (spaceId, login, role) => {
+  await request("share", { spaceId, login, role });
+};
+const unshareSpace = async (spaceId, uid) => {
+  await request("unshare", { spaceId, uid });
+};
+const setSpaceRole = async (spaceId, uid, role) => {
+  await request("setRole", { spaceId, uid, role });
+};
+const lookupUser = (login) => request("lookupUser", { login });
 export {
   createSpace,
   findMount,
   getMounts,
+  getSpaceMembers,
+  listAllSpaces,
   listSpaces,
+  lookupUser,
+  mount,
   mountSpace,
   onMountsChange,
   openAppSpace,
+  requestMount,
+  requestSpace,
+  setSpaceRole,
+  shareSpace,
   unmountSpace,
+  unshareSpace,
   useMounts,
   waitForMount
 };

package/dist/mounts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openAppSpace} / {@link mountSpace} to ask\n * the host to mount a Firestore-backed \"space\"; it appears at `/spaces/{id}`.\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\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(listener: (mounts: SandboxMount[]) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler` is the sandbox bundler injected into the\n// evaluation context (same path the other SDK helpers reach for `messageBus`).\nconst mountService = (): MountService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.mounts;\n};\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. */\nexport type MountQuery = { type?: string; id?: string; path?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  (query.type === undefined || mount.type === query.type) &&\n  (query.id === undefined || mount.id === query.id) &&\n  (query.path === undefined || mount.path === query.path);\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 */\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, then again on every change. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (listener: (mounts: SandboxMount[]) => void): (() => 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// 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: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unknown';\n}\n\ntype SpaceResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst request = async (method: string, query: Record<string, unknown> = {}): Promise<unknown> => {\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;\n};\n\n// The host announces the mount (`mount-add`) separately from the protocol reply,\n// so wait until the ZenFS port mount is actually registered before returning —\n// otherwise an immediate read could race the mount.\nconst awaitReady = (descriptor: SandboxMount): Promise<SandboxMount> =>\n  waitForMount({ id: descriptor.id ?? descriptor.path });\n\n/**\n * Open this app's workspace for the signed-in user (the zero-config path). The\n * `slot` names which workspace (default `'default'`); pass distinct slots for\n * multiple filesystems in one app. On a missing slot the host shows a\n * create-or-pick dialog. Rejects with a {@link SpaceError} (`.code`) on cancel.\n */\nexport const openAppSpace = async (slot = 'default'): Promise<SandboxMount> =>\n  awaitReady((await request('open', { slot })) as SandboxMount);\n\n/** Mount a specific space by id (e.g. one shared with you, or from a link). */\nexport const mountSpace = async (query: { spaceId: string }): Promise<SandboxMount> =>\n  awaitReady((await request('mount', query)) as SandboxMount);\n\n/** Create a brand-new space, optionally binding it to this app (a slot). */\nexport const createSpace = async (\n  opts: { name?: string; slot?: string; bindToApp?: boolean } = {}\n): Promise<SandboxMount> => awaitReady((await request('create', opts)) as SandboxMount);\n\n/** List spaces you can access — all of them, or just those bound to this app. */\nexport const listSpaces = async (opts: { app?: boolean } = {}): Promise<SpaceInfo[]> =>\n  (await request('list', opts)) as SpaceInfo[];\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"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AACpC,SAAS,uBAAuB;AA0BhC,MAAM,eAAe,MAAoB;AAEvC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAKA,MAAM,UAAU,CAAC,OAAqB,WACnC,MAAM,SAAS,UAAa,MAAM,SAAS,MAAM,UACjD,MAAM,OAAO,UAAa,MAAM,OAAO,MAAM,QAC7C,MAAM,SAAS,UAAa,MAAM,SAAS,MAAM;AAM7C,MAAM,YAAY,MAAsB,aAAa,EAAE,UAAU;AAGjE,MAAM,YAAY,CAAC,UACxB,UAAU,EAAE,KAAK,CAAC,MAAM,QAAQ,GAAG,KAAK,CAAC;AAMpC,MAAM,iBAAiB,CAAC,aAA6D;AAC1F,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,IAAI,SAAyB,SAAS;AAC9D,YAAU,MAAM,eAAe,SAAS,GAAG,CAAC,CAAC;AAC7C,SAAO;AACT;AA0BA,MAAM,UAAU,OAAO,QAAgB,QAAiC,CAAC,MAAwB;AAC/F,QAAM,MAAO,MAAM,gBAAgB,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,aAAa,CAAC,eAClB,aAAa,EAAE,IAAI,WAAW,MAAM,WAAW,KAAK,CAAC;AAQhD,MAAM,eAAe,OAAO,OAAO,cACxC,WAAY,MAAM,QAAQ,QAAQ,EAAE,KAAK,CAAC,CAAkB;AAGvD,MAAM,aAAa,OAAO,UAC/B,WAAY,MAAM,QAAQ,SAAS,KAAK,CAAkB;AAGrD,MAAM,cAAc,OACzB,OAA8D,CAAC,MACrC,WAAY,MAAM,QAAQ,UAAU,IAAI,CAAkB;AAG/E,MAAM,aAAa,OAAO,OAA0B,CAAC,MACzD,MAAM,QAAQ,QAAQ,IAAI;AAGtB,MAAM,eAAe,OAAO,UAA8C;AAC/E,QAAM,QAAQ,WAAW,KAAK;AAChC;","names":[]}
+{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear on demand — call {@link openAppSpace} / {@link mountSpace} to ask\n * the host to mount a Firestore-backed \"space\"; it appears at `/spaces/{id}`.\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\ninterface MountService {\n  getMounts(): SandboxMount[];\n  onChange(listener: (mounts: SandboxMount[]) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler` is the sandbox bundler injected into the\n// evaluation context (same path the other SDK helpers reach for `messageBus`).\nconst mountService = (): MountService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.mounts;\n};\n\n/** A predicate-style matcher for {@link findMount} / {@link waitForMount}. */\nexport type MountQuery = { type?: string; id?: string; path?: string };\n\nconst matches = (mount: SandboxMount, query: MountQuery): boolean =>\n  (query.type === undefined || mount.type === query.type) &&\n  (query.id === undefined || mount.id === query.id) &&\n  (query.path === undefined || mount.path === query.path);\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 */\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, then again on every change. Returns an unsubscribe fn.\n */\nexport const onMountsChange = (listener: (mounts: SandboxMount[]) => void): (() => 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// 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 * Open this app's workspace for the signed-in user (the zero-config path). The\n * `slot` names which workspace (default `'default'`); pass distinct slots for\n * multiple filesystems in one app. On a missing slot the host shows a\n * create-or-pick dialog. Rejects with a {@link SpaceError} (`.code`) on cancel.\n */\nexport const openAppSpace = (slot = 'default'): Promise<SandboxMount> =>\n  requestMountInternal('open', { slot });\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 mounts and the access choice (which mount,\n * an optional subtree, read-only vs read-write); the USER picks or declines. The\n * app never sees the list — it resolves with the single granted mount, or rejects\n * with a {@link SpaceError} (`cancelled`) if declined. The granted scope is\n * enforced host-side: the mount is chroot'd / `ro`-limited accordingly.\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/** @deprecated renamed to {@link requestMount} (backend-general, §3.5). */\nexport const requestSpace = requestMount;\n\n/** Create a brand-new space, optionally binding it to this app (a slot). */\nexport const createSpace = (\n  opts: { name?: string; slot?: string; bindToApp?: boolean } = {}\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\nexport type Role = 'owner' | 'writer' | 'reader';\n\n/** A member of a space (for the share/manage UI). */\nexport interface Member {\n  /** `user:{uid}` | `group:{gid}`. */\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/** 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\n *  one it invited. */\nexport const shareSpace = async (spaceId: string, login: string, role: Role): Promise<void> => {\n  await request('share', { spaceId, login, role });\n};\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"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AACpC,SAAS,uBAAuB;AA0BhC,MAAM,eAAe,MAAoB;AAEvC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAKA,MAAM,UAAU,CAACA,QAAqB,WACnC,MAAM,SAAS,UAAaA,OAAM,SAAS,MAAM,UACjD,MAAM,OAAO,UAAaA,OAAM,OAAO,MAAM,QAC7C,MAAM,SAAS,UAAaA,OAAM,SAAS,MAAM;AAM7C,MAAM,YAAY,MAAsB,aAAa,EAAE,UAAU;AAGjE,MAAM,YAAY,CAAC,UACxB,UAAU,EAAE,KAAK,CAAC,MAAM,QAAQ,GAAG,KAAK,CAAC;AAMpC,MAAM,iBAAiB,CAAC,aAA6D;AAC1F,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,IAAI,SAAyB,SAAS;AAC9D,YAAU,MAAM,eAAe,SAAS,GAAG,CAAC,CAAC;AAC7C,SAAO;AACT;AAkCA,MAAM,UAAU,OACd,QACA,QAAiC,CAAC,MACnB;AACf,QAAM,MAAO,MAAM,gBAAgB,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,eAAe,CAAC,OAAO,cAClC,qBAAqB,QAAQ,EAAE,KAAK,CAAC;AAQhC,MAAM,QAAQ,CAAC,YACpB,qBAAqB,SAAS,EAAE,OAAO,QAAQ,CAAC;AAI3C,MAAM,aAAa,CAAC,UACzB,MAAM,SAAS,MAAM,OAAO,EAAE;AAazB,MAAM,eAAe,MAC1B,qBAAqB,WAAW,CAAC,CAAC;AAG7B,MAAM,eAAe;AAGrB,MAAM,cAAc,CACzB,OAA8D,CAAC,MACrC,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;AA8BO,MAAM,gBAAgB,MAA4B,QAAqB,WAAW,CAAC,CAAC;AAGpF,MAAM,kBAAkB,CAAC,YAC9B,QAAkB,WAAW,EAAE,QAAQ,CAAC;AAKnC,MAAM,aAAa,OAAO,SAAiB,OAAe,SAA8B;AAC7F,QAAM,QAAQ,SAAS,EAAE,SAAS,OAAO,KAAK,CAAC;AACjD;AAIO,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;","names":["mount"]}

package/dist/protocolStream.cjs

@@ -0,0 +1,87 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var protocolStream_exports = {};
+__export(protocolStream_exports, {
+  StreamError: () => StreamError,
+  consumeStream: () => consumeStream,
+  protocolStream: () => protocolStream
+});
+module.exports = __toCommonJS(protocolStream_exports);
+var import_sandboxUtils = require("./sandboxUtils");
+class StreamError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "StreamError";
+    this.code = code;
+  }
+}
+let streamCounter = 0;
+const nextMsgId = () => {
+  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;
+  return streamCounter;
+};
+async function* consumeStream(transport, type, method, params, msgId = nextMsgId()) {
+  const queue = [];
+  let wake = null;
+  const push = (frame) => {
+    queue.push(frame);
+    const w = wake;
+    wake = null;
+    w?.();
+  };
+  const unsubscribe = transport.subscribe(type, (msg) => {
+    if (msg.msgId !== msgId || !msg.stream) return;
+    push(msg.stream);
+  });
+  try {
+    transport.send({ type, method, params, msgId, stream: true });
+    while (true) {
+      if (queue.length === 0) {
+        await new Promise((resolve) => {
+          wake = resolve;
+        });
+        continue;
+      }
+      const frame = queue.shift();
+      if (frame.kind === "event") {
+        yield frame.value;
+      } else if (frame.kind === "done") {
+        return frame.value;
+      } else {
+        throw new StreamError(frame.code, frame.message);
+      }
+    }
+  } finally {
+    unsubscribe();
+  }
+}
+const bundlerTransport = {
+  send: (msg) => (0, import_sandboxUtils.sendMessage)(msg.type, msg),
+  subscribe: (type, handler) => (0, import_sandboxUtils.addListener)(type, (msg) => handler(msg))
+};
+function protocolStream(protocolName, method, params) {
+  return consumeStream(bundlerTransport, protocolName, method, params);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StreamError,
+  consumeStream,
+  protocolStream
+});
+//# sourceMappingURL=protocolStream.cjs.map

package/dist/protocolStream.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\n\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n}\n\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId()\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  try {\n    transport.send({ type, method, params, msgId, stream: true });\n    while (true) {\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n        continue;\n      }\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        return frame.value as R;\n      } else {\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[]\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(bundlerTransport, protocolName, method, params);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,0BAAyC;AAkBlC,MAAM,oBAAoB,MAAM;AAAA,EAErC,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,gBAAgB;AACpB,MAAM,YAAY,MAAc;AAI9B,mBAAiB,gBAAgB,KAAK,OAAO;AAC7C,SAAO;AACT;AASA,gBAAuB,cACrB,WACA,MACA,QACA,QACA,QAAgB,UAAU,GACE;AAC5B,QAAM,QAAuB,CAAC;AAC9B,MAAI,OAA4B;AAChC,QAAM,OAAO,CAAC,UAAuB;AACnC,UAAM,KAAK,KAAK;AAChB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AAEA,QAAM,cAAc,UAAU,UAAU,MAAM,CAAC,QAAQ;AACrD,QAAI,IAAI,UAAU,SAAS,CAAC,IAAI,OAAQ;AACxC,SAAK,IAAI,MAAM;AAAA,EACjB,CAAC;AAED,MAAI;AACF,cAAU,KAAK,EAAE,MAAM,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC;AAC5D,WAAO,MAAM;AACX,UAAI,MAAM,WAAW,GAAG;AACtB,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAO;AAAA,QACT,CAAC;AACD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,MAAM;AAC1B,UAAI,MAAM,SAAS,SAAS;AAC1B,cAAM,MAAM;AAAA,MACd,WAAW,MAAM,SAAS,QAAQ;AAChC,eAAO,MAAM;AAAA,MACf,OAAO;AACL,cAAM,IAAI,YAAY,MAAM,MAAM,MAAM,OAAO;AAAA,MACjD;AAAA,IACF;AAAA,EACF,UAAE;AACA,gBAAY;AAAA,EACd;AACF;AAGA,MAAM,mBAAoC;AAAA,EACxC,MAAM,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,gBAChB,iCAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AACvF;AAOO,SAAS,eACd,cACA,QACA,QAC4B;AAC5B,SAAO,cAAoB,kBAAkB,cAAc,QAAQ,MAAM;AAC3E;","names":[]}

package/dist/protocolStream.d.cts

@@ -0,0 +1,44 @@
+type StreamFrame = {
+    kind: 'event';
+    value: unknown;
+} | {
+    kind: 'done';
+    value: unknown;
+} | {
+    kind: 'error';
+    code: string;
+    message: string;
+};
+interface StreamTransport {
+    send: (msg: {
+        type: string;
+        method: string;
+        params: unknown[];
+        msgId: number;
+        stream: true;
+    }) => void;
+    subscribe: (type: string, handler: (msg: {
+        msgId?: number;
+        stream?: StreamFrame;
+    }) => void) => () => void;
+}
+declare class StreamError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Drive one streamed request to completion over an injected transport.
+ *
+ * Yields each event value; returns the `done` value; throws `StreamError` on an
+ * error frame. Always unsubscribes (via the generator's `finally`) so an early
+ * `break` in the consumer doesn't leak the listener.
+ */
+declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransport, type: string, method: string, params: unknown[], msgId?: number): AsyncGenerator<T, R, void>;
+/**
+ * Consume an elevated streaming protocol method from app code.
+ *
+ * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`
+ */
+declare function protocolStream<T = unknown, R = unknown>(protocolName: string, method: string, params: unknown[]): AsyncGenerator<T, R, void>;
+
+export { StreamError, type StreamFrame, type StreamTransport, consumeStream, protocolStream };

package/dist/protocolStream.d.ts

@@ -0,0 +1,44 @@
+type StreamFrame = {
+    kind: 'event';
+    value: unknown;
+} | {
+    kind: 'done';
+    value: unknown;
+} | {
+    kind: 'error';
+    code: string;
+    message: string;
+};
+interface StreamTransport {
+    send: (msg: {
+        type: string;
+        method: string;
+        params: unknown[];
+        msgId: number;
+        stream: true;
+    }) => void;
+    subscribe: (type: string, handler: (msg: {
+        msgId?: number;
+        stream?: StreamFrame;
+    }) => void) => () => void;
+}
+declare class StreamError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Drive one streamed request to completion over an injected transport.
+ *
+ * Yields each event value; returns the `done` value; throws `StreamError` on an
+ * error frame. Always unsubscribes (via the generator's `finally`) so an early
+ * `break` in the consumer doesn't leak the listener.
+ */
+declare function consumeStream<T = unknown, R = unknown>(transport: StreamTransport, type: string, method: string, params: unknown[], msgId?: number): AsyncGenerator<T, R, void>;
+/**
+ * Consume an elevated streaming protocol method from app code.
+ *
+ * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`
+ */
+declare function protocolStream<T = unknown, R = unknown>(protocolName: string, method: string, params: unknown[]): AsyncGenerator<T, R, void>;
+
+export { StreamError, type StreamFrame, type StreamTransport, consumeStream, protocolStream };