@immediately-run/sdk 0.38.0 → 0.40.0

package/dist/catalog.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/catalog.ts"],"sourcesContent":["// The method catalog (UI_AS_APPS_SPEC §5.5) — the app's own grant-filtered RPC\n// surface, and a generic way to call it. The host advertises exactly the methods\n// this app may invoke (MCP-tool-shaped); `invoke()` calls one by its catalog name.\n// Handing the catalog to an embedded agent as its tool list confines the agent to\n// the app's authority (agent sandboxing falls out of the capability model, §5.9).\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport type { StreamFrame, StreamTransport } from './protocolStream';\nimport { consumeStream } from './protocolStream';\nimport { createPushChannel } from './pushChannel';\n\n/** One advertised method, as the host generated it from its gate table. */\nexport interface ApiMethod {\n  /** Catalog name, `protocol-` stripped — e.g. `spaces:share`, `contribute:run`. */\n  name: string;\n  /** The capability this method requires (already held — it's in your catalog). */\n  capability: string;\n  /** True when the method STREAMS (use {@link invokeStream}) vs. single-reply. */\n  stream?: boolean;\n  /**\n   * JSON Schema for the method's single object argument, when the host declares one.\n   * Self-describes the call so a catalog-as-tools bridge (an embedded agent) can\n   * advertise the real param shape — e.g. that `authoring:typecheck` takes a nested\n   * `{ files: [{ path, content }] }` array — instead of a permissive \"any object\".\n   * Absent for methods the host advertises without a schema.\n   */\n  paramsSchema?: Record<string, unknown>;\n}\n\n// `scheme:method` → ['scheme', 'method'] (the wire protocol is `protocol-scheme`).\nconst split = (name: string): [string, string] => {\n  const i = name.indexOf(':');\n  if (i <= 0) throw new Error(`invalid catalog method name: ${name}`);\n  return [name.slice(0, i), name.slice(i + 1)];\n};\n\n/**\n * Call a catalog method by name — `invoke('spaces:share', { spaceId, login, role })`.\n * A thin generic over the host protocol: the host validates params and gates the\n * call (an un-granted method → `forbidden`, even if you name it directly). For a\n * STREAMING method (`ApiMethod.stream`), use {@link invokeStream}.\n */\nexport const invoke = async <T = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): Promise<T> => {\n  const [scheme, method] = split(name);\n  // The host replies with an `{ ok, data } | { ok:false, code }` envelope; unwrap\n  // it and THROW on refusal (a `.code` like `forbidden` for an off-catalog call)\n  // so callers — and any agent driving `invoke` — see the gate's verdict.\n  const res = (await protocolRequest(scheme, method, [params])) as\n    | { ok: true; data: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `${name} failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Stream transport over the resolver (SDK_PACKAGING_SPEC §4) — sendMessage /\n// addListener route through `transport()` (injected bundler messageBus or the §4\n// global), never `bundler.messageBus` directly.\nconst streamTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  // Early-cancel: route a `{type, msgId, cancel:true}` frame back to the host so it\n  // aborts the in-flight generation (and, for `llm:chat`, stops billing) — §3.3.\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/** Call a STREAMING catalog method by name, yielding its events. Pass `signal` to\n *  abort mid-stream: the host stops generating and (for `llm:chat`) stops billing. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n  signal?: AbortSignal,\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(streamTransport, `protocol-${scheme}`, method, [params], undefined, signal);\n}\n\n// The catalog list is read over the transport (§4): the host pushes `api-catalog`\n// and answers `request-api-catalog` with this app's grant-filtered methods (wire\n// format: site-main channelBridge.ts).\nconst channel = createPushChannel<ApiMethod[]>({\n  pushType: 'api-catalog',\n  requestType: 'request-api-catalog',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.methods) ? (msg.methods as ApiMethod[]) : undefined),\n});\n\n/** The methods this app may call (grant-filtered, §5.5). Poll for a one-off read;\n *  use {@link onCatalogChange} / {@link useCatalog} to react. */\nexport const getCatalog = (): ApiMethod[] => channel.get();\n\n/** Subscribe to catalog changes (e.g. a grant added/revoked). Invoked immediately\n *  with the current catalog, then on every change. Returns an unsubscribe fn. */\nexport const onCatalogChange = (listener: (catalog: ApiMethod[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning this app's method catalog, re-rendering on change. Hand\n *  it to an embedded agent as its tool list to confine the agent to the app's\n *  authority (§5.9). */\nexport const useCatalog = (): ApiMethod[] => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,0BAA0D;AAE1D,4BAA8B;AAC9B,yBAAkC;AAqBlC,MAAM,QAAQ,CAAC,SAAmC;AAChD,QAAM,IAAI,KAAK,QAAQ,GAAG;AAC1B,MAAI,KAAK,EAAG,OAAM,IAAI,MAAM,gCAAgC,IAAI,EAAE;AAClE,SAAO,CAAC,KAAK,MAAM,GAAG,CAAC,GAAG,KAAK,MAAM,IAAI,CAAC,CAAC;AAC7C;AAQO,MAAM,SAAS,OACpB,MACA,SAAkC,CAAC,MACpB;AACf,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AAInC,QAAM,MAAO,UAAM,qCAAgB,QAAQ,QAAQ,CAAC,MAAM,CAAC;AAI3D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,GAAG,IAAI,SAAS;AACtD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAKA,MAAM,kBAAmC;AAAA,EACvC,MAAM,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,gBAChB,iCAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AAAA;AAAA;AAAA,EAGrF,QAAQ,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAClF;AAIO,SAAS,aACd,MACA,SAAkC,CAAC,GACnC,QAC4B;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,aAAO,qCAAoB,iBAAiB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAW,MAAM;AACvG;AAKA,MAAM,cAAU,sCAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA0B;AAC/E,CAAC;AAIM,MAAM,aAAa,MAAmB,QAAQ,IAAI;AAIlD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAKpB,MAAM,aAAa,MAAmB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/catalog.ts"],"sourcesContent":["// The method catalog (UI_AS_APPS_SPEC §5.5) — the app's own grant-filtered RPC\n// surface, and a generic way to call it. The host advertises exactly the methods\n// this app may invoke (MCP-tool-shaped); `invoke()` calls one by its catalog name.\n// Handing the catalog to an embedded agent as its tool list confines the agent to\n// the app's authority (agent sandboxing falls out of the capability model, §5.9).\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport type { StreamFrame, StreamTransport } from './protocolStream';\nimport { consumeStream } from './protocolStream';\nimport { createPushChannel } from './pushChannel';\n\n/** One advertised method, as the host generated it from its gate table. */\nexport interface ApiMethod {\n  /** Catalog name, `protocol-` stripped — e.g. `spaces:invite`, `contribute:run`. */\n  name: string;\n  /** The capability this method requires (already held — it's in your catalog). */\n  capability: string;\n  /** True when the method STREAMS (use {@link invokeStream}) vs. single-reply. */\n  stream?: boolean;\n  /**\n   * JSON Schema for the method's single object argument, when the host declares one.\n   * Self-describes the call so a catalog-as-tools bridge (an embedded agent) can\n   * advertise the real param shape — e.g. that `authoring:typecheck` takes a nested\n   * `{ files: [{ path, content }] }` array — instead of a permissive \"any object\".\n   * Absent for methods the host advertises without a schema.\n   */\n  paramsSchema?: Record<string, unknown>;\n}\n\n// `scheme:method` → ['scheme', 'method'] (the wire protocol is `protocol-scheme`).\nconst split = (name: string): [string, string] => {\n  const i = name.indexOf(':');\n  if (i <= 0) throw new Error(`invalid catalog method name: ${name}`);\n  return [name.slice(0, i), name.slice(i + 1)];\n};\n\n/**\n * Call a catalog method by name — `invoke('spaces:invite', { spaceId, login, role })`.\n * A thin generic over the host protocol: the host validates params and gates the\n * call (an un-granted method → `forbidden`, even if you name it directly). For a\n * STREAMING method (`ApiMethod.stream`), use {@link invokeStream}.\n */\nexport const invoke = async <T = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): Promise<T> => {\n  const [scheme, method] = split(name);\n  // The host replies with an `{ ok, data } | { ok:false, code }` envelope; unwrap\n  // it and THROW on refusal (a `.code` like `forbidden` for an off-catalog call)\n  // so callers — and any agent driving `invoke` — see the gate's verdict.\n  const res = (await protocolRequest(scheme, method, [params])) as\n    | { ok: true; data: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `${name} failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Stream transport over the resolver (SDK_PACKAGING_SPEC §4) — sendMessage /\n// addListener route through `transport()` (injected bundler messageBus or the §4\n// global), never `bundler.messageBus` directly.\nconst streamTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  // Early-cancel: route a `{type, msgId, cancel:true}` frame back to the host so it\n  // aborts the in-flight generation (and, for `llm:chat`, stops billing) — §3.3.\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/** Call a STREAMING catalog method by name, yielding its events. Pass `signal` to\n *  abort mid-stream: the host stops generating and (for `llm:chat`) stops billing. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n  signal?: AbortSignal,\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(streamTransport, `protocol-${scheme}`, method, [params], undefined, signal);\n}\n\n// The catalog list is read over the transport (§4): the host pushes `api-catalog`\n// and answers `request-api-catalog` with this app's grant-filtered methods (wire\n// format: site-main channelBridge.ts).\nconst channel = createPushChannel<ApiMethod[]>({\n  pushType: 'api-catalog',\n  requestType: 'request-api-catalog',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.methods) ? (msg.methods as ApiMethod[]) : undefined),\n});\n\n/** The methods this app may call (grant-filtered, §5.5). Poll for a one-off read;\n *  use {@link onCatalogChange} / {@link useCatalog} to react. */\nexport const getCatalog = (): ApiMethod[] => channel.get();\n\n/** Subscribe to catalog changes (e.g. a grant added/revoked). Invoked immediately\n *  with the current catalog, then on every change. Returns an unsubscribe fn. */\nexport const onCatalogChange = (listener: (catalog: ApiMethod[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning this app's method catalog, re-rendering on change. Hand\n *  it to an embedded agent as its tool list to confine the agent to the app's\n *  authority (§5.9). */\nexport const useCatalog = (): ApiMethod[] => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,0BAA0D;AAE1D,4BAA8B;AAC9B,yBAAkC;AAqBlC,MAAM,QAAQ,CAAC,SAAmC;AAChD,QAAM,IAAI,KAAK,QAAQ,GAAG;AAC1B,MAAI,KAAK,EAAG,OAAM,IAAI,MAAM,gCAAgC,IAAI,EAAE;AAClE,SAAO,CAAC,KAAK,MAAM,GAAG,CAAC,GAAG,KAAK,MAAM,IAAI,CAAC,CAAC;AAC7C;AAQO,MAAM,SAAS,OACpB,MACA,SAAkC,CAAC,MACpB;AACf,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AAInC,QAAM,MAAO,UAAM,qCAAgB,QAAQ,QAAQ,CAAC,MAAM,CAAC;AAI3D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,GAAG,IAAI,SAAS;AACtD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAKA,MAAM,kBAAmC;AAAA,EACvC,MAAM,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,gBAChB,iCAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AAAA;AAAA;AAAA,EAGrF,QAAQ,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAClF;AAIO,SAAS,aACd,MACA,SAAkC,CAAC,GACnC,QAC4B;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,aAAO,qCAAoB,iBAAiB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAW,MAAM;AACvG;AAKA,MAAM,cAAU,sCAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA0B;AAC/E,CAAC;AAIM,MAAM,aAAa,MAAmB,QAAQ,IAAI;AAIlD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAKpB,MAAM,aAAa,MAAmB,QAAQ,IAAI;","names":[]}

