@immediately-run/sdk 0.57.4 → 0.59.0

package/dist/index.cjs

@@ -45,6 +45,7 @@ __reExport(index_exports, require("./editorContext"), module.exports);
 __reExport(index_exports, require("./editor"), module.exports);
 __reExport(index_exports, require("./formFactor"), module.exports);
 __reExport(index_exports, require("./chromeState"), module.exports);
+__reExport(index_exports, require("./workspace"), module.exports);
 __reExport(index_exports, require("./hostAttention"), module.exports);
 __reExport(index_exports, require("./region"), module.exports);
 __reExport(index_exports, require("./mounts"), module.exports);
@@ -104,6 +105,7 @@ __reExport(index_exports, require("./fence"), module.exports);
   ...require("./editor"),
   ...require("./formFactor"),
   ...require("./chromeState"),
+  ...require("./workspace"),
   ...require("./hostAttention"),
   ...require("./region"),
   ...require("./mounts"),

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';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAQA,yBAA4B;AAC5B,0BAAc,0BATd;AAUA,0BAAc,uCAVd;AAWA,0BAAc,wBAXd;AAYA,0BAAc,qBAZd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,oCAfd;AAgBA,0BAAc,gCAhBd;AAiBA,0BAAc,oBAjBd;AAoBA,0BAAc,6BApBd;AAuBA,6BAAwE;AACxE,0BAAc,mBAxBd;AAyBA,0BAAc,oBAzBd;AA0BA,0BAAc,4BA1Bd;AA2BA,0BAAc,qBA3Bd;AA4BA,0BAAc,yBA5Bd;AA6BA,0BAAc,0BA7Bd;AA8BA,0BAAc,4BA9Bd;AA+BA,0BAAc,qBA/Bd;AAgCA,0BAAc,qBAhCd;AAiCA,0BAAc,wBAjCd;AAkCA,0BAAc,yBAlCd;AAmCA,0BAAc,sBAnCd;AAoCA,0BAAc,kBApCd;AAqCA,0BAAc,kBArCd;AAsCA,0BAAc,uBAtCd;AAuCA,0BAAc,mBAvCd;AAwCA,0BAAc,sBAxCd;AAyCA,0BAAc,sBAzCd;AA0CA,0BAAc,kBA1Cd;AA2CA,0BAAc,0BA3Cd;AA4CA,0BAAc,kBA5Cd;AA6CA,0BAAc,yBA7Cd;AA8CA,0BAAc,iBA9Cd;AA+CA,0BAAc,oBA/Cd;AAgDA,0BAAc,oBAhDd;AAiDA,0BAAc,qBAjDd;AAkDA,0BAAc,sBAlDd;AAmDA,0BAAc,wBAnDd;AAoDA,0BAAc,oBApDd;AAqDA,0BAAc,sBArDd;AAsDA,0BAAc,6BAtDd;AAuDA,0BAAc,+BAvDd;AAwDA,0BAAc,2BAxDd;AAyDA,0BAAc,0BAzDd;AA8DA,0BAAc,wBA9Dd;AA+DA,0BAAc,4BA/Dd;AAgEA,0BAAc,8BAhEd;AAiEA,0BAAc,gCAjEd;AAkEA,0BAAc,8BAlEd;AAmEA,0BAAc,2BAnEd;AAoEA,0BAAc,oBApEd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './MDXProvider';\nexport * from './routing';\nexport * from './boot';\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAQA,yBAA4B;AAC5B,0BAAc,0BATd;AAUA,0BAAc,uCAVd;AAWA,0BAAc,wBAXd;AAYA,0BAAc,qBAZd;AAcA,0BAAc,qBAdd;AAeA,0BAAc,oCAfd;AAgBA,0BAAc,gCAhBd;AAiBA,0BAAc,oBAjBd;AAoBA,0BAAc,6BApBd;AAuBA,6BAAwE;AACxE,0BAAc,mBAxBd;AAyBA,0BAAc,oBAzBd;AA0BA,0BAAc,4BA1Bd;AA2BA,0BAAc,qBA3Bd;AA4BA,0BAAc,yBA5Bd;AA6BA,0BAAc,0BA7Bd;AA8BA,0BAAc,wBA9Bd;AA+BA,0BAAc,4BA/Bd;AAgCA,0BAAc,qBAhCd;AAiCA,0BAAc,qBAjCd;AAkCA,0BAAc,wBAlCd;AAmCA,0BAAc,yBAnCd;AAoCA,0BAAc,sBApCd;AAqCA,0BAAc,kBArCd;AAsCA,0BAAc,kBAtCd;AAuCA,0BAAc,uBAvCd;AAwCA,0BAAc,mBAxCd;AAyCA,0BAAc,sBAzCd;AA0CA,0BAAc,sBA1Cd;AA2CA,0BAAc,kBA3Cd;AA4CA,0BAAc,0BA5Cd;AA6CA,0BAAc,kBA7Cd;AA8CA,0BAAc,yBA9Cd;AA+CA,0BAAc,iBA/Cd;AAgDA,0BAAc,oBAhDd;AAiDA,0BAAc,oBAjDd;AAkDA,0BAAc,qBAlDd;AAmDA,0BAAc,sBAnDd;AAoDA,0BAAc,wBApDd;AAqDA,0BAAc,oBArDd;AAsDA,0BAAc,sBAtDd;AAuDA,0BAAc,6BAvDd;AAwDA,0BAAc,+BAxDd;AAyDA,0BAAc,2BAzDd;AA0DA,0BAAc,0BA1Dd;AA+DA,0BAAc,wBA/Dd;AAgEA,0BAAc,4BAhEd;AAiEA,0BAAc,8BAjEd;AAkEA,0BAAc,gCAlEd;AAmEA,0BAAc,8BAnEd;AAoEA,0BAAc,2BApEd;AAqEA,0BAAc,oBArEd;","names":[]}

