@adea-ai/ui 0.128.1 → 0.128.3

package/src/components/theme/theme-document-core.ts

@@ -0,0 +1,262 @@
+import {
+  applyAppearanceFontSettings,
+  normalizeAppearanceEditorFontSettings,
+} from '#lib/appearance-font-settings'
+import { terminalCssVariables } from '#lib/theme-css'
+import type { ThemeEngine } from '#lib/theme-engine'
+import type { EditorRolesMode, ThemeAppearance, ThemeVariant } from '#lib/themes'
+import { isCustomAccent } from '#lib/accent-roles'
+import { surfaceAlpha, type SurfaceState } from '#lib/theme-surface'
+import { resolvedDensity, type ThemeSelection } from './theme-state-core'
+
+/**
+ * The document half of the theme provider: the single writer of `<html>`.
+ *
+ * Written against the few members of an element it uses, so the rules can be tested
+ * on a stand-in and the provider's effect stays a one-line call.
+ *
+ * This is the engine-parameterised half: every question the catalogue answers goes
+ * through the {@link ThemeEngine} it is given, so it imports no catalogue code or data.
+ * `theme-document.ts` binds the full catalogue and keeps the signatures the eager
+ * provider and the tests have always used.
+ */
+export type ThemeRoot = Pick<
+  HTMLElement,
+  'classList' | 'dataset' | 'style' | 'removeAttribute' | 'setAttribute'
+>
+
+export type ThemeDocumentState = {
+  /** What the document shows: the committed selection, or a preview laid over it. */
+  selection: ThemeSelection
+  appearance: ThemeAppearance
+  variant: ThemeVariant
+  /**
+   * The variant whose terminal palette is pinned over the interface variant's.
+   * Absent, the terminal follows the interface theme.
+   */
+  terminalVariant?: ThemeVariant
+  /**
+   * The resolved surface axis. Absent, the axis is off: no attribute and no
+   * `--surface-alpha` is written, and any this writer wrote before is removed.
+   */
+  surface?: SurfaceState
+}
+
+export type ThemeDocumentOptions = {
+  /**
+   * Rewrites the custom properties just before they are written: the variant's
+   * roles with the accent laid over them. It sees every property of the pass and
+   * must return the full map; a name it drops is not written.
+   */
+  transformTokens?: (tokens: Record<string, string>) => Record<string, string>
+  /**
+   * The contrast an accent is held to against the variant's background. Absent, a
+   * preset is painted verbatim (the catalogue measured it for its own themes) and
+   * only a custom `#rrggbb` is held to the default floor of 3:1.
+   */
+  accentContrastFloor?: number
+  /**
+   * Where a catalogue variant's palette comes from. `inline` (the default) writes
+   * every role onto the root. `stylesheet` writes none for a catalogue variant,
+   * because the host loads a stylesheet that carries a `[data-theme]` block for it;
+   * a variant the catalogue does not hold (a host's imported theme) is still written
+   * inline, since no stylesheet can know it. The accent, the terminal pin, the
+   * surface alpha and the fonts are written the same in both.
+   *
+   * Switching from an imported variant back to a catalogue one removes what the
+   * imported one wrote, so nothing inline outlives it to beat the stylesheet.
+   */
+  palette?: 'inline' | 'stylesheet'
+  /**
+   * The `--editor-*` projection. `syntax` (the default) is the catalogue's quiet
+   * syntax roles, which is what `theme-variants.css` carries; `floor` holds every
+   * editor role to 4.5:1 on the canvas, as hex.
+   *
+   * With `palette: 'stylesheet'`, `floor` is the one palette write a catalogue
+   * variant still gets: the stylesheet is generated for the default projection, so
+   * the sixteen `--editor-*` properties are written inline over it. The rest of the
+   * palette stays in the stylesheet.
+   */
+  editorRoles?: EditorRolesMode
+}
+
+/**
+ * What a catalogue variant still writes inline when its palette is the stylesheet's:
+ * nothing, unless the editor projection is not the one the stylesheet was generated
+ * for.
+ */
+function stylesheetOverrides(
+  engine: ThemeEngine,
+  variant: ThemeVariant,
+  editorRoles: EditorRolesMode | undefined
+): Record<string, string> {
+  if (editorRoles !== 'floor') return {}
+  return Object.fromEntries(
+    Object.entries(engine.themeCssVariables(variant, { editor: 'floor' })).filter(([name]) =>
+      name.startsWith('--editor-')
+    )
+  )
+}
+
+/**
+ * The custom properties a state paints: the variant's roles, with the accent
+ * selection laid over them, the pinned terminal palette over that, the surface
+ * alpha, then `transformTokens`.
+ *
+ * The accent is applied *here* rather than left to the `[data-accent]` blocks in
+ * `theme.css`, because the properties are written inline and an inline declaration
+ * outranks every stylesheet selector however specific it is. The blocks still exist
+ * and are still correct — they are what styles the window before this runs — but
+ * they cannot win from here, so leaving the accent to them meant the attribute was
+ * set, the rules were present, and nothing changed on screen.
+ */
+export function themeDocumentTokensWith(
+  engine: ThemeEngine,
+  state: ThemeDocumentState,
+  options: ThemeDocumentOptions = {}
+): { tokens: Record<string, string>; accented: boolean } {
+  const fromStylesheet =
+    options.palette === 'stylesheet' && engine.isCatalogueVariant(state.variant)
+  const properties = fromStylesheet
+    ? stylesheetOverrides(engine, state.variant, options.editorRoles)
+    : { ...engine.themeCssVariables(state.variant, { editor: options.editorRoles }) }
+  const accent = engine.accentVariables(state.selection.accent, state.appearance, state.selection, {
+    background: state.variant.colors.background,
+    floor: options.accentContrastFloor,
+    variantId: state.variant.id,
+  })
+  if (accent) Object.assign(properties, accent)
+  // Written after the variant and the accent, so it wins over the interface
+  // variant's own terminal ramp (and over the stylesheet's, which it outranks as an
+  // inline declaration). Dropping the pin needs no removal of its own: the ramp is
+  // then rewritten by the variant, or swept back to the stylesheet.
+  if (state.terminalVariant) Object.assign(properties, terminalCssVariables(state.terminalVariant))
+  if (state.surface) properties['--surface-alpha'] = surfaceAlpha[state.surface.surface]
+  return {
+    tokens: options.transformTokens ? options.transformTokens(properties) : properties,
+    accented: accent !== undefined,
+  }
+}
+
+/**
+ * Write a state onto a root and report which custom properties it owns.
+ *
+ * Pass the previous call's return as `previous` and any palette property that pass
+ * wrote and this one does not is removed. For the catalogue the two sets are the
+ * same, so nothing is ever removed; it matters for a host variant that carries
+ * `tokens` the catalogue does not, which would otherwise stay inline, beating the
+ * stylesheet, after the user switched away from it.
+ */
+export function applyThemeToRootWith(
+  engine: ThemeEngine,
+  root: ThemeRoot,
+  state: ThemeDocumentState,
+  options: ThemeDocumentOptions = {},
+  previous?: ReadonlySet<string>
+): ReadonlySet<string> {
+  const { tokens, accented } = themeDocumentTokensWith(engine, state, options)
+
+  for (const [name, value] of Object.entries(tokens)) {
+    root.style.setProperty(name, value)
+  }
+  if (previous) {
+    for (const name of previous) {
+      if (!(name in tokens)) root.style.removeProperty(name)
+    }
+  }
+
+  root.classList.toggle('dark', state.appearance === 'dark')
+  root.dataset['theme'] = state.variant.id
+  root.dataset['appearance'] = state.appearance
+  root.style.colorScheme = state.appearance
+
+  // A custom colour has no stylesheet block to select, and its value is the
+  // attribute's worst possible content, so it is reported as `custom`.
+  if (!accented) root.removeAttribute('data-accent')
+  else
+    root.dataset['accent'] = isCustomAccent(state.selection.accent)
+      ? 'custom'
+      : state.selection.accent
+
+  // The surface axis is opt-in, so its absence removes rather than defaults: a host
+  // that never enables it keeps an `<html>` with neither attribute, and one that
+  // turns it off leaves nothing behind. (`--surface-alpha` is swept with the tokens.)
+  if (state.surface) {
+    root.dataset['surface'] = state.surface.surface
+    root.dataset['reduceTransparency'] = state.surface.reduceTransparencyActive ? 'true' : 'false'
+  } else {
+    root.removeAttribute('data-surface')
+    root.removeAttribute('data-reduce-transparency')
+  }
+
+  applyAppearanceFontSettings(
+    root,
+    normalizeAppearanceEditorFontSettings(state.selection.fonts, state.selection.font).settings
+  )
+
+  // Density is a pure token shift, so unlike the colour axes there is nothing to
+  // compute: the attribute selects a block in `theme.css`. It is applied here for
+  // the same reason as the others — this is the one place that knows what the
+  // current selection is, and it is the only writer of these attributes.
+  if (resolvedDensity(state.selection) === 'comfortable') root.removeAttribute('data-density')
+  else root.dataset['density'] = resolvedDensity(state.selection)
+
+  return new Set(Object.keys(tokens))
+}
+
+/** What {@link applyWithoutTransitions} needs of a document. */
+export type TransitionDocument = {
+  head: { appendChild(node: unknown): unknown }
+  createElement(tag: 'style'): {
+    textContent: string | null
+    offsetHeight?: number
+    remove(): void
+  }
+}
+
+/**
+ * Run `apply` with every CSS transition switched off for the frame that carries
+ * it, so a theme switch cannot animate page-wide.
+ *
+ * Without this, flipping the custom properties on `<html>` starts a transition on
+ * every element that declares one, and each fades from the old palette to the new
+ * over its own duration: a theme change that looks like a rendering fault. The
+ * rule is removed two frames later, after the browser has committed the new styles
+ * with transitions off, and `restore` runs it early (the provider calls it when it
+ * is disposed mid-switch).
+ *
+ * `schedule` is the frame source; it defaults to `requestAnimationFrame` and falls
+ * back to running at once where there is none, which leaves transitions on rather
+ * than off.
+ */
+export function applyWithoutTransitions(
+  doc: TransitionDocument,
+  apply: () => void,
+  schedule: (callback: () => void) => void = defaultSchedule
+): () => void {
+  const style = doc.createElement('style')
+  style.textContent = '*{transition:none !important}'
+  doc.head.appendChild(style)
+  // Reading a layout property forces the browser to commit the rule before the
+  // properties change; without it the two can be batched into one style recalc.
+  void style.offsetHeight
+  let removed = false
+  const restore = () => {
+    if (removed) return
+    removed = true
+    style.remove()
+  }
+  try {
+    apply()
+  } catch (error) {
+    restore()
+    throw error
+  }
+  schedule(() => schedule(restore))
+  return restore
+}
+
+function defaultSchedule(callback: () => void): void {
+  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(callback)
+  else callback()
+}

