@immediately-run/sdk 0.45.3 → 0.47.0

package/dist/fs.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fs.ts"],"sourcesContent":["// Typed, discoverable filesystem access — the app-facing surface for the ZenFS\n// mount ports (SDK_FS_SURFACE_SPEC; FILESYSTEM_SPEC §2 the ZenFS-shaped contract).\n//\n// The single most important thing an app does — read/write files in its mounts —\n// previously had NO SDK surface: apps reached an ambient `globalThis.__sandpackSharedFs`\n// by hand-rolling the same accessor (editor/file-explorer `src/fs/mountFs.ts`, \"keep the\n// two in sync\"), with a documented footgun (`module.evaluation.module.bundler.fs` is the\n// WRONG object — it has no `promises`/`stat`). This module is that accessor's ONE home,\n// typed and documented.\n//\n// It adds NO authority: the ZenFS port is already minted and chroot/`ro`-enforced\n// host-side (FILESYSTEM_SPEC §2, UI_AS_APPS §8.7). This is typing + discoverability +\n// de-duplication only. `fs` is a Resource PORT (a byte channel), not a host-brokered RPC,\n// so — unlike the `invoke()` catalog surface — it is hand-written, not gate-table-derived.\nimport type { SandboxMount, MountRule } from './mounts';\nimport { getAppMountPath } from './mounts';\nimport { onFsChange } from './onFsChange';\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */\ninterface NodeFsPromises {\n  readFile(path: string, encoding?: any): Promise<string | Uint8Array>;\n  writeFile(path: string, data: string | Uint8Array): Promise<void>;\n  readdir(path: string, opts?: any): Promise<any[]>;\n  stat(path: string): Promise<any>;\n  mkdir(path: string, opts?: any): Promise<unknown>;\n  rm(path: string, opts?: any): Promise<void>;\n  rename(from: string, to: string): Promise<void>;\n}\n\n/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —\n *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */\nexport interface SandboxFsPort {\n  promises?: NodeFsPromises;\n  readFile?: NodeFsPromises['readFile'];\n}\n\nconst hasFs = (fs: any): boolean =>\n  typeof fs?.promises?.readFile === 'function' || typeof fs?.readFile === 'function';\n\n/**\n * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the\n * resolution order previously duplicated in every app's `mountFs.ts`:\n *\n * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.\n * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`\n *    whose surface has `readFile` (the bundler ZenFS-layer bound context).\n * 3. else `null` (local `vite dev` / before boot).\n *\n * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute\n * `/mnt/{hash}` paths (the file explorer / editor).\n */\nexport function sandboxFs(): SandboxFsPort | null {\n  try {\n    const shared = (globalThis as any).__sandpackSharedFs;\n    if (hasFs(shared)) return shared as SandboxFsPort;\n  } catch {\n    /* not in the sandbox */\n  }\n  try {\n    // @ts-ignore - `module` is injected by the sandbox runtime (see sandboxUtils transport).\n    const layers = module?.evaluation?.module?.bundler?.fs?.layers;\n    if (Array.isArray(layers)) {\n      for (const layer of layers) {\n        const fs = layer?.boundContext?.fs;\n        if (hasFs(fs)) return fs as SandboxFsPort;\n      }\n    }\n  } catch {\n    /* not in the sandbox */\n  }\n  return null;\n}\n\n/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before\n *  boot — gate file affordances on it so an app degrades instead of throwing. */\nexport function fsAvailable(): boolean {\n  return sandboxFs() != null;\n}\n\n/** A directory entry from {@link MountFs.readdir}. */\nexport interface DirEntry {\n  name: string;\n  kind: 'file' | 'dir';\n}\n\n/** A stat result from {@link MountFs.stat}. */\nexport interface FileStat {\n  kind: 'file' | 'dir';\n  size: number;\n  mtimeMs?: number;\n}\n\n/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`\n *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */\nexport interface FsError extends Error {\n  code:\n    | 'not-found' // ENOENT\n    | 'read-only' // EROFS — a `ro` mount / downgraded role; NEVER surface as UX (gate with canWrite)\n    | 'not-permitted' // EACCES\n    | 'exists' // EEXIST\n    | 'not-empty' // ENOTEMPTY\n    | 'invalid-path' // a `..` segment / absolute escape was passed as a relPath\n    | 'unavailable' // no sandbox fs (local dev / pre-boot)\n    | 'unknown';\n}\n\nconst ERRNO: Record<string, FsError['code']> = {\n  ENOENT: 'not-found',\n  EROFS: 'read-only',\n  EACCES: 'not-permitted',\n  EPERM: 'not-permitted',\n  EEXIST: 'exists',\n  ENOTEMPTY: 'not-empty',\n};\n\nconst fsError = (code: FsError['code'], message: string): FsError => {\n  const err = new Error(message) as FsError;\n  err.code = code;\n  return err;\n};\n\nconst mapError = (e: unknown): FsError => {\n  const errno = (e as { code?: string } | null)?.code;\n  const code: FsError['code'] = (errno ? ERRNO[errno] : undefined) ?? 'unknown';\n  const err = new Error((e as Error)?.message ?? 'fs operation failed') as FsError;\n  err.code = code;\n  return err;\n};\n\n// Lazily constructed so merely *importing* this module doesn't touch the\n// TextEncoder/TextDecoder globals — some non-DOM test/build environments only\n// provide them on demand, and no image/URL path needs them at all.\nlet _decoder: TextDecoder | undefined;\nlet _encoder: TextEncoder | undefined;\nconst decoder = (): TextDecoder => (_decoder ??= new TextDecoder());\nconst encoder = (): TextEncoder => (_encoder ??= new TextEncoder());\n\n// Extension → MIME type for the kinds an app displays inline. Images first (the\n// common case — `<img src>` off a mount), plus a couple of adjacent binary kinds.\n// Deliberately small: `mimeTypeFor` returns undefined for anything not here and\n// callers fall back to `application/octet-stream`.\nconst MIME_BY_EXT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  gif: 'image/gif',\n  webp: 'image/webp',\n  avif: 'image/avif',\n  svg: 'image/svg+xml',\n  bmp: 'image/bmp',\n  ico: 'image/x-icon',\n};\n\n/**\n * Best-effort MIME type from a filename's extension — mainly image kinds\n * (png/jpg/jpeg/gif/webp/avif/svg/bmp/ico). Returns `undefined` when the\n * extension isn't recognized (the caller falls back to `application/octet-stream`).\n * Used by {@link MountFs.readBlob} / {@link MountFs.readObjectUrl}; exported so an\n * app can label a Blob it builds itself.\n */\nexport function mimeTypeFor(path: string): string | undefined {\n  const dot = path.lastIndexOf('.');\n  if (dot < 0) return undefined;\n  return MIME_BY_EXT[path.slice(dot + 1).toLowerCase()];\n}\n\n// Join a mount-RELATIVE path under the mount root, rejecting `..` escapes and absolute\n// paths (CLAUDE.md security rule 3 — don't probe for escapes). The host chroot is the\n// real enforcer; this keeps an honest app from accidentally naming outside its grant.\nconst resolveUnder = (root: string, relPath: string): string => {\n  if (relPath.startsWith('/')) {\n    throw fsError('invalid-path', `expected a mount-relative path, got absolute \"${relPath}\"`);\n  }\n  const parts: string[] = [];\n  for (const seg of relPath.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') {\n      throw fsError('invalid-path', `\"${relPath}\" escapes the mount root`);\n    }\n    parts.push(seg);\n  }\n  const base = root.endsWith('/') ? root.slice(0, -1) : root;\n  return parts.length ? `${base}/${parts.join('/')}` : base;\n};\n\n// The longest matching `rules` subtree governs a path (mounts.ts MountRule); fall back to\n// the whole-mount `mode`. A CLIENT-SIDE hint mirroring the host rule — EROFS stays\n// authoritative (the host re-checks live policy on every write).\nconst writableAt = (mount: SandboxMount, relPath: string): boolean => {\n  const path = '/' + relPath.split('/').filter((s) => s && s !== '.').join('/');\n  const rules: MountRule[] | undefined = mount.rules;\n  if (rules && rules.length) {\n    let best: MountRule | undefined;\n    for (const r of rules) {\n      const sub = r.subtree.endsWith('/') ? r.subtree : r.subtree + '/';\n      if (path === r.subtree || path.startsWith(sub) || r.subtree === '/') {\n        if (!best || r.subtree.length > best.subtree.length) best = r;\n      }\n    }\n    if (best) return best.mode === 'rw';\n  }\n  return (mount.mode ?? 'rw') === 'rw';\n};\n\n/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;\n *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).\n *  Obtain one with {@link openFs}. */\nexport interface MountFs {\n  /** The mount this view is anchored to (read `mode`/`rules` for writability). */\n  readonly mount: SandboxMount;\n  /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */\n  readFile(relPath: string, encoding: 'utf8'): Promise<string>;\n  readFile(relPath: string): Promise<Uint8Array>;\n  /** Read a file's bytes as a `Blob`, tagged with a MIME `type` inferred from the\n   *  extension ({@link mimeTypeFor}) or `opts.type` when given (falls back to\n   *  `application/octet-stream`). The building block for downloads and object URLs. */\n  readBlob(relPath: string, opts?: { type?: string }): Promise<Blob>;\n  /** Read a file into an **object URL** suitable for `<img src>` / `<a href>` — the\n   *  fix for \"an opaque-origin iframe can't fetch a mount path\". Returns the `url`\n   *  and a `revoke()` you MUST call when done (typically on unmount) or the URL\n   *  leaks. Prefer the `useObjectUrl` hook / `MountImage` component, which revoke\n   *  for you; reach for this directly only outside React. */\n  readObjectUrl(\n    relPath: string,\n    opts?: { type?: string },\n  ): Promise<{ url: string; revoke: () => void }>;\n  /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */\n  writeFile(relPath: string, data: string | Uint8Array): Promise<void>;\n  /** List a directory (the mount root when `relPath` is omitted). */\n  readdir(relPath?: string): Promise<DirEntry[]>;\n  /** Stat a path. Throws `not-found` if absent. */\n  stat(relPath: string): Promise<FileStat>;\n  /** Does `relPath` exist? Never throws on absence. */\n  exists(relPath: string): Promise<boolean>;\n  /** Create a directory (pass `{ recursive: true }` to make parents). */\n  mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Remove a file, or a directory with `{ recursive: true }`. */\n  rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Rename/move within the mount. */\n  rename(fromRel: string, toRel: string): Promise<void>;\n  /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),\n   *  so an app can hide an \"edit\" affordance instead of catching `read-only`\n   *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade\n   *  flips it. EROFS from the host stays authoritative. */\n  canWrite(relPath?: string): boolean;\n  /** Subscribe to changes to files in this mount — the mount-scoped projection of\n   *  the host working-tree change stream (`onFsChange`), so a viewer re-reads an\n   *  affected file instead of polling (SDK_FS_SURFACE_SPEC §5). The callback gets\n   *  the changed paths RELATIVE to this mount (feed them straight back into\n   *  `readFile`/`stat`/…). Returns an unsubscribe fn.\n   *\n   *  **Working-tree-only in v1 (an honest gap, O2):** the host push channel carries\n   *  only working-tree changes, so `onChange` on a NON-working-tree mount (a space)\n   *  is an inert subscription that never fires until that channel lands. Like\n   *  `onFsChange`, origin-exclusion (ignoring the echo of your own write) is the\n   *  caller's responsibility. */\n  onChange(cb: (changedRelPaths: string[]) => void): () => void;\n}\n\nconst promisesOf = (port: SandboxFsPort): NodeFsPromises =>\n  (port.promises ?? (port as unknown as NodeFsPromises));\n\n/**\n * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:\n * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you\n * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path\n * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the\n * real enforcer).\n *\n * ```ts\n * import { mountSpace } from '@immediately-run/sdk';\n * import { openFs } from '@immediately-run/sdk/fs';\n * const fs = openFs(await mountSpace({ spaceId }));\n * const text = await fs.readFile('notes/idea.mdx', 'utf8');\n * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);\n * ```\n *\n * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`\n * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}\n * with a mapped `.code` (`not-found`, `read-only`, …).\n */\nexport function openFs(mount: SandboxMount): MountFs {\n  const root = mount.path;\n\n  const port = (): NodeFsPromises => {\n    const p = sandboxFs();\n    if (!p) throw fsError('unavailable', 'immediately.run: sandbox filesystem unavailable');\n    return promisesOf(p);\n  };\n\n  const api: MountFs = {\n    mount,\n    async readFile(relPath: string, encoding?: 'utf8'): Promise<any> {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const data = await p.readFile(abs);\n        const bytes =\n          typeof data === 'string' ? encoder().encode(data) : (data as Uint8Array);\n        return encoding === 'utf8' ? decoder().decode(bytes) : bytes;\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readBlob(relPath, opts) {\n      const bytes = await api.readFile(relPath);\n      const type = opts?.type ?? mimeTypeFor(relPath) ?? 'application/octet-stream';\n      return new Blob([bytes as BlobPart], { type });\n    },\n    async readObjectUrl(relPath, opts) {\n      const blob = await api.readBlob(relPath, opts);\n      const url = URL.createObjectURL(blob);\n      return { url, revoke: () => URL.revokeObjectURL(url) };\n    },\n    async writeFile(relPath, data) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.writeFile(abs, typeof data === 'string' ? encoder().encode(data) : data);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readdir(relPath = '') {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const entries = await p.readdir(abs, { withFileTypes: true });\n        return entries.map((d: any) =>\n          typeof d === 'string'\n            ? ({ name: d, kind: 'file' } as DirEntry)\n            : ({ name: d.name, kind: d.isDirectory?.() ? 'dir' : 'file' } as DirEntry),\n        );\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async stat(relPath) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const s: any = await p.stat(abs);\n        return {\n          kind: s.isDirectory?.() ? 'dir' : 'file',\n          size: typeof s.size === 'number' ? s.size : 0,\n          mtimeMs: typeof s.mtimeMs === 'number' ? s.mtimeMs : undefined,\n        };\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async exists(relPath) {\n      try {\n        await api.stat(relPath);\n        return true;\n      } catch (e) {\n        if ((e as FsError).code === 'not-found') return false;\n        if ((e as FsError).code === 'unavailable' || (e as FsError).code === 'invalid-path') {\n          throw e;\n        }\n        return false;\n      }\n    },\n    async mkdir(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.mkdir(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rm(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.rm(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rename(fromRel, toRel) {\n      const p = port();\n      const from = resolveUnder(root, fromRel);\n      const to = resolveUnder(root, toRel);\n      try {\n        await p.rename(from, to);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    canWrite(relPath = '') {\n      return writableAt(mount, relPath);\n    },\n    onChange(cb) {\n      // §5 — mount-scoped projection of the working-tree change channel\n      // (`onFsChange`). v1 is WORKING-TREE-ONLY: the host pushes only working-tree\n      // changes, so a non-working-tree mount (a space) has no channel yet (O2) and\n      // gets an inert subscription rather than another mount's paths leaking in.\n      if (root !== getAppMountPath()) {\n        return () => {}; // no channel for this mount — inert (honest v1 gap)\n      }\n      return onFsChange((change) => {\n        // Skip the empty pre-first-event initial batch; forward only real changes,\n        // as mount-relative paths (drop the repo-relative leading slash) so they\n        // feed straight back into readFile/stat/etc.\n        if (change.paths.length === 0) return;\n        cb(change.paths.map((p) => p.replace(/^\\/+/, '')));\n      });\n    },\n  };\n  return api;\n}\n\n/** Open a mount-anchored view of this app's OWN repository working tree — a convenience\n *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */\nexport function openAppFs(): MountFs {\n  return openFs({ path: getAppMountPath(), type: 'repo' } as SandboxMount);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,oBAAgC;AAChC,wBAA2B;AAsB3B,MAAM,QAAQ,CAAC,OACb,OAAO,IAAI,UAAU,aAAa,cAAc,OAAO,IAAI,aAAa;AAcnE,SAAS,YAAkC;AAChD,MAAI;AACF,UAAM,SAAU,WAAmB;AACnC,QAAI,MAAM,MAAM,EAAG,QAAO;AAAA,EAC5B,QAAQ;AAAA,EAER;AACA,MAAI;AAEF,UAAM,SAAS,QAAQ,YAAY,QAAQ,SAAS,IAAI;AACxD,QAAI,MAAM,QAAQ,MAAM,GAAG;AACzB,iBAAW,SAAS,QAAQ;AAC1B,cAAM,KAAK,OAAO,cAAc;AAChC,YAAI,MAAM,EAAE,EAAG,QAAO;AAAA,MACxB;AAAA,IACF;AAAA,EACF,QAAQ;AAAA,EAER;AACA,SAAO;AACT;AAIO,SAAS,cAAuB;AACrC,SAAO,UAAU,KAAK;AACxB;AA6BA,MAAM,QAAyC;AAAA,EAC7C,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,WAAW;AACb;AAEA,MAAM,UAAU,CAAC,MAAuB,YAA6B;AACnE,QAAM,MAAM,IAAI,MAAM,OAAO;AAC7B,MAAI,OAAO;AACX,SAAO;AACT;AAEA,MAAM,WAAW,CAAC,MAAwB;AACxC,QAAM,QAAS,GAAgC;AAC/C,QAAM,QAAyB,QAAQ,MAAM,KAAK,IAAI,WAAc;AACpE,QAAM,MAAM,IAAI,MAAO,GAAa,WAAW,qBAAqB;AACpE,MAAI,OAAO;AACX,SAAO;AACT;AAKA,IAAI;AACJ,IAAI;AACJ,MAAM,UAAU,MAAoB,wBAAa,IAAI,YAAY;AACjE,MAAM,UAAU,MAAoB,wBAAa,IAAI,YAAY;AAMjE,MAAM,cAAsC;AAAA,EAC1C,KAAK;AAAA,EACL,KAAK;AAAA,EACL,MAAM;AAAA,EACN,KAAK;AAAA,EACL,MAAM;AAAA,EACN,MAAM;AAAA,EACN,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AACP;AASO,SAAS,YAAY,MAAkC;AAC5D,QAAM,MAAM,KAAK,YAAY,GAAG;AAChC,MAAI,MAAM,EAAG,QAAO;AACpB,SAAO,YAAY,KAAK,MAAM,MAAM,CAAC,EAAE,YAAY,CAAC;AACtD;AAKA,MAAM,eAAe,CAAC,MAAc,YAA4B;AAC9D,MAAI,QAAQ,WAAW,GAAG,GAAG;AAC3B,UAAM,QAAQ,gBAAgB,iDAAiD,OAAO,GAAG;AAAA,EAC3F;AACA,QAAM,QAAkB,CAAC;AACzB,aAAW,OAAO,QAAQ,MAAM,GAAG,GAAG;AACpC,QAAI,QAAQ,MAAM,QAAQ,IAAK;AAC/B,QAAI,QAAQ,MAAM;AAChB,YAAM,QAAQ,gBAAgB,IAAI,OAAO,0BAA0B;AAAA,IACrE;AACA,UAAM,KAAK,GAAG;AAAA,EAChB;AACA,QAAM,OAAO,KAAK,SAAS,GAAG,IAAI,KAAK,MAAM,GAAG,EAAE,IAAI;AACtD,SAAO,MAAM,SAAS,GAAG,IAAI,IAAI,MAAM,KAAK,GAAG,CAAC,KAAK;AACvD;AAKA,MAAM,aAAa,CAAC,OAAqB,YAA6B;AACpE,QAAM,OAAO,MAAM,QAAQ,MAAM,GAAG,EAAE,OAAO,CAAC,MAAM,KAAK,MAAM,GAAG,EAAE,KAAK,GAAG;AAC5E,QAAM,QAAiC,MAAM;AAC7C,MAAI,SAAS,MAAM,QAAQ;AACzB,QAAI;AACJ,eAAW,KAAK,OAAO;AACrB,YAAM,MAAM,EAAE,QAAQ,SAAS,GAAG,IAAI,EAAE,UAAU,EAAE,UAAU;AAC9D,UAAI,SAAS,EAAE,WAAW,KAAK,WAAW,GAAG,KAAK,EAAE,YAAY,KAAK;AACnE,YAAI,CAAC,QAAQ,EAAE,QAAQ,SAAS,KAAK,QAAQ,OAAQ,QAAO;AAAA,MAC9D;AAAA,IACF;AACA,QAAI,KAAM,QAAO,KAAK,SAAS;AAAA,EACjC;AACA,UAAQ,MAAM,QAAQ,UAAU;AAClC;AAyDA,MAAM,aAAa,CAAC,SACjB,KAAK,YAAa;AAqBd,SAAS,OAAO,OAA8B;AACnD,QAAM,OAAO,MAAM;AAEnB,QAAM,OAAO,MAAsB;AACjC,UAAM,IAAI,UAAU;AACpB,QAAI,CAAC,EAAG,OAAM,QAAQ,eAAe,iDAAiD;AACtF,WAAO,WAAW,CAAC;AAAA,EACrB;AAEA,QAAM,MAAe;AAAA,IACnB;AAAA,IACA,MAAM,SAAS,SAAiB,UAAiC;AAC/D,YAAM,IAAI,KAAK;AACf,YAAM,MAAM,aAAa,MAAM,OAAO;AACtC,UAAI;AACF,cAAM,OAAO,MAAM,EAAE,SAAS,GAAG;AACjC,cAAM,QACJ,OAAO,SAAS,WAAW,QAAQ,EAAE,OAAO,IAAI,IAAK;AACvD,eAAO,aAAa,SAAS,QAAQ,EAAE,OAAO,KAAK,IAAI;AAAA,MACzD,SAAS,GAAG;AACV,cAAM,SAAS,CAAC;AAAA,MAClB;AAAA,IACF;AAAA,IACA,MAAM,SAAS,SAAS,MAAM;AAC5B,YAAM,QAAQ,MAAM,IAAI,SAAS,OAAO;AACxC,YAAM,OAAO,MAAM,QAAQ,YAAY,OAAO,KAAK;AACnD,aAAO,IAAI,KAAK,CAAC,KAAiB,GAAG,EAAE,KAAK,CAAC;AAAA,IAC/C;AAAA,IACA,MAAM,cAAc,SAAS,MAAM;AACjC,YAAM,OAAO,MAAM,IAAI,SAAS,SAAS,IAAI;AAC7C,YAAM,MAAM,IAAI,gBAAgB,IAAI;AACpC,aAAO,EAAE,KAAK,QAAQ,MAAM,IAAI,gBAAgB,GAAG,EAAE;AAAA,IACvD;AAAA,IACA,MAAM,UAAU,SAAS,MAAM;AAC7B,YAAM,IAAI,KAAK;AACf,YAAM,MAAM,aAAa,MAAM,OAAO;AACtC,UAAI;AACF,cAAM,EAAE,UAAU,KAAK,OAAO,SAAS,WAAW,QAAQ,EAAE,OAAO,IAAI,IAAI,IAAI;AAAA,MACjF,SAAS,GAAG;AACV,cAAM,SAAS,CAAC;AAAA,MAClB;AAAA,IACF;AAAA,IACA,MAAM,QAAQ,UAAU,IAAI;AAC1B,YAAM,IAAI,KAAK;AACf,YAAM,MAAM,aAAa,MAAM,OAAO;AACtC,UAAI;AACF,cAAM,UAAU,MAAM,EAAE,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;AAC5D,eAAO,QAAQ;AAAA,UAAI,CAAC,MAClB,OAAO,MAAM,WACR,EAAE,MAAM,GAAG,MAAM,OAAO,IACxB,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,cAAc,IAAI,QAAQ,OAAO;AAAA,QAChE;AAAA,MACF,SAAS,GAAG;AACV,cAAM,SAAS,CAAC;AAAA,MAClB;AAAA,IACF;AAAA,IACA,MAAM,KAAK,SAAS;AAClB,YAAM,IAAI,KAAK;AACf,YAAM,MAAM,aAAa,MAAM,OAAO;AACtC,UAAI;AACF,cAAM,IAAS,MAAM,EAAE,KAAK,GAAG;AAC/B,eAAO;AAAA,UACL,MAAM,EAAE,cAAc,IAAI,QAAQ;AAAA,UAClC,MAAM,OAAO,EAAE,SAAS,WAAW,EAAE,OAAO;AAAA,UAC5C,SAAS,OAAO,EAAE,YAAY,WAAW,EAAE,UAAU;AAAA,QACvD;AAAA,MACF,SAAS,GAAG;AACV,cAAM,SAAS,CAAC;AAAA,MAClB;AAAA,IACF;AAAA,IACA,MAAM,OAAO,SAAS;AACpB,UAAI;AACF,cAAM,IAAI,KAAK,OAAO;AACtB,eAAO;AAAA,MACT,SAAS,GAAG;AACV,YAAK,EAAc,SAAS,YAAa,QAAO;AAChD,YAAK,EAAc,SAAS,iBAAkB,EAAc,SAAS,gBAAgB;AACnF,gBAAM;AAAA,QACR;AACA,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,MAAM,MAAM,SAAS,MAAM;AACzB,YAAM,IAAI,KAAK;AACf,YAAM,MAAM,aAAa,MAAM,OAAO;AACtC,UAAI;AACF,cAAM,EAAE,MAAM,KAAK,EAAE,WAAW,MAAM,aAAa,MAAM,CAAC;AAAA,MAC5D,SAAS,GAAG;AACV,cAAM,SAAS,CAAC;AAAA,MAClB;AAAA,IACF;AAAA,IACA,MAAM,GAAG,SAAS,MAAM;AACtB,YAAM,IAAI,KAAK;AACf,YAAM,MAAM,aAAa,MAAM,OAAO;AACtC,UAAI;AACF,cAAM,EAAE,GAAG,KAAK,EAAE,WAAW,MAAM,aAAa,MAAM,CAAC;AAAA,MACzD,SAAS,GAAG;AACV,cAAM,SAAS,CAAC;AAAA,MAClB;AAAA,IACF;AAAA,IACA,MAAM,OAAO,SAAS,OAAO;AAC3B,YAAM,IAAI,KAAK;AACf,YAAM,OAAO,aAAa,MAAM,OAAO;AACvC,YAAM,KAAK,aAAa,MAAM,KAAK;AACnC,UAAI;AACF,cAAM,EAAE,OAAO,MAAM,EAAE;AAAA,MACzB,SAAS,GAAG;AACV,cAAM,SAAS,CAAC;AAAA,MAClB;AAAA,IACF;AAAA,IACA,SAAS,UAAU,IAAI;AACrB,aAAO,WAAW,OAAO,OAAO;AAAA,IAClC;AAAA,IACA,SAAS,IAAI;AAKX,UAAI,aAAS,+BAAgB,GAAG;AAC9B,eAAO,MAAM;AAAA,QAAC;AAAA,MAChB;AACA,iBAAO,8BAAW,CAAC,WAAW;AAI5B,YAAI,OAAO,MAAM,WAAW,EAAG;AAC/B,WAAG,OAAO,MAAM,IAAI,CAAC,MAAM,EAAE,QAAQ,QAAQ,EAAE,CAAC,CAAC;AAAA,MACnD,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO;AACT;AAIO,SAAS,YAAqB;AACnC,SAAO,OAAO,EAAE,UAAM,+BAAgB,GAAG,MAAM,OAAO,CAAiB;AACzE;","names":[]}
+{"version":3,"sources":["../src/fs.ts"],"sourcesContent":["// Typed, discoverable filesystem access — the app-facing surface for the ZenFS\n// mount ports (SDK_FS_SURFACE_SPEC; FILESYSTEM_SPEC §2 the ZenFS-shaped contract).\n//\n// The single most important thing an app does — read/write files in its mounts —\n// previously had NO SDK surface: apps reached an ambient `globalThis.__sandpackSharedFs`\n// by hand-rolling the same accessor (editor/file-explorer `src/fs/mountFs.ts`, \"keep the\n// two in sync\"), with a documented footgun (`module.evaluation.module.bundler.fs` is the\n// WRONG object — it has no `promises`/`stat`). This module is that accessor's ONE home,\n// typed and documented.\n//\n// It adds NO authority: the ZenFS port is already minted and chroot/`ro`-enforced\n// host-side (FILESYSTEM_SPEC §2, UI_AS_APPS §8.7). This is typing + discoverability +\n// de-duplication only. `fs` is a Resource PORT (a byte channel), not a host-brokered RPC,\n// so — unlike the `invoke()` catalog surface — it is hand-written, not gate-table-derived.\nimport type { SandboxMount, MountRule } from './mounts';\nimport { getAppMountPath } from './mounts';\nimport { onFsChange } from './onFsChange';\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */\ninterface NodeFsPromises {\n  readFile(path: string, encoding?: any): Promise<string | Uint8Array>;\n  writeFile(path: string, data: string | Uint8Array): Promise<void>;\n  readdir(path: string, opts?: any): Promise<any[]>;\n  stat(path: string): Promise<any>;\n  mkdir(path: string, opts?: any): Promise<unknown>;\n  rm(path: string, opts?: any): Promise<void>;\n  rename(from: string, to: string): Promise<void>;\n}\n\n/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —\n *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */\nexport interface SandboxFsPort {\n  promises?: NodeFsPromises;\n  readFile?: NodeFsPromises['readFile'];\n}\n\nconst hasFs = (fs: any): boolean => typeof fs?.promises?.readFile === 'function' || typeof fs?.readFile === 'function';\n\n/**\n * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the\n * resolution order previously duplicated in every app's `mountFs.ts`:\n *\n * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.\n * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`\n *    whose surface has `readFile` (the bundler ZenFS-layer bound context).\n * 3. else `null` (local `vite dev` / before boot).\n *\n * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute\n * `/mnt/{hash}` paths (the file explorer / editor).\n */\nexport function sandboxFs(): SandboxFsPort | null {\n  try {\n    const shared = (globalThis as any).__sandpackSharedFs;\n    if (hasFs(shared)) return shared as SandboxFsPort;\n  } catch {\n    /* not in the sandbox */\n  }\n  try {\n    // @ts-ignore - `module` is injected by the sandbox runtime (see sandboxUtils transport).\n    const layers = module?.evaluation?.module?.bundler?.fs?.layers;\n    if (Array.isArray(layers)) {\n      for (const layer of layers) {\n        const fs = layer?.boundContext?.fs;\n        if (hasFs(fs)) return fs as SandboxFsPort;\n      }\n    }\n  } catch {\n    /* not in the sandbox */\n  }\n  return null;\n}\n\n/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before\n *  boot — gate file affordances on it so an app degrades instead of throwing. */\nexport function fsAvailable(): boolean {\n  return sandboxFs() != null;\n}\n\n/** A directory entry from {@link MountFs.readdir}. */\nexport interface DirEntry {\n  name: string;\n  kind: 'file' | 'dir';\n}\n\n/** A stat result from {@link MountFs.stat}. */\nexport interface FileStat {\n  kind: 'file' | 'dir';\n  size: number;\n  mtimeMs?: number;\n}\n\n/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`\n *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */\nexport interface FsError extends Error {\n  code:\n    | 'not-found' // ENOENT\n    | 'read-only' // EROFS — a `ro` mount / downgraded role; NEVER surface as UX (gate with canWrite)\n    | 'not-permitted' // EACCES\n    | 'exists' // EEXIST\n    | 'not-empty' // ENOTEMPTY\n    | 'invalid-path' // a `..` segment / absolute escape was passed as a relPath\n    | 'unavailable' // no sandbox fs (local dev / pre-boot)\n    | 'unknown';\n}\n\nconst ERRNO: Record<string, FsError['code']> = {\n  ENOENT: 'not-found',\n  EROFS: 'read-only',\n  EACCES: 'not-permitted',\n  EPERM: 'not-permitted',\n  EEXIST: 'exists',\n  ENOTEMPTY: 'not-empty',\n};\n\nconst fsError = (code: FsError['code'], message: string): FsError => {\n  const err = new Error(message) as FsError;\n  err.code = code;\n  return err;\n};\n\nconst mapError = (e: unknown): FsError => {\n  const errno = (e as { code?: string } | null)?.code;\n  const code: FsError['code'] = (errno ? ERRNO[errno] : undefined) ?? 'unknown';\n  const err = new Error((e as Error)?.message ?? 'fs operation failed') as FsError;\n  err.code = code;\n  return err;\n};\n\n// Lazily constructed so merely *importing* this module doesn't touch the\n// TextEncoder/TextDecoder globals — some non-DOM test/build environments only\n// provide them on demand, and no image/URL path needs them at all.\nlet _decoder: TextDecoder | undefined;\nlet _encoder: TextEncoder | undefined;\nconst decoder = (): TextDecoder => (_decoder ??= new TextDecoder());\nconst encoder = (): TextEncoder => (_encoder ??= new TextEncoder());\n\n// Extension → MIME type for the kinds an app displays inline. Images first (the\n// common case — `<img src>` off a mount), plus a couple of adjacent binary kinds.\n// Deliberately small: `mimeTypeFor` returns undefined for anything not here and\n// callers fall back to `application/octet-stream`.\nconst MIME_BY_EXT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  gif: 'image/gif',\n  webp: 'image/webp',\n  avif: 'image/avif',\n  svg: 'image/svg+xml',\n  bmp: 'image/bmp',\n  ico: 'image/x-icon',\n};\n\n/**\n * Best-effort MIME type from a filename's extension — mainly image kinds\n * (png/jpg/jpeg/gif/webp/avif/svg/bmp/ico). Returns `undefined` when the\n * extension isn't recognized (the caller falls back to `application/octet-stream`).\n * Used by {@link MountFs.readBlob} / {@link MountFs.readObjectUrl}; exported so an\n * app can label a Blob it builds itself.\n */\nexport function mimeTypeFor(path: string): string | undefined {\n  const dot = path.lastIndexOf('.');\n  if (dot < 0) return undefined;\n  return MIME_BY_EXT[path.slice(dot + 1).toLowerCase()];\n}\n\n// Join a mount-RELATIVE path under the mount root, rejecting `..` escapes and absolute\n// paths (CLAUDE.md security rule 3 — don't probe for escapes). The host chroot is the\n// real enforcer; this keeps an honest app from accidentally naming outside its grant.\nconst resolveUnder = (root: string, relPath: string): string => {\n  if (relPath.startsWith('/')) {\n    throw fsError('invalid-path', `expected a mount-relative path, got absolute \"${relPath}\"`);\n  }\n  const parts: string[] = [];\n  for (const seg of relPath.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') {\n      throw fsError('invalid-path', `\"${relPath}\" escapes the mount root`);\n    }\n    parts.push(seg);\n  }\n  const base = root.endsWith('/') ? root.slice(0, -1) : root;\n  return parts.length ? `${base}/${parts.join('/')}` : base;\n};\n\n// The longest matching `rules` subtree governs a path (mounts.ts MountRule); fall back to\n// the whole-mount `mode`. A CLIENT-SIDE hint mirroring the host rule — EROFS stays\n// authoritative (the host re-checks live policy on every write).\nconst writableAt = (mount: SandboxMount, relPath: string): boolean => {\n  const path =\n    '/' +\n    relPath\n      .split('/')\n      .filter((s) => s && s !== '.')\n      .join('/');\n  const rules: MountRule[] | undefined = mount.rules;\n  if (rules && rules.length) {\n    let best: MountRule | undefined;\n    for (const r of rules) {\n      const sub = r.subtree.endsWith('/') ? r.subtree : r.subtree + '/';\n      if (path === r.subtree || path.startsWith(sub) || r.subtree === '/') {\n        if (!best || r.subtree.length > best.subtree.length) best = r;\n      }\n    }\n    if (best) return best.mode === 'rw';\n  }\n  return (mount.mode ?? 'rw') === 'rw';\n};\n\n/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;\n *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).\n *  Obtain one with {@link openFs}. */\nexport interface MountFs {\n  /** The mount this view is anchored to (read `mode`/`rules` for writability). */\n  readonly mount: SandboxMount;\n  /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */\n  readFile(relPath: string, encoding: 'utf8'): Promise<string>;\n  readFile(relPath: string): Promise<Uint8Array>;\n  /** Read a file's bytes as a `Blob`, tagged with a MIME `type` inferred from the\n   *  extension ({@link mimeTypeFor}) or `opts.type` when given (falls back to\n   *  `application/octet-stream`). The building block for downloads and object URLs. */\n  readBlob(relPath: string, opts?: { type?: string }): Promise<Blob>;\n  /** Read a file into an **object URL** suitable for `<img src>` / `<a href>` — the\n   *  fix for \"an opaque-origin iframe can't fetch a mount path\". Returns the `url`\n   *  and a `revoke()` you MUST call when done (typically on unmount) or the URL\n   *  leaks. Prefer the `useObjectUrl` hook / `MountImage` component, which revoke\n   *  for you; reach for this directly only outside React. */\n  readObjectUrl(relPath: string, opts?: { type?: string }): Promise<{ url: string; revoke: () => void }>;\n  /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */\n  writeFile(relPath: string, data: string | Uint8Array): Promise<void>;\n  /** List a directory (the mount root when `relPath` is omitted). */\n  readdir(relPath?: string): Promise<DirEntry[]>;\n  /** Stat a path. Throws `not-found` if absent. */\n  stat(relPath: string): Promise<FileStat>;\n  /** Does `relPath` exist? Never throws on absence. */\n  exists(relPath: string): Promise<boolean>;\n  /** Create a directory (pass `{ recursive: true }` to make parents). */\n  mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Remove a file, or a directory with `{ recursive: true }`. */\n  rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Rename/move within the mount. */\n  rename(fromRel: string, toRel: string): Promise<void>;\n  /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),\n   *  so an app can hide an \"edit\" affordance instead of catching `read-only`\n   *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade\n   *  flips it. EROFS from the host stays authoritative. */\n  canWrite(relPath?: string): boolean;\n  /** Subscribe to changes to files in this mount — the mount-scoped projection of\n   *  the host working-tree change stream (`onFsChange`), so a viewer re-reads an\n   *  affected file instead of polling (SDK_FS_SURFACE_SPEC §5). The callback gets\n   *  the changed paths RELATIVE to this mount (feed them straight back into\n   *  `readFile`/`stat`/…). Returns an unsubscribe fn.\n   *\n   *  **Working-tree-only in v1 (an honest gap, O2):** the host push channel carries\n   *  only working-tree changes, so `onChange` on a NON-working-tree mount (a space)\n   *  is an inert subscription that never fires until that channel lands. Like\n   *  `onFsChange`, origin-exclusion (ignoring the echo of your own write) is the\n   *  caller's responsibility. */\n  onChange(cb: (changedRelPaths: string[]) => void): () => void;\n}\n\nconst promisesOf = (port: SandboxFsPort): NodeFsPromises => port.promises ?? (port as unknown as NodeFsPromises);\n\n/**\n * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:\n * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you\n * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path\n * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the\n * real enforcer).\n *\n * ```ts\n * import { mountSpace } from '@immediately-run/sdk';\n * import { openFs } from '@immediately-run/sdk/fs';\n * const fs = openFs(await mountSpace({ spaceId }));\n * const text = await fs.readFile('notes/idea.mdx', 'utf8');\n * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);\n * ```\n *\n * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`\n * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}\n * with a mapped `.code` (`not-found`, `read-only`, …).\n */\nexport function openFs(mount: SandboxMount): MountFs {\n  const root = mount.path;\n\n  const port = (): NodeFsPromises => {\n    const p = sandboxFs();\n    if (!p) throw fsError('unavailable', 'immediately.run: sandbox filesystem unavailable');\n    return promisesOf(p);\n  };\n\n  const api: MountFs = {\n    mount,\n    async readFile(relPath: string, encoding?: 'utf8'): Promise<any> {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const data = await p.readFile(abs);\n        const bytes = typeof data === 'string' ? encoder().encode(data) : (data as Uint8Array);\n        return encoding === 'utf8' ? decoder().decode(bytes) : bytes;\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readBlob(relPath, opts) {\n      const bytes = await api.readFile(relPath);\n      const type = opts?.type ?? mimeTypeFor(relPath) ?? 'application/octet-stream';\n      return new Blob([bytes as BlobPart], { type });\n    },\n    async readObjectUrl(relPath, opts) {\n      const blob = await api.readBlob(relPath, opts);\n      const url = URL.createObjectURL(blob);\n      return { url, revoke: () => URL.revokeObjectURL(url) };\n    },\n    async writeFile(relPath, data) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.writeFile(abs, typeof data === 'string' ? encoder().encode(data) : data);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readdir(relPath = '') {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const entries = await p.readdir(abs, { withFileTypes: true });\n        return entries.map((d: any) =>\n          typeof d === 'string'\n            ? ({ name: d, kind: 'file' } as DirEntry)\n            : ({ name: d.name, kind: d.isDirectory?.() ? 'dir' : 'file' } as DirEntry),\n        );\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async stat(relPath) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const s: any = await p.stat(abs);\n        return {\n          kind: s.isDirectory?.() ? 'dir' : 'file',\n          size: typeof s.size === 'number' ? s.size : 0,\n          mtimeMs: typeof s.mtimeMs === 'number' ? s.mtimeMs : undefined,\n        };\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async exists(relPath) {\n      try {\n        await api.stat(relPath);\n        return true;\n      } catch (e) {\n        if ((e as FsError).code === 'not-found') return false;\n        if ((e as FsError).code === 'unavailable' || (e as FsError).code === 'invalid-path') {\n          throw e;\n        }\n        return false;\n      }\n    },\n    async mkdir(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.mkdir(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rm(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.rm(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rename(fromRel, toRel) {\n      const p = port();\n      const from = resolveUnder(root, fromRel);\n      const to = resolveUnder(root, toRel);\n      try {\n        await p.rename(from, to);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    canWrite(relPath = '') {\n      return writableAt(mount, relPath);\n    },\n    onChange(cb) {\n      // §5 — mount-scoped projection of the working-tree change channel\n      // (`onFsChange`). v1 is WORKING-TREE-ONLY: the host pushes only working-tree\n      // changes, so a non-working-tree mount (a space) has no channel yet (O2) and\n      // gets an inert subscription rather than another mount's paths leaking in.\n      if (root !== getAppMountPath()) {\n        return () => {}; // no channel for this mount — inert (honest v1 gap)\n      }\n      return onFsChange((change) => {\n        // Skip the empty pre-first-event initial batch; forward only real changes,\n        // as mount-relative paths (drop the repo-relative leading slash) so they\n        // feed straight back into readFile/stat/etc.\n        if (change.paths.length === 0) return;\n        cb(change.paths.map((p) => p.replace(/^\\/+/, '')));\n      });\n    },\n  };\n  return api;\n}\n\n/** Open a mount-anchored view of this app's OWN repository working tree — a convenience\n *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */\nexport function openAppFs(): MountFs {\n  return openFs({ path: getAppMountPath(), type: 'repo' } as SandboxMount);\n}\n"],"mappings":"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","names":[]}

