@immediately-run/sdk 0.2.8 → 0.4.0

package/dist/auth.cjs

@@ -23,20 +23,20 @@ __export(auth_exports, {
   useAuth: () => useAuth
 });
 module.exports = __toCommonJS(auth_exports);
-var import_react = require("react");
-const authService = () => {
-  return module.evaluation.module.bundler.auth;
-};
-const getAuthState = () => authService().getState();
-const onAuthChange = (listener) => {
-  const disposable = authService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useAuth = () => {
-  const [state, setState] = (0, import_react.useState)(getAuthState);
-  (0, import_react.useEffect)(() => onAuthChange(setState), []);
-  return state;
+var import_pushChannel = require("./pushChannel");
+const isAuthState = (v) => {
+  const s = v;
+  return !!s && (s.status === "unknown" || s.status === "signed-in" || s.status === "signed-out") && (s.user === null || typeof s.user === "object" && typeof s.user.login === "string");
 };
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "auth-state",
+  requestType: "request-auth-state",
+  initial: { status: "unknown", user: null },
+  parse: (msg) => isAuthState(msg.state) ? msg.state : void 0
+});
+const getAuthState = () => channel.get();
+const onAuthChange = (listener) => channel.onChange(listener);
+const useAuth = () => channel.use();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getAuthState,

