@immediately-run/sdk 0.58.0 → 0.59.0

package/dist/index.d.cts

@@ -13,7 +13,7 @@ export { ObjectUrlState, useAllMetadata, useFileMetadata, useMetadataQuery, useO
 export { MetadataSource, MetadataSourceMode, MetadataSourceProps, useMetadataStore } from './metadataSource.cjs';
 export { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler.cjs';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.cjs';
-export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.cjs';
+export { HostTheme, HostThemeSelection, SetHostThemeSelectionParams, ThemeBundleLocation, ThemeCatalog, ThemeCatalogEntry, addThemeSource, getHostTheme, getHostThemeSelection, getThemeCatalog, onHostThemeChange, onHostThemeSelectionChange, onThemeCatalogChange, removeThemeSource, setHostTheme, setHostThemeSelection, useHostTheme, useHostThemeSelection, useThemeCatalog } from './theme.cjs';
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.cjs';
 export { EditTarget, EditorOpenError, EditorOpenOptions, EditorSelection, EditorSessionError, EditorWriteError, RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile } from './editor.cjs';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.cjs';

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { ObjectUrlState, useAllMetadata, useFileMetadata, useMetadataQuery, useO
 export { MetadataSource, MetadataSourceMode, MetadataSourceProps, useMetadataStore } from './metadataSource.js';
 export { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler.js';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.js';
-export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.js';
+export { HostTheme, HostThemeSelection, SetHostThemeSelectionParams, ThemeBundleLocation, ThemeCatalog, ThemeCatalogEntry, addThemeSource, getHostTheme, getHostThemeSelection, getThemeCatalog, onHostThemeChange, onHostThemeSelectionChange, onThemeCatalogChange, removeThemeSource, setHostTheme, setHostThemeSelection, useHostTheme, useHostThemeSelection, useThemeCatalog } from './theme.js';
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.js';
 export { EditTarget, EditorOpenError, EditorOpenOptions, EditorSelection, EditorSessionError, EditorWriteError, RequestEditError, closeFile, createFile, createFolder, deleteEntry, openInEditor, renameEntry, requestEdit, setActiveFile, uploadFile } from './editor.js';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.js';

package/dist/theme.cjs

@@ -18,38 +18,122 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var theme_exports = {};
 __export(theme_exports, {
+  addThemeSource: () => addThemeSource,
   getHostTheme: () => getHostTheme,
+  getHostThemeSelection: () => getHostThemeSelection,
+  getThemeCatalog: () => getThemeCatalog,
   onHostThemeChange: () => onHostThemeChange,
+  onHostThemeSelectionChange: () => onHostThemeSelectionChange,
+  onThemeCatalogChange: () => onThemeCatalogChange,
+  removeThemeSource: () => removeThemeSource,
   setHostTheme: () => setHostTheme,
-  useHostTheme: () => useHostTheme
+  setHostThemeSelection: () => setHostThemeSelection,
+  useHostTheme: () => useHostTheme,
+  useHostThemeSelection: () => useHostThemeSelection,
+  useThemeCatalog: () => useThemeCatalog
 });
 module.exports = __toCommonJS(theme_exports);
 var import_pushChannel = require("./pushChannel");
 var import_sandboxUtils = require("./sandboxUtils");
 var import_protocol = require("./generated/protocol");
 var import_protocolSchemes = require("./protocolSchemes");
+const DEFAULT_SELECTION = {
+  theme: "dark",
+  themeKey: "immediately-run-default",
+  modeId: "dark"
+};
 const channel = (0, import_pushChannel.createPushChannel)({
   pushType: import_protocol.THEME,
   requestType: import_protocol.REQUEST_THEME,
-  initial: "dark",
-  parse: (msg) => msg.theme === "light" || msg.theme === "dark" ? msg.theme : void 0
+  initial: DEFAULT_SELECTION,
+  parse: (msg) => {
+    if (msg.theme !== "light" && msg.theme !== "dark") return void 0;
+    if (typeof msg.themeKey !== "string" || typeof msg.modeId !== "string") return void 0;
+    return { theme: msg.theme, themeKey: msg.themeKey, modeId: msg.modeId };
+  }
 });
-const getHostTheme = () => channel.get();
-const onHostThemeChange = (listener) => channel.onChange(listener);
-const useHostTheme = () => channel.use();
-const setHostTheme = async (theme) => {
-  const res = await (0, import_sandboxUtils.protocolRequest)(import_protocolSchemes.SCHEMES[import_protocol.PROTOCOL_THEME], "set", [{ theme }]);
+const getHostTheme = () => channel.get().theme;
+const onHostThemeChange = (listener) => channel.onChange((sel) => listener(sel.theme));
+const useHostTheme = () => channel.use().theme;
+const getHostThemeSelection = () => channel.get();
+const onHostThemeSelectionChange = (listener) => channel.onChange(listener);
+const useHostThemeSelection = () => channel.use();
+const DEFAULT_CATALOG = { themes: [] };
+const catalogChannel = (0, import_pushChannel.createPushChannel)({
+  pushType: import_protocol.THEME_CATALOG,
+  requestType: import_protocol.REQUEST_THEME_CATALOG,
+  initial: DEFAULT_CATALOG,
+  parse: (msg) => {
+    const themes = msg.themes;
+    if (!Array.isArray(themes)) return void 0;
+    const out = [];
+    for (const t of themes) {
+      if (!t || typeof t !== "object") return void 0;
+      const entry = t;
+      if (typeof entry.themeKey !== "string" || typeof entry.label !== "string" || !Array.isArray(entry.modes)) {
+        return void 0;
+      }
+      const modes = [];
+      for (const m of entry.modes) {
+        if (!m || typeof m !== "object") return void 0;
+        const mode = m;
+        if (typeof mode.id !== "string" || mode.polarity !== "light" && mode.polarity !== "dark") {
+          return void 0;
+        }
+        modes.push({ id: mode.id, polarity: mode.polarity });
+      }
+      out.push({ themeKey: entry.themeKey, label: entry.label, modes });
+    }
+    return { themes: out };
+  }
+});
+const getThemeCatalog = () => catalogChannel.get();
+const onThemeCatalogChange = (listener) => catalogChannel.onChange(listener);
+const useThemeCatalog = () => catalogChannel.use();
+const setTheme = async (params) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)(import_protocolSchemes.SCHEMES[import_protocol.PROTOCOL_THEME], "set", [params]);
   if (!res || res.ok !== true) {
     const err = new Error(res?.message ?? "setHostTheme failed");
     err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
     throw err;
   }
 };
+const setHostThemeSelection = async (selection) => {
+  await setTheme(selection);
+};
+const setHostTheme = async (theme) => {
+  await setTheme({ theme });
+};
+const addThemeSource = async (location) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)(import_protocolSchemes.SCHEMES[import_protocol.PROTOCOL_THEME], "add-source", [{ location }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "addThemeSource failed");
+    err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
+    throw err;
+  }
+};
+const removeThemeSource = async (themeKey) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)(import_protocolSchemes.SCHEMES[import_protocol.PROTOCOL_THEME], "remove-source", [{ themeKey }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "removeThemeSource failed");
+    err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
+    throw err;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  addThemeSource,
   getHostTheme,
+  getHostThemeSelection,
+  getThemeCatalog,
   onHostThemeChange,
+  onHostThemeSelectionChange,
+  onThemeCatalogChange,
+  removeThemeSource,
   setHostTheme,
-  useHostTheme
+  setHostThemeSelection,
+  useHostTheme,
+  useHostThemeSelection,
+  useThemeCatalog
 });
 //# sourceMappingURL=theme.cjs.map

