react-native-terra-ui 0.7.2 → 0.8.1

package/lib/typescript/src/theme/resolve-config.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Pure theme resolution — normalization, layer processing, derived values and
+ * theme creation. Shared by startup configuration, runtime accent changes and
+ * previews so every consumer sees the same colors for the same input.
+ *
+ * Precedence, identical for both schemes:
+ *
+ *   default tokens → shared → schemes[scheme]
+ *       → generated selected accent → selected accent explicit overrides
+ *
+ * This module must stay free of registry, provider, Unistyles and renderer
+ * imports so `createTerraThemes` works without any native configuration.
+ */
+import { type ContrastDiagnostic } from "../utils/accent-generator";
+import { type ThemeSource } from "./theme.js";
+import type { AccentSchemeInput, CreateTerraThemesOptions, ElevationKey, Scheme, TerraTheme, TerraThemeInput, TerraThemeOverride, ThemeColor } from "./types.js";
+/**
+ * A theme mid-resolution: its source form plus provenance for every elevation
+ * level whose `shadowColor` a layer pinned explicitly. Default shadow colors are
+ * derived, never pinned, so a later `color.shadow` override still moves them.
+ */
+export interface ThemeLayerState {
+    readonly source: ThemeSource;
+    readonly pinnedShadowColors: Readonly<Partial<Record<ElevationKey, string>>>;
+}
+/**
+ * Applies one override layer onto `state` and returns the next state. Every
+ * layer — shared, scheme, generated accent, accent overrides, or a full accent
+ * patch — goes through here, so they all follow the same rules:
+ * - deprecated names are normalized within the layer (canonical wins);
+ * - `undefined`/`null` leaves are no override; arrays replace; objects merge;
+ * - `spacing.base` / `radius.base` regenerate their scale, then that layer's
+ *   explicit steps win over the regenerated values;
+ * - `elevation.<level>.shadowColor` pins that level (a later pin replaces an
+ *   earlier one); other elevation fields merge normally.
+ * Inputs are never mutated.
+ */
+export declare function applyThemeLayer(state: ThemeLayerState, override?: TerraThemeOverride): ThemeLayerState;
+export type NormalizedAccentScheme = {
+    readonly kind: "none";
+} | {
+    readonly kind: "seed";
+    readonly seed: string;
+    readonly overrides?: Partial<ThemeColor>;
+} | {
+    readonly kind: "patch";
+    readonly patch: TerraThemeOverride;
+};
+interface NormalizedAccentEntry {
+    readonly light: NormalizedAccentScheme;
+    readonly dark: NormalizedAccentScheme;
+}
+/**
+ * A validated, immutable theme configuration. `base` is the fully layered
+ * `defaults → shared → scheme` state per scheme; every accent selection is
+ * re-resolved from it rather than from a previously resolved accent.
+ */
+export interface NormalizedThemeConfig {
+    readonly accentNames: readonly string[];
+    readonly defaultAccent: string | null;
+    /** @internal Immutable `defaults → shared → scheme` state per scheme. */
+    readonly base: Readonly<Record<Scheme, ThemeLayerState>>;
+    /** @internal Per-accent, per-scheme normalized inputs. */
+    readonly accents: Readonly<Record<string, NormalizedAccentEntry>>;
+}
+export declare function normalizeAccentScheme(input: AccentSchemeInput | undefined, path: string): NormalizedAccentScheme;
+/**
+ * Validates a theme input and pre-computes the immutable per-scheme base
+ * (`defaults → shared → scheme`). Throws {@link TerraConfigError} for invalid
+ * input — before any state exists to mutate. Never mutates `input` or the
+ * exported defaults.
+ */
+export declare function normalizeThemeInput(input?: TerraThemeInput): NormalizedThemeConfig;
+export interface ResolvedThemes {
+    themes: Record<Scheme, TerraTheme>;
+    /** Final-colour contrast pairs that fail or cannot be evaluated, across both schemes. */
+    diagnostics: ContrastDiagnostic[];
+}
+/**
+ * Resolves both schemes for `accent` from the config's immutable base. `null`
+ * selects the base themes; an unknown name throws {@link TerraConfigError}.
+ * Returned themes are freshly built and independently owned.
+ */
+export declare function resolveThemes(config: NormalizedThemeConfig, accent: string | null): ResolvedThemes;
+/** Resolves one scheme without generating and finalizing the other. */
+export declare function resolveThemeScheme(config: NormalizedThemeConfig, scheme: Scheme, accent: string | null): {
+    theme: TerraTheme;
+    diagnostics: ContrastDiagnostic[];
+};
+/**
+ * Pure theme creation — no Unistyles configuration or registry involved.
+ * `options.accent` omitted → the input's `defaultAccent`; `null` → the base
+ * themes. Invalid input and unknown accents throw {@link TerraConfigError}.
+ * In development, contrast diagnostics are reported once each via
+ * `console.warn`; requested colors are never altered.
+ */
+export declare function createTerraThemes(input?: TerraThemeInput, options?: CreateTerraThemesOptions): Record<Scheme, TerraTheme>;
+export {};
+//# sourceMappingURL=resolve-config.d.ts.map