package/dist/auth.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\ninterface AuthService {\n  getState(): AuthState;\n  onChange(listener: (state: AuthState) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler` is the sandbox bundler injected into the\n// evaluation context (same path the other SDK helpers reach for `messageBus`).\nconst authService = (): AuthService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.auth;\n};\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n */\nexport const getAuthState = (): AuthState => authService().getState();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) => {\n  const disposable = authService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n */\nexport const useAuth = (): AuthState => {\n  const [state, setState] = useState<AuthState>(getAuthState);\n  useEffect(() => onAuthChange(setState), []);\n  return state;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AA4BpC,MAAM,cAAc,MAAmB;AAErC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,eAAe,MAAiB,YAAY,EAAE,SAAS;AAM7D,MAAM,eAAe,CAAC,aAAuD;AAClF,QAAM,aAAa,YAAY,EAAE,SAAS,QAAQ;AAClD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAMO,MAAM,UAAU,MAAiB;AACtC,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAAoB,YAAY;AAC1D,8BAAU,MAAM,aAAa,QAAQ,GAAG,CAAC,CAAC;AAC1C,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\nconst isAuthState = (v: unknown): v is AuthState => {\n  const s = v as Partial<AuthState> | null;\n  return (\n    !!s &&\n    (s.status === 'unknown' || s.status === 'signed-in' || s.status === 'signed-out') &&\n    (s.user === null || (typeof s.user === 'object' && typeof (s.user as SandboxUser).login === 'string'))\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `auth-state`\n// and answers `request-auth-state` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<AuthState>({\n  pushType: 'auth-state',\n  requestType: 'request-auth-state',\n  initial: { status: 'unknown', user: null },\n  parse: (msg) => (isAuthState(msg.state) ? (msg.state as AuthState) : undefined),\n});\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n */\nexport const getAuthState = (): AuthState => channel.get();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n */\nexport const useAuth = (): AuthState => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAqBlC,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,WAAW,aAAa,EAAE,WAAW,eAAe,EAAE,WAAW,kBACnE,EAAE,SAAS,QAAS,OAAO,EAAE,SAAS,YAAY,OAAQ,EAAE,KAAqB,UAAU;AAEhG;AAIA,MAAM,cAAU,sCAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,QAAQ,WAAW,MAAM,KAAK;AAAA,EACzC,OAAO,CAAC,QAAS,YAAY,IAAI,KAAK,IAAK,IAAI,QAAsB;AACvE,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,eAAe,CAAC,aAC3B,QAAQ,SAAS,QAAQ;AAMpB,MAAM,UAAU,MAAiB,QAAQ,IAAI;","names":[]}

package/dist/auth.js

@@ -1,17 +1,17 @@
-import { useEffect, useState } from "react";
-const authService = () => {
-  return module.evaluation.module.bundler.auth;
-};
-const getAuthState = () => authService().getState();
-const onAuthChange = (listener) => {
-  const disposable = authService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useAuth = () => {
-  const [state, setState] = useState(getAuthState);
-  useEffect(() => onAuthChange(setState), []);
-  return state;
+import { createPushChannel } from "./pushChannel";
+const isAuthState = (v) => {
+  const s = v;
+  return !!s && (s.status === "unknown" || s.status === "signed-in" || s.status === "signed-out") && (s.user === null || typeof s.user === "object" && typeof s.user.login === "string");
 };
+const channel = createPushChannel({
+  pushType: "auth-state",
+  requestType: "request-auth-state",
+  initial: { status: "unknown", user: null },
+  parse: (msg) => isAuthState(msg.state) ? msg.state : void 0
+});
+const getAuthState = () => channel.get();
+const onAuthChange = (listener) => channel.onChange(listener);
+const useAuth = () => channel.use();
 export {
   getAuthState,
   onAuthChange,

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\ninterface AuthService {\n  getState(): AuthState;\n  onChange(listener: (state: AuthState) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler` is the sandbox bundler injected into the\n// evaluation context (same path the other SDK helpers reach for `messageBus`).\nconst authService = (): AuthService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.auth;\n};\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n */\nexport const getAuthState = (): AuthState => authService().getState();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) => {\n  const disposable = authService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n */\nexport const useAuth = (): AuthState => {\n  const [state, setState] = useState<AuthState>(getAuthState);\n  useEffect(() => onAuthChange(setState), []);\n  return state;\n};\n"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AA4BpC,MAAM,cAAc,MAAmB;AAErC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,eAAe,MAAiB,YAAY,EAAE,SAAS;AAM7D,MAAM,eAAe,CAAC,aAAuD;AAClF,QAAM,aAAa,YAAY,EAAE,SAAS,QAAQ;AAClD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAMO,MAAM,UAAU,MAAiB;AACtC,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAoB,YAAY;AAC1D,YAAU,MAAM,aAAa,QAAQ,GAAG,CAAC,CAAC;AAC1C,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/auth.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * Login / account state of the immediately.run user, mirrored from the host\n * window into the sandbox.\n *\n * `status` is `'unknown'` until the host has reported a value (use it to\n * distinguish \"still loading\" from a confirmed signed-out session).\n */\nexport type AuthStatus = 'unknown' | 'signed-in' | 'signed-out';\n\nexport interface SandboxUser {\n  /** GitHub login (handle) of the signed-in user. */\n  login: string;\n}\n\nexport interface AuthState {\n  status: AuthStatus;\n  user: SandboxUser | null;\n}\n\nconst isAuthState = (v: unknown): v is AuthState => {\n  const s = v as Partial<AuthState> | null;\n  return (\n    !!s &&\n    (s.status === 'unknown' || s.status === 'signed-in' || s.status === 'signed-out') &&\n    (s.user === null || (typeof s.user === 'object' && typeof (s.user as SandboxUser).login === 'string'))\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `auth-state`\n// and answers `request-auth-state` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<AuthState>({\n  pushType: 'auth-state',\n  requestType: 'request-auth-state',\n  initial: { status: 'unknown', user: null },\n  parse: (msg) => (isAuthState(msg.state) ? (msg.state as AuthState) : undefined),\n});\n\n/**\n * Returns the current login / account state. Poll this whenever you need a\n * one-off read; use {@link onAuthChange} or {@link useAuth} to react to changes.\n */\nexport const getAuthState = (): AuthState => channel.get();\n\n/**\n * Subscribe to login / logout changes. The listener is invoked immediately with\n * the current state, then again on every change. Returns an unsubscribe fn.\n */\nexport const onAuthChange = (listener: (state: AuthState) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current login / account state, re-rendering on\n * login / logout.\n */\nexport const useAuth = (): AuthState => channel.use();\n"],"mappings":"AAAA,SAAS,yBAAyB;AAqBlC,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,WAAW,aAAa,EAAE,WAAW,eAAe,EAAE,WAAW,kBACnE,EAAE,SAAS,QAAS,OAAO,EAAE,SAAS,YAAY,OAAQ,EAAE,KAAqB,UAAU;AAEhG;AAIA,MAAM,UAAU,kBAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,QAAQ,WAAW,MAAM,KAAK;AAAA,EACzC,OAAO,CAAC,QAAS,YAAY,IAAI,KAAK,IAAK,IAAI,QAAsB;AACvE,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,eAAe,CAAC,aAC3B,QAAQ,SAAS,QAAQ;AAMpB,MAAM,UAAU,MAAiB,QAAQ,IAAI;","names":[]}

package/dist/catalog.cjs

@@ -25,9 +25,9 @@ __export(catalog_exports, {
   useCatalog: () => useCatalog
 });
 module.exports = __toCommonJS(catalog_exports);
-var import_react = require("react");
 var import_sandboxUtils = require("./sandboxUtils");
 var import_protocolStream = require("./protocolStream");
+var import_pushChannel = require("./pushChannel");
 const split = (name) => {
   const i = name.indexOf(":");
   if (i <= 0) throw new Error(`invalid catalog method name: ${name}`);
@@ -43,35 +43,23 @@ const invoke = async (name, params = {}) => {
   }
   return res.data;
 };
-const bundlerTransport = {
-  send: (msg) => (
-    // @ts-ignore - injected by the sandbox runtime
-    module.evaluation.module.bundler.messageBus.sendMessage(msg.type, msg)
-  ),
-  subscribe: (type, handler) => {
-    const d = module.evaluation.module.bundler.messageBus.onMessage((m) => {
-      if (m && m.type === type) handler(m);
-    });
-    return () => d.dispose();
-  }
+const streamTransport = {
+  send: (msg) => (0, import_sandboxUtils.sendMessage)(msg.type, msg),
+  subscribe: (type, handler) => (0, import_sandboxUtils.addListener)(type, (msg) => handler(msg))
 };
 function invokeStream(name, params = {}) {
   const [scheme, method] = split(name);
-  return (0, import_protocolStream.consumeStream)(bundlerTransport, `protocol-${scheme}`, method, [params]);
+  return (0, import_protocolStream.consumeStream)(streamTransport, `protocol-${scheme}`, method, [params]);
 }
-const catalogService = () => {
-  return module.evaluation.module.bundler.catalog;
-};
-const getCatalog = () => catalogService().getCatalog();
-const onCatalogChange = (listener) => {
-  const disposable = catalogService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useCatalog = () => {
-  const [catalog, setCatalog] = (0, import_react.useState)(getCatalog);
-  (0, import_react.useEffect)(() => onCatalogChange(setCatalog), []);
-  return catalog;
-};
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "api-catalog",
+  requestType: "request-api-catalog",
+  initial: [],
+  parse: (msg) => Array.isArray(msg.methods) ? msg.methods : void 0
+});
+const getCatalog = () => channel.get();
+const onCatalogChange = (listener) => channel.onChange(listener);
+const useCatalog = () => channel.use();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getCatalog,

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 { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\nimport type { StreamFrame } from './protocolStream';\nimport { consumeStream } from './protocolStream';\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\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\nconst bundlerTransport = {\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) =>\n    // @ts-ignore - injected by the sandbox runtime\n    module.evaluation.module.bundler.messageBus.sendMessage(msg.type, msg),\n  subscribe: (type: string, handler: (msg: { msgId?: number; stream?: StreamFrame }) => void) => {\n    // @ts-ignore - injected by the sandbox runtime\n    const d = module.evaluation.module.bundler.messageBus.onMessage((m: { type?: string }) => {\n      if (m && m.type === type) handler(m as { msgId?: number; stream?: StreamFrame });\n    });\n    return () => d.dispose();\n  },\n};\n\n/** Call a STREAMING catalog method by name, yielding its events. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(bundlerTransport, `protocol-${scheme}`, method, [params]);\n}\n\ninterface CatalogService {\n  getCatalog(): ApiMethod[];\n  onChange(listener: (catalog: ApiMethod[]) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.catalog` — injected by the sandbox runtime.\nconst catalogService = (): CatalogService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.catalog;\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[] => catalogService().getCatalog();\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  const disposable = catalogService().onChange(listener);\n  return () => disposable.dispose();\n};\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[] => {\n  const [catalog, setCatalog] = useState<ApiMethod[]>(getCatalog);\n  useEffect(() => onCatalogChange(setCatalog), []);\n  return catalog;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,mBAAoC;AACpC,0BAAgC;AAEhC,4BAA8B;AAa9B,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;AAEA,MAAM,mBAAmB;AAAA,EACvB,MAAM,CAAC;AAAA;AAAA,IAEL,OAAO,WAAW,OAAO,QAAQ,WAAW,YAAY,IAAI,MAAM,GAAG;AAAA;AAAA,EACvE,WAAW,CAAC,MAAc,YAAqE;AAE7F,UAAM,IAAI,OAAO,WAAW,OAAO,QAAQ,WAAW,UAAU,CAAC,MAAyB;AACxF,UAAI,KAAK,EAAE,SAAS,KAAM,SAAQ,CAA6C;AAAA,IACjF,CAAC;AACD,WAAO,MAAM,EAAE,QAAQ;AAAA,EACzB;AACF;AAGO,SAAS,aACd,MACA,SAAkC,CAAC,GACP;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,aAAO,qCAAoB,kBAAkB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC;AACrF;AAQA,MAAM,iBAAiB,MAAsB;AAE3C,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAIO,MAAM,aAAa,MAAmB,eAAe,EAAE,WAAW;AAIlE,MAAM,kBAAkB,CAAC,aAA2D;AACzF,QAAM,aAAa,eAAe,EAAE,SAAS,QAAQ;AACrD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAKO,MAAM,aAAa,MAAmB;AAC3C,QAAM,CAAC,SAAS,UAAU,QAAI,uBAAsB,UAAU;AAC9D,8BAAU,MAAM,gBAAgB,UAAU,GAAG,CAAC,CAAC;AAC/C,SAAO;AACT;","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: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\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};\n\n/** Call a STREAMING catalog method by name, yielding its events. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(streamTransport, `protocol-${scheme}`, method, [params]);\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;AAalC,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;AACvF;AAGO,SAAS,aACd,MACA,SAAkC,CAAC,GACP;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,aAAO,qCAAoB,iBAAiB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC;AACpF;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.js

@@ -1,6 +1,6 @@
-import { useEffect, useState } from "react";
-import { protocolRequest } from "./sandboxUtils";
+import { protocolRequest, sendMessage, addListener } from "./sandboxUtils";
 import { consumeStream } from "./protocolStream";
+import { createPushChannel } from "./pushChannel";
 const split = (name) => {
   const i = name.indexOf(":");
   if (i <= 0) throw new Error(`invalid catalog method name: ${name}`);
@@ -16,35 +16,23 @@ const invoke = async (name, params = {}) => {
   }
   return res.data;
 };
-const bundlerTransport = {
-  send: (msg) => (
-    // @ts-ignore - injected by the sandbox runtime
-    module.evaluation.module.bundler.messageBus.sendMessage(msg.type, msg)
-  ),
-  subscribe: (type, handler) => {
-    const d = module.evaluation.module.bundler.messageBus.onMessage((m) => {
-      if (m && m.type === type) handler(m);
-    });
-    return () => d.dispose();
-  }
+const streamTransport = {
+  send: (msg) => sendMessage(msg.type, msg),
+  subscribe: (type, handler) => addListener(type, (msg) => handler(msg))
 };
 function invokeStream(name, params = {}) {
   const [scheme, method] = split(name);
-  return consumeStream(bundlerTransport, `protocol-${scheme}`, method, [params]);
+  return consumeStream(streamTransport, `protocol-${scheme}`, method, [params]);
 }
-const catalogService = () => {
-  return module.evaluation.module.bundler.catalog;
-};
-const getCatalog = () => catalogService().getCatalog();
-const onCatalogChange = (listener) => {
-  const disposable = catalogService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useCatalog = () => {
-  const [catalog, setCatalog] = useState(getCatalog);
-  useEffect(() => onCatalogChange(setCatalog), []);
-  return catalog;
-};
+const channel = createPushChannel({
+  pushType: "api-catalog",
+  requestType: "request-api-catalog",
+  initial: [],
+  parse: (msg) => Array.isArray(msg.methods) ? msg.methods : void 0
+});
+const getCatalog = () => channel.get();
+const onCatalogChange = (listener) => channel.onChange(listener);
+const useCatalog = () => channel.use();
 export {
   getCatalog,
   invoke,

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 { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\nimport type { StreamFrame } from './protocolStream';\nimport { consumeStream } from './protocolStream';\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\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\nconst bundlerTransport = {\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) =>\n    // @ts-ignore - injected by the sandbox runtime\n    module.evaluation.module.bundler.messageBus.sendMessage(msg.type, msg),\n  subscribe: (type: string, handler: (msg: { msgId?: number; stream?: StreamFrame }) => void) => {\n    // @ts-ignore - injected by the sandbox runtime\n    const d = module.evaluation.module.bundler.messageBus.onMessage((m: { type?: string }) => {\n      if (m && m.type === type) handler(m as { msgId?: number; stream?: StreamFrame });\n    });\n    return () => d.dispose();\n  },\n};\n\n/** Call a STREAMING catalog method by name, yielding its events. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(bundlerTransport, `protocol-${scheme}`, method, [params]);\n}\n\ninterface CatalogService {\n  getCatalog(): ApiMethod[];\n  onChange(listener: (catalog: ApiMethod[]) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.catalog` — injected by the sandbox runtime.\nconst catalogService = (): CatalogService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.catalog;\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[] => catalogService().getCatalog();\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  const disposable = catalogService().onChange(listener);\n  return () => disposable.dispose();\n};\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[] => {\n  const [catalog, setCatalog] = useState<ApiMethod[]>(getCatalog);\n  useEffect(() => onCatalogChange(setCatalog), []);\n  return catalog;\n};\n"],"mappings":"AAKA,SAAS,WAAW,gBAAgB;AACpC,SAAS,uBAAuB;AAEhC,SAAS,qBAAqB;AAa9B,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;AAEA,MAAM,mBAAmB;AAAA,EACvB,MAAM,CAAC;AAAA;AAAA,IAEL,OAAO,WAAW,OAAO,QAAQ,WAAW,YAAY,IAAI,MAAM,GAAG;AAAA;AAAA,EACvE,WAAW,CAAC,MAAc,YAAqE;AAE7F,UAAM,IAAI,OAAO,WAAW,OAAO,QAAQ,WAAW,UAAU,CAAC,MAAyB;AACxF,UAAI,KAAK,EAAE,SAAS,KAAM,SAAQ,CAA6C;AAAA,IACjF,CAAC;AACD,WAAO,MAAM,EAAE,QAAQ;AAAA,EACzB;AACF;AAGO,SAAS,aACd,MACA,SAAkC,CAAC,GACP;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,SAAO,cAAoB,kBAAkB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC;AACrF;AAQA,MAAM,iBAAiB,MAAsB;AAE3C,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAIO,MAAM,aAAa,MAAmB,eAAe,EAAE,WAAW;AAIlE,MAAM,kBAAkB,CAAC,aAA2D;AACzF,QAAM,aAAa,eAAe,EAAE,SAAS,QAAQ;AACrD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAKO,MAAM,aAAa,MAAmB;AAC3C,QAAM,CAAC,SAAS,UAAU,IAAI,SAAsB,UAAU;AAC9D,YAAU,MAAM,gBAAgB,UAAU,GAAG,CAAC,CAAC;AAC/C,SAAO;AACT;","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: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\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};\n\n/** Call a STREAMING catalog method by name, yielding its events. */\nexport function invokeStream<T = unknown, R = unknown>(\n  name: string,\n  params: Record<string, unknown> = {},\n): AsyncGenerator<T, R, void> {\n  const [scheme, method] = split(name);\n  return consumeStream<T, R>(streamTransport, `protocol-${scheme}`, method, [params]);\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;AAalC,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;AACvF;AAGO,SAAS,aACd,MACA,SAAkC,CAAC,GACP;AAC5B,QAAM,CAAC,QAAQ,MAAM,IAAI,MAAM,IAAI;AACnC,SAAO,cAAoB,iBAAiB,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC;AACpF;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/editorContext.cjs

@@ -23,20 +23,16 @@ __export(editorContext_exports, {
   useEditorContext: () => useEditorContext
 });
 module.exports = __toCommonJS(editorContext_exports);
-var import_react = require("react");
-const editorContextService = () => {
-  return module.evaluation.module.bundler.editorContext;
-};
-const getEditorContext = () => editorContextService().getContext();
-const onEditorContextChange = (listener) => {
-  const disposable = editorContextService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useEditorContext = () => {
-  const [context, setContext] = (0, import_react.useState)(getEditorContext);
-  (0, import_react.useEffect)(() => onEditorContextChange(setContext), []);
-  return context;
-};
+var import_pushChannel = require("./pushChannel");
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "editor-context",
+  requestType: "request-editor-context",
+  initial: { dirtyPaths: [] },
+  parse: (msg) => Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === "string") ? { dirtyPaths: msg.dirtyPaths } : void 0
+});
+const getEditorContext = () => channel.get();
+const onEditorContextChange = (listener) => channel.onChange(listener);
+const useEditorContext = () => channel.use();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getEditorContext,

package/dist/editorContext.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\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}\n\ninterface EditorContextService {\n  getContext(): EditorContext;\n  onChange(listener: (context: EditorContext) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.editorContext` is the sandbox bundler service\n// injected into the evaluation context (same path the other SDK helpers use).\nconst editorContextService = (): EditorContextService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.editorContext;\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 => editorContextService().getContext();\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 = (\n  listener: (context: EditorContext) => void,\n): (() => void) => {\n  const disposable = editorContextService().onChange(listener);\n  return () => disposable.dispose();\n};\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 => {\n  const [context, setContext] = useState<EditorContext>(getEditorContext);\n  useEffect(() => onEditorContextChange(setContext), []);\n  return context;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AAwBpC,MAAM,uBAAuB,MAA4B;AAEvD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,mBAAmB,MAAqB,qBAAqB,EAAE,WAAW;AAMhF,MAAM,wBAAwB,CACnC,aACiB;AACjB,QAAM,aAAa,qBAAqB,EAAE,SAAS,QAAQ;AAC3D,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,mBAAmB,MAAqB;AACnD,QAAM,CAAC,SAAS,UAAU,QAAI,uBAAwB,gBAAgB;AACtE,8BAAU,MAAM,sBAAsB,UAAU,GAAG,CAAC,CAAC;AACrD,SAAO;AACT;","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}\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 channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [] },\n  parse: (msg) =>\n    Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === 'string')\n      ? { dirtyPaths: msg.dirtyPaths as string[] }\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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAqBlC,MAAM,cAAU,sCAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,EAAE;AAAA,EAC1B,OAAO,CAAC,QACN,MAAM,QAAQ,IAAI,UAAU,KAAK,IAAI,WAAW,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ,IAC9E,EAAE,YAAY,IAAI,WAAuB,IACzC;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/editorContext.js

@@ -1,17 +1,13 @@
-import { useEffect, useState } from "react";
-const editorContextService = () => {
-  return module.evaluation.module.bundler.editorContext;
-};
-const getEditorContext = () => editorContextService().getContext();
-const onEditorContextChange = (listener) => {
-  const disposable = editorContextService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useEditorContext = () => {
-  const [context, setContext] = useState(getEditorContext);
-  useEffect(() => onEditorContextChange(setContext), []);
-  return context;
-};
+import { createPushChannel } from "./pushChannel";
+const channel = createPushChannel({
+  pushType: "editor-context",
+  requestType: "request-editor-context",
+  initial: { dirtyPaths: [] },
+  parse: (msg) => Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === "string") ? { dirtyPaths: msg.dirtyPaths } : void 0
+});
+const getEditorContext = () => channel.get();
+const onEditorContextChange = (listener) => channel.onChange(listener);
+const useEditorContext = () => channel.use();
 export {
   getEditorContext,
   onEditorContextChange,

package/dist/editorContext.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\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}\n\ninterface EditorContextService {\n  getContext(): EditorContext;\n  onChange(listener: (context: EditorContext) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.editorContext` is the sandbox bundler service\n// injected into the evaluation context (same path the other SDK helpers use).\nconst editorContextService = (): EditorContextService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.editorContext;\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 => editorContextService().getContext();\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 = (\n  listener: (context: EditorContext) => void,\n): (() => void) => {\n  const disposable = editorContextService().onChange(listener);\n  return () => disposable.dispose();\n};\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 => {\n  const [context, setContext] = useState<EditorContext>(getEditorContext);\n  useEffect(() => onEditorContextChange(setContext), []);\n  return context;\n};\n"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AAwBpC,MAAM,uBAAuB,MAA4B;AAEvD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,mBAAmB,MAAqB,qBAAqB,EAAE,WAAW;AAMhF,MAAM,wBAAwB,CACnC,aACiB;AACjB,QAAM,aAAa,qBAAqB,EAAE,SAAS,QAAQ;AAC3D,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,mBAAmB,MAAqB;AACnD,QAAM,CAAC,SAAS,UAAU,IAAI,SAAwB,gBAAgB;AACtE,YAAU,MAAM,sBAAsB,UAAU,GAAG,CAAC,CAAC;AACrD,SAAO;AACT;","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}\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 channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [] },\n  parse: (msg) =>\n    Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === 'string')\n      ? { dirtyPaths: msg.dirtyPaths as string[] }\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;AAqBlC,MAAM,UAAU,kBAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,EAAE;AAAA,EAC1B,OAAO,CAAC,QACN,MAAM,QAAQ,IAAI,UAAU,KAAK,IAAI,WAAW,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ,IAC9E,EAAE,YAAY,IAAI,WAAuB,IACzC;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.cjs

@@ -23,20 +23,26 @@ __export(formFactor_exports, {
   useFormFactor: () => useFormFactor
 });
 module.exports = __toCommonJS(formFactor_exports);
-var import_react = require("react");
-const formFactorService = () => {
-  return module.evaluation.module.bundler.formFactor;
+var import_pushChannel = require("./pushChannel");
+const DEFAULT_FORM_FACTOR = {
+  class: "desktop",
+  orientation: "landscape",
+  width: 1280,
+  height: 800
 };
-const getFormFactor = () => formFactorService().getFormFactor();
-const onFormFactorChange = (listener) => {
-  const disposable = formFactorService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useFormFactor = () => {
-  const [ff, setFf] = (0, import_react.useState)(getFormFactor);
-  (0, import_react.useEffect)(() => onFormFactorChange(setFf), []);
-  return ff;
+const isFormFactor = (v) => {
+  const f = v;
+  return !!f && (f.class === "mobile" || f.class === "tablet" || f.class === "desktop") && (f.orientation === "portrait" || f.orientation === "landscape") && typeof f.width === "number" && typeof f.height === "number";
 };
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "form-factor",
+  requestType: "request-form-factor",
+  initial: DEFAULT_FORM_FACTOR,
+  parse: (msg) => isFormFactor(msg.formFactor) ? msg.formFactor : void 0
+});
+const getFormFactor = () => channel.get();
+const onFormFactorChange = (listener) => channel.onChange(listener);
+const useFormFactor = () => channel.use();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getFormFactor,

package/dist/formFactor.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\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';\nexport type Orientation = 'portrait' | 'landscape';\n\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\ninterface FormFactorService {\n  getFormFactor(): FormFactor;\n  onChange(listener: (formFactor: FormFactor) => void): { dispose(): void };\n}\n\nconst formFactorService = (): FormFactorService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.formFactor;\n};\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor =>\n  formFactorService().getFormFactor();\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 = (\n  listener: (formFactor: FormFactor) => void,\n): (() => void) => {\n  const disposable = formFactorService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => {\n  const [ff, setFf] = useState<FormFactor>(getFormFactor);\n  useEffect(() => onFormFactorChange(setFf), []);\n  return ff;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AA2BpC,MAAM,oBAAoB,MAAyB;AAEjD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAGO,MAAM,gBAAgB,MAC3B,kBAAkB,EAAE,cAAc;AAM7B,MAAM,qBAAqB,CAChC,aACiB;AACjB,QAAM,aAAa,kBAAkB,EAAE,SAAS,QAAQ;AACxD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAGO,MAAM,gBAAgB,MAAkB;AAC7C,QAAM,CAAC,IAAI,KAAK,QAAI,uBAAqB,aAAa;AACtD,8BAAU,MAAM,mBAAmB,KAAK,GAAG,CAAC,CAAC;AAC7C,SAAO;AACT;","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';\nexport type Orientation = 'portrait' | 'landscape';\n\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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAuBlC,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,cAAU,sCAA8B;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/formFactor.js

@@ -1,17 +1,23 @@
-import { useEffect, useState } from "react";
-const formFactorService = () => {
-  return module.evaluation.module.bundler.formFactor;
+import { createPushChannel } from "./pushChannel";
+const DEFAULT_FORM_FACTOR = {
+  class: "desktop",
+  orientation: "landscape",
+  width: 1280,
+  height: 800
 };
-const getFormFactor = () => formFactorService().getFormFactor();
-const onFormFactorChange = (listener) => {
-  const disposable = formFactorService().onChange(listener);
-  return () => disposable.dispose();
-};
-const useFormFactor = () => {
-  const [ff, setFf] = useState(getFormFactor);
-  useEffect(() => onFormFactorChange(setFf), []);
-  return ff;
+const isFormFactor = (v) => {
+  const f = v;
+  return !!f && (f.class === "mobile" || f.class === "tablet" || f.class === "desktop") && (f.orientation === "portrait" || f.orientation === "landscape") && typeof f.width === "number" && typeof f.height === "number";
 };
+const channel = createPushChannel({
+  pushType: "form-factor",
+  requestType: "request-form-factor",
+  initial: DEFAULT_FORM_FACTOR,
+  parse: (msg) => isFormFactor(msg.formFactor) ? msg.formFactor : void 0
+});
+const getFormFactor = () => channel.get();
+const onFormFactorChange = (listener) => channel.onChange(listener);
+const useFormFactor = () => channel.use();
 export {
   getFormFactor,
   onFormFactorChange,

package/dist/formFactor.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\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';\nexport type Orientation = 'portrait' | 'landscape';\n\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\ninterface FormFactorService {\n  getFormFactor(): FormFactor;\n  onChange(listener: (formFactor: FormFactor) => void): { dispose(): void };\n}\n\nconst formFactorService = (): FormFactorService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.formFactor;\n};\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor =>\n  formFactorService().getFormFactor();\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 = (\n  listener: (formFactor: FormFactor) => void,\n): (() => void) => {\n  const disposable = formFactorService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => {\n  const [ff, setFf] = useState<FormFactor>(getFormFactor);\n  useEffect(() => onFormFactorChange(setFf), []);\n  return ff;\n};\n"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AA2BpC,MAAM,oBAAoB,MAAyB;AAEjD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAGO,MAAM,gBAAgB,MAC3B,kBAAkB,EAAE,cAAc;AAM7B,MAAM,qBAAqB,CAChC,aACiB;AACjB,QAAM,aAAa,kBAAkB,EAAE,SAAS,QAAQ;AACxD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAGO,MAAM,gBAAgB,MAAkB;AAC7C,QAAM,CAAC,IAAI,KAAK,IAAI,SAAqB,aAAa;AACtD,YAAU,MAAM,mBAAmB,KAAK,GAAG,CAAC,CAAC;AAC7C,SAAO;AACT;","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';\nexport type Orientation = 'portrait' | 'landscape';\n\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;AAuBlC,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/hostRuntime.cjs.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}\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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAwBO,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}\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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/hostRuntime.d.cts

@@ -8,6 +8,9 @@ interface ImmediatelyRunGlobal {
     transport?: unknown;
     /** Resolves when ports arrive, if they arrive async after register-frame. */
     ready?: Promise<void>;
+    /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);
+     *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */
+    appMountPath?: string;
 }
 /**
  * Read the sandbox runtime's discovery global (§4), or null when absent — in which

package/dist/hostRuntime.d.ts

@@ -8,6 +8,9 @@ interface ImmediatelyRunGlobal {
     transport?: unknown;
     /** Resolves when ports arrive, if they arrive async after register-frame. */
     ready?: Promise<void>;
+    /** Canonical `/mnt/{hash}` path of the app's own repo mount (FILE_SHARING §11.2);
+     *  surfaced to apps via `getAppMountPath()`. Absent until the host reports it. */
+    appMountPath?: string;
 }
 /**
  * Read the sandbox runtime's discovery global (§4), or null when absent — in which

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}\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":"AAwBO,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}\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":"AA2BO,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/index.cjs

@@ -29,6 +29,7 @@ __reExport(index_exports, require("./mounts"), module.exports);
 __reExport(index_exports, require("./contribute"), module.exports);
 __reExport(index_exports, require("./catalog"), module.exports);
 __reExport(index_exports, require("./ipc"), module.exports);
+__reExport(index_exports, require("./netFetch"), module.exports);
 __reExport(index_exports, require("./tasks"), module.exports);
 __reExport(index_exports, require("./runtime"), module.exports);
 __reExport(index_exports, require("./protocolStream"), module.exports);
@@ -49,6 +50,7 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./contribute"),
   ...require("./catalog"),
   ...require("./ipc"),
+  ...require("./netFetch"),
   ...require("./tasks"),
   ...require("./runtime"),
   ...require("./protocolStream"),

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 './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,4BARd;AASA,0BAAc,yBATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,sBAZd;AAaA,0BAAc,kBAbd;AAcA,0BAAc,oBAdd;AAeA,0BAAc,sBAfd;AAgBA,0BAAc,6BAhBd;AAiBA,0BAAc,2BAjBd;","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 './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './netFetch';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,4BARd;AASA,0BAAc,yBATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,sBAZd;AAaA,0BAAc,kBAbd;AAcA,0BAAc,uBAdd;AAeA,0BAAc,oBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,6BAjBd;AAkBA,0BAAc,2BAlBd;","names":[]}