@unpunnyfuns/swatchbook-blocks 0.55.0 → 0.56.0

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import * as _$react from "react";
 import { ReactElement, ReactNode } from "react";
-import { Axis, AxisVarianceResult, Diagnostic, Permutation, Preset } from "@unpunnyfuns/swatchbook-core";
+import { Axis, AxisVarianceResult, Diagnostic, Preset } from "@unpunnyfuns/swatchbook-core";
+import { SlimListedToken } from "@unpunnyfuns/swatchbook-core/snapshot-for-wire";
 
 //#region src/format-color.d.ts
 /**
@@ -65,15 +66,27 @@ declare function formatColor(value: unknown, format: ColorFormat, fallback?: str
  * in `packages/addon/src/virtual.d.ts` describe the same payload.
  */
 type VirtualAxisShape = Axis;
-type VirtualPermutationShape = Permutation;
 type VirtualDiagnosticShape = Diagnostic;
 interface VirtualTokenShape {
-  $type?: string;
+  $type?: string | undefined;
   $value?: unknown;
-  $description?: string;
-  aliasOf?: string;
-  aliasChain?: readonly string[];
-  aliasedBy?: readonly string[];
+  $description?: string | undefined;
+  aliasOf?: string | undefined;
+  aliasChain?: readonly string[] | undefined;
+  aliasedBy?: readonly string[] | undefined;
+  /**
+   * Per-sub-field alias map for composite tokens whose value blends
+   * primitives with aliased fragments — Terrazzo populates this when
+   * one or more component fields of a composite ($type: 'border',
+   * 'shadow', 'typography', 'gradient', 'transition') resolve through
+   * an alias. The `CompositeBreakdown` block reads it to render the
+   * source path beside each component value. Typed as `unknown` because
+   * the shape varies per composite type (color carries a
+   * `{components: (string | undefined)[]}` sub-shape; typography/border
+   * carry a flat `Record<string, string | undefined>`); the block
+   * narrows it at the consumer.
+   */
+  partialAliasOf?: unknown;
 }
 /**
  * Subset of `@terrazzo/plugin-token-listing`'s `ListedToken` that the
@@ -81,28 +94,11 @@ interface VirtualTokenShape {
  * variable name and `previewValue` for the display-ready CSS string.
  * `source.loc` enables "jump to authoring source" affordances.
  *
- * Only the fields blocks consume are typed here; the plugin's full shape
- * lives in `@unpunnyfuns/swatchbook-core`.
+ * Aliases `SlimListedToken` from core's `/snapshot-for-wire` subpath —
+ * the single canonical wire shape; both the addon's plugin (server-side
+ * emit) and blocks (consumer-side read) reference the same definition.
  */
-interface VirtualTokenListingShape {
-  names: Record<string, string>;
-  previewValue?: string | number;
-  source?: {
-    resource: string;
-    loc?: {
-      start: {
-        line: number;
-        column: number;
-        offset: number;
-      };
-      end: {
-        line: number;
-        column: number;
-        offset: number;
-      };
-    };
-  };
-}
+type VirtualTokenListingShape = SlimListedToken;
 type VirtualPresetShape = Preset;
 /**
  * Wire shape of one `Project.jointOverrides` entry — same as core's
@@ -116,7 +112,7 @@ interface VirtualJointOverrideShape {
 /**
  * Map from path → cached `AxisVarianceResult`. Snapshot carries this
  * so the `AxisVariance` block can O(1) look up which axes affect a
- * token instead of re-running `analyzeAxisVariance` on every render.
+ * token instead of re-running variance analysis on every render.
  */
 type VirtualVarianceByPathShape = Record<string, AxisVarianceResult>;
 /**
@@ -129,17 +125,6 @@ interface ProjectSnapshot {
   /** Axis names suppressed via `config.disabledAxes` — pinned to their defaults, hidden from the toolbar. */
   disabledAxes: readonly string[];
   presets: readonly VirtualPresetShape[];
