@adea-ai/ui 0.128.2 → 0.128.3

package/dist/components/theme/theme-persistence.js.map

@@ -1 +1 @@
-{"version":3,"file":"theme-persistence.js","names":[],"sources":["../../../src/components/theme/theme-persistence.ts"],"sourcesContent":["import { normalizeCustomAccent } from '#lib/accent-roles'\nimport { accentPresets } from '#lib/tokens'\nimport { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'\nimport { defaultDarkThemeId, defaultLightThemeId, isThemeAccentId, themeById } from '#lib/themes'\nimport { normalizeSurface } from '#lib/theme-surface'\nimport {\n  defaultPreferenceStorage,\n  readLegacyValue,\n  readVersionedRecord,\n  recoveryKeyFor,\n  writeVersionedRecord,\n  type PreferenceStorage,\n} from '#lib/preference-store'\nimport { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state'\n\n/**\n * Where a selection is kept between sessions.\n *\n * The provider never touches storage itself; it asks a `ThemePersistence`. The\n * default is {@link localStoragePersistence}, which is what the provider always did.\n * A host that stores the preference in a different shape, under a versioned\n * envelope, or somewhere that is not `localStorage` supplies its own and the\n * resolution and application rules stay the shared ones.\n *\n * The contract is deliberately narrow, so that an implementation cannot make the\n * provider less safe than it was:\n *\n *   - `read` is synchronous and runs once, when the provider is created. It may\n *     repair or quarantine what it finds, and it must not throw: the provider\n *     treats a throw as \"nothing stored\" and starts from the defaults.\n *   - `write` runs only from `setSelection`. Never on mount, never from `preview`,\n *     never as a side effect of reading, so the first write to a store is always a\n *     user's decision. A throw is swallowed, because a full or blocked store must\n *     not break the switch.\n */\nexport type ThemePersistence = {\n  read(): Partial<ThemeSelection> | undefined\n  write(next: ThemeSelection): void\n}\n\n/**\n * The preference store, or nothing.\n *\n * Only ever called inside a `try`: where storage is blocked — a sandboxed iframe, a\n * privacy mode, a denied site-data permission — merely *reading* the `localStorage`\n * global throws (\"Access is denied\", `SecurityError`), so even the `typeof` guard\n * has to sit inside the `try` rather than in front of it. Without a store the\n * preference lives only in the provider's signal for the session.\n */\nfunction preferenceStore(): Storage | undefined {\n  return typeof localStorage === 'undefined' ? undefined : localStorage\n}\n\n/** The stored preference, validated against the catalogue. */\nfunction readSelection(storageKey: string): ThemeSelection {\n  try {\n    const raw = preferenceStore()?.getItem(storageKey)\n    if (!raw) return defaultThemeSelection\n    const parsed = JSON.parse(raw) as Partial<ThemeSelection>\n    const fonts = normalizeAppearanceEditorFontSettings(parsed.fonts, parsed.font).settings\n    return {\n      appearance:\n        parsed.appearance === 'light' ||\n        parsed.appearance === 'dark' ||\n        parsed.appearance === 'system'\n          ? parsed.appearance\n          : defaultThemeSelection.appearance,\n      // An unknown id would leave the document with no theme at all, so a stale\n      // preference from an older catalogue falls back rather than applying nothing.\n      lightThemeId:\n        themeById(parsed.lightThemeId ?? '')?.appearance === 'light'\n          ? (parsed.lightThemeId as string)\n          : defaultLightThemeId,\n      darkThemeId:\n        themeById(parsed.darkThemeId ?? '')?.appearance === 'dark'\n          ? (parsed.darkThemeId as string)\n          : defaultDarkThemeId,\n      // A theme accent is kept whenever it names a slot, even one the stored pair\n      // cannot offer: the id is role-shaped so it survives a theme switch, and an\n      // unoffered slot already resolves to the theme's own primary when applied. A\n      // custom `#rrggbb` is kept in its one stored spelling; its readability is\n      // settled when it is painted, not when it is read.\n      accent:\n        typeof parsed.accent === 'string' &&\n        (accentPresets.some((preset) => preset.id === parsed.accent) ||\n          isThemeAccentId(parsed.accent))\n          ? parsed.accent\n          : (normalizeCustomAccent(parsed.accent) ?? defaultThemeSelection.accent),\n      font: fonts.ui.family,\n      fonts,\n      // Every axis has to be read back here, or it is lost twice: the provider's\n      // document effect removes the `data-density` that `themeScript` set for the first paint, and\n      // the next `setSelection` rewrites the store without it.\n      density: resolvedDensity(parsed as ThemeSelection),\n      // The newer axes are read back only when the store holds a usable value and are\n      // otherwise left `undefined`, never defaulted: `JSON.stringify` drops them, so a\n      // consumer that never sets one writes the bytes it always did. An id is kept as\n      // stored, known or not, for the same reason a theme id the registry lacks is.\n      terminalThemeId:\n        typeof parsed.terminalThemeId === 'string' && parsed.terminalThemeId.trim() !== ''\n          ? parsed.terminalThemeId\n          : undefined,\n      surface: normalizeSurface(parsed.surface),\n      reduceTransparency:\n        typeof parsed.reduceTransparency === 'boolean' ? parsed.reduceTransparency : undefined,\n    }\n  } catch {\n    return defaultThemeSelection\n  }\n}\n\n/**\n * The default persistence: one JSON document in `localStorage` under `key`.\n *\n * `read` is the provider's original `readSelection`, moved here unchanged — every\n * stored id is validated against the catalogue, so a stale preference falls back to\n * a default rather than reaching the document. `key` may be a function so a\n * provider whose `storageKey` prop changes writes to the key it is now given.\n *\n * Blocked, full or absent storage is survivable in both directions: a read answers\n * with the defaults and a write is dropped, so the preference simply lasts the\n * session.\n */\nexport function localStoragePersistence(key: string | (() => string)): ThemePersistence {\n  const keyOf = () => (typeof key === 'function' ? key() : key)\n  return {\n    read: () => readSelection(keyOf()),\n    write(next) {\n      try {\n        preferenceStore()?.setItem(keyOf(), JSON.stringify(next))\n      } catch {\n        // A full, blocked or unavailable store must not break the switch: the\n        // preference simply does not survive the reload.\n      }\n    },\n  }\n}\n\n/**\n * What a persistence knows, or nothing.\n *\n * The seam's `read` must not throw, and the provider does not rely on that: a host\n * persistence is code the design system has not seen, and a theme provider that\n * fails to mount because a store misbehaved has turned a lost preference into a\n * blank application.\n */\nexport function readPersisted(persistence: ThemePersistence): Partial<ThemeSelection> | undefined {\n  try {\n    return persistence.read()\n  } catch {\n    return undefined\n  }\n}\n\n/** Hand a selection to the store; a store that throws loses the preference, not the switch. */\nexport function writePersisted(persistence: ThemePersistence, next: ThemeSelection): void {\n  try {\n    persistence.write(next)\n  } catch {\n    // Same contract as a full or blocked `localStorage`: the choice holds for the\n    // session and does not survive the reload.\n  }\n}\n\n/**\n * Where a host's versioned preference document lives. One schema describes the\n * document to both halves of the system: {@link createVersionedPersistence} reads and\n * writes it, and `themeScript(options)` reads it before first paint, so the two\n * cannot disagree about a key or a version.\n */\nexport type ThemeStorageSchema = {\n  /** The storage key of the document. */\n  key: string\n  /**\n   * The only top-level `version` read. Absent, the document is unversioned. A record\n   * of any other version is quarantined (see `recoveryKey`), not interpreted.\n   */\n  version?: number\n  /**\n   * The document field that holds the appearance preference (`system`, `light`,\n   * `dark`). Read by `themeScript`; the persistence leaves field names to the codec.\n   * Default `appearance`.\n   */\n  appearanceField?: 'appearance' | 'mode'\n  /**\n   * An older single-value key (`light` | `dark` | `system`) read only while `key` is\n   * absent, and never deleted. The persistence hands it to the codec's `fromLegacy`.\n   */\n  legacyAppearanceKey?: string\n  /**\n   * The stored library of imported themes, for `themeScript` only: an imported\n   * theme's id and verbatim tokens, so the first paint can use the right variant. The\n   * persistence neither reads nor writes it.\n   */\n  libraryKey?: string\n  /** Where an unreadable document is kept. Default `${key}.recovery`. */\n  recoveryKey?: string\n}\n\n/**\n * How a host's document maps to and from the shared {@link ThemeSelection}.\n *\n * The codec is the product schema: it decides which fields a document has, how an\n * unknown value is corrected, and what a fresh install looks like. The engine decides\n * everything about *storage*: what is quarantined, when the legacy key is read, and\n * that nothing is written until `setSelection` asks.\n */\nexport type VersionedCodec<Doc> = {\n  /**\n   * A readable record (the right JSON shape and version) as a selection patch. Fields\n   * it leaves `undefined` fall back to the provider's defaults. It may keep an id the\n   * catalogue lacks; the provider resolves it, it does not rewrite it.\n   */\n  decode(record: Readonly<Record<string, unknown>>): Partial<ThemeSelection>\n  /**\n   * The legacy key's value (never `null`) as a selection patch, or `undefined` for a\n   * value it does not recognise. Called only when the main key is absent.\n   */\n  fromLegacy?(value: string): Partial<ThemeSelection> | undefined\n  /**\n   * What a store with nothing readable answers: a fresh install, an unreadable\n   * document, a blocked store. Absent, the provider's own defaults apply.\n   */\n  defaults?(): Partial<ThemeSelection> | undefined\n  /**\n   * The document to store for a selection. `previous` is the record last read or\n   * written, so a codec can carry a field the selection does not model.\n   */\n  encode(next: ThemeSelection, previous?: Readonly<Record<string, unknown>>): Doc\n}\n\n/** Seams for the storage and the clock; both default to the real ones. */\nexport type VersionedPersistenceOptions = {\n  /** The store, or nothing. Called per access; default is `localStorage` (blocked-safe). */\n  storage?: () => PreferenceStorage | undefined\n  /** The clock for the recovery envelope's `capturedAt`. */\n  now?: () => Date\n}\n\n/**\n * A {@link ThemePersistence} over a versioned document and a host codec.\n *\n * `read` follows the engine's rules (`lib/preference-store.ts`): the main key first;\n * an unreadable or unsupported document is quarantined byte for byte into the\n * recovery key and the codec's `defaults` answer; the legacy key only when the main\n * key is absent. It never writes the main key, so the first write is a user's\n * decision. `write` stores `codec.encode(next, previous)` as JSON and swallows a\n * failure.\n *\n * Neither method throws. The stored bytes are exactly what the codec encodes, so a\n * host keeps its keys, field names and bytes by keeping its codec.\n */\nexport function createVersionedPersistence<Doc>(\n  schema: ThemeStorageSchema,\n  codec: VersionedCodec<Doc>,\n  options: VersionedPersistenceOptions = {}\n): ThemePersistence {\n  const storageOf = options.storage ?? defaultPreferenceStorage\n  const recordSchema = {\n    key: schema.key,\n    version: schema.version,\n    recoveryKey: recoveryKeyFor(schema),\n  }\n  let previous: Readonly<Record<string, unknown>> | undefined\n\n  const fallback = () => {\n    try {\n      return codec.defaults?.()\n    } catch {\n      return undefined\n    }\n  }\n\n  return {\n    read() {\n      const storage = storageOf()\n      if (!storage) return fallback()\n      try {\n        const found = readVersionedRecord(storage, recordSchema, options.now)\n        if (found.status === 'record') {\n          previous = found.record\n          return codec.decode(found.record)\n        }\n        if (found.status === 'absent' && schema.legacyAppearanceKey && codec.fromLegacy) {\n          const legacy = readLegacyValue(storage, schema.legacyAppearanceKey)\n          const migrated = legacy === null ? undefined : codec.fromLegacy(legacy)\n          if (migrated) return migrated\n        }\n      } catch {\n        // A codec that throws on a record it cannot read is an unreadable store.\n      }\n      return fallback()\n    },\n    write(next) {\n      const storage = storageOf()\n      if (!storage) return\n      try {\n        const document = codec.encode(next, previous)\n        if (writeVersionedRecord(storage, schema.key, document)) {\n          previous =\n            typeof document === 'object' && document !== null\n              ? (document as Readonly<Record<string, unknown>>)\n              : undefined\n        }\n      } catch {\n        // An encoder that throws loses the preference, not the switch.\n      }\n    },\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"theme-persistence.js","names":[],"sources":["../../../src/components/theme/theme-persistence.ts"],"sourcesContent":["import { normalizeCustomAccent } from '#lib/accent-roles'\nimport { accentPresets } from '#lib/accent-presets'\nimport { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'\nimport { isThemeAccentId } from '#lib/theme-accents'\nimport {\n  catalogueThemeAppearance,\n  defaultDarkThemeId,\n  defaultLightThemeId,\n} from '#lib/theme-defaults'\nimport { normalizeSurface } from '#lib/theme-surface'\nimport {\n  defaultPreferenceStorage,\n  readLegacyValue,\n  readVersionedRecord,\n  recoveryKeyFor,\n  writeVersionedRecord,\n  type PreferenceStorage,\n} from '#lib/preference-store'\nimport { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state-core'\n\n/**\n * Where a selection is kept between sessions.\n *\n * The provider never touches storage itself; it asks a `ThemePersistence`. The\n * default is {@link localStoragePersistence}, which is what the provider always did.\n * A host that stores the preference in a different shape, under a versioned\n * envelope, or somewhere that is not `localStorage` supplies its own and the\n * resolution and application rules stay the shared ones.\n *\n * The contract is deliberately narrow, so that an implementation cannot make the\n * provider less safe than it was:\n *\n *   - `read` is synchronous and runs once, when the provider is created. It may\n *     repair or quarantine what it finds, and it must not throw: the provider\n *     treats a throw as \"nothing stored\" and starts from the defaults.\n *   - `write` runs only from `setSelection`. Never on mount, never from `preview`,\n *     never as a side effect of reading, so the first write to a store is always a\n *     user's decision. A throw is swallowed, because a full or blocked store must\n *     not break the switch.\n */\nexport type ThemePersistence = {\n  read(): Partial<ThemeSelection> | undefined\n  write(next: ThemeSelection): void\n}\n\n/**\n * The preference store, or nothing.\n *\n * Only ever called inside a `try`: where storage is blocked — a sandboxed iframe, a\n * privacy mode, a denied site-data permission — merely *reading* the `localStorage`\n * global throws (\"Access is denied\", `SecurityError`), so even the `typeof` guard\n * has to sit inside the `try` rather than in front of it. Without a store the\n * preference lives only in the provider's signal for the session.\n */\nfunction preferenceStore(): Storage | undefined {\n  return typeof localStorage === 'undefined' ? undefined : localStorage\n}\n\n/**\n * The stored preference, validated against the catalogue's ids (`theme-defaults`), so\n * reading it never loads the catalogue.\n */\nfunction readSelection(storageKey: string): ThemeSelection {\n  try {\n    const raw = preferenceStore()?.getItem(storageKey)\n    if (!raw) return defaultThemeSelection\n    const parsed = JSON.parse(raw) as Partial<ThemeSelection>\n    const fonts = normalizeAppearanceEditorFontSettings(parsed.fonts, parsed.font).settings\n    return {\n      appearance:\n        parsed.appearance === 'light' ||\n        parsed.appearance === 'dark' ||\n        parsed.appearance === 'system'\n          ? parsed.appearance\n          : defaultThemeSelection.appearance,\n      // An unknown id would leave the document with no theme at all, so a stale\n      // preference from an older catalogue falls back rather than applying nothing.\n      lightThemeId:\n        catalogueThemeAppearance(parsed.lightThemeId ?? '') === 'light'\n          ? (parsed.lightThemeId as string)\n          : defaultLightThemeId,\n      darkThemeId:\n        catalogueThemeAppearance(parsed.darkThemeId ?? '') === 'dark'\n          ? (parsed.darkThemeId as string)\n          : defaultDarkThemeId,\n      // A theme accent is kept whenever it names a slot, even one the stored pair\n      // cannot offer: the id is role-shaped so it survives a theme switch, and an\n      // unoffered slot already resolves to the theme's own primary when applied. A\n      // custom `#rrggbb` is kept in its one stored spelling; its readability is\n      // settled when it is painted, not when it is read.\n      accent:\n        typeof parsed.accent === 'string' &&\n        (accentPresets.some((preset) => preset.id === parsed.accent) ||\n          isThemeAccentId(parsed.accent))\n          ? parsed.accent\n          : (normalizeCustomAccent(parsed.accent) ?? defaultThemeSelection.accent),\n      font: fonts.ui.family,\n      fonts,\n      // Every axis has to be read back here, or it is lost twice: the provider's\n      // document effect removes the `data-density` that `themeScript` set for the first paint, and\n      // the next `setSelection` rewrites the store without it.\n      density: resolvedDensity(parsed as ThemeSelection),\n      // The newer axes are read back only when the store holds a usable value and are\n      // otherwise left `undefined`, never defaulted: `JSON.stringify` drops them, so a\n      // consumer that never sets one writes the bytes it always did. An id is kept as\n      // stored, known or not, for the same reason a theme id the registry lacks is.\n      terminalThemeId:\n        typeof parsed.terminalThemeId === 'string' && parsed.terminalThemeId.trim() !== ''\n          ? parsed.terminalThemeId\n          : undefined,\n      surface: normalizeSurface(parsed.surface),\n      reduceTransparency:\n        typeof parsed.reduceTransparency === 'boolean' ? parsed.reduceTransparency : undefined,\n    }\n  } catch {\n    return defaultThemeSelection\n  }\n}\n\n/**\n * The default persistence: one JSON document in `localStorage` under `key`.\n *\n * `read` is the provider's original `readSelection`, moved here unchanged — every\n * stored id is validated against the catalogue, so a stale preference falls back to\n * a default rather than reaching the document. `key` may be a function so a\n * provider whose `storageKey` prop changes writes to the key it is now given.\n *\n * Blocked, full or absent storage is survivable in both directions: a read answers\n * with the defaults and a write is dropped, so the preference simply lasts the\n * session.\n */\nexport function localStoragePersistence(key: string | (() => string)): ThemePersistence {\n  const keyOf = () => (typeof key === 'function' ? key() : key)\n  return {\n    read: () => readSelection(keyOf()),\n    write(next) {\n      try {\n        preferenceStore()?.setItem(keyOf(), JSON.stringify(next))\n      } catch {\n        // A full, blocked or unavailable store must not break the switch: the\n        // preference simply does not survive the reload.\n      }\n    },\n  }\n}\n\n/**\n * What a persistence knows, or nothing.\n *\n * The seam's `read` must not throw, and the provider does not rely on that: a host\n * persistence is code the design system has not seen, and a theme provider that\n * fails to mount because a store misbehaved has turned a lost preference into a\n * blank application.\n */\nexport function readPersisted(persistence: ThemePersistence): Partial<ThemeSelection> | undefined {\n  try {\n    return persistence.read()\n  } catch {\n    return undefined\n  }\n}\n\n/** Hand a selection to the store; a store that throws loses the preference, not the switch. */\nexport function writePersisted(persistence: ThemePersistence, next: ThemeSelection): void {\n  try {\n    persistence.write(next)\n  } catch {\n    // Same contract as a full or blocked `localStorage`: the choice holds for the\n    // session and does not survive the reload.\n  }\n}\n\n/**\n * Where a host's versioned preference document lives. One schema describes the\n * document to both halves of the system: {@link createVersionedPersistence} reads and\n * writes it, and `themeScript(options)` reads it before first paint, so the two\n * cannot disagree about a key or a version.\n */\nexport type ThemeStorageSchema = {\n  /** The storage key of the document. */\n  key: string\n  /**\n   * The only top-level `version` read. Absent, the document is unversioned. A record\n   * of any other version is quarantined (see `recoveryKey`), not interpreted.\n   */\n  version?: number\n  /**\n   * The document field that holds the appearance preference (`system`, `light`,\n   * `dark`). Read by `themeScript`; the persistence leaves field names to the codec.\n   * Default `appearance`.\n   */\n  appearanceField?: 'appearance' | 'mode'\n  /**\n   * An older single-value key (`light` | `dark` | `system`) read only while `key` is\n   * absent, and never deleted. The persistence hands it to the codec's `fromLegacy`.\n   */\n  legacyAppearanceKey?: string\n  /**\n   * The stored library of imported themes, for `themeScript` only: an imported\n   * theme's id and verbatim tokens, so the first paint can use the right variant. The\n   * persistence neither reads nor writes it.\n   */\n  libraryKey?: string\n  /** Where an unreadable document is kept. Default `${key}.recovery`. */\n  recoveryKey?: string\n}\n\n/**\n * How a host's document maps to and from the shared {@link ThemeSelection}.\n *\n * The codec is the product schema: it decides which fields a document has, how an\n * unknown value is corrected, and what a fresh install looks like. The engine decides\n * everything about *storage*: what is quarantined, when the legacy key is read, and\n * that nothing is written until `setSelection` asks.\n */\nexport type VersionedCodec<Doc> = {\n  /**\n   * A readable record (the right JSON shape and version) as a selection patch. Fields\n   * it leaves `undefined` fall back to the provider's defaults. It may keep an id the\n   * catalogue lacks; the provider resolves it, it does not rewrite it.\n   */\n  decode(record: Readonly<Record<string, unknown>>): Partial<ThemeSelection>\n  /**\n   * The legacy key's value (never `null`) as a selection patch, or `undefined` for a\n   * value it does not recognise. Called only when the main key is absent.\n   */\n  fromLegacy?(value: string): Partial<ThemeSelection> | undefined\n  /**\n   * What a store with nothing readable answers: a fresh install, an unreadable\n   * document, a blocked store. Absent, the provider's own defaults apply.\n   */\n  defaults?(): Partial<ThemeSelection> | undefined\n  /**\n   * The document to store for a selection. `previous` is the record last read or\n   * written, so a codec can carry a field the selection does not model.\n   */\n  encode(next: ThemeSelection, previous?: Readonly<Record<string, unknown>>): Doc\n}\n\n/** Seams for the storage and the clock; both default to the real ones. */\nexport type VersionedPersistenceOptions = {\n  /** The store, or nothing. Called per access; default is `localStorage` (blocked-safe). */\n  storage?: () => PreferenceStorage | undefined\n  /** The clock for the recovery envelope's `capturedAt`. */\n  now?: () => Date\n}\n\n/**\n * A {@link ThemePersistence} over a versioned document and a host codec.\n *\n * `read` follows the engine's rules (`lib/preference-store.ts`): the main key first;\n * an unreadable or unsupported document is quarantined byte for byte into the\n * recovery key and the codec's `defaults` answer; the legacy key only when the main\n * key is absent. It never writes the main key, so the first write is a user's\n * decision. `write` stores `codec.encode(next, previous)` as JSON and swallows a\n * failure.\n *\n * Neither method throws. The stored bytes are exactly what the codec encodes, so a\n * host keeps its keys, field names and bytes by keeping its codec.\n */\nexport function createVersionedPersistence<Doc>(\n  schema: ThemeStorageSchema,\n  codec: VersionedCodec<Doc>,\n  options: VersionedPersistenceOptions = {}\n): ThemePersistence {\n  const storageOf = options.storage ?? defaultPreferenceStorage\n  const recordSchema = {\n    key: schema.key,\n    version: schema.version,\n    recoveryKey: recoveryKeyFor(schema),\n  }\n  let previous: Readonly<Record<string, unknown>> | undefined\n\n  const fallback = () => {\n    try {\n      return codec.defaults?.()\n    } catch {\n      return undefined\n    }\n  }\n\n  return {\n    read() {\n      const storage = storageOf()\n      if (!storage) return fallback()\n      try {\n        const found = readVersionedRecord(storage, recordSchema, options.now)\n        if (found.status === 'record') {\n          previous = found.record\n          return codec.decode(found.record)\n        }\n        if (found.status === 'absent' && schema.legacyAppearanceKey && codec.fromLegacy) {\n          const legacy = readLegacyValue(storage, schema.legacyAppearanceKey)\n          const migrated = legacy === null ? undefined : codec.fromLegacy(legacy)\n          if (migrated) return migrated\n        }\n      } catch {\n        // A codec that throws on a record it cannot read is an unreadable store.\n      }\n      return fallback()\n    },\n    write(next) {\n      const storage = storageOf()\n      if (!storage) return\n      try {\n        const document = codec.encode(next, previous)\n        if (writeVersionedRecord(storage, schema.key, document)) {\n          previous =\n            typeof document === 'object' && document !== null\n              ? (document as Readonly<Record<string, unknown>>)\n              : undefined\n        }\n      } catch {\n        // An encoder that throws loses the preference, not the switch.\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/components/theme/theme-provider-core.d.ts

@@ -0,0 +1,19 @@
+import { 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 declare function ThemeProviderCore(props: ThemeProviderProps & {
+    catalogue: ThemeCatalogueSource;
+}): import("solid-js").JSX.Element;
+//# sourceMappingURL=theme-provider-core.d.ts.map

package/dist/components/theme/theme-provider-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-provider-core.d.ts","sourceRoot":"","sources":["../../../src/components/theme/theme-provider-core.tsx"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,wBAAwB,CAAA;AAE/B,YAAY,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AACtF,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,2BAA2B,GACjC,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAC1F,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAA;AAE3B;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG;IAAE,SAAS,EAAE,oBAAoB,CAAA;CAAE,kCAIhG"}

package/dist/components/theme/theme-provider-core.js

@@ -0,0 +1,28 @@
+import { themeContext, useOptionalTheme, useTheme } from "./theme-context.js";
+import { defaultThemeSelection, resolvedDensity } from "./theme-state-core.js";
+import { createVersionedPersistence, localStoragePersistence } from "./theme-persistence.js";
+import { createThemeContextValue } from "./theme-provider-value.js";
+import { inlineScriptLiteral, themeScript } from "./theme-script.js";
+import { createComponent } from "solid-js/web";
+//#region src/components/theme/theme-provider-core.tsx
+/**
+* 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.
+*/
+function ThemeProviderCore(props) {
+	const value = createThemeContextValue(props);
+	const Context = themeContext();
+	return createComponent(Context.Provider, {
+		value,
+		get children() {
+			return props.children;
+		}
+	});
+}
+//#endregion
+export { ThemeProviderCore, createVersionedPersistence, defaultThemeSelection, inlineScriptLiteral, localStoragePersistence, resolvedDensity, themeScript, useOptionalTheme, useTheme };
+
+//# sourceMappingURL=theme-provider-core.js.map

package/dist/components/theme/theme-provider-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-provider-core.js","names":["themeContext","createThemeContextValue","ThemeCatalogueSource","ThemeProviderProps","createVersionedPersistence","localStoragePersistence","ThemePersistence","ThemeStorageSchema","VersionedCodec","VersionedPersistenceOptions","useOptionalTheme","useTheme","ThemeSurface","EditorRolesMode","inlineScriptLiteral","themeScript","ThemeScriptOptions","defaultThemeSelection","resolvedDensity","ThemeContextValue","ThemeDensity","ThemeSelection","ThemeProviderCore","props","catalogue","value","Context","_$createComponent","Provider","children","_$createComponent"],"sources":["../../../src/components/theme/theme-provider-core.tsx"],"sourcesContent":["import { themeContext } from './theme-context'\nimport {\n  createThemeContextValue,\n  type ThemeCatalogueSource,\n  type ThemeProviderProps,\n} from './theme-provider-value'\n\nexport type { ThemeCatalogueSource, ThemeProviderProps } from './theme-provider-value'\nexport {\n  createVersionedPersistence,\n  localStoragePersistence,\n  type ThemePersistence,\n  type ThemeStorageSchema,\n  type VersionedCodec,\n  type VersionedPersistenceOptions,\n} from './theme-persistence'\nexport { useOptionalTheme, useTheme } from './theme-context'\nexport type { ThemeSurface } from '#lib/theme-surface'\nexport type { EditorRolesMode } from '#lib/themes'\nexport { inlineScriptLiteral, themeScript, type ThemeScriptOptions } from './theme-script'\nexport {\n  defaultThemeSelection,\n  resolvedDensity,\n  type ThemeContextValue,\n  type ThemeDensity,\n  type ThemeSelection,\n} from './theme-state-core'\n\n/**\n * The provider, parameterised by where its catalogue comes from.\n *\n * `ThemeProvider` (`theme-provider.tsx`) and the lazy `ThemeProvider`\n * (`theme-provider-lazy.tsx`) are this component with a source; the work is\n * `createThemeContextValue`. It imports no catalogue code or data.\n */\nexport function ThemeProviderCore(props: ThemeProviderProps & { catalogue: ThemeCatalogueSource }) {\n  const value = createThemeContextValue(props)\n  const Context = themeContext()\n  return <Context.Provider value={value}>{props.children}</Context.Provider>\n}\n"],"mappings":";;;;;;;;;;;;;;AAmCA,SAAgBsB,kBAAkBC,OAAiE;CACjG,MAAME,QAAQxB,wBAAwBsB,KAAK;CAC3C,MAAMG,UAAU1B,aAAa;CAC7B,OAAA2B,gBAAQD,QAAQE,UAAQ;EAAQH;EAAK,IAAAI,WAAA;GAAA,OAAGN,MAAMM;EAAQ;CAAA,CAAA;AACxD"}

package/dist/components/theme/theme-provider-lazy.d.ts

@@ -0,0 +1,28 @@
+import { 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 declare function ThemeProvider(props: ThemeProviderProps): import("solid-js").JSX.Element;
+//# sourceMappingURL=theme-provider-lazy.d.ts.map

package/dist/components/theme/theme-provider-lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-provider-lazy.d.ts","sourceRoot":"","sources":["../../../src/components/theme/theme-provider-lazy.tsx"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAElF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,kCAItD"}

package/dist/components/theme/theme-provider-lazy.js

@@ -0,0 +1,36 @@
+import { ThemeProviderCore } from "./theme-provider-core.js";
+import { createLazyCatalogue } from "./theme-catalogue-source.js";
+import { createComponent, mergeProps } from "solid-js/web";
+//#region src/components/theme/theme-provider-lazy.tsx
+/**
+* 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.
+*/
+function ThemeProvider(props) {
+	const catalogue = createLazyCatalogue();
+	return createComponent(ThemeProviderCore, mergeProps(props, { catalogue }));
+}
+//#endregion
+export { ThemeProvider };
+
+//# sourceMappingURL=theme-provider-lazy.js.map

package/dist/components/theme/theme-provider-lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-provider-lazy.js","names":["createLazyCatalogue","ThemeProviderCore","ThemeProviderProps","loadThemeCatalogue","ThemeProvider","props","catalogue","_$createComponent","_$mergeProps","_$createComponent","_$mergeProps"],"sources":["../../../src/components/theme/theme-provider-lazy.tsx"],"sourcesContent":["import { createLazyCatalogue } from './theme-catalogue-source'\nimport { ThemeProviderCore, type ThemeProviderProps } from './theme-provider-core'\n\nexport { loadThemeCatalogue } from './theme-catalogue-source'\n\n/**\n * ThemeProvider, with the theme catalogue out of the start-up path.\n *\n * Same props, same context and same behaviour as `ThemeProvider` for everything the\n * shipped default pair covers: the default light and dark themes, a host's own\n * `themes`, every accent preset and custom colour, the surface axis, fonts and\n * density. Only the 32 other catalogue themes are not in the start-up chunk. The first\n * time the selection (or a preview) names one, or a theme-derived `ansi-*` accent over\n * such a pair, this provider imports the catalogue in a chunk of its own:\n *\n *   - until it arrives the document keeps what is on it (set before first paint by\n *     `themeScript`, painted by the stylesheet under `palette=\"stylesheet\"`), and\n *     `variant()` is the default of the appearance;\n *   - when it arrives the provider re-resolves and paints the stored theme, and\n *     `useTheme().catalogueReady()` turns true;\n *   - a preview of a theme that has not loaded starts the load and shows when it ends.\n *\n * Pair it with `palette=\"stylesheet\"` and `themeScript`: inline palettes of catalogue\n * themes need the catalogue to compute, so under the default `inline` palette every\n * stored theme but the defaults waits for the import.\n *\n * `useTheme().themes` and `allThemes()` list only the default pair until\n * `catalogueReady()`; a picker calls `useTheme().loadCatalogue()` when it mounts.\n */\nexport function ThemeProvider(props: ThemeProviderProps) {\n  // Hoisted: a JSX prop expression is re-evaluated on every read, and this source owns signals.\n  const catalogue = createLazyCatalogue()\n  return <ThemeProviderCore {...props} catalogue={catalogue} />\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgBI,cAAcC,OAA2B;CAEvD,MAAMC,YAAYN,oBAAoB;CACtC,OAAAO,gBAAQN,mBAAiBO,WAAKH,OAAK,EAAaC,UAAS,CAAA,CAAA;AAC3D"}

package/dist/components/theme/theme-provider-value.d.ts

@@ -0,0 +1,175 @@
+import type { JSX } from 'solid-js';
+import { type ThemeEngine } from '#lib/theme-engine';
+import type { EditorRolesMode, ThemeVariant } from '#lib/themes';
+import { type ThemePersistence } from './theme-persistence';
+import { type ThemeContextValue, type ThemeSelection } from './theme-state-core';
+/**
+ * ThemeProvider.
+ *
+ * Owns the appearance preference and applies it to the document. One provider near
+ * the root; everything below reads it.
+ *
+ * ## What a preference is
+ *
+ * Four independent choices (`ThemeSelection`), and keeping them independent is the
+ * point: appearance, a theme per appearance, an accent and fonts. They compose: a
+ * user who wants Nord with a violet accent and the system font should not need
+ * someone to author that combination.
+ *
+ * ## Where the rules live
+ *
+ * This component is wiring. What a selection merges to and resolves to is
+ * `theme-state.ts`; what lands on `<html>` is `theme-document.ts`; where the
+ * preference is kept is `theme-persistence.ts`. Each is plain code a test can call,
+ * which is the reason none of it is inlined here.
+ *
+ * ## Why the variants are applied as inline properties
+ *
+ * The catalogue is data, and a theme is applied by writing its roles onto
+ * `<html>` as custom properties. That is what makes an imported palette work
+ * without a hand-written `[data-theme]` block per theme, and it is why a settings
+ * UI can show a preview by reading the same object rather than by loading a
+ * stylesheet. `theme.css` keeps the default theme's values so the first paint is
+ * correct before any script runs.
+ */
+export type ThemeProviderProps = {
+    children?: JSX.Element;
+    /** Where the preference is persisted. Distinct per application. */
+    storageKey?: string;
+    /** Start from this instead of the stored preference. */
+    initial?: Partial<ThemeSelection>;
+    /**
+     * The selection, owned by the caller.
+     *
+     * For a consumer that keeps the state itself — a settings store, or a workshop
+     * whose selection lives in Storybook globals — rather than handing it to this
+     * provider's signal. Each change lands here and the document follows; nothing is
+     * written to the store, because the caller is the one who persists. A picker
+     * below the provider still works, and its change is the caller's to read back.
+     *
+     * Absent, the provider is the whole owner: it reads `storageKey` on mount,
+     * seeds from `initial`, and persists every `setSelection`.
+     */
+    selection?: Partial<ThemeSelection>;
+    /**
+     * Where the preference is kept, in place of `localStorage` under `storageKey`.
+     *
+     * Read once when the provider is created, so changing the prop later does not
+     * move the store. `storageKey` is ignored when this is given.
+     */
+    persistence?: ThemePersistence;
+    /**
+     * Variants the host adds to the built-in catalogue — themes a user imported.
+     *
+     * A function is read inside the provider's reactive scope, so one that reads a
+     * signal keeps the picker and the document current when the set changes. A
+     * stored id that names no variant, built in or added, paints the default of its
+     * appearance and stays in the selection untouched.
+     */
+    themes?: readonly ThemeVariant[] | (() => readonly ThemeVariant[]);
+    /**
+     * Rewrites the custom properties of each pass before they are written to
+     * `<html>`: the variant's roles with the accent over them. `tokensAsHex` from
+     * `lib/themes` is the one the system ships.
+     */
+    transformTokens?: (tokens: Record<string, string>) => Record<string, string>;
+    /**
+     * Switch CSS transitions off for the frame that carries a change, so a theme
+     * switch cannot animate the whole page. Off by default: it adds a `<style>`
+     * element to `<head>` for two frames on every change.
+     */
+    disableTransitionOnChange?: boolean;
+    /**
+     * The contrast ratio an accent is held to against the variant's background,
+     * repaired to the nearest passing colour when it falls short. Absent, presets
+     * are painted verbatim — the catalogue measured them for its own themes — and
+     * only a custom `#rrggbb` is held to 3:1. A host that adds themes the catalogue
+     * never measured passes 3 to hold the presets to it as well; for the catalogue's
+     * own themes the floor changes no preset.
+     */
+    accentContrastFloor?: number;
+    /**
+     * Turns the surface axis on: `selection.surface` and `selection.reduceTransparency`
+     * are resolved against the operating system's Reduce Transparency setting and the
+     * host's capability, and `data-surface`, `data-reduce-transparency` and
+     * `--surface-alpha` are written to `<html>` (the frost rule in `theme.css` reads
+     * them). Off by default: a provider that never opts in writes none of them, adds no
+     * media-query listener, and stores nothing new.
+     *
+     * An object also states the host's capability. `nativeTranslucency` is whether the
+     * window can render the OS's own translucency; without it a `translucent`
+     * preference paints the tokenized `frosted` surface instead of pretending to
+     * vibrancy. A function is read inside the provider's reactive scope, for a
+     * capability that is learned after mount.
+     *
+     * A selection that already carries a `surface` turns the axis on for itself, so a
+     * host that stores the field gets the same document without the prop.
+     */
+    surface?: boolean | {
+        nativeTranslucency?: boolean | (() => boolean);
+    };
+    /**
+     * Where a catalogue variant's palette comes from. `inline` (the default) writes
+     * every role onto `<html>`. `stylesheet` leaves a catalogue variant to the host's
+     * `[data-theme]` stylesheet and writes inline only what no stylesheet can know: a
+     * host's own `themes`, the accent, the pinned terminal palette, the surface alpha
+     * and the fonts. Switching from a host variant back to a catalogue one removes the
+     * properties the host variant wrote.
+     */
+    palette?: 'inline' | 'stylesheet';
+    /**
+     * The projection behind the `--editor-*` ramp. `syntax` (the default) is the
+     * catalogue's quiet syntax roles, a comment among them deliberately below
+     * body-text contrast. `floor` holds all sixteen roles to 4.5:1 on the canvas, as
+     * hex, for a host that renders code as content (a diff, a file view) rather than
+     * as decoration.
+     *
+     * Applies to catalogue variants; a host's own `themes` keep their `editor` and
+     * their `tokens`. With `palette="stylesheet"` it is the one palette property a
+     * catalogue variant still writes inline, because `theme-variants.css` is generated
+     * for `syntax`. Absent, nothing changes.
+     */
+    editorRoles?: EditorRolesMode;
+    /**
+     * Bind the platform zoom chords (Cmd or Ctrl with `=`, `+`, `-`, `0`) to the three
+     * text sizes instead of the browser's page zoom: stepping them together is zoom
+     * inside the persisted type system. Off by default: it adds a capturing `keydown`
+     * listener to `window`, and an event already handled elsewhere is left alone.
+     * `zoomFonts` on the context does the same from a menu or a host's own binding.
+     */
+    fontZoom?: boolean;
+};
+/**
+ * Where the provider's catalogue questions are answered, and whether the whole
+ * catalogue is available yet.
+ *
+ * The eager provider's source is the full catalogue and is always loaded. The lazy
+ * provider's source starts on the default pair that ships with it and swaps to the
+ * full catalogue when {@link ThemeCatalogueSource.load} resolves. Both read the same
+ * way in the provider: `engine()` is reactive, so everything derived from it follows
+ * the swap.
+ */
+export type ThemeCatalogueSource = {
+    /** The engine answering catalogue questions now. Changes once, when loading completes. */
+    engine: () => ThemeEngine;
+    /** True when `engine()` is the full catalogue. */
+    loaded: () => boolean;
+    /** True when loading failed; the provider then paints what it can without the rest. */
+    failed: () => boolean;
+    /** Start loading the full catalogue (idempotent). Resolves when `loaded()` is true. */
+    load: () => Promise<void>;
+};
+/**
+ * Everything the provider is, as a value: the context object, with its effects and
+ * listeners created in the caller's reactive scope.
+ *
+ * Parameterised by where its catalogue comes from: `ThemeProvider`
+ * (`theme-provider.tsx`) and the lazy `ThemeProvider` (`theme-provider-lazy.tsx`) wrap
+ * this with a source. It imports no catalogue code or data, which is what lets the lazy
+ * one keep them out of a consumer's start-up chunk. It is not JSX so that the unit lane,
+ * which has no Solid compiler, can drive it directly.
+ */
+export declare function createThemeContextValue(props: ThemeProviderProps & {
+    catalogue: ThemeCatalogueSource;
+}): ThemeContextValue;
+//# sourceMappingURL=theme-provider-value.d.ts.map

package/dist/components/theme/theme-provider-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-provider-value.d.ts","sourceRoot":"","sources":["../../../src/components/theme/theme-provider-value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAInC,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACvF,OAAO,KAAK,EAAE,eAAe,EAAmB,YAAY,EAAE,MAAM,aAAa,CAAA;AAEjF,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAQL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,EAAE,GAAG,CAAC,OAAO,CAAA;IACtB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;IACjC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;IACnC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,SAAS,YAAY,EAAE,GAAG,CAAC,MAAM,SAAS,YAAY,EAAE,CAAC,CAAA;IAClE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5E;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,kBAAkB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;KAAE,CAAA;IACtE;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAA;IACjC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,0FAA0F;IAC1F,MAAM,EAAE,MAAM,WAAW,CAAA;IACzB,kDAAkD;IAClD,MAAM,EAAE,MAAM,OAAO,CAAA;IACrB,uFAAuF;IACvF,MAAM,EAAE,MAAM,OAAO,CAAA;IACrB,uFAAuF;IACvF,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B,CAAA;AASD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,GAAG;IAAE,SAAS,EAAE,oBAAoB,CAAA;CAAE,GAC9D,iBAAiB,CAoPnB"}

package/dist/components/theme/theme-provider-value.js

@@ -0,0 +1,200 @@
+import { fontZoomShortcut } from "../../lib/font-zoom.js";
+import { REDUCED_TRANSPARENCY_QUERY, resolveSurfaceState } from "../../lib/theme-surface.js";
+import { CatalogueRequired, needsCatalogue } from "../../lib/theme-engine.js";
+import { accentRolesForStateWith, initialThemeSelection, mergeRegistry, mergeThemeSelection, resolveTerminalVariant, resolveThemeState, zoomedFontSettings } from "./theme-state-core.js";
+import { applyThemeToRootWith, applyWithoutTransitions } from "./theme-document-core.js";
+import { localStoragePersistence, readPersisted, writePersisted } from "./theme-persistence.js";
+import { createEffect, createMemo, createSignal, onCleanup, splitProps, untrack } from "solid-js";
+//#region src/components/theme/theme-provider-value.ts
+/** The operating system's Reduce Transparency query, where there is a window to ask. */
+function reducedTransparencyMedia() {
+	return typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(REDUCED_TRANSPARENCY_QUERY) : void 0;
+}
+/**
+* Everything the provider is, as a value: the context object, with its effects and
+* listeners created in the caller's reactive scope.
+*
+* Parameterised by where its catalogue comes from: `ThemeProvider`
+* (`theme-provider.tsx`) and the lazy `ThemeProvider` (`theme-provider-lazy.tsx`) wrap
+* this with a source. It imports no catalogue code or data, which is what lets the lazy
+* one keep them out of a consumer's start-up chunk. It is not JSX so that the unit lane,
+* which has no Solid compiler, can drive it directly.
+*/
+function createThemeContextValue(props) {
+	const [local] = splitProps(props, [
+		"catalogue",
+		"storageKey",
+		"initial",
+		"selection",
+		"persistence",
+		"themes",
+		"transformTokens",
+		"disableTransitionOnChange",
+		"accentContrastFloor",
+		"surface",
+		"palette",
+		"editorRoles",
+		"fontZoom"
+	]);
+	const storageKey = () => local.storageKey ?? "adea-appearance";
+	const persistence = local.persistence ?? localStoragePersistence(storageKey);
+	const extraThemes = createMemo(() => typeof local.themes === "function" ? local.themes() : local.themes ?? []);
+	const source = () => local.catalogue;
+	const engine = () => source().engine();
+	const registry = createMemo(() => mergeRegistry(engine().builtinThemes, extraThemes()));
+	const [selection, setSelectionState] = createSignal(initialThemeSelection(readPersisted(persistence), local.initial));
+	createEffect(() => {
+		const incoming = local.selection;
+		if (incoming) setSelectionState((current) => mergeThemeSelection(current, incoming));
+	});
+	const [systemAppearance, setSystemAppearance] = createSignal("light");
+	if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
+		const query = window.matchMedia("(prefers-color-scheme: dark)");
+		setSystemAppearance(query.matches ? "dark" : "light");
+		const onChange = (event) => setSystemAppearance(event.matches ? "dark" : "light");
+		query.addEventListener("change", onChange);
+		onCleanup(() => query.removeEventListener("change", onChange));
+	}
+	const committed = createMemo(() => resolveThemeState(selection(), systemAppearance(), registry()));
+	const resolvedAppearance = createMemo(() => committed().appearance);
+	const variant = createMemo(() => committed().variant);
+	const [draft, setDraft] = createSignal();
+	const shownSelection = createMemo(() => {
+		const preview = draft();
+		return preview ? mergeThemeSelection(selection(), preview) : selection();
+	});
+	const shown = createMemo(() => draft() ? resolveThemeState(shownSelection(), systemAppearance(), registry()) : committed());
+	const surfaceOn = (candidate) => local.surface === true || typeof local.surface === "object" || candidate.surface !== void 0;
+	const nativeTranslucency = () => {
+		const capability = typeof local.surface === "object" ? local.surface.nativeTranslucency : false;
+		return (typeof capability === "function" ? capability() : capability) === true;
+	};
+	const [osReducedTransparency, setOsReducedTransparency] = createSignal(surfaceOn(untrack(shownSelection)) ? reducedTransparencyMedia()?.matches ?? false : false);
+	const axisOn = createMemo(() => surfaceOn(shownSelection()));
+	createEffect(() => {
+		const query = axisOn() ? reducedTransparencyMedia() : void 0;
+		setOsReducedTransparency(query?.matches ?? false);
+		if (!query) return;
+		const onChange = (event) => setOsReducedTransparency(event.matches);
+		query.addEventListener("change", onChange);
+		onCleanup(() => query.removeEventListener("change", onChange));
+	});
+	const surfaceStateOf = (candidate) => resolveSurfaceState(candidate.surface, {
+		osReducedTransparency: osReducedTransparency(),
+		userReducedTransparency: candidate.reduceTransparency === true,
+		nativeTranslucency: nativeTranslucency()
+	});
+	const committedSurface = createMemo(() => surfaceOn(selection()) ? surfaceStateOf(selection()) : void 0);
+	const waitingFor = (candidate, appearance) => !source().loaded() && !source().failed() && needsCatalogue(candidate, appearance);
+	createEffect(() => {
+		if (needsCatalogue(selection(), committed().appearance) || needsCatalogue(shownSelection(), shown().appearance)) source().load();
+	});
+	let written;
+	let restoreTransitions;
+	createEffect(() => {
+		if (typeof document === "undefined") return;
+		const current = engine();
+		const display = shown();
+		if (waitingFor(shownSelection(), display.appearance)) return;
+		const state = {
+			selection: shownSelection(),
+			appearance: display.appearance,
+			variant: display.variant,
+			terminalVariant: resolveTerminalVariant(shownSelection().terminalThemeId, registry()),
+			surface: axisOn() ? surfaceStateOf(shownSelection()) : void 0
+		};
+		const options = {
+			transformTokens: local.transformTokens,
+			accentContrastFloor: local.accentContrastFloor,
+			palette: local.palette,
+			editorRoles: local.editorRoles
+		};
+		const apply = () => {
+			try {
+				written = applyThemeToRootWith(current, document.documentElement, state, options, written);
+			} catch (error) {
+				if (!(error instanceof CatalogueRequired)) throw error;
+			}
+		};
+		if (local.disableTransitionOnChange) {
+			restoreTransitions?.();
+			restoreTransitions = applyWithoutTransitions(document, apply);
+		} else apply();
+	});
+	onCleanup(() => restoreTransitions?.());
+	const themeAccents = createMemo(() => {
+		try {
+			return engine().themeAccentsFor(selection().lightThemeId, selection().darkThemeId);
+		} catch (error) {
+			if (!(error instanceof CatalogueRequired)) throw error;
+			return [];
+		}
+	});
+	const zoomFonts = (intent) => value.setSelection({ fonts: zoomedFontSettings(selection(), intent) });
+	const onKeyDown = (event) => {
+		if (event.defaultPrevented) return;
+		const intent = fontZoomShortcut(event);
+		if (!intent) return;
+		event.preventDefault();
+		zoomFonts(intent);
+	};
+	createEffect(() => {
+		if (!local.fontZoom || typeof window === "undefined") return;
+		window.addEventListener("keydown", onKeyDown, { capture: true });
+		onCleanup(() => window.removeEventListener("keydown", onKeyDown, { capture: true }));
+	});
+	const value = {
+		selection,
+		resolvedAppearance,
+		variant,
+		get themes() {
+			return engine().builtinThemes;
+		},
+		themeAccents,
+		allThemes: registry,
+		preview(next) {
+			setDraft(next ? { ...next } : void 0);
+		},
+		previewing: () => draft() !== void 0,
+		accentRolesFor(accent, variantId) {
+			const current = engine();
+			const state = {
+				selection: selection(),
+				variant: variant(),
+				registry: registry(),
+				accentContrastFloor: local.accentContrastFloor
+			};
+			try {
+				return accentRolesForStateWith(current, accent, variantId, state);
+			} catch (error) {
+				if (!(error instanceof CatalogueRequired)) throw error;
+				source().load();
+				try {
+					return accentRolesForStateWith({ accentRolesForSelection: (id, appearance, pair, options) => current.accentRolesForSelection(id, appearance, pair, {
+						...options,
+						variantId: void 0
+					}) }, accent, variantId, state);
+				} catch (inner) {
+					if (!(inner instanceof CatalogueRequired)) throw inner;
+					return;
+				}
+			}
+		},
+		catalogueReady: () => source().loaded(),
+		loadCatalogue: () => source().load(),
+		effectiveSurface: () => committedSurface()?.surface ?? "opaque",
+		reduceTransparencyActive: () => committedSurface()?.reduceTransparencyActive ?? false,
+		zoomFonts,
+		setSelection(patch) {
+			const next = mergeThemeSelection(selection(), patch);
+			setSelectionState(next);
+			setDraft(void 0);
+			writePersisted(persistence, next);
+		}
+	};
+	return value;
+}
+//#endregion
+export { createThemeContextValue };
+
+//# sourceMappingURL=theme-provider-value.js.map