@immediately-run/sdk 0.34.0 → 0.35.0

package/dist/debug.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/debug.ts"],"sourcesContent":["// System-app devtools — the app-facing surface (plan: docs/plans/system-app-devtools.md).\n//\n// Two opt-in, DEV-ONLY instruments for debugging a sandboxed UI-as-app region:\n//   1. `debug.log(...)` — an app→host one-way log surfaced in the host dev panel\n//      / CLI `/debug` stream (instead of hand-fishing console output out of a\n//      cross-origin iframe's devtools).\n//   2. a READ-ONLY DOM/layout responder the host can query from outside — the\n//      thing a cross-origin screenshot can't reliably give you (a blank capture\n//      is ambiguous between a real 0-height collapse and a paint artifact).\n//\n// SECURITY (the gating constraint — see the plan's §0):\n//   - Both are inert unless the HOST signals dev mode via the `debug-enabled`\n//     channel. The host only sets it for a dev/override session (the `ir-dev-*`\n//     deep link) or an explicit operator developer-mode. A published app served\n//     to a normal user gets `enabled:false` → `debug.log` is a no-op and the\n//     responder never answers. Production isolation is therefore unchanged.\n//   - The responder is READ-ONLY with a fixed vocabulary (snapshotDom /\n//     computedStyle / rect). There is deliberately NO eval bridge — that would\n//     turn a debug aid into remote code execution into the sandbox.\n//   - The responder reads only its OWN `document` (it lives in its own opaque\n//     iframe and cannot reach a sibling app), so there is no app↔app leak even\n//     in dev.\n//   - Output is bounded (node/depth/text caps) so a query can't exfiltrate an\n//     unbounded payload or wedge the app.\n//\n// Apps that want the strongest guarantee can additionally guard their own usage\n// behind `import.meta.env.DEV` so the calls are tree-shaken from prod bundles;\n// the runtime gate here is the backstop that holds regardless.\n\nimport { createPushChannel } from './pushChannel';\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** Severity of a {@link debug.log} entry. */\nexport type DebugLevel = 'debug' | 'info' | 'warn' | 'error';\n\n// ── Dev gate ────────────────────────────────────────────────────────────────\n// The host pushes `debug-enabled:true` only for a dev/override session. Until\n// then (and always in production) it stays false and every instrument is inert.\nconst enabledChannel = createPushChannel<boolean>({\n  pushType: 'debug-enabled',\n  requestType: 'request-debug-enabled',\n  initial: false,\n  parse: (msg) => (typeof msg.enabled === 'boolean' ? msg.enabled : undefined),\n});\n\n/** Is the host dev-debug surface active for this session? `false` in production. */\nexport const isDebugEnabled = (): boolean => enabledChannel.get();\n\n/** React hook: whether the host dev-debug surface is active (re-renders on change).\n *  Handy for showing a debug affordance only when it would do something. */\nexport const useDebugEnabled = (): boolean => enabledChannel.use();\n\n// ── 1. App→host debug log ─────────────────────────────────────────────────────\n// Best-effort: a value that can't be structured-cloned is replaced with a marker\n// rather than throwing — `debug.log` must never break the app.\nconst MAX_DATA_BYTES = 16 * 1024;\n\nfunction safeData(data: unknown): unknown {\n  if (data === undefined) return undefined;\n  try {\n    const json = JSON.stringify(data);\n    if (json === undefined) return '[unserializable]';\n    if (json.length > MAX_DATA_BYTES) return `[truncated ${json.length}B]`;\n    return JSON.parse(json);\n  } catch {\n    return '[unserializable]';\n  }\n}\n\n/**\n * Emit a structured debug entry to the host dev surface. A NO-OP unless the host\n * has enabled the dev-debug session ({@link isDebugEnabled}); in production it\n * does nothing and sends nothing.\n *\n *   debug.log('info', 'mounted', { activeFile });\n */\nexport function log(level: DebugLevel, message: string, data?: unknown): void {\n  if (!enabledChannel.get()) return; // inert in prod / non-dev sessions\n  try {\n    sendMessage('debug-log', { level, message: String(message), data: safeData(data) });\n  } catch {\n    /* transport not ready — drop silently; logging must never throw */\n  }\n}\n\n// ── 2. Read-only DOM / layout responder ───────────────────────────────────────\n// The host sends `debug-query` { id, method, params }; we reply with\n// `debug-query-result` { id, ok, result | error }. Only ever active while the dev\n// gate is enabled. Vocabulary is fixed and read-only.\n\ninterface DomNode {\n  tag: string;\n  id?: string;\n  classes?: string[];\n  attrs?: Record<string, string>;\n  rect?: { x: number; y: number; w: number; h: number };\n  text?: string;\n  children?: DomNode[];\n  truncated?: true;\n}\n\nconst ATTR_ALLOW = new Set(['role', 'aria-hidden', 'data-theme', 'data-active', 'href', 'type', 'hidden']);\nconst MAX_NODES = 2000;\nconst MAX_DEPTH = 25;\nconst MAX_TEXT = 200;\n\nfunction round(n: number): number {\n  return Math.round(n);\n}\n\nfunction snapshotDom(params: { selector?: string; maxDepth?: number; maxNodes?: number }): DomNode | null {\n  if (typeof document === 'undefined') return null;\n  const root = params.selector ? document.querySelector(params.selector) : document.body;\n  if (!root) return null;\n  const maxDepth = Math.min(params.maxDepth ?? MAX_DEPTH, MAX_DEPTH);\n  const maxNodes = Math.min(params.maxNodes ?? MAX_NODES, MAX_NODES);\n  let budget = maxNodes;\n\n  const walk = (el: Element, depth: number): DomNode => {\n    budget--;\n    const r = el.getBoundingClientRect();\n    const classes = el.classList.length ? [...el.classList] : undefined;\n    const attrs: Record<string, string> = {};\n    for (const name of el.getAttributeNames()) {\n      if (ATTR_ALLOW.has(name)) attrs[name] = el.getAttribute(name) ?? '';\n    }\n    // Direct text (not descendants') so a leaf's label is visible without dumping\n    // the whole subtree's text.\n    const ownText = [...el.childNodes]\n      .filter((n) => n.nodeType === 3)\n      .map((n) => (n.textContent ?? '').trim())\n      .join(' ')\n      .trim();\n    const node: DomNode = {\n      tag: el.tagName.toLowerCase(),\n      ...(el.id ? { id: el.id } : {}),\n      ...(classes ? { classes } : {}),\n      ...(Object.keys(attrs).length ? { attrs } : {}),\n      rect: { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) },\n      ...(ownText ? { text: ownText.slice(0, MAX_TEXT) } : {}),\n    };\n    if (depth < maxDepth && el.children.length && budget > 0) {\n      const children: DomNode[] = [];\n      for (const child of el.children) {\n        if (budget <= 0) {\n          node.truncated = true;\n          break;\n        }\n        children.push(walk(child, depth + 1));\n      }\n      if (children.length) node.children = children;\n    } else if (el.children.length) {\n      node.truncated = true;\n    }\n    return node;\n  };\n\n  return walk(root, 0);\n}\n\nfunction computedStyle(params: { selector: string; props: string[] }): Record<string, string> | null {\n  if (typeof document === 'undefined') return null;\n  const el = document.querySelector(params.selector);\n  if (!el) return null;\n  const cs = getComputedStyle(el);\n  const out: Record<string, string> = {};\n  for (const p of params.props.slice(0, 50)) out[p] = cs.getPropertyValue(p) || cs[p as keyof CSSStyleDeclaration]?.toString?.() || '';\n  return out;\n}\n\nfunction rects(params: { selector: string }): Array<{ x: number; y: number; w: number; h: number }> {\n  if (typeof document === 'undefined') return [];\n  return [...document.querySelectorAll(params.selector)].slice(0, 200).map((el) => {\n    const r = el.getBoundingClientRect();\n    return { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) };\n  });\n}\n\nlet responderStarted = false;\n\n/** Wire the read-only DOM/layout responder. Idempotent; called lazily once the\n *  dev gate turns on. No effect when `document` is absent (non-browser realm). */\nfunction startResponder(): void {\n  if (responderStarted || typeof window === 'undefined') return;\n  responderStarted = true;\n  addListener('debug-query', (msg: { id?: unknown; method?: unknown; params?: unknown }) => {\n    if (!enabledChannel.get()) return; // gate: ignore unless dev-enabled\n    const id = msg.id;\n    const method = msg.method;\n    const params = (msg.params ?? {}) as Record<string, unknown>;\n    let ok = true;\n    let result: unknown = null;\n    let error: string | undefined;\n    try {\n      switch (method) {\n        case 'snapshotDom':\n          result = snapshotDom(params as never);\n          break;\n        case 'computedStyle':\n          result = computedStyle(params as never);\n          break;\n        case 'rect':\n          result = rects(params as never);\n          break;\n        default:\n          ok = false;\n          error = `unknown debug method: ${String(method)}`;\n      }\n    } catch (e) {\n      ok = false;\n      error = e instanceof Error ? e.message : String(e);\n    }\n    try {\n      sendMessage('debug-query-result', { id, ok, result, error });\n    } catch {\n      /* transport gone — nothing to do */\n    }\n  });\n}\n\n// Start the responder as soon as the gate flips on (and not before).\nenabledChannel.onChange((enabled) => {\n  if (enabled) startResponder();\n});\n\n/** The dev-only debug surface. Inert unless the host enables it ({@link isDebugEnabled}). */\nexport const debug = { log, isEnabled: isDebugEnabled } as const;\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/debug.ts"],"sourcesContent":["// System-app devtools — the app-facing surface (plan: docs/plans/system-app-devtools.md).\n//\n// Two opt-in, DEV-ONLY instruments for debugging a sandboxed UI-as-app region:\n//   1. `debug.log(...)` — an app→host one-way log surfaced in the host dev panel\n//      / CLI `/debug` stream (instead of hand-fishing console output out of a\n//      cross-origin iframe's devtools).\n//   2. a READ-ONLY DOM/layout responder the host can query from outside — the\n//      thing a cross-origin screenshot can't reliably give you (a blank capture\n//      is ambiguous between a real 0-height collapse and a paint artifact).\n//\n// SECURITY (the gating constraint — see the plan's §0):\n//   - Both are inert unless the HOST signals dev mode via the `debug-enabled`\n//     channel. The host only sets it for a dev/override session (the `ir-dev-*`\n//     deep link) or an explicit operator developer-mode. A published app served\n//     to a normal user gets `enabled:false` → `debug.log` is a no-op and the\n//     responder never answers. Production isolation is therefore unchanged.\n//   - The responder is READ-ONLY with a fixed vocabulary (snapshotDom /\n//     computedStyle / rect). There is deliberately NO eval bridge — that would\n//     turn a debug aid into remote code execution into the sandbox.\n//   - The responder reads only its OWN `document` (it lives in its own opaque\n//     iframe and cannot reach a sibling app), so there is no app↔app leak even\n//     in dev.\n//   - Output is bounded (node/depth/text caps) so a query can't exfiltrate an\n//     unbounded payload or wedge the app.\n//\n// Apps that want the strongest guarantee can additionally guard their own usage\n// behind `import.meta.env.DEV` so the calls are tree-shaken from prod bundles;\n// the runtime gate here is the backstop that holds regardless.\n\nimport { createPushChannel } from './pushChannel';\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** Severity of a {@link debug.log} entry. */\nexport type DebugLevel = 'debug' | 'info' | 'warn' | 'error';\n\n// ── Dev gate ────────────────────────────────────────────────────────────────\n// The host pushes `debug-enabled:true` only for a dev/override session. Until\n// then (and always in production) it stays false and every instrument is inert.\nconst enabledChannel = createPushChannel<boolean>({\n  pushType: 'debug-enabled',\n  requestType: 'request-debug-enabled',\n  initial: false,\n  parse: (msg) => (typeof msg.enabled === 'boolean' ? msg.enabled : undefined),\n});\n\n/** Is the host dev-debug surface active for this session? `false` in production. */\nexport const isDebugEnabled = (): boolean => enabledChannel.get();\n\n/** React hook: whether the host dev-debug surface is active (re-renders on change).\n *  Handy for showing a debug affordance only when it would do something. */\nexport const useDebugEnabled = (): boolean => enabledChannel.use();\n\n// ── 1. App→host debug log ─────────────────────────────────────────────────────\n// Best-effort: a value that can't be structured-cloned is replaced with a marker\n// rather than throwing — `debug.log` must never break the app.\nconst MAX_DATA_BYTES = 16 * 1024;\n\nfunction safeData(data: unknown): unknown {\n  if (data === undefined) return undefined;\n  try {\n    const json = JSON.stringify(data);\n    if (json === undefined) return '[unserializable]';\n    if (json.length > MAX_DATA_BYTES) return `[truncated ${json.length}B]`;\n    return JSON.parse(json);\n  } catch {\n    return '[unserializable]';\n  }\n}\n\n/**\n * Emit a structured debug entry to the host dev surface. A NO-OP unless the host\n * has enabled the dev-debug session ({@link isDebugEnabled}); in production it\n * does nothing and sends nothing.\n *\n *   debug.log('info', 'mounted', { activeFile });\n */\nexport function log(level: DebugLevel, message: string, data?: unknown): void {\n  if (!enabledChannel.get()) return; // inert in prod / non-dev sessions\n  try {\n    sendMessage('debug-log', { level, message: String(message), data: safeData(data) });\n  } catch {\n    /* transport not ready — drop silently; logging must never throw */\n  }\n}\n\n// ── 2. Read-only DOM / layout responder ───────────────────────────────────────\n// The host sends `debug-query` { id, method, params }; we reply with\n// `debug-query-result` { id, ok, result | error }. Only ever active while the dev\n// gate is enabled. Vocabulary is fixed and read-only.\n\ninterface DomNode {\n  tag: string;\n  id?: string;\n  classes?: string[];\n  attrs?: Record<string, string>;\n  rect?: { x: number; y: number; w: number; h: number };\n  text?: string;\n  children?: DomNode[];\n  truncated?: true;\n}\n\nconst ATTR_ALLOW = new Set(['role', 'aria-hidden', 'data-theme', 'data-active', 'href', 'type', 'hidden']);\nconst MAX_NODES = 2000;\nconst MAX_DEPTH = 25;\nconst MAX_TEXT = 200;\n\nfunction round(n: number): number {\n  return Math.round(n);\n}\n\nfunction snapshotDom(params: { selector?: string; maxDepth?: number; maxNodes?: number }): DomNode | null {\n  if (typeof document === 'undefined') return null;\n  const root = params.selector ? document.querySelector(params.selector) : document.body;\n  if (!root) return null;\n  const maxDepth = Math.min(params.maxDepth ?? MAX_DEPTH, MAX_DEPTH);\n  const maxNodes = Math.min(params.maxNodes ?? MAX_NODES, MAX_NODES);\n  let budget = maxNodes;\n\n  const walk = (el: Element, depth: number): DomNode => {\n    budget--;\n    const r = el.getBoundingClientRect();\n    const classes = el.classList.length ? [...el.classList] : undefined;\n    const attrs: Record<string, string> = {};\n    for (const name of el.getAttributeNames()) {\n      if (ATTR_ALLOW.has(name)) attrs[name] = el.getAttribute(name) ?? '';\n    }\n    // Direct text (not descendants') so a leaf's label is visible without dumping\n    // the whole subtree's text.\n    const ownText = [...el.childNodes]\n      .filter((n) => n.nodeType === 3)\n      .map((n) => (n.textContent ?? '').trim())\n      .join(' ')\n      .trim();\n    const node: DomNode = {\n      tag: el.tagName.toLowerCase(),\n      ...(el.id ? { id: el.id } : {}),\n      ...(classes ? { classes } : {}),\n      ...(Object.keys(attrs).length ? { attrs } : {}),\n      rect: { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) },\n      ...(ownText ? { text: ownText.slice(0, MAX_TEXT) } : {}),\n    };\n    if (depth < maxDepth && el.children.length && budget > 0) {\n      const children: DomNode[] = [];\n      for (const child of el.children) {\n        if (budget <= 0) {\n          node.truncated = true;\n          break;\n        }\n        children.push(walk(child, depth + 1));\n      }\n      if (children.length) node.children = children;\n    } else if (el.children.length) {\n      node.truncated = true;\n    }\n    return node;\n  };\n\n  return walk(root, 0);\n}\n\nfunction computedStyle(params: { selector: string; props: string[] }): Record<string, string> | null {\n  if (typeof document === 'undefined') return null;\n  const el = document.querySelector(params.selector);\n  if (!el) return null;\n  const cs = getComputedStyle(el);\n  const out: Record<string, string> = {};\n  for (const p of params.props.slice(0, 50)) out[p] = cs.getPropertyValue(p) || cs[p as keyof CSSStyleDeclaration]?.toString?.() || '';\n  return out;\n}\n\nfunction rects(params: { selector: string }): Array<{ x: number; y: number; w: number; h: number }> {\n  if (typeof document === 'undefined') return [];\n  return [...document.querySelectorAll(params.selector)].slice(0, 200).map((el) => {\n    const r = el.getBoundingClientRect();\n    return { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) };\n  });\n}\n\nlet responderStarted = false;\n\n/** Wire the read-only DOM/layout responder. Idempotent; called lazily once the\n *  dev gate turns on. No effect when `document` is absent (non-browser realm). */\nfunction startResponder(): void {\n  if (responderStarted || typeof window === 'undefined') return;\n  responderStarted = true;\n  addListener('debug-query', (msg: { id?: unknown; method?: unknown; params?: unknown }) => {\n    if (!enabledChannel.get()) return; // gate: ignore unless dev-enabled\n    const id = msg.id;\n    const method = msg.method;\n    const params = (msg.params ?? {}) as Record<string, unknown>;\n    let ok = true;\n    let result: unknown = null;\n    let error: string | undefined;\n    try {\n      switch (method) {\n        case 'snapshotDom':\n          result = snapshotDom(params as never);\n          break;\n        case 'computedStyle':\n          result = computedStyle(params as never);\n          break;\n        case 'rect':\n          result = rects(params as never);\n          break;\n        default:\n          ok = false;\n          error = `unknown debug method: ${String(method)}`;\n      }\n    } catch (e) {\n      ok = false;\n      error = e instanceof Error ? e.message : String(e);\n    }\n    try {\n      sendMessage('debug-query-result', { id, ok, result, error });\n    } catch {\n      /* transport gone — nothing to do */\n    }\n  });\n}\n\n// Start the responder as soon as the gate flips on (and not before).\nenabledChannel.onChange((enabled) => {\n  if (enabled) startResponder();\n});\n\n/** The dev-only debug surface. Inert unless the host enables it ({@link isDebugEnabled}). */\nexport const debug = { log, isEnabled: isDebugEnabled } as const;\n"],"mappings":"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","names":[]}

