@immediately-run/sdk 0.1.4 → 0.1.5

package/dist/index.d.cts

@@ -5,7 +5,7 @@ export { Include, RenderExportedComponent, RenderExportedComponentContext, Rende
 export { DEFAULT_MDX_COMPONENTS, InternalLink, Link } from './components/MDXComponents.cjs';
 export { useFileMetadata, useMetadataQuery } from './hooks.cjs';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.cjs';
-export { MountQuery, SandboxMount, findMount, getMounts, onMountsChange, useMounts, waitForMount } from './mounts.cjs';
+export { MountQuery, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount } from './mounts.cjs';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
 import 'react';
 import './TinkerableContext.cjs';

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { Include, RenderExportedComponent, RenderExportedComponentContext, Rende
 export { DEFAULT_MDX_COMPONENTS, InternalLink, Link } from './components/MDXComponents.js';
 export { useFileMetadata, useMetadataQuery } from './hooks.js';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.js';
-export { MountQuery, SandboxMount, findMount, getMounts, onMountsChange, useMounts, waitForMount } from './mounts.js';
+export { MountQuery, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount } from './mounts.js';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
 import 'react';
 import './TinkerableContext.js';

package/dist/mounts.cjs

@@ -18,14 +18,20 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var mounts_exports = {};
 __export(mounts_exports, {
+  createSpace: () => createSpace,
   findMount: () => findMount,
   getMounts: () => getMounts,
+  listSpaces: () => listSpaces,
+  mountSpace: () => mountSpace,
   onMountsChange: () => onMountsChange,
+  openAppSpace: () => openAppSpace,
+  unmountSpace: () => unmountSpace,
   useMounts: () => useMounts,
   waitForMount: () => waitForMount
 });
 module.exports = __toCommonJS(mounts_exports);
 var import_react = require("react");
+var import_sandboxUtils = require("./sandboxUtils");
 const mountService = () => {
   return module.evaluation.module.bundler.mounts;
 };
@@ -50,11 +56,33 @@ const useMounts = () => {
   (0, import_react.useEffect)(() => onMountsChange(setMounts), []);
   return mounts;
 };
+const request = async (method, query = {}) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)("spaces", method, [query]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "space request failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+  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 unmountSpace = async (query) => {
+  await request("unmount", query);
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createSpace,
   findMount,
   getMounts,
+  listSpaces,
+  mountSpace,
   onMountsChange,
+  openAppSpace,
+  unmountSpace,
   useMounts,
   waitForMount
 });

package/dist/mounts.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear and disappear at runtime — e.g. a Firestore-backed store is\n * mounted at `/firestore` after the user signs in and removed on logout. Read\n * or subscribe to the set, then access the files through the `fs` module at the\n * mount's `path`.\n */\nexport interface SandboxMount {\n  /** Absolute path where the mount is reachable (e.g. `/firestore`). */\n  path: string;\n  /** Backend kind, e.g. `'firestore'`. */\n  type: string;\n  /** Optional stable identifier. */\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"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AA0BpC,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;","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: '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":[]}

package/dist/mounts.d.cts

@@ -1,17 +1,17 @@
 /**
  * A filesystem mount available to the sandbox, mirrored from the host window.
  *
- * Mounts appear and disappear at runtime — e.g. a Firestore-backed store is
- * mounted at `/firestore` after the user signs in and removed on logout. Read
- * or subscribe to the set, then access the files through the `fs` module at the
- * mount's `path`.
+ * Mounts appear on demand — call {@link openAppSpace} / {@link mountSpace} to ask
+ * the host to mount a Firestore-backed "space"; it appears at `/spaces/{id}`.
+ * Read or subscribe to the set, then access the files through the `fs` module at
+ * the mount's `path`.
  */
 interface SandboxMount {
-    /** Absolute path where the mount is reachable (e.g. `/firestore`). */
+    /** Absolute path where the mount is reachable (e.g. `/spaces/{id}`). */
     path: string;
     /** Backend kind, e.g. `'firestore'`. */
     type: string;
-    /** Optional stable identifier. */
+    /** Optional stable identifier (the spaceId, for spaces). */
     id?: string;
 }
 /** A predicate-style matcher for {@link findMount} / {@link waitForMount}. */
