@cube-dev/ui-kit 0.142.4 → 0.142.5

package/dist/utils/react/forwardRefWithGenerics.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/react/forwardRefWithGenerics.tsx
 /**
 * A helper for creating forwardRef components with generic types.

package/dist/utils/react/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { forwardRefWithGenerics } from "./forwardRefWithGenerics.js";
 import { isTextOnly } from "./isTextOnly.js";

package/dist/utils/react/interactions.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useState } from "react";
 import { useFocus, useFocusVisible } from "react-aria";
 

package/dist/utils/react/isTextOnly.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { Children, isValidElement } from "react";
 
 //#region src/utils/react/isTextOnly.ts

package/dist/utils/react/mapProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/react/mapProps.ts
 /** Converts AriaButtonProps to CubeButtonProps */
 function ariaToCubeButtonProps(props) {

package/dist/utils/react/mergeProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { mergeIds } from "./useId.js";
 import { mergeStyles } from "@tenphi/tasty";

package/dist/utils/react/nullableValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/react/nullableValue.ts
 function castNullableStringValue(props) {
 	return castNullableField(props, ["value", "defaultValue"], "string", (v) => String(v));

package/dist/utils/react/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/react/resolveIcon.ts
 /**
 * Resolves a dynamic icon prop to its content and slot state.

package/dist/utils/react/sharedStore.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useSyncExternalStore } from "react";
 

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useEffect, useRef } from "react";
 
 //#region src/utils/react/useCombinedRefs.ts

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { useEffect } from "react";
 import { useFocusVisible } from "react-aria";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 
 //#region src/utils/react/useEventBus.ts

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useEffect, useRef, useState } from "react";
 import { useSSRSafeId } from "@react-aria/ssr";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useIsDarwin.ts

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { useMemo } from "react";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useCallback, useSyncExternalStore } from "react";
 

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { useCallback, useContext, useEffect, useRef } from "react";
 

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.142.4 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.5 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.142.4";
+const VERSION = "0.142.5";
 const TASTY_VERSION = "2.6.4";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/glaze/api.md

@@ -25,8 +25,8 @@ Full reference for every public method, option, and type exported by `@tenphi/gl
 
 | Method | Description |
 |---|---|
-| `glaze(hue, saturation?)` | Create a theme from hue (0–360) and saturation (0–100). Default saturation: `100`. |
-| `glaze({ hue, saturation })` | Create a theme from an options object. |
+| `glaze(hue, saturation?, config?)` | Create a theme from hue (0–360) and saturation (0–100). Optional `config` overrides the global config for this theme. |
+| `glaze({ hue, saturation }, config?)` | Create a theme from an options object, with optional per-theme config override. |
 | `glaze.from(data)` | Create a theme from an exported configuration (`theme.export()` snapshot). |
 | `glaze.fromHex(hex)` | Create a theme from a hex color (`#rgb` or `#rrggbb`). Extracts hue and saturation. |
 | `glaze.fromRgb(r, g, b)` | Create a theme from RGB values (0–255). Extracts hue and saturation. |
@@ -37,8 +37,13 @@ const b = glaze({ hue: 280, saturation: 80 });
 const c = glaze.fromHex('#7a4dbf');
 const d = glaze.fromRgb(122, 77, 191);
 const e = glaze.from(a.export());
+
+// Per-theme config override:
+const rawTheme = glaze(280, 80, { lightLightness: false, darkLightness: false });
 ```
 
+The optional `config` parameter is a `GlazeConfigOverride` — see [Per-instance config override](#per-instance-config-override).
+
 ---
 
 ## Theme methods
@@ -81,13 +86,16 @@ const def = theme.color('surface');                              // get
 
 ### `theme.extend(options)`
 
-Creates a new theme inheriting all color definitions, optionally replacing the hue / saturation seed and merging in per-theme overrides:
+Creates a new theme inheriting all color definitions, optionally replacing the hue / saturation seed, color overrides, and config:
 
 ```ts
 const danger = primary.extend({
   hue: 23,
   colors: { 'accent-fill': { lightness: 48, mode: 'fixed' } },
 });
+
+// Inherit parent's config override and tighten the dark window further:
+const highSat = base.extend({ config: { darkLightness: [10, 100] } });
 ```
 
 `GlazeExtendOptions`:
@@ -97,6 +105,7 @@ const danger = primary.extend({
 | `hue` | `number` | Replace the hue seed. Defaults to the parent's hue. |
 | `saturation` | `number` | Replace the saturation seed. Defaults to the parent's saturation. |
 | `colors` | `ColorMap` | Per-theme overrides (additive merge over the inherited map). |
+| `config` | `GlazeConfigOverride` | Config override for the child. Shallow-merged with the parent's override — child fields win. |
 
 Colors marked with `inherit: false` on the parent are **not** copied into the child.
 
@@ -240,6 +249,8 @@ type MinContrast = number | 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
 
 You can also pass any numeric ratio directly (e.g., `contrast: 4.5`, `contrast: 11`). The constraint is applied independently for each scheme — if the `lightness` already satisfies the floor it's kept, otherwise the solver adjusts lightness until the target is met.
 
+By default, `autoFlip` lets the solver cross to the opposite side of the base color when the requested lightness direction cannot satisfy contrast. Set `glaze.configure({ autoFlip: false })` to keep strict directionality: unmet colors pin to that direction's 0 or 100 lightness extreme instead of falling back to the original requested value.
+
 **Full lightness spectrum in HC mode:** in high-contrast variants the `lightLightness` and `darkLightness` window constraints are bypassed entirely. Colors can reach the full 0–100 range, maximizing perceivable contrast.
 
 #### Per-color hue override
@@ -287,28 +298,39 @@ See [Mix colors](#mix-colors) below.
 
 ## Standalone color tokens
 
-`glaze.color()` creates a single color token without a full theme. Two overloads:
+`glaze.color()` creates a single color token without a full theme.
 
 ```ts
-glaze.color(input: GlazeColorInput, scaling?: GlazeColorScaling): GlazeColorToken;
-glaze.color(value: GlazeColorValue, overrides?: GlazeColorOverrides, scaling?: GlazeColorScaling): GlazeColorToken;
+// arg1: the color (four shapes — see below)
+// arg2: optional config override (GlazeConfigOverride — see below)
+glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride): GlazeColorToken;
 ```
 
 ### Input forms
 
-`GlazeColorValue` (the value-shorthand input) accepts:
+`glaze.color()` accepts **four input shapes**, discriminated by structure:
+
+| Shape | Example | Notes |
+|---|---|---|
+| **Bare string** | `'#26fcb2'` | Hex or CSS color function (`rgb()`, `hsl()`, `okhsl()`, `oklch()`). |
+| **Value object** | `{ h: 152, s: 0.95, l: 0.74 }` | OKHSL, `{ r, g, b }` (sRGB 0–255), or `{ l, c, h }` (OKLCh). |
+| **`{ from, ...overrides }`** | `{ from: '#1a1a2e', base: bg, contrast: 'AA' }` | Value + color overrides in one object. |
+| **Structured** | `{ hue: 152, saturation: 95, lightness: 74 }` | Full theme-style token (hue/saturation/lightness all in 0–100). |
+
+`GlazeColorValue` (bare string or value-object forms) accepts:
 
 | Form | Example | Notes |
 |---|---|---|
-| Hex | `'#26fcb2'`, `'#26fcb2ff'`, `'#abc'` | 3, 6, or 8 digits. Alpha components are dropped with a `console.warn` — use `opacity` instead. |
+| Hex | `'#26fcb2'`, `'#26fcb2ff'`, `'#abc'` | 3, 6, or 8 digits. Alpha is dropped with a `console.warn` — use `opacity` instead. |
 | `rgb()` | `'rgb(38 252 178)'`, `'rgb(38 252 178 / 0.8)'` | Modern space syntax. Alpha dropped with warning. |
 | `hsl()` | `'hsl(152 97% 57%)'` | Modern space syntax. Alpha dropped with warning. |
 | `okhsl()` | `'okhsl(152 95% 74%)'` | Glaze's own emit format. Alpha dropped with warning. |
 | `oklch()` | `'oklch(0.85 0.18 152)'` | Glaze's own emit format. Alpha dropped with warning. |
 | `OkhslColor` object | `{ h: 152, s: 0.95, l: 0.74 }` | Glaze's native shape (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l` throws with a hint to use the structured form. |
-| RGB tuple | `[38, 252, 178]` | 0–255, same range as `glaze.fromRgb`. |
+| `RgbColor` object | `{ r: 38, g: 252, b: 178 }` | sRGB 0–255. RGB tuple `[r, g, b]` is not supported — use this object form. |
+| `OklchColor` object | `{ l: 0.85, c: 0.18, h: 152 }` | OKLCh (L/C: 0–1, H: degrees), same semantics as `oklch()` strings. |
 
-`GlazeColorInput` (the structured input) is `{ hue, saturation, lightness, ... }`:
+`GlazeColorInput` (structured form) is `{ hue, saturation, lightness, ... }`:
 
 | Field | Type | Description |
 |---|---|---|
@@ -319,63 +341,49 @@ glaze.color(value: GlazeColorValue, overrides?: GlazeColorOverrides, scaling?: G
 | `mode` | `AdaptationMode` | Default: `'auto'`. |
 | `opacity` | `number` | Fixed alpha 0–1. |
 | `base` | `GlazeColorToken \| GlazeColorValue` | Optional dependency. See [Pairing colors](#pairing-colors). |
-| `contrast` | `HCPair<MinContrast>` | WCAG floor against `base` (requires `base`). |
+| `contrast` | `HCPair<MinContrast>` | WCAG floor against `base`. Without `base`, anchored to the literal seed. |
 | `name` | `string` | Debug label for warnings; doesn't change output keys. Reserved names (`'value'`, `'seed'`, `'externalBase'`) are rejected. |
 
-Named CSS colors (`'red'`, `'blueviolet'`) are not supported.
-
-### Defaults
-
-Every input form defaults to `mode: 'auto'` so the resolved token adapts between light and dark like an ordinary theme color. The *scaling* snapshot taken at create time differs by input form:
-
-- **String value-shorthand** (`'#000'`, `'rgb(...)'`, etc.):
-  - Light variant preserves the input lightness exactly (`lightLightness: false`).
-  - Dark variant is Möbius-inverted into `[globalConfig.darkLightness[0], 100]`, so `glaze.color('#000')` renders as `#fff` in dark mode and `glaze.color('#fff')` falls to the dark `lo` floor (default `0.15`).
-- **Object / tuple / structured inputs**:
-  - Both light and dark variants are mapped through `globalConfig.lightLightness` / `globalConfig.darkLightness` (defaults `[10, 100]` / `[15, 95]`) — the same windows a theme color uses.
-- All windows are **snapshotted at color-creation time** so later `glaze.configure()` calls don't retroactively change exported tokens. `token.export()` round-trips byte-for-byte.
-
-To opt back into the legacy fixed-linear default (no Möbius inversion), pass `{ mode: 'fixed' }` as the second arg, or supply an explicit `scaling` (see [`GlazeColorScaling`](#glazecolorscaling)).
-
-### `GlazeColorOverrides`
+`GlazeFromInput` (from form) is `{ from: GlazeColorValue, ...colorOverrides }`:
 
-Overrides for the value-shorthand overload's second argument:
-
-| Option | Notes |
+| Field | Notes |
 |---|---|
-| `hue` | Number (absolute 0–360) or `'+N'`/`'-N'` (relative to seed — never to `base`). |
+| `from` | **Required.** The source color value — same forms as `GlazeColorValue`. |
+| `hue` | Number (absolute 0–360) or `'+N'`/`'-N'` (relative to seed, never to `base`). |
 | `saturation` | Override seed saturation (0–100). |
-| `lightness` | Number (absolute 0–100) or `'+N'`/`'-N'`. Without `base`, relative is anchored to the literal seed; with `base`, anchored to `base`'s lightness per scheme. Supports `[normal, hc]` pairs. |
-| `saturationFactor` | Multiplier on the seed (0–1). Default: `1`. |
-| `mode` | `'auto'` (default for every input form) / `'fixed'` / `'static'`. |
-| `contrast` | WCAG floor. Without `base`, anchored to the literal seed; with `base`, solved per scheme against `base`'s resolved variant. When the target can't be met, a `console.warn` is emitted and the closest passing variant is returned. |
-| `base` | `GlazeColorToken` **or** raw `GlazeColorValue`. Raw values are auto-wrapped via `glaze.color(value)`. When set, `contrast` and relative `lightness` anchor to it per scheme; relative `hue` still anchors to the seed. |
-| `opacity` | Fixed alpha 0–1 applied to every variant. Combining with `contrast` is not recommended — `console.warn` is emitted. |
-| `name` | Debug label only — surfaces in `console.warn` / Error messages. Does not change output keys. |
+| `lightness` | Number (absolute 0–100) or `'+N'`/`'-N'`. Without `base`, relative anchors to the seed; with `base`, anchors to `base`'s lightness per scheme. |
+| `saturationFactor` | Multiplier on the seed (0–1). |
+| `mode` | `'auto'` (default) / `'fixed'` / `'static'`. |
+| `contrast` | WCAG floor. Without `base`, anchored to the literal seed; with `base`, solved per scheme. |
+| `base` | `GlazeColorToken` or raw `GlazeColorValue`. See [Pairing colors](#pairing-colors). |
+| `opacity` | Fixed alpha 0–1. Combining with `contrast` is not recommended — `console.warn` is emitted. |
+| `name` | Debug label only — surfaces in warnings/errors. Does not change output keys. |
 
-### `GlazeColorScaling`
+Named CSS colors (`'red'`, `'blueviolet'`) are not supported.
 
-Per-call lightness-window override. Mirrors `GlazeConfig`'s field names:
+### Defaults
 
-| Key | Default for string input | Default for object / tuple / structured input | Effect |
-|---|---|---|---|
-| `lightLightness` | `false` | `globalConfig.lightLightness` (snapshotted) | `false` = preserve input. Pass `[lo, hi]` to opt into a remap window. |
-| `darkLightness` | `[globalConfig.darkLightness[0], 100]` (snapshotted) | `globalConfig.darkLightness` (snapshotted) | `false` = preserve input in dark too. Pass `[lo, hi]` to override the window. |
+Every input form defaults to `mode: 'auto'` so the resolved token adapts between light and dark like an ordinary theme color. The config snapshot taken at create time differs by input form:
 
-Passing `scaling` is **all-or-nothing** — both fields are replaced. To keep one field's default while overriding the other, restate the default explicitly.
+- **Value-shorthand** (bare strings, value objects, and `{ from, ...overrides }`):
+  - Light variant preserves the input lightness exactly (`lightLightness: false`).
+  - All other config fields (`darkLightness`, `darkDesaturation`, `darkCurve`, `autoFlip`) snapshot from `globalConfig` at create time.
+- **Structured input** (`{ hue, saturation, lightness, ... }`):
+  - Both lightness windows snapshot from `globalConfig` at create time (same as a theme color).
+- All fields are **snapshotted at color-creation time** — later `glaze.configure()` calls don't retroactively change existing tokens.
 
 ```ts
-// Preserve raw lightness in dark mode too
-glaze.color('#26fcb2', undefined, { darkLightness: false });
+// Bare string — adapts automatically
+glaze.color('#26fcb2')
 
-// Opt back into a theme-style window
-glaze.color('#26fcb2', undefined, {
-  lightLightness: [10, 100],
-  darkLightness: [15, 95],
-});
+// Value-object — same behavior
+glaze.color({ h: 152, s: 0.95, l: 0.74 })
 
-// Structured form takes scaling as the second positional arg
-glaze.color({ hue: 152, saturation: 95, lightness: 74 }, { darkLightness: false });
+// From form — value + color overrides
+glaze.color({ from: '#1a1a2e', hue: '+20', contrast: 'AA' })
+
+// Structured form — explicit hue/saturation/lightness (0–100)
+glaze.color({ hue: 152, saturation: 95, lightness: 74 })
 ```
 
 ### Token methods
@@ -391,12 +399,71 @@ A `GlazeColorToken` exposes:
 | `token.css({ name, format?, suffix? })` | CSS custom property declarations grouped by scheme variant. `name` is **required** and becomes the variable identifier (`'brand'` → `--brand-color`). Defaults: `format: 'rgb'`, `suffix: '-color'` (matches `theme.css`). |
 | `token.export()` | JSON-safe snapshot — pass to `glaze.colorFrom(...)` to rehydrate. |
 
+### Per-instance config override
+
+The optional `config` second argument (`GlazeConfigOverride`) overrides the resolve-relevant global config fields for a single token or theme. Fields that are omitted fall through to the live global config at create time (and are snapshotted). Pass `false` for a lightness window to disable clamping entirely — equivalent to `[0, 100]`.
+
+`GlazeConfigOverride`:
+
+| Field | Default (from global) | Description |
+|---|---|---|
+| `lightLightness` | `[10, 100]` | Light window `[lo, hi]` or `false` (disable clamping = `[0, 100]`). |
+| `darkLightness` | `[15, 95]` | Dark window `[lo, hi]` or `false` (disable clamping). |
+| `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). |
+| `darkCurve` | `0.5` | Möbius beta for dark `auto`-inversion (0–1). Accepts `[normal, hc]` pair. |
+| `autoFlip` | `true` | When solving `contrast`, allow the solver to switch lightness direction if the requested side can't meet the target. |
+| `shadowTuning` | `undefined` | Default shadow tuning (meaningful for themes; harmless on color tokens). |
+
+Config overrides apply to both `glaze.color()` tokens and `glaze()` themes:
+
+```ts
+// Standalone color — preserve raw lightness in both schemes
+glaze.color('#26fcb2', { darkLightness: false })
+
+// Restore the #000 → white dark flip (full dark range)
+glaze.color('#000000', {
+  lightLightness: false,
+  darkLightness: [15, 100],
+})
+
+// Structured form with config override
+glaze.color({ hue: 152, saturation: 95, lightness: 74 }, { darkLightness: false })
+
+// Theme with config override
+const rawTheme = glaze(280, 80, { lightLightness: false })
+```
+
+The override is **snapshotted at create time** so later `glaze.configure()` calls don't change already-created tokens or themes (for non-overridden fields, the snapshot captured the global value at creation time; for themes, non-overridden fields are re-read from the live global at resolve time — see [Theme config override](#theme-config-override)).
+
+### Theme config override
+
+When a theme is created with a `GlazeConfigOverride`, the override is **merged over the live global config at resolve time**. This means:
+
+- Fields you overrode are fixed — `glaze.configure()` can't change them for this theme.
+- Fields you didn't override still react to later `glaze.configure()` calls.
+
+```ts
+const t = glaze(280, 80, { lightLightness: [0, 50] });
+t.colors({ text: { lightness: 50, saturation: 1 } });
+// text.light.l ≈ 0.25 — always, regardless of global lightLightness changes.
+// text.dark.s reacts to glaze.configure({ darkDesaturation }) since it's not overridden.
+```
+
+`extend` inherits the parent's override and shallow-merges the child's:
+
+```ts
+const child = t.extend({ config: { darkLightness: false } });
+// child: lightLightness: [0, 50] (inherited) + darkLightness: false (added)
+```
+
+`theme.export()` includes `config`; `glaze.from(data)` restores it.
+
 ### `glaze.colorFrom(data)`
 
-Inverse of `token.export()`. Captures the original input value, all overrides (with any `base` token recursively serialized), and the effective `scaling` so later `glaze.configure()` calls don't change exported tokens.
+Inverse of `token.export()`. The exported snapshot includes the original input, all overrides (with any `base` token recursively serialized), and the full effective config — so later `glaze.configure()` calls don't change rehydrated tokens.
 
 ```ts
-const text = glaze.color('#1a1a1a', { contrast: 'AA' });
+const text = glaze.color({ from: '#1a1a1a', contrast: 'AA' });
 const data = text.export();
 const restored = glaze.colorFrom(data);
 // restored.resolve() === text.resolve() byte-for-byte
@@ -412,17 +479,17 @@ Set `base` to anchor a standalone color to another standalone color or raw value
 const bg = glaze.color('#1a1a2e');
 
 // Text guaranteed AA against `bg` in every scheme.
-const text = glaze.color('#ffffff', { base: bg, contrast: 'AA' });
+const text = glaze.color({ from: '#ffffff', base: bg, contrast: 'AA' });
 
 // Border 8 lightness units lighter than `bg` in each scheme.
-const border = glaze.color('#000000', {
+const border = glaze.color({ from: '#000000',
   base: bg,
   lightness: '+8',
   mode: 'fixed',
 });
 
 // Raw-value base — Glaze auto-wraps it via `glaze.color(value)`.
-const text2 = glaze.color('#ffffff', { base: '#1a1a2e', contrast: 'AA' });
+const text2 = glaze.color({ from: '#ffffff', base: '#1a1a2e', contrast: 'AA' });
 ```
 
 Behavior with `base`:
@@ -432,15 +499,15 @@ Behavior with `base`:
 - Relative `hue: '+N'` / `'-N'` still anchors to the **seed** (the value passed to `glaze.color()`), not the base.
 - `mode` works as a per-pair knob.
 - The base token's `.resolve()` is called lazily on the first resolve of the dependent and the result is captured by reference; later mutations to the base don't apply.
-- Raw-value bases inherit the same string-vs-object scaling defaults. To skip auto-invert on the base, wrap it yourself: `base: glaze.color(value, undefined, { darkLightness: false })`.
+- **Structured bases are resolved at full range for linking math**: when a value/`from` color links to a base created via the structured form, the contrast/lightness anchor uses the raw input lightness (not the windowed output). This ensures the anchor matches what you intended, not what the light window remapped it to. The base's own `.resolve()` output is unaffected.
 - When the contrast target is physically unreachable, `glaze` emits a single `console.warn` per `(name, scheme, target)` triple and returns the closest passing variant. Use the `name` override to make the warning identifiable.
 
 Chains compose:
 
 ```ts
 const bg = glaze.color('#000000');
-const surface = glaze.color('#222222', { base: bg, contrast: 'AAA' });
-const text = glaze.color('#ffffff', { base: surface, contrast: 'AA' });
+const surface = glaze.color({ from: '#222222', base: bg, contrast: 'AAA' });
+const text = glaze.color({ from: '#ffffff', base: surface, contrast: 'AA' });
 ```
 
 ### `name` is a debug label
@@ -899,10 +966,10 @@ S_dark = S_light * (1 - darkDesaturation) // default: 0.1
 
 ```ts
 glaze.configure({
-  lightLightness: [10, 100],
-  darkLightness: [15, 95],
+  lightLightness: [10, 100],   // or false to disable clamping
+  darkLightness: [15, 95],     // or false to disable clamping
   darkDesaturation: 0.1,
-  darkCurve: 0.5,                   // or [normal, hc] pair
+  darkCurve: 0.5,              // or [normal, hc] pair
   states: {
     dark: '@dark',
     highContrast: '@high-contrast',
@@ -922,8 +989,8 @@ glaze.configure({
 
 | Field | Default | Description |
 |---|---|---|
-| `lightLightness` | `[10, 100]` | Light scheme lightness window `[lo, hi]`. Bypassed in HC. |
-| `darkLightness` | `[15, 95]` | Dark scheme lightness window. Bypassed in HC. |
+| `lightLightness` | `[10, 100]` | Light scheme lightness window `[lo, hi]`, or `false` to disable clamping (equivalent to `[0, 100]`). Bypassed in HC. |
+| `darkLightness` | `[15, 95]` | Dark scheme lightness window, or `false` to disable clamping. Bypassed in HC. |
 | `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). |
 | `darkCurve` | `0.5` | Möbius beta for dark `auto`-inversion (0–1). Accepts `[normal, hc]` pair. |
 | `states.dark` | `'@dark'` | State alias for dark mode tokens (Tasty export). |
@@ -931,6 +998,7 @@ glaze.configure({
 | `modes.dark` | `true` | Include dark variants in exports. |
 | `modes.highContrast` | `false` | Include HC variants. |
 | `shadowTuning` | `undefined` | Default tuning for all shadow colors. Per-color tuning merges field-by-field. |
+| `autoFlip` | `true` | When solving `contrast`, allow the solver to switch away from the requested lightness direction if that side can't meet the target. With `false`, only the requested direction is considered; unmet contrasts pin the lightness to that direction's extreme (and emit a warning). |
 
 | Method | Description |
 |---|---|
@@ -938,7 +1006,7 @@ glaze.configure({
 | `glaze.getConfig()` | Snapshot the current resolved config (shallow copy). |
 | `glaze.resetConfig()` | Reset to defaults (also bumps the version counter). |
 
-Standalone `glaze.color()` tokens snapshot the relevant fields at create time, so later `configure()` calls don't change already-created tokens.
+Standalone `glaze.color()` tokens snapshot the resolve-relevant fields at create time, so later `configure()` calls don't change already-created tokens. Themes merge the live global at resolve time for fields not overridden via `GlazeConfigOverride`.
 
 ---
 
@@ -970,8 +1038,10 @@ Resolution priority (highest first):
 
 | Condition | Behavior |
 |---|---|
-| `contrast` without `base` | Validation error |
-| Relative `lightness` without `base` | Validation error |
+| `contrast` without `base` in a **theme** color | Validation error |
+| Relative `lightness` without `base` in a **theme** color | Validation error |
+| `contrast` without `base` in `glaze.color()` | Anchors against the literal seed (no error) |
+| Relative `lightness` without `base` in `glaze.color()` | Anchors against the literal seed (no error) |
 | `lightness` resolves outside 0–100 | Clamp silently |
 | `saturation` outside 0–1 | Clamp silently |
 | Circular `base` references | Validation error |
@@ -1070,5 +1140,7 @@ import {
 | `lightnessRange` | `[0, 1]` | Search bounds. |
 | `epsilon` | `1e-4` | Convergence threshold. |
 | `maxIterations` | `14` | Max binary-search iterations per branch. |
+| `initialDirection` | higher-contrast side | Direction to search first (`'lighter'` or `'darker'`). Theme resolution sets this from the requested lightness relative to the base color. |
+| `flip` | `false` | When `true`, try the opposite direction if the initial one doesn't meet the target. When `false`, only the initial direction is searched — unmet contrasts pin the result to that direction's extreme. |
 
-Result: `{ lightness, contrast, met, branch: 'lighter' | 'darker' | 'preferred' }`.
+Result: `{ lightness, contrast, met, branch: 'lighter' | 'darker' | 'preferred', flipped? }`. `flipped: true` indicates the initial direction failed and the opposite direction satisfied the target.