package/dist/diagnostics.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { createPushChannel } from "./pushChannel";
 const EMPTY = { buildErrors: [], consoleEntries: [], provenance: null };
 const channel = createPushChannel({

package/dist/diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\n/** The `console.*` method a captured entry came from. */\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\n/** A snapshot of the previewed app's diagnostics: its build errors, captured\n *  console output, and the {@link DiagnosticsProvenance} of the compile. */\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":"AAgBA,SAAS,yBAAyB;AA4ClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,UAAU,kBAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\n/** The `console.*` method a captured entry came from. */\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\n/** A snapshot of the previewed app's diagnostics: its build errors, captured\n *  console output, and the {@link DiagnosticsProvenance} of the compile. */\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":";AAgBA,SAAS,yBAAyB;AA4ClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,UAAU,kBAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}

package/dist/dnd.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { useEffect, useState } from "react";
 import { protocolRequest, sendMessage, addListener } from "./sandboxUtils";
 const startItemDrag = async (item) => {

package/dist/dnd.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/dnd.ts"],"sourcesContent":["// Cross-app drag-out (FILE_EXPLORER_SPEC §7; UI_AS_APPS_SPEC §2 host-mediated).\n//\n// Native HTML5 drag-and-drop does NOT cross the sandboxed cross-origin iframe\n// boundary, and pointer events inside one app's iframe never reach the host or a\n// sibling. So a drag that STARTS in one app (the file explorer) and ENDS over\n// another (the previewed app) can only be mediated by the host (the TCB). This\n// module is the SDK surface for that one net-new platform primitive:\n//\n//  - SOURCE side (the file explorer, needs the first-party `dnd:source` cap):\n//    `startItemDrag(item)` asks the host to begin a host-mediated drag carrying a\n//    file/dir reference (+ optional inlined bytes for a small file). The host draws\n//    the trusted drag ghost, tracks the pointer across regions, and on drop over the\n//    preview delivers the item to that app. `cancelItemDrag()` aborts.\n//  - RECEIVER side (the previewed app, NO new grant — it opts in by subscribing):\n//    `onItemDrop(cb)` / `useDroppedItem()` deliver the dropped item with host-attached,\n//    unspoofable provenance (`from` = source region id) and the drop position.\n//\n// The payload is UNTRUSTED app data (CLAUDE.md §5): the host attaches `from`; the app\n// validates everything else. v1 inlines bytes only for small files (the source can\n// only relay data it can already read — no new read authority is minted).\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\n\n/** A file/dir being dragged out of an app. `bytes` is present only for a small file\n *  the source chose to inline (transferred zero-copy); a dir or an over-cap file\n *  carries the reference only (`kind`/`name`/`mountId`/`relPath`). */\nexport interface DraggableItem {\n  kind: 'file' | 'dir';\n  /** Basename — display only. */\n  name: string;\n  /** Which mounted filesystem the item lives in. */\n  mountId: string;\n  /** Path within that mount (leading slash, no `..`). */\n  relPath: string;\n  /** Optional inlined content for a small file. */\n  bytes?: Uint8Array;\n}\n\n/** An item dropped onto THIS app by a host-mediated cross-app drag. */\nexport interface DroppedItem {\n  /** The dragged item (`bytes` present iff the source inlined them). */\n  item: DraggableItem;\n  /** Host-attached source region id — unspoofable (T19), like an `ipc` `from`. */\n  from: string;\n  /** Drop point in this app's viewport. */\n  position: { x: number; y: number };\n}\n\n/** An error from {@link startItemDrag}, carrying a machine-readable `.code`. */\nexport interface ItemDragError extends Error {\n  code:\n    | 'forbidden' // the frame lacks the first-party `dnd:source` capability\n    | 'invalid-params' // the item was malformed (empty path / `..` / URI / bad kind)\n    | 'too-large' // inlined `bytes` exceed the host's size limit\n    | 'rate-limited' // too many drags started too fast (capacity-class, fail-open)\n    | 'unknown';\n}\n\n/**\n * Begin a host-mediated drag of `item` out of this app. Resolves once the host has\n * taken over the drag (drawn the ghost, installed the pointer-capture layer); rejects\n * with an {@link ItemDragError} if this app may not initiate drags (`forbidden`) or the\n * item is invalid. Only a first-party chrome app holding `dnd:source` may call this — a\n * previewed/third-party app is refused at the gate (it must not synthesize drags into\n * sibling apps).\n */\nexport const startItemDrag = async (item: DraggableItem): Promise<void> => {\n  const res = (await protocolRequest('dnd', 'startDrag', [item])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'dnd startDrag failed') as ItemDragError;\n    err.code = (res?.code as ItemDragError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Abort an in-progress host-mediated drag this app started (e.g. the user pressed\n *  Escape, or the gesture was cancelled). Best-effort and fire-and-forget. */\nexport const cancelItemDrag = (): void => {\n  sendMessage('dnd-cancel', {});\n};\n\n/** Subscribe to items dropped onto this app by a host-mediated cross-app drag.\n *  Returns an unsubscribe fn. Subscribing is the opt-in: an app that never subscribes\n *  receives nothing (the host shows a \"not accepted\" cue and the drop is a no-op). */\nexport const onItemDrop = (listener: (d: DroppedItem) => void): (() => void) =>\n  addListener('dropped-item', (m: { item: DraggableItem; from: string; position: { x: number; y: number } }) =>\n    listener({ item: m.item, from: m.from, position: m.position }),\n  );\n\n/** React hook: the most recently dropped item (or `null`). */\nexport const useDroppedItem = (): DroppedItem | null => {\n  const [dropped, setDropped] = useState<DroppedItem | null>(null);\n  useEffect(() => onItemDrop(setDropped), []);\n  return dropped;\n};\n"],"mappings":"AAoBA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,aAAa,mBAAmB;AA6CnD,MAAM,gBAAgB,OAAO,SAAuC;AACzE,QAAM,MAAO,MAAM,gBAAgB,OAAO,aAAa,CAAC,IAAI,CAAC;AAI7D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,sBAAsB;AAC5D,QAAI,OAAQ,KAAK,QAAkC;AACnD,UAAM;AAAA,EACR;AACF;AAIO,MAAM,iBAAiB,MAAY;AACxC,cAAY,cAAc,CAAC,CAAC;AAC9B;AAKO,MAAM,aAAa,CAAC,aACzB;AAAA,EAAY;AAAA,EAAgB,CAAC,MAC3B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,UAAU,EAAE,SAAS,CAAC;AAC/D;AAGK,MAAM,iBAAiB,MAA0B;AACtD,QAAM,CAAC,SAAS,UAAU,IAAI,SAA6B,IAAI;AAC/D,YAAU,MAAM,WAAW,UAAU,GAAG,CAAC,CAAC;AAC1C,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/dnd.ts"],"sourcesContent":["// Cross-app drag-out (FILE_EXPLORER_SPEC §7; UI_AS_APPS_SPEC §2 host-mediated).\n//\n// Native HTML5 drag-and-drop does NOT cross the sandboxed cross-origin iframe\n// boundary, and pointer events inside one app's iframe never reach the host or a\n// sibling. So a drag that STARTS in one app (the file explorer) and ENDS over\n// another (the previewed app) can only be mediated by the host (the TCB). This\n// module is the SDK surface for that one net-new platform primitive:\n//\n//  - SOURCE side (the file explorer, needs the first-party `dnd:source` cap):\n//    `startItemDrag(item)` asks the host to begin a host-mediated drag carrying a\n//    file/dir reference (+ optional inlined bytes for a small file). The host draws\n//    the trusted drag ghost, tracks the pointer across regions, and on drop over the\n//    preview delivers the item to that app. `cancelItemDrag()` aborts.\n//  - RECEIVER side (the previewed app, NO new grant — it opts in by subscribing):\n//    `onItemDrop(cb)` / `useDroppedItem()` deliver the dropped item with host-attached,\n//    unspoofable provenance (`from` = source region id) and the drop position.\n//\n// The payload is UNTRUSTED app data (CLAUDE.md §5): the host attaches `from`; the app\n// validates everything else. v1 inlines bytes only for small files (the source can\n// only relay data it can already read — no new read authority is minted).\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\n\n/** A file/dir being dragged out of an app. `bytes` is present only for a small file\n *  the source chose to inline (transferred zero-copy); a dir or an over-cap file\n *  carries the reference only (`kind`/`name`/`mountId`/`relPath`). */\nexport interface DraggableItem {\n  kind: 'file' | 'dir';\n  /** Basename — display only. */\n  name: string;\n  /** Which mounted filesystem the item lives in. */\n  mountId: string;\n  /** Path within that mount (leading slash, no `..`). */\n  relPath: string;\n  /** Optional inlined content for a small file. */\n  bytes?: Uint8Array;\n}\n\n/** An item dropped onto THIS app by a host-mediated cross-app drag. */\nexport interface DroppedItem {\n  /** The dragged item (`bytes` present iff the source inlined them). */\n  item: DraggableItem;\n  /** Host-attached source region id — unspoofable (T19), like an `ipc` `from`. */\n  from: string;\n  /** Drop point in this app's viewport. */\n  position: { x: number; y: number };\n}\n\n/** An error from {@link startItemDrag}, carrying a machine-readable `.code`. */\nexport interface ItemDragError extends Error {\n  code:\n    | 'forbidden' // the frame lacks the first-party `dnd:source` capability\n    | 'invalid-params' // the item was malformed (empty path / `..` / URI / bad kind)\n    | 'too-large' // inlined `bytes` exceed the host's size limit\n    | 'rate-limited' // too many drags started too fast (capacity-class, fail-open)\n    | 'unknown';\n}\n\n/**\n * Begin a host-mediated drag of `item` out of this app. Resolves once the host has\n * taken over the drag (drawn the ghost, installed the pointer-capture layer); rejects\n * with an {@link ItemDragError} if this app may not initiate drags (`forbidden`) or the\n * item is invalid. Only a first-party chrome app holding `dnd:source` may call this — a\n * previewed/third-party app is refused at the gate (it must not synthesize drags into\n * sibling apps).\n */\nexport const startItemDrag = async (item: DraggableItem): Promise<void> => {\n  const res = (await protocolRequest('dnd', 'startDrag', [item])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'dnd startDrag failed') as ItemDragError;\n    err.code = (res?.code as ItemDragError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Abort an in-progress host-mediated drag this app started (e.g. the user pressed\n *  Escape, or the gesture was cancelled). Best-effort and fire-and-forget. */\nexport const cancelItemDrag = (): void => {\n  sendMessage('dnd-cancel', {});\n};\n\n/** Subscribe to items dropped onto this app by a host-mediated cross-app drag.\n *  Returns an unsubscribe fn. Subscribing is the opt-in: an app that never subscribes\n *  receives nothing (the host shows a \"not accepted\" cue and the drop is a no-op). */\nexport const onItemDrop = (listener: (d: DroppedItem) => void): (() => void) =>\n  addListener('dropped-item', (m: { item: DraggableItem; from: string; position: { x: number; y: number } }) =>\n    listener({ item: m.item, from: m.from, position: m.position }),\n  );\n\n/** React hook: the most recently dropped item (or `null`). */\nexport const useDroppedItem = (): DroppedItem | null => {\n  const [dropped, setDropped] = useState<DroppedItem | null>(null);\n  useEffect(() => onItemDrop(setDropped), []);\n  return dropped;\n};\n"],"mappings":";AAoBA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,aAAa,mBAAmB;AA6CnD,MAAM,gBAAgB,OAAO,SAAuC;AACzE,QAAM,MAAO,MAAM,gBAAgB,OAAO,aAAa,CAAC,IAAI,CAAC;AAI7D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,sBAAsB;AAC5D,QAAI,OAAQ,KAAK,QAAkC;AACnD,UAAM;AAAA,EACR;AACF;AAIO,MAAM,iBAAiB,MAAY;AACxC,cAAY,cAAc,CAAC,CAAC;AAC9B;AAKO,MAAM,aAAa,CAAC,aACzB;AAAA,EAAY;AAAA,EAAgB,CAAC,MAC3B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,UAAU,EAAE,SAAS,CAAC;AAC/D;AAGK,MAAM,iBAAiB,MAA0B;AACtD,QAAM,CAAC,SAAS,UAAU,IAAI,SAA6B,IAAI;AAC/D,YAAU,MAAM,WAAW,UAAU,GAAG,CAAC,CAAC;AAC1C,SAAO;AACT;","names":[]}

package/dist/editor.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { protocolRequest } from "./sandboxUtils";
 const editorRequest = async (method, arg) => {
   const res = await protocolRequest("editor", method, [arg]);

package/dist/editor.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n/**\n * Where to land when entering the edit experience (EDITOR_FIRST_EDITING_SPEC §6\n * Delta A). v1 supports only an optional repo-relative `path` in the CURRENT repo\n * (self-scoped — the app you are already running; the host navigates within the\n * current route, never to another repo). A URI or `..` path is refused\n * `invalid-params`. Editing a file in one of your *mounts* (a space) is the\n * `edit-file` task, not this.\n */\nexport interface EditTarget {\n  /** A repo-relative working-tree path in the current repo to focus once in edit\n   *  mode (e.g. `src/App.tsx`). Omit to edit the current route's entry. */\n  path?: string;\n}\n\n/** An error from {@link requestEdit}, carrying a machine-readable `.code`. */\nexport interface RequestEditError extends Error {\n  code:\n    | 'read-only' // editing isn't possible here (a `ro` mount / anonymous viewer) — HIDE the affordance\n    | 'forbidden' // the host refuses (e.g. a cross-repo / out-of-scope target)\n    | 'invalid-params' // the target was malformed (URI / `..` / a non-current repo)\n    | 'no-target' // there is no host editor session to enter\n    | 'unknown';\n}\n\n/**\n * Ask the host to enter the **edit experience** for the app you are running —\n * the present→edit transition (`/present/...` → `/edit/...`) an app cannot make\n * itself. This is an INTENT (§2 recursion boundary): the app asks, the HOST\n * performs the visible, user-observable navigation and draws all editor chrome;\n * the app never navigates or paints chrome.\n *\n * Use it to offer an \"edit this\" affordance from a run/present-mode app that opens\n * the app's own source in the platform editor — instead of shipping a bespoke\n * in-app editor (EDITOR_FIRST_EDITING_SPEC §1).\n *\n * Resolves once the host begins the transition; rejects with a\n * {@link RequestEditError} (`.code`). Treat `read-only`/`forbidden` as \"editing is\n * not available — hide the affordance,\" never as an error to surface to the user.\n */\nexport const requestEdit = (target?: EditTarget): Promise<void> =>\n  editorRequest('requestEdit', target ? { ...target } : {});\n\n// ---------------------------------------------------------------------------\n// Editor SESSION management (EDITOR_AS_APP_SPEC §5.1; editor-as-app plan Phase\n// 03). Unlike `openInEditor` (the explorer's cross-app intent, `editor:open`),\n// these drive the editor's OWN open-tab set + active file, so they are gated by\n// the editor app's `editor:document` capability — a file explorer holding only\n// `editor:open` cannot call them. The host re-validates the path against the live\n// working tree; the editor itself stays host-owned (§2 recursion boundary).\n// ---------------------------------------------------------------------------\n\n/** An error from a session intent ({@link setActiveFile} / {@link closeFile}),\n *  carrying a machine-readable `.code`. */\nexport interface EditorSessionError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:document`\n    | 'not-found' // no such file in the live working tree\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Switch the editor's active file to `path`, opening it (adding a tab) if it is\n *  not already open — native `setActiveFile` parity. Rejects with an\n *  {@link EditorSessionError} (`.code`) if the path is missing/invalid or this app\n *  lacks `editor:document`. */\nexport const setActiveFile = (path: string): Promise<void> =>\n  editorRequest('setActive', { path });\n\n/** Close `path`'s tab in the editor (remove it from the open set) — native\n *  `closeFile` parity. Rejects with an {@link EditorSessionError} (`.code`). */\nexport const closeFile = (path: string): Promise<void> => editorRequest('close', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":"AAAA,SAAS,uBAAuB;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,MAAM,gBAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyCpF,MAAM,cAAc,CAAC,WAC1B,cAAc,eAAe,SAAS,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC;AA0BnD,MAAM,gBAAgB,CAAC,SAC5B,cAAc,aAAa,EAAE,KAAK,CAAC;AAI9B,MAAM,YAAY,CAAC,SAAgC,cAAc,SAAS,EAAE,KAAK,CAAC;AAyBlF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}
+{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n/**\n * Where to land when entering the edit experience (EDITOR_FIRST_EDITING_SPEC §6\n * Delta A). v1 supports only an optional repo-relative `path` in the CURRENT repo\n * (self-scoped — the app you are already running; the host navigates within the\n * current route, never to another repo). A URI or `..` path is refused\n * `invalid-params`. Editing a file in one of your *mounts* (a space) is the\n * `edit-file` task, not this.\n */\nexport interface EditTarget {\n  /** A repo-relative working-tree path in the current repo to focus once in edit\n   *  mode (e.g. `src/App.tsx`). Omit to edit the current route's entry. */\n  path?: string;\n}\n\n/** An error from {@link requestEdit}, carrying a machine-readable `.code`. */\nexport interface RequestEditError extends Error {\n  code:\n    | 'read-only' // editing isn't possible here (a `ro` mount / anonymous viewer) — HIDE the affordance\n    | 'forbidden' // the host refuses (e.g. a cross-repo / out-of-scope target)\n    | 'invalid-params' // the target was malformed (URI / `..` / a non-current repo)\n    | 'no-target' // there is no host editor session to enter\n    | 'unknown';\n}\n\n/**\n * Ask the host to enter the **edit experience** for the app you are running —\n * the present→edit transition (`/present/...` → `/edit/...`) an app cannot make\n * itself. This is an INTENT (§2 recursion boundary): the app asks, the HOST\n * performs the visible, user-observable navigation and draws all editor chrome;\n * the app never navigates or paints chrome.\n *\n * Use it to offer an \"edit this\" affordance from a run/present-mode app that opens\n * the app's own source in the platform editor — instead of shipping a bespoke\n * in-app editor (EDITOR_FIRST_EDITING_SPEC §1).\n *\n * Resolves once the host begins the transition; rejects with a\n * {@link RequestEditError} (`.code`). Treat `read-only`/`forbidden` as \"editing is\n * not available — hide the affordance,\" never as an error to surface to the user.\n */\nexport const requestEdit = (target?: EditTarget): Promise<void> =>\n  editorRequest('requestEdit', target ? { ...target } : {});\n\n// ---------------------------------------------------------------------------\n// Editor SESSION management (EDITOR_AS_APP_SPEC §5.1; editor-as-app plan Phase\n// 03). Unlike `openInEditor` (the explorer's cross-app intent, `editor:open`),\n// these drive the editor's OWN open-tab set + active file, so they are gated by\n// the editor app's `editor:document` capability — a file explorer holding only\n// `editor:open` cannot call them. The host re-validates the path against the live\n// working tree; the editor itself stays host-owned (§2 recursion boundary).\n// ---------------------------------------------------------------------------\n\n/** An error from a session intent ({@link setActiveFile} / {@link closeFile}),\n *  carrying a machine-readable `.code`. */\nexport interface EditorSessionError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:document`\n    | 'not-found' // no such file in the live working tree\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Switch the editor's active file to `path`, opening it (adding a tab) if it is\n *  not already open — native `setActiveFile` parity. Rejects with an\n *  {@link EditorSessionError} (`.code`) if the path is missing/invalid or this app\n *  lacks `editor:document`. */\nexport const setActiveFile = (path: string): Promise<void> =>\n  editorRequest('setActive', { path });\n\n/** Close `path`'s tab in the editor (remove it from the open set) — native\n *  `closeFile` parity. Rejects with an {@link EditorSessionError} (`.code`). */\nexport const closeFile = (path: string): Promise<void> => editorRequest('close', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":";AAAA,SAAS,uBAAuB;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,MAAM,gBAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyCpF,MAAM,cAAc,CAAC,WAC1B,cAAc,eAAe,SAAS,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC;AA0BnD,MAAM,gBAAgB,CAAC,SAC5B,cAAc,aAAa,EAAE,KAAK,CAAC;AAI9B,MAAM,YAAY,CAAC,SAAgC,cAAc,SAAS,EAAE,KAAK,CAAC;AAyBlF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}

package/dist/editorContext.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { createPushChannel } from "./pushChannel";
 const isStringArray = (v) => Array.isArray(v) && v.every((p) => typeof p === "string");
 const channel = createPushChannel({

package/dist/editorContext.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The editor \"dirty set\" mirrored from the immediately.run host into the sandbox\n * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.\n *\n * This is the ELEVATED `editor:read` capability — only a system app whose binding\n * grants it (e.g. the contribute dialog) receives it. The active file and ref are\n * already available to every app via routing (`useNavigationState`), so this\n * channel carries only the genuine delta: the unsaved paths. An app without\n * `editor:read` simply sees an empty dirty set.\n */\nexport interface EditorContext {\n  /** Repo-relative paths the user has modified but not yet saved. */\n  dirtyPaths: string[];\n  /** Repo-relative paths currently open as tabs in the host editor (§4.2). */\n  openFiles: string[];\n  /**\n   * The one file currently focused in the host editor (repo-relative, leading\n   * slash — e.g. `/src/index.ts`), or `null` when no file is open. Distinct from\n   * {@link dirtyPaths} (the unsaved SET) and {@link openFiles} (the open-tab set):\n   * this is the single ACTIVE file. A baseline app reads its own active file from\n   * the route, but a self-routed system panel (`drivesHostRoute=false`, e.g. the\n   * file explorer) does not see the host editor's route, so it receives the active\n   * file here instead (UI_AS_APPS_SPEC §5.3 self-routed-panel refinement).\n   */\n  activeFile: string | null;\n}\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `editor-context`\n// and answers `request-editor-context` — but only for a frame holding `editor:read`\n// (gated by the channel router). An app without it gets no reply, so the empty\n// default below stands. Wire format: site-main channelBridge.ts.\nconst isStringArray = (v: unknown): v is string[] =>\n  Array.isArray(v) && v.every((p) => typeof p === 'string');\n\nconst channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [], openFiles: [], activeFile: null },\n  parse: (msg) =>\n    isStringArray(msg.dirtyPaths)\n      ? {\n          dirtyPaths: msg.dirtyPaths,\n          // `openFiles` is newer than `dirtyPaths`; tolerate an older host that\n          // omits it (defensive SDK — defaults to empty rather than rejecting).\n          openFiles: isStringArray(msg.openFiles) ? msg.openFiles : [],\n          // `activeFile` is newer still; an older host that omits it (or sends a\n          // non-string) reads as `null` — no file highlighted, never a throw.\n          activeFile: typeof msg.activeFile === 'string' ? msg.activeFile : null,\n        }\n      : undefined,\n});\n\n/**\n * Returns the current editor context (dirty set). Poll this for a one-off read;\n * use {@link onEditorContextChange} or {@link useEditorContext} to react.\n */\nexport const getEditorContext = (): EditorContext => channel.get();\n\n/**\n * Subscribe to editor-context changes. The listener is invoked immediately with\n * the current context, then again on every change. Returns an unsubscribe fn.\n */\nexport const onEditorContextChange = (listener: (context: EditorContext) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current editor context (dirty set), re-rendering when\n * it changes. Handy for a contribute dialog: `const { dirtyPaths } =\n * useEditorContext()` to show \"you'll save N files\" before calling `contribute()`.\n */\nexport const useEditorContext = (): EditorContext => channel.use();\n"],"mappings":"AAAA,SAAS,yBAAyB;AAiClC,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ;AAE1D,MAAM,UAAU,kBAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,GAAG,WAAW,CAAC,GAAG,YAAY,KAAK;AAAA,EAC3D,OAAO,CAAC,QACN,cAAc,IAAI,UAAU,IACxB;AAAA,IACE,YAAY,IAAI;AAAA;AAAA;AAAA,IAGhB,WAAW,cAAc,IAAI,SAAS,IAAI,IAAI,YAAY,CAAC;AAAA;AAAA;AAAA,IAG3D,YAAY,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,EACpE,IACA;AACR,CAAC;AAMM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The editor \"dirty set\" mirrored from the immediately.run host into the sandbox\n * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.\n *\n * This is the ELEVATED `editor:read` capability — only a system app whose binding\n * grants it (e.g. the contribute dialog) receives it. The active file and ref are\n * already available to every app via routing (`useNavigationState`), so this\n * channel carries only the genuine delta: the unsaved paths. An app without\n * `editor:read` simply sees an empty dirty set.\n */\nexport interface EditorContext {\n  /** Repo-relative paths the user has modified but not yet saved. */\n  dirtyPaths: string[];\n  /** Repo-relative paths currently open as tabs in the host editor (§4.2). */\n  openFiles: string[];\n  /**\n   * The one file currently focused in the host editor (repo-relative, leading\n   * slash — e.g. `/src/index.ts`), or `null` when no file is open. Distinct from\n   * {@link dirtyPaths} (the unsaved SET) and {@link openFiles} (the open-tab set):\n   * this is the single ACTIVE file. A baseline app reads its own active file from\n   * the route, but a self-routed system panel (`drivesHostRoute=false`, e.g. the\n   * file explorer) does not see the host editor's route, so it receives the active\n   * file here instead (UI_AS_APPS_SPEC §5.3 self-routed-panel refinement).\n   */\n  activeFile: string | null;\n}\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `editor-context`\n// and answers `request-editor-context` — but only for a frame holding `editor:read`\n// (gated by the channel router). An app without it gets no reply, so the empty\n// default below stands. Wire format: site-main channelBridge.ts.\nconst isStringArray = (v: unknown): v is string[] =>\n  Array.isArray(v) && v.every((p) => typeof p === 'string');\n\nconst channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [], openFiles: [], activeFile: null },\n  parse: (msg) =>\n    isStringArray(msg.dirtyPaths)\n      ? {\n          dirtyPaths: msg.dirtyPaths,\n          // `openFiles` is newer than `dirtyPaths`; tolerate an older host that\n          // omits it (defensive SDK — defaults to empty rather than rejecting).\n          openFiles: isStringArray(msg.openFiles) ? msg.openFiles : [],\n          // `activeFile` is newer still; an older host that omits it (or sends a\n          // non-string) reads as `null` — no file highlighted, never a throw.\n          activeFile: typeof msg.activeFile === 'string' ? msg.activeFile : null,\n        }\n      : undefined,\n});\n\n/**\n * Returns the current editor context (dirty set). Poll this for a one-off read;\n * use {@link onEditorContextChange} or {@link useEditorContext} to react.\n */\nexport const getEditorContext = (): EditorContext => channel.get();\n\n/**\n * Subscribe to editor-context changes. The listener is invoked immediately with\n * the current context, then again on every change. Returns an unsubscribe fn.\n */\nexport const onEditorContextChange = (listener: (context: EditorContext) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current editor context (dirty set), re-rendering when\n * it changes. Handy for a contribute dialog: `const { dirtyPaths } =\n * useEditorContext()` to show \"you'll save N files\" before calling `contribute()`.\n */\nexport const useEditorContext = (): EditorContext => channel.use();\n"],"mappings":";AAAA,SAAS,yBAAyB;AAiClC,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ;AAE1D,MAAM,UAAU,kBAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,GAAG,WAAW,CAAC,GAAG,YAAY,KAAK;AAAA,EAC3D,OAAO,CAAC,QACN,cAAc,IAAI,UAAU,IACxB;AAAA,IACE,YAAY,IAAI;AAAA;AAAA;AAAA,IAGhB,WAAW,cAAc,IAAI,SAAS,IAAI,IAAI,YAAY,CAAC;AAAA;AAAA;AAAA,IAG3D,YAAY,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,EACpE,IACA;AACR,CAAC;AAMM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}

package/dist/formFactor.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { createPushChannel } from "./pushChannel";
 const DEFAULT_FORM_FACTOR = {
   class: "desktop",

package/dist/formFactor.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\n/** Whether the rendered surface is taller than wide (`portrait`) or wider (`landscape`). */\nexport type Orientation = 'portrait' | 'landscape';\n\n/** The host-reported size class, orientation, and pixel box of your app's surface. */\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\n/** Assumed before the host reports — a reasonable desktop default. */\nconst DEFAULT_FORM_FACTOR: FormFactor = {\n  class: 'desktop',\n  orientation: 'landscape',\n  width: 1280,\n  height: 800,\n};\n\nconst isFormFactor = (v: unknown): v is FormFactor => {\n  const f = v as Partial<FormFactor> | null;\n  return (\n    !!f &&\n    (f.class === 'mobile' || f.class === 'tablet' || f.class === 'desktop') &&\n    (f.orientation === 'portrait' || f.orientation === 'landscape') &&\n    typeof f.width === 'number' &&\n    typeof f.height === 'number'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `form-factor`\n// and answers `request-form-factor` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<FormFactor>({\n  pushType: 'form-factor',\n  requestType: 'request-form-factor',\n  initial: DEFAULT_FORM_FACTOR,\n  parse: (msg) => (isFormFactor(msg.formFactor) ? (msg.formFactor as FormFactor) : undefined),\n});\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor => channel.get();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (listener: (formFactor: FormFactor) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => channel.use();\n"],"mappings":"AAAA,SAAS,yBAAyB;AAyBlC,MAAM,sBAAkC;AAAA,EACtC,OAAO;AAAA,EACP,aAAa;AAAA,EACb,OAAO;AAAA,EACP,QAAQ;AACV;AAEA,MAAM,eAAe,CAAC,MAAgC;AACpD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,UAAU,YAAY,EAAE,UAAU,YAAY,EAAE,UAAU,eAC5D,EAAE,gBAAgB,cAAc,EAAE,gBAAgB,gBACnD,OAAO,EAAE,UAAU,YACnB,OAAO,EAAE,WAAW;AAExB;AAIA,MAAM,UAAU,kBAA8B;AAAA,EAC5C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,aAAa,IAAI,UAAU,IAAK,IAAI,aAA4B;AACnF,CAAC;AAGM,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;AAMpD,MAAM,qBAAqB,CAAC,aACjC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\n/** Whether the rendered surface is taller than wide (`portrait`) or wider (`landscape`). */\nexport type Orientation = 'portrait' | 'landscape';\n\n/** The host-reported size class, orientation, and pixel box of your app's surface. */\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\n/** Assumed before the host reports — a reasonable desktop default. */\nconst DEFAULT_FORM_FACTOR: FormFactor = {\n  class: 'desktop',\n  orientation: 'landscape',\n  width: 1280,\n  height: 800,\n};\n\nconst isFormFactor = (v: unknown): v is FormFactor => {\n  const f = v as Partial<FormFactor> | null;\n  return (\n    !!f &&\n    (f.class === 'mobile' || f.class === 'tablet' || f.class === 'desktop') &&\n    (f.orientation === 'portrait' || f.orientation === 'landscape') &&\n    typeof f.width === 'number' &&\n    typeof f.height === 'number'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `form-factor`\n// and answers `request-form-factor` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<FormFactor>({\n  pushType: 'form-factor',\n  requestType: 'request-form-factor',\n  initial: DEFAULT_FORM_FACTOR,\n  parse: (msg) => (isFormFactor(msg.formFactor) ? (msg.formFactor as FormFactor) : undefined),\n});\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor => channel.get();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (listener: (formFactor: FormFactor) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => channel.use();\n"],"mappings":";AAAA,SAAS,yBAAyB;AAyBlC,MAAM,sBAAkC;AAAA,EACtC,OAAO;AAAA,EACP,aAAa;AAAA,EACb,OAAO;AAAA,EACP,QAAQ;AACV;AAEA,MAAM,eAAe,CAAC,MAAgC;AACpD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,UAAU,YAAY,EAAE,UAAU,YAAY,EAAE,UAAU,eAC5D,EAAE,gBAAgB,cAAc,EAAE,gBAAgB,gBACnD,OAAO,EAAE,UAAU,YACnB,OAAO,EAAE,WAAW;AAExB;AAIA,MAAM,UAAU,kBAA8B;AAAA,EAC5C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,aAAa,IAAI,UAAU,IAAK,IAAI,aAA4B;AACnF,CAAC;AAGM,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;AAMpD,MAAM,qBAAqB,CAAC,aACjC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;","names":[]}

package/dist/fs.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { getAppMountPath } from "./mounts";
 import { onFsChange } from "./onFsChange";
 const hasFs = (fs) => typeof fs?.promises?.readFile === "function" || typeof fs?.readFile === "function";

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 =>\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":[]}

package/dist/hooks.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { use, useEffect, useMemo, useRef, useState } from "react";
 import { TinkerableContext } from "./TinkerableContext";
 import { openFs } from "./fs";

package/dist/hooks.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks.ts"],"sourcesContent":["import { use, useEffect, useMemo, useRef, useState } from 'react';\nimport { TinkerableContext } from './TinkerableContext';\nimport { openFs, type FsError } from './fs';\nimport type { SandboxMount } from './mounts';\nimport {\n  FilesMetadata,\n  Metadata,\n  MetadataQueryEntry,\n  MetadataQueryFunction,\n  MetadataQueryResult,\n} from './sandboxTypes';\n\nconst entriesEqual = <T>(a: MetadataQueryEntry<T>[], b: MetadataQueryEntry<T>[]): boolean => {\n  if (a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    // Unchanged frontmatter keeps its object identity across `metadata-update`\n    // merges, so an identity check on `meta` is a sound \"did this match change?\".\n    if (a[i].path !== b[i].path || a[i].meta !== b[i].meta) {\n      return false;\n    }\n  }\n  return true;\n};\n\n/**\n * Query the file metadata store (MDX frontmatter) with a plain JS function.\n *\n * The query receives every file's frontmatter keyed by path and returns the paths\n * that match; the hook resolves each path back to its frontmatter and returns an\n * array of `{ path, meta }` entries — so a single call gives you everything you\n * filtered on, with no second lookup. A throwing query is reported as `{ error }`\n * rather than crashing the render.\n *\n * The query runs synchronously during render (no empty first frame), and the\n * returned array keeps its identity while the matches are unchanged, so it is safe\n * to use directly in downstream `useMemo`/`useEffect` dependency arrays.\n *\n * Pass a type parameter to get typed frontmatter throughout:\n * ```ts\n * interface PostMeta { title: string; date: string; draft?: boolean }\n * const posts = useMetadataQuery<PostMeta>((files) =>\n *   Object.entries(files)\n *     .filter(([, m]) => !m.draft)\n *     .sort(([, a], [, b]) => b.date.localeCompare(a.date))\n *     .map(([path]) => path),\n * );\n * ```\n */\nexport const useMetadataQuery = <T = Metadata>(\n  queryFunction: MetadataQueryFunction<T>,\n): MetadataQueryResult<T> => {\n  const { filesMetadata } = use(TinkerableContext);\n  const previous = useRef<MetadataQueryEntry<T>[]>([]);\n  return useMemo<MetadataQueryResult<T>>(() => {\n    const files = (filesMetadata ?? {}) as FilesMetadata<T>;\n    let entries: MetadataQueryEntry<T>[];\n    try {\n      entries = queryFunction(files).map((path) => ({ path, meta: files[path] }));\n    } catch (error) {\n      return { error };\n    }\n    // Preserve the prior array reference when nothing matched differently.\n    if (entriesEqual(entries, previous.current)) {\n      return previous.current;\n    }\n    previous.current = entries;\n    return entries;\n  }, [filesMetadata, queryFunction]);\n};\n\n/**\n * Read one file's metadata (MDX frontmatter) by repo-relative path. Returns\n * `undefined` when the path has no metadata. Pass a type parameter for typed\n * field access.\n */\nexport const useFileMetadata = <T = Metadata>(path: string): T | undefined => {\n  const { filesMetadata } = use(TinkerableContext);\n  return useMemo(\n    () => (filesMetadata ?? {})[path] as T | undefined,\n    [path, filesMetadata],\n  );\n};\n\n/**\n * The raw, reactive metadata store: a map from file path to frontmatter. The\n * escape hatch for apps that want to render their own index rather than express it\n * as a path-returning query. Pass a type parameter for typed frontmatter values.\n */\nexport const useAllMetadata = <T = Metadata>(): FilesMetadata<T> => {\n  const { filesMetadata } = use(TinkerableContext);\n  return (filesMetadata ?? {}) as FilesMetadata<T>;\n};\n\n/** The reactive state returned by {@link useObjectUrl}. */\nexport interface ObjectUrlState {\n  /** The object URL once the bytes have loaded; `null` while loading or on error. */\n  url: string | null;\n  /** True while the file is being read. */\n  loading: boolean;\n  /** The {@link FsError} if the read failed (`not-found`, `unavailable`, …), else `null`. */\n  error: FsError | null;\n}\n\n/**\n * Read a file from a mount into an **object URL** for `<img src>`, revoking it\n * automatically on unmount or when `mount`/`relPath` changes. This is the React\n * answer to \"an opaque-origin iframe can't fetch a mount path\": it reads the bytes\n * off the sandbox ZenFS ({@link openFs}) and hands you a URL to drop into an\n * `<img>`, and it owns the create/revoke lifecycle so you never leak a URL.\n *\n * Pass `null`/`undefined` for `mount` or `relPath` to mean \"nothing to load yet\"\n * (idle state, no read). For a ready-made element use `MountImage`.\n *\n * ```tsx\n * const { url, loading, error } = useObjectUrl(mount, 'photos/cat.png');\n * if (loading) return <Spinner />;\n * if (error || !url) return <span>missing</span>;\n * return <img src={url} alt=\"cat\" />;\n * ```\n */\nexport const useObjectUrl = (\n  mount: SandboxMount | null | undefined,\n  relPath: string | null | undefined,\n  opts?: { type?: string },\n): ObjectUrlState => {\n  const [state, setState] = useState<ObjectUrlState>({\n    url: null,\n    loading: Boolean(mount && relPath),\n    error: null,\n  });\n  const type = opts?.type;\n  // Key the effect on the mount's stable `path` (its object identity churns as the\n  // mount set re-announces) plus the relPath and the optional type override.\n  const mountPath = mount?.path;\n  useEffect(() => {\n    if (!mount || !relPath) {\n      setState({ url: null, loading: false, error: null });\n      return;\n    }\n    let alive = true;\n    let revoke: (() => void) | null = null;\n    setState({ url: null, loading: true, error: null });\n    openFs(mount)\n      .readObjectUrl(relPath, type ? { type } : undefined)\n      .then((res) => {\n        // Lost the race (unmounted / prop changed): revoke immediately, don't set.\n        if (!alive) {\n          res.revoke();\n          return;\n        }\n        revoke = res.revoke;\n        setState({ url: res.url, loading: false, error: null });\n      })\n      .catch((e) => {\n        if (alive) setState({ url: null, loading: false, error: e as FsError });\n      });\n    return () => {\n      alive = false;\n      if (revoke) revoke();\n    };\n    // `mount` is intentionally tracked via its stable `mountPath`.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [mountPath, relPath, type]);\n  return state;\n};\n"],"mappings":"AAAA,SAAS,KAAK,WAAW,SAAS,QAAQ,gBAAgB;AAC1D,SAAS,yBAAyB;AAClC,SAAS,cAA4B;AAUrC,MAAM,eAAe,CAAI,GAA4B,MAAwC;AAC3F,MAAI,EAAE,WAAW,EAAE,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AAGjC,QAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM;AACtD,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AA0BO,MAAM,mBAAmB,CAC9B,kBAC2B;AAC3B,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,QAAM,WAAW,OAAgC,CAAC,CAAC;AACnD,SAAO,QAAgC,MAAM;AAC3C,UAAM,QAAS,iBAAiB,CAAC;AACjC,QAAI;AACJ,QAAI;AACF,gBAAU,cAAc,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,MAAM,MAAM,IAAI,EAAE,EAAE;AAAA,IAC5E,SAAS,OAAO;AACd,aAAO,EAAE,MAAM;AAAA,IACjB;AAEA,QAAI,aAAa,SAAS,SAAS,OAAO,GAAG;AAC3C,aAAO,SAAS;AAAA,IAClB;AACA,aAAS,UAAU;AACnB,WAAO;AAAA,EACT,GAAG,CAAC,eAAe,aAAa,CAAC;AACnC;AAOO,MAAM,kBAAkB,CAAe,SAAgC;AAC5E,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,SAAO;AAAA,IACL,OAAO,iBAAiB,CAAC,GAAG,IAAI;AAAA,IAChC,CAAC,MAAM,aAAa;AAAA,EACtB;AACF;AAOO,MAAM,iBAAiB,MAAsC;AAClE,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,SAAQ,iBAAiB,CAAC;AAC5B;AA6BO,MAAM,eAAe,CAC1B,OACA,SACA,SACmB;AACnB,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAyB;AAAA,IACjD,KAAK;AAAA,IACL,SAAS,QAAQ,SAAS,OAAO;AAAA,IACjC,OAAO;AAAA,EACT,CAAC;AACD,QAAM,OAAO,MAAM;AAGnB,QAAM,YAAY,OAAO;AACzB,YAAU,MAAM;AACd,QAAI,CAAC,SAAS,CAAC,SAAS;AACtB,eAAS,EAAE,KAAK,MAAM,SAAS,OAAO,OAAO,KAAK,CAAC;AACnD;AAAA,IACF;AACA,QAAI,QAAQ;AACZ,QAAI,SAA8B;AAClC,aAAS,EAAE,KAAK,MAAM,SAAS,MAAM,OAAO,KAAK,CAAC;AAClD,WAAO,KAAK,EACT,cAAc,SAAS,OAAO,EAAE,KAAK,IAAI,MAAS,EAClD,KAAK,CAAC,QAAQ;AAEb,UAAI,CAAC,OAAO;AACV,YAAI,OAAO;AACX;AAAA,MACF;AACA,eAAS,IAAI;AACb,eAAS,EAAE,KAAK,IAAI,KAAK,SAAS,OAAO,OAAO,KAAK,CAAC;AAAA,IACxD,CAAC,EACA,MAAM,CAAC,MAAM;AACZ,UAAI,MAAO,UAAS,EAAE,KAAK,MAAM,SAAS,OAAO,OAAO,EAAa,CAAC;AAAA,IACxE,CAAC;AACH,WAAO,MAAM;AACX,cAAQ;AACR,UAAI,OAAQ,QAAO;AAAA,IACrB;AAAA,EAGF,GAAG,CAAC,WAAW,SAAS,IAAI,CAAC;AAC7B,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/hooks.ts"],"sourcesContent":["import { use, useEffect, useMemo, useRef, useState } from 'react';\nimport { TinkerableContext } from './TinkerableContext';\nimport { openFs, type FsError } from './fs';\nimport type { SandboxMount } from './mounts';\nimport {\n  FilesMetadata,\n  Metadata,\n  MetadataQueryEntry,\n  MetadataQueryFunction,\n  MetadataQueryResult,\n} from './sandboxTypes';\n\nconst entriesEqual = <T>(a: MetadataQueryEntry<T>[], b: MetadataQueryEntry<T>[]): boolean => {\n  if (a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    // Unchanged frontmatter keeps its object identity across `metadata-update`\n    // merges, so an identity check on `meta` is a sound \"did this match change?\".\n    if (a[i].path !== b[i].path || a[i].meta !== b[i].meta) {\n      return false;\n    }\n  }\n  return true;\n};\n\n/**\n * Query the file metadata store (MDX frontmatter) with a plain JS function.\n *\n * The query receives every file's frontmatter keyed by path and returns the paths\n * that match; the hook resolves each path back to its frontmatter and returns an\n * array of `{ path, meta }` entries — so a single call gives you everything you\n * filtered on, with no second lookup. A throwing query is reported as `{ error }`\n * rather than crashing the render.\n *\n * The query runs synchronously during render (no empty first frame), and the\n * returned array keeps its identity while the matches are unchanged, so it is safe\n * to use directly in downstream `useMemo`/`useEffect` dependency arrays.\n *\n * Pass a type parameter to get typed frontmatter throughout:\n * ```ts\n * interface PostMeta { title: string; date: string; draft?: boolean }\n * const posts = useMetadataQuery<PostMeta>((files) =>\n *   Object.entries(files)\n *     .filter(([, m]) => !m.draft)\n *     .sort(([, a], [, b]) => b.date.localeCompare(a.date))\n *     .map(([path]) => path),\n * );\n * ```\n */\nexport const useMetadataQuery = <T = Metadata>(\n  queryFunction: MetadataQueryFunction<T>,\n): MetadataQueryResult<T> => {\n  const { filesMetadata } = use(TinkerableContext);\n  const previous = useRef<MetadataQueryEntry<T>[]>([]);\n  return useMemo<MetadataQueryResult<T>>(() => {\n    const files = (filesMetadata ?? {}) as FilesMetadata<T>;\n    let entries: MetadataQueryEntry<T>[];\n    try {\n      entries = queryFunction(files).map((path) => ({ path, meta: files[path] }));\n    } catch (error) {\n      return { error };\n    }\n    // Preserve the prior array reference when nothing matched differently.\n    if (entriesEqual(entries, previous.current)) {\n      return previous.current;\n    }\n    previous.current = entries;\n    return entries;\n  }, [filesMetadata, queryFunction]);\n};\n\n/**\n * Read one file's metadata (MDX frontmatter) by repo-relative path. Returns\n * `undefined` when the path has no metadata. Pass a type parameter for typed\n * field access.\n */\nexport const useFileMetadata = <T = Metadata>(path: string): T | undefined => {\n  const { filesMetadata } = use(TinkerableContext);\n  return useMemo(\n    () => (filesMetadata ?? {})[path] as T | undefined,\n    [path, filesMetadata],\n  );\n};\n\n/**\n * The raw, reactive metadata store: a map from file path to frontmatter. The\n * escape hatch for apps that want to render their own index rather than express it\n * as a path-returning query. Pass a type parameter for typed frontmatter values.\n */\nexport const useAllMetadata = <T = Metadata>(): FilesMetadata<T> => {\n  const { filesMetadata } = use(TinkerableContext);\n  return (filesMetadata ?? {}) as FilesMetadata<T>;\n};\n\n/** The reactive state returned by {@link useObjectUrl}. */\nexport interface ObjectUrlState {\n  /** The object URL once the bytes have loaded; `null` while loading or on error. */\n  url: string | null;\n  /** True while the file is being read. */\n  loading: boolean;\n  /** The {@link FsError} if the read failed (`not-found`, `unavailable`, …), else `null`. */\n  error: FsError | null;\n}\n\n/**\n * Read a file from a mount into an **object URL** for `<img src>`, revoking it\n * automatically on unmount or when `mount`/`relPath` changes. This is the React\n * answer to \"an opaque-origin iframe can't fetch a mount path\": it reads the bytes\n * off the sandbox ZenFS ({@link openFs}) and hands you a URL to drop into an\n * `<img>`, and it owns the create/revoke lifecycle so you never leak a URL.\n *\n * Pass `null`/`undefined` for `mount` or `relPath` to mean \"nothing to load yet\"\n * (idle state, no read). For a ready-made element use `MountImage`.\n *\n * ```tsx\n * const { url, loading, error } = useObjectUrl(mount, 'photos/cat.png');\n * if (loading) return <Spinner />;\n * if (error || !url) return <span>missing</span>;\n * return <img src={url} alt=\"cat\" />;\n * ```\n */\nexport const useObjectUrl = (\n  mount: SandboxMount | null | undefined,\n  relPath: string | null | undefined,\n  opts?: { type?: string },\n): ObjectUrlState => {\n  const [state, setState] = useState<ObjectUrlState>({\n    url: null,\n    loading: Boolean(mount && relPath),\n    error: null,\n  });\n  const type = opts?.type;\n  // Key the effect on the mount's stable `path` (its object identity churns as the\n  // mount set re-announces) plus the relPath and the optional type override.\n  const mountPath = mount?.path;\n  useEffect(() => {\n    if (!mount || !relPath) {\n      setState({ url: null, loading: false, error: null });\n      return;\n    }\n    let alive = true;\n    let revoke: (() => void) | null = null;\n    setState({ url: null, loading: true, error: null });\n    openFs(mount)\n      .readObjectUrl(relPath, type ? { type } : undefined)\n      .then((res) => {\n        // Lost the race (unmounted / prop changed): revoke immediately, don't set.\n        if (!alive) {\n          res.revoke();\n          return;\n        }\n        revoke = res.revoke;\n        setState({ url: res.url, loading: false, error: null });\n      })\n      .catch((e) => {\n        if (alive) setState({ url: null, loading: false, error: e as FsError });\n      });\n    return () => {\n      alive = false;\n      if (revoke) revoke();\n    };\n    // `mount` is intentionally tracked via its stable `mountPath`.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [mountPath, relPath, type]);\n  return state;\n};\n"],"mappings":";AAAA,SAAS,KAAK,WAAW,SAAS,QAAQ,gBAAgB;AAC1D,SAAS,yBAAyB;AAClC,SAAS,cAA4B;AAUrC,MAAM,eAAe,CAAI,GAA4B,MAAwC;AAC3F,MAAI,EAAE,WAAW,EAAE,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AAGjC,QAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM;AACtD,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AA0BO,MAAM,mBAAmB,CAC9B,kBAC2B;AAC3B,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,QAAM,WAAW,OAAgC,CAAC,CAAC;AACnD,SAAO,QAAgC,MAAM;AAC3C,UAAM,QAAS,iBAAiB,CAAC;AACjC,QAAI;AACJ,QAAI;AACF,gBAAU,cAAc,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,MAAM,MAAM,IAAI,EAAE,EAAE;AAAA,IAC5E,SAAS,OAAO;AACd,aAAO,EAAE,MAAM;AAAA,IACjB;AAEA,QAAI,aAAa,SAAS,SAAS,OAAO,GAAG;AAC3C,aAAO,SAAS;AAAA,IAClB;AACA,aAAS,UAAU;AACnB,WAAO;AAAA,EACT,GAAG,CAAC,eAAe,aAAa,CAAC;AACnC;AAOO,MAAM,kBAAkB,CAAe,SAAgC;AAC5E,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,SAAO;AAAA,IACL,OAAO,iBAAiB,CAAC,GAAG,IAAI;AAAA,IAChC,CAAC,MAAM,aAAa;AAAA,EACtB;AACF;AAOO,MAAM,iBAAiB,MAAsC;AAClE,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,SAAQ,iBAAiB,CAAC;AAC5B;AA6BO,MAAM,eAAe,CAC1B,OACA,SACA,SACmB;AACnB,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAyB;AAAA,IACjD,KAAK;AAAA,IACL,SAAS,QAAQ,SAAS,OAAO;AAAA,IACjC,OAAO;AAAA,EACT,CAAC;AACD,QAAM,OAAO,MAAM;AAGnB,QAAM,YAAY,OAAO;AACzB,YAAU,MAAM;AACd,QAAI,CAAC,SAAS,CAAC,SAAS;AACtB,eAAS,EAAE,KAAK,MAAM,SAAS,OAAO,OAAO,KAAK,CAAC;AACnD;AAAA,IACF;AACA,QAAI,QAAQ;AACZ,QAAI,SAA8B;AAClC,aAAS,EAAE,KAAK,MAAM,SAAS,MAAM,OAAO,KAAK,CAAC;AAClD,WAAO,KAAK,EACT,cAAc,SAAS,OAAO,EAAE,KAAK,IAAI,MAAS,EAClD,KAAK,CAAC,QAAQ;AAEb,UAAI,CAAC,OAAO;AACV,YAAI,OAAO;AACX;AAAA,MACF;AACA,eAAS,IAAI;AACb,eAAS,EAAE,KAAK,IAAI,KAAK,SAAS,OAAO,OAAO,KAAK,CAAC;AAAA,IACxD,CAAC,EACA,MAAM,CAAC,MAAM;AACZ,UAAI,MAAO,UAAS,EAAE,KAAK,MAAM,SAAS,OAAO,OAAO,EAAa,CAAC;AAAA,IACxE,CAAC;AACH,WAAO,MAAM;AACX,cAAQ;AACR,UAAI,OAAQ,QAAO;AAAA,IACrB;AAAA,EAGF,GAAG,CAAC,WAAW,SAAS,IAAI,CAAC;AAC7B,SAAO;AACT;","names":[]}

package/dist/hostRuntime.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 function getHostRuntime() {
   try {
     return globalThis.__immediatelyRun__ ?? null;

package/dist/hostRuntime.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hostRuntime.ts"],"sourcesContent":["// Runtime-discovery global (SDK_PACKAGING_SPEC §4) — a LEAF module that imports\n// nothing, so it can be read by both `sandboxUtils` (transport resolver) and\n// `runtime` (handshake) without forming an import cycle. `sandboxUtils → runtime`\n// + `runtime → sandboxUtils` was a cycle the sandbox bundler cannot evaluate\n// (infinite re-require → \"Maximum call stack size exceeded\"); routing the shared\n// `getHostRuntime` through this leaf breaks it.\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n  /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);\n   *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */\n  appMountPath?: string;\n  /** The chrome region this app instance occupies, e.g. `\"panel.agent\"` or\n   *  `\"stage.conversation\"` (UI_AS_APPS_SPEC §4.1); surfaced via `getRegion()`.\n   *  Absent for a standalone app, in local dev, or on a host that doesn't report\n   *  it. Descriptive only — it grants nothing. */\n  region?: string;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":"AAgCO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../src/hostRuntime.ts"],"sourcesContent":["// Runtime-discovery global (SDK_PACKAGING_SPEC §4) — a LEAF module that imports\n// nothing, so it can be read by both `sandboxUtils` (transport resolver) and\n// `runtime` (handshake) without forming an import cycle. `sandboxUtils → runtime`\n// + `runtime → sandboxUtils` was a cycle the sandbox bundler cannot evaluate\n// (infinite re-require → \"Maximum call stack size exceeded\"); routing the shared\n// `getHostRuntime` through this leaf breaks it.\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n  /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);\n   *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */\n  appMountPath?: string;\n  /** The chrome region this app instance occupies, e.g. `\"panel.agent\"` or\n   *  `\"stage.conversation\"` (UI_AS_APPS_SPEC §4.1); surfaced via `getRegion()`.\n   *  Absent for a standalone app, in local dev, or on a host that doesn't report\n   *  it. Descriptive only — it grants nothing. */\n  region?: string;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";AAgCO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/index.cjs

@@ -43,6 +43,7 @@ __reExport(index_exports, require("./onFsChange"), module.exports);
 __reExport(index_exports, require("./fs"), module.exports);
 __reExport(index_exports, require("./debug"), module.exports);
 __reExport(index_exports, require("./tasks"), module.exports);
+__reExport(index_exports, require("./launch"), module.exports);
 __reExport(index_exports, require("./runtime"), module.exports);
 __reExport(index_exports, require("./irMarkers"), module.exports);
 __reExport(index_exports, require("./ready"), module.exports);
@@ -80,6 +81,7 @@ __reExport(index_exports, require("./safeContent"), module.exports);
   ...require("./fs"),
   ...require("./debug"),
   ...require("./tasks"),
+  ...require("./launch"),
   ...require("./runtime"),
   ...require("./irMarkers"),
   ...require("./ready"),

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oCALd;AAMA,0BAAc,gCANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,mBARd;AASA,0BAAc,oBATd;AAUA,0BAAc,4BAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,yBAZd;AAaA,0BAAc,qBAbd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,yBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,kBAjBd;AAkBA,0BAAc,kBAlBd;AAmBA,0BAAc,uBAnBd;AAoBA,0BAAc,sBApBd;AAqBA,0BAAc,kBArBd;AAsBA,0BAAc,0BAtBd;AAuBA,0BAAc,kBAvBd;AAwBA,0BAAc,yBAxBd;AAyBA,0BAAc,iBAzBd;AA0BA,0BAAc,oBA1Bd;AA2BA,0BAAc,oBA3Bd;AA4BA,0BAAc,sBA5Bd;AA6BA,0BAAc,wBA7Bd;AA8BA,0BAAc,oBA9Bd;AA+BA,0BAAc,sBA/Bd;AAgCA,0BAAc,6BAhCd;AAiCA,0BAAc,2BAjCd;AAkCA,0BAAc,0BAlCd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oCALd;AAMA,0BAAc,gCANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,mBARd;AASA,0BAAc,oBATd;AAUA,0BAAc,4BAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,yBAZd;AAaA,0BAAc,qBAbd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,yBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,kBAjBd;AAkBA,0BAAc,kBAlBd;AAmBA,0BAAc,uBAnBd;AAoBA,0BAAc,sBApBd;AAqBA,0BAAc,kBArBd;AAsBA,0BAAc,0BAtBd;AAuBA,0BAAc,kBAvBd;AAwBA,0BAAc,yBAxBd;AAyBA,0BAAc,iBAzBd;AA0BA,0BAAc,oBA1Bd;AA2BA,0BAAc,oBA3Bd;AA4BA,0BAAc,qBA5Bd;AA6BA,0BAAc,sBA7Bd;AA8BA,0BAAc,wBA9Bd;AA+BA,0BAAc,oBA/Bd;AAgCA,0BAAc,sBAhCd;AAiCA,0BAAc,6BAjCd;AAkCA,0BAAc,2BAlCd;AAmCA,0BAAc,0BAnCd;","names":[]}

package/dist/index.d.cts

@@ -26,6 +26,7 @@ export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.cjs
 export { DirEntry, FileStat, FsError, MountFs, SandboxFsPort, fsAvailable, mimeTypeFor, openAppFs, openFs, sandboxFs } from './fs.cjs';
 export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.cjs';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.cjs';
+export { LaunchErrorCode, LaunchHandle, LaunchOptions, LaunchRegion, LaunchStatus, LaunchTarget, launch } from './launch.cjs';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.cjs';
 export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMarkerName, resolveInteractive, validateMarker } from './irMarkers.cjs';
 export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.cjs';

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.js'
 export { DirEntry, FileStat, FsError, MountFs, SandboxFsPort, fsAvailable, mimeTypeFor, openAppFs, openFs, sandboxFs } from './fs.js';
 export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.js';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.js';
+export { LaunchErrorCode, LaunchHandle, LaunchOptions, LaunchRegion, LaunchStatus, LaunchTarget, launch } from './launch.js';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.js';
 export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMarkerName, resolveInteractive, validateMarker } from './irMarkers.js';
 export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.js';

package/dist/index.js

@@ -26,6 +26,7 @@ export * from "./onFsChange";
 export * from "./fs";
 export * from "./debug";
 export * from "./tasks";
+export * from "./launch";
 export * from "./runtime";
 export * from "./irMarkers";
 export * from "./ready";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/injectedBundler.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 const injectedBundler = () => {
   try {
     return module?.evaluation?.module?.bundler ?? null;

package/dist/injectedBundler.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/injectedBundler.ts"],"sourcesContent":["// Injected sandbox-bundler access (SDK_PACKAGING_SPEC §4/§8, Phase 5). The SDK was\n// historically wired straight to the injected bundler service objects\n// (`module.evaluation.module.bundler.<x>`). Phase 5 makes the SDK transport-agnostic\n// so those services can eventually be retired: every reader PREFERS the injection\n// (so the current, live path stays byte-for-byte unchanged) and FALLS BACK to the\n// §4 transport when the SDK is fetched from npm with no injection present.\n//\n// This module centralizes the `module.evaluation.module.bundler.*` reads (the same\n// philosophy as `sandboxUtils`' transport resolver) and exposes a PURE resolver for\n// the metadata-update subscription so the dual-mode decision is unit-tested without\n// a live bundler. The ambient reads themselves are thin (untestable without the\n// sandbox realm, exactly like `sandboxUtils.transport()`).\n\n/** vscode-style Event source: subscribe with a listener, get a disposable back. */\nexport type EventSource = (listener: (msg: any) => void) => { dispose(): void };\n\n/** The injected bundler's metadata emitter — fires `{type:'metadata-update', update}`\n *  as files (re)compile. Absent when the SDK is npm-fetched (no injection). */\nexport interface InjectedMetadataEmitter {\n  onMetadataChange: EventSource;\n  /** Start the DelayedEmitter once a subscriber is attached (injected path only). */\n  enable(): void;\n}\n\n/** The injected bundler object, or null when there is no injection (npm-fetched). */\nconst injectedBundler = (): any | null => {\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    return module?.evaluation?.module?.bundler ?? null;\n  } catch {\n    return null;\n  }\n};\n\n/** The injected bundler's metadata emitter, or null when npm-fetched. */\nexport const getInjectedMetadataEmitter = (): InjectedMetadataEmitter | null => {\n  const b = injectedBundler();\n  if (b && typeof b.onMetadataChange === 'function' && b.onMetadataChangeEmitter) {\n    return {\n      onMetadataChange: b.onMetadataChange,\n      enable: () => b.onMetadataChangeEmitter.enable(),\n    };\n  }\n  return null;\n};\n\n/**\n * The injected bundler's synchronous metadata snapshot for the boot seed\n * (MDX_CONTENT_COLLECTIONS_SPEC §1.4). Returns the full `/app`-keyed collection the\n * bundler seeded (from the frontmatter sidecar) so the app's first render already\n * holds it — the SDK-side counterpart of the bundler seeding. Null when npm-fetched\n * (no in-realm bundler) → the SDK degrades to event-fill over the §4 transport, no\n * first-paint guarantee. The returned VALUE refs are the same objects the emitter\n * replays, so the `enable()` replay is a no-op (the §1.4 identity contract).\n */\nexport const getInjectedMetadataSnapshot = (): Record<string, Record<string, any>> | null => {\n  const b = injectedBundler();\n  if (b && typeof b.getMetadataSnapshot === 'function') {\n    return b.getMetadataSnapshot();\n  }\n  return null;\n};\n\n/** What `boot` needs to subscribe to metadata updates: the `event` source to hand\n *  `addListener` (the injected emitter, or `undefined` → listen over the transport)\n *  and an `enable` to start the injected DelayedEmitter (a no-op off-injection). */\nexport interface MetadataSource {\n  event?: EventSource;\n  enable(): void;\n}\n\n/**\n * Resolve the metadata-update subscription source (PURE — the dual-mode decision).\n * With the injected emitter: use it and arm it, so the live path is byte-identical.\n * Without it (npm-fetched): return no `event`, so the caller's `addListener` falls\n * back to the §4 transport's `onMessage`, and `enable` is a no-op.\n */\nexport const resolveMetadataSource = (\n  injected: InjectedMetadataEmitter | null,\n): MetadataSource =>\n  injected\n    ? { event: injected.onMetadataChange, enable: () => injected.enable() }\n    : { event: undefined, enable: () => {} };\n"],"mappings":"AAyBA,MAAM,kBAAkB,MAAkB;AACxC,MAAI;AAEF,WAAO,QAAQ,YAAY,QAAQ,WAAW;AAAA,EAChD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGO,MAAM,6BAA6B,MAAsC;AAC9E,QAAM,IAAI,gBAAgB;AAC1B,MAAI,KAAK,OAAO,EAAE,qBAAqB,cAAc,EAAE,yBAAyB;AAC9E,WAAO;AAAA,MACL,kBAAkB,EAAE;AAAA,MACpB,QAAQ,MAAM,EAAE,wBAAwB,OAAO;AAAA,IACjD;AAAA,EACF;AACA,SAAO;AACT;AAWO,MAAM,8BAA8B,MAAkD;AAC3F,QAAM,IAAI,gBAAgB;AAC1B,MAAI,KAAK,OAAO,EAAE,wBAAwB,YAAY;AACpD,WAAO,EAAE,oBAAoB;AAAA,EAC/B;AACA,SAAO;AACT;AAgBO,MAAM,wBAAwB,CACnC,aAEA,WACI,EAAE,OAAO,SAAS,kBAAkB,QAAQ,MAAM,SAAS,OAAO,EAAE,IACpE,EAAE,OAAO,QAAW,QAAQ,MAAM;AAAC,EAAE;","names":[]}
+{"version":3,"sources":["../src/injectedBundler.ts"],"sourcesContent":["// Injected sandbox-bundler access (SDK_PACKAGING_SPEC §4/§8, Phase 5). The SDK was\n// historically wired straight to the injected bundler service objects\n// (`module.evaluation.module.bundler.<x>`). Phase 5 makes the SDK transport-agnostic\n// so those services can eventually be retired: every reader PREFERS the injection\n// (so the current, live path stays byte-for-byte unchanged) and FALLS BACK to the\n// §4 transport when the SDK is fetched from npm with no injection present.\n//\n// This module centralizes the `module.evaluation.module.bundler.*` reads (the same\n// philosophy as `sandboxUtils`' transport resolver) and exposes a PURE resolver for\n// the metadata-update subscription so the dual-mode decision is unit-tested without\n// a live bundler. The ambient reads themselves are thin (untestable without the\n// sandbox realm, exactly like `sandboxUtils.transport()`).\n\n/** vscode-style Event source: subscribe with a listener, get a disposable back. */\nexport type EventSource = (listener: (msg: any) => void) => { dispose(): void };\n\n/** The injected bundler's metadata emitter — fires `{type:'metadata-update', update}`\n *  as files (re)compile. Absent when the SDK is npm-fetched (no injection). */\nexport interface InjectedMetadataEmitter {\n  onMetadataChange: EventSource;\n  /** Start the DelayedEmitter once a subscriber is attached (injected path only). */\n  enable(): void;\n}\n\n/** The injected bundler object, or null when there is no injection (npm-fetched). */\nconst injectedBundler = (): any | null => {\n  try {\n    // @ts-ignore - `module.evaluation` is injected by the sandbox runtime\n    return module?.evaluation?.module?.bundler ?? null;\n  } catch {\n    return null;\n  }\n};\n\n/** The injected bundler's metadata emitter, or null when npm-fetched. */\nexport const getInjectedMetadataEmitter = (): InjectedMetadataEmitter | null => {\n  const b = injectedBundler();\n  if (b && typeof b.onMetadataChange === 'function' && b.onMetadataChangeEmitter) {\n    return {\n      onMetadataChange: b.onMetadataChange,\n      enable: () => b.onMetadataChangeEmitter.enable(),\n    };\n  }\n  return null;\n};\n\n/**\n * The injected bundler's synchronous metadata snapshot for the boot seed\n * (MDX_CONTENT_COLLECTIONS_SPEC §1.4). Returns the full `/app`-keyed collection the\n * bundler seeded (from the frontmatter sidecar) so the app's first render already\n * holds it — the SDK-side counterpart of the bundler seeding. Null when npm-fetched\n * (no in-realm bundler) → the SDK degrades to event-fill over the §4 transport, no\n * first-paint guarantee. The returned VALUE refs are the same objects the emitter\n * replays, so the `enable()` replay is a no-op (the §1.4 identity contract).\n */\nexport const getInjectedMetadataSnapshot = (): Record<string, Record<string, any>> | null => {\n  const b = injectedBundler();\n  if (b && typeof b.getMetadataSnapshot === 'function') {\n    return b.getMetadataSnapshot();\n  }\n  return null;\n};\n\n/** What `boot` needs to subscribe to metadata updates: the `event` source to hand\n *  `addListener` (the injected emitter, or `undefined` → listen over the transport)\n *  and an `enable` to start the injected DelayedEmitter (a no-op off-injection). */\nexport interface MetadataSource {\n  event?: EventSource;\n  enable(): void;\n}\n\n/**\n * Resolve the metadata-update subscription source (PURE — the dual-mode decision).\n * With the injected emitter: use it and arm it, so the live path is byte-identical.\n * Without it (npm-fetched): return no `event`, so the caller's `addListener` falls\n * back to the §4 transport's `onMessage`, and `enable` is a no-op.\n */\nexport const resolveMetadataSource = (\n  injected: InjectedMetadataEmitter | null,\n): MetadataSource =>\n  injected\n    ? { event: injected.onMetadataChange, enable: () => injected.enable() }\n    : { event: undefined, enable: () => {} };\n"],"mappings":";AAyBA,MAAM,kBAAkB,MAAkB;AACxC,MAAI;AAEF,WAAO,QAAQ,YAAY,QAAQ,WAAW;AAAA,EAChD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGO,MAAM,6BAA6B,MAAsC;AAC9E,QAAM,IAAI,gBAAgB;AAC1B,MAAI,KAAK,OAAO,EAAE,qBAAqB,cAAc,EAAE,yBAAyB;AAC9E,WAAO;AAAA,MACL,kBAAkB,EAAE;AAAA,MACpB,QAAQ,MAAM,EAAE,wBAAwB,OAAO;AAAA,IACjD;AAAA,EACF;AACA,SAAO;AACT;AAWO,MAAM,8BAA8B,MAAkD;AAC3F,QAAM,IAAI,gBAAgB;AAC1B,MAAI,KAAK,OAAO,EAAE,wBAAwB,YAAY;AACpD,WAAO,EAAE,oBAAoB;AAAA,EAC/B;AACA,SAAO;AACT;AAgBO,MAAM,wBAAwB,CACnC,aAEA,WACI,EAAE,OAAO,SAAS,kBAAkB,QAAQ,MAAM,SAAS,OAAO,EAAE,IACpE,EAAE,OAAO,QAAW,QAAQ,MAAM;AAAC,EAAE;","names":[]}

package/dist/ipc.js

@@ -1,3 +1,4 @@
+import "./chunk-VHAA22YE.js";
 import { useEffect, useState } from "react";
 import { protocolRequest, addListener } from "./sandboxUtils";
 const postToRegion = async (region, data) => {

package/dist/ipc.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":"AAIA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,mBAAmB;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,MAAM,gBAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,aAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,IAAI,SAA+B,IAAI;AACzD,YAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":";AAIA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,mBAAmB;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,MAAM,gBAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,aAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,IAAI,SAA+B,IAAI;AACzD,YAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}