package/dist/catalog.d.cts

@@ -1,6 +1,6 @@
 /** One advertised method, as the host generated it from its gate table. */
 interface ApiMethod {
-    /** Catalog name, `protocol-` stripped — e.g. `spaces:share`, `contribute:run`. */
+    /** Catalog name, `protocol-` stripped — e.g. `spaces:invite`, `contribute:run`. */
     name: string;
     /** The capability this method requires (already held — it's in your catalog). */
     capability: string;
@@ -16,7 +16,7 @@ interface ApiMethod {
     paramsSchema?: Record<string, unknown>;
 }
 /**
- * Call a catalog method by name — `invoke('spaces:share', { spaceId, login, role })`.
+ * Call a catalog method by name — `invoke('spaces:invite', { spaceId, login, role })`.
  * A thin generic over the host protocol: the host validates params and gates the
  * call (an un-granted method → `forbidden`, even if you name it directly). For a
  * STREAMING method (`ApiMethod.stream`), use {@link invokeStream}.

package/dist/catalog.d.ts

@@ -1,6 +1,6 @@
 /** One advertised method, as the host generated it from its gate table. */
 interface ApiMethod {
-    /** Catalog name, `protocol-` stripped — e.g. `spaces:share`, `contribute:run`. */
+    /** Catalog name, `protocol-` stripped — e.g. `spaces:invite`, `contribute:run`. */
     name: string;
     /** The capability this method requires (already held — it's in your catalog). */
     capability: string;
@@ -16,7 +16,7 @@ interface ApiMethod {
     paramsSchema?: Record<string, unknown>;
 }
 /**
- * Call a catalog method by name — `invoke('spaces:share', { spaceId, login, role })`.
+ * Call a catalog method by name — `invoke('spaces:invite', { spaceId, login, role })`.
  * A thin generic over the host protocol: the host validates params and gates the
  * call (an un-granted method → `forbidden`, even if you name it directly). For a
  * STREAMING method (`ApiMethod.stream`), use {@link invokeStream}.

package/dist/catalog.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/catalog.ts"],"sourcesContent":["// The method catalog (UI_AS_APPS_SPEC §5.5) — the app's own grant-filtered RPC\n// surface, and a generic way to call it. The host advertises exactly the methods\n// this app may invoke (MCP-tool-shaped); `invoke()` calls one by its catalog name.\n// Handing the catalog to an embedded agent as its tool list confines the agent to\n// the app's authority (agent sandboxing falls out of the capability model, §5.9).\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport type { StreamFrame, StreamTransport } from './protocolStream';\nimport { consumeStream } from './protocolStream';\nimport { createPushChannel } from './pushChannel';\n\n/** One advertised method, as the host generated it from its gate table. */\nexport interface ApiMethod {\n  /** Catalog name, `protocol-` stripped — e.g. `spaces:share`, `contribute:run`. */\n  name: string;\n  /** The capability this method requires (already held — it's in your catalog). */\n  capability: string;\n  /** True when the method STREAMS (use {@link invokeStream}) vs. single-reply. */\n  stream?: boolean;\n  /**\n   * JSON Schema for the method's single object argument, when the host declares one.\n   * Self-describes the call so a catalog-as-tools bridge (an embedded agent) can\n   * advertise the real param shape — e.g. that `authoring:typecheck` takes a nested\n   * `{ files: [{ path, content }] }` array — instead of a permissive \"any object\".\n   * Absent for methods the host advertises without a schema.\n   */\n  paramsSchema?: Record<string, unknown>;\n}\n\n// `scheme:method` → ['scheme', 'method'] (the wire protocol is `protocol-scheme`).\nconst split = (name: string): [string, string] => {\n  const i = name.indexOf(':');\n  if (i <= 0) throw new Error(`invalid catalog method name: ${name}`);\n  return [name.slice(0, i), name.slice(i + 1)];\n};\n\n/**\n * Call a catalog method by name — `invoke('spaces:share', { spaceId, login, role })`.\n * A thin generic over the host protocol: the host validates params and gates the\n * call (an un-granted method → `forbidden`, even if you name it directly). For a\n * STREAMING method (`ApiMethod.stream`), use {@link invokeStream}.\n */\nexport const invoke = async <T = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): Promise<T> => {\n  const [scheme, method] = split(name);\n  // The host replies with an `{ ok, data } | { ok:false, code }` envelope; unwrap\n  // it and THROW on refusal (a `.code` like `forbidden` for an off-catalog call)\n  // so callers — and any agent driving `invoke` — see the gate's verdict.\n  const res = (await protocolRequest(scheme, method, [params])) as\n    | { ok: true; data: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `${name} failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Stream transport over the resolver (SDK_PACKAGING_SPEC §4) — sendMessage /\n// addListener route through `transport()` (injected bundler messageBus or the §4\n// global), never `bundler.messageBus` directly.\nconst streamTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  // Early-cancel: route a `{type, msgId, cancel:true}` frame back to the host so it\n  // aborts the in-flight generation (and, for `llm:chat`, stops billing) — §3.3.\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/** Call a STREAMING catalog method by name, yielding its events. Pass `signal` to\n *  abort mid-stream: the host stops generating and (for `llm:chat`) stops billing. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n  signal?: AbortSignal,\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(streamTransport, `protocol-${scheme}`, method, [params], undefined, signal);\n}\n\n// The catalog list is read over the transport (§4): the host pushes `api-catalog`\n// and answers `request-api-catalog` with this app's grant-filtered methods (wire\n// format: site-main channelBridge.ts).\nconst channel = createPushChannel<ApiMethod[]>({\n  pushType: 'api-catalog',\n  requestType: 'request-api-catalog',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.methods) ? (msg.methods as ApiMethod[]) : undefined),\n});\n\n/** The methods this app may call (grant-filtered, §5.5). Poll for a one-off read;\n *  use {@link onCatalogChange} / {@link useCatalog} to react. */\nexport const getCatalog = (): ApiMethod[] => channel.get();\n\n/** Subscribe to catalog changes (e.g. a grant added/revoked). Invoked immediately\n *  with the current catalog, then on every change. Returns an unsubscribe fn. */\nexport const onCatalogChange = (listener: (catalog: ApiMethod[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning this app's method catalog, re-rendering on change. Hand\n *  it to an embedded agent as its tool list to confine the agent to the app's\n *  authority (§5.9). */\nexport const useCatalog = (): ApiMethod[] => channel.use();\n"],"mappings":";AAKA,SAAS,iBAAiB,aAAa,mBAAmB;AAE1D,SAAS,qBAAqB;AAC9B,SAAS,yBAAyB;AAqBlC,MAAM,QAAQ,CAAC,SAAmC;AAChD,QAAM,IAAI,KAAK,QAAQ,GAAG;AAC1B,MAAI,KAAK,EAAG,OAAM,IAAI,MAAM,gCAAgC,IAAI,EAAE;AAClE,SAAO,CAAC,KAAK,MAAM,GAAG,CAAC,GAAG,KAAK,MAAM,IAAI,CAAC,CAAC;AAC7C;AAQO,MAAM,SAAS,OACpB,MACA,SAAkC,CAAC,MACpB;AACf,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AAInC,QAAM,MAAO,MAAM,gBAAgB,QAAQ,QAAQ,CAAC,MAAM,CAAC;AAI3D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,GAAG,IAAI,SAAS;AACtD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAKA,MAAM,kBAAmC;AAAA,EACvC,MAAM,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,YAChB,YAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AAAA;AAAA;AAAA,EAGrF,QAAQ,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAClF;AAIO,SAAS,aACd,MACA,SAAkC,CAAC,GACnC,QAC4B;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,SAAO,cAAoB,iBAAiB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAW,MAAM;AACvG;AAKA,MAAM,UAAU,kBAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA0B;AAC/E,CAAC;AAIM,MAAM,aAAa,MAAmB,QAAQ,IAAI;AAIlD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAKpB,MAAM,aAAa,MAAmB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/catalog.ts"],"sourcesContent":["// The method catalog (UI_AS_APPS_SPEC §5.5) — the app's own grant-filtered RPC\n// surface, and a generic way to call it. The host advertises exactly the methods\n// this app may invoke (MCP-tool-shaped); `invoke()` calls one by its catalog name.\n// Handing the catalog to an embedded agent as its tool list confines the agent to\n// the app's authority (agent sandboxing falls out of the capability model, §5.9).\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\nimport type { StreamFrame, StreamTransport } from './protocolStream';\nimport { consumeStream } from './protocolStream';\nimport { createPushChannel } from './pushChannel';\n\n/** One advertised method, as the host generated it from its gate table. */\nexport interface ApiMethod {\n  /** Catalog name, `protocol-` stripped — e.g. `spaces:invite`, `contribute:run`. */\n  name: string;\n  /** The capability this method requires (already held — it's in your catalog). */\n  capability: string;\n  /** True when the method STREAMS (use {@link invokeStream}) vs. single-reply. */\n  stream?: boolean;\n  /**\n   * JSON Schema for the method's single object argument, when the host declares one.\n   * Self-describes the call so a catalog-as-tools bridge (an embedded agent) can\n   * advertise the real param shape — e.g. that `authoring:typecheck` takes a nested\n   * `{ files: [{ path, content }] }` array — instead of a permissive \"any object\".\n   * Absent for methods the host advertises without a schema.\n   */\n  paramsSchema?: Record<string, unknown>;\n}\n\n// `scheme:method` → ['scheme', 'method'] (the wire protocol is `protocol-scheme`).\nconst split = (name: string): [string, string] => {\n  const i = name.indexOf(':');\n  if (i <= 0) throw new Error(`invalid catalog method name: ${name}`);\n  return [name.slice(0, i), name.slice(i + 1)];\n};\n\n/**\n * Call a catalog method by name — `invoke('spaces:invite', { spaceId, login, role })`.\n * A thin generic over the host protocol: the host validates params and gates the\n * call (an un-granted method → `forbidden`, even if you name it directly). For a\n * STREAMING method (`ApiMethod.stream`), use {@link invokeStream}.\n */\nexport const invoke = async <T = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): Promise<T> => {\n  const [scheme, method] = split(name);\n  // The host replies with an `{ ok, data } | { ok:false, code }` envelope; unwrap\n  // it and THROW on refusal (a `.code` like `forbidden` for an off-catalog call)\n  // so callers — and any agent driving `invoke` — see the gate's verdict.\n  const res = (await protocolRequest(scheme, method, [params])) as\n    | { ok: true; data: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `${name} failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n// Stream transport over the resolver (SDK_PACKAGING_SPEC §4) — sendMessage /\n// addListener route through `transport()` (injected bundler messageBus or the §4\n// global), never `bundler.messageBus` directly.\nconst streamTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n  // Early-cancel: route a `{type, msgId, cancel:true}` frame back to the host so it\n  // aborts the in-flight generation (and, for `llm:chat`, stops billing) — §3.3.\n  cancel: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n};\n\n/** Call a STREAMING catalog method by name, yielding its events. Pass `signal` to\n *  abort mid-stream: the host stops generating and (for `llm:chat`) stops billing. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n  signal?: AbortSignal,\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(streamTransport, `protocol-${scheme}`, method, [params], undefined, signal);\n}\n\n// The catalog list is read over the transport (§4): the host pushes `api-catalog`\n// and answers `request-api-catalog` with this app's grant-filtered methods (wire\n// format: site-main channelBridge.ts).\nconst channel = createPushChannel<ApiMethod[]>({\n  pushType: 'api-catalog',\n  requestType: 'request-api-catalog',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.methods) ? (msg.methods as ApiMethod[]) : undefined),\n});\n\n/** The methods this app may call (grant-filtered, §5.5). Poll for a one-off read;\n *  use {@link onCatalogChange} / {@link useCatalog} to react. */\nexport const getCatalog = (): ApiMethod[] => channel.get();\n\n/** Subscribe to catalog changes (e.g. a grant added/revoked). Invoked immediately\n *  with the current catalog, then on every change. Returns an unsubscribe fn. */\nexport const onCatalogChange = (listener: (catalog: ApiMethod[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning this app's method catalog, re-rendering on change. Hand\n *  it to an embedded agent as its tool list to confine the agent to the app's\n *  authority (§5.9). */\nexport const useCatalog = (): ApiMethod[] => channel.use();\n"],"mappings":";AAKA,SAAS,iBAAiB,aAAa,mBAAmB;AAE1D,SAAS,qBAAqB;AAC9B,SAAS,yBAAyB;AAqBlC,MAAM,QAAQ,CAAC,SAAmC;AAChD,QAAM,IAAI,KAAK,QAAQ,GAAG;AAC1B,MAAI,KAAK,EAAG,OAAM,IAAI,MAAM,gCAAgC,IAAI,EAAE;AAClE,SAAO,CAAC,KAAK,MAAM,GAAG,CAAC,GAAG,KAAK,MAAM,IAAI,CAAC,CAAC;AAC7C;AAQO,MAAM,SAAS,OACpB,MACA,SAAkC,CAAC,MACpB;AACf,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AAInC,QAAM,MAAO,MAAM,gBAAgB,QAAQ,QAAQ,CAAC,MAAM,CAAC;AAI3D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,GAAG,IAAI,SAAS;AACtD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAKA,MAAM,kBAAmC;AAAA,EACvC,MAAM,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,YAChB,YAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AAAA;AAAA;AAAA,EAGrF,QAAQ,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAClF;AAIO,SAAS,aACd,MACA,SAAkC,CAAC,GACnC,QAC4B;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,SAAO,cAAoB,iBAAiB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAW,MAAM;AACvG;AAKA,MAAM,UAAU,kBAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA0B;AAC/E,CAAC;AAIM,MAAM,aAAa,MAAmB,QAAQ,IAAI;AAIlD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAKpB,MAAM,aAAa,MAAmB,QAAQ,IAAI;","names":[]}

package/dist/components/Include.cjs

@@ -19,8 +19,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var Include_exports = {};
 __export(Include_exports, {
   Include: () => Include,
+  IncludeModeContext: () => import_includeContexts2.IncludeModeContext,
   RenderExportedComponent: () => RenderExportedComponent,
-  RenderExportedComponentContext: () => RenderExportedComponentContext
+  RenderExportedComponentContext: () => import_includeContexts2.RenderExportedComponentContext
 });
 module.exports = __toCommonJS(Include_exports);
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -28,29 +29,46 @@ var import_react = require("react");
 var import_react_error_boundary = require("react-error-boundary");
 var import_moduleCache = require("../moduleCache");
 var import_defaults = require("./defaults");
-const RenderExportedComponentContext = (0, import_react.createContext)(null);
+var import_includeContexts = require("./includeContexts");
+var import_SafeInclude = require("./SafeInclude");
+var import_includeContexts2 = require("./includeContexts");
 const RenderExportedComponent = ({
   evaluationContextPromise,
   exportedSymbol = "default"
 }) => {
   const evaluationContext = (0, import_react.use)(evaluationContextPromise);
   const Component = exportedSymbol === "*" ? evaluationContext.exports : evaluationContext.exports[exportedSymbol];
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RenderExportedComponentContext, { value: { evaluationContext }, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Component, {}) });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_includeContexts.RenderExportedComponentContext, { value: { evaluationContext }, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Component, {}) });
 };
 const Include = ({
   filename,
   exportedSymbol = "default",
   LoadingComponent = import_defaults.defaultLoadingComponent,
   ErrorComponent = import_defaults.defaultErrorComponent,
-  baseModule
+  baseModule,
+  mode,
+  components
 }) => {
+  const contextMode = (0, import_react.use)(import_includeContexts.IncludeModeContext);
   const moduleCache = (0, import_react.use)(import_moduleCache.ModuleCacheContext);
+  if ((mode ?? contextMode) === "interpreted") {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_SafeInclude.SafeInclude,
+      {
+        filename,
+        components,
+        LoadingComponent,
+        ErrorComponent
+      }
+    );
+  }
   const evaluationContextPromise = moduleCache.getEvaluationContext(filename, baseModule ?? module);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_error_boundary.ErrorBoundary, { fallbackRender: ErrorComponent, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react.Suspense, { fallback: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LoadingComponent, {}), children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RenderExportedComponent, { evaluationContextPromise, exportedSymbol }) }) });
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Include,
+  IncludeModeContext,
   RenderExportedComponent,
   RenderExportedComponentContext
 });

