@ccheever/exact-facet-core 0.1.0

package/src/internals.ts

@@ -0,0 +1,1313 @@
+// @system @ref LLP 0157 — facet-core: framework-neutral heart of the Facet design system.
+//
+// Everything in this module is pure data or pure functions over
+// `theme + options -> style object`. It was moved verbatim from
+// `@exact/facet`'s internals (LLP 0008) as the F0 extraction; the React
+// package re-exports all of it, so the React-facing API is unchanged.
+//
+// Dependency rule (enforced by the `facet-core-import-boundary` check):
+// this package may import from `@exact/core` only — no `react`, no
+// `solid-js`, no `vue`, no `svelte`, and no `@exact/renderer`.
+
+import { colorToRgba, parseColor } from '@exact/core/style/color';
+import type {
+  SpringTransition,
+  TransitionEasing,
+  TransitionMap,
+} from '@exact/core/style/transitions';
+
+export type Scheme = 'light' | 'dark';
+export type SizeClass = 'compact' | 'regular' | 'expanded';
+export type PresencePhase = 'entering' | 'entered' | 'exiting';
+export type FieldVariant = 'default' | 'filled' | 'ghost';
+export type FieldValidationState = 'default' | 'error' | 'success';
+export type MotionTransform = Array<
+  | { translateX: number }
+  | { translateY: number }
+  | { scale: number }
+>;
+
+export type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+export interface ShadowSpec {
+  x: number;
+  y: number;
+  blur: number;
+  spread?: number;
+  color: string;
+  opacity?: number;
+}
+
+export interface SizeClassToken {
+  minWidth?: number;
+  maxWidth?: number;
+}
+
+export type SizeClassTokens = Record<SizeClass, SizeClassToken>;
+
+// @system @ref LLP 0269 Part III — the resolved semantic token taxonomy.
+//
+// `FacetTheme` is the *resolved* theme components read: every leaf names its
+// purpose, not its appearance, so themes, schemes, density, and locales vary
+// automatically. It is the output of `resolve(definition)` — see
+// `theme-definition.ts` for `FacetThemeDefinition` and `resolveFacetTheme`.
+// The old flat `FacetTheme` (a hand-authored token bag) was deleted in this
+// revision; there are no `LegacyFacet*` aliases (pre-release execution note).
+
+/** A status colour family — fill, its muted background, on-fill text, the
+ * status text colour for muted surfaces, and a border. Status badges, alerts,
+ * validation states, and destructive actions read these rather than inventing
+ * one-off contrast pairs. */
+export interface StatusColorSet {
+  fill: string;
+  muted: string;
+  text: string;
+  onFill: string;
+  border: string;
+}
+
+export interface FacetColorTokens {
+  /** Surface layers, lightest/recessed → most raised. `surface` is the subtle
+   * inset neutral (secondary control fill); `card`/`popover` are raised. */
+  background: {
+    body: string;
+    surface: string;
+    card: string;
+    popover: string;
+    inverted: string;
+  };
+  text: {
+    primary: string;
+    secondary: string;
+    disabled: string;
+    accent: string;
+    onAccent: string;
+    onDanger: string;
+    onSuccess: string;
+    onWarning: string;
+  };
+  icon: {
+    primary: string;
+    secondary: string;
+    disabled: string;
+    accent: string;
+  };
+  border: {
+    subtle: string;
+    default: string;
+    strong: string;
+    focus: string;
+  };
+  status: {
+    success: StatusColorSet;
+    warning: StatusColorSet;
+    danger: StatusColorSet;
+    info: StatusColorSet;
+  };
+  /** Generic interaction overlays composited over a base surface. */
+  overlay: {
+    scrim: string;
+    hover: string;
+    pressed: string;
+    selected: string;
+  };
+  accent: {
+    fill: string;
+    hover: string;
+    pressed: string;
+    text: string;
+    onFill: string;
+  };
+}
+
+export interface FacetSpaceTokens {
+  xs: number;
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+}
+
+export type DensitySize = 'sm' | 'md' | 'lg';
+
+/** Density resolves comfort/spacing intent into concrete control sizing. The
+ * `mode` echoes the definition dial. `paddingScale` is the multiplier recipes
+ * apply at apply-time (LLP 0269 §6 context-computed values). */
+export interface FacetDensityTokens {
+  mode: ThemeDensity;
+  controlHeight: Record<DensitySize, number>;
+  rowHeight: number;
+  iconSize: Record<DensitySize, number>;
+  minHitTarget: number;
+  paddingScale: number;
+}
+
+export interface FacetTypeRole {
+  fontSize: number;
+  lineHeight: number;
+  fontWeight: number;
+  /** A font-family stack (array form the renderer already understands on every
+   * platform), not a CSS comma string. */
+  fontFamily: readonly string[];
+  letterSpacing?: number;
+}
+
+export interface FacetTypeTokens {
+  caption: FacetTypeRole;
+  body: FacetTypeRole;
+  bodyStrong: FacetTypeRole;
+  label: FacetTypeRole;
+  title: FacetTypeRole;
+  heading: FacetTypeRole;
+  display: FacetTypeRole;
+  code: FacetTypeRole;
+  families: {
+    body: readonly string[];
+    heading: readonly string[];
+    mono: readonly string[];
+  };
+}
+
+/** Semantic radius levels. `inner` is the concentric inner default; recipes
+ * compute per-instance concentricity via `concentricRadius(outer, padding)`. */
+export interface FacetRadiusTokens {
+  none: number;
+  inner: number;
+  element: number;
+  container: number;
+  page: number;
+  full: number;
+}
+
+export interface FacetElevationTokens {
+  low: ShadowSpec;
+  medium: ShadowSpec;
+  high: ShadowSpec;
+}
+
+export interface FacetZIndexTokens {
+  base: number;
+  dropdown: number;
+  sticky: number;
+  modal: number;
+  toast: number;
+  tooltip: number;
+}
+
+export interface FacetMotionTokens {
+  reducedMotion: boolean;
+  /** The definition's motion multiplier, carried for inspection/agents. */
+  multiplier: number;
+  duration: {
+    fast: number;
+    normal: number;
+    slow: number;
+  };
+  easing: {
+    enter: TransitionEasing;
+    exit: TransitionEasing;
+    move: TransitionEasing;
+    /** 0260 Proposal I's single standard curve, aliased onto `move`. */
+    standard: TransitionEasing;
+  };
+  spring: {
+    default: SpringTransition;
+    snappy: SpringTransition;
+  };
+  preset: {
+    control: TransitionMap;
+    controlPress: TransitionMap;
+    selection: TransitionMap;
+    tabIndicator: TransitionMap;
+    fadeIn: TransitionMap;
+    fadeOut: TransitionMap;
+    scaleIn: TransitionMap;
+    popIn: TransitionMap;
+    popOut: TransitionMap;
+    slideUp: TransitionMap;
+    slideDown: TransitionMap;
+  };
+}
+
+export type ThemeContrast = 'standard' | 'increased';
+export type PlatformFamily = 'apple' | 'android' | 'windows' | 'web';
+
+/** Adaptation preferences as resolved token input (LLP 0269 §9) — recipes and
+ * native bridges consume these; app code does not branch on them by default. */
+export interface FacetAdaptationTokens {
+  scheme: Scheme;
+  sizeClass: SizeClass;
+  reducedMotion: boolean;
+  textScale: number;
+  contrast: ThemeContrast;
+  platform: PlatformFamily;
+}
+
+export interface FacetTheme {
+  name: string;
+  scheme: Scheme;
+  /** Active viewport/host size class resolved from `sizeClasses` (LLP 0195 S0). */
+  sizeClass: SizeClass;
+  /** Framework-neutral size-class tokens, shared by Contract and React lanes. */
+  sizeClasses: SizeClassTokens;
+  color: FacetColorTokens;
+  space: FacetSpaceTokens;
+  density: FacetDensityTokens;
+  type: FacetTypeTokens;
+  radius: FacetRadiusTokens;
+  elevation: FacetElevationTokens;
+  zIndex: FacetZIndexTokens;
+  motion: FacetMotionTokens;
+  adaptation: FacetAdaptationTokens;
+}
+
+/** Spec name from LLP 0269 §2. Kept as an alias so references to the
+ * "resolved theme" type resolve; the public name stays `FacetTheme`. */
+export type ResolvedFacetTheme = FacetTheme;
+
+/** The density dial values (LLP 0269 §5). Defined here because
+ * `FacetDensityTokens.mode` references it; the full definition lives in
+ * `theme-definition.ts`. */
+export type ThemeDensity = 'compact' | 'default' | 'comfortable' | 'gigantic';
+
+export const defaultSizeClasses: SizeClassTokens = {
+  compact: { maxWidth: 599 },
+  regular: { minWidth: 600, maxWidth: 1023 },
+  expanded: { minWidth: 1024 },
+};
+
+const SIZE_CLASS_ORDER: SizeClass[] = ['compact', 'regular', 'expanded'];
+
+export function resolveSizeClassForWidth(
+  width: number,
+  sizeClasses: SizeClassTokens = defaultSizeClasses,
+): SizeClass {
+  const safeWidth = Number.isFinite(width) ? Math.max(0, width) : 0;
+  for (const name of SIZE_CLASS_ORDER) {
+    const token = sizeClasses[name];
+    const min = token.minWidth ?? Number.NEGATIVE_INFINITY;
+    const max = token.maxWidth ?? Number.POSITIVE_INFINITY;
+    if (safeWidth >= min && safeWidth <= max) {
+      return name;
+    }
+  }
+  return 'expanded';
+}
+
+export const facetSansFontFamily = [
+  '-apple-system',
+  'BlinkMacSystemFont',
+  'Inter',
+  'Segoe UI',
+  'system-ui',
+  'Helvetica Neue',
+  'sans-serif',
+] as const;
+
+function cloneTransitionMap(map: TransitionMap): TransitionMap {
+  return { ...map };
+}
+
+function stripTransformTransition(map: TransitionMap): TransitionMap {
+  const next = { ...map };
+  delete next.transform;
+  return next;
+}
+
+export function buildFacetMotion(
+  reducedMotion: boolean,
+  multiplier: number = 1,
+): FacetMotionTokens {
+  // The motion multiplier (LLP 0269 §8) is a definition dial; it scales every
+  // resolved duration. Clamp to a sane range so a hostile dial cannot freeze or
+  // stall the UI.
+  const scale = Number.isFinite(multiplier) ? clamp(multiplier, 0, 4) : 1;
+  const round = (ms: number): number => Math.max(0, Math.round(ms * scale));
+  const duration = {
+    fast: round(100),
+    normal: round(200),
+    slow: round(300),
+  } as const;
+  const easing = {
+    enter: 'easeOut' as const,
+    exit: 'easeIn' as const,
+    move: 'easeInOut' as const,
+    standard: 'easeInOut' as const,
+  };
+  const spring = {
+    default: {
+      type: 'spring' as const,
+      damping: 20,
+      stiffness: 300,
+    },
+    snappy: {
+      type: 'spring' as const,
+      damping: 22,
+      stiffness: 350,
+    },
+  };
+  const fadeIn: TransitionMap = {
+    opacity: { type: 'timing', duration: duration.normal, easing: easing.enter },
+  };
+  const fadeOut: TransitionMap = {
+    opacity: { type: 'timing', duration: round(150), easing: easing.exit },
+  };
+  const control: TransitionMap = {
+    backgroundColor: { type: 'timing', duration: duration.fast, easing: easing.move },
+    borderRadius: { type: 'timing', duration: duration.fast, easing: easing.move },
+  };
+  const controlPress: TransitionMap = reducedMotion
+    ? cloneTransitionMap(control)
+    : {
+        ...cloneTransitionMap(control),
+        transform: { type: 'timing', duration: duration.fast, easing: easing.move },
+      };
+  const selection: TransitionMap = reducedMotion
+    ? {
+        backgroundColor: { type: 'timing', duration: duration.fast, easing: easing.move },
+      }
+    : {
+        backgroundColor: { type: 'timing', duration: duration.fast, easing: easing.move },
+        transform: { type: 'timing', duration: duration.fast, easing: easing.move },
+      };
+  const tabIndicator: TransitionMap = reducedMotion
+    ? {
+        opacity: { type: 'timing', duration: duration.fast, easing: easing.move },
+      }
+    : {
+        opacity: { type: 'timing', duration: duration.fast, easing: easing.move },
+        transform: spring.snappy,
+      };
+  const scaleIn: TransitionMap = reducedMotion
+    ? {}
+    : {
+        transform: spring.snappy,
+      };
+  const popIn: TransitionMap = reducedMotion
+    ? cloneTransitionMap(fadeIn)
+    : {
+        opacity: { type: 'timing', duration: round(150), easing: easing.enter },
+        transform: { type: 'timing', duration: round(150), easing: easing.enter },
+      };
+  const popOut: TransitionMap = reducedMotion
+    ? cloneTransitionMap(fadeOut)
+    : {
+        opacity: { type: 'timing', duration: duration.fast, easing: easing.exit },
+        transform: { type: 'timing', duration: duration.fast, easing: easing.exit },
+      };
+  const slideUp: TransitionMap = reducedMotion
+    ? cloneTransitionMap(fadeIn)
+    : {
+        opacity: { type: 'timing', duration: round(250), easing: easing.enter },
+        transform: { type: 'timing', duration: round(250), easing: easing.enter },
+      };
+  const slideDown: TransitionMap = reducedMotion
+    ? cloneTransitionMap(fadeOut)
+    : {
+        opacity: { type: 'timing', duration: duration.normal, easing: easing.exit },
+        transform: { type: 'timing', duration: duration.normal, easing: easing.exit },
+      };
+
+  return {
+    reducedMotion,
+    multiplier: scale,
+    duration,
+    easing,
+    spring,
+    preset: {
+      control,
+      controlPress,
+      selection,
+      tabIndicator,
+      fadeIn,
+      fadeOut,
+      scaleIn,
+      popIn,
+      popOut,
+      slideUp,
+      slideDown,
+    },
+  };
+}
+
+export function applyMotionPreference(
+  animation: FacetMotionTokens,
+  reducedMotion: boolean,
+): FacetMotionTokens {
+  if (!reducedMotion) {
+    return {
+      ...animation,
+      reducedMotion: false,
+      preset: {
+        control: cloneTransitionMap(animation.preset.control),
+        controlPress: cloneTransitionMap(animation.preset.controlPress),
+        selection: cloneTransitionMap(animation.preset.selection),
+        tabIndicator: cloneTransitionMap(animation.preset.tabIndicator),
+        fadeIn: cloneTransitionMap(animation.preset.fadeIn),
+        fadeOut: cloneTransitionMap(animation.preset.fadeOut),
+        scaleIn: cloneTransitionMap(animation.preset.scaleIn),
+        popIn: cloneTransitionMap(animation.preset.popIn),
+        popOut: cloneTransitionMap(animation.preset.popOut),
+        slideUp: cloneTransitionMap(animation.preset.slideUp),
+        slideDown: cloneTransitionMap(animation.preset.slideDown),
+      },
+    };
+  }
+
+  return {
+    ...animation,
+    reducedMotion: true,
+    preset: {
+      control: stripTransformTransition(animation.preset.control),
+      controlPress: stripTransformTransition(animation.preset.controlPress),
+      selection: stripTransformTransition(animation.preset.selection),
+      tabIndicator: stripTransformTransition(animation.preset.tabIndicator),
+      fadeIn: stripTransformTransition(animation.preset.fadeIn),
+      fadeOut: stripTransformTransition(animation.preset.fadeOut),
+      scaleIn: stripTransformTransition(animation.preset.scaleIn),
+      popIn: stripTransformTransition(animation.preset.popIn),
+      popOut: stripTransformTransition(animation.preset.popOut),
+      slideUp: stripTransformTransition(animation.preset.slideUp),
+      slideDown: stripTransformTransition(animation.preset.slideDown),
+    },
+  };
+}
+
+export function buildMotionTransform(
+  theme: FacetTheme,
+  transform: MotionTransform,
+): MotionTransform | undefined {
+  return theme.motion.reducedMotion ? undefined : transform;
+}
+
+function resolvePlacementSide(
+  placement: string | undefined,
+): 'top' | 'right' | 'bottom' | 'left' {
+  const side = placement?.split('-')[0];
+  if (side === 'top' || side === 'right' || side === 'left') {
+    return side;
+  }
+  return 'bottom';
+}
+
+export function resolveSheetHiddenTransform(
+  theme: FacetTheme,
+  side: 'left' | 'right' | 'bottom',
+): MotionTransform | undefined {
+  if (side === 'left') {
+    return buildMotionTransform(theme, [{ translateX: -28 }]);
+  }
+  if (side === 'bottom') {
+    return buildMotionTransform(theme, [{ translateY: 28 }]);
+  }
+  return buildMotionTransform(theme, [{ translateX: 28 }]);
+}
+
+export function resolveSheetVisibleTransform(
+  theme: FacetTheme,
+  side: 'left' | 'right' | 'bottom',
+): MotionTransform | undefined {
+  if (side === 'bottom') {
+    return buildMotionTransform(theme, [{ translateY: 0 }]);
+  }
+  return buildMotionTransform(theme, [{ translateX: 0 }]);
+}
+
+export function resolveFloatingHiddenTransform(
+  theme: FacetTheme,
+  placement: string | undefined,
+  distance: number = 8,
+): MotionTransform | undefined {
+  const side = resolvePlacementSide(placement);
+  if (side === 'top') {
+    return buildMotionTransform(theme, [{ translateY: distance }]);
+  }
+  if (side === 'left') {
+    return buildMotionTransform(theme, [{ translateX: distance }]);
+  }
+  if (side === 'right') {
+    return buildMotionTransform(theme, [{ translateX: -distance }]);
+  }
+  return buildMotionTransform(theme, [{ translateY: -distance }]);
+}
+
+export function resolveFloatingVisibleTransform(
+  theme: FacetTheme,
+  placement: string | undefined,
+): MotionTransform | undefined {
+  const side = resolvePlacementSide(placement);
+  if (side === 'top' || side === 'bottom') {
+    return buildMotionTransform(theme, [{ translateY: 0 }]);
+  }
+  return buildMotionTransform(theme, [{ translateX: 0 }]);
+}
+
+export function resolvePresenceMotionStyle(
+  phase: PresencePhase,
+  options: {
+    enterTransition: TransitionMap;
+    exitTransition?: TransitionMap;
+    enteredStyle?: Record<string, unknown>;
+    enteringStyle?: Record<string, unknown>;
+    exitingStyle?: Record<string, unknown>;
+  },
+): Record<string, unknown> {
+  const enteredStyle = options.enteredStyle ?? {};
+  if (phase === 'entered') {
+    return {
+      ...enteredStyle,
+      transition: options.enterTransition,
+    };
+  }
+  if (phase === 'entering') {
+    return {
+      ...enteredStyle,
+      ...(options.enteringStyle ?? {}),
+      transition: options.enterTransition,
+    };
+  }
+  return {
+    ...enteredStyle,
+    ...(options.exitingStyle ?? options.enteringStyle ?? {}),
+    transition: options.exitTransition ?? options.enterTransition,
+  };
+}
+
+export function mergeFloatingMotionStyle(
+  floatingStyle: Record<string, unknown>,
+  motionStyle: Record<string, unknown>,
+): Record<string, unknown> {
+  const floatingOpacity =
+    typeof floatingStyle.opacity === 'number'
+      ? floatingStyle.opacity
+      : undefined;
+  const motionOpacity =
+    typeof motionStyle.opacity === 'number'
+      ? motionStyle.opacity
+      : undefined;
+
+  return {
+    ...floatingStyle,
+    ...motionStyle,
+    opacity:
+      floatingOpacity !== undefined && motionOpacity !== undefined
+        ? floatingOpacity * motionOpacity
+        : motionOpacity ?? floatingOpacity,
+    pointerEvents: floatingStyle.pointerEvents,
+  };
+}
+
+// `lightTheme` / `darkTheme` are no longer hand-authored token bags. They are
+// `resolveFacetTheme(defaultThemeDefinition, { scheme })` and live in
+// `theme-definition.ts` alongside the definition + resolver. The shipped Facet
+// look (a cool near-monochrome neutral ramp, hairline borders, a single indigo
+// accent — the Linear / Vercel / Stripe family) is now the *default
+// definition's* resolved output. `index.ts` re-exports them.
+
+const facetWarnedMessages = new Set<string>();
+
+export function deepMerge<T extends Record<string, any>>(
+  base: T,
+  override: DeepPartial<T> | null | undefined,
+): T {
+  if (!override) {
+    return base;
+  }
+
+  const result = { ...base } as T;
+  for (const key of Object.keys(override) as Array<keyof T>) {
+    const overrideValue = override[key];
+    if (overrideValue === undefined) {
+      continue;
+    }
+
+    const baseValue = result[key];
+    if (
+      baseValue &&
+      typeof baseValue === 'object' &&
+      !Array.isArray(baseValue) &&
+      overrideValue &&
+      typeof overrideValue === 'object' &&
+      !Array.isArray(overrideValue)
+    ) {
+      result[key] = deepMerge(baseValue, overrideValue as DeepPartial<typeof baseValue>) as T[keyof T];
+    } else {
+      result[key] = overrideValue as T[keyof T];
+    }
+  }
+
+  return result;
+}
+
+export function provenanceProps(
+  componentName: string,
+  slotName?: string,
+  variantProps?: Record<string, unknown>,
+  sourceFilePath: string = 'packages/exact-facet/src',
+): Record<string, unknown> {
+  return {
+    __exactComponentName: componentName,
+    __exactComponentSlot: slotName,
+    __exactSourceFilePath: sourceFilePath,
+    __exactVariantProps: variantProps ? JSON.stringify(variantProps) : undefined,
+  };
+}
+
+export function isFacetDevMode(): boolean {
+  const runtime = globalThis as typeof globalThis & {
+    __DEV__?: boolean;
+    process?: {
+      env?: {
+        NODE_ENV?: string;
+      };
+    };
+  };
+
+  if (typeof runtime.__DEV__ === 'boolean') {
+    return runtime.__DEV__;
+  }
+
+  return runtime.process?.env?.NODE_ENV !== 'production';
+}
+
+export function warnFacetOnce(message: string): void {
+  if (!isFacetDevMode() || facetWarnedMessages.has(message)) {
+    return;
+  }
+
+  facetWarnedMessages.add(message);
+  console.warn(message);
+}
+
+export function resolveCompactInset(theme: FacetTheme): number {
+  return Math.max(1, Math.round(theme.space.xs / 3));
+}
+
+/**
+ * Density-scaled padding (LLP 0269 §5): the apply-time mechanism that makes
+ * the density dial *felt*. Recipes pass a base from the space scale and the
+ * instance applies `density.paddingScale`. A non-finite or non-positive
+ * scale falls back to 1 so a malformed override can never zero out control
+ * padding. Default density (`paddingScale: 1`) is byte-identical to the
+ * unscaled base.
+ */
+export function resolveDensityPadding(theme: FacetTheme, base: number): number {
+  const scale = theme.density?.paddingScale;
+  const multiplier =
+    typeof scale === 'number' && Number.isFinite(scale) && scale > 0 ? scale : 1;
+  if (multiplier === 1) {
+    // Identity, exactly: the default density passes the base through
+    // untouched — byte-identical values AND an intact provenance sentinel
+    // (the D0 tracing still sees the raw token, e.g. `space.md`).
+    return base;
+  }
+  return Math.max(0, Math.round(base * multiplier));
+}
+
+export function resolveFocusRingInset(theme: FacetTheme): number {
+  return Math.max(1, Math.round(theme.space.xs / 2));
+}
+
+export function resolveInlineInset(theme: FacetTheme): number {
+  return Math.max(theme.space.xs, Math.round((theme.space.xs + theme.space.sm) / 2));
+}
+
+export function resolveFloatingViewportPadding(theme: FacetTheme): number {
+  return Math.round((theme.space.sm + theme.space.md) / 2);
+}
+
+export function resolveThemeColorContrastPair(
+  foreground: string,
+  background: string,
+): number | null {
+  const parsedForeground = parseColor(foreground);
+  const parsedBackground = parseColor(background);
+  if (!parsedForeground || !parsedBackground) {
+    return null;
+  }
+
+  const alpha = parsedForeground.a / 255;
+  const compositedForeground = alpha >= 1
+    ? parsedForeground
+    : {
+        r: Math.round(parsedForeground.r * alpha + parsedBackground.r * (1 - alpha)),
+        g: Math.round(parsedForeground.g * alpha + parsedBackground.g * (1 - alpha)),
+        b: Math.round(parsedForeground.b * alpha + parsedBackground.b * (1 - alpha)),
+        a: 255,
+      };
+
+  const toLinear = (channel: number): number => {
+    const normalized = channel / 255;
+    return normalized <= 0.03928
+      ? normalized / 12.92
+      : ((normalized + 0.055) / 1.055) ** 2.4;
+  };
+  const luminance = (color: { r: number; g: number; b: number }): number => (
+    0.2126 * toLinear(color.r) +
+    0.7152 * toLinear(color.g) +
+    0.0722 * toLinear(color.b)
+  );
+  const foregroundLuminance = luminance(compositedForeground);
+  const backgroundLuminance = luminance(parsedBackground);
+  const lighter = Math.max(foregroundLuminance, backgroundLuminance);
+  const darker = Math.min(foregroundLuminance, backgroundLuminance);
+
+  return Number(((lighter + 0.05) / (darker + 0.05)).toFixed(2));
+}
+
+export function validateFacetContrast(theme: FacetTheme): string[] {
+  const { color } = theme;
+  const surfaces = [
+    ['body', color.background.body],
+    ['surface', color.background.surface],
+    ['card', color.background.card],
+  ] as const;
+
+  const contrastChecks: Array<{ label: string; foreground: string; background: string }> = [];
+  for (const [name, bg] of surfaces) {
+    contrastChecks.push({ label: `text.primary on ${name}`, foreground: color.text.primary, background: bg });
+    contrastChecks.push({ label: `text.secondary on ${name}`, foreground: color.text.secondary, background: bg });
+  }
+  contrastChecks.push(
+    { label: 'accent.onFill on accent.fill', foreground: color.accent.onFill, background: color.accent.fill },
+    { label: 'accent.onFill on accent.hover', foreground: color.accent.onFill, background: color.accent.hover },
+    { label: 'accent.onFill on accent.pressed', foreground: color.accent.onFill, background: color.accent.pressed },
+    { label: 'status.success onFill', foreground: color.status.success.onFill, background: color.status.success.fill },
+    { label: 'status.danger onFill', foreground: color.status.danger.onFill, background: color.status.danger.fill },
+    { label: 'status.warning onFill', foreground: color.status.warning.onFill, background: color.status.warning.fill },
+    { label: 'status.info onFill', foreground: color.status.info.onFill, background: color.status.info.fill },
+  );
+
+  return contrastChecks.flatMap((check) => {
+    const ratio = resolveThemeColorContrastPair(check.foreground, check.background);
+    if (ratio == null || ratio >= 4.5) {
+      return [];
+    }
+    return [`${check.label} (${ratio}:1)`];
+  });
+}
+
+export function combineAccessibilityIds(
+  ...ids: Array<string | undefined>
+): string | undefined {
+  const uniqueIds = Array.from(
+    new Set(
+      ids
+        .flatMap((value) => (typeof value === 'string' ? value.split(/\s+/) : []))
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0),
+    ),
+  );
+
+  return uniqueIds.length > 0 ? uniqueIds.join(' ') : undefined;
+}
+
+export function pickFieldTextStyle(
+  style: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!style) {
+    return {};
+  }
+
+  const keys = [
+    'color',
+    'fontFamily',
+    'fontSize',
+    'fontStyle',
+    'fontWeight',
+    'letterSpacing',
+    'lineHeight',
+    'textAlign',
+    'textTransform',
+  ] as const;
+
+  const textStyle: Record<string, unknown> = {};
+  for (const key of keys) {
+    if (style[key] !== undefined) {
+      textStyle[key] = style[key];
+    }
+  }
+  return textStyle;
+}
+
+export function mergeEventHandlers<T extends (...args: any[]) => void>(
+  first: T | undefined,
+  second: T | undefined,
+): T | undefined {
+  if (!first) {
+    return second;
+  }
+  if (!second) {
+    return first;
+  }
+  return (((...args: Parameters<T>) => {
+    first(...args);
+    second(...args);
+  }) as T);
+}
+
+/**
+ * Returns `color` with its alpha multiplied by `alpha` (0..1), as an rgba()
+ * string. Used wherever a web `boxShadow`/halo needs the translucent form of
+ * a token while native keeps the opaque color + a separate opacity field.
+ */
+export function withAlpha(color: string, alpha: number): string {
+  const parsed = parseColor(color);
+  if (!parsed) {
+    return color;
+  }
+  const weight = Math.max(0, Math.min(alpha, 1));
+  return colorToRgba({ ...parsed, a: Math.round(parsed.a * weight) });
+}
+
+export function applyShadow(shadow: ShadowSpec): Record<string, unknown> {
+  const opacity = shadow.opacity ?? 1;
+  return {
+    // The CSS string is the web truth and must carry the opacity itself —
+    // native reads the separate shadowColor/shadowOpacity fields instead.
+    boxShadow: `${shadow.x}px ${shadow.y}px ${shadow.blur}px ${shadow.spread ?? 0}px ${withAlpha(shadow.color, opacity)}`,
+    shadowColor: shadow.color,
+    shadowOffset: { width: shadow.x, height: shadow.y },
+    shadowRadius: shadow.blur,
+    shadowOpacity: opacity,
+  };
+}
+
+export function mixColors(base: string, target: string, amount: number): string {
+  const baseColor = parseColor(base);
+  const targetColor = parseColor(target);
+  if (!baseColor || !targetColor) {
+    return base;
+  }
+
+  const weight = Math.max(0, Math.min(amount, 1));
+  return colorToRgba({
+    r: Math.round(baseColor.r + (targetColor.r - baseColor.r) * weight),
+    g: Math.round(baseColor.g + (targetColor.g - baseColor.g) * weight),
+    b: Math.round(baseColor.b + (targetColor.b - baseColor.b) * weight),
+    a: Math.round(baseColor.a + (targetColor.a - baseColor.a) * weight),
+  });
+}
+
+/**
+ * Solid hover/pressed states for the neutral inset surface
+ * (`color.background.surface`). The old flat theme carried precomputed
+ * `surfaceAltHovered` / `surfaceAltPressed`; the resolved taxonomy expresses
+ * the same intent as the overlay system, so secondary controls darken
+ * consistently with ghost controls. Computed as a solid because native paths
+ * prefer an opaque fill to a composited translucent overlay.
+ */
+export function resolveNeutralSurfaceState(
+  theme: FacetTheme,
+  state: 'rest' | 'hover' | 'pressed',
+): string {
+  const base = theme.color.background.surface;
+  if (state === 'rest') {
+    return base;
+  }
+  return mixColors(base, theme.color.text.primary, state === 'pressed' ? 0.07 : 0.04);
+}
+
+export function resolveInteractiveBadgeBackground(
+  theme: FacetTheme,
+  variant: 'neutral' | 'accent' | 'success' | 'danger',
+  pressed: boolean,
+  hovered: boolean,
+): string {
+  if (variant === 'neutral') {
+    return resolveNeutralSurfaceState(theme, pressed ? 'pressed' : hovered ? 'hover' : 'rest');
+  }
+
+  if (variant === 'accent') {
+    return pressed
+      ? theme.color.accent.pressed
+      : hovered
+        ? theme.color.accent.hover
+        : theme.color.accent.fill;
+  }
+
+  const base = variant === 'success' ? theme.color.status.success.fill : theme.color.status.danger.fill;
+  return pressed
+    ? mixColors(base, theme.color.text.primary, 0.18)
+    : hovered
+      ? mixColors(base, theme.color.text.primary, 0.1)
+      : base;
+}
+
+/**
+ * Button focus feedback needs to survive three rendering situations:
+ *
+ * 1. React DOM, where CSS `box-shadow` is the most expressive visual ring.
+ * 2. The custom reconciler web path, where Exact normalizes shadow fields into
+ *    canonical style/protocol data.
+ * 3. Native renderers, where border + shadow are available but CSS outline is
+ *    not.
+ *
+ * Using border + shadow here keeps the focused state visible everywhere instead
+ * of relying on `outline*`, which only React DOM understands.
+ */
+export function resolveButtonFocusStyle(
+  theme: FacetTheme,
+  focusVisible: boolean,
+  pressed: boolean,
+): Record<string, unknown> | null {
+  if (!focusVisible || pressed) {
+    return null;
+  }
+
+  // Accent border + a translucent halo one step wider: the Stripe-style ring.
+  // On web the halo is the boxShadow string; native renders the same intent
+  // as an accent-colored soft glow via the shadow fields.
+  const ringWidth = resolveCompactInset(theme) + 1;
+  const ring = theme.color.border.focus;
+  return {
+    borderColor: ring,
+    boxShadow: `0 0 0 ${ringWidth}px ${withAlpha(ring, 0.28)}`,
+    shadowColor: ring,
+    shadowOffset: { width: 0, height: 0 },
+    shadowRadius: theme.space.xs,
+    shadowOpacity: 0.28,
+  };
+}
+
+export function resolvePressTransform(
+  theme: FacetTheme,
+  pressed: boolean,
+): MotionTransform | undefined {
+  return buildMotionTransform(theme, [{ scale: pressed ? 0.98 : 1 }]);
+}
+
+export function resolveIndicatorMotionStyle(
+  theme: FacetTheme,
+  phase: PresencePhase,
+): Record<string, unknown> {
+  return resolvePresenceMotionStyle(phase, {
+    enterTransition: theme.motion.preset.popIn,
+    exitTransition: theme.motion.preset.popOut,
+    enteredStyle: {
+      opacity: 1,
+      transform: buildMotionTransform(theme, [{ scale: 1 }]),
+    },
+    enteringStyle: {
+      opacity: 0,
+      transform: buildMotionTransform(theme, [{ scale: 0.72 }]),
+    },
+  });
+}
+
+export function resolveToggleThumbStyle(
+  theme: FacetTheme,
+  checked: boolean,
+): Record<string, unknown> {
+  const offset = checked ? 18 : 0;
+  return {
+    marginLeft: theme.motion.reducedMotion ? offset : 0,
+    transform: buildMotionTransform(theme, [{ translateX: offset }]),
+    transition: theme.motion.preset.selection,
+    // iOS-style thumb: accent.onFill (white in both schemes) so it stays
+    // crisp on the unchecked neutral track and the checked accent track,
+    // separated from either by a soft drop shadow instead of a border.
+    backgroundColor: theme.color.accent.onFill,
+    ...applyShadow({
+      x: 0,
+      y: 1,
+      blur: 3,
+      color: theme.scheme === 'dark' ? '#000000' : '#101828',
+      opacity: theme.scheme === 'dark' ? 0.5 : 0.25,
+    }),
+  };
+}
+
+export function resolveFieldRingColor(
+  theme: FacetTheme,
+  validationState: FieldValidationState,
+): string {
+  if (validationState === 'error') {
+    return theme.color.status.danger.fill;
+  }
+  if (validationState === 'success') {
+    return theme.color.status.success.fill;
+  }
+  return theme.color.accent.fill;
+}
+
+export function resolveFieldLabelColor(
+  theme: FacetTheme,
+  options: {
+    validationState: FieldValidationState;
+    disabled: boolean;
+    focused: boolean;
+  },
+): string {
+  if (options.disabled) {
+    return theme.color.text.secondary;
+  }
+  if (options.validationState === 'error') {
+    return theme.color.status.danger.fill;
+  }
+  if (options.validationState === 'success') {
+    return theme.color.status.success.fill;
+  }
+  if (options.focused) {
+    return theme.color.accent.fill;
+  }
+  return theme.color.text.secondary;
+}
+
+export function resolveFieldChromeStyle(
+  theme: FacetTheme,
+  options: {
+    variant: FieldVariant;
+    validationState: FieldValidationState;
+    disabled: boolean;
+    focused: boolean;
+    hovered: boolean;
+  },
+): Record<string, unknown> {
+  const { variant, validationState, disabled, focused, hovered } = options;
+  // Hover strengthens the hairline without jumping all the way to a text
+  // color; focus hands the border to the accent (plus the halo overlay the
+  // field components render).
+  const hoverBorderColor = mixColors(theme.color.border.default, theme.color.text.primary, 0.22);
+  const interactiveBorderColor =
+    validationState === 'error'
+      ? theme.color.status.danger.fill
+      : validationState === 'success'
+        ? theme.color.status.success.fill
+        : focused
+          ? theme.color.border.focus
+          : hovered
+            ? hoverBorderColor
+            : theme.color.border.default;
+
+  // Default-variant fields sit on the raised card surface; filled fields use
+  // the recessed neutral surface.
+  const baseBackground =
+    variant === 'ghost'
+      ? 'transparent'
+      : variant === 'filled'
+        ? theme.color.background.surface
+        : theme.color.background.card;
+  // Default-variant fields keep their clean base fill in every state — the
+  // border and focus halo carry the feedback. Filled fields lighten on hover
+  // and settle back once focused; ghost fields tint like ghost buttons.
+  const hoveredBackground =
+    variant === 'ghost'
+      ? theme.color.overlay.hover
+      : variant === 'filled'
+        ? (focused ? theme.color.background.surface : resolveNeutralSurfaceState(theme, 'hover'))
+        : baseBackground;
+  const disabledBackground =
+    variant === 'ghost'
+      ? 'transparent'
+      : theme.color.background.surface;
+
+  return {
+    minHeight: theme.density.controlHeight.md,
+    flexDirection: 'row',
+    alignItems: variant === 'ghost' ? 'flex-end' : 'center',
+    width: '100%',
+    backgroundColor: disabled
+      ? disabledBackground
+      : hovered || focused
+        ? hoveredBackground
+        : baseBackground,
+    borderColor: variant === 'filled' && !focused && validationState === 'default'
+      ? 'transparent'
+      : interactiveBorderColor,
+    borderWidth: variant === 'ghost' ? 0 : 1,
+    borderBottomWidth: variant === 'ghost' ? 1 : undefined,
+    borderRadius: variant === 'ghost' ? 0 : theme.radius.container,
+    transition: theme.motion.preset.control,
+    opacity: disabled ? 0.5 : 1,
+    overflow: 'visible',
+  };
+}
+
+export function resolveFieldInputStyle(
+  theme: FacetTheme,
+  options: {
+    variant: FieldVariant;
+    loading: boolean;
+    multiline?: boolean;
+    rows?: number;
+    style?: Record<string, unknown>;
+  },
+): Record<string, unknown> {
+  // LLP 0269 §5 (D10): field paddings are density-scaled at apply time. The
+  // loading clearance stays unscaled — it reserves room for the spinner,
+  // whose size does not track the density dial.
+  const inlinePadding = resolveDensityPadding(theme, theme.space.md);
+  const blockPadding = resolveDensityPadding(theme, theme.space.sm);
+  const rightPadding = options.loading ? theme.space.xl + resolveInlineInset(theme) : inlinePadding;
+
+  return {
+    flex: 1,
+    minHeight: options.multiline
+      ? Math.max((options.rows ?? 4) * 24, 88)
+      : theme.density.controlHeight.md,
+    backgroundColor: 'transparent',
+    color: theme.color.text.primary,
+    fontFamily: theme.type.body.fontFamily,
+    fontSize: theme.type.body.fontSize,
+    lineHeight: theme.type.body.lineHeight,
+    borderWidth: 0,
+    borderRadius: 0,
+    paddingLeft: options.variant === 'ghost' ? 0 : inlinePadding,
+    paddingRight: options.variant === 'ghost' ? Math.max(rightPadding - inlinePadding, 0) : rightPadding,
+    paddingTop: blockPadding,
+    paddingBottom: blockPadding,
+    textAlignVertical: options.multiline ? 'top' : undefined,
+    ...(options.style ?? {}),
+  };
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+export type FacetRenderMode = 'native' | 'composed';
+
+export interface PlatformCapabilities {
+  platform: 'ios' | 'android' | 'web' | 'macos' | string;
+  supports(moduleName: string): boolean;
+}
+
+export interface NativeSliderChangeEvent {
+  nativeEvent?: {
+    value?: unknown;
+  };
+  value?: unknown;
+}
+
+export function getFacetPlatform(): PlatformCapabilities['platform'] {
+  const runtimeGlobals = globalThis as typeof globalThis & {
+    __exactPlatform?: string;
+    HermesInternal?: unknown;
+    process?: {
+      platform?: string;
+      versions?: Record<string, unknown>;
+    };
+  };
+
+  // Keep Facet's platform check local so the package does not need to reach
+  // into runtime-internal entry points just to choose native vs composed
+  // control leaves.
+  let platform = 'unknown';
+  if (typeof runtimeGlobals.__exactPlatform === 'string' && runtimeGlobals.__exactPlatform.length > 0) {
+    platform = runtimeGlobals.__exactPlatform;
+  } else if (typeof document !== 'undefined' && document.createElement) {
+    platform = 'web';
+  } else if (runtimeGlobals.process) {
+    const versions = runtimeGlobals.process.versions;
+    const isExactProcess =
+      !!versions &&
+      typeof versions === 'object' &&
+      (typeof versions.ibex === 'string' || typeof versions.exact === 'string');
+    if (!isExactProcess && typeof runtimeGlobals.process.platform === 'string') {
+      platform = runtimeGlobals.process.platform;
+    }
+  } else if (typeof runtimeGlobals.HermesInternal !== 'undefined') {
+    platform = 'ios';
+  }
+
+  if (platform === 'darwin' || platform === 'mac' || platform === 'macos') {
+    return 'macos';
+  }
+  return platform as PlatformCapabilities['platform'];
+}
+
+export function readModuleMetadata(moduleName: string): { moduleId: number } | null {
+  const exactRuntime = (
+    globalThis as typeof globalThis & {
+      exact?: {
+        getModuleMetadata?: (name: string) => { moduleId: number } | null;
+      };
+    }
+  ).exact;
+
+  if (typeof exactRuntime?.getModuleMetadata !== 'function') {
+    return null;
+  }
+
+  return exactRuntime.getModuleMetadata(moduleName);
+}
+
+export function createPlatformCapabilities(): PlatformCapabilities {
+  const platform = getFacetPlatform();
+
+  return {
+    platform,
+    supports(moduleName: string): boolean {
+      if (platform === 'web') {
+        return false;
+      }
+
+      const metadata = readModuleMetadata(moduleName);
+      return !!metadata && Number.isInteger(metadata.moduleId) && metadata.moduleId > 0;
+    },
+  };
+}
+
+export function resolveRenderMode(
+  componentName: string,
+  moduleName: string,
+  nativePreference: boolean | undefined,
+  platform: PlatformCapabilities,
+): FacetRenderMode {
+  if (nativePreference === false) {
+    return 'composed';
+  }
+
+  const supported = platform.supports(moduleName);
+  if (nativePreference === true && !supported) {
+    throw new Error(
+      `[Facet] ${componentName} native={true} requires ${moduleName} support on ${platform.platform}.`,
+    );
+  }
+
+  return supported ? 'native' : 'composed';
+}
+
+export function getSliderStep(min: number, max: number, requestedStep: number | undefined): number {
+  if (typeof requestedStep === 'number' && isFinite(requestedStep) && requestedStep > 0) {
+    return requestedStep;
+  }
+
+  const range = max - min;
+  if (range <= 0) {
+    return 1;
+  }
+
+  return Math.max(range / 20, 0.01);
+}
+
+export function snapSliderValue(value: number, min: number, max: number, step: number): number {
+  if (!isFinite(value)) {
+    return min;
+  }
+
+  const clamped = clamp(value, min, max);
+  if (!isFinite(step) || step <= 0) {
+    return clamped;
+  }
+
+  const snapped = min + Math.round((clamped - min) / step) * step;
+  return clamp(Number(snapped.toFixed(4)), min, max);
+}
+
+export function formatSliderValue(value: number): string {
+  return Number.isInteger(value) ? String(value) : value.toFixed(2).replace(/0+$/, '').replace(/\.$/, '');
+}
+
+export function extractNativeSliderValue(
+  event: NativeSliderChangeEvent,
+  fallbackValue: number,
+): number {
+  const candidate = event.nativeEvent?.value ?? event.value;
+  return typeof candidate === 'number' && isFinite(candidate)
+    ? candidate
+    : fallbackValue;
+}