package/dist/fs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fs.ts"],"sourcesContent":["// Typed, discoverable filesystem access — the app-facing surface for the ZenFS\n// mount ports (SDK_FS_SURFACE_SPEC; FILESYSTEM_SPEC §2 the ZenFS-shaped contract).\n//\n// The single most important thing an app does — read/write files in its mounts —\n// previously had NO SDK surface: apps reached an ambient `globalThis.__sandpackSharedFs`\n// by hand-rolling the same accessor (editor/file-explorer `src/fs/mountFs.ts`, \"keep the\n// two in sync\"), with a documented footgun (`module.evaluation.module.bundler.fs` is the\n// WRONG object — it has no `promises`/`stat`). This module is that accessor's ONE home,\n// typed and documented.\n//\n// It adds NO authority: the ZenFS port is already minted and chroot/`ro`-enforced\n// host-side (FILESYSTEM_SPEC §2, UI_AS_APPS §8.7). This is typing + discoverability +\n// de-duplication only. `fs` is a Resource PORT (a byte channel), not a host-brokered RPC,\n// so — unlike the `invoke()` catalog surface — it is hand-written, not gate-table-derived.\nimport type { SandboxMount, MountRule } from './mounts';\nimport { getAppMountPath } from './mounts';\nimport { onFsChange } from './onFsChange';\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */\ninterface NodeFsPromises {\n  readFile(path: string, encoding?: any): Promise<string | Uint8Array>;\n  writeFile(path: string, data: string | Uint8Array): Promise<void>;\n  readdir(path: string, opts?: any): Promise<any[]>;\n  stat(path: string): Promise<any>;\n  mkdir(path: string, opts?: any): Promise<unknown>;\n  rm(path: string, opts?: any): Promise<void>;\n  rename(from: string, to: string): Promise<void>;\n}\n\n/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —\n *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */\nexport interface SandboxFsPort {\n  promises?: NodeFsPromises;\n  readFile?: NodeFsPromises['readFile'];\n}\n\nconst hasFs = (fs: any): boolean =>\n  typeof fs?.promises?.readFile === 'function' || typeof fs?.readFile === 'function';\n\n/**\n * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the\n * resolution order previously duplicated in every app's `mountFs.ts`:\n *\n * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.\n * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`\n *    whose surface has `readFile` (the bundler ZenFS-layer bound context).\n * 3. else `null` (local `vite dev` / before boot).\n *\n * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute\n * `/mnt/{hash}` paths (the file explorer / editor).\n */\nexport function sandboxFs(): SandboxFsPort | null {\n  try {\n    const shared = (globalThis as any).__sandpackSharedFs;\n    if (hasFs(shared)) return shared as SandboxFsPort;\n  } catch {\n    /* not in the sandbox */\n  }\n  try {\n    // @ts-ignore - `module` is injected by the sandbox runtime (see sandboxUtils transport).\n    const layers = module?.evaluation?.module?.bundler?.fs?.layers;\n    if (Array.isArray(layers)) {\n      for (const layer of layers) {\n        const fs = layer?.boundContext?.fs;\n        if (hasFs(fs)) return fs as SandboxFsPort;\n      }\n    }\n  } catch {\n    /* not in the sandbox */\n  }\n  return null;\n}\n\n/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before\n *  boot — gate file affordances on it so an app degrades instead of throwing. */\nexport function fsAvailable(): boolean {\n  return sandboxFs() != null;\n}\n\n/** A directory entry from {@link MountFs.readdir}. */\nexport interface DirEntry {\n  name: string;\n  kind: 'file' | 'dir';\n}\n\n/** A stat result from {@link MountFs.stat}. */\nexport interface FileStat {\n  kind: 'file' | 'dir';\n  size: number;\n  mtimeMs?: number;\n}\n\n/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`\n *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */\nexport interface FsError extends Error {\n  code:\n    | 'not-found' // ENOENT\n    | 'read-only' // EROFS — a `ro` mount / downgraded role; NEVER surface as UX (gate with canWrite)\n    | 'not-permitted' // EACCES\n    | 'exists' // EEXIST\n    | 'not-empty' // ENOTEMPTY\n    | 'invalid-path' // a `..` segment / absolute escape was passed as a relPath\n    | 'unavailable' // no sandbox fs (local dev / pre-boot)\n    | 'unknown';\n}\n\nconst ERRNO: Record<string, FsError['code']> = {\n  ENOENT: 'not-found',\n  EROFS: 'read-only',\n  EACCES: 'not-permitted',\n  EPERM: 'not-permitted',\n  EEXIST: 'exists',\n  ENOTEMPTY: 'not-empty',\n};\n\nconst fsError = (code: FsError['code'], message: string): FsError => {\n  const err = new Error(message) as FsError;\n  err.code = code;\n  return err;\n};\n\nconst mapError = (e: unknown): FsError => {\n  const errno = (e as { code?: string } | null)?.code;\n  const code: FsError['code'] = (errno ? ERRNO[errno] : undefined) ?? 'unknown';\n  const err = new Error((e as Error)?.message ?? 'fs operation failed') as FsError;\n  err.code = code;\n  return err;\n};\n\n// Lazily constructed so merely *importing* this module doesn't touch the\n// TextEncoder/TextDecoder globals — some non-DOM test/build environments only\n// provide them on demand, and no image/URL path needs them at all.\nlet _decoder: TextDecoder | undefined;\nlet _encoder: TextEncoder | undefined;\nconst decoder = (): TextDecoder => (_decoder ??= new TextDecoder());\nconst encoder = (): TextEncoder => (_encoder ??= new TextEncoder());\n\n// Extension → MIME type for the kinds an app displays inline. Images first (the\n// common case — `<img src>` off a mount), plus a couple of adjacent binary kinds.\n// Deliberately small: `mimeTypeFor` returns undefined for anything not here and\n// callers fall back to `application/octet-stream`.\nconst MIME_BY_EXT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  gif: 'image/gif',\n  webp: 'image/webp',\n  avif: 'image/avif',\n  svg: 'image/svg+xml',\n  bmp: 'image/bmp',\n  ico: 'image/x-icon',\n};\n\n/**\n * Best-effort MIME type from a filename's extension — mainly image kinds\n * (png/jpg/jpeg/gif/webp/avif/svg/bmp/ico). Returns `undefined` when the\n * extension isn't recognized (the caller falls back to `application/octet-stream`).\n * Used by {@link MountFs.readBlob} / {@link MountFs.readObjectUrl}; exported so an\n * app can label a Blob it builds itself.\n */\nexport function mimeTypeFor(path: string): string | undefined {\n  const dot = path.lastIndexOf('.');\n  if (dot < 0) return undefined;\n  return MIME_BY_EXT[path.slice(dot + 1).toLowerCase()];\n}\n\n// Join a mount-RELATIVE path under the mount root, rejecting `..` escapes and absolute\n// paths (CLAUDE.md security rule 3 — don't probe for escapes). The host chroot is the\n// real enforcer; this keeps an honest app from accidentally naming outside its grant.\nconst resolveUnder = (root: string, relPath: string): string => {\n  if (relPath.startsWith('/')) {\n    throw fsError('invalid-path', `expected a mount-relative path, got absolute \"${relPath}\"`);\n  }\n  const parts: string[] = [];\n  for (const seg of relPath.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') {\n      throw fsError('invalid-path', `\"${relPath}\" escapes the mount root`);\n    }\n    parts.push(seg);\n  }\n  const base = root.endsWith('/') ? root.slice(0, -1) : root;\n  return parts.length ? `${base}/${parts.join('/')}` : base;\n};\n\n// The longest matching `rules` subtree governs a path (mounts.ts MountRule); fall back to\n// the whole-mount `mode`. A CLIENT-SIDE hint mirroring the host rule — EROFS stays\n// authoritative (the host re-checks live policy on every write).\nconst writableAt = (mount: SandboxMount, relPath: string): boolean => {\n  const path = '/' + relPath.split('/').filter((s) => s && s !== '.').join('/');\n  const rules: MountRule[] | undefined = mount.rules;\n  if (rules && rules.length) {\n    let best: MountRule | undefined;\n    for (const r of rules) {\n      const sub = r.subtree.endsWith('/') ? r.subtree : r.subtree + '/';\n      if (path === r.subtree || path.startsWith(sub) || r.subtree === '/') {\n        if (!best || r.subtree.length > best.subtree.length) best = r;\n      }\n    }\n    if (best) return best.mode === 'rw';\n  }\n  return (mount.mode ?? 'rw') === 'rw';\n};\n\n/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;\n *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).\n *  Obtain one with {@link openFs}. */\nexport interface MountFs {\n  /** The mount this view is anchored to (read `mode`/`rules` for writability). */\n  readonly mount: SandboxMount;\n  /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */\n  readFile(relPath: string, encoding: 'utf8'): Promise<string>;\n  readFile(relPath: string): Promise<Uint8Array>;\n  /** Read a file's bytes as a `Blob`, tagged with a MIME `type` inferred from the\n   *  extension ({@link mimeTypeFor}) or `opts.type` when given (falls back to\n   *  `application/octet-stream`). The building block for downloads and object URLs. */\n  readBlob(relPath: string, opts?: { type?: string }): Promise<Blob>;\n  /** Read a file into an **object URL** suitable for `<img src>` / `<a href>` — the\n   *  fix for \"an opaque-origin iframe can't fetch a mount path\". Returns the `url`\n   *  and a `revoke()` you MUST call when done (typically on unmount) or the URL\n   *  leaks. Prefer the `useObjectUrl` hook / `MountImage` component, which revoke\n   *  for you; reach for this directly only outside React. */\n  readObjectUrl(\n    relPath: string,\n    opts?: { type?: string },\n  ): Promise<{ url: string; revoke: () => void }>;\n  /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */\n  writeFile(relPath: string, data: string | Uint8Array): Promise<void>;\n  /** List a directory (the mount root when `relPath` is omitted). */\n  readdir(relPath?: string): Promise<DirEntry[]>;\n  /** Stat a path. Throws `not-found` if absent. */\n  stat(relPath: string): Promise<FileStat>;\n  /** Does `relPath` exist? Never throws on absence. */\n  exists(relPath: string): Promise<boolean>;\n  /** Create a directory (pass `{ recursive: true }` to make parents). */\n  mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Remove a file, or a directory with `{ recursive: true }`. */\n  rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Rename/move within the mount. */\n  rename(fromRel: string, toRel: string): Promise<void>;\n  /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),\n   *  so an app can hide an \"edit\" affordance instead of catching `read-only`\n   *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade\n   *  flips it. EROFS from the host stays authoritative. */\n  canWrite(relPath?: string): boolean;\n  /** Subscribe to changes to files in this mount — the mount-scoped projection of\n   *  the host working-tree change stream (`onFsChange`), so a viewer re-reads an\n   *  affected file instead of polling (SDK_FS_SURFACE_SPEC §5). The callback gets\n   *  the changed paths RELATIVE to this mount (feed them straight back into\n   *  `readFile`/`stat`/…). Returns an unsubscribe fn.\n   *\n   *  **Working-tree-only in v1 (an honest gap, O2):** the host push channel carries\n   *  only working-tree changes, so `onChange` on a NON-working-tree mount (a space)\n   *  is an inert subscription that never fires until that channel lands. Like\n   *  `onFsChange`, origin-exclusion (ignoring the echo of your own write) is the\n   *  caller's responsibility. */\n  onChange(cb: (changedRelPaths: string[]) => void): () => void;\n}\n\nconst promisesOf = (port: SandboxFsPort): NodeFsPromises =>\n  (port.promises ?? (port as unknown as NodeFsPromises));\n\n/**\n * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:\n * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you\n * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path\n * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the\n * real enforcer).\n *\n * ```ts\n * import { mountSpace } from '@immediately-run/sdk';\n * import { openFs } from '@immediately-run/sdk/fs';\n * const fs = openFs(await mountSpace({ spaceId }));\n * const text = await fs.readFile('notes/idea.mdx', 'utf8');\n * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);\n * ```\n *\n * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`\n * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}\n * with a mapped `.code` (`not-found`, `read-only`, …).\n */\nexport function openFs(mount: SandboxMount): MountFs {\n  const root = mount.path;\n\n  const port = (): NodeFsPromises => {\n    const p = sandboxFs();\n    if (!p) throw fsError('unavailable', 'immediately.run: sandbox filesystem unavailable');\n    return promisesOf(p);\n  };\n\n  const api: MountFs = {\n    mount,\n    async readFile(relPath: string, encoding?: 'utf8'): Promise<any> {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const data = await p.readFile(abs);\n        const bytes =\n          typeof data === 'string' ? encoder().encode(data) : (data as Uint8Array);\n        return encoding === 'utf8' ? decoder().decode(bytes) : bytes;\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readBlob(relPath, opts) {\n      const bytes = await api.readFile(relPath);\n      const type = opts?.type ?? mimeTypeFor(relPath) ?? 'application/octet-stream';\n      return new Blob([bytes as BlobPart], { type });\n    },\n    async readObjectUrl(relPath, opts) {\n      const blob = await api.readBlob(relPath, opts);\n      const url = URL.createObjectURL(blob);\n      return { url, revoke: () => URL.revokeObjectURL(url) };\n    },\n    async writeFile(relPath, data) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.writeFile(abs, typeof data === 'string' ? encoder().encode(data) : data);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readdir(relPath = '') {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const entries = await p.readdir(abs, { withFileTypes: true });\n        return entries.map((d: any) =>\n          typeof d === 'string'\n            ? ({ name: d, kind: 'file' } as DirEntry)\n            : ({ name: d.name, kind: d.isDirectory?.() ? 'dir' : 'file' } as DirEntry),\n        );\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async stat(relPath) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const s: any = await p.stat(abs);\n        return {\n          kind: s.isDirectory?.() ? 'dir' : 'file',\n          size: typeof s.size === 'number' ? s.size : 0,\n          mtimeMs: typeof s.mtimeMs === 'number' ? s.mtimeMs : undefined,\n        };\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async exists(relPath) {\n      try {\n        await api.stat(relPath);\n        return true;\n      } catch (e) {\n        if ((e as FsError).code === 'not-found') return false;\n        if ((e as FsError).code === 'unavailable' || (e as FsError).code === 'invalid-path') {\n          throw e;\n        }\n        return false;\n      }\n    },\n    async mkdir(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.mkdir(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rm(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.rm(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rename(fromRel, toRel) {\n      const p = port();\n      const from = resolveUnder(root, fromRel);\n      const to = resolveUnder(root, toRel);\n      try {\n        await p.rename(from, to);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    canWrite(relPath = '') {\n      return writableAt(mount, relPath);\n    },\n    onChange(cb) {\n      // §5 — mount-scoped projection of the working-tree change channel\n      // (`onFsChange`). v1 is WORKING-TREE-ONLY: the host pushes only working-tree\n      // changes, so a non-working-tree mount (a space) has no channel yet (O2) and\n      // gets an inert subscription rather than another mount's paths leaking in.\n      if (root !== getAppMountPath()) {\n        return () => {}; // no channel for this mount — inert (honest v1 gap)\n      }\n      return onFsChange((change) => {\n        // Skip the empty pre-first-event initial batch; forward only real changes,\n        // as mount-relative paths (drop the repo-relative leading slash) so they\n        // feed straight back into readFile/stat/etc.\n        if (change.paths.length === 0) return;\n        cb(change.paths.map((p) => p.replace(/^\\/+/, '')));\n      });\n    },\n  };\n  return api;\n}\n\n/** Open a mount-anchored view of this app's OWN repository working tree — a convenience\n *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */\nexport function openAppFs(): MountFs {\n  return openFs({ path: getAppMountPath(), type: 'repo' } as SandboxMount);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/fs.ts"],"sourcesContent":["// Typed, discoverable filesystem access — the app-facing surface for the ZenFS\n// mount ports (SDK_FS_SURFACE_SPEC; FILESYSTEM_SPEC §2 the ZenFS-shaped contract).\n//\n// The single most important thing an app does — read/write files in its mounts —\n// previously had NO SDK surface: apps reached an ambient `globalThis.__sandpackSharedFs`\n// by hand-rolling the same accessor (editor/file-explorer `src/fs/mountFs.ts`, \"keep the\n// two in sync\"), with a documented footgun (`module.evaluation.module.bundler.fs` is the\n// WRONG object — it has no `promises`/`stat`). This module is that accessor's ONE home,\n// typed and documented.\n//\n// It adds NO authority: the ZenFS port is already minted and chroot/`ro`-enforced\n// host-side (FILESYSTEM_SPEC §2, UI_AS_APPS §8.7). This is typing + discoverability +\n// de-duplication only. `fs` is a Resource PORT (a byte channel), not a host-brokered RPC,\n// so — unlike the `invoke()` catalog surface — it is hand-written, not gate-table-derived.\nimport type { SandboxMount, MountRule } from './mounts';\nimport { getAppMountPath } from './mounts';\nimport { onFsChange } from './onFsChange';\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */\ninterface NodeFsPromises {\n  readFile(path: string, encoding?: any): Promise<string | Uint8Array>;\n  writeFile(path: string, data: string | Uint8Array): Promise<void>;\n  readdir(path: string, opts?: any): Promise<any[]>;\n  stat(path: string): Promise<any>;\n  mkdir(path: string, opts?: any): Promise<unknown>;\n  rm(path: string, opts?: any): Promise<void>;\n  rename(from: string, to: string): Promise<void>;\n}\n\n/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —\n *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */\nexport interface SandboxFsPort {\n  promises?: NodeFsPromises;\n  readFile?: NodeFsPromises['readFile'];\n}\n\nconst hasFs = (fs: any): boolean => typeof fs?.promises?.readFile === 'function' || typeof fs?.readFile === 'function';\n\n/**\n * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the\n * resolution order previously duplicated in every app's `mountFs.ts`:\n *\n * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.\n * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`\n *    whose surface has `readFile` (the bundler ZenFS-layer bound context).\n * 3. else `null` (local `vite dev` / before boot).\n *\n * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute\n * `/mnt/{hash}` paths (the file explorer / editor).\n */\nexport function sandboxFs(): SandboxFsPort | null {\n  try {\n    const shared = (globalThis as any).__sandpackSharedFs;\n    if (hasFs(shared)) return shared as SandboxFsPort;\n  } catch {\n    /* not in the sandbox */\n  }\n  try {\n    // @ts-ignore - `module` is injected by the sandbox runtime (see sandboxUtils transport).\n    const layers = module?.evaluation?.module?.bundler?.fs?.layers;\n    if (Array.isArray(layers)) {\n      for (const layer of layers) {\n        const fs = layer?.boundContext?.fs;\n        if (hasFs(fs)) return fs as SandboxFsPort;\n      }\n    }\n  } catch {\n    /* not in the sandbox */\n  }\n  return null;\n}\n\n/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before\n *  boot — gate file affordances on it so an app degrades instead of throwing. */\nexport function fsAvailable(): boolean {\n  return sandboxFs() != null;\n}\n\n/** A directory entry from {@link MountFs.readdir}. */\nexport interface DirEntry {\n  name: string;\n  kind: 'file' | 'dir';\n}\n\n/** A stat result from {@link MountFs.stat}. */\nexport interface FileStat {\n  kind: 'file' | 'dir';\n  size: number;\n  mtimeMs?: number;\n}\n\n/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`\n *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */\nexport interface FsError extends Error {\n  code:\n    | 'not-found' // ENOENT\n    | 'read-only' // EROFS — a `ro` mount / downgraded role; NEVER surface as UX (gate with canWrite)\n    | 'not-permitted' // EACCES\n    | 'exists' // EEXIST\n    | 'not-empty' // ENOTEMPTY\n    | 'invalid-path' // a `..` segment / absolute escape was passed as a relPath\n    | 'unavailable' // no sandbox fs (local dev / pre-boot)\n    | 'unknown';\n}\n\nconst ERRNO: Record<string, FsError['code']> = {\n  ENOENT: 'not-found',\n  EROFS: 'read-only',\n  EACCES: 'not-permitted',\n  EPERM: 'not-permitted',\n  EEXIST: 'exists',\n  ENOTEMPTY: 'not-empty',\n};\n\nconst fsError = (code: FsError['code'], message: string): FsError => {\n  const err = new Error(message) as FsError;\n  err.code = code;\n  return err;\n};\n\nconst mapError = (e: unknown): FsError => {\n  const errno = (e as { code?: string } | null)?.code;\n  const code: FsError['code'] = (errno ? ERRNO[errno] : undefined) ?? 'unknown';\n  const err = new Error((e as Error)?.message ?? 'fs operation failed') as FsError;\n  err.code = code;\n  return err;\n};\n\n// Lazily constructed so merely *importing* this module doesn't touch the\n// TextEncoder/TextDecoder globals — some non-DOM test/build environments only\n// provide them on demand, and no image/URL path needs them at all.\nlet _decoder: TextDecoder | undefined;\nlet _encoder: TextEncoder | undefined;\nconst decoder = (): TextDecoder => (_decoder ??= new TextDecoder());\nconst encoder = (): TextEncoder => (_encoder ??= new TextEncoder());\n\n// Extension → MIME type for the kinds an app displays inline. Images first (the\n// common case — `<img src>` off a mount), plus a couple of adjacent binary kinds.\n// Deliberately small: `mimeTypeFor` returns undefined for anything not here and\n// callers fall back to `application/octet-stream`.\nconst MIME_BY_EXT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  gif: 'image/gif',\n  webp: 'image/webp',\n  avif: 'image/avif',\n  svg: 'image/svg+xml',\n  bmp: 'image/bmp',\n  ico: 'image/x-icon',\n};\n\n/**\n * Best-effort MIME type from a filename's extension — mainly image kinds\n * (png/jpg/jpeg/gif/webp/avif/svg/bmp/ico). Returns `undefined` when the\n * extension isn't recognized (the caller falls back to `application/octet-stream`).\n * Used by {@link MountFs.readBlob} / {@link MountFs.readObjectUrl}; exported so an\n * app can label a Blob it builds itself.\n */\nexport function mimeTypeFor(path: string): string | undefined {\n  const dot = path.lastIndexOf('.');\n  if (dot < 0) return undefined;\n  return MIME_BY_EXT[path.slice(dot + 1).toLowerCase()];\n}\n\n// Join a mount-RELATIVE path under the mount root, rejecting `..` escapes and absolute\n// paths (CLAUDE.md security rule 3 — don't probe for escapes). The host chroot is the\n// real enforcer; this keeps an honest app from accidentally naming outside its grant.\nconst resolveUnder = (root: string, relPath: string): string => {\n  if (relPath.startsWith('/')) {\n    throw fsError('invalid-path', `expected a mount-relative path, got absolute \"${relPath}\"`);\n  }\n  const parts: string[] = [];\n  for (const seg of relPath.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') {\n      throw fsError('invalid-path', `\"${relPath}\" escapes the mount root`);\n    }\n    parts.push(seg);\n  }\n  const base = root.endsWith('/') ? root.slice(0, -1) : root;\n  return parts.length ? `${base}/${parts.join('/')}` : base;\n};\n\n// The longest matching `rules` subtree governs a path (mounts.ts MountRule); fall back to\n// the whole-mount `mode`. A CLIENT-SIDE hint mirroring the host rule — EROFS stays\n// authoritative (the host re-checks live policy on every write).\nconst writableAt = (mount: SandboxMount, relPath: string): boolean => {\n  const path =\n    '/' +\n    relPath\n      .split('/')\n      .filter((s) => s && s !== '.')\n      .join('/');\n  const rules: MountRule[] | undefined = mount.rules;\n  if (rules && rules.length) {\n    let best: MountRule | undefined;\n    for (const r of rules) {\n      const sub = r.subtree.endsWith('/') ? r.subtree : r.subtree + '/';\n      if (path === r.subtree || path.startsWith(sub) || r.subtree === '/') {\n        if (!best || r.subtree.length > best.subtree.length) best = r;\n      }\n    }\n    if (best) return best.mode === 'rw';\n  }\n  return (mount.mode ?? 'rw') === 'rw';\n};\n\n/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;\n *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).\n *  Obtain one with {@link openFs}. */\nexport interface MountFs {\n  /** The mount this view is anchored to (read `mode`/`rules` for writability). */\n  readonly mount: SandboxMount;\n  /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */\n  readFile(relPath: string, encoding: 'utf8'): Promise<string>;\n  readFile(relPath: string): Promise<Uint8Array>;\n  /** Read a file's bytes as a `Blob`, tagged with a MIME `type` inferred from the\n   *  extension ({@link mimeTypeFor}) or `opts.type` when given (falls back to\n   *  `application/octet-stream`). The building block for downloads and object URLs. */\n  readBlob(relPath: string, opts?: { type?: string }): Promise<Blob>;\n  /** Read a file into an **object URL** suitable for `<img src>` / `<a href>` — the\n   *  fix for \"an opaque-origin iframe can't fetch a mount path\". Returns the `url`\n   *  and a `revoke()` you MUST call when done (typically on unmount) or the URL\n   *  leaks. Prefer the `useObjectUrl` hook / `MountImage` component, which revoke\n   *  for you; reach for this directly only outside React. */\n  readObjectUrl(relPath: string, opts?: { type?: string }): Promise<{ url: string; revoke: () => void }>;\n  /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */\n  writeFile(relPath: string, data: string | Uint8Array): Promise<void>;\n  /** List a directory (the mount root when `relPath` is omitted). */\n  readdir(relPath?: string): Promise<DirEntry[]>;\n  /** Stat a path. Throws `not-found` if absent. */\n  stat(relPath: string): Promise<FileStat>;\n  /** Does `relPath` exist? Never throws on absence. */\n  exists(relPath: string): Promise<boolean>;\n  /** Create a directory (pass `{ recursive: true }` to make parents). */\n  mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Remove a file, or a directory with `{ recursive: true }`. */\n  rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Rename/move within the mount. */\n  rename(fromRel: string, toRel: string): Promise<void>;\n  /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),\n   *  so an app can hide an \"edit\" affordance instead of catching `read-only`\n   *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade\n   *  flips it. EROFS from the host stays authoritative. */\n  canWrite(relPath?: string): boolean;\n  /** Subscribe to changes to files in this mount — the mount-scoped projection of\n   *  the host working-tree change stream (`onFsChange`), so a viewer re-reads an\n   *  affected file instead of polling (SDK_FS_SURFACE_SPEC §5). The callback gets\n   *  the changed paths RELATIVE to this mount (feed them straight back into\n   *  `readFile`/`stat`/…). Returns an unsubscribe fn.\n   *\n   *  **Working-tree-only in v1 (an honest gap, O2):** the host push channel carries\n   *  only working-tree changes, so `onChange` on a NON-working-tree mount (a space)\n   *  is an inert subscription that never fires until that channel lands. Like\n   *  `onFsChange`, origin-exclusion (ignoring the echo of your own write) is the\n   *  caller's responsibility. */\n  onChange(cb: (changedRelPaths: string[]) => void): () => void;\n}\n\nconst promisesOf = (port: SandboxFsPort): NodeFsPromises => port.promises ?? (port as unknown as NodeFsPromises);\n\n/**\n * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:\n * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you\n * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path\n * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the\n * real enforcer).\n *\n * ```ts\n * import { mountSpace } from '@immediately-run/sdk';\n * import { openFs } from '@immediately-run/sdk/fs';\n * const fs = openFs(await mountSpace({ spaceId }));\n * const text = await fs.readFile('notes/idea.mdx', 'utf8');\n * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);\n * ```\n *\n * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`\n * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}\n * with a mapped `.code` (`not-found`, `read-only`, …).\n */\nexport function openFs(mount: SandboxMount): MountFs {\n  const root = mount.path;\n\n  const port = (): NodeFsPromises => {\n    const p = sandboxFs();\n    if (!p) throw fsError('unavailable', 'immediately.run: sandbox filesystem unavailable');\n    return promisesOf(p);\n  };\n\n  const api: MountFs = {\n    mount,\n    async readFile(relPath: string, encoding?: 'utf8'): Promise<any> {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const data = await p.readFile(abs);\n        const bytes = typeof data === 'string' ? encoder().encode(data) : (data as Uint8Array);\n        return encoding === 'utf8' ? decoder().decode(bytes) : bytes;\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readBlob(relPath, opts) {\n      const bytes = await api.readFile(relPath);\n      const type = opts?.type ?? mimeTypeFor(relPath) ?? 'application/octet-stream';\n      return new Blob([bytes as BlobPart], { type });\n    },\n    async readObjectUrl(relPath, opts) {\n      const blob = await api.readBlob(relPath, opts);\n      const url = URL.createObjectURL(blob);\n      return { url, revoke: () => URL.revokeObjectURL(url) };\n    },\n    async writeFile(relPath, data) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.writeFile(abs, typeof data === 'string' ? encoder().encode(data) : data);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readdir(relPath = '') {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const entries = await p.readdir(abs, { withFileTypes: true });\n        return entries.map((d: any) =>\n          typeof d === 'string'\n            ? ({ name: d, kind: 'file' } as DirEntry)\n            : ({ name: d.name, kind: d.isDirectory?.() ? 'dir' : 'file' } as DirEntry),\n        );\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async stat(relPath) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const s: any = await p.stat(abs);\n        return {\n          kind: s.isDirectory?.() ? 'dir' : 'file',\n          size: typeof s.size === 'number' ? s.size : 0,\n          mtimeMs: typeof s.mtimeMs === 'number' ? s.mtimeMs : undefined,\n        };\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async exists(relPath) {\n      try {\n        await api.stat(relPath);\n        return true;\n      } catch (e) {\n        if ((e as FsError).code === 'not-found') return false;\n        if ((e as FsError).code === 'unavailable' || (e as FsError).code === 'invalid-path') {\n          throw e;\n        }\n        return false;\n      }\n    },\n    async mkdir(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.mkdir(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rm(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.rm(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rename(fromRel, toRel) {\n      const p = port();\n      const from = resolveUnder(root, fromRel);\n      const to = resolveUnder(root, toRel);\n      try {\n        await p.rename(from, to);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    canWrite(relPath = '') {\n      return writableAt(mount, relPath);\n    },\n    onChange(cb) {\n      // §5 — mount-scoped projection of the working-tree change channel\n      // (`onFsChange`). v1 is WORKING-TREE-ONLY: the host pushes only working-tree\n      // changes, so a non-working-tree mount (a space) has no channel yet (O2) and\n      // gets an inert subscription rather than another mount's paths leaking in.\n      if (root !== getAppMountPath()) {\n        return () => {}; // no channel for this mount — inert (honest v1 gap)\n      }\n      return onFsChange((change) => {\n        // Skip the empty pre-first-event initial batch; forward only real changes,\n        // as mount-relative paths (drop the repo-relative leading slash) so they\n        // feed straight back into readFile/stat/etc.\n        if (change.paths.length === 0) return;\n        cb(change.paths.map((p) => p.replace(/^\\/+/, '')));\n      });\n    },\n  };\n  return api;\n}\n\n/** Open a mount-anchored view of this app's OWN repository working tree — a convenience\n *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */\nexport function openAppFs(): MountFs {\n  return openFs({ path: getAppMountPath(), type: 'repo' } as SandboxMount);\n}\n"],"mappings":"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","names":[]}