@@ -40,5 +40,41 @@ declare const onMountsChange: (listener: (mounts: SandboxMount[]) => void) => ((
 declare const waitForMount: (query: MountQuery) => Promise<SandboxMount>;
 /** React hook returning the mounts currently available, re-rendering on change. */
 declare const useMounts: () => SandboxMount[];
+/** Summary of a space, as returned by {@link listSpaces}. */
+interface SpaceInfo {
+    spaceId: string;
+    role?: 'owner' | 'writer' | 'reader';
+    owner?: string;
+    name?: string;
+}
+/** An error from a space operation, carrying a machine-readable `code`. */
+interface SpaceError extends Error {
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unknown';
+}
+/**
+ * Open this app's workspace for the signed-in user (the zero-config path). The
+ * `slot` names which workspace (default `'default'`); pass distinct slots for
+ * multiple filesystems in one app. On a missing slot the host shows a
+ * 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). */
+declare const mountSpace: (query: {
+    spaceId: string;
+}) => Promise<SandboxMount>;
+/** Create a brand-new space, optionally binding it to this app (a slot). */
+declare const createSpace: (opts?: {
+    name?: string;
+    slot?: string;
+    bindToApp?: boolean;
+}) => Promise<SandboxMount>;
+/** List spaces you can access — all of them, or just those bound to this app. */
+declare const listSpaces: (opts?: {
+    app?: boolean;
+}) => Promise<SpaceInfo[]>;
+/** Release a mounted space (stops its listener on the host). */
+declare const unmountSpace: (query: {
+    spaceId: string;
+}) => Promise<void>;
 
-export { type MountQuery, type SandboxMount, findMount, getMounts, onMountsChange, useMounts, waitForMount };
+export { type MountQuery, type SandboxMount, type SpaceError, type SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount };

package/dist/mounts.d.ts

@@ -1,17 +1,17 @@
 /**
  * A filesystem mount available to the sandbox, mirrored from the host window.
  *
- * Mounts appear and disappear at runtime — e.g. a Firestore-backed store is
- * mounted at `/firestore` after the user signs in and removed on logout. Read
- * or subscribe to the set, then access the files through the `fs` module at the
- * mount's `path`.
+ * Mounts appear on demand — call {@link openAppSpace} / {@link mountSpace} to ask
+ * the host to mount a Firestore-backed "space"; it appears at `/spaces/{id}`.
+ * Read or subscribe to the set, then access the files through the `fs` module at
+ * the mount's `path`.
  */
 interface SandboxMount {
-    /** Absolute path where the mount is reachable (e.g. `/firestore`). */
+    /** Absolute path where the mount is reachable (e.g. `/spaces/{id}`). */
     path: string;
     /** Backend kind, e.g. `'firestore'`. */
     type: string;
-    /** Optional stable identifier. */
+    /** Optional stable identifier (the spaceId, for spaces). */
     id?: string;
 }
 /** A predicate-style matcher for {@link findMount} / {@link waitForMount}. */
@@ -40,5 +40,41 @@ declare const onMountsChange: (listener: (mounts: SandboxMount[]) => void) => ((
 declare const waitForMount: (query: MountQuery) => Promise<SandboxMount>;
 /** React hook returning the mounts currently available, re-rendering on change. */
 declare const useMounts: () => SandboxMount[];
+/** Summary of a space, as returned by {@link listSpaces}. */
+interface SpaceInfo {
+    spaceId: string;
+    role?: 'owner' | 'writer' | 'reader';
+    owner?: string;
+    name?: string;
+}
+/** An error from a space operation, carrying a machine-readable `code`. */
+interface SpaceError extends Error {
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'unknown';
+}
+/**
+ * Open this app's workspace for the signed-in user (the zero-config path). The
+ * `slot` names which workspace (default `'default'`); pass distinct slots for
+ * multiple filesystems in one app. On a missing slot the host shows a
+ * 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). */
+declare const mountSpace: (query: {
+    spaceId: string;
+}) => Promise<SandboxMount>;
+/** Create a brand-new space, optionally binding it to this app (a slot). */
+declare const createSpace: (opts?: {
+    name?: string;
+    slot?: string;
+    bindToApp?: boolean;
+}) => Promise<SandboxMount>;
+/** List spaces you can access — all of them, or just those bound to this app. */
+declare const listSpaces: (opts?: {
+    app?: boolean;
+}) => Promise<SpaceInfo[]>;
+/** Release a mounted space (stops its listener on the host). */
+declare const unmountSpace: (query: {
+    spaceId: string;
+}) => Promise<void>;
 
-export { type MountQuery, type SandboxMount, findMount, getMounts, onMountsChange, useMounts, waitForMount };
+export { type MountQuery, type SandboxMount, type SpaceError, type SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount };

package/dist/mounts.js

@@ -1,4 +1,5 @@
 import { useEffect, useState } from "react";
+import { protocolRequest } from "./sandboxUtils";
 const mountService = () => {
   return module.evaluation.module.bundler.mounts;
 };
@@ -23,10 +24,32 @@ const useMounts = () => {
   useEffect(() => onMountsChange(setMounts), []);
   return mounts;
 };
+const request = async (method, query = {}) => {
+  const res = await protocolRequest("spaces", method, [query]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "space request failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+  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 unmountSpace = async (query) => {
+  await request("unmount", query);
+};
 export {
+  createSpace,
   findMount,
   getMounts,
+  listSpaces,
+  mountSpace,
   onMountsChange,
+  openAppSpace,
+  unmountSpace,
   useMounts,
   waitForMount
 };

package/dist/mounts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mounts.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\n/**\n * A filesystem mount available to the sandbox, mirrored from the host window.\n *\n * Mounts appear and disappear at runtime — e.g. a Firestore-backed store is\n * mounted at `/firestore` after the user signs in and removed on logout. Read\n * or subscribe to the set, then access the files through the `fs` module at the\n * mount's `path`.\n */\nexport interface SandboxMount {\n  /** Absolute path where the mount is reachable (e.g. `/firestore`). */\n  path: string;\n  /** Backend kind, e.g. `'firestore'`. */\n  type: string;\n  /** Optional stable identifier. */\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"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AA0BpC,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;","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: '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":[]}

package/package.json

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