package/dist/index.d.cts

@@ -13,11 +13,12 @@ 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';
 export { ChromeState, getChromeState, onChromeStateChange, useChromeState } from './chromeState.cjs';
+export { Workspace, getWorkspace, onWorkspaceChange, useWorkspace } from './workspace.cjs';
 export { HostAttention, HostAttentionKind, NO_HOST_ATTENTION, getHostAttention, onHostAttentionChange, useHostAttention } from './hostAttention.cjs';
 export { getRegion, useRegion } from './region.cjs';
 export { Invite, MountQuery, MountRemoveReason, MountRule, RemovedMount, SandboxMount, SessionMount, SpaceError, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, importSettingsFromParent, listMyInvites, listPendingInvites, listSettingsApps, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeInvite, unmountSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.cjs';

package/dist/index.d.ts

@@ -13,11 +13,12 @@ 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';
 export { ChromeState, getChromeState, onChromeStateChange, useChromeState } from './chromeState.js';
+export { Workspace, getWorkspace, onWorkspaceChange, useWorkspace } from './workspace.js';
 export { HostAttention, HostAttentionKind, NO_HOST_ATTENTION, getHostAttention, onHostAttentionChange, useHostAttention } from './hostAttention.js';
 export { getRegion, useRegion } from './region.js';
 export { Invite, MountQuery, MountRemoveReason, MountRule, RemovedMount, SandboxMount, SessionMount, SpaceError, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, importSettingsFromParent, listMyInvites, listPendingInvites, listSettingsApps, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeInvite, unmountSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.js';

package/dist/index.js

@@ -20,6 +20,7 @@ export * from "./editorContext";
 export * from "./editor";
 export * from "./formFactor";
 export * from "./chromeState";
+export * from "./workspace";
 export * from "./hostAttention";
 export * from "./region";
 export * from "./mounts";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './MDXProvider';\nexport * from './routing';\nexport * from './boot';\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,SAAS,4BAA4B,mCAAmC;AACxE,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './MDXProvider';\nexport * from './routing';\nexport * from './boot';\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,SAAS,4BAA4B,mCAAmC;AACxE,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

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.57.4";
+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.57.4';\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.57.4";
+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.57.4";
+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.57.4";
+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.57.4';\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/dist/workspace.cjs

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var workspace_exports = {};
+__export(workspace_exports, {
+  getWorkspace: () => getWorkspace,
+  onWorkspaceChange: () => onWorkspaceChange,
+  useWorkspace: () => useWorkspace
+});
+module.exports = __toCommonJS(workspace_exports);
+var import_pushChannel = require("./pushChannel");
+var import_protocol = require("./generated/protocol");
+const DEFAULT_WORKSPACE = null;
+const isWorkspace = (v) => {
+  const w = v;
+  return !!w && typeof w === "object" && typeof w.provider === "string" && typeof w.namespace === "string" && typeof w.repository === "string" && typeof w.ref === "string" && typeof w.label === "string";
+};
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: import_protocol.WORKSPACE,
+  requestType: import_protocol.REQUEST_WORKSPACE,
+  initial: DEFAULT_WORKSPACE,
+  parse: (msg) => {
+    if (msg.workspace === null) return null;
+    if (!isWorkspace(msg.workspace)) return void 0;
+    const { provider, namespace, repository, ref, label } = msg.workspace;
+    return { provider, namespace, repository, ref, label };
+  }
+});
+const getWorkspace = () => channel.get();
+const onWorkspaceChange = (listener) => channel.onChange(listener);
+const useWorkspace = () => channel.use();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getWorkspace,
+  onWorkspaceChange,
+  useWorkspace
+});
+//# sourceMappingURL=workspace.cjs.map