package/src/components/theme/theme-document.ts

@@ -1,149 +1,36 @@
+import { catalogueThemeEngine } from '#lib/theme-catalogue'
 import {
-  applyAppearanceFontSettings,
-  normalizeAppearanceEditorFontSettings,
-} from '#lib/appearance-font-settings'
-import {
-  accentVariables,
-  isCatalogueVariant,
-  terminalCssVariables,
-  themeCssVariables,
-  type EditorRolesMode,
-  type ThemeAppearance,
-  type ThemeVariant,
-} from '#lib/themes'
-import { isCustomAccent } from '#lib/accent-roles'
-import { surfaceAlpha, type SurfaceState } from '#lib/theme-surface'
-import { resolvedDensity, type ThemeSelection } from './theme-state'
-
-/**
- * The document half of the theme provider: the single writer of `<html>`.
- *
- * Written against the few members of an element it uses, so the rules can be tested
- * on a stand-in and the provider's effect stays a one-line call.
- */
-export type ThemeRoot = Pick<
-  HTMLElement,
-  'classList' | 'dataset' | 'style' | 'removeAttribute' | 'setAttribute'
->
-
-export type ThemeDocumentState = {
-  /** What the document shows: the committed selection, or a preview laid over it. */
-  selection: ThemeSelection
-  appearance: ThemeAppearance
-  variant: ThemeVariant
-  /**
-   * The variant whose terminal palette is pinned over the interface variant's.
-   * Absent, the terminal follows the interface theme.
-   */
-  terminalVariant?: ThemeVariant
-  /**
-   * The resolved surface axis. Absent, the axis is off: no attribute and no
-   * `--surface-alpha` is written, and any this writer wrote before is removed.
-   */
-  surface?: SurfaceState
-}
-
-export type ThemeDocumentOptions = {
-  /**
-   * Rewrites the custom properties just before they are written: the variant's
-   * roles with the accent laid over them. It sees every property of the pass and
-   * must return the full map; a name it drops is not written.
-   */
-  transformTokens?: (tokens: Record<string, string>) => Record<string, string>
-  /**
-   * The contrast an accent is held to against the variant's background. Absent, a
-   * preset is painted verbatim (the catalogue measured it for its own themes) and
-   * only a custom `#rrggbb` is held to the default floor of 3:1.
-   */
-  accentContrastFloor?: number
-  /**
-   * Where a catalogue variant's palette comes from. `inline` (the default) writes
-   * every role onto the root. `stylesheet` writes none for a catalogue variant,
-   * because the host loads a stylesheet that carries a `[data-theme]` block for it;
-   * a variant the catalogue does not hold (a host's imported theme) is still written
-   * inline, since no stylesheet can know it. The accent, the terminal pin, the
-   * surface alpha and the fonts are written the same in both.
-   *
-   * Switching from an imported variant back to a catalogue one removes what the
-   * imported one wrote, so nothing inline outlives it to beat the stylesheet.
-   */
-  palette?: 'inline' | 'stylesheet'
-  /**
-   * The `--editor-*` projection. `syntax` (the default) is the catalogue's quiet
-   * syntax roles, which is what `theme-variants.css` carries; `floor` holds every
-   * editor role to 4.5:1 on the canvas, as hex.
-   *
-   * With `palette: 'stylesheet'`, `floor` is the one palette write a catalogue
-   * variant still gets: the stylesheet is generated for the default projection, so
-   * the sixteen `--editor-*` properties are written inline over it. The rest of the
-   * palette stays in the stylesheet.
-   */
-  editorRoles?: EditorRolesMode
-}
+  applyThemeToRootWith,
+  themeDocumentTokensWith,
+  type ThemeDocumentOptions,
+  type ThemeDocumentState,
+  type ThemeRoot,
+} from './theme-document-core'
+
+export {
+  applyWithoutTransitions,
+  type ThemeDocumentOptions,
+  type ThemeDocumentState,
+  type ThemeRoot,
+  type TransitionDocument,
+} from './theme-document-core'
 
 /**
- * What a catalogue variant still writes inline when its palette is the stylesheet's:
- * nothing, unless the editor projection is not the one the stylesheet was generated
- * for.
- */
-function stylesheetOverrides(
-  variant: ThemeVariant,
-  editorRoles: EditorRolesMode | undefined
-): Record<string, string> {
-  if (editorRoles !== 'floor') return {}
-  return Object.fromEntries(
-    Object.entries(themeCssVariables(variant, { editor: 'floor' })).filter(([name]) =>
-      name.startsWith('--editor-')
-    )
-  )
-}
-
-/**
- * The custom properties a state paints: the variant's roles, with the accent
- * selection laid over them, the pinned terminal palette over that, the surface
- * alpha, then `transformTokens`.
- *
- * The accent is applied *here* rather than left to the `[data-accent]` blocks in
- * `theme.css`, because the properties are written inline and an inline declaration
- * outranks every stylesheet selector however specific it is. The blocks still exist
- * and are still correct — they are what styles the window before this runs — but
- * they cannot win from here, so leaving the accent to them meant the attribute was
- * set, the rules were present, and nothing changed on screen.
+ * The custom properties a state paints, resolved against the whole catalogue: the
+ * variant's roles, with the accent selection laid over them, the pinned terminal
+ * palette over that, the surface alpha, then `transformTokens`. See
+ * {@link themeDocumentTokensWith} for the rules.
  */
 export function themeDocumentTokens(
   state: ThemeDocumentState,
   options: ThemeDocumentOptions = {}
 ): { tokens: Record<string, string>; accented: boolean } {
-  const fromStylesheet = options.palette === 'stylesheet' && isCatalogueVariant(state.variant)
-  const properties = fromStylesheet
-    ? stylesheetOverrides(state.variant, options.editorRoles)
-    : { ...themeCssVariables(state.variant, { editor: options.editorRoles }) }
-  const accent = accentVariables(state.selection.accent, state.appearance, state.selection, {
-    background: state.variant.colors.background,
-    floor: options.accentContrastFloor,
-    variantId: state.variant.id,
-  })
-  if (accent) Object.assign(properties, accent)
-  // Written after the variant and the accent, so it wins over the interface
-  // variant's own terminal ramp (and over the stylesheet's, which it outranks as an
-  // inline declaration). Dropping the pin needs no removal of its own: the ramp is
-  // then rewritten by the variant, or swept back to the stylesheet.
-  if (state.terminalVariant) Object.assign(properties, terminalCssVariables(state.terminalVariant))
-  if (state.surface) properties['--surface-alpha'] = surfaceAlpha[state.surface.surface]
-  return {
-    tokens: options.transformTokens ? options.transformTokens(properties) : properties,
-    accented: accent !== undefined,
-  }
+  return themeDocumentTokensWith(catalogueThemeEngine, state, options)
 }
 
 /**
- * Write a state onto a root and report which custom properties it owns.
- *
- * Pass the previous call's return as `previous` and any palette property that pass
- * wrote and this one does not is removed. For the catalogue the two sets are the
- * same, so nothing is ever removed; it matters for a host variant that carries
- * `tokens` the catalogue does not, which would otherwise stay inline, beating the
- * stylesheet, after the user switched away from it.
+ * Write a state onto a root and report which custom properties it owns, resolved
+ * against the whole catalogue. See {@link applyThemeToRootWith} for the rules.
  */
 export function applyThemeToRoot(
   root: ThemeRoot,
@@ -151,109 +38,5 @@ export function applyThemeToRoot(
   options: ThemeDocumentOptions = {},
   previous?: ReadonlySet<string>
 ): ReadonlySet<string> {
-  const { tokens, accented } = themeDocumentTokens(state, options)
-
-  for (const [name, value] of Object.entries(tokens)) {
-    root.style.setProperty(name, value)
-  }
-  if (previous) {
-    for (const name of previous) {
-      if (!(name in tokens)) root.style.removeProperty(name)
-    }
-  }
-
-  root.classList.toggle('dark', state.appearance === 'dark')
-  root.dataset['theme'] = state.variant.id
-  root.dataset['appearance'] = state.appearance
-  root.style.colorScheme = state.appearance
-
-  // A custom colour has no stylesheet block to select, and its value is the
-  // attribute's worst possible content, so it is reported as `custom`.
-  if (!accented) root.removeAttribute('data-accent')
-  else
-    root.dataset['accent'] = isCustomAccent(state.selection.accent)
-      ? 'custom'
-      : state.selection.accent
-
-  // The surface axis is opt-in, so its absence removes rather than defaults: a host
-  // that never enables it keeps an `<html>` with neither attribute, and one that
-  // turns it off leaves nothing behind. (`--surface-alpha` is swept with the tokens.)
-  if (state.surface) {
-    root.dataset['surface'] = state.surface.surface
-    root.dataset['reduceTransparency'] = state.surface.reduceTransparencyActive ? 'true' : 'false'
-  } else {
-    root.removeAttribute('data-surface')
-    root.removeAttribute('data-reduce-transparency')
-  }
-
-  applyAppearanceFontSettings(
-    root,
-    normalizeAppearanceEditorFontSettings(state.selection.fonts, state.selection.font).settings
-  )
-
-  // Density is a pure token shift, so unlike the colour axes there is nothing to
-  // compute: the attribute selects a block in `theme.css`. It is applied here for
-  // the same reason as the others — this is the one place that knows what the
-  // current selection is, and it is the only writer of these attributes.
-  if (resolvedDensity(state.selection) === 'comfortable') root.removeAttribute('data-density')
-  else root.dataset['density'] = resolvedDensity(state.selection)
-
-  return new Set(Object.keys(tokens))
-}
-
-/** What {@link applyWithoutTransitions} needs of a document. */
-export type TransitionDocument = {
-  head: { appendChild(node: unknown): unknown }
-  createElement(tag: 'style'): {
-    textContent: string | null
-    offsetHeight?: number
-    remove(): void
-  }
-}
-
-/**
- * Run `apply` with every CSS transition switched off for the frame that carries
- * it, so a theme switch cannot animate page-wide.
- *
- * Without this, flipping the custom properties on `<html>` starts a transition on
- * every element that declares one, and each fades from the old palette to the new
- * over its own duration: a theme change that looks like a rendering fault. The
- * rule is removed two frames later, after the browser has committed the new styles
- * with transitions off, and `restore` runs it early (the provider calls it when it
- * is disposed mid-switch).
- *
- * `schedule` is the frame source; it defaults to `requestAnimationFrame` and falls
- * back to running at once where there is none, which leaves transitions on rather
- * than off.
- */
-export function applyWithoutTransitions(
-  doc: TransitionDocument,
-  apply: () => void,
-  schedule: (callback: () => void) => void = defaultSchedule
-): () => void {
-  const style = doc.createElement('style')
-  style.textContent = '*{transition:none !important}'
-  doc.head.appendChild(style)
-  // Reading a layout property forces the browser to commit the rule before the
-  // properties change; without it the two can be batched into one style recalc.
-  void style.offsetHeight
-  let removed = false
-  const restore = () => {
-    if (removed) return
-    removed = true
-    style.remove()
-  }
-  try {
-    apply()
-  } catch (error) {
-    restore()
-    throw error
-  }
-  schedule(() => schedule(restore))
-  return restore
-}
-
-function defaultSchedule(callback: () => void): void {
-  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(callback)
-  else callback()
+  return applyThemeToRootWith(catalogueThemeEngine, root, state, options, previous)
 }

package/src/components/theme/theme-persistence.ts

@@ -1,7 +1,12 @@
 import { normalizeCustomAccent } from '#lib/accent-roles'
-import { accentPresets } from '#lib/tokens'
+import { accentPresets } from '#lib/accent-presets'
 import { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'
-import { defaultDarkThemeId, defaultLightThemeId, isThemeAccentId, themeById } from '#lib/themes'
+import { isThemeAccentId } from '#lib/theme-accents'
+import {
+  catalogueThemeAppearance,
+  defaultDarkThemeId,
+  defaultLightThemeId,
+} from '#lib/theme-defaults'
 import { normalizeSurface } from '#lib/theme-surface'
 import {
   defaultPreferenceStorage,
@@ -11,7 +16,7 @@ import {
   writeVersionedRecord,
   type PreferenceStorage,
 } from '#lib/preference-store'
-import { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state'
+import { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state-core'
 
 /**
  * Where a selection is kept between sessions.
@@ -51,7 +56,10 @@ function preferenceStore(): Storage | undefined {
   return typeof localStorage === 'undefined' ? undefined : localStorage
 }
 
-/** The stored preference, validated against the catalogue. */
+/**
+ * The stored preference, validated against the catalogue's ids (`theme-defaults`), so
+ * reading it never loads the catalogue.
+ */
 function readSelection(storageKey: string): ThemeSelection {
   try {
     const raw = preferenceStore()?.getItem(storageKey)
@@ -68,11 +76,11 @@ function readSelection(storageKey: string): ThemeSelection {
       // An unknown id would leave the document with no theme at all, so a stale
       // preference from an older catalogue falls back rather than applying nothing.
       lightThemeId:
-        themeById(parsed.lightThemeId ?? '')?.appearance === 'light'
+        catalogueThemeAppearance(parsed.lightThemeId ?? '') === 'light'
           ? (parsed.lightThemeId as string)
           : defaultLightThemeId,
       darkThemeId:
-        themeById(parsed.darkThemeId ?? '')?.appearance === 'dark'
+        catalogueThemeAppearance(parsed.darkThemeId ?? '') === 'dark'
           ? (parsed.darkThemeId as string)
           : defaultDarkThemeId,
       // A theme accent is kept whenever it names a slot, even one the stored pair

package/src/components/theme/theme-provider-core.tsx

@@ -0,0 +1,40 @@
+import { themeContext } from './theme-context'
+import {
+  createThemeContextValue,
+  type ThemeCatalogueSource,
+  type ThemeProviderProps,
+} from './theme-provider-value'
+
+export type { ThemeCatalogueSource, ThemeProviderProps } from './theme-provider-value'
+export {
+  createVersionedPersistence,
+  localStoragePersistence,
+  type ThemePersistence,
+  type ThemeStorageSchema,
+  type VersionedCodec,
+  type VersionedPersistenceOptions,
+} from './theme-persistence'
+export { useOptionalTheme, useTheme } from './theme-context'
+export type { ThemeSurface } from '#lib/theme-surface'
+export type { EditorRolesMode } from '#lib/themes'
+export { inlineScriptLiteral, themeScript, type ThemeScriptOptions } from './theme-script'
+export {
+  defaultThemeSelection,
+  resolvedDensity,
+  type ThemeContextValue,
+  type ThemeDensity,
+  type ThemeSelection,
+} from './theme-state-core'
+
+/**
+ * The provider, parameterised by where its catalogue comes from.
+ *
+ * `ThemeProvider` (`theme-provider.tsx`) and the lazy `ThemeProvider`
+ * (`theme-provider-lazy.tsx`) are this component with a source; the work is
+ * `createThemeContextValue`. It imports no catalogue code or data.
+ */
+export function ThemeProviderCore(props: ThemeProviderProps & { catalogue: ThemeCatalogueSource }) {
+  const value = createThemeContextValue(props)
+  const Context = themeContext()
+  return <Context.Provider value={value}>{props.children}</Context.Provider>
+}

package/src/components/theme/theme-provider-lazy.tsx

@@ -0,0 +1,34 @@
+import { createLazyCatalogue } from './theme-catalogue-source'
+import { ThemeProviderCore, type ThemeProviderProps } from './theme-provider-core'
+
+export { loadThemeCatalogue } from './theme-catalogue-source'
+
+/**
+ * ThemeProvider, with the theme catalogue out of the start-up path.
+ *
+ * Same props, same context and same behaviour as `ThemeProvider` for everything the
+ * shipped default pair covers: the default light and dark themes, a host's own
+ * `themes`, every accent preset and custom colour, the surface axis, fonts and
+ * density. Only the 32 other catalogue themes are not in the start-up chunk. The first
+ * time the selection (or a preview) names one, or a theme-derived `ansi-*` accent over
+ * such a pair, this provider imports the catalogue in a chunk of its own:
+ *
+ *   - until it arrives the document keeps what is on it (set before first paint by
+ *     `themeScript`, painted by the stylesheet under `palette="stylesheet"`), and
+ *     `variant()` is the default of the appearance;
+ *   - when it arrives the provider re-resolves and paints the stored theme, and
+ *     `useTheme().catalogueReady()` turns true;
+ *   - a preview of a theme that has not loaded starts the load and shows when it ends.
+ *
+ * Pair it with `palette="stylesheet"` and `themeScript`: inline palettes of catalogue
+ * themes need the catalogue to compute, so under the default `inline` palette every
+ * stored theme but the defaults waits for the import.
+ *
+ * `useTheme().themes` and `allThemes()` list only the default pair until
+ * `catalogueReady()`; a picker calls `useTheme().loadCatalogue()` when it mounts.
+ */
+export function ThemeProvider(props: ThemeProviderProps) {
+  // Hoisted: a JSX prop expression is re-evaluated on every read, and this source owns signals.
+  const catalogue = createLazyCatalogue()
+  return <ThemeProviderCore {...props} catalogue={catalogue} />
+}