package/dist/hostAttention.cjs

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var hostAttention_exports = {};
+__export(hostAttention_exports, {
+  NO_HOST_ATTENTION: () => NO_HOST_ATTENTION,
+  getHostAttention: () => getHostAttention,
+  onHostAttentionChange: () => onHostAttentionChange,
+  useHostAttention: () => useHostAttention
+});
+module.exports = __toCommonJS(hostAttention_exports);
+var import_pushChannel = require("./pushChannel");
+var import_protocol = require("./generated/protocol");
+const NO_HOST_ATTENTION = { awaiting: false, kind: null, since: null };
+const KINDS = /* @__PURE__ */ new Set(["passkey", "consent", "picker", "confirmation"]);
+const parseHostAttention = (value) => {
+  const a = value;
+  if (!a || typeof a !== "object" || typeof a.awaiting !== "boolean") return void 0;
+  if (!a.awaiting) return NO_HOST_ATTENTION;
+  return {
+    awaiting: true,
+    kind: typeof a.kind === "string" && KINDS.has(a.kind) ? a.kind : null,
+    since: typeof a.since === "number" ? a.since : null
+  };
+};
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: import_protocol.HOST_ATTENTION,
+  requestType: import_protocol.REQUEST_HOST_ATTENTION,
+  initial: NO_HOST_ATTENTION,
+  parse: (msg) => parseHostAttention(msg.attention)
+});
+const getHostAttention = () => channel.get();
+const onHostAttentionChange = (listener) => channel.onChange(listener);
+const useHostAttention = () => channel.use();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NO_HOST_ATTENTION,
+  getHostAttention,
+  onHostAttentionChange,
+  useHostAttention
+});
+//# sourceMappingURL=hostAttention.cjs.map

