@riverbankcms/sdk 0.102.0 → 0.104.0

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

@@ -0,0 +1,241 @@
+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;
+}>;
+declare const legacyPaletteRequestBaselineUpdateBrand: unique symbol;
+/** A normalized legacy request snapshot, persisted only with a successful save. */
+export type LegacyPaletteRequestBaselineUpdate = Readonly<{
+    paletteVariantId: CuratedPaletteId;
+    paletteOverrides: PaletteOverrides | null;
+    [legacyPaletteRequestBaselineUpdateBrand]: 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;
+/** Separates a legacy request-baseline write from the palette command ADT. */
+export declare function legacyPaletteRequestBaselineUpdateFromSelection(selection: LegacyPaletteSaveSelection): LegacyPaletteRequestBaselineUpdate;
+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;

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

@@ -0,0 +1,50 @@
+import type { PaletteColors, PaletteMode } from './colors';
+import { type CuratedPalette, type CuratedPaletteId } from './curated';
+import type { PaletteSelection, SitePalette, SitePaletteId } from './selection';
+declare const resolvedPaletteSelectionBrand: unique symbol;
+export type ResolvedCuratedPaletteSelection = Readonly<{
+    kind: 'curated';
+    selection: Extract<PaletteSelection, {
+        kind: 'curated';
+    }>;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    [resolvedPaletteSelectionBrand]: true;
+}>;
+export type ResolvedSitePaletteSelection = Readonly<{
+    kind: 'site';
+    selection: Extract<PaletteSelection, {
+        kind: 'site';
+    }>;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    version: SitePalette['version'];
+    [resolvedPaletteSelectionBrand]: true;
+}>;
+export type ResolvedPaletteSelection = ResolvedCuratedPaletteSelection | ResolvedSitePaletteSelection;
+export type PaletteSelectionResolutionError = Readonly<{
+    kind: 'curated-palette-not-found';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'site-palette-not-found';
+    paletteId: SitePaletteId;
+}>;
+export type PaletteSelectionResolution = Readonly<{
+    ok: true;
+    resolved: ResolvedPaletteSelection;
+}> | Readonly<{
+    ok: false;
+    error: PaletteSelectionResolutionError;
+}>;
+/** Core-owned constructors keep the resolved marker out of application code. */
+export declare function resolvedCuratedPaletteSelection(palette: CuratedPalette): ResolvedCuratedPaletteSelection;
+export declare function resolvedSitePaletteSelection(palette: SitePalette): ResolvedSitePaletteSelection;
+/** Resolves a persisted selection against the records that actually own it. */
+export declare function resolvePaletteSelection(input: Readonly<{
+    selection: PaletteSelection;
+    curatedPalettes: readonly CuratedPalette[];
+    sitePalettes: readonly SitePalette[];
+}>): PaletteSelectionResolution;
+/** Resolves catalog authority without asking callers to manufacture a brand. */
+export declare function resolveCuratedPaletteSelection(paletteId: CuratedPaletteId): PaletteSelectionResolution;
+export {};

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

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { type CuratedPaletteId } from './curated/types';
+import { type PaletteColors, type PaletteMode } from './colors';
+export type SitePaletteId = string & {
+    readonly __brand: 'SitePaletteId';
+};
+export type SitePaletteVersion = number & {
+    readonly __brand: 'SitePaletteVersion';
+};
+export declare const sitePaletteIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SitePaletteId, string>>;
+export declare const sitePaletteVersionSchema: z.ZodPipe<z.ZodNumber, z.ZodTransform<SitePaletteVersion, number>>;
+export declare function parseSitePaletteId(value: unknown): SitePaletteId | null;
+export declare function parseSitePaletteVersion(value: unknown): SitePaletteVersion | null;
+export type PaletteSelection = Readonly<{
+    kind: 'curated';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'site';
+    paletteId: SitePaletteId;
+}>;
+export declare const paletteSelectionSchema: z.ZodType<PaletteSelection>;
+export type SitePaletteOrigin = Readonly<{
+    kind: 'onboarding';
+    sourceKey: string | null;
+}> | Readonly<{
+    kind: 'curated-fork';
+    sourcePaletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'manual';
+}> | Readonly<{
+    kind: 'legacy-customized';
+    sourceKey: string | null;
+}>;
+export declare const sitePaletteOriginSchema: z.ZodType<SitePaletteOrigin>;
+export type EditorSitePaletteOrigin = Extract<SitePaletteOrigin, {
+    kind: 'curated-fork';
+}> | Extract<SitePaletteOrigin, {
+    kind: 'manual';
+}>;
+export type SitePalette = Readonly<{
+    id: SitePaletteId;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: SitePaletteOrigin;
+    version: SitePaletteVersion;
+}>;
+export declare const sitePaletteSchema: z.ZodType<SitePalette>;
+export type PaletteCommand = Readonly<{
+    kind: 'preserve';
+}> | Readonly<{
+    kind: 'select';
+    selection: PaletteSelection;
+}> | Readonly<{
+    kind: 'create-site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: EditorSitePaletteOrigin;
+}> | Readonly<{
+    kind: 'update-site';
+    paletteId: SitePaletteId;
+    expectedVersion: SitePaletteVersion;
+    colors: PaletteColors;
+    mode: PaletteMode;
+}>;
+/** Server-only command shape for provisioning and legacy write-through. */
+export type TrustedPaletteCommand = PaletteCommand | Readonly<{
+    kind: 'create-site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: SitePaletteOrigin;
+}>;
+export declare const paletteCommandSchema: z.ZodType<PaletteCommand>;

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

@@ -0,0 +1,34 @@
+import { type SitePalette } from './selection';
+/** Structural persistence shape shared by every site-palette reader. */
+export type SitePalettePersistenceRow = Readonly<{
+    id: string;
+    colors: unknown;
+    mode: string;
+    originKind: string;
+    originReference: string | null;
+    version: number;
+}>;
+export type SitePaletteParseError = Readonly<{
+    kind: 'invalid-site-palette-id';
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-site-palette-colors';
+}> | Readonly<{
+    kind: 'invalid-site-palette-mode';
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-site-palette-origin';
+    originKind: string;
+    originReference: string | null;
+}> | Readonly<{
+    kind: 'invalid-site-palette-version';
+    value: number;
+}>;
+export type SitePaletteParseResult = Readonly<{
+    ok: true;
+    palette: SitePalette;
+}> | Readonly<{
+    ok: false;
+    error: SitePaletteParseError;
+}>;
+export declare function parseSitePalettePersistenceRow(row: SitePalettePersistenceRow): SitePaletteParseResult;

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

@@ -0,0 +1,58 @@
+import { type PaletteTokenName } from '../tokens/themeColorTokens';
+import { type PaletteColors, type PaletteMode } from './colors';
+import type { PaletteOverrides } from './curated';
+/**
+ * The persisted Theme palette boundary. It deliberately stays narrower than
+ * the full Theme schema so consumers do not need to depend on another package
+ * just to interpret old sparse palette entries.
+ */
+export type ThemePaletteCompatibilityInput = Readonly<{
+    palette?: Readonly<{
+        colors: readonly Readonly<{
+            name: string;
+            hex: string;
+        }>[];
+        meta?: Readonly<{
+            mode?: unknown;
+        }> | null;
+    }> | null;
+}>;
+export type ThemePaletteCompatibilityError = Readonly<{
+    kind: 'missing-palette';
+}> | Readonly<{
+    kind: 'invalid-mode';
+}> | Readonly<{
+    kind: 'unknown-role';
+    role: string;
+}> | Readonly<{
+    kind: 'duplicate-role';
+    role: PaletteTokenName;
+}> | Readonly<{
+    kind: 'invalid-color';
+    role: PaletteTokenName;
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-complete-palette';
+}>;
+export type CompatibleThemePalette = Readonly<{
+    kind: 'complete';
+    colors: PaletteColors;
+    mode: PaletteMode;
+}> | Readonly<{
+    kind: 'partial';
+    overrides: PaletteOverrides;
+    mode: PaletteMode;
+}>;
+export type ParseCompatibleThemePaletteResult = Readonly<{
+    ok: true;
+    palette: CompatibleThemePalette;
+}> | Readonly<{
+    ok: false;
+    error: ThemePaletteCompatibilityError;
+}>;
+/**
+ * Parses both current complete Theme palettes and historical sparse palettes.
+ * Sparse entries remain sparse so callers can overlay them onto their own
+ * authoritative base without silently changing the persisted Theme shape.
+ */
+export declare function parseCompatibleThemePalette(theme: ThemePaletteCompatibilityInput): ParseCompatibleThemePaletteResult;