package/lib/typescript/src/theme/resolve-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-config.d.ts","sourceRoot":"","sources":["../../../../src/theme/resolve-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAGL,KAAK,kBAAkB,EAMxB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,YAAS,CAAC;AACjB,OAAO,KAAK,EAEV,iBAAiB,EACjB,wBAAwB,EACxB,YAAY,EACZ,MAAM,EACN,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,UAAU,EACX,MAAM,YAAS,CAAC;AAajB;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CAC9E;AAsBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,eAAe,CAuCtG;AAID,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAA;CAAE,GAC1F;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEnE,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IACzD,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;CACnE;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,GAAG,SAAS,EACpC,IAAI,EAAE,MAAM,GACX,sBAAsB,CAoDxB;AAmBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,eAAoB,GAAG,qBAAqB,CAyCtF;AAID,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,yFAAyF;IACzF,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AA+DD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAYlG;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAG1D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAQ5B"}

package/lib/typescript/src/theme/runtime.d.ts

@@ -1,7 +1,28 @@
-import type { Scheme } from "./types.js";
-/** Apply a named accent at runtime by updating both registered themes. */
-export declare function applyAccent(name: string): void;
+import type { Scheme, ThemeMode } from "./types.js";
+export type { ThemeSelection } from "./selection-store.js";
+export { getThemeSelection, subscribeThemeSelection } from "./selection-store.js";
+/**
+ * Apply a registered accent (`null` restores the base themes) by updating both
+ * registered themes. An unknown name warns in development and changes nothing.
+ *
+ * If the native update fails part-way (see `updateThemes` in the adapter), the
+ * error propagates and the previous selection stays published; calling
+ * `applyAccent(getCurrentAccent() ?? null)` rewrites both themes.
+ */
+export declare function applyAccent(name: string | null): void;
+/** The applied accent name, or `undefined` for the base themes. */
 export declare const getCurrentAccent: () => string | undefined;
-/** Switch the active color scheme, disabling adaptive (system) theming. */
+/**
+ * Choose how the active scheme is selected: `system` follows the OS appearance;
+ * `light` / `dark` pin a scheme until the next call.
+ */
+export declare function setThemeMode(mode: ThemeMode): void;
+/** The current theme mode. A system appearance change does not change it. */
+export declare const getThemeMode: () => ThemeMode;
+/**
+ * Pin the active color scheme, disabling adaptive (system) theming.
+ * Compatibility wrapper for `setThemeMode(scheme)`; use `setThemeMode("system")`
+ * to return to the OS preference.
+ */
 export declare function applyScheme(scheme: Scheme): void;
 //# sourceMappingURL=runtime.d.ts.map