package/dist/workspace.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { WORKSPACE, REQUEST_WORKSPACE } from './generated/protocol';\n\n/**\n * Which project the immediately.run workbench currently has open — the repository\n * the user is editing, not your app's own repository. `null` when your app is not\n * running inside an editing session at all (a standalone full-tab route, a task\n * overlay): that is a real answer, not a failure, and code here must handle it.\n *\n * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is\n * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`\n * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:\n * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.\n *\n * Baseline capability `workspace:read` — every app may read it. It discloses\n * nothing that is not already in the session URL your app can read from\n * {@link onUrlChange} when it drives the host route; this channel exists for the\n * apps that *don't* — a self-routed panel keeps its own route, never receives\n * `urlchange`, and would otherwise have no way to learn which project it is in.\n *\n * There is deliberately no counterpart that lets an app *change* the workspace:\n * navigating the workbench stays a host action under the ordinary consent.\n *\n * ```ts\n * import { useWorkspace } from '@immediately-run/sdk';\n *\n * const workspace = useWorkspace();\n * // Scope your app's stored data to the project it belongs to.\n * const scope = workspace?.label ?? null;\n * ```\n */\nexport interface Workspace {\n  /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */\n  provider: string;\n  /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */\n  namespace: string;\n  /** Repository/project segment. */\n  repository: string;\n  /** The branch, tag, or ref-shaped segment of the session. */\n  ref: string;\n  /**\n   * The session's display identity, `` `${namespace}/${repository}` `` — e.g.\n   * `neumark-family/recipes`.\n   *\n   * This is the string to key durable per-project data on. It is the SAME value the\n   * host labels the working-tree mount with, so an app that already scopes by that\n   * mount's label needs no migration to move onto this channel.\n   */\n  label: string;\n}\n\n/**\n * Assumed before the host reports — and the value that stands forever on a host too\n * old to push this channel. `null` means \"no project here\", which is also the honest\n * answer outside an editing session, so an app written against it degrades to\n * unscoped rather than to wrong.\n */\nconst DEFAULT_WORKSPACE: Workspace | null = null;\n\nconst isWorkspace = (v: unknown): v is Workspace => {\n  const w = v as Partial<Workspace> | null;\n  return (\n    !!w &&\n    typeof w === 'object' &&\n    typeof w.provider === 'string' &&\n    typeof w.namespace === 'string' &&\n    typeof w.repository === 'string' &&\n    typeof w.ref === 'string' &&\n    typeof w.label === 'string'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `workspace` and\n// answers `request-workspace` (wire format: site-main channelBridge.ts).\n//\n// `parse` must distinguish the host SAYING `null` from a message it cannot read.\n// `undefined` means \"not a value for this channel\" (createPushChannel ignores it and\n// keeps the last known workspace), while `null` is the host reporting \"no session\"\n// and MUST land — otherwise a frame that navigates out of a session would keep\n// reporting the project it used to be in.\n//\n// It REBUILDS the value field by field rather than passing the host's object through.\n// This channel is baseline-readable by every app, so \"it carries only the session's\n// coordinates\" has to be a property of this code, not of the host's good manners: a\n// host that pushed a token or a user id alongside them would otherwise get it into\n// app-visible memory by reference.\nconst channel = createPushChannel<Workspace | null>({\n  pushType: WORKSPACE,\n  requestType: REQUEST_WORKSPACE,\n  initial: DEFAULT_WORKSPACE,\n  parse: (msg) => {\n    if (msg.workspace === null) return null;\n    if (!isWorkspace(msg.workspace)) return undefined;\n    const { provider, namespace, repository, ref, label } = msg.workspace;\n    return { provider, namespace, repository, ref, label };\n  },\n});\n\n/** Returns the current workspace, or `null` outside an editing session. */\nexport const getWorkspace = (): Workspace | null => channel.get();\n\n/**\n * Subscribe to workspace changes. The listener is invoked immediately with the\n * current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onWorkspaceChange = (listener: (workspace: Workspace | null) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current workspace, re-rendering on change. */\nexport const useWorkspace = (): Workspace | null => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAClC,sBAA6C;AAwD7C,MAAM,oBAAsC;AAE5C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,KACF,OAAO,MAAM,YACb,OAAO,EAAE,aAAa,YACtB,OAAO,EAAE,cAAc,YACvB,OAAO,EAAE,eAAe,YACxB,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,UAAU;AAEvB;AAgBA,MAAM,cAAU,sCAAoC;AAAA,EAClD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AACd,QAAI,IAAI,cAAc,KAAM,QAAO;AACnC,QAAI,CAAC,YAAY,IAAI,SAAS,EAAG,QAAO;AACxC,UAAM,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM,IAAI,IAAI;AAC5D,WAAO,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM;AAAA,EACvD;AACF,CAAC;AAGM,MAAM,eAAe,MAAwB,QAAQ,IAAI;AAMzD,MAAM,oBAAoB,CAAC,aAChC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,eAAe,MAAwB,QAAQ,IAAI;","names":[]}

package/dist/workspace.d.cts

@@ -0,0 +1,58 @@
+/**
+ * Which project the immediately.run workbench currently has open — the repository
+ * the user is editing, not your app's own repository. `null` when your app is not
+ * running inside an editing session at all (a standalone full-tab route, a task
+ * overlay): that is a real answer, not a failure, and code here must handle it.
+ *
+ * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is
+ * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`
+ * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:
+ * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.
+ *
+ * Baseline capability `workspace:read` — every app may read it. It discloses
+ * nothing that is not already in the session URL your app can read from
+ * {@link onUrlChange} when it drives the host route; this channel exists for the
+ * apps that *don't* — a self-routed panel keeps its own route, never receives
+ * `urlchange`, and would otherwise have no way to learn which project it is in.
+ *
+ * There is deliberately no counterpart that lets an app *change* the workspace:
+ * navigating the workbench stays a host action under the ordinary consent.
+ *
+ * ```ts
+ * import { useWorkspace } from '@immediately-run/sdk';
+ *
+ * const workspace = useWorkspace();
+ * // Scope your app's stored data to the project it belongs to.
+ * const scope = workspace?.label ?? null;
+ * ```
+ */
+interface Workspace {
+    /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */
+    provider: string;
+    /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */
+    namespace: string;
+    /** Repository/project segment. */
+    repository: string;
+    /** The branch, tag, or ref-shaped segment of the session. */
+    ref: string;
+    /**
+     * The session's display identity, `` `${namespace}/${repository}` `` — e.g.
+     * `neumark-family/recipes`.
+     *
+     * This is the string to key durable per-project data on. It is the SAME value the
+     * host labels the working-tree mount with, so an app that already scopes by that
+     * mount's label needs no migration to move onto this channel.
+     */
+    label: string;
+}
+/** Returns the current workspace, or `null` outside an editing session. */
+declare const getWorkspace: () => Workspace | null;
+/**
+ * Subscribe to workspace changes. The listener is invoked immediately with the
+ * current value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onWorkspaceChange: (listener: (workspace: Workspace | null) => void) => (() => void);
+/** React hook returning the current workspace, re-rendering on change. */
+declare const useWorkspace: () => Workspace | null;
+
+export { type Workspace, getWorkspace, onWorkspaceChange, useWorkspace };

package/dist/workspace.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which project the immediately.run workbench currently has open — the repository
+ * the user is editing, not your app's own repository. `null` when your app is not
+ * running inside an editing session at all (a standalone full-tab route, a task
+ * overlay): that is a real answer, not a failure, and code here must handle it.
+ *
+ * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is
+ * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`
+ * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:
+ * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.
+ *
+ * Baseline capability `workspace:read` — every app may read it. It discloses
+ * nothing that is not already in the session URL your app can read from
+ * {@link onUrlChange} when it drives the host route; this channel exists for the
+ * apps that *don't* — a self-routed panel keeps its own route, never receives
+ * `urlchange`, and would otherwise have no way to learn which project it is in.
+ *
+ * There is deliberately no counterpart that lets an app *change* the workspace:
+ * navigating the workbench stays a host action under the ordinary consent.
+ *
+ * ```ts
+ * import { useWorkspace } from '@immediately-run/sdk';
+ *
+ * const workspace = useWorkspace();
+ * // Scope your app's stored data to the project it belongs to.
+ * const scope = workspace?.label ?? null;
+ * ```
+ */
+interface Workspace {
+    /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */
+    provider: string;
+    /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */
+    namespace: string;
+    /** Repository/project segment. */
+    repository: string;
+    /** The branch, tag, or ref-shaped segment of the session. */
+    ref: string;
+    /**
+     * The session's display identity, `` `${namespace}/${repository}` `` — e.g.
+     * `neumark-family/recipes`.
+     *
+     * This is the string to key durable per-project data on. It is the SAME value the
+     * host labels the working-tree mount with, so an app that already scopes by that
+     * mount's label needs no migration to move onto this channel.
+     */
+    label: string;
+}
+/** Returns the current workspace, or `null` outside an editing session. */
+declare const getWorkspace: () => Workspace | null;
+/**
+ * Subscribe to workspace changes. The listener is invoked immediately with the
+ * current value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onWorkspaceChange: (listener: (workspace: Workspace | null) => void) => (() => void);
+/** React hook returning the current workspace, re-rendering on change. */
+declare const useWorkspace: () => Workspace | null;
+
+export { type Workspace, getWorkspace, onWorkspaceChange, useWorkspace };

package/dist/workspace.js

@@ -0,0 +1,28 @@
+import "./chunk-VHAA22YE.js";
+import { createPushChannel } from "./pushChannel";
+import { WORKSPACE, REQUEST_WORKSPACE } from "./generated/protocol";
+const DEFAULT_WORKSPACE = null;
+const isWorkspace = (v) => {
+  const w = v;
+  return !!w && typeof w === "object" && typeof w.provider === "string" && typeof w.namespace === "string" && typeof w.repository === "string" && typeof w.ref === "string" && typeof w.label === "string";
+};
+const channel = createPushChannel({
+  pushType: WORKSPACE,
+  requestType: REQUEST_WORKSPACE,
+  initial: DEFAULT_WORKSPACE,
+  parse: (msg) => {
+    if (msg.workspace === null) return null;
+    if (!isWorkspace(msg.workspace)) return void 0;
+    const { provider, namespace, repository, ref, label } = msg.workspace;
+    return { provider, namespace, repository, ref, label };
+  }
+});
+const getWorkspace = () => channel.get();
+const onWorkspaceChange = (listener) => channel.onChange(listener);
+const useWorkspace = () => channel.use();
+export {
+  getWorkspace,
+  onWorkspaceChange,
+  useWorkspace
+};
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\nimport { WORKSPACE, REQUEST_WORKSPACE } from './generated/protocol';\n\n/**\n * Which project the immediately.run workbench currently has open — the repository\n * the user is editing, not your app's own repository. `null` when your app is not\n * running inside an editing session at all (a standalone full-tab route, a task\n * overlay): that is a real answer, not a failure, and code here must handle it.\n *\n * ⚠ **`namespace` is not necessarily a GitHub owner.** A `local` session is\n * well-formed but not GitHub-shaped — `/edit/local/my-app-3fa9c2d1/my-app/live`\n * reads back as `{ provider: 'local', namespace: 'my-app-3fa9c2d1', repository:\n * 'my-app', ref: 'live' }`. Branch on `provider` before rendering a GitHub URL.\n *\n * Baseline capability `workspace:read` — every app may read it. It discloses\n * nothing that is not already in the session URL your app can read from\n * {@link onUrlChange} when it drives the host route; this channel exists for the\n * apps that *don't* — a self-routed panel keeps its own route, never receives\n * `urlchange`, and would otherwise have no way to learn which project it is in.\n *\n * There is deliberately no counterpart that lets an app *change* the workspace:\n * navigating the workbench stays a host action under the ordinary consent.\n *\n * ```ts\n * import { useWorkspace } from '@immediately-run/sdk';\n *\n * const workspace = useWorkspace();\n * // Scope your app's stored data to the project it belongs to.\n * const scope = workspace?.label ?? null;\n * ```\n */\nexport interface Workspace {\n  /** Loader provider — `'github'`, `'local'`, … Branch on this, never assume. */\n  provider: string;\n  /** Owner/namespace segment. See the warning above: NOT always a GitHub owner. */\n  namespace: string;\n  /** Repository/project segment. */\n  repository: string;\n  /** The branch, tag, or ref-shaped segment of the session. */\n  ref: string;\n  /**\n   * The session's display identity, `` `${namespace}/${repository}` `` — e.g.\n   * `neumark-family/recipes`.\n   *\n   * This is the string to key durable per-project data on. It is the SAME value the\n   * host labels the working-tree mount with, so an app that already scopes by that\n   * mount's label needs no migration to move onto this channel.\n   */\n  label: string;\n}\n\n/**\n * Assumed before the host reports — and the value that stands forever on a host too\n * old to push this channel. `null` means \"no project here\", which is also the honest\n * answer outside an editing session, so an app written against it degrades to\n * unscoped rather than to wrong.\n */\nconst DEFAULT_WORKSPACE: Workspace | null = null;\n\nconst isWorkspace = (v: unknown): v is Workspace => {\n  const w = v as Partial<Workspace> | null;\n  return (\n    !!w &&\n    typeof w === 'object' &&\n    typeof w.provider === 'string' &&\n    typeof w.namespace === 'string' &&\n    typeof w.repository === 'string' &&\n    typeof w.ref === 'string' &&\n    typeof w.label === 'string'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `workspace` and\n// answers `request-workspace` (wire format: site-main channelBridge.ts).\n//\n// `parse` must distinguish the host SAYING `null` from a message it cannot read.\n// `undefined` means \"not a value for this channel\" (createPushChannel ignores it and\n// keeps the last known workspace), while `null` is the host reporting \"no session\"\n// and MUST land — otherwise a frame that navigates out of a session would keep\n// reporting the project it used to be in.\n//\n// It REBUILDS the value field by field rather than passing the host's object through.\n// This channel is baseline-readable by every app, so \"it carries only the session's\n// coordinates\" has to be a property of this code, not of the host's good manners: a\n// host that pushed a token or a user id alongside them would otherwise get it into\n// app-visible memory by reference.\nconst channel = createPushChannel<Workspace | null>({\n  pushType: WORKSPACE,\n  requestType: REQUEST_WORKSPACE,\n  initial: DEFAULT_WORKSPACE,\n  parse: (msg) => {\n    if (msg.workspace === null) return null;\n    if (!isWorkspace(msg.workspace)) return undefined;\n    const { provider, namespace, repository, ref, label } = msg.workspace;\n    return { provider, namespace, repository, ref, label };\n  },\n});\n\n/** Returns the current workspace, or `null` outside an editing session. */\nexport const getWorkspace = (): Workspace | null => channel.get();\n\n/**\n * Subscribe to workspace changes. The listener is invoked immediately with the\n * current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onWorkspaceChange = (listener: (workspace: Workspace | null) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current workspace, re-rendering on change. */\nexport const useWorkspace = (): Workspace | null => channel.use();\n"],"mappings":";AAAA,SAAS,yBAAyB;AAClC,SAAS,WAAW,yBAAyB;AAwD7C,MAAM,oBAAsC;AAE5C,MAAM,cAAc,CAAC,MAA+B;AAClD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,KACF,OAAO,MAAM,YACb,OAAO,EAAE,aAAa,YACtB,OAAO,EAAE,cAAc,YACvB,OAAO,EAAE,eAAe,YACxB,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,UAAU;AAEvB;AAgBA,MAAM,UAAU,kBAAoC;AAAA,EAClD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AACd,QAAI,IAAI,cAAc,KAAM,QAAO;AACnC,QAAI,CAAC,YAAY,IAAI,SAAS,EAAG,QAAO;AACxC,UAAM,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM,IAAI,IAAI;AAC5D,WAAO,EAAE,UAAU,WAAW,YAAY,KAAK,MAAM;AAAA,EACvD;AACF,CAAC;AAGM,MAAM,eAAe,MAAwB,QAAQ,IAAI;AAMzD,MAAM,oBAAoB,CAAC,aAChC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,eAAe,MAAwB,QAAQ,IAAI;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.57.4",
+  "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.6",
+    "@immediately-run/sandbox-protocol": "0.8.2",
     "react-error-boundary": "^6.0.0"
   },
   "devDependencies": {