-  /**
-   * @deprecated Wire-shipped permutations were removed in PR 6a.
-   * Hand-built snapshots (tests, MDX consumers) may still populate
-   * this for backward compatibility with the legacy fallback path
-   * in `useProject`. Production preview snapshots omit it.
-   */
-  permutations?: readonly VirtualPermutationShape[];
-  /**
-   * @deprecated See `permutations`. Wire format dropped in PR 6a.
-   */
-  permutationsResolved?: Record<string, Record<string, VirtualTokenShape>>;
   activePermutation: string;
   activeAxes: Readonly<Record<string, string>>;
   cssVarPrefix: string;
@@ -157,26 +142,23 @@ interface ProjectSnapshot {
    * Per-axis cell maps — `cells[axis][context]` is the resolved token
    * data for `{ ...defaults, [axis]: context }`. Bounded by
    * `Σ(axes × contexts)` regardless of cartesian product size.
-   * Optional during the chain rollout — empty fallback when the
-   * snapshot pre-dates the wire format change.
+   * Non-default cells store only the tokens whose value differs from
+   * the default-cell baseline (delta cells).
    */
-  cells?: Record<string, Record<string, Record<string, VirtualTokenShape>>>;
+  cells: Record<string, Record<string, Record<string, VirtualTokenShape>>>;
   /**
    * `Project.jointOverrides` flattened to entries for wire transport.
    * Same ascending-arity iteration order the Map carries on the
-   * server side.
+   * server side. Empty array when no joint divergences exist.
    */
-  jointOverrides?: readonly (readonly [string, VirtualJointOverrideShape])[];
+  jointOverrides: readonly (readonly [string, VirtualJointOverrideShape])[];
   /**
    * Cached per-path variance results. Blocks read this for O(1) axis
    * variance lookup instead of recomputing on each render.
    */
   varianceByPath?: VirtualVarianceByPathShape;
-  /**
-   * The default tuple — `{ axis: axis.default }` for every axis.
-   * Replaces the legacy "look at `permutations[0].input`" pattern.
-   */
-  defaultTuple?: Record<string, string>;
+  /** The default tuple — `{ axis: axis.default }` for every axis. */
+  defaultTuple: Record<string, string>;
   /**
    * Pre-built `resolveAt(tuple)` accessor. The addon's preview
    * decorator instantiates this once per iframe lifetime — the
@@ -901,5 +883,5 @@ declare function TypographyScale({
   sortDir
 }: TypographyScaleProps): ReactElement;
 //#endregion
-export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, BorderPreview, type BorderPreviewProps, BorderSample, type BorderSampleProps, COLOR_FORMATS, type ColorFormat, ColorFormatContext, ColorPalette, type ColorPaletteProps, ColorTable, type ColorTableProps, CompositeBreakdown, type CompositeBreakdownProps, CompositePreview, type CompositePreviewProps, ConsumerOutput, type ConsumerOutputProps, Diagnostics, type DiagnosticsProps, DimensionBar, type DimensionBarProps, type DimensionKind, DimensionScale, type DimensionScaleProps, FontFamilySample, type FontFamilySampleProps, FontWeightScale, type FontWeightScaleProps, type FormatColorResult, GradientPalette, type GradientPaletteProps, MotionPreview, type MotionPreviewProps, MotionSample, type MotionSampleProps, type MotionSpeed, type NormalizedColor, OpacityScale, type OpacityScaleProps, PermutationContext, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, StrokeStyleSample, type StrokeStyleSampleProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, TokenDetail, type TokenDetailProps, TokenHeader, type TokenHeaderProps, TokenNavigator, type TokenNavigatorProps, TokenTable, type TokenTableProps, TokenUsageSnippet, type TokenUsageSnippetProps, TypographyScale, type TypographyScaleProps, type VirtualAxisShape as VirtualAxis, type VirtualAxisShape, type VirtualDiagnosticShape as VirtualDiagnostic, type VirtualDiagnosticShape, type VirtualPermutationShape as VirtualPermutation, type VirtualPermutationShape, type VirtualPresetShape as VirtualPreset, type VirtualPresetShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, type VirtualTokenListingShape, formatColor, useActiveAxes, useActivePermutation, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
+export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, BorderPreview, type BorderPreviewProps, BorderSample, type BorderSampleProps, COLOR_FORMATS, type ColorFormat, ColorFormatContext, ColorPalette, type ColorPaletteProps, ColorTable, type ColorTableProps, CompositeBreakdown, type CompositeBreakdownProps, CompositePreview, type CompositePreviewProps, ConsumerOutput, type ConsumerOutputProps, Diagnostics, type DiagnosticsProps, DimensionBar, type DimensionBarProps, type DimensionKind, DimensionScale, type DimensionScaleProps, FontFamilySample, type FontFamilySampleProps, FontWeightScale, type FontWeightScaleProps, type FormatColorResult, GradientPalette, type GradientPaletteProps, MotionPreview, type MotionPreviewProps, MotionSample, type MotionSampleProps, type MotionSpeed, type NormalizedColor, OpacityScale, type OpacityScaleProps, PermutationContext, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, StrokeStyleSample, type StrokeStyleSampleProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, TokenDetail, type TokenDetailProps, TokenHeader, type TokenHeaderProps, TokenNavigator, type TokenNavigatorProps, TokenTable, type TokenTableProps, TokenUsageSnippet, type TokenUsageSnippetProps, TypographyScale, type TypographyScaleProps, type VirtualAxisShape as VirtualAxis, type VirtualAxisShape, type VirtualDiagnosticShape as VirtualDiagnostic, type VirtualDiagnosticShape, type VirtualPresetShape as VirtualPreset, type VirtualPresetShape, type VirtualTokenShape as VirtualToken, type VirtualTokenShape, type VirtualTokenListingShape, formatColor, useActiveAxes, useActivePermutation, useColorFormat, useOptionalSwatchbookData, useSwatchbookData };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -3,9 +3,10 @@ import Color from "colorjs.io";
 import { Fragment, createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { buildResolveAt } from "@unpunnyfuns/swatchbook-core/resolve-at";
-import { makeCSSVar } from "@terrazzo/token-tools/css";
+import { makeCssVar } from "@unpunnyfuns/swatchbook-core/css-var";
 import { addons } from "storybook/preview-api";
 import { axes, cells, css, cssVarPrefix, defaultTuple, diagnostics, jointOverrides, listing, presets, varianceByPath } from "virtual:swatchbook/tokens";
+import { dataAttr } from "@unpunnyfuns/swatchbook-core/data-attr";
 import { fuzzyFilter } from "@unpunnyfuns/swatchbook-core/fuzzy";
 import cx from "clsx";
 //#region src/format-color.ts
@@ -56,7 +57,8 @@ function coerce(value) {
 		return null;
 	}
 	const alpha = typeof v.alpha === "number" ? v.alpha : void 0;
-	const hex = typeof v["hex"] === "string" ? v["hex"] : void 0;
+	const hexVal = v["hex"];
+	const hex = typeof hexVal === "string" ? hexVal : void 0;
 	return {
 		colorSpace,
 		components,
@@ -217,33 +219,23 @@ function ensureSubscribed$1() {
 	if (subscribed$1 || typeof window === "undefined") return;
 	subscribed$1 = true;
 	const channel = addons.getChannel();
+	let lastFingerprint = "";
 	const onGlobals = (payload) => {
 		const globals = payload.globals;
 		if (!globals) return;
-		let next = snapshot$1;
-		const nextAxes = globals[AXES_GLOBAL_KEY];
-		if (nextAxes && typeof nextAxes === "object") next = {
-			...next,
-			axes: nextAxes
-		};
-		const nextFormat = globals[COLOR_FORMAT_GLOBAL_KEY];
-		if (isColorFormat(nextFormat)) next = {
-			...next,
+		const incomingAxes = globals[AXES_GLOBAL_KEY];
+		const incomingFormat = globals[COLOR_FORMAT_GLOBAL_KEY];
+		const nextAxes = incomingAxes && typeof incomingAxes === "object" ? incomingAxes : snapshot$1.axes;
+		const nextFormat = isColorFormat(incomingFormat) ? incomingFormat : snapshot$1.format;
+		const fingerprint = `${nextFormat ?? ""}|${nextAxes ? JSON.stringify(nextAxes) : ""}`;
+		if (fingerprint === lastFingerprint) return;
+		lastFingerprint = fingerprint;
+		snapshot$1 = {
+			axes: nextAxes,
 			format: nextFormat
 		};
-		if (next !== snapshot$1) {
-			snapshot$1 = next;
-			for (const cb of listeners$1) cb();
-		}
+		for (const cb of listeners$1) cb();
 	};
-	/**
-	* `setGlobals` fires once on preview init carrying the URL-persisted user
-	* globals (Storybook stores toolbar selections in `?globals=…`). Without
-	* this listener, deeplinking to an MDX page with a non-default axis tuple
-	* or color format renders defaults for one frame before the first
-	* `updateGlobals` arrives. `emitGlobals()` reads from `userGlobals.get()`
-	* (current state), so the payload is never stale — safe to handle.
-	*/
 	channel.on("globalsUpdated", onGlobals);
 	channel.on("updateGlobals", onGlobals);
 	channel.on("setGlobals", onGlobals);
@@ -408,44 +400,24 @@ function defaultTuple$1(axes) {
 	return out;
 }
 /**
-* Stable string key for a tuple — axes sorted by name + `:` separator.
-* Matches the key form `buildResolveAt` uses in core so both surfaces
-* agree on what counts as "the same tuple."
+* Synthesize a permutation name from a tuple — same form
+* `permutationID` produces server-side (axis values joined by ` · `).
+* Used by the AxisVariance grid for `data-<prefix>-theme` attribution
+* and similar display-only callers.
 */
-function canonicalTupleKey(tuple) {
-	return Object.keys(tuple).toSorted().map((k) => `${k}:${tuple[k]}`).join("|");
+function tupleToName(axes, tuple) {
+	return axes.map((a) => tuple[a.name] ?? a.default).join(" · ");
 }
 /**
-* Build a `Map<canonicalKey, permutationName>` once per permutations
-* list so per-tuple lookups go through O(1) `Map.get` instead of an
-* `Array.prototype.find` scan per call. Bounded by the permutations
-* count regardless of how many lookups consumers do.
-*/
-function buildPermutationNameByTuple(permutations) {
-	const out = /* @__PURE__ */ new Map();
-	for (const perm of permutations) out.set(canonicalTupleKey(perm.input), perm.name);
-	return out;
-}
-const noPermutationName = () => void 0;
-function tuplesEqual(a, b) {
-	const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
-	for (const k of keys) if (a[k] !== b[k]) return false;
-	return true;
-}
-function nameForTuple(themesList, tuple) {
-	return themesList.find((t) => tuplesEqual(t.input, tuple))?.name;
-}
-/**
-* Reconstruct a `resolveAt` accessor from snapshot data. The wire
-* format ships `cells` as plain JSON and `jointOverrides` as an
-* array of `[key, entry]` pairs (Map doesn't survive JSON.stringify);
-* this hydrates them and wraps `buildResolveAt` from core. Stable
-* identity across calls with the same snapshot — `useMemo` keyed on
-* the snapshot fields produces a referentially stable function.
+* Reconstruct a `resolveAt` accessor from snapshot data. Both `cells`
+* and `jointOverrides` ship as plain JSON in the same shape core uses
+* internally — no Map reconstruction at the boundary. Stable identity
+* across calls with the same snapshot — `useMemo` keyed on the
+* snapshot fields produces a referentially stable function.
 */
 function makeResolveAt(snapshot) {
 	const cells = snapshot.cells ?? {};
-	const jointOverrides = new Map(snapshot.jointOverrides ?? []);
+	const jointOverrides = snapshot.jointOverrides ?? [];
 	const defaults = snapshot.defaultTuple ?? defaultTuple$1(snapshot.axes);
 	const resolver = buildResolveAt(snapshot.axes, cells, jointOverrides, defaults);
 	return (tuple) => resolver(tuple);
@@ -454,20 +426,14 @@ function makeResolveAt(snapshot) {
 * Build the `resolveAt` accessor for a snapshot. Prefers the
 * snapshot's own `resolveAt` (the addon's preview decorator
 * pre-builds one at module load — see `previewResolveAt` in
-* `packages/addon/src/preview.tsx`), falling back to constructing
-* one from `cells` + `jointOverrides` when present (covers
-* hand-built test snapshots and the no-provider path) and finally to
-* the legacy per-permutation lookup for snapshots that only carry
-* `permutationsResolved` + `permutations` (MDX consumers that
-* pre-date the wire format change).
+* `packages/addon/src/preview.tsx`), otherwise composes one from
+* `cells` + `jointOverrides` via `makeResolveAt`. Hand-built
+* snapshots should provide both via the test `withCellsShape`
+* helper or by populating the fields directly.
 */
 function snapshotResolveAt(snapshot) {
 	if (snapshot.resolveAt) return snapshot.resolveAt;
-	if (Object.keys(snapshot.cells ?? {}).length > 0) return makeResolveAt(snapshot);
-	return (tuple) => {
-		const perms = snapshot.permutations ?? [];
-		return (snapshot.permutationsResolved ?? {})[nameForTuple(perms, tuple) ?? snapshot.activePermutation] ?? {};
-	};
+	return makeResolveAt(snapshot);
 }
 /**
 * Reads project data either from a mounted {@link SwatchbookProvider}
@@ -487,7 +453,12 @@ function useProject() {
 	const cells = snapshot?.cells;
 	const jointOverrides = snapshot?.jointOverrides;
 	const dataDefaultTuple = snapshot?.defaultTuple;
+	const activeAxes = snapshot?.activeAxes;
 	const activePermutation = snapshot?.activePermutation;
+	const diagnostics = snapshot?.diagnostics;
+	const cssVarPrefix = snapshot?.cssVarPrefix;
+	const listing = snapshot?.listing;
+	const varianceByPath = snapshot?.varianceByPath;
 	const resolveAt = useMemo(() => {
 		if (!snapshot) return null;
 		return snapshotResolveAt(snapshot);
@@ -498,24 +469,36 @@ function useProject() {
 		dataDefaultTuple,
 		activePermutation
 	]);
-	const permutationNameByTuple = useMemo(() => buildPermutationNameByTuple(snapshot?.permutations ?? []), [snapshot?.permutations]);
-	const fallback = useVirtualModuleFallback(snapshot === null);
-	if (snapshot !== null && resolveAt !== null) return snapshotToData(snapshot, resolveAt, permutationNameByTuple);
-	return fallback;
-}
-function snapshotToData(snapshot, resolveAt, permutationNameByTuple) {
-	return {
-		activePermutation: snapshot.activePermutation,
-		activeAxes: snapshot.activeAxes,
-		axes: snapshot.axes,
-		resolved: resolveAt(snapshot.activeAxes),
-		diagnostics: snapshot.diagnostics,
-		cssVarPrefix: snapshot.cssVarPrefix,
-		listing: snapshot.listing ?? {},
-		varianceByPath: snapshot.varianceByPath ?? {},
+	const providerData = useMemo(() => {
+		if (!snapshot || !resolveAt || !axes || !activeAxes) return null;
+		return {
+			activePermutation: activePermutation ?? "",
+			activeAxes,
+			axes,
+			resolved: resolveAt(activeAxes),
+			diagnostics: diagnostics ?? [],
+			cssVarPrefix: cssVarPrefix ?? "",
+			listing: listing ?? {},
+			varianceByPath: varianceByPath ?? {},
+			resolveAt,
+			permutationNameForTuple: (tuple) => tupleToName(axes, tuple)
+		};
+	}, [
+		snapshot,
 		resolveAt,
-		permutationNameForTuple: (tuple) => permutationNameByTuple.get(canonicalTupleKey(tuple))
-	};
+		axes,
+		cells,
+		jointOverrides,
+		dataDefaultTuple,
+		activePermutation,
+		activeAxes,
+		diagnostics,
+		cssVarPrefix,
+		listing,
+		varianceByPath
+	]);
+	const fallback = useVirtualModuleFallback(snapshot === null);
+	return providerData ?? fallback;
 }
 function useVirtualModuleFallback(enabled) {
 	const contextPermutation = useActivePermutation();
@@ -533,8 +516,14 @@ function useVirtualModuleFallback(enabled) {
 		if (!enabled) return;
 		ensureStylesheet(tokens.css);
 	}, [enabled, tokens.css]);
-	const activeAxes = Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple$1(tokens.axes);
-	const activePermutation = contextPermutation || tokens.axes.map((a) => activeAxes[a.name] ?? a.default).join(" · ") || "";
+	const activeAxes = useMemo(() => {
+		return Object.keys(contextAxes).length > 0 ? { ...contextAxes } : channelGlobals.axes ?? defaultTuple$1(tokens.axes);
+	}, [
+		contextAxes,
+		channelGlobals.axes,
+		tokens.axes
+	]);
+	const activePermutation = contextPermutation || tupleToName(tokens.axes, activeAxes);
 	const resolveAt = useMemo(() => makeResolveAt({
 		axes: tokens.axes,
 		cells: tokens.cells,
@@ -546,32 +535,27 @@ function useVirtualModuleFallback(enabled) {
 		tokens.jointOverrides,
 		tokens.defaultTuple
 	]);
-	const resolved = resolveAt(activeAxes);
-	const permutationNameForTuple = noPermutationName;
-	return {
+	return useMemo(() => ({
 		activePermutation,
 		activeAxes,
 		axes: tokens.axes,
-		resolved,
+		resolved: resolveAt(activeAxes),
 		diagnostics: tokens.diagnostics,
 		cssVarPrefix: tokens.cssVarPrefix,
 		listing: tokens.listing,
 		varianceByPath: tokens.varianceByPath,
 		resolveAt,
-		permutationNameForTuple
-	};
-}
-/**
-* Thin wrapper around Terrazzo's `makeCSSVar` so the block-display surface
-* and `packages/core/src/css.ts`'s emitter share one implementation. Any
-* future naming-policy shift in Terrazzo (casing, unicode, prefix handling)
-* reaches both surfaces at once instead of needing a parallel update here.
-*/
-function makeCssVar(path, prefix) {
-	return prefix ? makeCSSVar(path, {
-		prefix,
-		wrapVar: true
-	}) : makeCSSVar(path, { wrapVar: true });
+		permutationNameForTuple: (tuple) => tupleToName(tokens.axes, tuple)
+	}), [
+		activePermutation,
+		activeAxes,
+		tokens.axes,
+		tokens.diagnostics,
+		tokens.cssVarPrefix,
+		tokens.listing,
+		tokens.varianceByPath,
+		resolveAt
+	]);
 }
 /**
 * Resolve a token's CSS var reference, preferring the authoritative name
@@ -654,15 +638,6 @@ function BorderSample({ path }) {
 //#endregion
 //#region src/internal/data-attr.ts
 /**
-* Produce a prefixed `data-*` attribute name when `prefix` is set, bare
-* `data-<key>` otherwise. Mirrors `dataAttr` in `@unpunnyfuns/swatchbook-core`
-* so block wrappers and emitted-CSS selectors stay in lockstep without
-* blocks taking a runtime dep on core.
-*/
-function dataAttr(prefix, key) {
-	return prefix ? `data-${prefix}-${key}` : `data-${key}`;
-}
-/**
 * Marker attribute set on every block wrapper. Retained as a stable hook
 * for consumer-side selectors (e.g. when a host app wants to target or
 * override block chrome without relying on hashed class names).
@@ -697,59 +672,73 @@ function themeAttrs(prefix, themeName) {
 }
 //#endregion
 //#region src/internal/sort-tokens.ts
-/**
-* Stable sort for a filtered `[path, token][]` list.
-*
-* `sortBy: 'path'` — lexicographic on the dot-path (locale-aware, numeric).
-* `sortBy: 'value'` — per-`$type` ordering:
-*   - `dimension` / `duration` → numeric pixels / ms (via `toMagnitude`).
-*   - `fontWeight` / `opacity` / `number` / `lineHeight` → numeric.
-*   - `color` → perceptual by oklch L → C → H.
-*   - `fontFamily` / `strokeStyle` (string form) → lexicographic.
-*   - Composites (`typography`, `shadow`, `border`, `gradient`, `transition`) →
-*     fall back to path-alpha. No useful single-axis order.
-* `sortBy: 'none'` — preserve input order (still respects `sortDir: 'desc'`
-*   as a reverse).
-*/
+const NUMERIC_TYPES = new Set([
+	"dimension",
+	"duration",
+	"fontWeight",
+	"opacity",
+	"number",
+	"lineHeight"
+]);
+const STRING_TYPES = new Set(["fontFamily", "strokeStyle"]);
+function computeSortKey(token) {
+	const type = token.$type;
+	if (!type) return { kind: "none" };
+	if (NUMERIC_TYPES.has(type)) {
+		const value = toMagnitude(token.$value);
+		return {
+			kind: "numeric",
+			value,
+			valid: Number.isFinite(value)
+		};
+	}
+	if (type === "color") return {
+		kind: "color",
+		key: colorKey(token.$value)
+	};
+	if (STRING_TYPES.has(type)) return {
+		kind: "string",
+		value: toDisplayable(token.$value)
+	};
+	return { kind: "none" };
+}
 function sortTokens(entries, options = {}) {
 	const by = options.by ?? "path";
 	const dir = options.dir ?? "asc";
 	const sign = dir === "desc" ? -1 : 1;
 	if (by === "none") return dir === "desc" ? [...entries].toReversed() : [...entries];
 	if (by === "path") return [...entries].toSorted(([a], [b]) => sign * a.localeCompare(b, void 0, { numeric: true }));
+	const keys = /* @__PURE__ */ new Map();
+	for (const [, token] of entries) keys.set(token, computeSortKey(token));
 	return [...entries].toSorted(([aPath, aTok], [bPath, bTok]) => {
-		const cmp = compareValue(aTok, bTok);
+		const cmp = compareValue(aTok, bTok, keys);
 		if (cmp !== 0) return sign * cmp;
 		return sign * aPath.localeCompare(bPath, void 0, { numeric: true });
 	});
 }