package/dist/components/Include.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/Include.tsx"],"sourcesContent":["import { Suspense, createContext, use } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\nimport { ModuleCacheContext } from '../moduleCache';\nimport { EvaluationContext } from '../sandboxTypes';\nimport { defaultErrorComponent, defaultLoadingComponent } from './defaults';\n\n/** The value exposed on {@link RenderExportedComponentContext}: the evaluation\n *  context of the module {@link Include} resolved. */\nexport type RenderFileContextType = {\n  evaluationContext: EvaluationContext;\n};\n\n/** Context carrying the included module's {@link EvaluationContext} to its subtree. */\nexport const RenderExportedComponentContext = createContext<RenderFileContextType | null>(null);\n\n/** Low-level: render one export of an already-resolving module evaluation. Most\n *  code should use {@link Include}, which resolves the module and adds Suspense. */\nexport const RenderExportedComponent = ({\n  evaluationContextPromise,\n  exportedSymbol = 'default',\n}: {\n  evaluationContextPromise: Promise<EvaluationContext>;\n  exportedSymbol: string;\n}) => {\n  const evaluationContext = use(evaluationContextPromise);\n  // TODO: handle case where exported symbol not found.\n  const Component = exportedSymbol === '*' ? evaluationContext.exports : evaluationContext.exports[exportedSymbol];\n  return (\n    <RenderExportedComponentContext value={{ evaluationContext }}>\n      <Component />\n    </RenderExportedComponentContext>\n  );\n};\n\n/** Render another repo file's exported component inline, resolving + evaluating it\n *  through the module cache (with Suspense + an error boundary). */\nexport const Include = ({\n  filename,\n  exportedSymbol = 'default',\n  LoadingComponent = defaultLoadingComponent,\n  ErrorComponent = defaultErrorComponent,\n  baseModule,\n}: {\n  filename: string;\n  exportedSymbol?: string;\n  LoadingComponent?: typeof defaultLoadingComponent;\n  ErrorComponent?: typeof defaultErrorComponent;\n  baseModule?: EvaluationContext;\n}) => {\n  const moduleCache = use(ModuleCacheContext);\n  // @ts-ignore\n  const evaluationContextPromise = moduleCache!.getEvaluationContext(filename, baseModule ?? module);\n  return (\n    <ErrorBoundary fallbackRender={ErrorComponent}>\n      <Suspense fallback={<LoadingComponent />}>\n        <RenderExportedComponent evaluationContextPromise={evaluationContextPromise} exportedSymbol={exportedSymbol} />\n      </Suspense>\n    </ErrorBoundary>\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8BM;AA9BN,mBAA6C;AAC7C,kCAA8B;AAE9B,yBAAmC;AAEnC,sBAA+D;AASxD,MAAM,qCAAiC,4BAA4C,IAAI;AAIvF,MAAM,0BAA0B,CAAC;AAAA,EACtC;AAAA,EACA,iBAAiB;AACnB,MAGM;AACJ,QAAM,wBAAoB,kBAAI,wBAAwB;AAEtD,QAAM,YAAY,mBAAmB,MAAM,kBAAkB,UAAU,kBAAkB,QAAQ,cAAc;AAC/G,SACE,4CAAC,kCAA+B,OAAO,EAAE,kBAAkB,GACzD,sDAAC,aAAU,GACb;AAEJ;AAIO,MAAM,UAAU,CAAC;AAAA,EACtB;AAAA,EACA,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,iBAAiB;AAAA,EACjB;AACF,MAMM;AACJ,QAAM,kBAAc,kBAAI,qCAAkB;AAE1C,QAAM,2BAA2B,YAAa,qBAAqB,UAAU,cAAc,MAAM;AACjG,SACE,4CAAC,6CAAc,gBAAgB,gBAC7B,sDAAC,yBAAS,UAAU,4CAAC,oBAAiB,GACpC,sDAAC,2BAAwB,0BAAoD,gBAAgC,GAC/G,GACF;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/components/Include.tsx"],"sourcesContent":["import { Suspense, use } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\nimport { ModuleCacheContext } from '../moduleCache';\nimport { EvaluationContext } from '../sandboxTypes';\nimport { defaultErrorComponent, defaultLoadingComponent } from './defaults';\nimport { IncludeModeContext, RenderExportedComponentContext, type IncludeMode } from './includeContexts';\nimport { SafeInclude } from './SafeInclude';\n\n// The contexts live in `./includeContexts` so `Include` and `SafeInclude` do not import each\n// other (`check:circular`); re-exported here because this is the public entry point and the\n// import path must not change.\nexport { IncludeModeContext, RenderExportedComponentContext } from './includeContexts';\nexport type { IncludeMode, RenderFileContextType } from './includeContexts';\n\n/** Low-level: render one export of an already-resolving module evaluation. Most\n *  code should use {@link Include}, which resolves the module and adds Suspense. */\nexport const RenderExportedComponent = ({\n  evaluationContextPromise,\n  exportedSymbol = 'default',\n}: {\n  evaluationContextPromise: Promise<EvaluationContext>;\n  exportedSymbol: string;\n}) => {\n  const evaluationContext = use(evaluationContextPromise);\n  // TODO: handle case where exported symbol not found.\n  const Component = exportedSymbol === '*' ? evaluationContext.exports : evaluationContext.exports[exportedSymbol];\n  return (\n    <RenderExportedComponentContext value={{ evaluationContext }}>\n      <Component />\n    </RenderExportedComponentContext>\n  );\n};\n\n/** Render another repo file's exported component inline, resolving + evaluating it\n *  through the module cache (with Suspense + an error boundary).\n *\n *  Under `mode=\"interpreted\"` (or inside an {@link IncludeModeContext} set to it) the file is\n *  instead rendered **as data** through the safe renderer — no author JavaScript executes,\n *  and the file need not be an evaluable module at all. */\nexport const Include = ({\n  filename,\n  exportedSymbol = 'default',\n  LoadingComponent = defaultLoadingComponent,\n  ErrorComponent = defaultErrorComponent,\n  baseModule,\n  mode,\n  components,\n}: {\n  filename: string;\n  exportedSymbol?: string;\n  LoadingComponent?: typeof defaultLoadingComponent;\n  ErrorComponent?: typeof defaultErrorComponent;\n  baseModule?: EvaluationContext;\n  /** Override {@link IncludeModeContext} for this one include. */\n  mode?: IncludeMode;\n  /** Interpreted mode only: components merged OVER the surrounding MDXProvider map.\n   *\n   *  An app's SAFE component set is not always the same as the one it hands\n   *  `boot({ mdxComponents })`. Grove is the worked example: under the safe renderer it also\n   *  needs sanitizing wrappers for structural tags (`main`, `section`, …), and it must NOT\n   *  register those globally, because MDX consults the provider for intrinsics on the\n   *  COMPILED path too — so a global registration would silently strip `style` and other\n   *  non-allow-listed props from compiled authors who legitimately pass them. Ignored in\n   *  compiled mode, where components come from the provider as they always have. */\n  components?: Record<string, unknown>;\n}) => {\n  // Both contexts are read unconditionally, before the branch, so hook order is stable\n  // whichever renderer this include resolves to.\n  const contextMode = use(IncludeModeContext);\n  const moduleCache = use(ModuleCacheContext);\n  // The prop wins over the context so a single file can opt out either way: an interpreter\n  // app including one trusted, executable component of its own, or a compiled app rendering\n  // one file it does not trust (the shape Grove's non-executable proof page needs).\n  if ((mode ?? contextMode) === 'interpreted') {\n    return (\n      <SafeInclude\n        filename={filename}\n        components={components}\n        LoadingComponent={LoadingComponent}\n        ErrorComponent={ErrorComponent}\n      />\n    );\n  }\n  // @ts-ignore\n  const evaluationContextPromise = moduleCache!.getEvaluationContext(filename, baseModule ?? module);\n  return (\n    <ErrorBoundary fallbackRender={ErrorComponent}>\n      <Suspense fallback={<LoadingComponent />}>\n        <RenderExportedComponent evaluationContextPromise={evaluationContextPromise} exportedSymbol={exportedSymbol} />\n      </Suspense>\n    </ErrorBoundary>\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6BM;AA7BN,mBAA8B;AAC9B,kCAA8B;AAE9B,yBAAmC;AAEnC,sBAA+D;AAC/D,6BAAqF;AACrF,yBAA4B;AAK5B,IAAAA,0BAAmE;AAK5D,MAAM,0BAA0B,CAAC;AAAA,EACtC;AAAA,EACA,iBAAiB;AACnB,MAGM;AACJ,QAAM,wBAAoB,kBAAI,wBAAwB;AAEtD,QAAM,YAAY,mBAAmB,MAAM,kBAAkB,UAAU,kBAAkB,QAAQ,cAAc;AAC/G,SACE,4CAAC,yDAA+B,OAAO,EAAE,kBAAkB,GACzD,sDAAC,aAAU,GACb;AAEJ;AAQO,MAAM,UAAU,CAAC;AAAA,EACtB;AAAA,EACA,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,iBAAiB;AAAA,EACjB;AAAA,EACA;AAAA,EACA;AACF,MAkBM;AAGJ,QAAM,kBAAc,kBAAI,yCAAkB;AAC1C,QAAM,kBAAc,kBAAI,qCAAkB;AAI1C,OAAK,QAAQ,iBAAiB,eAAe;AAC3C,WACE;AAAA,MAAC;AAAA;AAAA,QACC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA;AAAA,IACF;AAAA,EAEJ;AAEA,QAAM,2BAA2B,YAAa,qBAAqB,UAAU,cAAc,MAAM;AACjG,SACE,4CAAC,6CAAc,gBAAgB,gBAC7B,sDAAC,yBAAS,UAAU,4CAAC,oBAAiB,GACpC,sDAAC,2BAAwB,0BAAoD,gBAAgC,GAC/G,GACF;AAEJ;","names":["import_includeContexts"]}

package/dist/components/Include.d.cts

@@ -1,15 +1,10 @@
 import * as react from 'react';
 import { EvaluationContext } from '../sandboxTypes.cjs';
 import { defaultLoadingComponent, defaultErrorComponent } from './defaults.cjs';
+import { IncludeMode } from './includeContexts.cjs';
+export { IncludeModeContext, RenderExportedComponentContext, RenderFileContextType } from './includeContexts.cjs';
 import 'react-error-boundary';
 
-/** The value exposed on {@link RenderExportedComponentContext}: the evaluation
- *  context of the module {@link Include} resolved. */
-type RenderFileContextType = {
-    evaluationContext: EvaluationContext;
-};
-/** Context carrying the included module's {@link EvaluationContext} to its subtree. */
-declare const RenderExportedComponentContext: react.Context<RenderFileContextType | null>;
 /** Low-level: render one export of an already-resolving module evaluation. Most
  *  code should use {@link Include}, which resolves the module and adds Suspense. */
 declare const RenderExportedComponent: ({ evaluationContextPromise, exportedSymbol, }: {
@@ -17,13 +12,29 @@ declare const RenderExportedComponent: ({ evaluationContextPromise, exportedSymb
     exportedSymbol: string;
 }) => react.JSX.Element;
 /** Render another repo file's exported component inline, resolving + evaluating it
- *  through the module cache (with Suspense + an error boundary). */
-declare const Include: ({ filename, exportedSymbol, LoadingComponent, ErrorComponent, baseModule, }: {
+ *  through the module cache (with Suspense + an error boundary).
+ *
+ *  Under `mode="interpreted"` (or inside an {@link IncludeModeContext} set to it) the file is
+ *  instead rendered **as data** through the safe renderer — no author JavaScript executes,
+ *  and the file need not be an evaluable module at all. */
+declare const Include: ({ filename, exportedSymbol, LoadingComponent, ErrorComponent, baseModule, mode, components, }: {
     filename: string;
     exportedSymbol?: string;
     LoadingComponent?: typeof defaultLoadingComponent;
     ErrorComponent?: typeof defaultErrorComponent;
     baseModule?: EvaluationContext;
+    /** Override {@link IncludeModeContext} for this one include. */
+    mode?: IncludeMode;
+    /** Interpreted mode only: components merged OVER the surrounding MDXProvider map.
+     *
+     *  An app's SAFE component set is not always the same as the one it hands
+     *  `boot({ mdxComponents })`. Grove is the worked example: under the safe renderer it also
+     *  needs sanitizing wrappers for structural tags (`main`, `section`, …), and it must NOT
+     *  register those globally, because MDX consults the provider for intrinsics on the
+     *  COMPILED path too — so a global registration would silently strip `style` and other
+     *  non-allow-listed props from compiled authors who legitimately pass them. Ignored in
+     *  compiled mode, where components come from the provider as they always have. */
+    components?: Record<string, unknown>;
 }) => react.JSX.Element;
 
-export { Include, RenderExportedComponent, RenderExportedComponentContext, type RenderFileContextType };
+export { Include, IncludeMode, RenderExportedComponent };

package/dist/components/Include.d.ts

@@ -1,15 +1,10 @@
 import * as react from 'react';
 import { EvaluationContext } from '../sandboxTypes.js';
 import { defaultLoadingComponent, defaultErrorComponent } from './defaults.js';
+import { IncludeMode } from './includeContexts.js';
+export { IncludeModeContext, RenderExportedComponentContext, RenderFileContextType } from './includeContexts.js';
 import 'react-error-boundary';
 
-/** The value exposed on {@link RenderExportedComponentContext}: the evaluation
- *  context of the module {@link Include} resolved. */
-type RenderFileContextType = {
-    evaluationContext: EvaluationContext;
-};
-/** Context carrying the included module's {@link EvaluationContext} to its subtree. */
-declare const RenderExportedComponentContext: react.Context<RenderFileContextType | null>;
 /** Low-level: render one export of an already-resolving module evaluation. Most
  *  code should use {@link Include}, which resolves the module and adds Suspense. */
 declare const RenderExportedComponent: ({ evaluationContextPromise, exportedSymbol, }: {
@@ -17,13 +12,29 @@ declare const RenderExportedComponent: ({ evaluationContextPromise, exportedSymb
     exportedSymbol: string;
 }) => react.JSX.Element;
 /** Render another repo file's exported component inline, resolving + evaluating it
- *  through the module cache (with Suspense + an error boundary). */
-declare const Include: ({ filename, exportedSymbol, LoadingComponent, ErrorComponent, baseModule, }: {
+ *  through the module cache (with Suspense + an error boundary).
+ *
+ *  Under `mode="interpreted"` (or inside an {@link IncludeModeContext} set to it) the file is
+ *  instead rendered **as data** through the safe renderer — no author JavaScript executes,
+ *  and the file need not be an evaluable module at all. */
+declare const Include: ({ filename, exportedSymbol, LoadingComponent, ErrorComponent, baseModule, mode, components, }: {
     filename: string;
     exportedSymbol?: string;
     LoadingComponent?: typeof defaultLoadingComponent;
     ErrorComponent?: typeof defaultErrorComponent;
     baseModule?: EvaluationContext;
+    /** Override {@link IncludeModeContext} for this one include. */
+    mode?: IncludeMode;
+    /** Interpreted mode only: components merged OVER the surrounding MDXProvider map.
+     *
+     *  An app's SAFE component set is not always the same as the one it hands
+     *  `boot({ mdxComponents })`. Grove is the worked example: under the safe renderer it also
+     *  needs sanitizing wrappers for structural tags (`main`, `section`, …), and it must NOT
+     *  register those globally, because MDX consults the provider for intrinsics on the
+     *  COMPILED path too — so a global registration would silently strip `style` and other
+     *  non-allow-listed props from compiled authors who legitimately pass them. Ignored in
+     *  compiled mode, where components come from the provider as they always have. */
+    components?: Record<string, unknown>;
 }) => react.JSX.Element;
 
-export { Include, RenderExportedComponent, RenderExportedComponentContext, type RenderFileContextType };
+export { Include, IncludeMode, RenderExportedComponent };

package/dist/components/Include.js

@@ -1,10 +1,12 @@
 import "../chunk-VHAA22YE.js";
 import { jsx } from "react/jsx-runtime";
-import { Suspense, createContext, use } from "react";
+import { Suspense, use } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { ModuleCacheContext } from "../moduleCache";
 import { defaultErrorComponent, defaultLoadingComponent } from "./defaults";
-const RenderExportedComponentContext = createContext(null);
+import { IncludeModeContext, RenderExportedComponentContext } from "./includeContexts";
+import { SafeInclude } from "./SafeInclude";
+import { IncludeModeContext as IncludeModeContext2, RenderExportedComponentContext as RenderExportedComponentContext2 } from "./includeContexts";
 const RenderExportedComponent = ({
   evaluationContextPromise,
   exportedSymbol = "default"
@@ -18,15 +20,30 @@ const Include = ({
   exportedSymbol = "default",
   LoadingComponent = defaultLoadingComponent,
   ErrorComponent = defaultErrorComponent,
-  baseModule
+  baseModule,
+  mode,
+  components
 }) => {
+  const contextMode = use(IncludeModeContext);
   const moduleCache = use(ModuleCacheContext);
+  if ((mode ?? contextMode) === "interpreted") {
+    return /* @__PURE__ */ jsx(
+      SafeInclude,
+      {
+        filename,
+        components,
+        LoadingComponent,
+        ErrorComponent
+      }
+    );
+  }
   const evaluationContextPromise = moduleCache.getEvaluationContext(filename, baseModule ?? module);
   return /* @__PURE__ */ jsx(ErrorBoundary, { fallbackRender: ErrorComponent, children: /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx(LoadingComponent, {}), children: /* @__PURE__ */ jsx(RenderExportedComponent, { evaluationContextPromise, exportedSymbol }) }) });
 };
 export {
   Include,
+  IncludeModeContext2 as IncludeModeContext,
   RenderExportedComponent,
-  RenderExportedComponentContext
+  RenderExportedComponentContext2 as RenderExportedComponentContext
 };
 //# sourceMappingURL=Include.js.map

package/dist/components/Include.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/Include.tsx"],"sourcesContent":["import { Suspense, createContext, use } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\nimport { ModuleCacheContext } from '../moduleCache';\nimport { EvaluationContext } from '../sandboxTypes';\nimport { defaultErrorComponent, defaultLoadingComponent } from './defaults';\n\n/** The value exposed on {@link RenderExportedComponentContext}: the evaluation\n *  context of the module {@link Include} resolved. */\nexport type RenderFileContextType = {\n  evaluationContext: EvaluationContext;\n};\n\n/** Context carrying the included module's {@link EvaluationContext} to its subtree. */\nexport const RenderExportedComponentContext = createContext<RenderFileContextType | null>(null);\n\n/** Low-level: render one export of an already-resolving module evaluation. Most\n *  code should use {@link Include}, which resolves the module and adds Suspense. */\nexport const RenderExportedComponent = ({\n  evaluationContextPromise,\n  exportedSymbol = 'default',\n}: {\n  evaluationContextPromise: Promise<EvaluationContext>;\n  exportedSymbol: string;\n}) => {\n  const evaluationContext = use(evaluationContextPromise);\n  // TODO: handle case where exported symbol not found.\n  const Component = exportedSymbol === '*' ? evaluationContext.exports : evaluationContext.exports[exportedSymbol];\n  return (\n    <RenderExportedComponentContext value={{ evaluationContext }}>\n      <Component />\n    </RenderExportedComponentContext>\n  );\n};\n\n/** Render another repo file's exported component inline, resolving + evaluating it\n *  through the module cache (with Suspense + an error boundary). */\nexport const Include = ({\n  filename,\n  exportedSymbol = 'default',\n  LoadingComponent = defaultLoadingComponent,\n  ErrorComponent = defaultErrorComponent,\n  baseModule,\n}: {\n  filename: string;\n  exportedSymbol?: string;\n  LoadingComponent?: typeof defaultLoadingComponent;\n  ErrorComponent?: typeof defaultErrorComponent;\n  baseModule?: EvaluationContext;\n}) => {\n  const moduleCache = use(ModuleCacheContext);\n  // @ts-ignore\n  const evaluationContextPromise = moduleCache!.getEvaluationContext(filename, baseModule ?? module);\n  return (\n    <ErrorBoundary fallbackRender={ErrorComponent}>\n      <Suspense fallback={<LoadingComponent />}>\n        <RenderExportedComponent evaluationContextPromise={evaluationContextPromise} exportedSymbol={exportedSymbol} />\n      </Suspense>\n    </ErrorBoundary>\n  );\n};\n"],"mappings":";AA8BM;AA9BN,SAAS,UAAU,eAAe,WAAW;AAC7C,SAAS,qBAAqB;AAE9B,SAAS,0BAA0B;AAEnC,SAAS,uBAAuB,+BAA+B;AASxD,MAAM,iCAAiC,cAA4C,IAAI;AAIvF,MAAM,0BAA0B,CAAC;AAAA,EACtC;AAAA,EACA,iBAAiB;AACnB,MAGM;AACJ,QAAM,oBAAoB,IAAI,wBAAwB;AAEtD,QAAM,YAAY,mBAAmB,MAAM,kBAAkB,UAAU,kBAAkB,QAAQ,cAAc;AAC/G,SACE,oBAAC,kCAA+B,OAAO,EAAE,kBAAkB,GACzD,8BAAC,aAAU,GACb;AAEJ;AAIO,MAAM,UAAU,CAAC;AAAA,EACtB;AAAA,EACA,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,iBAAiB;AAAA,EACjB;AACF,MAMM;AACJ,QAAM,cAAc,IAAI,kBAAkB;AAE1C,QAAM,2BAA2B,YAAa,qBAAqB,UAAU,cAAc,MAAM;AACjG,SACE,oBAAC,iBAAc,gBAAgB,gBAC7B,8BAAC,YAAS,UAAU,oBAAC,oBAAiB,GACpC,8BAAC,2BAAwB,0BAAoD,gBAAgC,GAC/G,GACF;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/components/Include.tsx"],"sourcesContent":["import { Suspense, use } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\nimport { ModuleCacheContext } from '../moduleCache';\nimport { EvaluationContext } from '../sandboxTypes';\nimport { defaultErrorComponent, defaultLoadingComponent } from './defaults';\nimport { IncludeModeContext, RenderExportedComponentContext, type IncludeMode } from './includeContexts';\nimport { SafeInclude } from './SafeInclude';\n\n// The contexts live in `./includeContexts` so `Include` and `SafeInclude` do not import each\n// other (`check:circular`); re-exported here because this is the public entry point and the\n// import path must not change.\nexport { IncludeModeContext, RenderExportedComponentContext } from './includeContexts';\nexport type { IncludeMode, RenderFileContextType } from './includeContexts';\n\n/** Low-level: render one export of an already-resolving module evaluation. Most\n *  code should use {@link Include}, which resolves the module and adds Suspense. */\nexport const RenderExportedComponent = ({\n  evaluationContextPromise,\n  exportedSymbol = 'default',\n}: {\n  evaluationContextPromise: Promise<EvaluationContext>;\n  exportedSymbol: string;\n}) => {\n  const evaluationContext = use(evaluationContextPromise);\n  // TODO: handle case where exported symbol not found.\n  const Component = exportedSymbol === '*' ? evaluationContext.exports : evaluationContext.exports[exportedSymbol];\n  return (\n    <RenderExportedComponentContext value={{ evaluationContext }}>\n      <Component />\n    </RenderExportedComponentContext>\n  );\n};\n\n/** Render another repo file's exported component inline, resolving + evaluating it\n *  through the module cache (with Suspense + an error boundary).\n *\n *  Under `mode=\"interpreted\"` (or inside an {@link IncludeModeContext} set to it) the file is\n *  instead rendered **as data** through the safe renderer — no author JavaScript executes,\n *  and the file need not be an evaluable module at all. */\nexport const Include = ({\n  filename,\n  exportedSymbol = 'default',\n  LoadingComponent = defaultLoadingComponent,\n  ErrorComponent = defaultErrorComponent,\n  baseModule,\n  mode,\n  components,\n}: {\n  filename: string;\n  exportedSymbol?: string;\n  LoadingComponent?: typeof defaultLoadingComponent;\n  ErrorComponent?: typeof defaultErrorComponent;\n  baseModule?: EvaluationContext;\n  /** Override {@link IncludeModeContext} for this one include. */\n  mode?: IncludeMode;\n  /** Interpreted mode only: components merged OVER the surrounding MDXProvider map.\n   *\n   *  An app's SAFE component set is not always the same as the one it hands\n   *  `boot({ mdxComponents })`. Grove is the worked example: under the safe renderer it also\n   *  needs sanitizing wrappers for structural tags (`main`, `section`, …), and it must NOT\n   *  register those globally, because MDX consults the provider for intrinsics on the\n   *  COMPILED path too — so a global registration would silently strip `style` and other\n   *  non-allow-listed props from compiled authors who legitimately pass them. Ignored in\n   *  compiled mode, where components come from the provider as they always have. */\n  components?: Record<string, unknown>;\n}) => {\n  // Both contexts are read unconditionally, before the branch, so hook order is stable\n  // whichever renderer this include resolves to.\n  const contextMode = use(IncludeModeContext);\n  const moduleCache = use(ModuleCacheContext);\n  // The prop wins over the context so a single file can opt out either way: an interpreter\n  // app including one trusted, executable component of its own, or a compiled app rendering\n  // one file it does not trust (the shape Grove's non-executable proof page needs).\n  if ((mode ?? contextMode) === 'interpreted') {\n    return (\n      <SafeInclude\n        filename={filename}\n        components={components}\n        LoadingComponent={LoadingComponent}\n        ErrorComponent={ErrorComponent}\n      />\n    );\n  }\n  // @ts-ignore\n  const evaluationContextPromise = moduleCache!.getEvaluationContext(filename, baseModule ?? module);\n  return (\n    <ErrorBoundary fallbackRender={ErrorComponent}>\n      <Suspense fallback={<LoadingComponent />}>\n        <RenderExportedComponent evaluationContextPromise={evaluationContextPromise} exportedSymbol={exportedSymbol} />\n      </Suspense>\n    </ErrorBoundary>\n  );\n};\n"],"mappings":";AA6BM;AA7BN,SAAS,UAAU,WAAW;AAC9B,SAAS,qBAAqB;AAE9B,SAAS,0BAA0B;AAEnC,SAAS,uBAAuB,+BAA+B;AAC/D,SAAS,oBAAoB,sCAAwD;AACrF,SAAS,mBAAmB;AAK5B,SAAS,sBAAAA,qBAAoB,kCAAAC,uCAAsC;AAK5D,MAAM,0BAA0B,CAAC;AAAA,EACtC;AAAA,EACA,iBAAiB;AACnB,MAGM;AACJ,QAAM,oBAAoB,IAAI,wBAAwB;AAEtD,QAAM,YAAY,mBAAmB,MAAM,kBAAkB,UAAU,kBAAkB,QAAQ,cAAc;AAC/G,SACE,oBAAC,kCAA+B,OAAO,EAAE,kBAAkB,GACzD,8BAAC,aAAU,GACb;AAEJ;AAQO,MAAM,UAAU,CAAC;AAAA,EACtB;AAAA,EACA,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,iBAAiB;AAAA,EACjB;AAAA,EACA;AAAA,EACA;AACF,MAkBM;AAGJ,QAAM,cAAc,IAAI,kBAAkB;AAC1C,QAAM,cAAc,IAAI,kBAAkB;AAI1C,OAAK,QAAQ,iBAAiB,eAAe;AAC3C,WACE;AAAA,MAAC;AAAA;AAAA,QACC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA;AAAA,IACF;AAAA,EAEJ;AAEA,QAAM,2BAA2B,YAAa,qBAAqB,UAAU,cAAc,MAAM;AACjG,SACE,oBAAC,iBAAc,gBAAgB,gBAC7B,8BAAC,YAAS,UAAU,oBAAC,oBAAiB,GACpC,8BAAC,2BAAwB,0BAAoD,gBAAgC,GAC/G,GACF;AAEJ;","names":["IncludeModeContext","RenderExportedComponentContext"]}

package/dist/components/MountImage.d.cts

@@ -1,6 +1,7 @@
 import * as react from 'react';
 import { ImgHTMLAttributes, ReactNode } from 'react';
 import { SandboxMount } from '../mounts.cjs';
+import '../generated/spaces.cjs';
 import '../tasks.cjs';
 
 /** Props for {@link MountImage}. Extends the native `<img>` attributes (minus `src`,

package/dist/components/MountImage.d.ts

@@ -1,6 +1,7 @@
 import * as react from 'react';
 import { ImgHTMLAttributes, ReactNode } from 'react';
 import { SandboxMount } from '../mounts.js';
+import '../generated/spaces.js';
 import '../tasks.js';
 
 /** Props for {@link MountImage}. Extends the native `<img>` attributes (minus `src`,

package/dist/components/SafeInclude.cjs

@@ -0,0 +1,89 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var SafeInclude_exports = {};
+__export(SafeInclude_exports, {
+  SafeInclude: () => SafeInclude,
+  appMountRelative: () => appMountRelative,
+  stripFrontmatter: () => stripFrontmatter
+});
+module.exports = __toCommonJS(SafeInclude_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_react = require("react");
+var import_react_error_boundary = require("react-error-boundary");
+var import_fs = require("../fs");
+var import_mounts = require("../mounts");
+var import_MDXProvider = require("../MDXProvider");
+var import_SafeContent = require("../safeContent/SafeContent");
+var import_sourceCache = require("../sourceCache");
+var import_includeContexts = require("./includeContexts");
+var import_defaults = require("./defaults");
+function stripFrontmatter(source) {
+  return source.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
+}
+function appMountRelative(filename) {
+  const root = (0, import_mounts.getAppMountPath)().replace(/\/+$/, "");
+  const abs = filename.startsWith(root + "/") ? filename.slice(root.length) : filename;
+  return abs.replace(/^\/+/, "");
+}
+const defaultSources = (0, import_sourceCache.createSourceCache)(
+  (path) => (0, import_fs.openAppFs)().readFile(path, "utf8")
+);
+function InterpretedBody({
+  filename,
+  components,
+  readSource
+}) {
+  const sources = (0, import_react.useMemo)(
+    () => readSource ? (0, import_sourceCache.createSourceCache)(readSource) : defaultSources,
+    [readSource]
+  );
+  const raw = (0, import_react.use)(sources.read(appMountRelative(filename)));
+  const provided = (0, import_MDXProvider.useMDXComponents)(components);
+  const body = stripFrontmatter(raw);
+  return (
+    // Publishing the included file's path is what lets the WikiLink resolver know which file
+    // a relative `[[target]]` (and its `#sec-…` fragment) is relative TO — the same context
+    // the compiled path publishes from the module's evaluation.
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_includeContexts.RenderExportedComponentContext,
+      {
+        value: { evaluationContext: { evaluation: { module: { filepath: filename } } } },
+        children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_SafeContent.SafeContent, { source: body, components: provided })
+      }
+    )
+  );
+}
+const SafeInclude = ({
+  filename,
+  components,
+  readSource,
+  LoadingComponent = import_defaults.defaultLoadingComponent,
+  ErrorComponent = import_defaults.defaultErrorComponent
+}) => (
+  // Same boundary shape as the compiled path: a file that fails to read renders the error
+  // component rather than taking down the tree that included it.
+  /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_error_boundary.ErrorBoundary, { fallbackRender: ErrorComponent, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react.Suspense, { fallback: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LoadingComponent, {}), children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(InterpretedBody, { filename, components, readSource }) }) })
+);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SafeInclude,
+  appMountRelative,
+  stripFrontmatter
+});
+//# sourceMappingURL=SafeInclude.cjs.map

package/dist/components/SafeInclude.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/SafeInclude.tsx"],"sourcesContent":["import { Suspense, use, useMemo } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\nimport { openAppFs } from '../fs';\nimport { getAppMountPath } from '../mounts';\nimport { useMDXComponents } from '../MDXProvider';\nimport { SafeContent } from '../safeContent/SafeContent';\nimport { createSourceCache, type SourceReader } from '../sourceCache';\nimport { RenderExportedComponentContext } from './includeContexts';\nimport { defaultErrorComponent, defaultLoadingComponent } from './defaults';\n\n// `<Include mode=\"interpreted\">` — the same tag, the NON-EXECUTABLE renderer. (R3-263)\n//\n// WHY THIS EXISTS. `<Include>` resolves a file through the module cache and *evaluates* it,\n// which is right for an app's own source and wrong for content. An interpreter app\n// (TRUST_MODES_SPEC §5) had no way to say \"include this file, but as data\": it could render\n// its own bodies through `<SafeContent>` while any file it pulled in with `<Include>` still\n// executed. Grove hit exactly that — a wiki declaring `render: safe` still ran author\n// JavaScript out of its `_layout.mdx`, because the layout chain went through `<Include>`.\n//\n// It is also what makes such a file renderable AT ALL when it does not live in the app: the\n// compiled path evaluates an app-source module, which a file resident in a content mount is\n// not. That is the `AGENT_AUTHORING §10` MDX-from-mount gate, which `TRUST_MODES §5.1` says\n// MUST terminate in the safe renderer and never in compiled MDX.\n//\n// The component map comes from `useMDXComponents` — the SAME provider map `boot({\n// mdxComponents })` establishes for the compiled path — so a document resolves the identical\n// vocabulary under either renderer and an app wires nothing extra to get it.\n\n/** Strip a leading YAML frontmatter block (and an optional BOM). The compiled path never\n *  renders frontmatter — the MDX loader consumes it — so the safe path must not either, or\n *  the same file gains a wall of raw YAML when the renderer changes. */\nexport function stripFrontmatter(source: string): string {\n  return source.replace(/^\\uFEFF?---\\r?\\n[\\s\\S]*?\\r?\\n---[ \\t]*\\r?\\n?/, '');\n}\n\n/** `/app/content/x.mdx` → `content/x.mdx`. {@link openAppFs} is anchored at the app mount,\n *  so an absolute module path has to be made mount-relative before it is read. A path that\n *  is already relative is passed through untouched. */\nexport function appMountRelative(filename: string): string {\n  const root = getAppMountPath().replace(/\\/+$/, '');\n  const abs = filename.startsWith(root + '/') ? filename.slice(root.length) : filename;\n  return abs.replace(/^\\/+/, '');\n}\n\n// One cache for every interpreted include in the app: a layout file is included on every\n// page, so a per-component cache would re-read it per navigation. See `../sourceCache` for\n// why a REJECTED read must not be memoised.\nconst defaultSources = createSourceCache(\n  (path) => openAppFs().readFile(path, 'utf8') as Promise<string>,\n);\n\nfunction InterpretedBody({\n  filename,\n  components,\n  readSource,\n}: {\n  filename: string;\n  components?: Record<string, unknown>;\n  readSource?: SourceReader;\n}) {\n  // A caller-supplied reader gets its own cache; the shared one is used otherwise. Memoised\n  // on the reader identity so `use()` still sees a stable promise across renders.\n  const sources = useMemo(\n    () => (readSource ? createSourceCache(readSource) : defaultSources),\n    [readSource],\n  );\n  const raw = use(sources.read(appMountRelative(filename)));\n  const provided = useMDXComponents(components) as Record<string, unknown>;\n  const body = stripFrontmatter(raw);\n  return (\n    // Publishing the included file's path is what lets the WikiLink resolver know which file\n    // a relative `[[target]]` (and its `#sec-…` fragment) is relative TO — the same context\n    // the compiled path publishes from the module's evaluation.\n    <RenderExportedComponentContext\n      value={{ evaluationContext: { evaluation: { module: { filepath: filename } } } } as never}\n    >\n      <SafeContent source={body} components={provided as never} />\n    </RenderExportedComponentContext>\n  );\n}\n\n/** Render another file's Markdown/MDX **as data** — no author JavaScript executes. Reached\n *  via `<Include mode=\"interpreted\">` or `<IncludeModeContext value=\"interpreted\">`. */\nexport const SafeInclude = ({\n  filename,\n  components,\n  readSource,\n  LoadingComponent = defaultLoadingComponent,\n  ErrorComponent = defaultErrorComponent,\n}: {\n  filename: string;\n  /** Extra/override components, merged OVER the surrounding MDXProvider map. */\n  components?: Record<string, unknown>;\n  /** Read the raw bytes yourself — e.g. from a content mount rather than the app repo. */\n  readSource?: SourceReader;\n  LoadingComponent?: typeof defaultLoadingComponent;\n  ErrorComponent?: typeof defaultErrorComponent;\n}) => (\n  // Same boundary shape as the compiled path: a file that fails to read renders the error\n  // component rather than taking down the tree that included it.\n  <ErrorBoundary fallbackRender={ErrorComponent}>\n    <Suspense fallback={<LoadingComponent />}>\n      <InterpretedBody filename={filename} components={components} readSource={readSource} />\n    </Suspense>\n  </ErrorBoundary>\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6EM;AA7EN,mBAAuC;AACvC,kCAA8B;AAE9B,gBAA0B;AAC1B,oBAAgC;AAChC,yBAAiC;AACjC,yBAA4B;AAC5B,yBAAqD;AACrD,6BAA+C;AAC/C,sBAA+D;AAuBxD,SAAS,iBAAiB,QAAwB;AACvD,SAAO,OAAO,QAAQ,gDAAgD,EAAE;AAC1E;AAKO,SAAS,iBAAiB,UAA0B;AACzD,QAAM,WAAO,+BAAgB,EAAE,QAAQ,QAAQ,EAAE;AACjD,QAAM,MAAM,SAAS,WAAW,OAAO,GAAG,IAAI,SAAS,MAAM,KAAK,MAAM,IAAI;AAC5E,SAAO,IAAI,QAAQ,QAAQ,EAAE;AAC/B;AAKA,MAAM,qBAAiB;AAAA,EACrB,CAAC,aAAS,qBAAU,EAAE,SAAS,MAAM,MAAM;AAC7C;AAEA,SAAS,gBAAgB;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AACF,GAIG;AAGD,QAAM,cAAU;AAAA,IACd,MAAO,iBAAa,sCAAkB,UAAU,IAAI;AAAA,IACpD,CAAC,UAAU;AAAA,EACb;AACA,QAAM,UAAM,kBAAI,QAAQ,KAAK,iBAAiB,QAAQ,CAAC,CAAC;AACxD,QAAM,eAAW,qCAAiB,UAAU;AAC5C,QAAM,OAAO,iBAAiB,GAAG;AACjC;AAAA;AAAA;AAAA;AAAA,IAIE;AAAA,MAAC;AAAA;AAAA,QACC,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,SAAS,EAAE,EAAE,EAAE;AAAA,QAE/E,sDAAC,kCAAY,QAAQ,MAAM,YAAY,UAAmB;AAAA;AAAA,IAC5D;AAAA;AAEJ;AAIO,MAAM,cAAc,CAAC;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA,mBAAmB;AAAA,EACnB,iBAAiB;AACnB;AAAA;AAAA;AAAA,EAWE,4CAAC,6CAAc,gBAAgB,gBAC7B,sDAAC,yBAAS,UAAU,4CAAC,oBAAiB,GACpC,sDAAC,mBAAgB,UAAoB,YAAwB,YAAwB,GACvF,GACF;AAAA;","names":[]}

package/dist/components/SafeInclude.d.cts

@@ -0,0 +1,26 @@
+import * as react from 'react';
+import { SourceReader } from '../sourceCache.cjs';
+import { defaultLoadingComponent, defaultErrorComponent } from './defaults.cjs';
+import 'react-error-boundary';
+
+/** Strip a leading YAML frontmatter block (and an optional BOM). The compiled path never
+ *  renders frontmatter — the MDX loader consumes it — so the safe path must not either, or
+ *  the same file gains a wall of raw YAML when the renderer changes. */
+declare function stripFrontmatter(source: string): string;
+/** `/app/content/x.mdx` → `content/x.mdx`. {@link openAppFs} is anchored at the app mount,
+ *  so an absolute module path has to be made mount-relative before it is read. A path that
+ *  is already relative is passed through untouched. */
+declare function appMountRelative(filename: string): string;
+/** Render another file's Markdown/MDX **as data** — no author JavaScript executes. Reached
+ *  via `<Include mode="interpreted">` or `<IncludeModeContext value="interpreted">`. */
+declare const SafeInclude: ({ filename, components, readSource, LoadingComponent, ErrorComponent, }: {
+    filename: string;
+    /** Extra/override components, merged OVER the surrounding MDXProvider map. */
+    components?: Record<string, unknown>;
+    /** Read the raw bytes yourself — e.g. from a content mount rather than the app repo. */
+    readSource?: SourceReader;
+    LoadingComponent?: typeof defaultLoadingComponent;
+    ErrorComponent?: typeof defaultErrorComponent;
+}) => react.JSX.Element;
+
+export { SafeInclude, appMountRelative, stripFrontmatter };

package/dist/components/SafeInclude.d.ts

@@ -0,0 +1,26 @@
+import * as react from 'react';
+import { SourceReader } from '../sourceCache.js';
+import { defaultLoadingComponent, defaultErrorComponent } from './defaults.js';
+import 'react-error-boundary';
+
+/** Strip a leading YAML frontmatter block (and an optional BOM). The compiled path never
+ *  renders frontmatter — the MDX loader consumes it — so the safe path must not either, or
+ *  the same file gains a wall of raw YAML when the renderer changes. */
+declare function stripFrontmatter(source: string): string;
+/** `/app/content/x.mdx` → `content/x.mdx`. {@link openAppFs} is anchored at the app mount,
+ *  so an absolute module path has to be made mount-relative before it is read. A path that
+ *  is already relative is passed through untouched. */
+declare function appMountRelative(filename: string): string;
+/** Render another file's Markdown/MDX **as data** — no author JavaScript executes. Reached
+ *  via `<Include mode="interpreted">` or `<IncludeModeContext value="interpreted">`. */
+declare const SafeInclude: ({ filename, components, readSource, LoadingComponent, ErrorComponent, }: {
+    filename: string;
+    /** Extra/override components, merged OVER the surrounding MDXProvider map. */
+    components?: Record<string, unknown>;
+    /** Read the raw bytes yourself — e.g. from a content mount rather than the app repo. */
+    readSource?: SourceReader;
+    LoadingComponent?: typeof defaultLoadingComponent;
+    ErrorComponent?: typeof defaultErrorComponent;
+}) => react.JSX.Element;
+
+export { SafeInclude, appMountRelative, stripFrontmatter };

package/dist/components/SafeInclude.js

@@ -0,0 +1,64 @@
+import "../chunk-VHAA22YE.js";
+import { jsx } from "react/jsx-runtime";
+import { Suspense, use, useMemo } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { openAppFs } from "../fs";
+import { getAppMountPath } from "../mounts";
+import { useMDXComponents } from "../MDXProvider";
+import { SafeContent } from "../safeContent/SafeContent";
+import { createSourceCache } from "../sourceCache";
+import { RenderExportedComponentContext } from "./includeContexts";
+import { defaultErrorComponent, defaultLoadingComponent } from "./defaults";
+function stripFrontmatter(source) {
+  return source.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
+}
+function appMountRelative(filename) {
+  const root = getAppMountPath().replace(/\/+$/, "");
+  const abs = filename.startsWith(root + "/") ? filename.slice(root.length) : filename;
+  return abs.replace(/^\/+/, "");
+}
+const defaultSources = createSourceCache(
+  (path) => openAppFs().readFile(path, "utf8")
+);
+function InterpretedBody({
+  filename,
+  components,
+  readSource
+}) {
+  const sources = useMemo(
+    () => readSource ? createSourceCache(readSource) : defaultSources,
+    [readSource]
+  );
+  const raw = use(sources.read(appMountRelative(filename)));
+  const provided = useMDXComponents(components);
+  const body = stripFrontmatter(raw);
+  return (
+    // Publishing the included file's path is what lets the WikiLink resolver know which file
+    // a relative `[[target]]` (and its `#sec-…` fragment) is relative TO — the same context
+    // the compiled path publishes from the module's evaluation.
+    /* @__PURE__ */ jsx(
+      RenderExportedComponentContext,
+      {
+        value: { evaluationContext: { evaluation: { module: { filepath: filename } } } },
+        children: /* @__PURE__ */ jsx(SafeContent, { source: body, components: provided })
+      }
+    )
+  );
+}
+const SafeInclude = ({
+  filename,
+  components,
+  readSource,
+  LoadingComponent = defaultLoadingComponent,
+  ErrorComponent = defaultErrorComponent
+}) => (
+  // Same boundary shape as the compiled path: a file that fails to read renders the error
+  // component rather than taking down the tree that included it.
+  /* @__PURE__ */ jsx(ErrorBoundary, { fallbackRender: ErrorComponent, children: /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx(LoadingComponent, {}), children: /* @__PURE__ */ jsx(InterpretedBody, { filename, components, readSource }) }) })
+);
+export {
+  SafeInclude,
+  appMountRelative,
+  stripFrontmatter
+};
+//# sourceMappingURL=SafeInclude.js.map