package/dist/theme.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\nimport { PROTOCOL_THEME, REQUEST_THEME, THEME } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/**\n * The host UI theme, mirrored from the immediately.run host window into the\n * sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n */\nexport type HostTheme = 'light' | 'dark';\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `theme` and\n// answers `request-theme` (wire format: site-main channelBridge.ts). The host's\n// default before it reports is `dark` (sandbox themeState.DEFAULT_THEME).\nconst channel = createPushChannel<HostTheme>({\n  pushType: THEME,\n  requestType: REQUEST_THEME,\n  initial: 'dark',\n  parse: (msg) => (msg.theme === 'light' || msg.theme === 'dark' ? msg.theme : undefined),\n});\n\n/**\n * Returns the current host theme. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => channel.get();\n\n/**\n * Subscribe to host theme changes. The listener is invoked immediately with the\n * current theme, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (listener: (theme: HostTheme) => void): (() => void) => channel.onChange(listener);\n\n/**\n * React hook returning the current host theme, re-rendering when it changes.\n * The recommended way to implement an app's own `useTheme`: follow the host,\n * allow a local override.\n */\nexport const useHostTheme = (): HostTheme => channel.use();\n\n/**\n * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host\n * applies it and re-pushes the new value to every `theme:read` iframe, so your\n * own {@link useHostTheme} confirms the change (the loop closes with no special\n * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may\n * call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims. Update\n * optimistically and let the re-push confirm.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])) 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 ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAClC,0BAAgC;AAChC,sBAAqD;AACrD,6BAAwB;AAgBxB,MAAM,cAAU,sCAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,IAAI,UAAU,WAAW,IAAI,UAAU,SAAS,IAAI,QAAQ;AAC/E,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,oBAAoB,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAO3G,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAWlD,MAAM,eAAe,OAAO,UAAoC;AACrE,QAAM,MAAO,UAAM,qCAAgB,+BAAQ,8BAAc,GAAG,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AAI9E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,qBAAqB;AAG3D,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACF;","names":[]}
+{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\nimport { PROTOCOL_THEME, REQUEST_THEME, REQUEST_THEME_CATALOG, THEME, THEME_CATALOG } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/**\n * The host UI theme polarity, mirrored from the immediately.run host window into\n * the sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n *\n * `HostTheme` is the RESOLVED POLARITY only. The full selection — which theme is\n * active and which of its modes — is {@link HostThemeSelection}.\n */\nexport type HostTheme = 'light' | 'dark';\n\n/**\n * The full host theme selection (HOST_THEMING_SPEC §2/§9.1): the resolved polarity\n * plus the active theme's registry key and resolved mode. Carried on the widened\n * `theme` push. `modeId` is always the RESOLVED mode (never the literal `system` —\n * an app wants to know what is on screen).\n */\nexport interface HostThemeSelection {\n  /** Resolved polarity — the same value the legacy `theme` field carried. */\n  theme: HostTheme;\n  /** The host-minted registry key of the active theme. */\n  themeKey: string;\n  /** The resolved active mode id of the active theme. */\n  modeId: string;\n}\n\n/**\n * The selection assumed before the host reports. The platform default theme is\n * `immediately-run-default` (dark polarity first-paint, matching the shipped\n * provider default — HOST_THEMING_SPEC §3 build-time correction).\n */\nconst DEFAULT_SELECTION: HostThemeSelection = {\n  theme: 'dark',\n  themeKey: 'immediately-run-default',\n  modeId: 'dark',\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `theme` and\n// answers `request-theme` (wire format: site-main channelBridge.ts). The parse\n// reads ALL THREE fields so the full selection survives the transport; the\n// polarity-only surface derives from it.\nconst channel = createPushChannel<HostThemeSelection>({\n  pushType: THEME,\n  requestType: REQUEST_THEME,\n  initial: DEFAULT_SELECTION,\n  parse: (msg) => {\n    if (msg.theme !== 'light' && msg.theme !== 'dark') return undefined;\n    if (typeof msg.themeKey !== 'string' || typeof msg.modeId !== 'string') return undefined;\n    return { theme: msg.theme, themeKey: msg.themeKey, modeId: msg.modeId };\n  },\n});\n\n/**\n * Returns the current host theme polarity. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => channel.get().theme;\n\n/**\n * Subscribe to host theme polarity changes. The listener is invoked immediately\n * with the current polarity, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (listener: (theme: HostTheme) => void): (() => void) =>\n  channel.onChange((sel) => listener(sel.theme));\n\n/**\n * React hook returning the current host theme polarity, re-rendering when it\n * changes. The recommended way to implement an app's own `useTheme`: follow the\n * host, allow a local override.\n */\nexport const useHostTheme = (): HostTheme => channel.use().theme;\n\n/**\n * Returns the current full host theme selection — polarity, active theme key, and\n * resolved mode. Use {@link useHostThemeSelection} to react to changes.\n */\nexport const getHostThemeSelection = (): HostThemeSelection => channel.get();\n\n/**\n * Subscribe to full host theme selection changes. The listener is invoked\n * immediately with the current selection, then again on every change. Returns an\n * unsubscribe fn.\n */\nexport const onHostThemeSelectionChange = (listener: (selection: HostThemeSelection) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current full host theme selection. */\nexport const useHostThemeSelection = (): HostThemeSelection => channel.use();\n\n/**\n * One entry of the theme catalogue: a selectable theme and its modes. The\n * catalogue is projected per grant — the baseline `theme:read` projection carries\n * NO source identities (no repo coordinates, no spaceIds), and labels are bounded.\n */\nexport interface ThemeCatalogEntry {\n  themeKey: string;\n  label: string;\n  modes: { id: string; polarity: 'light' | 'dark' }[];\n}\n\n/**\n * The loaded-theme catalogue (HOST_THEMING_SPEC §9.2): every selectable theme, so\n * a theme-aware app can render a picker and match chrome. Pushed on\n * `theme-catalog` / polled with `request-theme-catalog`.\n */\nexport interface ThemeCatalog {\n  themes: ThemeCatalogEntry[];\n}\n\nconst DEFAULT_CATALOG: ThemeCatalog = { themes: [] };\n\nconst catalogChannel = createPushChannel<ThemeCatalog>({\n  pushType: THEME_CATALOG,\n  requestType: REQUEST_THEME_CATALOG,\n  initial: DEFAULT_CATALOG,\n  parse: (msg) => {\n    const themes = msg.themes;\n    if (!Array.isArray(themes)) return undefined;\n    const out: ThemeCatalogEntry[] = [];\n    for (const t of themes as unknown[]) {\n      if (!t || typeof t !== 'object') return undefined;\n      const entry = t as { themeKey?: unknown; label?: unknown; modes?: unknown };\n      if (typeof entry.themeKey !== 'string' || typeof entry.label !== 'string' || !Array.isArray(entry.modes)) {\n        return undefined;\n      }\n      const modes: ThemeCatalogEntry['modes'] = [];\n      for (const m of entry.modes) {\n        if (!m || typeof m !== 'object') return undefined;\n        const mode = m as { id?: unknown; polarity?: unknown };\n        if (typeof mode.id !== 'string' || (mode.polarity !== 'light' && mode.polarity !== 'dark')) {\n          return undefined;\n        }\n        modes.push({ id: mode.id, polarity: mode.polarity });\n      }\n      out.push({ themeKey: entry.themeKey, label: entry.label, modes });\n    }\n    return { themes: out };\n  },\n});\n\n/**\n * Returns the current theme catalogue (themes + their modes). Use\n * {@link useThemeCatalog} to react to changes.\n */\nexport const getThemeCatalog = (): ThemeCatalog => catalogChannel.get();\n\n/**\n * Subscribe to theme catalogue changes. The listener is invoked immediately with\n * the current catalogue, then again on every change. Returns an unsubscribe fn.\n */\nexport const onThemeCatalogChange = (listener: (catalog: ThemeCatalog) => void): (() => void) =>\n  catalogChannel.onChange(listener);\n\n/** React hook returning the current theme catalogue. */\nexport const useThemeCatalog = (): ThemeCatalog => catalogChannel.use();\n\n/**\n * A location the open-bundle picker returned — a repo or a space, with a\n * confined in-bundle path (OPEN_BUNDLE_SPEC §2). Carried to the host's\n * `theme:sources` `add-source` verb.\n */\nexport type ThemeBundleLocation =\n  | { kind: 'repo'; repo: string; ref?: string; path: string }\n  | { kind: 'space'; spaceId: string; path: string };\n\n/**\n * The canonical `theme:set` params (HOST_THEMING_SPEC §9.3). `theme` is the\n * registry key of the theme to select (or the legacy `'light' | 'dark'` polarity —\n * the host disambiguates by the reserved-id rule: legacy iff the value is\n * light/dark AND `mode` is absent). `mode` is one of that theme's modes or\n * `'system'`.\n */\nexport interface SetHostThemeSelectionParams {\n  theme: string;\n  mode?: string;\n}\n\n/** The one `set` call site, so the wire shape is fingerprint-stable. */\nconst setTheme = async (params: SetHostThemeSelectionParams): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [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 ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Set the host theme selection — the ELEVATED `theme:set` action\n * (HOST_THEMING_SPEC §9.3). `theme` is the registry key of the theme to select,\n * `mode` is one of that theme's modes or `'system'`. The host applies it and\n * re-pushes the new selection to every `theme:read` iframe, so your own\n * {@link useHostThemeSelection} confirms the change (the loop closes with no\n * special case). Only a grant holding `theme:set` (e.g. the theme-toggle system\n * app) may call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims.\n */\nexport const setHostThemeSelection = async (selection: { theme: string; mode: string }): Promise<void> => {\n  await setTheme(selection);\n};\n\n/**\n * Set the host UI theme polarity — the LEGACY form of `theme:set` (§9.3). The host\n * applies that polarity to the CURRENT theme (never resets to the default), then\n * re-pushes. Keep this alias for old-SDK callers; new code should prefer\n * {@link setHostThemeSelection}.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  await setTheme({ theme });\n};\n\n/**\n * Add a theme source — the ELEVATED `theme:sources` `add-source` verb\n * (HOST_THEMING_SPEC §9.3). `location` must be a location the host journal saw a\n * RECENT open-bundle invocation OF THIS APP return (the picker-provenance rule —\n * \"the pick is the consent\", machine-checked); anything else is rejected with a\n * readable reason. The host fetches, gates, and registers the theme before\n * returning, so a rejected pick surfaces inline in the switcher. Only a grant\n * holding `theme:sources` (the theme switcher) may call this.\n */\nexport const addThemeSource = async (location: ThemeBundleLocation): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'add-source', [{ location }])) 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 ?? 'addThemeSource failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Remove a theme source — the `theme:sources` `remove-source` verb (§9.3). If the\n * removed theme is the current selection, the host falls back to the default theme\n * (keeping the mode selection where it exists). The default theme is never\n * removable. Only a grant holding `theme:sources` may call this.\n */\nexport const removeThemeSource = async (themeKey: string): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'remove-source', [{ themeKey }])) 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 ?? 'removeThemeSource failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":"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","names":[]}

package/dist/theme.d.cts

@@ -1,38 +1,155 @@
 /**
- * The host UI theme, mirrored from the immediately.run host window into the
- * sandbox. Your app can read this to render in step with the host chrome
+ * The host UI theme polarity, mirrored from the immediately.run host window into
+ * the sandbox. Your app can read this to render in step with the host chrome
  * (light / dark).
  *
  * This is the baseline `theme:read` capability — every app may read it. Changing
  * the host theme is a separate, elevated action (`theme:set`), available only to
  * the theme-toggle system app.
+ *
+ * `HostTheme` is the RESOLVED POLARITY only. The full selection — which theme is
+ * active and which of its modes — is {@link HostThemeSelection}.
  */
 type HostTheme = 'light' | 'dark';
 /**
- * Returns the current host theme. Poll this for a one-off read; use
+ * The full host theme selection (HOST_THEMING_SPEC §2/§9.1): the resolved polarity
+ * plus the active theme's registry key and resolved mode. Carried on the widened
+ * `theme` push. `modeId` is always the RESOLVED mode (never the literal `system` —
+ * an app wants to know what is on screen).
+ */
+interface HostThemeSelection {
+    /** Resolved polarity — the same value the legacy `theme` field carried. */
+    theme: HostTheme;
+    /** The host-minted registry key of the active theme. */
+    themeKey: string;
+    /** The resolved active mode id of the active theme. */
+    modeId: string;
+}
+/**
+ * Returns the current host theme polarity. Poll this for a one-off read; use
  * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.
  */
 declare const getHostTheme: () => HostTheme;
 /**
- * Subscribe to host theme changes. The listener is invoked immediately with the
- * current theme, then again on every change. Returns an unsubscribe fn.
+ * Subscribe to host theme polarity changes. The listener is invoked immediately
+ * with the current polarity, then again on every change. Returns an unsubscribe fn.
  */
 declare const onHostThemeChange: (listener: (theme: HostTheme) => void) => (() => void);
 /**
- * React hook returning the current host theme, re-rendering when it changes.
- * The recommended way to implement an app's own `useTheme`: follow the host,
- * allow a local override.
+ * React hook returning the current host theme polarity, re-rendering when it
+ * changes. The recommended way to implement an app's own `useTheme`: follow the
+ * host, allow a local override.
  */
 declare const useHostTheme: () => HostTheme;
 /**
- * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host
- * applies it and re-pushes the new value to every `theme:read` iframe, so your
- * own {@link useHostTheme} confirms the change (the loop closes with no special
- * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may
- * call this; any other app is rejected host-side with a `forbidden`
- * {@link Error} (carrying `.code`), regardless of what the app claims. Update
- * optimistically and let the re-push confirm.
+ * Returns the current full host theme selection — polarity, active theme key, and
+ * resolved mode. Use {@link useHostThemeSelection} to react to changes.
+ */
+declare const getHostThemeSelection: () => HostThemeSelection;
+/**
+ * Subscribe to full host theme selection changes. The listener is invoked
+ * immediately with the current selection, then again on every change. Returns an
+ * unsubscribe fn.
+ */
+declare const onHostThemeSelectionChange: (listener: (selection: HostThemeSelection) => void) => (() => void);
+/** React hook returning the current full host theme selection. */
+declare const useHostThemeSelection: () => HostThemeSelection;
+/**
+ * One entry of the theme catalogue: a selectable theme and its modes. The
+ * catalogue is projected per grant — the baseline `theme:read` projection carries
+ * NO source identities (no repo coordinates, no spaceIds), and labels are bounded.
+ */
+interface ThemeCatalogEntry {
+    themeKey: string;
+    label: string;
+    modes: {
+        id: string;
+        polarity: 'light' | 'dark';
+    }[];
+}
+/**
+ * The loaded-theme catalogue (HOST_THEMING_SPEC §9.2): every selectable theme, so
+ * a theme-aware app can render a picker and match chrome. Pushed on
+ * `theme-catalog` / polled with `request-theme-catalog`.
+ */
+interface ThemeCatalog {
+    themes: ThemeCatalogEntry[];
+}
+/**
+ * Returns the current theme catalogue (themes + their modes). Use
+ * {@link useThemeCatalog} to react to changes.
+ */
+declare const getThemeCatalog: () => ThemeCatalog;
+/**
+ * Subscribe to theme catalogue changes. The listener is invoked immediately with
+ * the current catalogue, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onThemeCatalogChange: (listener: (catalog: ThemeCatalog) => void) => (() => void);
+/** React hook returning the current theme catalogue. */
+declare const useThemeCatalog: () => ThemeCatalog;
+/**
+ * A location the open-bundle picker returned — a repo or a space, with a
+ * confined in-bundle path (OPEN_BUNDLE_SPEC §2). Carried to the host's
+ * `theme:sources` `add-source` verb.
+ */
+type ThemeBundleLocation = {
+    kind: 'repo';
+    repo: string;
+    ref?: string;
+    path: string;
+} | {
+    kind: 'space';
+    spaceId: string;
+    path: string;
+};
+/**
+ * The canonical `theme:set` params (HOST_THEMING_SPEC §9.3). `theme` is the
+ * registry key of the theme to select (or the legacy `'light' | 'dark'` polarity —
+ * the host disambiguates by the reserved-id rule: legacy iff the value is
+ * light/dark AND `mode` is absent). `mode` is one of that theme's modes or
+ * `'system'`.
+ */
+interface SetHostThemeSelectionParams {
+    theme: string;
+    mode?: string;
+}
+/**
+ * Set the host theme selection — the ELEVATED `theme:set` action
+ * (HOST_THEMING_SPEC §9.3). `theme` is the registry key of the theme to select,
+ * `mode` is one of that theme's modes or `'system'`. The host applies it and
+ * re-pushes the new selection to every `theme:read` iframe, so your own
+ * {@link useHostThemeSelection} confirms the change (the loop closes with no
+ * special case). Only a grant holding `theme:set` (e.g. the theme-toggle system
+ * app) may call this; any other app is rejected host-side with a `forbidden`
+ * {@link Error} (carrying `.code`), regardless of what the app claims.
+ */
+declare const setHostThemeSelection: (selection: {
+    theme: string;
+    mode: string;
+}) => Promise<void>;
+/**
+ * Set the host UI theme polarity — the LEGACY form of `theme:set` (§9.3). The host
+ * applies that polarity to the CURRENT theme (never resets to the default), then
+ * re-pushes. Keep this alias for old-SDK callers; new code should prefer
+ * {@link setHostThemeSelection}.
  */
 declare const setHostTheme: (theme: HostTheme) => Promise<void>;
+/**
+ * Add a theme source — the ELEVATED `theme:sources` `add-source` verb
+ * (HOST_THEMING_SPEC §9.3). `location` must be a location the host journal saw a
+ * RECENT open-bundle invocation OF THIS APP return (the picker-provenance rule —
+ * "the pick is the consent", machine-checked); anything else is rejected with a
+ * readable reason. The host fetches, gates, and registers the theme before
+ * returning, so a rejected pick surfaces inline in the switcher. Only a grant
+ * holding `theme:sources` (the theme switcher) may call this.
+ */
+declare const addThemeSource: (location: ThemeBundleLocation) => Promise<void>;
+/**
+ * Remove a theme source — the `theme:sources` `remove-source` verb (§9.3). If the
+ * removed theme is the current selection, the host falls back to the default theme
+ * (keeping the mode selection where it exists). The default theme is never
+ * removable. Only a grant holding `theme:sources` may call this.
+ */
+declare const removeThemeSource: (themeKey: string) => Promise<void>;
 
-export { type HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme };
+export { type HostTheme, type HostThemeSelection, type SetHostThemeSelectionParams, type ThemeBundleLocation, type ThemeCatalog, type ThemeCatalogEntry, addThemeSource, getHostTheme, getHostThemeSelection, getThemeCatalog, onHostThemeChange, onHostThemeSelectionChange, onThemeCatalogChange, removeThemeSource, setHostTheme, setHostThemeSelection, useHostTheme, useHostThemeSelection, useThemeCatalog };

package/dist/theme.d.ts

@@ -1,38 +1,155 @@
 /**
- * The host UI theme, mirrored from the immediately.run host window into the
- * sandbox. Your app can read this to render in step with the host chrome
+ * The host UI theme polarity, mirrored from the immediately.run host window into
+ * the sandbox. Your app can read this to render in step with the host chrome
  * (light / dark).
  *
  * This is the baseline `theme:read` capability — every app may read it. Changing
  * the host theme is a separate, elevated action (`theme:set`), available only to
  * the theme-toggle system app.
+ *
+ * `HostTheme` is the RESOLVED POLARITY only. The full selection — which theme is
+ * active and which of its modes — is {@link HostThemeSelection}.
  */
 type HostTheme = 'light' | 'dark';
 /**
- * Returns the current host theme. Poll this for a one-off read; use
+ * The full host theme selection (HOST_THEMING_SPEC §2/§9.1): the resolved polarity
+ * plus the active theme's registry key and resolved mode. Carried on the widened
+ * `theme` push. `modeId` is always the RESOLVED mode (never the literal `system` —
+ * an app wants to know what is on screen).
+ */
+interface HostThemeSelection {
+    /** Resolved polarity — the same value the legacy `theme` field carried. */
+    theme: HostTheme;
+    /** The host-minted registry key of the active theme. */
+    themeKey: string;
+    /** The resolved active mode id of the active theme. */
+    modeId: string;
+}
+/**
+ * Returns the current host theme polarity. Poll this for a one-off read; use
  * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.
  */
 declare const getHostTheme: () => HostTheme;
 /**
- * Subscribe to host theme changes. The listener is invoked immediately with the
- * current theme, then again on every change. Returns an unsubscribe fn.
+ * Subscribe to host theme polarity changes. The listener is invoked immediately
+ * with the current polarity, then again on every change. Returns an unsubscribe fn.
  */
 declare const onHostThemeChange: (listener: (theme: HostTheme) => void) => (() => void);
 /**
- * React hook returning the current host theme, re-rendering when it changes.
- * The recommended way to implement an app's own `useTheme`: follow the host,
- * allow a local override.
+ * React hook returning the current host theme polarity, re-rendering when it
+ * changes. The recommended way to implement an app's own `useTheme`: follow the
+ * host, allow a local override.
  */
 declare const useHostTheme: () => HostTheme;
 /**
- * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host
- * applies it and re-pushes the new value to every `theme:read` iframe, so your
- * own {@link useHostTheme} confirms the change (the loop closes with no special
- * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may
- * call this; any other app is rejected host-side with a `forbidden`
- * {@link Error} (carrying `.code`), regardless of what the app claims. Update
- * optimistically and let the re-push confirm.
+ * Returns the current full host theme selection — polarity, active theme key, and
+ * resolved mode. Use {@link useHostThemeSelection} to react to changes.
+ */
+declare const getHostThemeSelection: () => HostThemeSelection;
+/**
+ * Subscribe to full host theme selection changes. The listener is invoked
+ * immediately with the current selection, then again on every change. Returns an
+ * unsubscribe fn.
+ */
+declare const onHostThemeSelectionChange: (listener: (selection: HostThemeSelection) => void) => (() => void);
+/** React hook returning the current full host theme selection. */
+declare const useHostThemeSelection: () => HostThemeSelection;
+/**
+ * One entry of the theme catalogue: a selectable theme and its modes. The
+ * catalogue is projected per grant — the baseline `theme:read` projection carries
+ * NO source identities (no repo coordinates, no spaceIds), and labels are bounded.
+ */
+interface ThemeCatalogEntry {
+    themeKey: string;
+    label: string;
+    modes: {
+        id: string;
+        polarity: 'light' | 'dark';
+    }[];
+}
+/**
+ * The loaded-theme catalogue (HOST_THEMING_SPEC §9.2): every selectable theme, so
+ * a theme-aware app can render a picker and match chrome. Pushed on
+ * `theme-catalog` / polled with `request-theme-catalog`.
+ */
+interface ThemeCatalog {
+    themes: ThemeCatalogEntry[];
+}
+/**
+ * Returns the current theme catalogue (themes + their modes). Use
+ * {@link useThemeCatalog} to react to changes.
+ */
+declare const getThemeCatalog: () => ThemeCatalog;
+/**
+ * Subscribe to theme catalogue changes. The listener is invoked immediately with
+ * the current catalogue, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onThemeCatalogChange: (listener: (catalog: ThemeCatalog) => void) => (() => void);
+/** React hook returning the current theme catalogue. */
+declare const useThemeCatalog: () => ThemeCatalog;
+/**
+ * A location the open-bundle picker returned — a repo or a space, with a
+ * confined in-bundle path (OPEN_BUNDLE_SPEC §2). Carried to the host's
+ * `theme:sources` `add-source` verb.
+ */
+type ThemeBundleLocation = {
+    kind: 'repo';
+    repo: string;
+    ref?: string;
+    path: string;
+} | {
+    kind: 'space';
+    spaceId: string;
+    path: string;
+};
+/**
+ * The canonical `theme:set` params (HOST_THEMING_SPEC §9.3). `theme` is the
+ * registry key of the theme to select (or the legacy `'light' | 'dark'` polarity —
+ * the host disambiguates by the reserved-id rule: legacy iff the value is
+ * light/dark AND `mode` is absent). `mode` is one of that theme's modes or
+ * `'system'`.
+ */
+interface SetHostThemeSelectionParams {
+    theme: string;
+    mode?: string;
+}
+/**
+ * Set the host theme selection — the ELEVATED `theme:set` action
+ * (HOST_THEMING_SPEC §9.3). `theme` is the registry key of the theme to select,
+ * `mode` is one of that theme's modes or `'system'`. The host applies it and
+ * re-pushes the new selection to every `theme:read` iframe, so your own
+ * {@link useHostThemeSelection} confirms the change (the loop closes with no
+ * special case). Only a grant holding `theme:set` (e.g. the theme-toggle system
+ * app) may call this; any other app is rejected host-side with a `forbidden`
+ * {@link Error} (carrying `.code`), regardless of what the app claims.
+ */
+declare const setHostThemeSelection: (selection: {
+    theme: string;
+    mode: string;
+}) => Promise<void>;
+/**
+ * Set the host UI theme polarity — the LEGACY form of `theme:set` (§9.3). The host
+ * applies that polarity to the CURRENT theme (never resets to the default), then
+ * re-pushes. Keep this alias for old-SDK callers; new code should prefer
+ * {@link setHostThemeSelection}.
  */
 declare const setHostTheme: (theme: HostTheme) => Promise<void>;
+/**
+ * Add a theme source — the ELEVATED `theme:sources` `add-source` verb
+ * (HOST_THEMING_SPEC §9.3). `location` must be a location the host journal saw a
+ * RECENT open-bundle invocation OF THIS APP return (the picker-provenance rule —
+ * "the pick is the consent", machine-checked); anything else is rejected with a
+ * readable reason. The host fetches, gates, and registers the theme before
+ * returning, so a rejected pick surfaces inline in the switcher. Only a grant
+ * holding `theme:sources` (the theme switcher) may call this.
+ */
+declare const addThemeSource: (location: ThemeBundleLocation) => Promise<void>;
+/**
+ * Remove a theme source — the `theme:sources` `remove-source` verb (§9.3). If the
+ * removed theme is the current selection, the host falls back to the default theme
+ * (keeping the mode selection where it exists). The default theme is never
+ * removable. Only a grant holding `theme:sources` may call this.
+ */
+declare const removeThemeSource: (themeKey: string) => Promise<void>;
 
-export { type HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme };
+export { type HostTheme, type HostThemeSelection, type SetHostThemeSelectionParams, type ThemeBundleLocation, type ThemeCatalog, type ThemeCatalogEntry, addThemeSource, getHostTheme, getHostThemeSelection, getThemeCatalog, onHostThemeChange, onHostThemeSelectionChange, onThemeCatalogChange, removeThemeSource, setHostTheme, setHostThemeSelection, useHostTheme, useHostThemeSelection, useThemeCatalog };

package/dist/theme.js

@@ -1,29 +1,104 @@
 import "./chunk-VHAA22YE.js";
 import { createPushChannel } from "./pushChannel";
 import { protocolRequest } from "./sandboxUtils";
-import { PROTOCOL_THEME, REQUEST_THEME, THEME } from "./generated/protocol";
+import { PROTOCOL_THEME, REQUEST_THEME, REQUEST_THEME_CATALOG, THEME, THEME_CATALOG } from "./generated/protocol";
 import { SCHEMES } from "./protocolSchemes";
+const DEFAULT_SELECTION = {
+  theme: "dark",
+  themeKey: "immediately-run-default",
+  modeId: "dark"
+};
 const channel = createPushChannel({
   pushType: THEME,
   requestType: REQUEST_THEME,
-  initial: "dark",
-  parse: (msg) => msg.theme === "light" || msg.theme === "dark" ? msg.theme : void 0
+  initial: DEFAULT_SELECTION,
+  parse: (msg) => {
+    if (msg.theme !== "light" && msg.theme !== "dark") return void 0;
+    if (typeof msg.themeKey !== "string" || typeof msg.modeId !== "string") return void 0;
+    return { theme: msg.theme, themeKey: msg.themeKey, modeId: msg.modeId };
+  }
 });
-const getHostTheme = () => channel.get();
-const onHostThemeChange = (listener) => channel.onChange(listener);
-const useHostTheme = () => channel.use();
-const setHostTheme = async (theme) => {
-  const res = await protocolRequest(SCHEMES[PROTOCOL_THEME], "set", [{ theme }]);
+const getHostTheme = () => channel.get().theme;
+const onHostThemeChange = (listener) => channel.onChange((sel) => listener(sel.theme));
+const useHostTheme = () => channel.use().theme;
+const getHostThemeSelection = () => channel.get();
+const onHostThemeSelectionChange = (listener) => channel.onChange(listener);
+const useHostThemeSelection = () => channel.use();
+const DEFAULT_CATALOG = { themes: [] };
+const catalogChannel = createPushChannel({
+  pushType: THEME_CATALOG,
+  requestType: REQUEST_THEME_CATALOG,
+  initial: DEFAULT_CATALOG,
+  parse: (msg) => {
+    const themes = msg.themes;
+    if (!Array.isArray(themes)) return void 0;
+    const out = [];
+    for (const t of themes) {
+      if (!t || typeof t !== "object") return void 0;
+      const entry = t;
+      if (typeof entry.themeKey !== "string" || typeof entry.label !== "string" || !Array.isArray(entry.modes)) {
+        return void 0;
+      }
+      const modes = [];
+      for (const m of entry.modes) {
+        if (!m || typeof m !== "object") return void 0;
+        const mode = m;
+        if (typeof mode.id !== "string" || mode.polarity !== "light" && mode.polarity !== "dark") {
+          return void 0;
+        }
+        modes.push({ id: mode.id, polarity: mode.polarity });
+      }
+      out.push({ themeKey: entry.themeKey, label: entry.label, modes });
+    }
+    return { themes: out };
+  }
+});
+const getThemeCatalog = () => catalogChannel.get();
+const onThemeCatalogChange = (listener) => catalogChannel.onChange(listener);
+const useThemeCatalog = () => catalogChannel.use();
+const setTheme = async (params) => {
+  const res = await protocolRequest(SCHEMES[PROTOCOL_THEME], "set", [params]);
   if (!res || res.ok !== true) {
     const err = new Error(res?.message ?? "setHostTheme failed");
     err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
     throw err;
   }
 };
+const setHostThemeSelection = async (selection) => {
+  await setTheme(selection);
+};
+const setHostTheme = async (theme) => {
+  await setTheme({ theme });
+};
+const addThemeSource = async (location) => {
+  const res = await protocolRequest(SCHEMES[PROTOCOL_THEME], "add-source", [{ location }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "addThemeSource failed");
+    err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
+    throw err;
+  }
+};
+const removeThemeSource = async (themeKey) => {
+  const res = await protocolRequest(SCHEMES[PROTOCOL_THEME], "remove-source", [{ themeKey }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "removeThemeSource failed");
+    err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
+    throw err;
+  }
+};
 export {
+  addThemeSource,
   getHostTheme,
+  getHostThemeSelection,
+  getThemeCatalog,
   onHostThemeChange,
+  onHostThemeSelectionChange,
+  onThemeCatalogChange,
+  removeThemeSource,
   setHostTheme,
-  useHostTheme
+  setHostThemeSelection,
+  useHostTheme,
+  useHostThemeSelection,
+  useThemeCatalog
 };
 //# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\nimport { PROTOCOL_THEME, REQUEST_THEME, THEME } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/**\n * The host UI theme, mirrored from the immediately.run host window into the\n * sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n */\nexport type HostTheme = 'light' | 'dark';\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `theme` and\n// answers `request-theme` (wire format: site-main channelBridge.ts). The host's\n// default before it reports is `dark` (sandbox themeState.DEFAULT_THEME).\nconst channel = createPushChannel<HostTheme>({\n  pushType: THEME,\n  requestType: REQUEST_THEME,\n  initial: 'dark',\n  parse: (msg) => (msg.theme === 'light' || msg.theme === 'dark' ? msg.theme : undefined),\n});\n\n/**\n * Returns the current host theme. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => channel.get();\n\n/**\n * Subscribe to host theme changes. The listener is invoked immediately with the\n * current theme, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (listener: (theme: HostTheme) => void): (() => void) => channel.onChange(listener);\n\n/**\n * React hook returning the current host theme, re-rendering when it changes.\n * The recommended way to implement an app's own `useTheme`: follow the host,\n * allow a local override.\n */\nexport const useHostTheme = (): HostTheme => channel.use();\n\n/**\n * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host\n * applies it and re-pushes the new value to every `theme:read` iframe, so your\n * own {@link useHostTheme} confirms the change (the loop closes with no special\n * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may\n * call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims. Update\n * optimistically and let the re-push confirm.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [{ theme }])) 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 ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":";AAAA,SAAS,yBAAyB;AAClC,SAAS,uBAAuB;AAChC,SAAS,gBAAgB,eAAe,aAAa;AACrD,SAAS,eAAe;AAgBxB,MAAM,UAAU,kBAA6B;AAAA,EAC3C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,IAAI,UAAU,WAAW,IAAI,UAAU,SAAS,IAAI,QAAQ;AAC/E,CAAC;AAMM,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAMlD,MAAM,oBAAoB,CAAC,aAAuD,QAAQ,SAAS,QAAQ;AAO3G,MAAM,eAAe,MAAiB,QAAQ,IAAI;AAWlD,MAAM,eAAe,OAAO,UAAoC;AACrE,QAAM,MAAO,MAAM,gBAAgB,QAAQ,cAAc,GAAG,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AAI9E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,qBAAqB;AAG3D,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACF;","names":[]}
+{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { protocolRequest } from './sandboxUtils';\nimport { PROTOCOL_THEME, REQUEST_THEME, REQUEST_THEME_CATALOG, THEME, THEME_CATALOG } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/**\n * The host UI theme polarity, mirrored from the immediately.run host window into\n * the sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n *\n * `HostTheme` is the RESOLVED POLARITY only. The full selection — which theme is\n * active and which of its modes — is {@link HostThemeSelection}.\n */\nexport type HostTheme = 'light' | 'dark';\n\n/**\n * The full host theme selection (HOST_THEMING_SPEC §2/§9.1): the resolved polarity\n * plus the active theme's registry key and resolved mode. Carried on the widened\n * `theme` push. `modeId` is always the RESOLVED mode (never the literal `system` —\n * an app wants to know what is on screen).\n */\nexport interface HostThemeSelection {\n  /** Resolved polarity — the same value the legacy `theme` field carried. */\n  theme: HostTheme;\n  /** The host-minted registry key of the active theme. */\n  themeKey: string;\n  /** The resolved active mode id of the active theme. */\n  modeId: string;\n}\n\n/**\n * The selection assumed before the host reports. The platform default theme is\n * `immediately-run-default` (dark polarity first-paint, matching the shipped\n * provider default — HOST_THEMING_SPEC §3 build-time correction).\n */\nconst DEFAULT_SELECTION: HostThemeSelection = {\n  theme: 'dark',\n  themeKey: 'immediately-run-default',\n  modeId: 'dark',\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `theme` and\n// answers `request-theme` (wire format: site-main channelBridge.ts). The parse\n// reads ALL THREE fields so the full selection survives the transport; the\n// polarity-only surface derives from it.\nconst channel = createPushChannel<HostThemeSelection>({\n  pushType: THEME,\n  requestType: REQUEST_THEME,\n  initial: DEFAULT_SELECTION,\n  parse: (msg) => {\n    if (msg.theme !== 'light' && msg.theme !== 'dark') return undefined;\n    if (typeof msg.themeKey !== 'string' || typeof msg.modeId !== 'string') return undefined;\n    return { theme: msg.theme, themeKey: msg.themeKey, modeId: msg.modeId };\n  },\n});\n\n/**\n * Returns the current host theme polarity. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => channel.get().theme;\n\n/**\n * Subscribe to host theme polarity changes. The listener is invoked immediately\n * with the current polarity, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (listener: (theme: HostTheme) => void): (() => void) =>\n  channel.onChange((sel) => listener(sel.theme));\n\n/**\n * React hook returning the current host theme polarity, re-rendering when it\n * changes. The recommended way to implement an app's own `useTheme`: follow the\n * host, allow a local override.\n */\nexport const useHostTheme = (): HostTheme => channel.use().theme;\n\n/**\n * Returns the current full host theme selection — polarity, active theme key, and\n * resolved mode. Use {@link useHostThemeSelection} to react to changes.\n */\nexport const getHostThemeSelection = (): HostThemeSelection => channel.get();\n\n/**\n * Subscribe to full host theme selection changes. The listener is invoked\n * immediately with the current selection, then again on every change. Returns an\n * unsubscribe fn.\n */\nexport const onHostThemeSelectionChange = (listener: (selection: HostThemeSelection) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current full host theme selection. */\nexport const useHostThemeSelection = (): HostThemeSelection => channel.use();\n\n/**\n * One entry of the theme catalogue: a selectable theme and its modes. The\n * catalogue is projected per grant — the baseline `theme:read` projection carries\n * NO source identities (no repo coordinates, no spaceIds), and labels are bounded.\n */\nexport interface ThemeCatalogEntry {\n  themeKey: string;\n  label: string;\n  modes: { id: string; polarity: 'light' | 'dark' }[];\n}\n\n/**\n * The loaded-theme catalogue (HOST_THEMING_SPEC §9.2): every selectable theme, so\n * a theme-aware app can render a picker and match chrome. Pushed on\n * `theme-catalog` / polled with `request-theme-catalog`.\n */\nexport interface ThemeCatalog {\n  themes: ThemeCatalogEntry[];\n}\n\nconst DEFAULT_CATALOG: ThemeCatalog = { themes: [] };\n\nconst catalogChannel = createPushChannel<ThemeCatalog>({\n  pushType: THEME_CATALOG,\n  requestType: REQUEST_THEME_CATALOG,\n  initial: DEFAULT_CATALOG,\n  parse: (msg) => {\n    const themes = msg.themes;\n    if (!Array.isArray(themes)) return undefined;\n    const out: ThemeCatalogEntry[] = [];\n    for (const t of themes as unknown[]) {\n      if (!t || typeof t !== 'object') return undefined;\n      const entry = t as { themeKey?: unknown; label?: unknown; modes?: unknown };\n      if (typeof entry.themeKey !== 'string' || typeof entry.label !== 'string' || !Array.isArray(entry.modes)) {\n        return undefined;\n      }\n      const modes: ThemeCatalogEntry['modes'] = [];\n      for (const m of entry.modes) {\n        if (!m || typeof m !== 'object') return undefined;\n        const mode = m as { id?: unknown; polarity?: unknown };\n        if (typeof mode.id !== 'string' || (mode.polarity !== 'light' && mode.polarity !== 'dark')) {\n          return undefined;\n        }\n        modes.push({ id: mode.id, polarity: mode.polarity });\n      }\n      out.push({ themeKey: entry.themeKey, label: entry.label, modes });\n    }\n    return { themes: out };\n  },\n});\n\n/**\n * Returns the current theme catalogue (themes + their modes). Use\n * {@link useThemeCatalog} to react to changes.\n */\nexport const getThemeCatalog = (): ThemeCatalog => catalogChannel.get();\n\n/**\n * Subscribe to theme catalogue changes. The listener is invoked immediately with\n * the current catalogue, then again on every change. Returns an unsubscribe fn.\n */\nexport const onThemeCatalogChange = (listener: (catalog: ThemeCatalog) => void): (() => void) =>\n  catalogChannel.onChange(listener);\n\n/** React hook returning the current theme catalogue. */\nexport const useThemeCatalog = (): ThemeCatalog => catalogChannel.use();\n\n/**\n * A location the open-bundle picker returned — a repo or a space, with a\n * confined in-bundle path (OPEN_BUNDLE_SPEC §2). Carried to the host's\n * `theme:sources` `add-source` verb.\n */\nexport type ThemeBundleLocation =\n  | { kind: 'repo'; repo: string; ref?: string; path: string }\n  | { kind: 'space'; spaceId: string; path: string };\n\n/**\n * The canonical `theme:set` params (HOST_THEMING_SPEC §9.3). `theme` is the\n * registry key of the theme to select (or the legacy `'light' | 'dark'` polarity —\n * the host disambiguates by the reserved-id rule: legacy iff the value is\n * light/dark AND `mode` is absent). `mode` is one of that theme's modes or\n * `'system'`.\n */\nexport interface SetHostThemeSelectionParams {\n  theme: string;\n  mode?: string;\n}\n\n/** The one `set` call site, so the wire shape is fingerprint-stable. */\nconst setTheme = async (params: SetHostThemeSelectionParams): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'set', [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 ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Set the host theme selection — the ELEVATED `theme:set` action\n * (HOST_THEMING_SPEC §9.3). `theme` is the registry key of the theme to select,\n * `mode` is one of that theme's modes or `'system'`. The host applies it and\n * re-pushes the new selection to every `theme:read` iframe, so your own\n * {@link useHostThemeSelection} confirms the change (the loop closes with no\n * special case). Only a grant holding `theme:set` (e.g. the theme-toggle system\n * app) may call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims.\n */\nexport const setHostThemeSelection = async (selection: { theme: string; mode: string }): Promise<void> => {\n  await setTheme(selection);\n};\n\n/**\n * Set the host UI theme polarity — the LEGACY form of `theme:set` (§9.3). The host\n * applies that polarity to the CURRENT theme (never resets to the default), then\n * re-pushes. Keep this alias for old-SDK callers; new code should prefer\n * {@link setHostThemeSelection}.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  await setTheme({ theme });\n};\n\n/**\n * Add a theme source — the ELEVATED `theme:sources` `add-source` verb\n * (HOST_THEMING_SPEC §9.3). `location` must be a location the host journal saw a\n * RECENT open-bundle invocation OF THIS APP return (the picker-provenance rule —\n * \"the pick is the consent\", machine-checked); anything else is rejected with a\n * readable reason. The host fetches, gates, and registers the theme before\n * returning, so a rejected pick surfaces inline in the switcher. Only a grant\n * holding `theme:sources` (the theme switcher) may call this.\n */\nexport const addThemeSource = async (location: ThemeBundleLocation): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'add-source', [{ location }])) 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 ?? 'addThemeSource failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Remove a theme source — the `theme:sources` `remove-source` verb (§9.3). If the\n * removed theme is the current selection, the host falls back to the default theme\n * (keeping the mode selection where it exists). The default theme is never\n * removable. Only a grant holding `theme:sources` may call this.\n */\nexport const removeThemeSource = async (themeKey: string): Promise<void> => {\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_THEME], 'remove-source', [{ themeKey }])) 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 ?? 'removeThemeSource failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":"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","names":[]}

package/dist/version.cjs

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

package/dist/version.cjs.map

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

package/dist/version.d.cts

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

package/dist/version.d.ts

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

package/dist/version.js

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

package/dist/version.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -64,7 +64,7 @@
     "@immediately-run/mdx-plugins": "0.5.0",
     "@immediately-run/platform-constants": "0.2.0",
     "@immediately-run/safe-content": "0.1.0",
-    "@immediately-run/sandbox-protocol": "0.7.7",
+    "@immediately-run/sandbox-protocol": "0.8.2",
     "react-error-boundary": "^6.0.0"
   },
   "devDependencies": {