-function compareValue(a, b) {
-	const type = a.$type;
-	if (type !== b.$type) return String(type ?? "").localeCompare(String(b.$type ?? ""));
-	if (!type) return 0;
-	if (type === "dimension" || type === "duration" || type === "fontWeight" || type === "opacity" || type === "number" || type === "lineHeight") {
-		const av = toMagnitude(a.$value);
-		const bv = toMagnitude(b.$value);
-		if (Number.isFinite(av) && Number.isFinite(bv)) return av - bv;
-		if (Number.isFinite(av)) return -1;
-		if (Number.isFinite(bv)) return 1;
+function compareValue(a, b, keys) {
+	if (a.$type !== b.$type) return String(a.$type ?? "").localeCompare(String(b.$type ?? ""));
+	const ak = keys.get(a);
+	const bk = keys.get(b);
+	if (!ak || !bk) return 0;
+	if (ak.kind !== bk.kind) return 0;
+	if (ak.kind === "numeric" && bk.kind === "numeric") {
+		if (ak.valid && bk.valid) return ak.value - bk.value;
+		if (ak.valid) return -1;
+		if (bk.valid) return 1;
 		return 0;
 	}
-	if (type === "color") {
-		const ak = colorKey(a.$value);
-		const bk = colorKey(b.$value);
-		if (!ak && !bk) return 0;
-		if (!ak) return 1;
-		if (!bk) return -1;
-		if (ak.l !== bk.l) return ak.l - bk.l;
-		if (ak.c !== bk.c) return ak.c - bk.c;
-		return ak.h - bk.h;
-	}
-	if (type === "fontFamily" || type === "strokeStyle") {
-		const as = toDisplayable(a.$value);
-		const bs = toDisplayable(b.$value);
-		return as.localeCompare(bs, void 0, { numeric: true });
+	if (ak.kind === "color" && bk.kind === "color") {
+		const a3 = ak.key;
+		const b3 = bk.key;
+		if (!a3 && !b3) return 0;
+		if (!a3) return 1;
+		if (!b3) return -1;
+		if (a3.l !== b3.l) return a3.l - b3.l;
+		if (a3.c !== b3.c) return a3.c - b3.c;
+		return a3.h - b3.h;
 	}
+	if (ak.kind === "string" && bk.kind === "string") return ak.value.localeCompare(bk.value, void 0, { numeric: true });
 	return 0;
 }
 function toMagnitude(v) {
@@ -769,6 +758,14 @@ function toMagnitude(v) {
 	}
 	return NaN;
 }
+/**
+* Coerce a possibly-null/undefined number to 0 — `coords` returns
+* `(number | null)[]` and `noUncheckedIndexedAccess` adds `undefined`
+* on top. `typeof` narrows the union for the comparator below.
+*/
+function safeNumber(v) {
+	return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
 function colorKey(v) {
 	if (!v || typeof v !== "object") return null;
 	try {
@@ -785,9 +782,9 @@ function colorKey(v) {
 		} else return null;
 		const [l, chroma, h] = new Color(source).to("oklch").coords;
 		return {
-			l: Number.isFinite(l) ? l : 0,
-			c: Number.isFinite(chroma) ? chroma : 0,
-			h: Number.isFinite(h) ? h : 0
+			l: safeNumber(l),
+			c: safeNumber(chroma),
+			h: safeNumber(h)
 		};
 	} catch {
 		return null;
@@ -2117,9 +2114,9 @@ function GradientPalette({ filter, caption, sortBy = "path", sortDir = "asc" })
 * True when rendering inside Chromatic's snapshot runner. Chromatic's
 * browser ships a recognisable user-agent string; checked here so
 * motion-looping components can fall back to their static state for
-* deterministic snapshots without needing a global Chromatic parameter
-* (globally forcing `prefersReducedMotion: true` broke Chromatic's
-* verification parser in our setup — see commit 893331f).
+* deterministic snapshots. Per-component detection rather than the
+* global `chromatic.prefersReducedMotion: true` parameter — that
+* parameter is incompatible with Chromatic's verification parser.
 */
 function isChromatic() {
 	if (typeof navigator === "undefined") return false;
@@ -2887,14 +2884,19 @@ function AxisVariance({ path }) {
 	const formatFn = (t) => valueFor(t, tokenType, colorFormat);
 	const variance = useMemo(() => {
 		const result = varianceByPath[path];
-		if (!result) return {
-			kind: "constant",
-			varyingAxes: []
-		};
-		return {
-			kind: result.kind === "constant" ? "constant" : result.kind === "single" ? "one-axis" : "multi-axis",
-			varyingAxes: result.varyingAxes
-		};
+		if (!result) return { kind: "constant" };
+		switch (result.kind) {
+			case "constant": return { kind: "constant" };
+			case "single": return {
+				kind: "one-axis",
+				axis: result.axis,
+				varyingAxes: result.varyingAxes
+			};
+			case "multi": return {
+				kind: "multi-axis",
+				varyingAxes: result.varyingAxes
+			};
+		}
 	}, [path, varianceByPath]);
 	if (axes.length === 0) return /* @__PURE__ */ jsx(Fragment$1, {});
 	if (variance.kind === "constant") {
@@ -2930,8 +2932,7 @@ function AxisVariance({ path }) {
 		})] });
 	}
 	if (variance.kind === "one-axis") {
-		const axisName = variance.varyingAxes[0];
-		if (!axisName) return /* @__PURE__ */ jsx(Fragment$1, {});
+		const axisName = variance.axis;
 		const axis = axes.find((a) => a.name === axisName);
 		if (!axis) return /* @__PURE__ */ jsx(Fragment$1, {});
 		const contextValues = axis.contexts.map((ctx) => {
@@ -3775,6 +3776,7 @@ function buildTree(resolved, root, typeFilter) {
 		let node = rootNode;
 		for (let i = 0; i < segments.length - 1; i += 1) {
 			const seg = segments[i];
+			if (seg === void 0) continue;
 			const prefix = [...rootSegments, ...segments.slice(0, i + 1)].join(".");
 			let child = node.children.find((c) => c.kind === "group" && c.segment === seg);
 			if (!child) {