package/lib/typescript/src/theme/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/theme/runtime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAS,CAAC;AAEtC,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAW9C;AAED,eAAO,MAAM,gBAAgB,QAAO,MAAM,GAAG,SAAwC,CAAC;AAEtF,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGhD"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/theme/runtime.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAS,CAAC;AAGjD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAmB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,sBAAmB,CAAC;AAE/E;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAarD;AAED,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,QAAO,MAAM,GAAG,SAAuC,CAAC;AAErF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAGlD;AAED,6EAA6E;AAC7E,eAAO,MAAM,YAAY,QAAO,SAAqC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEhD"}

package/lib/typescript/src/theme/screen-margin.d.ts

@@ -1,15 +1,7 @@
-import type { UnistylesBreakpoints } from "react-native-unistyles";
-import type { TerraTheme } from "./types.js";
-export interface ResolvedScreenMargin {
-    x: number;
-    y: number;
-}
-/**
- * Resolves both axes of `theme.layout.screen.margin` for the current runtime
- * breakpoint in one call — nearly every consumer needs both axes, so this
- * saves calling `resolveBreakpointValue` twice. Call inside a
- * `StyleSheet.create` factory (passing `rt.breakpoint`) so the result stays
- * reactive to breakpoint changes; outside one, use {@link useScreenMargin}.
- */
-export declare function resolveScreenMargin(theme: TerraTheme, breakpoint: keyof UnistylesBreakpoints | undefined): ResolvedScreenMargin;
+import type { ResolvedScreenPadding } from "./screen-padding.js";
+import { resolveScreenPadding } from "./screen-padding.js";
+/** @deprecated Use ResolvedScreenPadding. */
+export type ResolvedScreenMargin = ResolvedScreenPadding;
+/** @deprecated Use resolveScreenPadding. */
+export declare const resolveScreenMargin: typeof resolveScreenPadding;
 //# sourceMappingURL=screen-margin.d.ts.map

