@riverbankcms/sdk 0.103.0 → 0.104.1

package/dist/_dts/theme-core/src/palette/{variants → curated}/warm-neutral.d.ts

@@ -3,7 +3,7 @@
  * Warm Editorial, Modern Wellness, Calm Studio site styles.
  */
 export declare const warmNeutralClay: Readonly<{
-    id: import("../../../../blocks/src/index").PaletteVariantId<"warm-neutral-clay">;
+    id: import("../../../../blocks/src/index").CuratedPaletteId<"warm-neutral-clay">;
     name: string;
     description: string;
     tags: Readonly<Partial<Readonly<{
@@ -12,14 +12,11 @@ export declare const warmNeutralClay: Readonly<{
         motion: import("../../../../blocks/src/index").StyleMotion;
         era: import("../../../../blocks/src/index").StyleEra;
     }>>>;
-    mode: "light" | "dark";
-    colors: readonly Readonly<{
-        name: import("../../../../blocks/src/index").PaletteTokenName;
-        hex: string;
-    }>[];
+    mode: import("../../../../blocks/src/index").PaletteMode;
+    colors: import("../../../../blocks/src/index").PaletteColors;
 }>;
 export declare const warmNeutralCream: Readonly<{
-    id: import("../../../../blocks/src/index").PaletteVariantId<"warm-neutral-cream">;
+    id: import("../../../../blocks/src/index").CuratedPaletteId<"warm-neutral-cream">;
     name: string;
     description: string;
     tags: Readonly<Partial<Readonly<{
@@ -28,14 +25,11 @@ export declare const warmNeutralCream: Readonly<{
         motion: import("../../../../blocks/src/index").StyleMotion;
         era: import("../../../../blocks/src/index").StyleEra;
     }>>>;
-    mode: "light" | "dark";
-    colors: readonly Readonly<{
-        name: import("../../../../blocks/src/index").PaletteTokenName;
-        hex: string;
-    }>[];
+    mode: import("../../../../blocks/src/index").PaletteMode;
+    colors: import("../../../../blocks/src/index").PaletteColors;
 }>;
 export declare const warmNeutralSoftEarth: Readonly<{
-    id: import("../../../../blocks/src/index").PaletteVariantId<"warm-neutral-soft-earth">;
+    id: import("../../../../blocks/src/index").CuratedPaletteId<"warm-neutral-soft-earth">;
     name: string;
     description: string;
     tags: Readonly<Partial<Readonly<{
@@ -44,14 +38,11 @@ export declare const warmNeutralSoftEarth: Readonly<{
         motion: import("../../../../blocks/src/index").StyleMotion;
         era: import("../../../../blocks/src/index").StyleEra;
     }>>>;
-    mode: "light" | "dark";
-    colors: readonly Readonly<{
-        name: import("../../../../blocks/src/index").PaletteTokenName;
-        hex: string;
-    }>[];
+    mode: import("../../../../blocks/src/index").PaletteMode;
+    colors: import("../../../../blocks/src/index").PaletteColors;
 }>;
 export declare const warmNeutralForest: Readonly<{
-    id: import("../../../../blocks/src/index").PaletteVariantId<"warm-neutral-forest">;
+    id: import("../../../../blocks/src/index").CuratedPaletteId<"warm-neutral-forest">;
     name: string;
     description: string;
     tags: Readonly<Partial<Readonly<{
@@ -60,9 +51,6 @@ export declare const warmNeutralForest: Readonly<{
         motion: import("../../../../blocks/src/index").StyleMotion;
         era: import("../../../../blocks/src/index").StyleEra;
     }>>>;
-    mode: "light" | "dark";
-    colors: readonly Readonly<{
-        name: import("../../../../blocks/src/index").PaletteTokenName;
-        hex: string;
-    }>[];
+    mode: import("../../../../blocks/src/index").PaletteMode;
+    colors: import("../../../../blocks/src/index").PaletteColors;
 }>;

package/dist/_dts/theme-core/src/palette/editorState.d.ts

@@ -0,0 +1,45 @@
+import type { PaletteColors, PaletteMode } from './colors';
+import type { CuratedPaletteId } from './curated/types';
+import type { ResolvedPaletteSelection } from './resolveSelection';
+import type { PaletteCommand, SitePaletteId, SitePaletteVersion } from './selection';
+export type PalettePreview = Readonly<{
+    kind: 'clean';
+    resolved: ResolvedPaletteSelection;
+}> | Readonly<{
+    kind: 'selected';
+    resolved: ResolvedPaletteSelection;
+}> | Readonly<{
+    kind: 'edited-curated';
+    sourcePaletteId: CuratedPaletteId;
+    colors: PaletteColors;
+    mode: PaletteMode;
+}> | Readonly<{
+    kind: 'edited-site';
+    paletteId: SitePaletteId;
+    expectedVersion: SitePaletteVersion;
+    colors: PaletteColors;
+    mode: PaletteMode;
+}> | Readonly<{
+    kind: 'new-site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+}>;
+export type PaletteEditorState = Readonly<{
+    committed: ResolvedPaletteSelection;
+    preview: PalettePreview;
+}>;
+export type PaletteEditorAction = Readonly<{
+    kind: 'select';
+    resolved: ResolvedPaletteSelection;
+}> | Readonly<{
+    kind: 'edit';
+    colors: PaletteColors;
+    mode: PaletteMode;
+}> | Readonly<{
+    kind: 'create';
+}> | Readonly<{
+    kind: 'cancel';
+}>;
+export declare function createPaletteEditorState(committed: ResolvedPaletteSelection): PaletteEditorState;
+export declare function reducePaletteEditorState(state: PaletteEditorState, action: PaletteEditorAction): PaletteEditorState;
+export declare function planPaletteCommand(state: PaletteEditorState): PaletteCommand;

package/dist/_dts/theme-core/src/palette/index.d.ts

@@ -1,14 +1,25 @@
-export * from "../mock-themes/all";
-export * from "./classifyColor";
-export * from "./expandPalette";
-export * from "./generateCssVars";
-export * from "./generateShades";
-export * from "./neutralScale";
-export * from "./types";
-export * from "./utils";
-export * from "./utils/paletteAccess";
-export * from "./extractPalette";
-export * from "./utils/fromVibrant";
-export * from "./utils/suggestRecipes";
-export * from "./recipes/allRecipes";
-export * from "./variants";
+export * from '../mock-themes/all';
+export * from './classifyColor';
+export * from './expandPalette';
+export * from './generateCssVars';
+export * from './generateShades';
+export * from './neutralScale';
+export * from './types';
+export * from './utils';
+export * from './utils/paletteAccess';
+export * from './extractPalette';
+export * from './colors';
+export * from './editorState';
+export * from './libraryModel';
+export * from './legacySelection';
+export * from './legacyRuntimeProjection';
+export * from './paletteCompatibilityTransition';
+export * from './persistenceReadSource';
+export * from './resolveSelection';
+export * from './selection';
+export * from './sitePalettePersistence';
+export * from './themePaletteCompatibility';
+export * from './utils/fromVibrant';
+export * from './utils/suggestRecipes';
+export * from './recipes/allRecipes';
+export * from './curated';

package/dist/_dts/theme-core/src/palette/legacyRuntimeProjection.d.ts

@@ -0,0 +1,55 @@
+import type { CuratedPaletteId, PaletteOverrides } from './curated';
+import type { PaletteColors, PaletteMode } from './colors';
+import type { PalettePersistenceReadResult, RuntimePaletteState } from './persistenceReadSource';
+import type { LegacyPaletteRequestBaseline, PaletteCompatibilityState } from './paletteCompatibilityTransition';
+import type { PaletteSelection } from './selection';
+export type LegacyPaletteResponseProjection = Readonly<{
+    paletteVariantId: CuratedPaletteId | null;
+    paletteOverrides: PaletteOverrides | null;
+}>;
+declare const paletteCompatibilityBaselineBrand: unique symbol;
+/**
+ * The complete compatibility representation of a resolved palette. This is
+ * deliberately narrower than the nullable legacy response wire shape: every
+ * successful authoritative write must persist one of these values.
+ */
+export type PaletteCompatibilityBaseline = Readonly<{
+    paletteVariantId: CuratedPaletteId;
+    paletteOverrides: PaletteOverrides | null;
+    [paletteCompatibilityBaselineBrand]: true;
+}>;
+type ResolvedPaletteForLegacyProjection = Readonly<{
+    selection: PaletteSelection;
+    colors: PaletteColors;
+    mode: PaletteMode;
+}>;
+/**
+ * Derives the bounded, lossless compatibility baseline for a resolved
+ * authoritative selection. Site palettes retain their complete colours,
+ * using a preferred same-mode curated base when possible and a stable
+ * same-mode fallback otherwise.
+ */
+export declare function derivePaletteCompatibilityBaseline(input: ResolvedPaletteForLegacyProjection & Readonly<{
+    preferredCuratedPaletteId?: CuratedPaletteId | null;
+}>): PaletteCompatibilityBaseline;
+/**
+ * One-way egress adapter for stale clients. It accepts canonical compatibility
+ * state only; its lossy curated-plus-overrides response is never a transition
+ * input.
+ */
+export declare function projectPaletteCompatibilityStateForLegacyResponse(state: PaletteCompatibilityState, preferredCuratedPaletteId?: CuratedPaletteId | null): LegacyPaletteResponseProjection;
+/**
+ * Projects runtime state without letting stale legacy columns override an
+ * explicit new authority. Unmigrated rows preserve their validated legacy
+ * identity so mixed-version clients do not receive an unnecessary rewrite.
+ */
+export declare function projectRuntimePaletteStateForLegacyResponse(input: Readonly<{
+    runtimePaletteState: RuntimePaletteState | null;
+    persistenceRead: PalettePersistenceReadResult | null;
+    /**
+     * Parsed independently from active authority. A valid persisted request
+     * baseline remains the exact legacy egress value after a migrated reload.
+     */
+    legacyRequestBaseline: LegacyPaletteRequestBaseline | null;
+}>): LegacyPaletteResponseProjection;
+export {};

package/dist/_dts/theme-core/src/palette/legacySelection.d.ts

@@ -0,0 +1,34 @@
+import type { Theme } from '../schema';
+import { type PaletteTokenName } from '../tokens/themeColorTokens';
+import { type HexColor, type PaletteColors, type PaletteMode } from './colors';
+import type { CuratedPalette, CuratedPaletteId, PaletteOverrides } from './curated/types';
+import type { SitePaletteOrigin } from './selection';
+export type LegacyPaletteClassification = Readonly<{
+    kind: 'curated';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: Extract<SitePaletteOrigin, {
+        kind: 'onboarding' | 'legacy-customized';
+    }>;
+}> | Readonly<{
+    kind: 'defaulted-curated';
+    paletteId: CuratedPaletteId;
+    reason: 'no-valid-legacy-palette';
+}> | Readonly<{
+    kind: 'unresolved';
+    reason: 'missing-palette-sources' | 'invalid-saved-theme-palette' | 'overrides-without-base-palette';
+}>;
+export type LegacyOnboardingPaletteEvidence = Readonly<{
+    sourceKey: string | null;
+    candidateColors: Readonly<Partial<Record<PaletteTokenName, HexColor>>> | null;
+}>;
+export declare function classifyLegacyPaletteSelection(input: Readonly<{
+    basePalette: CuratedPalette | null;
+    overrides: PaletteOverrides | null;
+    savedThemePalette: Theme['palette'] | null;
+    fallbackPaletteId: CuratedPaletteId | null;
+    onboardingEvidence: LegacyOnboardingPaletteEvidence;
+}>): LegacyPaletteClassification;

package/dist/_dts/theme-core/src/palette/libraryModel.d.ts

@@ -0,0 +1,58 @@
+import type { CuratedPalette, CuratedPaletteId } from './curated/types';
+import type { PaletteColors, PaletteMode } from './colors';
+import type { PaletteSelection, SitePalette, SitePaletteId, SitePaletteOrigin, SitePaletteVersion } from './selection';
+export type PaletteSwatch = readonly [
+    PaletteColors['background'],
+    PaletteColors['surface'],
+    PaletteColors['primary'],
+    PaletteColors['secondary'],
+    PaletteColors['accent']
+];
+export type CuratedPaletteLibraryItem = Readonly<{
+    kind: 'curated';
+    paletteId: CuratedPaletteId;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    swatch: PaletteSwatch;
+    accessibleLabel: string;
+    selected: boolean;
+}>;
+export type SitePaletteLibraryItem = Readonly<{
+    kind: 'site';
+    paletteId: SitePaletteId;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: SitePaletteOrigin;
+    version: SitePaletteVersion;
+    swatch: PaletteSwatch;
+    accessibleLabel: string;
+    selected: boolean;
+}>;
+export type PaletteLibraryItem = CuratedPaletteLibraryItem | SitePaletteLibraryItem;
+export type PaletteLibraryReadModel = Readonly<{
+    activeSelection: PaletteSelection;
+    yours: readonly SitePaletteLibraryItem[];
+    suggested: readonly CuratedPaletteLibraryItem[];
+    more: readonly CuratedPaletteLibraryItem[];
+}>;
+export type PaletteLibraryReadModelError = Readonly<{
+    kind: 'active-curated-palette-missing';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'active-site-palette-missing';
+    paletteId: SitePaletteId;
+}>;
+export type PaletteLibraryReadModelResult = Readonly<{
+    ok: true;
+    model: PaletteLibraryReadModel;
+}> | Readonly<{
+    ok: false;
+    error: PaletteLibraryReadModelError;
+}>;
+export declare function buildPaletteLibraryReadModel(input: Readonly<{
+    activeSelection: PaletteSelection;
+    sitePalettes: readonly SitePalette[];
+    curatedPalettes: readonly CuratedPalette[];
+    recommendations: readonly CuratedPaletteId[];
+}>): PaletteLibraryReadModelResult;
+export declare function paletteSelectionForItem(item: PaletteLibraryItem): PaletteSelection;

package/dist/_dts/theme-core/src/palette/paletteCompatibilityTransition.d.ts

@@ -0,0 +1,232 @@
+import { type PaletteColors, type PaletteMode } from './colors';
+import { type CuratedPaletteId, type PaletteOverrides } from './curated';
+import type { LegacyPaletteClassification } from './legacySelection';
+import { type ResolvedCuratedPaletteSelection, type ResolvedPaletteSelection, type ResolvedSitePaletteSelection } from './resolveSelection';
+import type { PaletteSelection, SitePalette, SitePaletteOrigin, TrustedPaletteCommand } from './selection';
+import type { CompatibleThemePalette } from './themePaletteCompatibility';
+export type ResolvedCompatibilityPalette = Readonly<{
+    colors: PaletteColors;
+    mode: PaletteMode;
+}>;
+export type MaterializedSitePaletteTarget = Readonly<{
+    kind: 'materialized-site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+}>;
+/** A legacy PATCH field has an explicit operation; null is only a value at the wire boundary. */
+export type LegacyPaletteFieldPatch<Value> = Readonly<{
+    kind: 'preserve';
+}> | Readonly<{
+    kind: 'clear';
+}> | Readonly<{
+    kind: 'set';
+    value: Value;
+}>;
+export type LegacyPaletteSavePatch = Readonly<{
+    paletteVariantId: LegacyPaletteFieldPatch<CuratedPaletteId>;
+    paletteOverrides: LegacyPaletteFieldPatch<PaletteOverrides>;
+}>;
+declare const persistedLegacyPaletteRequestEvidenceBrand: unique symbol;
+/**
+ * Validated evidence read from the persisted legacy columns. This is ingress
+ * data only: it deliberately cannot be confused with a legacy response
+ * projection or a resolved palette.
+ */
+export type PersistedLegacyPaletteRequestEvidence = Readonly<{
+    paletteVariantId: CuratedPaletteId;
+    paletteOverrides: PaletteOverrides | null;
+    [persistedLegacyPaletteRequestEvidenceBrand]: true;
+}>;
+export type LegacyPaletteRequestBaselineError = Readonly<{
+    kind: 'missing-curated-palette';
+}> | Readonly<{
+    kind: 'unknown-curated-palette';
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-palette-overrides';
+}>;
+/**
+ * The request baseline is intentionally not inferred from compatibility state.
+ * Existing records either carry their persisted legacy evidence or state why it
+ * cannot be used. Only a genuinely new record may use the absent variant.
+ */
+export type LegacyPaletteRequestBaseline = Readonly<{
+    kind: 'persisted';
+    evidence: PersistedLegacyPaletteRequestEvidence;
+}> | Readonly<{
+    kind: 'absent';
+}> | Readonly<{
+    kind: 'unusable';
+    error: LegacyPaletteRequestBaselineError;
+}>;
+/** Parses legacy persistence columns into branded request-side evidence. */
+export declare function parsePersistedLegacyPaletteRequestBaseline(input: Readonly<{
+    paletteVariantId: unknown;
+    paletteOverrides: unknown;
+}>): LegacyPaletteRequestBaseline;
+/** Marks the one case where request omission may use creation fallback values. */
+export declare function absentLegacyPaletteRequestBaseline(): LegacyPaletteRequestBaseline;
+/** Wraps already validated, branded persistence evidence for PATCH normalization. */
+export declare function legacyPaletteRequestBaselineFromPersistedEvidence(evidence: PersistedLegacyPaletteRequestEvidence): LegacyPaletteRequestBaseline;
+declare const legacyPaletteSaveSelectionBrand: unique symbol;
+/** A complete legacy save request after PATCH fields have been normalized. */
+export type LegacyPaletteSaveSelection = Readonly<{
+    paletteVariantId: CuratedPaletteId;
+    paletteOverrides: PaletteOverrides | null;
+    [legacyPaletteSaveSelectionBrand]: true;
+}>;
+export type LegacyPaletteSaveNormalizationError = Readonly<{
+    kind: 'missing-base-palette';
+}>;
+export type LegacyPaletteSaveNormalizationResult = Readonly<{
+    ok: true;
+    selection: LegacyPaletteSaveSelection;
+}> | Readonly<{
+    ok: false;
+    error: LegacyPaletteSaveNormalizationError;
+}>;
+export type LegacyResolvedPaletteSelection = Readonly<{
+    kind: 'curated';
+    selection: Extract<PaletteSelection, {
+        kind: 'curated';
+    }>;
+    colors: PaletteColors;
+    mode: PaletteMode;
+}> | Readonly<{
+    kind: 'site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: Extract<SitePaletteOrigin, {
+        kind: 'onboarding' | 'legacy-customized';
+    }>;
+}>;
+export type PaletteCompatibilityStateError = Readonly<{
+    kind: 'invalid-authoritative-selection';
+}> | Readonly<{
+    kind: 'invalid-legacy-evidence';
+    reason: 'unknown-curated-palette';
+}> | Readonly<{
+    kind: 'unresolved-legacy-selection';
+    reason: Extract<LegacyPaletteClassification, {
+        kind: 'unresolved';
+    }>['reason'];
+}> | Readonly<{
+    kind: 'defaulted-legacy-selection';
+    paletteId: CuratedPaletteId;
+}>;
+export type PaletteCompatibilityState = Readonly<{
+    kind: 'authoritative';
+    resolved: ResolvedPaletteSelection;
+}> | Readonly<{
+    kind: 'legacy-unmigrated';
+    resolved: LegacyResolvedPaletteSelection;
+}> | Readonly<{
+    kind: 'uninitialized';
+}> | Readonly<{
+    kind: 'invalid';
+    error: PaletteCompatibilityStateError;
+}>;
+export type PaletteCompatibilityIntent = Readonly<{
+    kind: 'preserve';
+}> | Readonly<{
+    kind: 'current-command';
+    command: TrustedPaletteCommand;
+    selectedSitePalette: SitePalette | null;
+}> | Readonly<{
+    kind: 'legacy-save';
+    selection: LegacyPaletteSaveSelection;
+}> | Readonly<{
+    kind: 'theme-palette-save';
+    themePalette: CompatibleThemePalette;
+    fallbackCuratedPaletteId: CuratedPaletteId | null;
+}>;
+export type PaletteCompatibilityTransitionError = Readonly<{
+    kind: 'invalid-state';
+    error: PaletteCompatibilityStateError;
+}> | Readonly<{
+    kind: 'missing-base-palette';
+}> | Readonly<{
+    kind: 'unknown-curated-palette';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'missing-selected-site-palette';
+    paletteId: Extract<PaletteSelection, {
+        kind: 'site';
+    }>['paletteId'];
+}> | Readonly<{
+    kind: 'selected-site-palette-mismatch';
+    expectedPaletteId: Extract<PaletteSelection, {
+        kind: 'site';
+    }>['paletteId'];
+    receivedPaletteId: SitePalette['id'];
+}> | Readonly<{
+    kind: 'site-update-not-authoritative';
+}> | Readonly<{
+    kind: 'site-update-palette-mismatch';
+    expectedPaletteId: SitePalette['id'];
+    receivedPaletteId: SitePalette['id'];
+}> | Readonly<{
+    kind: 'stale-site-palette-update';
+    paletteId: SitePalette['id'];
+}>;
+/**
+ * This is deliberately a correlated ADT rather than a command/target product.
+ * Every variant carries only the target evidence that its action can legally use.
+ */
+export type PaletteCompatibilityTransitionPlan = Readonly<{
+    kind: 'preserve-curated';
+    command: Extract<TrustedPaletteCommand, {
+        kind: 'preserve';
+    }>;
+    target: ResolvedCuratedPaletteSelection;
+}> | Readonly<{
+    kind: 'preserve-existing-site';
+    command: Extract<TrustedPaletteCommand, {
+        kind: 'preserve';
+    }>;
+    target: ResolvedSitePaletteSelection;
+}> | Readonly<{
+    kind: 'select-curated';
+    command: Extract<TrustedPaletteCommand, {
+        kind: 'select';
+    }>;
+    target: ResolvedCuratedPaletteSelection;
+}> | Readonly<{
+    kind: 'select-existing-site';
+    command: Extract<TrustedPaletteCommand, {
+        kind: 'select';
+    }>;
+    target: ResolvedSitePaletteSelection;
+}> | Readonly<{
+    kind: 'create-site';
+    command: Extract<TrustedPaletteCommand, {
+        kind: 'create-site';
+    }>;
+    target: MaterializedSitePaletteTarget;
+}> | Readonly<{
+    kind: 'update-existing-site';
+    command: Extract<TrustedPaletteCommand, {
+        kind: 'update-site';
+    }>;
+    target: ResolvedSitePaletteSelection;
+}>;
+export type PaletteCompatibilityTransitionResult = Readonly<{
+    ok: true;
+    plan: PaletteCompatibilityTransitionPlan;
+}> | Readonly<{
+    ok: false;
+    error: PaletteCompatibilityTransitionError;
+}>;
+export declare function paletteCompatibilityStateFromLegacyClassification(classification: LegacyPaletteClassification): PaletteCompatibilityState;
+/**
+ * Applies independent PATCH operations at the legacy ingress boundary. A
+ * fallback supplies omitted fields only for explicitly uninitialized creation;
+ * an explicit variant clear always selects the caller-supplied fallback.
+ */
+export declare function normalizeLegacyPaletteSavePatch(input: Readonly<{
+    patch: LegacyPaletteSavePatch;
+    baseline: LegacyPaletteRequestBaseline;
+    fallbackCuratedPaletteId: CuratedPaletteId | null;
+}>): LegacyPaletteSaveNormalizationResult;
+export declare function planPaletteTransition(state: PaletteCompatibilityState, intent: PaletteCompatibilityIntent): PaletteCompatibilityTransitionResult;
+export {};

package/dist/_dts/theme-core/src/palette/persistenceReadSource.d.ts

@@ -0,0 +1,118 @@
+import { type CuratedPaletteId, type PaletteOverrides } from './curated';
+import type { Theme } from '../schema';
+import type { PaletteSelection } from './selection';
+import { type SitePalette } from './selection';
+import { resolvedCuratedPaletteSelection, resolvedSitePaletteSelection, type ResolvedPaletteSelection } from './resolveSelection';
+import type { SitePaletteParseError } from './sitePalettePersistence';
+export type PalettePersistenceReadSource = Readonly<{
+    kind: 'new-selection';
+    selection: PaletteSelection;
+}> | Readonly<{
+    kind: 'legacy-selection';
+    paletteVariant: LegacyPaletteVariantEvidence;
+    paletteOverrides: PaletteOverrides | null;
+}>;
+/** Legacy catalog IDs are migration evidence, not authoritative references. */
+export type LegacyPaletteVariantEvidence = Readonly<{
+    kind: 'known';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'unknown';
+    value: string;
+}> | Readonly<{
+    kind: 'missing';
+}>;
+export type PalettePersistenceReadError = Readonly<{
+    kind: 'dual-active-reference';
+}> | Readonly<{
+    kind: 'unknown-active-curated-palette';
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-active-site-palette-id';
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-legacy-overrides';
+}>;
+export type PalettePersistenceReadResult = Readonly<{
+    ok: true;
+    source: PalettePersistenceReadSource;
+}> | Readonly<{
+    ok: false;
+    error: PalettePersistenceReadError;
+}>;
+/**
+ * Transport state remains flat for existing runtime consumers. Its migrated
+ * variants are nevertheless correlated: `authority`, selection, and version
+ * cannot describe independent sources of truth.
+ */
+export type RuntimePaletteState = Readonly<{
+    kind: 'migrated';
+    authority: 'curated';
+    selection: Extract<PaletteSelection, {
+        kind: 'curated';
+    }>;
+    colors: ReturnType<typeof resolvedCuratedPaletteSelection>['colors'];
+    mode: ReturnType<typeof resolvedCuratedPaletteSelection>['mode'];
+    sitePaletteVersion: null;
+}> | Readonly<{
+    kind: 'migrated';
+    authority: 'site';
+    selection: Extract<PaletteSelection, {
+        kind: 'site';
+    }>;
+    colors: ReturnType<typeof resolvedSitePaletteSelection>['colors'];
+    mode: ReturnType<typeof resolvedSitePaletteSelection>['mode'];
+    sitePaletteVersion: ReturnType<typeof resolvedSitePaletteSelection>['version'];
+}> | Readonly<{
+    kind: 'legacy-unmigrated';
+    colors: ResolvedPaletteSelection['colors'];
+    mode: ResolvedPaletteSelection['mode'];
+}> | Readonly<{
+    kind: 'invalid';
+    reason: PalettePersistenceReadError['kind'] | 'invalid-saved-theme-palette' | 'active-site-palette-missing' | 'invalid-active-site-palette' | 'active-site-palette-mismatch' | 'active-curated-palette-missing';
+}>;
+export type ActiveSitePaletteAuthority = Readonly<{
+    kind: 'missing';
+}> | Readonly<{
+    kind: 'malformed';
+    error: SitePaletteParseError;
+}> | Readonly<{
+    kind: 'resolved';
+    palette: SitePalette;
+}>;
+export type RuntimePaletteResolutionError = Readonly<{
+    kind: 'runtime-curated-palette-missing';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'runtime-curated-palette-mismatch';
+    paletteId: CuratedPaletteId;
+}>;
+export type RuntimePaletteResolution = Readonly<{
+    ok: true;
+    resolved: ResolvedPaletteSelection;
+}> | Readonly<{
+    ok: false;
+    error: RuntimePaletteResolutionError;
+}>;
+/**
+ * Rehydrates a runtime transport payload through the core-owned constructors.
+ * It is intentionally checked, and replaces the old unsafe brand cast bridge.
+ */
+export declare function resolveMigratedRuntimePaletteState(state: Extract<RuntimePaletteState, {
+    kind: 'migrated';
+}>): RuntimePaletteResolution;
+export declare function runtimePaletteStateFromPersisted(input: Readonly<{
+    parsed: PalettePersistenceReadResult;
+    savedThemePalette: Theme['palette'];
+    activeSitePaletteAuthority: ActiveSitePaletteAuthority;
+}>): RuntimePaletteState;
+/**
+ * Bounded rollout adapter. New active references are authoritative whenever
+ * present; legacy fields are parsed only while both references are absent.
+ */
+export declare function parsePalettePersistenceReadSource(input: Readonly<{
+    activeCuratedPaletteId: string | null;
+    activeSitePaletteId: string | null;
+    legacyPaletteVariantId: string | null;
+    legacyPaletteOverrides: unknown;
+}>): PalettePersistenceReadResult;