@immediately-run/sdk 0.57.1 → 0.58.0

package/dist/tasks.d.ts

@@ -44,27 +44,156 @@ declare const capDir: (ref: {
 /**
  * Invoke another app via a task contract and await its typed result (Recipe B).
  * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the
- * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file
- * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/
- * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).
+ * overlay), `timeout` (§5.7.1 liveness), `forbidden` (missing `task:invoke`, or a
+ * file delegation you don't hold), `not-declared` (the task is missing from your
+ * `immediately.run.invokes`), `no-such-task` (no app is bound to that contract),
+ * `task-cycle`/`task-depth-exceeded`/`task-version-mismatch`, or `invalid-params`
+ * (result failed the contract schema). **Read `err.message`** — since R3-418 the host
+ * says which capability, which declaration or which param was at fault; the code alone
+ * does not distinguish them.
+ *
+ * Two things must BOTH be true before any invoke is admitted, and they are separate:
+ *  1. your `package.json` `immediately.run.invokes` lists the task (else `not-declared`);
+ *  2. your app holds the `task:invoke` capability — declare it in
+ *     `immediately.run.capabilities` so the user can grant it (else `forbidden`).
+ * Declaring the invoke does not imply the capability.
+ *
+ * ── `pick-file`: `roots` is required (SPACES_UI_SPEC §4.1) ───────────────────
+ * ```ts
+ * import { invokeTask, capDir, requestMount } from '@immediately-run/sdk';
+ *
+ * const mount = await requestMount();                    // the user picks a space
+ * // `invokeTask` returns `unknown` — name the result type, or the destructuring
+ * // below does not compile.
+ * const { root, path } = await invokeTask<{ root: number; path: string }>('pick-file', {
+ *   // `SandboxMount.id` is optional (absent on the primary repo mount) — fall back to
+ *   // `path`, which is always present and is what the host resolves against.
+ *   roots: [capDir({ mountId: mount.id ?? mount.path, relPath: 'boards' }, { mode: 'ro' })],
+ * });
+ * ```
+ * - `roots` is a NON-EMPTY `DirCap[]` of directories you **already hold**. The result
+ *   names its target as `{ root, path }` where `root` INDEXES `params.roots`, so
+ *   `invokeTask('pick-file', {})` can never produce a valid result and is rejected.
+ *   There is no rootless "pick from any of my spaces" mode by design: enumerating the
+ *   user's spaces is the host's powerbox (`requestMount()`), and composing the two —
+ *   as above — is that flow. See SPACES_UI_SPEC R-SPACES-5/R-SPACES-12.
+ * - Each `capDir` is attenuated against your own grant. **`{ mode: 'rw' }` over a space
+ *   the user granted `ro` is refused `forbidden`** — the commonest failure, because the
+ *   mount *was* granted and the path *is* inside it. Pass the mode you actually hold;
+ *   `ro` is right for a plain pick.
+ * - The `requestMount()` grant is DURABLE and survives a cancelled pick: the user
+ *   consented to the mount in host chrome, separately from the pick (SPACES_UI_SPEC §4.1).
+ *   Reuse it for later picks rather than re-requesting.
+ *
+ * Off-host (plain `vite dev` — no host transport) it rejects with a plain
+ * "no host transport" error: there is no host to resolve the task binding.
  */
 declare const invokeTask: <R = unknown>(task: string, params?: Record<string, unknown>) => Promise<R>;
+/** Bytes captured by the host, as `capturePhoto()` / `captureAudio()` return them.
+ *  `bytes` is a transferable `ArrayBuffer` — write it to a space, decode it, upload
+ *  it. You never receive a `MediaStream` or a `MediaStreamTrack`, and that is not an
+ *  omission: a track cannot be transferred into an app frame at all
+ *  (`DataCloneError`), and the frame's opaque origin cannot open a device itself
+ *  (`getUserMedia` throws `SecurityError: Invalid security origin`). */
+interface CaptureResult {
+    bytes: ArrayBuffer;
+    /** e.g. `image/jpeg`, `audio/webm`. Chosen by the HOST, not by you. */
+    mimeType: string;
+    /** How long the device was open, in ms. */
+    durationMs: number;
+}
+/** Optional hints for a capture. They deliberately name NOTHING — no device id, no
+ *  camera index — because the host chooses everything about how the capture is
+ *  performed. That is what lets the grant be a plain on/off instead of a per-call
+ *  target list the way `net:fetch` needs. */
+interface CaptureOptions {
+    /** Which way the camera should face, if the device has a choice. A HINT: the host
+     *  may ignore it. Ignored for audio. */
+    facing?: 'user' | 'environment';
+}
+/**
+ * Take one photo, or record one audio clip, through the HOST's capture UI
+ * (`BROWSER_CAPABILITIES_SPEC` §3 grade 1).
+ *
+ * The host opens the device at its own origin, draws the viewfinder, and hands you
+ * the bytes when the user presses Done. **You are never in the loop while the device
+ * is live** — that is the point of the design, not a limitation of it:
+ *
+ * - The capture UI is drawn by the host, so a user can trust it the way they trust
+ *   the sign-in dialog. Do not build a lookalike; imitating host chrome is spoofing.
+ * - While the device is open the host shows a persistent "camera on" / "microphone
+ *   on" indicator in its own chrome, for the whole session. You cannot hide it and
+ *   should not try to.
+ * - If the user cancels, this rejects `cancelled` and **nothing was recorded**. There
+ *   is no partial result — do not write error handling that hopes for one.
+ *
+ * ```ts
+ * import { capturePhoto, requestMount, openFs } from '@immediately-run/sdk';
+ *
+ * try {
+ *   const { bytes, mimeType } = await capturePhoto({ facing: 'environment' });
+ *   const mount = await requestMount();          // the user picks a space to save into
+ *   const fs = openFs(mount);                    // writeFile is a METHOD on the MountFs
+ *   await fs.mkdir('photos', { recursive: true }); // writeFile does not create parents
+ *   await fs.writeFile(`photos/latest.${mimeType === 'image/png' ? 'png' : 'jpg'}`, new Uint8Array(bytes));
+ * } catch (e) {
+ *   if ((e as { code?: string }).code === 'cancelled') return; // the user said no
+ *   throw e;
+ * }
+ * ```
+ * (The extension follows `mimeType` because the HOST chooses the format — do not assume
+ * JPEG. `openAppFs()` is the variant that writes to your own app space with no pick.)
+ *
+ * Two things must BOTH be true, exactly as for any other task:
+ *  1. `immediately.run.invokes` lists `capture-photo` (or `capture-audio`);
+ *  2. your app holds `task:invoke` **and** `device:camera` (or `device:microphone`)
+ *     — declare them in `immediately.run.capabilities` so the user can grant them.
+ *
+ * Rejects with `.code`: `cancelled` (the user dismissed the capture — nothing was
+ * recorded), `forbidden` (you lack the capability; `message: 'browser-denied'` means
+ * the BROWSER refused immediately.run itself, which your consent cannot fix),
+ * `unavailable` (no such device on this machine, or it would not start),
+ * `unsupported` (this host cannot capture), `not-declared`, `timeout`.
+ *
+ * *Zero-platform alternative, still worth knowing:* `<input type="file"
+ * accept="image/*" capture="environment">` opens the OS camera from inside the
+ * sandbox (file choosers are not permission-gated). It needs no capability and no
+ * host support; it also gives you no indicator and no host-drawn surface.
+ */
+declare const capturePhoto: (options?: CaptureOptions) => Promise<CaptureResult>;
+/** Record one audio clip through the host's capture UI. See {@link capturePhoto} —
+ *  every rule there applies verbatim, with `device:microphone` and `capture-audio`. */
+declare const captureAudio: (options?: CaptureOptions) => Promise<CaptureResult>;
 /** The params this app was invoked with as a task callee. */
 interface TaskInput {
     task: string;
     params: Record<string, unknown>;
 }
-/** The task params this app was invoked with, or null if it isn't a task callee. */
+/** The task params this app was invoked with, or null if it isn't a task callee.
+ *  Off-host (plain `vite dev`) this is always `null` — there is no host to invoke
+ *  this app as a callee. */
 declare const getTaskInput: () => TaskInput | null;
 /**
  * Finish the task, returning a result to the caller. The host validates it against
  * the contract's result schema before resolving the caller (`invalid-params` on
  * violation), then tears down this overlay.
+ *
+ * `result` must be STRUCTURED-CLONEABLE — it crosses a frame boundary. A DOM node, a
+ * function, a class instance with methods, a `MediaStreamTrack`: all `DataCloneError`.
+ * **That throws**, deliberately and loudly: the alternative is a caller left hanging to
+ * its `invokeTask` deadline while this app believes it answered.
+ *
+ * Off-host (plain `vite dev` — no host transport) this is a no-op: there is no caller
+ * to answer. That case, and only that case, is silent.
  */
 declare const completeTask: (result: unknown) => void;
-/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */
+/** Abort the task; the caller's `invokeTask` rejects with `cancelled`.
+ *  Off-host (plain `vite dev` — no host transport) this is a no-op; on-host a failed
+ *  send throws rather than leaving the caller waiting, exactly as {@link completeTask}. */
 declare const cancelTask: () => void;
-/** React hook: the task input for this callee, re-rendering when it arrives. */
+/** React hook: the task input for this callee, re-rendering when it arrives.
+ *  Off-host (plain `vite dev`) it stays `null` forever — render the non-callee
+ *  state rather than waiting on it. */
 declare const useTaskInput: () => TaskInput | null;
 
-export { type DirCap, type FileCap, type TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput };
+export { type CaptureOptions, type CaptureResult, type DirCap, type FileCap, type TaskInput, cancelTask, capDir, capFile, captureAudio, capturePhoto, completeTask, getTaskInput, invokeTask, useTaskInput };

package/dist/tasks.js

@@ -1,6 +1,7 @@
 import "./chunk-VHAA22YE.js";
 import { useEffect, useState } from "react";
 import { protocolRequest, sendMessage, addListener } from "./sandboxUtils";
+import { transport } from "./hostTransport";
 import { PROTOCOL_TASK, TASK_CANCEL, TASK_COMPLETE, TASK_INPUT } from "./generated/protocol";
 import { SCHEMES } from "./protocolSchemes";
 const capFile = (ref, opts) => ({
@@ -24,15 +25,44 @@ const invokeTask = async (task, params = {}) => {
   }
   return res.data;
 };
+const capturePhoto = (options = {}) => invokeTask("capture-photo", { ...options });
+const captureAudio = (options = {}) => invokeTask("capture-audio", { ...options });
 let latestInput = null;
 const inputListeners = /* @__PURE__ */ new Set();
-addListener(TASK_INPUT, (m) => {
-  latestInput = { task: m.task, params: m.params ?? {} };
-  inputListeners.forEach((l) => l(latestInput));
-});
-const getTaskInput = () => latestInput;
-const completeTask = (result) => sendMessage(TASK_COMPLETE, { result });
-const cancelTask = () => sendMessage(TASK_CANCEL, {});
+let inputListenerRegistered = false;
+const ensureInputListener = () => {
+  if (inputListenerRegistered) return;
+  try {
+    addListener(TASK_INPUT, (m) => {
+      latestInput = { task: m.task, params: m.params ?? {} };
+      inputListeners.forEach((l) => l(latestInput));
+    });
+  } catch {
+    return;
+  }
+  inputListenerRegistered = true;
+};
+ensureInputListener();
+const getTaskInput = () => {
+  ensureInputListener();
+  return latestInput;
+};
+const hostReachable = () => {
+  try {
+    transport();
+    return true;
+  } catch {
+    return false;
+  }
+};
+const completeTask = (result) => {
+  if (!hostReachable()) return;
+  sendMessage(TASK_COMPLETE, { result });
+};
+const cancelTask = () => {
+  if (!hostReachable()) return;
+  sendMessage(TASK_CANCEL, {});
+};
 const useTaskInput = () => {
   const [input, setInput] = useState(getTaskInput);
   useEffect(() => {
@@ -49,6 +79,8 @@ export {
   cancelTask,
   capDir,
   capFile,
+  captureAudio,
+  capturePhoto,
   completeTask,
   getTaskInput,
   invokeTask,

package/dist/tasks.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tasks.ts"],"sourcesContent":["// Task invocation — apps invoking apps (UI_AS_APPS_SPEC §5.7). The\n// `startActivityForResult` pattern: one app invokes another by TASK CONTRACT\n// (never by app name — the user's override picks the bound app), passes typed\n// params, and awaits a typed result. The callee runs in a host-owned overlay\n// under ITS OWN grants — data crosses, your authority does not (§5.7).\n//\n// Two roles:\n//  - CALLER: `invokeTask(task, params)` (Recipe B — a deferred reply the host\n//    holds open until the callee finishes). Delegate a file with `capFile(...)`:\n//    the host resolves it against YOUR grants and mints an attenuated chroot.\n//  - CALLEE: read `useTaskInput()`, then `completeTask(result)` / `cancelTask()`.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { PROTOCOL_TASK, TASK_CANCEL, TASK_COMPLETE, TASK_INPUT } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n// ── caller side ─────────────────────────────────────────────────────────────\n\n/** A delegated FILE capability marker for a task param (§5.7). */\nexport interface FileCap {\n  $cap: 'file';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated file reference for a task param. The host resolves it against\n * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you\n * can only delegate a path you already hold (attenuation only, never escalation).\n *\n *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })\n */\nexport const capFile = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): FileCap => ({\n  $cap: 'file',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/** A delegated DIRECTORY capability marker for a task param (D2). Like {@link FileCap}\n *  but `relPath` names a DIRECTORY: the host chroots the callee AT that directory\n *  (the whole subtree). Used for the `pick-file` `roots` — one chroot per root. */\nexport interface DirCap {\n  $cap: 'dir';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated DIRECTORY reference for a task param (the directory analogue of\n * {@link capFile}). The host resolves it against YOUR OWN grants and mints an\n * attenuated, task-scoped chroot of that directory for the callee — you can only\n * delegate a directory you already hold (attenuation only, never escalation):\n *\n *   roots: [capDir({ mountId: 'space:abc', relPath: 'boards' }, { mode: 'rw' })]\n */\nexport const capDir = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): DirCap => ({\n  $cap: 'dir',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/**\n * Invoke another app via a task contract and await its typed result (Recipe B).\n * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the\n * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file\n * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/\n * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).\n */\nexport const invokeTask = async <R = unknown>(task: string, params: Record<string, unknown> = {}): Promise<R> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_TASK], 'invoke', [{ task, params }])) as\n    | { ok: true; data: R }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `task '${task}' failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n// ── callee side ─────────────────────────────────────────────────────────────\n\n/** The params this app was invoked with as a task callee. */\nexport interface TaskInput {\n  task: string;\n  params: Record<string, unknown>;\n}\n\nlet latestInput: TaskInput | null = null;\nconst inputListeners = new Set<(i: TaskInput) => void>();\n\n// The host delivers a `task-input` message to the callee's iframe right after it\n// mounts the overlay (the §5.7 \"params via the region's mount event\").\naddListener(TASK_INPUT, (m: { task: string; params?: Record<string, unknown> }) => {\n  latestInput = { task: m.task, params: m.params ?? {} };\n  inputListeners.forEach((l) => l(latestInput!));\n});\n\n/** The task params this app was invoked with, or null if it isn't a task callee. */\nexport const getTaskInput = (): TaskInput | null => latestInput;\n\n/**\n * Finish the task, returning a result to the caller. The host validates it against\n * the contract's result schema before resolving the caller (`invalid-params` on\n * violation), then tears down this overlay.\n */\nexport const completeTask = (result: unknown): void => sendMessage(TASK_COMPLETE, { result });\n\n/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */\nexport const cancelTask = (): void => sendMessage(TASK_CANCEL, {});\n\n/** React hook: the task input for this callee, re-rendering when it arrives. */\nexport const useTaskInput = (): TaskInput | null => {\n  const [input, setInput] = useState<TaskInput | null>(getTaskInput);\n  useEffect(() => {\n    const l = (i: TaskInput) => setInput(i);\n    inputListeners.add(l);\n    if (latestInput) setInput(latestInput);\n    return () => {\n      inputListeners.delete(l);\n    };\n  }, []);\n  return input;\n};\n"],"mappings":";AAWA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,aAAa,mBAAmB;AAC1D,SAAS,eAAe,aAAa,eAAe,kBAAkB;AACtE,SAAS,eAAe;AAmBjB,MAAM,UAAU,CAAC,KAA2C,UAA0C;AAAA,EAC3G,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AAoBO,MAAM,SAAS,CAAC,KAA2C,UAAyC;AAAA,EACzG,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AASO,MAAM,aAAa,OAAoB,MAAc,SAAkC,CAAC,MAAkB;AAC/G,QAAM,MAAO,MAAM,gBAAgB,QAAQ,aAAa,GAAG,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAIvF,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,SAAS,IAAI,UAAU;AAC7D,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAUA,IAAI,cAAgC;AACpC,MAAM,iBAAiB,oBAAI,IAA4B;AAIvD,YAAY,YAAY,CAAC,MAA0D;AACjF,gBAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,EAAE,UAAU,CAAC,EAAE;AACrD,iBAAe,QAAQ,CAAC,MAAM,EAAE,WAAY,CAAC;AAC/C,CAAC;AAGM,MAAM,eAAe,MAAwB;AAO7C,MAAM,eAAe,CAAC,WAA0B,YAAY,eAAe,EAAE,OAAO,CAAC;AAGrF,MAAM,aAAa,MAAY,YAAY,aAAa,CAAC,CAAC;AAG1D,MAAM,eAAe,MAAwB;AAClD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA2B,YAAY;AACjE,YAAU,MAAM;AACd,UAAM,IAAI,CAAC,MAAiB,SAAS,CAAC;AACtC,mBAAe,IAAI,CAAC;AACpB,QAAI,YAAa,UAAS,WAAW;AACrC,WAAO,MAAM;AACX,qBAAe,OAAO,CAAC;AAAA,IACzB;AAAA,EACF,GAAG,CAAC,CAAC;AACL,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/tasks.ts"],"sourcesContent":["// Task invocation — apps invoking apps (UI_AS_APPS_SPEC §5.7). The\n// `startActivityForResult` pattern: one app invokes another by TASK CONTRACT\n// (never by app name — the user's override picks the bound app), passes typed\n// params, and awaits a typed result. The callee runs in a host-owned overlay\n// under ITS OWN grants — data crosses, your authority does not (§5.7).\n//\n// Two roles:\n//  - CALLER: `invokeTask(task, params)` (Recipe B — a deferred reply the host\n//    holds open until the callee finishes). Delegate a file with `capFile(...)`:\n//    the host resolves it against YOUR grants and mints an attenuated chroot.\n//  - CALLEE: read `useTaskInput()`, then `completeTask(result)` / `cancelTask()`.\n//\n// OFF-HOST (plain `vite dev`, node/jsdom tests — no sandbox, no host transport):\n// importing this module is always safe (R3-421 — no subpath may throw at import\n// time), and the surface degrades instead of crashing: `getTaskInput()` /\n// `useTaskInput()` stay `null` forever (you are never a task callee without a\n// host), `completeTask` / `cancelTask` are no-ops, and `invokeTask` rejects with\n// a \"no host transport\" error. Under the @immediately-run/dev-fs substrate the\n// transport resolves but no task ever arrives — same observable behaviour.\n// The no-op is scoped to the ABSENCE of a host: when there IS one, a failed send\n// throws instead of leaving the caller to hang out its deadline.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport { transport } from './hostTransport';\nimport { PROTOCOL_TASK, TASK_CANCEL, TASK_COMPLETE, TASK_INPUT } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n// ── caller side ─────────────────────────────────────────────────────────────\n\n/** A delegated FILE capability marker for a task param (§5.7). */\nexport interface FileCap {\n  $cap: 'file';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated file reference for a task param. The host resolves it against\n * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you\n * can only delegate a path you already hold (attenuation only, never escalation).\n *\n *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })\n */\nexport const capFile = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): FileCap => ({\n  $cap: 'file',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/** A delegated DIRECTORY capability marker for a task param (D2). Like {@link FileCap}\n *  but `relPath` names a DIRECTORY: the host chroots the callee AT that directory\n *  (the whole subtree). Used for the `pick-file` `roots` — one chroot per root. */\nexport interface DirCap {\n  $cap: 'dir';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated DIRECTORY reference for a task param (the directory analogue of\n * {@link capFile}). The host resolves it against YOUR OWN grants and mints an\n * attenuated, task-scoped chroot of that directory for the callee — you can only\n * delegate a directory you already hold (attenuation only, never escalation):\n *\n *   roots: [capDir({ mountId: 'space:abc', relPath: 'boards' }, { mode: 'rw' })]\n */\nexport const capDir = (ref: { mountId: string; relPath: string }, opts: { mode: 'ro' | 'rw' }): DirCap => ({\n  $cap: 'dir',\n  mountId: ref.mountId,\n  relPath: ref.relPath,\n  mode: opts.mode,\n});\n\n/**\n * Invoke another app via a task contract and await its typed result (Recipe B).\n * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the\n * overlay), `timeout` (§5.7.1 liveness), `forbidden` (missing `task:invoke`, or a\n * file delegation you don't hold), `not-declared` (the task is missing from your\n * `immediately.run.invokes`), `no-such-task` (no app is bound to that contract),\n * `task-cycle`/`task-depth-exceeded`/`task-version-mismatch`, or `invalid-params`\n * (result failed the contract schema). **Read `err.message`** — since R3-418 the host\n * says which capability, which declaration or which param was at fault; the code alone\n * does not distinguish them.\n *\n * Two things must BOTH be true before any invoke is admitted, and they are separate:\n *  1. your `package.json` `immediately.run.invokes` lists the task (else `not-declared`);\n *  2. your app holds the `task:invoke` capability — declare it in\n *     `immediately.run.capabilities` so the user can grant it (else `forbidden`).\n * Declaring the invoke does not imply the capability.\n *\n * ── `pick-file`: `roots` is required (SPACES_UI_SPEC §4.1) ───────────────────\n * ```ts\n * import { invokeTask, capDir, requestMount } from '@immediately-run/sdk';\n *\n * const mount = await requestMount();                    // the user picks a space\n * // `invokeTask` returns `unknown` — name the result type, or the destructuring\n * // below does not compile.\n * const { root, path } = await invokeTask<{ root: number; path: string }>('pick-file', {\n *   // `SandboxMount.id` is optional (absent on the primary repo mount) — fall back to\n *   // `path`, which is always present and is what the host resolves against.\n *   roots: [capDir({ mountId: mount.id ?? mount.path, relPath: 'boards' }, { mode: 'ro' })],\n * });\n * ```\n * - `roots` is a NON-EMPTY `DirCap[]` of directories you **already hold**. The result\n *   names its target as `{ root, path }` where `root` INDEXES `params.roots`, so\n *   `invokeTask('pick-file', {})` can never produce a valid result and is rejected.\n *   There is no rootless \"pick from any of my spaces\" mode by design: enumerating the\n *   user's spaces is the host's powerbox (`requestMount()`), and composing the two —\n *   as above — is that flow. See SPACES_UI_SPEC R-SPACES-5/R-SPACES-12.\n * - Each `capDir` is attenuated against your own grant. **`{ mode: 'rw' }` over a space\n *   the user granted `ro` is refused `forbidden`** — the commonest failure, because the\n *   mount *was* granted and the path *is* inside it. Pass the mode you actually hold;\n *   `ro` is right for a plain pick.\n * - The `requestMount()` grant is DURABLE and survives a cancelled pick: the user\n *   consented to the mount in host chrome, separately from the pick (SPACES_UI_SPEC §4.1).\n *   Reuse it for later picks rather than re-requesting.\n *\n * Off-host (plain `vite dev` — no host transport) it rejects with a plain\n * \"no host transport\" error: there is no host to resolve the task binding.\n */\nexport const invokeTask = async <R = unknown>(task: string, params: Record<string, unknown> = {}): Promise<R> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_TASK], 'invoke', [{ task, params }])) as\n    | { ok: true; data: R }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `task '${task}' failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n// ── the host-provided CAPTURE contracts (R3-425) ────────────────────────────\n\n/** Bytes captured by the host, as `capturePhoto()` / `captureAudio()` return them.\n *  `bytes` is a transferable `ArrayBuffer` — write it to a space, decode it, upload\n *  it. You never receive a `MediaStream` or a `MediaStreamTrack`, and that is not an\n *  omission: a track cannot be transferred into an app frame at all\n *  (`DataCloneError`), and the frame's opaque origin cannot open a device itself\n *  (`getUserMedia` throws `SecurityError: Invalid security origin`). */\nexport interface CaptureResult {\n  bytes: ArrayBuffer;\n  /** e.g. `image/jpeg`, `audio/webm`. Chosen by the HOST, not by you. */\n  mimeType: string;\n  /** How long the device was open, in ms. */\n  durationMs: number;\n}\n\n/** Optional hints for a capture. They deliberately name NOTHING — no device id, no\n *  camera index — because the host chooses everything about how the capture is\n *  performed. That is what lets the grant be a plain on/off instead of a per-call\n *  target list the way `net:fetch` needs. */\nexport interface CaptureOptions {\n  /** Which way the camera should face, if the device has a choice. A HINT: the host\n   *  may ignore it. Ignored for audio. */\n  facing?: 'user' | 'environment';\n}\n\n/**\n * Take one photo, or record one audio clip, through the HOST's capture UI\n * (`BROWSER_CAPABILITIES_SPEC` §3 grade 1).\n *\n * The host opens the device at its own origin, draws the viewfinder, and hands you\n * the bytes when the user presses Done. **You are never in the loop while the device\n * is live** — that is the point of the design, not a limitation of it:\n *\n * - The capture UI is drawn by the host, so a user can trust it the way they trust\n *   the sign-in dialog. Do not build a lookalike; imitating host chrome is spoofing.\n * - While the device is open the host shows a persistent \"camera on\" / \"microphone\n *   on\" indicator in its own chrome, for the whole session. You cannot hide it and\n *   should not try to.\n * - If the user cancels, this rejects `cancelled` and **nothing was recorded**. There\n *   is no partial result — do not write error handling that hopes for one.\n *\n * ```ts\n * import { capturePhoto, requestMount, openFs } from '@immediately-run/sdk';\n *\n * try {\n *   const { bytes, mimeType } = await capturePhoto({ facing: 'environment' });\n *   const mount = await requestMount();          // the user picks a space to save into\n *   const fs = openFs(mount);                    // writeFile is a METHOD on the MountFs\n *   await fs.mkdir('photos', { recursive: true }); // writeFile does not create parents\n *   await fs.writeFile(`photos/latest.${mimeType === 'image/png' ? 'png' : 'jpg'}`, new Uint8Array(bytes));\n * } catch (e) {\n *   if ((e as { code?: string }).code === 'cancelled') return; // the user said no\n *   throw e;\n * }\n * ```\n * (The extension follows `mimeType` because the HOST chooses the format — do not assume\n * JPEG. `openAppFs()` is the variant that writes to your own app space with no pick.)\n *\n * Two things must BOTH be true, exactly as for any other task:\n *  1. `immediately.run.invokes` lists `capture-photo` (or `capture-audio`);\n *  2. your app holds `task:invoke` **and** `device:camera` (or `device:microphone`)\n *     — declare them in `immediately.run.capabilities` so the user can grant them.\n *\n * Rejects with `.code`: `cancelled` (the user dismissed the capture — nothing was\n * recorded), `forbidden` (you lack the capability; `message: 'browser-denied'` means\n * the BROWSER refused immediately.run itself, which your consent cannot fix),\n * `unavailable` (no such device on this machine, or it would not start),\n * `unsupported` (this host cannot capture), `not-declared`, `timeout`.\n *\n * *Zero-platform alternative, still worth knowing:* `<input type=\"file\"\n * accept=\"image/*\" capture=\"environment\">` opens the OS camera from inside the\n * sandbox (file choosers are not permission-gated). It needs no capability and no\n * host support; it also gives you no indicator and no host-drawn surface.\n */\nexport const capturePhoto = (options: CaptureOptions = {}): Promise<CaptureResult> =>\n  invokeTask<CaptureResult>('capture-photo', { ...options });\n\n/** Record one audio clip through the host's capture UI. See {@link capturePhoto} —\n *  every rule there applies verbatim, with `device:microphone` and `capture-audio`. */\nexport const captureAudio = (options: CaptureOptions = {}): Promise<CaptureResult> =>\n  invokeTask<CaptureResult>('capture-audio', { ...options });\n\n// ── callee side ─────────────────────────────────────────────────────────────\n\n/** The params this app was invoked with as a task callee. */\nexport interface TaskInput {\n  task: string;\n  params: Record<string, unknown>;\n}\n\nlet latestInput: TaskInput | null = null;\nconst inputListeners = new Set<(i: TaskInput) => void>();\nlet inputListenerRegistered = false;\n\n// Register the `task-input` listener IF a host transport is reachable; otherwise do\n// nothing (and let the next call retry — the same pattern as pushChannel's `start`).\n// Split out so both the module-eval attempt below and the first-use call sites share\n// one idempotent path.\nconst ensureInputListener = (): void => {\n  if (inputListenerRegistered) return;\n  try {\n    addListener(TASK_INPUT, (m: { task: string; params?: Record<string, unknown> }) => {\n      latestInput = { task: m.task, params: m.params ?? {} };\n      inputListeners.forEach((l) => l(latestInput!));\n    });\n  } catch {\n    return; // off-host: the transport resolver threw — no host to listen on\n  }\n  inputListenerRegistered = true;\n};\n\n// The host delivers a `task-input` message to the callee's iframe right after it\n// mounts the overlay (the §5.7 \"params via the region's mount event\"). That wire\n// message is a plain one-shot host→app message with NO replay/poll counterpart —\n// the contract (`@immediately-run/sandbox-protocol/sdk`) marks replayable state as\n// \"push … polled with request-*\" (mounts, theme, auth-state, …) and `task-input`\n// is not one of them — so a listener registered only on first use could miss an\n// input delivered between module evaluation and the app's first render. Hence:\n// register EAGERLY when a host transport is already present at module eval\n// (on-host, byte-for-byte the pre-R3-421 behaviour), and lazily-on-first-use\n// otherwise, so importing this module off-host (plain `vite dev`) never throws.\nensureInputListener();\n\n/** The task params this app was invoked with, or null if it isn't a task callee.\n *  Off-host (plain `vite dev`) this is always `null` — there is no host to invoke\n *  this app as a callee. */\nexport const getTaskInput = (): TaskInput | null => {\n  ensureInputListener();\n  return latestInput;\n};\n\n/**\n * Is a host transport reachable from this realm at all?\n *\n * The R3-421 off-host no-op below must mean EXACTLY \"there is nobody to answer\" —\n * plain `vite dev`, node, jsdom. A blanket try/catch around the send meant it also\n * swallowed a genuine failure against a REAL host (`DataCloneError` because the\n * result holds a DOM node, a function or a live class instance, being the usual\n * one): the host was then never told the task finished, and the caller's\n * `invokeTask` hung to its deadline with no diagnostic anywhere. Absence is\n * therefore decided BEFORE the send, and the send itself is left to throw.\n */\nconst hostReachable = (): boolean => {\n  try {\n    transport();\n    return true;\n  } catch {\n    return false; // no injected bundler bus and no §4 discovery global — off-host\n  }\n};\n\n/**\n * Finish the task, returning a result to the caller. The host validates it against\n * the contract's result schema before resolving the caller (`invalid-params` on\n * violation), then tears down this overlay.\n *\n * `result` must be STRUCTURED-CLONEABLE — it crosses a frame boundary. A DOM node, a\n * function, a class instance with methods, a `MediaStreamTrack`: all `DataCloneError`.\n * **That throws**, deliberately and loudly: the alternative is a caller left hanging to\n * its `invokeTask` deadline while this app believes it answered.\n *\n * Off-host (plain `vite dev` — no host transport) this is a no-op: there is no caller\n * to answer. That case, and only that case, is silent.\n */\nexport const completeTask = (result: unknown): void => {\n  if (!hostReachable()) return; // off-host: no caller to answer — documented no-op\n  // On-host, a failure here is REAL and the caller is waiting on this exact message.\n  sendMessage(TASK_COMPLETE, { result });\n};\n\n/** Abort the task; the caller's `invokeTask` rejects with `cancelled`.\n *  Off-host (plain `vite dev` — no host transport) this is a no-op; on-host a failed\n *  send throws rather than leaving the caller waiting, exactly as {@link completeTask}. */\nexport const cancelTask = (): void => {\n  if (!hostReachable()) return; // off-host: no caller to answer — documented no-op\n  sendMessage(TASK_CANCEL, {});\n};\n\n/** React hook: the task input for this callee, re-rendering when it arrives.\n *  Off-host (plain `vite dev`) it stays `null` forever — render the non-callee\n *  state rather than waiting on it. */\nexport const useTaskInput = (): TaskInput | null => {\n  const [input, setInput] = useState<TaskInput | null>(getTaskInput);\n  useEffect(() => {\n    const l = (i: TaskInput) => setInput(i);\n    inputListeners.add(l);\n    if (latestInput) setInput(latestInput);\n    return () => {\n      inputListeners.delete(l);\n    };\n  }, []);\n  return input;\n};\n"],"mappings":";AAqBA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,aAAa,mBAAmB;AAC1D,SAAS,iBAAiB;AAC1B,SAAS,eAAe,aAAa,eAAe,kBAAkB;AACtE,SAAS,eAAe;AAmBjB,MAAM,UAAU,CAAC,KAA2C,UAA0C;AAAA,EAC3G,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AAoBO,MAAM,SAAS,CAAC,KAA2C,UAAyC;AAAA,EACzG,MAAM;AAAA,EACN,SAAS,IAAI;AAAA,EACb,SAAS,IAAI;AAAA,EACb,MAAM,KAAK;AACb;AAiDO,MAAM,aAAa,OAAoB,MAAc,SAAkC,CAAC,MAAkB;AAC/G,QAAM,MAAO,MAAM,gBAAgB,QAAQ,aAAa,GAAG,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAIvF,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,SAAS,IAAI,UAAU;AAC7D,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AA6EO,MAAM,eAAe,CAAC,UAA0B,CAAC,MACtD,WAA0B,iBAAiB,EAAE,GAAG,QAAQ,CAAC;AAIpD,MAAM,eAAe,CAAC,UAA0B,CAAC,MACtD,WAA0B,iBAAiB,EAAE,GAAG,QAAQ,CAAC;AAU3D,IAAI,cAAgC;AACpC,MAAM,iBAAiB,oBAAI,IAA4B;AACvD,IAAI,0BAA0B;AAM9B,MAAM,sBAAsB,MAAY;AACtC,MAAI,wBAAyB;AAC7B,MAAI;AACF,gBAAY,YAAY,CAAC,MAA0D;AACjF,oBAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,EAAE,UAAU,CAAC,EAAE;AACrD,qBAAe,QAAQ,CAAC,MAAM,EAAE,WAAY,CAAC;AAAA,IAC/C,CAAC;AAAA,EACH,QAAQ;AACN;AAAA,EACF;AACA,4BAA0B;AAC5B;AAYA,oBAAoB;AAKb,MAAM,eAAe,MAAwB;AAClD,sBAAoB;AACpB,SAAO;AACT;AAaA,MAAM,gBAAgB,MAAe;AACnC,MAAI;AACF,cAAU;AACV,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAeO,MAAM,eAAe,CAAC,WAA0B;AACrD,MAAI,CAAC,cAAc,EAAG;AAEtB,cAAY,eAAe,EAAE,OAAO,CAAC;AACvC;AAKO,MAAM,aAAa,MAAY;AACpC,MAAI,CAAC,cAAc,EAAG;AACtB,cAAY,aAAa,CAAC,CAAC;AAC7B;AAKO,MAAM,eAAe,MAAwB;AAClD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA2B,YAAY;AACjE,YAAU,MAAM;AACd,UAAM,IAAI,CAAC,MAAiB,SAAS,CAAC;AACtC,mBAAe,IAAI,CAAC;AACpB,QAAI,YAAa,UAAS,WAAW;AACrC,WAAO,MAAM;AACX,qBAAe,OAAO,CAAC;AAAA,IACzB;AAAA,EACF,GAAG,CAAC,CAAC;AACL,SAAO;AACT;","names":[]}

package/dist/version.cjs

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

package/dist/version.cjs.map

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

package/dist/version.d.cts

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

package/dist/version.d.ts

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

package/dist/version.js

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

package/dist/version.js.map

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

package/dist/workspace.cjs

@@ -0,0 +1,53 @@
+"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 workspace_exports = {};
+__export(workspace_exports, {
+  getWorkspace: () => getWorkspace,
+  onWorkspaceChange: () => onWorkspaceChange,
+  useWorkspace: () => useWorkspace
+});
+module.exports = __toCommonJS(workspace_exports);
+var import_pushChannel = require("./pushChannel");
+var import_protocol = require("./generated/protocol");
+const DEFAULT_WORKSPACE = null;
+const isWorkspace = (v) => {
+  const w = v;
+  return !!w && typeof w === "object" && typeof w.provider === "string" && typeof w.namespace === "string" && typeof w.repository === "string" && typeof w.ref === "string" && typeof w.label === "string";
+};
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: import_protocol.WORKSPACE,
+  requestType: import_protocol.REQUEST_WORKSPACE,
+  initial: DEFAULT_WORKSPACE,
+  parse: (msg) => {
+    if (msg.workspace === null) return null;
+    if (!isWorkspace(msg.workspace)) return void 0;
+    const { provider, namespace, repository, ref, label } = msg.workspace;
+    return { provider, namespace, repository, ref, label };
+  }
+});
+const getWorkspace = () => channel.get();
+const onWorkspaceChange = (listener) => channel.onChange(listener);
+const useWorkspace = () => channel.use();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getWorkspace,
+  onWorkspaceChange,
+  useWorkspace
+});
+//# sourceMappingURL=workspace.cjs.map

package/dist/workspace.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { WORKSPACE, REQUEST_WORKSPACE } from './generated/protocol';\n\n/**\n * Which project the immediately.run workbench currently has open — the repository\n * the user is editing, not your app's own repository. `null` when your app is not\n * running inside an editing session at all (a standalone full-tab route, a task\n * overlay): that is a real answer, not a failure, and code here must handle it.\n *\n * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is\n * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`\n * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:\n * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.\n *\n * Baseline capability `workspace:read` — every app may read it. It discloses\n * nothing that is not already in the session URL your app can read from\n * {@link onUrlChange} when it drives the host route; this channel exists for the\n * apps that *don't* — a self-routed panel keeps its own route, never receives\n * `urlchange`, and would otherwise have no way to learn which project it is in.\n *\n * There is deliberately no counterpart that lets an app *change* the workspace:\n * navigating the workbench stays a host action under the ordinary consent.\n *\n * ```ts\n * import { useWorkspace } from '@immediately-run/sdk';\n *\n * const workspace = useWorkspace();\n * // Scope your app's stored data to the project it belongs to.\n * const scope = workspace?.label ?? null;\n * ```\n */\nexport interface Workspace {\n  /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */\n  provider: string;\n  /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */\n  namespace: string;\n  /** Repository/project segment. */\n  repository: string;\n  /** The branch, tag, or ref-shaped segment of the session. */\n  ref: string;\n  /**\n   * The session's display identity, `` `${namespace}/${repository}` `` — e.g.\n   * `neumark-family/recipes`.\n   *\n   * This is the string to key durable per-project data on. It is the SAME value the\n   * host labels the working-tree mount with, so an app that already scopes by that\n   * mount's label needs no migration to move onto this channel.\n   */\n  label: string;\n}\n\n/**\n * Assumed before the host reports — and the value that stands forever on a host too\n * old to push this channel. `null` means \"no project here\", which is also the honest\n * answer outside an editing session, so an app written against it degrades to\n * unscoped rather than to wrong.\n */\nconst DEFAULT_WORKSPACE: Workspace | null = null;\n\nconst isWorkspace = (v: unknown): v is Workspace => {\n  const w = v as Partial<Workspace> | null;\n  return (\n    !!w &&\n    typeof w === 'object' &&\n    typeof w.provider === 'string' &&\n    typeof w.namespace === 'string' &&\n    typeof w.repository === 'string' &&\n    typeof w.ref === 'string' &&\n    typeof w.label === 'string'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `workspace` and\n// answers `request-workspace` (wire format: site-main channelBridge.ts).\n//\n// `parse` must distinguish the host SAYING `null` from a message it cannot read.\n// `undefined` means \"not a value for this channel\" (createPushChannel ignores it and\n// keeps the last known workspace), while `null` is the host reporting \"no session\"\n// and MUST land — otherwise a frame that navigates out of a session would keep\n// reporting the project it used to be in.\n//\n// It REBUILDS the value field by field rather than passing the host's object through.\n// This channel is baseline-readable by every app, so \"it carries only the session's\n// coordinates\" has to be a property of this code, not of the host's good manners: a\n// host that pushed a token or a user id alongside them would otherwise get it into\n// app-visible memory by reference.\nconst channel = createPushChannel<Workspace | null>({\n  pushType: WORKSPACE,\n  requestType: REQUEST_WORKSPACE,\n  initial: DEFAULT_WORKSPACE,\n  parse: (msg) => {\n    if (msg.workspace === null) return null;\n    if (!isWorkspace(msg.workspace)) return undefined;\n    const { provider, namespace, repository, ref, label } = msg.workspace;\n    return { provider, namespace, repository, ref, label };\n  },\n});\n\n/** Returns the current workspace, or `null` outside an editing session. */\nexport const getWorkspace = (): Workspace | null => channel.get();\n\n/**\n * Subscribe to workspace changes. The listener is invoked immediately with the\n * current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onWorkspaceChange = (listener: (workspace: Workspace | null) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current workspace, re-rendering on change. */\nexport const useWorkspace = (): Workspace | null => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAClC,sBAA6C;AAwD7C,MAAM,oBAAsC;AAE5C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,KACF,OAAO,MAAM,YACb,OAAO,EAAE,aAAa,YACtB,OAAO,EAAE,cAAc,YACvB,OAAO,EAAE,eAAe,YACxB,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,UAAU;AAEvB;AAgBA,MAAM,cAAU,sCAAoC;AAAA,EAClD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AACd,QAAI,IAAI,cAAc,KAAM,QAAO;AACnC,QAAI,CAAC,YAAY,IAAI,SAAS,EAAG,QAAO;AACxC,UAAM,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM,IAAI,IAAI;AAC5D,WAAO,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM;AAAA,EACvD;AACF,CAAC;AAGM,MAAM,eAAe,MAAwB,QAAQ,IAAI;AAMzD,MAAM,oBAAoB,CAAC,aAChC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,eAAe,MAAwB,QAAQ,IAAI;","names":[]}

package/dist/workspace.d.cts

@@ -0,0 +1,58 @@
+/**
+ * Which project the immediately.run workbench currently has open — the repository
+ * the user is editing, not your app's own repository. `null` when your app is not
+ * running inside an editing session at all (a standalone full-tab route, a task
+ * overlay): that is a real answer, not a failure, and code here must handle it.
+ *
+ * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is
+ * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`
+ * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:
+ * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.
+ *
+ * Baseline capability `workspace:read` — every app may read it. It discloses
+ * nothing that is not already in the session URL your app can read from
+ * {@link onUrlChange} when it drives the host route; this channel exists for the
+ * apps that *don't* — a self-routed panel keeps its own route, never receives
+ * `urlchange`, and would otherwise have no way to learn which project it is in.
+ *
+ * There is deliberately no counterpart that lets an app *change* the workspace:
+ * navigating the workbench stays a host action under the ordinary consent.
+ *
+ * ```ts
+ * import { useWorkspace } from '@immediately-run/sdk';
+ *
+ * const workspace = useWorkspace();
+ * // Scope your app's stored data to the project it belongs to.
+ * const scope = workspace?.label ?? null;
+ * ```
+ */
+interface Workspace {
+    /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */
+    provider: string;
+    /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */
+    namespace: string;
+    /** Repository/project segment. */
+    repository: string;
+    /** The branch, tag, or ref-shaped segment of the session. */
+    ref: string;
+    /**
+     * The session's display identity, `` `${namespace}/${repository}` `` — e.g.
+     * `neumark-family/recipes`.
+     *
+     * This is the string to key durable per-project data on. It is the SAME value the
+     * host labels the working-tree mount with, so an app that already scopes by that
+     * mount's label needs no migration to move onto this channel.
+     */
+    label: string;
+}
+/** Returns the current workspace, or `null` outside an editing session. */
+declare const getWorkspace: () => Workspace | null;
+/**
+ * Subscribe to workspace changes. The listener is invoked immediately with the
+ * current value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onWorkspaceChange: (listener: (workspace: Workspace | null) => void) => (() => void);
+/** React hook returning the current workspace, re-rendering on change. */
+declare const useWorkspace: () => Workspace | null;
+
+export { type Workspace, getWorkspace, onWorkspaceChange, useWorkspace };

package/dist/workspace.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which project the immediately.run workbench currently has open — the repository
+ * the user is editing, not your app's own repository. `null` when your app is not
+ * running inside an editing session at all (a standalone full-tab route, a task
+ * overlay): that is a real answer, not a failure, and code here must handle it.
+ *
+ * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is
+ * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`
+ * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:
+ * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.
+ *
+ * Baseline capability `workspace:read` — every app may read it. It discloses
+ * nothing that is not already in the session URL your app can read from
+ * {@link onUrlChange} when it drives the host route; this channel exists for the
+ * apps that *don't* — a self-routed panel keeps its own route, never receives
+ * `urlchange`, and would otherwise have no way to learn which project it is in.
+ *
+ * There is deliberately no counterpart that lets an app *change* the workspace:
+ * navigating the workbench stays a host action under the ordinary consent.
+ *
+ * ```ts
+ * import { useWorkspace } from '@immediately-run/sdk';
+ *
+ * const workspace = useWorkspace();
+ * // Scope your app's stored data to the project it belongs to.
+ * const scope = workspace?.label ?? null;
+ * ```
+ */
+interface Workspace {
+    /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */
+    provider: string;
+    /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */
+    namespace: string;
+    /** Repository/project segment. */
+    repository: string;
+    /** The branch, tag, or ref-shaped segment of the session. */
+    ref: string;
+    /**
+     * The session's display identity, `` `${namespace}/${repository}` `` — e.g.
+     * `neumark-family/recipes`.
+     *
+     * This is the string to key durable per-project data on. It is the SAME value the
+     * host labels the working-tree mount with, so an app that already scopes by that
+     * mount's label needs no migration to move onto this channel.
+     */
+    label: string;
+}
+/** Returns the current workspace, or `null` outside an editing session. */
+declare const getWorkspace: () => Workspace | null;
+/**
+ * Subscribe to workspace changes. The listener is invoked immediately with the
+ * current value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onWorkspaceChange: (listener: (workspace: Workspace | null) => void) => (() => void);
+/** React hook returning the current workspace, re-rendering on change. */
+declare const useWorkspace: () => Workspace | null;
+
+export { type Workspace, getWorkspace, onWorkspaceChange, useWorkspace };

package/dist/workspace.js

@@ -0,0 +1,28 @@
+import "./chunk-VHAA22YE.js";
+import { createPushChannel } from "./pushChannel";
+import { WORKSPACE, REQUEST_WORKSPACE } from "./generated/protocol";
+const DEFAULT_WORKSPACE = null;
+const isWorkspace = (v) => {
+  const w = v;
+  return !!w && typeof w === "object" && typeof w.provider === "string" && typeof w.namespace === "string" && typeof w.repository === "string" && typeof w.ref === "string" && typeof w.label === "string";
+};
+const channel = createPushChannel({
+  pushType: WORKSPACE,
+  requestType: REQUEST_WORKSPACE,
+  initial: DEFAULT_WORKSPACE,
+  parse: (msg) => {
+    if (msg.workspace === null) return null;
+    if (!isWorkspace(msg.workspace)) return void 0;
+    const { provider, namespace, repository, ref, label } = msg.workspace;
+    return { provider, namespace, repository, ref, label };
+  }
+});
+const getWorkspace = () => channel.get();
+const onWorkspaceChange = (listener) => channel.onChange(listener);
+const useWorkspace = () => channel.use();
+export {
+  getWorkspace,
+  onWorkspaceChange,
+  useWorkspace
+};
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { WORKSPACE, REQUEST_WORKSPACE } from './generated/protocol';\n\n/**\n * Which project the immediately.run workbench currently has open — the repository\n * the user is editing, not your app's own repository. `null` when your app is not\n * running inside an editing session at all (a standalone full-tab route, a task\n * overlay): that is a real answer, not a failure, and code here must handle it.\n *\n * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is\n * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`\n * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:\n * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.\n *\n * Baseline capability `workspace:read` — every app may read it. It discloses\n * nothing that is not already in the session URL your app can read from\n * {@link onUrlChange} when it drives the host route; this channel exists for the\n * apps that *don't* — a self-routed panel keeps its own route, never receives\n * `urlchange`, and would otherwise have no way to learn which project it is in.\n *\n * There is deliberately no counterpart that lets an app *change* the workspace:\n * navigating the workbench stays a host action under the ordinary consent.\n *\n * ```ts\n * import { useWorkspace } from '@immediately-run/sdk';\n *\n * const workspace = useWorkspace();\n * // Scope your app's stored data to the project it belongs to.\n * const scope = workspace?.label ?? null;\n * ```\n */\nexport interface Workspace {\n  /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */\n  provider: string;\n  /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */\n  namespace: string;\n  /** Repository/project segment. */\n  repository: string;\n  /** The branch, tag, or ref-shaped segment of the session. */\n  ref: string;\n  /**\n   * The session's display identity, `` `${namespace}/${repository}` `` — e.g.\n   * `neumark-family/recipes`.\n   *\n   * This is the string to key durable per-project data on. It is the SAME value the\n   * host labels the working-tree mount with, so an app that already scopes by that\n   * mount's label needs no migration to move onto this channel.\n   */\n  label: string;\n}\n\n/**\n * Assumed before the host reports — and the value that stands forever on a host too\n * old to push this channel. `null` means \"no project here\", which is also the honest\n * answer outside an editing session, so an app written against it degrades to\n * unscoped rather than to wrong.\n */\nconst DEFAULT_WORKSPACE: Workspace | null = null;\n\nconst isWorkspace = (v: unknown): v is Workspace => {\n  const w = v as Partial<Workspace> | null;\n  return (\n    !!w &&\n    typeof w === 'object' &&\n    typeof w.provider === 'string' &&\n    typeof w.namespace === 'string' &&\n    typeof w.repository === 'string' &&\n    typeof w.ref === 'string' &&\n    typeof w.label === 'string'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `workspace` and\n// answers `request-workspace` (wire format: site-main channelBridge.ts).\n//\n// `parse` must distinguish the host SAYING `null` from a message it cannot read.\n// `undefined` means \"not a value for this channel\" (createPushChannel ignores it and\n// keeps the last known workspace), while `null` is the host reporting \"no session\"\n// and MUST land — otherwise a frame that navigates out of a session would keep\n// reporting the project it used to be in.\n//\n// It REBUILDS the value field by field rather than passing the host's object through.\n// This channel is baseline-readable by every app, so \"it carries only the session's\n// coordinates\" has to be a property of this code, not of the host's good manners: a\n// host that pushed a token or a user id alongside them would otherwise get it into\n// app-visible memory by reference.\nconst channel = createPushChannel<Workspace | null>({\n  pushType: WORKSPACE,\n  requestType: REQUEST_WORKSPACE,\n  initial: DEFAULT_WORKSPACE,\n  parse: (msg) => {\n    if (msg.workspace === null) return null;\n    if (!isWorkspace(msg.workspace)) return undefined;\n    const { provider, namespace, repository, ref, label } = msg.workspace;\n    return { provider, namespace, repository, ref, label };\n  },\n});\n\n/** Returns the current workspace, or `null` outside an editing session. */\nexport const getWorkspace = (): Workspace | null => channel.get();\n\n/**\n * Subscribe to workspace changes. The listener is invoked immediately with the\n * current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onWorkspaceChange = (listener: (workspace: Workspace | null) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current workspace, re-rendering on change. */\nexport const useWorkspace = (): Workspace | null => channel.use();\n"],"mappings":";AAAA,SAAS,yBAAyB;AAClC,SAAS,WAAW,yBAAyB;AAwD7C,MAAM,oBAAsC;AAE5C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,KACF,OAAO,MAAM,YACb,OAAO,EAAE,aAAa,YACtB,OAAO,EAAE,cAAc,YACvB,OAAO,EAAE,eAAe,YACxB,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,UAAU;AAEvB;AAgBA,MAAM,UAAU,kBAAoC;AAAA,EAClD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AACd,QAAI,IAAI,cAAc,KAAM,QAAO;AACnC,QAAI,CAAC,YAAY,IAAI,SAAS,EAAG,QAAO;AACxC,UAAM,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM,IAAI,IAAI;AAC5D,WAAO,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM;AAAA,EACvD;AACF,CAAC;AAGM,MAAM,eAAe,MAAwB,QAAQ,IAAI;AAMzD,MAAM,oBAAoB,CAAC,aAChC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,eAAe,MAAwB,QAAQ,IAAI;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.57.1",
+  "version": "0.58.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -39,11 +39,12 @@
     "api:update": "node scripts/check-api-stability.mjs --update",
     "check:pins": "node scripts/check-dependency-pins.mjs --self-test && node scripts/check-dependency-pins.mjs",
     "check:publish-version": "node scripts/check-publish-version.mjs --self-test && node scripts/check-publish-version.mjs",
-    "verify": "npm run check:pins && npm run check:publish-version && npm run format:check && npm run check:circular && npm run check:bundler:selftest && npm run check:bundler && npm run build && npm test && npm run test:safe-content && npm run test:metadata-e2e && npm run api:selftest && npm run api:check && npm run compat:selftest && npm run compat:previous && npm run protocol:check && npm run protocol:selftest && npm run check:ambient:selftest && npm run check:ambient && npm run check:selfhost:selftest && npm run check:selfhost && npm run verify:codegen-parity",
+    "verify": "npm run check:pins && npm run check:publish-version && npm run format:check && npm run check:circular && npm run check:bundler:selftest && npm run check:bundler && npm run build && npm test && npm run test:safe-content && npm run test:metadata-e2e && npm run test:subpath-imports && npm run api:selftest && npm run api:check && npm run compat:selftest && npm run compat:previous && npm run protocol:check && npm run protocol:selftest && npm run check:ambient:selftest && npm run check:ambient && npm run check:selfhost:selftest && npm run check:selfhost && npm run verify:codegen-parity",
     "docs": "typedoc --json docs/api.json && node scripts/gen-llms.mjs",
     "prepublishOnly": "npm run check:circular && npm run build && npm run api:selftest && npm run api:check",
     "test:safe-content": "node scripts/build-safecontent-e2e.mjs && node --test test/safeContent.e2e.mjs",
     "test:metadata-e2e": "node --test test/metadataHooks.e2e.mjs",
+    "test:subpath-imports": "node --test test/subpathImports.e2e.mjs",
     "protocol:selftest": "node scripts/check-protocol-snapshot.mjs --self-test",
     "compat:previous": "node scripts/check-previous-sdk-compat.mjs",
     "compat:selftest": "node scripts/check-previous-sdk-compat.mjs --self-test",
@@ -60,11 +61,11 @@
     "react-dom": "^19.0.0"
   },
   "dependencies": {
+    "@immediately-run/mdx-plugins": "0.5.0",
     "@immediately-run/platform-constants": "0.2.0",
-    "@immediately-run/sandbox-protocol": "0.7.1",
-    "react-error-boundary": "^6.0.0",
     "@immediately-run/safe-content": "0.1.0",
-    "@immediately-run/mdx-plugins": "0.5.0"
+    "@immediately-run/sandbox-protocol": "0.7.7",
+    "react-error-boundary": "^6.0.0"
   },
   "devDependencies": {
     "@immediately-run/prettier-config": "0.1.0",