package/dist/hostAttention.cjs.map

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

package/dist/hostAttention.d.cts

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

package/dist/hostAttention.d.ts

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

package/dist/hostAttention.js

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

package/dist/hostAttention.js.map

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

package/dist/hostTransport.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var hostTransport_exports = {};
+__export(hostTransport_exports, {
+  addListener: () => addListener,
+  sendMessage: () => sendMessage,
+  transport: () => transport
+});
+module.exports = __toCommonJS(hostTransport_exports);
+var import_hostRuntime = require("./hostRuntime");
+function transport() {
+  try {
+    const injected = module?.evaluation?.module?.bundler?.messageBus;
+    if (injected && typeof injected.sendMessage === "function") return injected;
+  } catch {
+  }
+  const t = (0, import_hostRuntime.getHostRuntime)()?.transport;
+  if (t && typeof t.sendMessage === "function") return t;
+  throw new Error("immediately.run: no host transport (neither injected nor __immediatelyRun__)");
+}
+const sendMessage = (type, data = {}) => {
+  transport().sendMessage(type, data);
+};
+const addListener = (msgType, handler, event) => {
+  const onMessage = event ?? transport().onMessage;
+  const disposable = onMessage((msg) => {
+    if (msg.type === msgType) {
+      handler(msg);
+    }
+  });
+  return () => disposable.dispose();
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  addListener,
+  sendMessage,
+  transport
+});
+//# sourceMappingURL=hostTransport.cjs.map

package/dist/hostTransport.cjs.map

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

package/dist/hostTransport.d.cts

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

package/dist/hostTransport.d.ts

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

package/dist/hostTransport.js

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

package/dist/hostTransport.js.map

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

package/dist/index.cjs

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