package/lib/typescript/src/theme/screen-margin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screen-margin.d.ts","sourceRoot":"","sources":["../../../../src/theme/screen-margin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAGnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAE1C,MAAM,WAAW,oBAAoB;IACnC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,oBAAoB,GAAG,SAAS,GACjD,oBAAoB,CAKtB"}
+{"version":3,"file":"screen-margin.d.ts","sourceRoot":"","sources":["../../../../src/theme/screen-margin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAkB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAkB,CAAC;AAExD,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AACzD,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB,6BAAuB,CAAC"}

package/lib/typescript/src/theme/screen-padding.d.ts

@@ -0,0 +1,15 @@
+import type { UnistylesBreakpoints } from "react-native-unistyles";
+import type { TerraTheme } from "./types.js";
+export interface ResolvedScreenPadding {
+    x: number;
+    y: number;
+}
+/**
+ * Resolves both axes of `theme.layout.screen.padding` for the current runtime
+ * breakpoint in one call — nearly every consumer needs both axes, so this
+ * saves calling `resolveBreakpointValue` twice. Call inside a
+ * `StyleSheet.create` factory (passing `rt.breakpoint`) so the result stays
+ * reactive to breakpoint changes; outside one, use {@link useScreenPadding}.
+ */
+export declare function resolveScreenPadding(theme: TerraTheme, breakpoint: keyof UnistylesBreakpoints | undefined): ResolvedScreenPadding;
+//# sourceMappingURL=screen-padding.d.ts.map

package/lib/typescript/src/theme/screen-padding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-padding.d.ts","sourceRoot":"","sources":["../../../../src/theme/screen-padding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAGnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACpC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,oBAAoB,GAAG,SAAS,GACjD,qBAAqB,CAKvB"}

package/lib/typescript/src/theme/selection-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Internal runtime state shared by `registry.ts` (installation) and
+ * `runtime.ts` (selection commands). Lives in its own module so neither of
+ * those has to import the other.
+ *
+ * Holds two things, both private to `theme/`:
+ * - the installed {@link NormalizedThemeConfig} — immutable; every accent
+ *   selection is re-resolved from it, never layered on a previous result;
+ * - the selection snapshot (`accent`, `mode`) behind a `useSyncExternalStore`
+ *   compatible subscribe/get pair. The snapshot object keeps its identity until
+ *   a value actually changes, so subscribers only re-render on real changes.
+ *
+ * Nothing here touches Unistyles. Callers publish *after* native work succeeds.
+ */
+import { type NormalizedThemeConfig } from "./resolve-config.js";
+import type { ThemeMode } from "./types.js";
+/** @internal Read-only handle on the installed config. */
+export declare const getInstalledConfig: () => NormalizedThemeConfig;
+/** @internal Replaces the installed config; only `registry.ts` should call this. */
+export declare function setInstalledConfig(config: NormalizedThemeConfig): void;
+/** The current runtime selection: which accent is applied and how the scheme is chosen. */
+export interface ThemeSelection {
+    /** Applied accent name, or `undefined` for the base themes. */
+    readonly accent: string | undefined;
+    /** `system` follows the OS appearance; `light` / `dark` pin a scheme. */
+    readonly mode: ThemeMode;
+}
+/**
+ * Current selection snapshot. Stable identity: the same object is returned
+ * until {@link publishThemeSelection} commits a real change, which makes it a
+ * valid `getSnapshot` for `useSyncExternalStore`.
+ */
+export declare const getThemeSelection: () => ThemeSelection;
+/** Subscribe to selection changes. Returns the unsubscribe function. */
+export declare function subscribeThemeSelection(listener: () => void): () => void;
+/**
+ * @internal Commits a (partial) selection change and notifies subscribers.
+ * A no-op — same snapshot identity, no notification — when nothing changed.
+ */
+export declare function publishThemeSelection(next: Partial<ThemeSelection>): void;
+//# sourceMappingURL=selection-store.d.ts.map

package/lib/typescript/src/theme/selection-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection-store.d.ts","sourceRoot":"","sources":["../../../../src/theme/selection-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,KAAK,qBAAqB,EAAuB,MAAM,qBAAkB,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAS,CAAC;AAUzC,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,QAAO,qBAAwC,CAAC;AAE/E,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAEtE;AAID,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAMD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAO,cAA2B,CAAC;AAEjE,wEAAwE;AACxE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAKxE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CASzE"}

package/lib/typescript/src/theme/theme.d.ts

@@ -1,4 +1,4 @@
-import type { RadiusKey, SpacingKey, TerraTheme } from "./types.js";
+import type { CanonicalThemeColor, ElevationKey, ElevationScale, ElevationStyle, LayoutTokens, OpacityTokens, RadiusKey, Scheme, ScreenPaddingTokens, SpacingKey, TerraColorRegistry, TerraTheme, Typography } from "./types.js";
 /**
  * Default base corner radius (dp) — the `lg` (×1) step — taken from the
  * `radius.base` primitive. The rest of the scale is derived from it via
@@ -37,6 +37,59 @@ export declare const RADIUS_MULTIPLIERS: Record<Exclude<RadiusKey, "none" | "ful
  * their exact (possibly fractional) dp; `none`/`full` are constant.
  */
 export declare function buildRadiusScale(base?: number): Record<RadiusKey, number>;
+/** Elevation levels as authored: everything except the per-scheme `shadowColor`. */
+export type ThemeSourceElevation = Record<ElevationKey, Omit<ElevationStyle, "shadowColor">>;
+/**
+ * The pre-finalization ("source") form of a theme — what the resolver layers
+ * overrides onto. It differs from {@link TerraTheme} only in what is DERIVED at
+ * the final boundary instead of authored:
+ * - `color` holds canonical (and app-declared custom) keys only; deprecated
+ *   aliases are materialized by {@link finalizeThemeSource}.
+ * - `elevation` levels carry no `shadowColor`; it is derived from `color.shadow`
+ *   (unless explicitly pinned) at finalization.
+ * - `layout.screen` has no `margin` alias; it mirrors `padding` at finalization.
+ */
+export interface ThemeSource {
+    color: CanonicalThemeColor & TerraColorRegistry;
+    spacing: Record<SpacingKey, number>;
+    radius: Record<RadiusKey, number>;
+    typography: Typography;
+    elevation: ThemeSourceElevation;
+    opacity: OpacityTokens;
+    layout: {
+        screen: {
+            padding: ScreenPaddingTokens;
+        };
+        header: LayoutTokens["header"];
+    };
+}
+/**
+ * Structural deep clone for token data (plain objects, arrays and primitives —
+ * the theme never carries functions or class instances). Used so every source
+ * and every finalized theme is independently owned.
+ */
+export declare function cloneTokenTree<T>(value: T): T;
+/**
+ * Builds the built-in default theme for `scheme` in its source form (see
+ * {@link ThemeSource}). Returns a FRESH object on every call, so callers may
+ * layer onto or mutate it without affecting the exported defaults or later
+ * calls. This is the immutable starting point of the resolution pipeline:
+ * `defaults → shared → scheme → accent`.
+ */
+export declare function createDefaultThemeSource(scheme: Scheme): ThemeSource;
+/**
+ * Resolves each elevation level's `shadowColor`: an explicitly pinned
+ * per-level color wins, otherwise the theme's `color.shadow` token is used —
+ * rather than authoring it redundantly on every level in `light.ts` / `dark.ts`.
+ */
+export declare function resolveElevationScale(elevation: ThemeSourceElevation, shadowColor: string, pinnedShadowColors?: Partial<Record<ElevationKey, string>>): ElevationScale;
+/**
+ * Turns a {@link ThemeSource} into a complete, independently owned
+ * {@link TerraTheme}: derives elevation shadow colors (honouring pinned levels)
+ * and materializes every compatibility alias. Neither `source` nor the returned
+ * theme share object references with each other.
+ */
+export declare function finalizeThemeSource(source: ThemeSource, pinnedShadowColors?: Partial<Record<ElevationKey, string>>): TerraTheme;
 export declare const defaultLightTheme: TerraTheme;
 export declare const defaultDarkTheme: TerraTheme;
 //# sourceMappingURL=theme.d.ts.map

package/lib/typescript/src/theme/theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../../src/theme/theme.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAMV,SAAS,EACT,UAAU,EACV,UAAU,EAGX,MAAM,YAAS,CAAC;AA+FjB;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAmB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,EAkBpC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,QAAoB,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAA6B,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAMjG;AAID;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,CAQlF,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAA4B,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAM9F;AAkCD,eAAO,MAAM,iBAAiB,EAAE,UAQ/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UAQ9B,CAAC"}
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../../src/theme/theme.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,YAAY,EACZ,aAAa,EACb,SAAS,EACT,MAAM,EACN,mBAAmB,EACnB,UAAU,EACV,kBAAkB,EAClB,UAAU,EACV,UAAU,EACX,MAAM,YAAS,CAAC;AA+FjB;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAmB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,EAkBpC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,QAAoB,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAA6B,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAMjG;AAID;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,CAQlF,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAA4B,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAM9F;AAOD,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC,CAAC;AAE7F;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,mBAAmB,GAAG,kBAAkB,CAAC;IAChD,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAClC,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,oBAAoB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE;QACN,MAAM,EAAE;YAAE,OAAO,EAAE,mBAAmB,CAAA;SAAE,CAAC;QACzC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;KAChC,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAY7C;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAWpE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,oBAAoB,EAC/B,WAAW,EAAE,MAAM,EACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,GACzD,cAAc,CAMhB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,GACzD,UAAU,CAWZ;AAED,eAAO,MAAM,iBAAiB,EAAE,UAAmE,CAAC;AAEpG,eAAO,MAAM,gBAAgB,EAAE,UAAkE,CAAC"}

package/lib/typescript/src/theme/tokens/canonical-color-keys.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Runtime list of the built-in canonical colour keys.
+ *
+ * `CanonicalThemeColor` (types.ts) is the authoritative schema, but it is a
+ * type and cannot be iterated at runtime. This object mirrors it key-for-key
+ * so the raw-data validator can check `light.ts` / `dark.ts` against the real
+ * schema instead of a hand-maintained regex. The `satisfies` clause makes the
+ * mirror self-checking: a key missing here fails on the `Record<…>`
+ * requirement, and a key that is not in `CanonicalThemeColor` fails the
+ * excess-property check.
+ *
+ * Type-only import — this file stays free of runtime imports like the other
+ * token data.
+ */
+import type { CanonicalThemeColor } from "../types.js";
+declare const CANONICAL_COLOR_KEY_MAP: {
+    readonly "surface.canvas": true;
+    readonly "surface.default": true;
+    readonly "surface.raised": true;
+    readonly "surface.sunken": true;
+    readonly "text.primary": true;
+    readonly "text.secondary": true;
+    readonly "text.tertiary": true;
+    readonly "text.disabled": true;
+    readonly "text.inverse": true;
+    readonly "text.link": true;
+    readonly "border.subtle": true;
+    readonly "border.default": true;
+    readonly "border.strong": true;
+    readonly "focus.ring": true;
+    readonly backdrop: true;
+    readonly shadow: true;
+    readonly "accent.text": true;
+    readonly "accent.border": true;
+    readonly "accent.solid.bg": true;
+    readonly "accent.solid.bg.hover": true;
+    readonly "accent.solid.bg.pressed": true;
+    readonly "accent.solid.bg.disabled": true;
+    readonly "accent.solid.fg": true;
+    readonly "accent.soft.bg": true;
+    readonly "accent.soft.bg.hover": true;
+    readonly "accent.soft.bg.pressed": true;
+    readonly "accent.soft.bg.disabled": true;
+    readonly "accent.soft.fg": true;
+    readonly "neutral.solid.bg": true;
+    readonly "neutral.solid.fg": true;
+    readonly "neutral.soft.bg": true;
+    readonly "neutral.soft.bg.hover": true;
+    readonly "neutral.soft.bg.pressed": true;
+    readonly "neutral.soft.bg.disabled": true;
+    readonly "neutral.soft.fg": true;
+    readonly "success.text": true;
+    readonly "success.solid.bg": true;
+    readonly "success.solid.fg": true;
+    readonly "success.solid.border": true;
+    readonly "success.soft.bg": true;
+    readonly "success.soft.fg": true;
+    readonly "success.soft.border": true;
+    readonly "warning.text": true;
+    readonly "warning.solid.bg": true;
+    readonly "warning.solid.fg": true;
+    readonly "warning.solid.border": true;
+    readonly "warning.soft.bg": true;
+    readonly "warning.soft.fg": true;
+    readonly "warning.soft.border": true;
+    readonly "danger.text": true;
+    readonly "danger.solid.bg": true;
+    readonly "danger.solid.fg": true;
+    readonly "danger.solid.border": true;
+    readonly "danger.soft.bg": true;
+    readonly "danger.soft.fg": true;
+    readonly "danger.soft.border": true;
+    readonly "info.text": true;
+    readonly "info.solid.bg": true;
+    readonly "info.solid.fg": true;
+    readonly "info.solid.border": true;
+    readonly "info.soft.bg": true;
+    readonly "info.soft.fg": true;
+    readonly "info.soft.border": true;
+};
+/**
+ * Every built-in canonical colour key (without the `color.` category prefix
+ * used by the raw token files). Exhaustive and extra-free by construction —
+ * see {@link CANONICAL_COLOR_KEY_MAP}.
+ */
+export declare const CANONICAL_COLOR_KEYS: readonly (keyof CanonicalThemeColor)[];
+/** Type-level guard that the map's literal keys and the schema's keys are the same set. */
+type MissingCanonicalKey = Exclude<keyof CanonicalThemeColor, keyof typeof CANONICAL_COLOR_KEY_MAP>;
+type ExtraCanonicalKey = Exclude<keyof typeof CANONICAL_COLOR_KEY_MAP, keyof CanonicalThemeColor>;
+export type CanonicalColorKeysAreExhaustive = [MissingCanonicalKey, ExtraCanonicalKey] extends [never, never] ? true : {
+    missing: MissingCanonicalKey;
+    extra: ExtraCanonicalKey;
+};
+export {};
+//# sourceMappingURL=canonical-color-keys.d.ts.map

package/lib/typescript/src/theme/tokens/canonical-color-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-color-keys.d.ts","sourceRoot":"","sources":["../../../../../src/theme/tokens/canonical-color-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAU,CAAC;AAEpD,QAAA,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0E+B,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,CAAC,MAAM,mBAAmB,CAAC,EAErC,CAAC;AAEnC,2FAA2F;AAC3F,KAAK,mBAAmB,GAAG,OAAO,CAAC,MAAM,mBAAmB,EAAE,MAAM,OAAO,uBAAuB,CAAC,CAAC;AACpG,KAAK,iBAAiB,GAAG,OAAO,CAAC,MAAM,OAAO,uBAAuB,EAAE,MAAM,mBAAmB,CAAC,CAAC;AAClG,MAAM,MAAM,+BAA+B,GAAG,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,GACzG,IAAI,GACJ;IAAE,OAAO,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAAC"}

package/lib/typescript/src/theme/tokens/dark.d.ts

@@ -1,77 +1,70 @@
 /**
- * Dark-scheme color tokens — flat, dotted-key data (no imports, no types).
- *
- * Convention: [category].[context].[property?].[variant].[state]
- *
- * GENERATED-STYLE SOURCE: intended to be replaced by the Figma / design-sync export.
+ * Dark semantic colors. See docs/design-tokens.md for naming and references.
+ * Generated-style source; naming and contrast updates await the next design-sync export.
  */
 export declare const dark: {
-    "color.background": string;
-    "color.shadow": string;
+    "color.surface.canvas": string;
     "color.surface.default": string;
     "color.surface.raised": string;
     "color.surface.sunken": string;
-    "color.surface.overlay": string;
-    "color.surface.accent": string;
-    "color.surface.accent.subtle": string;
-    "color.text.default": string;
-    "color.text.muted": string;
-    "color.text.subtle": string;
+    "color.text.primary": string;
+    "color.text.secondary": string;
+    "color.text.tertiary": string;
     "color.text.disabled": string;
     "color.text.inverse": string;
     "color.text.link": string;
-    "color.text.accent": string;
-    "color.text.on-accent": string;
-    "color.text.on-accent-subtle": string;
     "color.border.subtle": string;
     "color.border.default": string;
     "color.border.strong": string;
-    "color.border.focus": string;
-    "color.border.accent": string;
-    "color.action.bg.primary": string;
-    "color.action.bg.primary.hover": string;
-    "color.action.bg.primary.active": string;
-    "color.action.bg.primary.disabled": string;
-    "color.action.fg.primary": string;
-    "color.action.bg.primary.subtle": string;
-    "color.action.bg.primary.subtle.hover": string;
-    "color.action.bg.primary.subtle.active": string;
-    "color.action.bg.primary.subtle.disabled": string;
-    "color.action.fg.primary.subtle": string;
-    "color.action.bg.secondary": string;
-    "color.action.fg.secondary": string;
-    "color.action.bg.secondary.subtle": string;
-    "color.action.bg.secondary.subtle.hover": string;
-    "color.action.bg.secondary.subtle.active": string;
-    "color.action.bg.secondary.subtle.disabled": string;
-    "color.action.fg.secondary.subtle": string;
-    "color.status.success": string;
-    "color.status.success.bg": string;
-    "color.status.success.bg.subtle": string;
-    "color.status.success.border": string;
-    "color.status.success.border.subtle": string;
-    "color.status.success.fg": string;
-    "color.status.success.fg.subtle": string;
-    "color.status.warning": string;
-    "color.status.warning.bg": string;
-    "color.status.warning.bg.subtle": string;
-    "color.status.warning.border": string;
-    "color.status.warning.border.subtle": string;
-    "color.status.warning.fg": string;
-    "color.status.warning.fg.subtle": string;
-    "color.status.danger": string;
-    "color.status.danger.bg": string;
-    "color.status.danger.bg.subtle": string;
-    "color.status.danger.border": string;
-    "color.status.danger.border.subtle": string;
-    "color.status.danger.fg": string;
-    "color.status.danger.fg.subtle": string;
-    "color.status.info": string;
-    "color.status.info.bg": string;
-    "color.status.info.bg.subtle": string;
-    "color.status.info.border": string;
-    "color.status.info.border.subtle": string;
-    "color.status.info.fg": string;
-    "color.status.info.fg.subtle": string;
+    "color.focus.ring": string;
+    "color.backdrop": string;
+    "color.shadow": string;
+    "color.accent.text": string;
+    "color.accent.border": string;
+    "color.accent.solid.bg": string;
+    "color.accent.solid.bg.hover": string;
+    "color.accent.solid.bg.pressed": string;
+    "color.accent.solid.bg.disabled": string;
+    "color.accent.solid.fg": string;
+    "color.accent.soft.bg": string;
+    "color.accent.soft.bg.hover": string;
+    "color.accent.soft.bg.pressed": string;
+    "color.accent.soft.bg.disabled": string;
+    "color.accent.soft.fg": string;
+    "color.neutral.solid.bg": string;
+    "color.neutral.solid.fg": string;
+    "color.neutral.soft.bg": string;
+    "color.neutral.soft.bg.hover": string;
+    "color.neutral.soft.bg.pressed": string;
+    "color.neutral.soft.bg.disabled": string;
+    "color.neutral.soft.fg": string;
+    "color.success.text": string;
+    "color.success.solid.bg": string;
+    "color.success.solid.fg": string;
+    "color.success.solid.border": string;
+    "color.success.soft.bg": string;
+    "color.success.soft.fg": string;
+    "color.success.soft.border": string;
+    "color.warning.text": string;
+    "color.warning.solid.bg": string;
+    "color.warning.solid.fg": string;
+    "color.warning.solid.border": string;
+    "color.warning.soft.bg": string;
+    "color.warning.soft.fg": string;
+    "color.warning.soft.border": string;
+    "color.danger.text": string;
+    "color.danger.solid.bg": string;
+    "color.danger.solid.fg": string;
+    "color.danger.solid.border": string;
+    "color.danger.soft.bg": string;
+    "color.danger.soft.fg": string;
+    "color.danger.soft.border": string;
+    "color.info.text": string;
+    "color.info.solid.bg": string;
+    "color.info.solid.fg": string;
+    "color.info.solid.border": string;
+    "color.info.soft.bg": string;
+    "color.info.soft.fg": string;
+    "color.info.soft.border": string;
 };
 //# sourceMappingURL=dark.d.ts.map

package/lib/typescript/src/theme/tokens/dark.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dark.d.ts","sourceRoot":"","sources":["../../../../../src/theme/tokens/dark.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoGhB,CAAC"}
+{"version":3,"file":"dark.d.ts","sourceRoot":"","sources":["../../../../../src/theme/tokens/dark.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgGhB,CAAC"}