@ccheever/exact-renderer 0.1.0

package/src/style/normalize.ts

@@ -0,0 +1,1426 @@
+/**
+ * Style Normalization
+ *
+ * This module converts user-provided style objects into the canonical
+ * internal format used by the protocol encoder.
+ *
+ * Design Principles:
+ * - Input validation and clamping for safety
+ * - Consistent handling of shorthand properties
+ * - Clear precedence rules (specific > general)
+ * - Web defaults with RN compatibility mode
+ */
+
+import type {
+  ViewStyle,
+  FullStyle,
+  CanonicalStyle,
+  TransitionConfig,
+  StyleTransition,
+  TransitionEasing,
+  TransitionEasingName,
+  CubicBezierEasing,
+  CanonicalTransitionConfig,
+  CanonicalTransitionMap,
+  CanonicalTransitionProperty,
+  DimensionValue,
+  DimensionInput,
+  FlexDirection,
+  Direction,
+  ResolvedDirection,
+  WritingMode,
+} from '../types.js';
+import { resolveFontFamilyId } from '@exact/core/assets-fonts-state';
+import { parseColor } from './color.js';
+
+const TIMING_DURATION_DEFAULT_MS = 250;
+const TIMING_DELAY_DEFAULT_MS = 0;
+const TIMING_EASING_DEFAULT: TransitionEasingName = 'easeInOut';
+
+const SPRING_DELAY_DEFAULT_MS = 0;
+const SPRING_DAMPING_DEFAULT = 16;
+const SPRING_STIFFNESS_DEFAULT = 220;
+const SPRING_MASS_DEFAULT = 1;
+const SPRING_VELOCITY_DEFAULT = 0;
+
+const FONT_VARIANT_NUMERIC_TABULAR_NUMS = 1 << 0;
+const FONT_VARIANT_NUMERIC_PROPORTIONAL_NUMS = 1 << 1;
+const FONT_VARIANT_NUMERIC_LINING_NUMS = 1 << 2;
+const FONT_VARIANT_NUMERIC_OLDSTYLE_NUMS = 1 << 3;
+const FONT_VARIANT_NUMERIC_SLASHED_ZERO = 1 << 4;
+
+const FONT_WEIGHT_MAP: Readonly<Record<string, number>> = {
+  normal: 400,
+  bold: 700,
+  '100': 100,
+  '200': 200,
+  '300': 300,
+  '400': 400,
+  '500': 500,
+  '600': 600,
+  '700': 700,
+  '800': 800,
+  '900': 900,
+};
+
+const TRANSITION_PROPERTY_ALIASES: Record<string, CanonicalTransitionProperty> = {
+  opacity: 'opacity',
+  transform: 'transform',
+  'background-color': 'backgroundColor',
+  backgroundcolor: 'backgroundColor',
+  backgroundColor: 'backgroundColor',
+  'border-radius': 'borderRadius',
+  borderradius: 'borderRadius',
+  borderRadius: 'borderRadius',
+};
+
+const TRANSITION_EASING_ALIASES: Record<string, TransitionEasingName> = {
+  linear: 'linear',
+  ease: 'easeInOut',
+  'ease-in': 'easeIn',
+  easeIn: 'easeIn',
+  'ease-out': 'easeOut',
+  easeOut: 'easeOut',
+  'ease-in-out': 'easeInOut',
+  easeInOut: 'easeInOut',
+};
+
+export interface NormalizeStyleOptions {
+  resolvedDirection?: ResolvedDirection;
+  resolvedWritingMode?: WritingMode;
+  includeInheritedValues?: boolean;
+}
+
+type CanonicalDimensionKey = Extract<keyof CanonicalStyle,
+  | 'width'
+  | 'height'
+  | 'minWidth'
+  | 'minHeight'
+  | 'maxWidth'
+  | 'maxHeight'
+  | 'paddingTop'
+  | 'paddingRight'
+  | 'paddingBottom'
+  | 'paddingLeft'
+  | 'marginTop'
+  | 'marginRight'
+  | 'marginBottom'
+  | 'marginLeft'
+  | 'flexBasis'
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'left'
+>;
+
+const BOX_DIMENSION_KEYS = [
+  'width',
+  'height',
+  'minWidth',
+  'minHeight',
+  'maxWidth',
+  'maxHeight',
+] as const satisfies readonly CanonicalDimensionKey[];
+
+const PADDING_KEYS = {
+  top: 'paddingTop',
+  right: 'paddingRight',
+  bottom: 'paddingBottom',
+  left: 'paddingLeft',
+} as const satisfies Record<PhysicalEdge, CanonicalDimensionKey>;
+
+const MARGIN_KEYS = {
+  top: 'marginTop',
+  right: 'marginRight',
+  bottom: 'marginBottom',
+  left: 'marginLeft',
+} as const satisfies Record<PhysicalEdge, CanonicalDimensionKey>;
+
+const INSET_KEYS = {
+  top: 'top',
+  right: 'right',
+  bottom: 'bottom',
+  left: 'left',
+} as const satisfies Record<PhysicalEdge, CanonicalDimensionKey>;
+
+const PADDING_EDGE_KEYS = [
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+] as const satisfies readonly CanonicalDimensionKey[];
+
+const MARGIN_EDGE_KEYS = [
+  'marginTop',
+  'marginRight',
+  'marginBottom',
+  'marginLeft',
+] as const satisfies readonly CanonicalDimensionKey[];
+
+const POSITION_TRAILING_EDGE_KEYS = [
+  'right',
+  'bottom',
+  'left',
+] as const satisfies readonly CanonicalDimensionKey[];
+
+type DirectStyleAssignment = readonly [keyof CanonicalStyle, keyof FullStyle];
+type NumberStyleKind = 'finite' | 'positive' | 'nonNegative' | 'unit' | 'floorPositive';
+type NumberStyleAssignment = readonly [keyof CanonicalStyle, keyof FullStyle, NumberStyleKind];
+
+const FLEX_DIRECT_ASSIGNMENTS: readonly DirectStyleAssignment[] = [
+  ['flexWrap', 'flexWrap'],
+  ['justifyContent', 'justifyContent'],
+  ['alignItems', 'alignItems'],
+  ['alignSelf', 'alignSelf'],
+];
+
+const FLEX_NUMBER_ASSIGNMENTS: readonly NumberStyleAssignment[] = [
+  ['flexGrow', 'flexGrow', 'finite'],
+  ['flexShrink', 'flexShrink', 'finite'],
+];
+
+const GAP_NUMBER_ASSIGNMENTS: readonly NumberStyleAssignment[] = [
+  ['rowGap', 'rowGap', 'finite'],
+  ['columnGap', 'columnGap', 'finite'],
+];
+
+const APPEARANCE_NUMBER_ASSIGNMENTS: readonly NumberStyleAssignment[] = [
+  ['opacity', 'opacity', 'unit'],
+  ['borderRadius', 'borderRadius', 'nonNegative'],
+  ['borderTopLeftRadius', 'borderTopLeftRadius', 'nonNegative'],
+  ['borderTopRightRadius', 'borderTopRightRadius', 'nonNegative'],
+  ['borderBottomLeftRadius', 'borderBottomLeftRadius', 'nonNegative'],
+  ['borderBottomRightRadius', 'borderBottomRightRadius', 'nonNegative'],
+  ['borderWidth', 'borderWidth', 'nonNegative'],
+  ['borderTopWidth', 'borderTopWidth', 'nonNegative'],
+  ['borderRightWidth', 'borderRightWidth', 'nonNegative'],
+  ['borderBottomWidth', 'borderBottomWidth', 'nonNegative'],
+  ['borderLeftWidth', 'borderLeftWidth', 'nonNegative'],
+  ['backdropBlur', 'backdropBlur', 'nonNegative'],
+  ['aspectRatio', 'aspectRatio', 'positive'],
+];
+
+const SHADOW_NUMBER_ASSIGNMENTS: readonly NumberStyleAssignment[] = [
+  ['shadowRadius', 'shadowRadius', 'nonNegative'],
+  ['shadowOpacity', 'shadowOpacity', 'unit'],
+];
+
+const TYPOGRAPHY_NUMBER_ASSIGNMENTS: readonly NumberStyleAssignment[] = [
+  ['fontSize', 'fontSize', 'positive'],
+  ['lineHeight', 'lineHeight', 'finite'],
+  ['letterSpacing', 'letterSpacing', 'finite'],
+  ['numberOfLines', 'numberOfLines', 'floorPositive'],
+];
+
+/**
+ * Parse a dimension input into a canonical dimension value.
+ *
+ * @param input - The dimension input (number, string, or explicit)
+ * @returns The canonical dimension value, or undefined if invalid
+ */
+export function parseDimension(input: DimensionInput | undefined): DimensionValue | undefined {
+  if (input === undefined || input === null) {
+    return undefined;
+  }
+
+  // Number is interpreted as points
+  if (typeof input === 'number') {
+    if (!isFinite(input)) {
+      return undefined;
+    }
+    return { type: 'points', value: input };
+  }
+
+  // String parsing
+  if (typeof input === 'string') {
+    const trimmed = input.trim();
+
+    if (trimmed === 'auto') {
+      return { type: 'auto' };
+    }
+
+    // Check for percentage
+    if (trimmed.endsWith('%')) {
+      const value = parseFloat(trimmed.slice(0, -1));
+      if (!isFinite(value)) {
+        return undefined;
+      }
+      return { type: 'percent', value };
+    }
+
+    // Check for px suffix
+    if (trimmed.endsWith('px')) {
+      const value = parseFloat(trimmed.slice(0, -2));
+      if (!isFinite(value)) {
+        return undefined;
+      }
+      return { type: 'points', value };
+    }
+
+    // Try parsing as a number
+    const value = parseFloat(trimmed);
+    if (!isFinite(value)) {
+      return undefined;
+    }
+    return { type: 'points', value };
+  }
+
+  // Already a dimension value object
+  if (typeof input === 'object' && 'type' in input) {
+    if (input.type === 'auto') {
+      return { type: 'auto' };
+    }
+    if ((input.type === 'points' || input.type === 'percent') && typeof input.value === 'number') {
+      if (!isFinite(input.value)) {
+        return undefined;
+      }
+      return input as DimensionValue;
+    }
+  }
+
+  return undefined;
+}
+
+function setDimension(
+  canonical: CanonicalStyle,
+  key: CanonicalDimensionKey,
+  input: DimensionInput | undefined,
+): void {
+  const value = parseDimension(input);
+  if (value) {
+    canonical[key] = value;
+  }
+}
+
+function setDimensionValue(
+  canonical: CanonicalStyle,
+  key: CanonicalDimensionKey,
+  value: DimensionValue,
+): void {
+  canonical[key] = value;
+}
+
+function setDimensionEdges(
+  canonical: CanonicalStyle,
+  keys: readonly CanonicalDimensionKey[],
+  value: DimensionValue,
+): void {
+  for (const key of keys) {
+    canonical[key] = value;
+  }
+}
+
+function normalizeNumberStyleValue(value: unknown, kind: NumberStyleKind): number | undefined {
+  if (typeof value !== 'number' || !isFinite(value)) {
+    return undefined;
+  }
+
+  switch (kind) {
+    case 'positive':
+      return value > 0 ? value : undefined;
+    case 'nonNegative':
+      return Math.max(0, value);
+    case 'unit':
+      return Math.max(0, Math.min(1, value));
+    case 'floorPositive':
+      return value > 0 ? Math.floor(value) : undefined;
+    case 'finite':
+    default:
+      return value;
+  }
+}
+
+function assignNumberStyles(
+  canonical: CanonicalStyle,
+  style: FullStyle,
+  assignments: readonly NumberStyleAssignment[],
+): void {
+  const target = canonical as Record<string, unknown>;
+  const source = style as Record<string, unknown>;
+  for (const [targetKey, sourceKey, kind] of assignments) {
+    const value = normalizeNumberStyleValue(source[sourceKey], kind);
+    if (value !== undefined) {
+      target[targetKey] = value;
+    }
+  }
+}
+
+function assignDefinedStyles(
+  canonical: CanonicalStyle,
+  style: FullStyle,
+  assignments: readonly DirectStyleAssignment[],
+): void {
+  const target = canonical as Record<string, unknown>;
+  const source = style as Record<string, unknown>;
+  for (const [targetKey, sourceKey] of assignments) {
+    const value = source[sourceKey];
+    if (value !== undefined) {
+      target[targetKey] = value;
+    }
+  }
+}
+
+function parseExplicitDirection(value: unknown): Direction | undefined {
+  return value === 'ltr' || value === 'rtl' || value === 'auto'
+    ? value
+    : undefined;
+}
+
+function parseWritingMode(value: unknown): WritingMode | undefined {
+  return value === 'horizontal-tb' || value === 'vertical-rl' || value === 'vertical-lr'
+    ? value
+    : undefined;
+}
+
+type PhysicalEdge = 'top' | 'right' | 'bottom' | 'left';
+
+function inlineStartEdge(
+  direction: ResolvedDirection,
+  writingMode: WritingMode,
+): PhysicalEdge {
+  switch (writingMode) {
+    case 'vertical-rl':
+    case 'vertical-lr':
+      return direction === 'rtl' ? 'bottom' : 'top';
+    case 'horizontal-tb':
+    default:
+      return direction === 'rtl' ? 'right' : 'left';
+  }
+}
+
+function inlineEndEdge(
+  direction: ResolvedDirection,
+  writingMode: WritingMode,
+): PhysicalEdge {
+  switch (writingMode) {
+    case 'vertical-rl':
+    case 'vertical-lr':
+      return direction === 'rtl' ? 'top' : 'bottom';
+    case 'horizontal-tb':
+    default:
+      return direction === 'rtl' ? 'left' : 'right';
+  }
+}
+
+function assignPaddingEdge(
+  canonical: CanonicalStyle,
+  edge: PhysicalEdge,
+  value: DimensionValue,
+): void {
+  setDimensionValue(canonical, PADDING_KEYS[edge], value);
+}
+
+function assignMarginEdge(
+  canonical: CanonicalStyle,
+  edge: PhysicalEdge,
+  value: DimensionValue,
+): void {
+  setDimensionValue(canonical, MARGIN_KEYS[edge], value);
+}
+
+function assignInsetEdge(
+  canonical: CanonicalStyle,
+  edge: PhysicalEdge,
+  value: DimensionValue,
+): void {
+  setDimensionValue(canonical, INSET_KEYS[edge], value);
+}
+
+/**
+ * Parse a font weight value to a numeric weight (100-900).
+ *
+ * @param weight - The font weight input
+ * @returns The numeric weight, or undefined if invalid
+ */
+export function parseFontWeight(weight: string | number | undefined): number | undefined {
+  if (weight === undefined || weight === null) {
+    return undefined;
+  }
+
+  // Already a number
+  if (typeof weight === 'number') {
+    if (weight >= 100 && weight <= 900) {
+      return weight;
+    }
+    return undefined;
+  }
+
+  return FONT_WEIGHT_MAP[weight];
+}
+
+/**
+ * Parse a CSS font-variant-numeric string into the protocol bitmask.
+ *
+ * Mutually exclusive categories use last-token-wins semantics to match CSS.
+ */
+export function parseFontVariantNumeric(value: string | undefined): number {
+  if (typeof value !== 'string') {
+    return 0;
+  }
+
+  let mask = 0;
+
+  for (const token of value.split(/\s+/)) {
+    switch (token) {
+      case 'tabular-nums':
+        mask = (mask & ~FONT_VARIANT_NUMERIC_PROPORTIONAL_NUMS) | FONT_VARIANT_NUMERIC_TABULAR_NUMS;
+        break;
+      case 'proportional-nums':
+        mask = (mask & ~FONT_VARIANT_NUMERIC_TABULAR_NUMS) | FONT_VARIANT_NUMERIC_PROPORTIONAL_NUMS;
+        break;
+      case 'lining-nums':
+        mask = (mask & ~FONT_VARIANT_NUMERIC_OLDSTYLE_NUMS) | FONT_VARIANT_NUMERIC_LINING_NUMS;
+        break;
+      case 'oldstyle-nums':
+        mask = (mask & ~FONT_VARIANT_NUMERIC_LINING_NUMS) | FONT_VARIANT_NUMERIC_OLDSTYLE_NUMS;
+        break;
+      case 'slashed-zero':
+        mask |= FONT_VARIANT_NUMERIC_SLASHED_ZERO;
+        break;
+      case 'normal':
+        mask = 0;
+        break;
+      default:
+        break;
+    }
+  }
+
+  return mask;
+}
+
+/**
+ * Extract transform values from the transform array.
+ *
+ * @param transform - The transform array from styles
+ * @returns Object with extracted transform values
+ */
+export function extractTransforms(
+  transform: ViewStyle['transform']
+): { x?: number; y?: number; scale?: number; rotate?: number } {
+  if (!transform || !Array.isArray(transform)) {
+    return {};
+  }
+
+  const result: { x?: number; y?: number; scale?: number; rotate?: number } = {};
+
+  for (const t of transform) {
+    if ('translateX' in t && typeof t.translateX === 'number') {
+      result.x = t.translateX;
+    } else if ('translateY' in t && typeof t.translateY === 'number') {
+      result.y = t.translateY;
+    } else if ('scale' in t && typeof t.scale === 'number') {
+      result.scale = t.scale;
+    } else if ('rotate' in t && typeof t.rotate === 'string') {
+      // Parse rotation - support deg and rad
+      const rotateStr = t.rotate.trim();
+      if (rotateStr.endsWith('deg')) {
+        const degrees = parseFloat(rotateStr.slice(0, -3));
+        if (isFinite(degrees)) {
+          result.rotate = (degrees * Math.PI) / 180;
+        }
+      } else if (rotateStr.endsWith('rad')) {
+        const radians = parseFloat(rotateStr.slice(0, -3));
+        if (isFinite(radians)) {
+          result.rotate = radians;
+        }
+      } else {
+        // Assume degrees if no unit
+        const degrees = parseFloat(rotateStr);
+        if (isFinite(degrees)) {
+          result.rotate = (degrees * Math.PI) / 180;
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+function parseLengthToken(token: string): number | undefined {
+  const trimmed = token.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+
+  if (trimmed.endsWith('px')) {
+    const value = parseFloat(trimmed.slice(0, -2));
+    return isFinite(value) ? value : undefined;
+  }
+
+  const value = parseFloat(trimmed);
+  return isFinite(value) ? value : undefined;
+}
+
+function splitTopLevelTokens(input: string, separator: 'comma' | 'space'): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let depth = 0;
+
+  for (const char of input.trim()) {
+    if (char === '(') {
+      depth += 1;
+      current += char;
+      continue;
+    }
+
+    if (char === ')') {
+      depth = Math.max(0, depth - 1);
+      current += char;
+      continue;
+    }
+
+    const shouldSplit =
+      depth === 0 &&
+      (separator === 'comma' ? char === ',' : /\s/.test(char));
+    if (shouldSplit) {
+      const token = current.trim();
+      if (token.length > 0) {
+        tokens.push(token);
+      }
+      current = '';
+      continue;
+    }
+
+    current += char;
+  }
+
+  const token = current.trim();
+  if (token.length > 0) {
+    tokens.push(token);
+  }
+
+  return tokens;
+}
+
+function firstBoxShadowLayer(input: string): string {
+  let depth = 0;
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index]!;
+    if (char === '(') {
+      depth += 1;
+      continue;
+    }
+    if (char === ')') {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (char === ',' && depth === 0) {
+      return input.slice(0, index).trim();
+    }
+  }
+
+  return input.trim();
+}
+
+function splitShadowColor(
+  color: ReturnType<typeof parseColor> | undefined,
+): { color?: ReturnType<typeof parseColor>; opacity?: number } {
+  if (!color) {
+    return {};
+  }
+
+  return {
+    color: { ...color, a: 255 },
+    opacity: color.a / 255,
+  };
+}
+
+function parseBoxShadow(value: string | undefined): {
+  offsetX: number;
+  offsetY: number;
+  radius: number;
+  color?: ReturnType<typeof parseColor>;
+  opacity?: number;
+} | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const layer = firstBoxShadowLayer(value);
+  if (layer.length === 0 || layer === 'none') {
+    return undefined;
+  }
+
+  const tokens = splitTopLevelTokens(layer, 'space').filter((token) => token !== 'inset');
+  if (tokens.length < 2) {
+    return undefined;
+  }
+
+  let colorTokenIndex = -1;
+  for (let index = tokens.length - 1; index >= 0; index -= 1) {
+    if (parseColor(tokens[index]!)) {
+      colorTokenIndex = index;
+      break;
+    }
+  }
+
+  const color =
+    colorTokenIndex >= 0 ? parseColor(tokens[colorTokenIndex]!) ?? undefined : undefined;
+  const lengthTokens = tokens.filter((_, index) => index !== colorTokenIndex);
+  const lengths = lengthTokens
+    .map((token) => parseLengthToken(token))
+    .filter((token): token is number => typeof token === 'number');
+
+  if (lengths.length < 2) {
+    return undefined;
+  }
+
+  const normalizedColor = splitShadowColor(color);
+  return {
+    offsetX: lengths[0]!,
+    offsetY: lengths[1]!,
+    radius: Math.max(0, lengths[2] ?? 0),
+    color: normalizedColor.color,
+    opacity: normalizedColor.opacity,
+  };
+}
+
+function normalizeTransitionPropertyName(input: string): CanonicalTransitionProperty | undefined {
+  return TRANSITION_PROPERTY_ALIASES[input.trim()];
+}
+
+function normalizePositiveMs(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(0, Math.round(value));
+}
+
+function normalizeSpringDuration(value: unknown): number | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  return normalizePositiveMs(value, 0);
+}
+
+function normalizeBoolean(value: unknown, fallback: boolean): boolean {
+  if (typeof value !== 'boolean') {
+    return fallback;
+  }
+  return value;
+}
+
+function normalizeCubicBezierEasing(value: unknown): CubicBezierEasing | undefined {
+  if (!Array.isArray(value) || value.length !== 4) {
+    return undefined;
+  }
+
+  const [x1, y1, x2, y2] = value;
+  if (
+    typeof x1 !== 'number' || !isFinite(x1) ||
+    typeof y1 !== 'number' || !isFinite(y1) ||
+    typeof x2 !== 'number' || !isFinite(x2) ||
+    typeof y2 !== 'number' || !isFinite(y2)
+  ) {
+    return undefined;
+  }
+
+  return [x1, y1, x2, y2];
+}
+
+function normalizeTransitionEasing(easing: TransitionEasing | undefined): TransitionEasing {
+  if (typeof easing === 'string') {
+    return TRANSITION_EASING_ALIASES[easing] ?? TIMING_EASING_DEFAULT;
+  }
+
+  const cubicBezier = normalizeCubicBezierEasing(easing);
+  return cubicBezier ?? TIMING_EASING_DEFAULT;
+}
+
+function normalizeTransitionConfig(config: TransitionConfig | undefined): CanonicalTransitionConfig | undefined {
+  if (!config || config.type === 'none') {
+    return undefined;
+  }
+
+  if (config.type === 'timing') {
+    return {
+      type: 'timing',
+      duration: normalizePositiveMs(config.duration, TIMING_DURATION_DEFAULT_MS),
+      delay: normalizePositiveMs(config.delay, TIMING_DELAY_DEFAULT_MS),
+      easing: normalizeTransitionEasing(config.easing),
+      respectsReducedMotion: normalizeBoolean(config.respectsReducedMotion, true),
+    };
+  }
+
+  return {
+    type: 'spring',
+    duration: normalizeSpringDuration(config.duration),
+    delay: normalizePositiveMs(config.delay, SPRING_DELAY_DEFAULT_MS),
+    damping: typeof config.damping === 'number' && isFinite(config.damping) ? config.damping : SPRING_DAMPING_DEFAULT,
+    stiffness: typeof config.stiffness === 'number' && isFinite(config.stiffness) ? config.stiffness : SPRING_STIFFNESS_DEFAULT,
+    mass: typeof config.mass === 'number' && isFinite(config.mass) ? config.mass : SPRING_MASS_DEFAULT,
+    velocity: typeof config.velocity === 'number' && isFinite(config.velocity) ? config.velocity : SPRING_VELOCITY_DEFAULT,
+    respectsReducedMotion: normalizeBoolean(config.respectsReducedMotion, true),
+  };
+}
+
+function parseTimeToken(token: string): number | undefined {
+  const trimmed = token.trim();
+
+  if (trimmed.endsWith('ms')) {
+    const value = parseFloat(trimmed.slice(0, -2));
+    return isFinite(value) ? Math.max(0, Math.round(value)) : undefined;
+  }
+
+  if (trimmed.endsWith('s')) {
+    const value = parseFloat(trimmed.slice(0, -1));
+    return isFinite(value) ? Math.max(0, Math.round(value * 1000)) : undefined;
+  }
+
+  return undefined;
+}
+
+function parseCubicBezierFunction(token: string): CubicBezierEasing | undefined {
+  const match = /^cubic-bezier\((.+)\)$/i.exec(token.trim());
+  if (!match) {
+    return undefined;
+  }
+
+  const values = match[1]
+    .split(',')
+    .map((value) => parseFloat(value.trim()));
+
+  return normalizeCubicBezierEasing(values);
+}
+
+type ParsedSpringConfig = {
+  damping?: number;
+  stiffness?: number;
+  mass?: number;
+  velocity?: number;
+};
+
+function parseSpringFunction(token: string): ParsedSpringConfig | undefined {
+  const match = /^spring\((.*)\)$/i.exec(token.trim());
+  if (!match) {
+    return undefined;
+  }
+
+  const params: Record<string, number> = {};
+  for (const entry of match[1].split(',')) {
+    const [rawKey, rawValue] = entry.split(':');
+    if (!rawKey || !rawValue) {
+      continue;
+    }
+    const key = rawKey.trim();
+    const value = parseFloat(rawValue.trim());
+    if (isFinite(value)) {
+      params[key] = value;
+    }
+  }
+
+  return {
+    damping: params.damping,
+    stiffness: params.stiffness,
+    mass: params.mass,
+    velocity: params.velocity,
+  };
+}
+
+function splitTransitionEntries(input: string): string[] {
+  return splitTopLevelTokens(input, 'comma');
+}
+
+function tokenizeTransitionEntry(entry: string): string[] {
+  return splitTopLevelTokens(entry, 'space');
+}
+
+function parseTransitionStringEntry(entry: string): [CanonicalTransitionProperty, CanonicalTransitionConfig] | undefined {
+  const tokens = tokenizeTransitionEntry(entry);
+  if (tokens.length < 2) {
+    return undefined;
+  }
+
+  const property = normalizeTransitionPropertyName(tokens[0]);
+  if (!property) {
+    return undefined;
+  }
+
+  const initialDuration = parseTimeToken(tokens[1]);
+  const initialSpring = parseSpringFunction(tokens[1]);
+  if (initialDuration === undefined && !initialSpring) {
+    return undefined;
+  }
+
+  let duration = initialDuration;
+  let delay = 0;
+  let easing: TransitionEasing = TIMING_EASING_DEFAULT;
+  let config: TransitionConfig = initialSpring
+    ? {
+        type: 'spring',
+        duration,
+        damping: initialSpring.damping,
+        stiffness: initialSpring.stiffness,
+        mass: initialSpring.mass,
+        velocity: initialSpring.velocity,
+      }
+    : {
+        type: 'timing',
+        duration: duration ?? TIMING_DURATION_DEFAULT_MS,
+        easing,
+      };
+
+  for (const token of tokens.slice(2)) {
+    const spring = parseSpringFunction(token);
+    if (spring) {
+      config = {
+        type: 'spring',
+        duration,
+        delay,
+        damping: typeof spring.damping === 'number' ? spring.damping : undefined,
+        stiffness: typeof spring.stiffness === 'number' ? spring.stiffness : undefined,
+        mass: typeof spring.mass === 'number' ? spring.mass : undefined,
+        velocity: typeof spring.velocity === 'number' ? spring.velocity : undefined,
+      };
+      continue;
+    }
+
+    const cubicBezier = parseCubicBezierFunction(token);
+    if (cubicBezier) {
+      easing = cubicBezier;
+      if (config.type === 'timing') {
+        config = { ...config, easing };
+      }
+      continue;
+    }
+
+    const time = parseTimeToken(token);
+    if (time !== undefined) {
+      if (duration === undefined) {
+        duration = time;
+        if (config.type === 'timing') {
+          config = { ...config, duration };
+        } else {
+          config = { ...config, duration };
+        }
+      } else {
+        delay = time;
+        config = { ...config, delay };
+      }
+      continue;
+    }
+
+    const easingName = TRANSITION_EASING_ALIASES[token];
+    if (easingName) {
+      easing = easingName;
+      if (config.type === 'timing') {
+        config = { ...config, easing };
+      }
+    }
+  }
+
+  const normalized = normalizeTransitionConfig(config);
+  return normalized ? [property, normalized] : undefined;
+}
+
+/**
+ * Normalize transition metadata from the style object.
+ *
+ * The normalized transition map intentionally lives outside CanonicalStyle so
+ * style diffing and protocol emission can treat transition metadata separately.
+ */
+export function normalizeTransition(transition: StyleTransition | undefined): CanonicalTransitionMap {
+  if (!transition) {
+    return {};
+  }
+
+  if (typeof transition === 'string') {
+    const trimmed = transition.trim();
+    if (trimmed.length === 0 || trimmed === 'none') {
+      return {};
+    }
+
+    const normalized: CanonicalTransitionMap = {};
+    for (const entry of splitTransitionEntries(trimmed)) {
+      const parsed = parseTransitionStringEntry(entry);
+      if (!parsed) {
+        continue;
+      }
+      const [property, config] = parsed;
+      normalized[property] = config;
+    }
+    return normalized;
+  }
+
+  const normalized: CanonicalTransitionMap = {};
+  for (const [propertyName, config] of Object.entries(transition)) {
+    const property = normalizeTransitionPropertyName(propertyName);
+    if (!property) {
+      continue;
+    }
+
+    const normalizedConfig = normalizeTransitionConfig(config);
+    if (normalizedConfig) {
+      normalized[property] = normalizedConfig;
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Compare two normalized transition maps.
+ */
+export function transitionsEqual(a: CanonicalTransitionMap, b: CanonicalTransitionMap): boolean {
+  if (a === b) {
+    return true;
+  }
+
+  const keysA = Object.keys(a) as CanonicalTransitionProperty[];
+  const keysB = Object.keys(b) as CanonicalTransitionProperty[];
+
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  for (const key of keysA) {
+    const valA = a[key];
+    const valB = b[key];
+
+    if (!valA || !valB || valA.type !== valB.type) {
+      return false;
+    }
+
+    if (valA.delay !== valB.delay || valA.respectsReducedMotion !== valB.respectsReducedMotion) {
+      return false;
+    }
+
+    if (valA.type === 'timing' && valB.type === 'timing') {
+      if (valA.duration !== valB.duration) {
+        return false;
+      }
+
+      const easingA = valA.easing;
+      const easingB = valB.easing;
+      if (typeof easingA === 'string' || typeof easingB === 'string') {
+        if (easingA !== easingB) {
+          return false;
+        }
+      } else if (
+        easingA[0] !== easingB[0] ||
+        easingA[1] !== easingB[1] ||
+        easingA[2] !== easingB[2] ||
+        easingA[3] !== easingB[3]
+      ) {
+        return false;
+      }
+      continue;
+    }
+
+    if (valA.type === 'spring' && valB.type === 'spring') {
+      if (
+        valA.duration !== valB.duration ||
+        valA.damping !== valB.damping ||
+        valA.stiffness !== valB.stiffness ||
+        valA.mass !== valB.mass ||
+        valA.velocity !== valB.velocity
+      ) {
+        return false;
+      }
+      continue;
+    }
+
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Normalize a style object into canonical internal format.
+ *
+ * @param style - The user-provided style object
+ * @param defaultFlexDirection - The default flex direction for this element type
+ * @returns The normalized canonical style
+ */
+export function normalizeStyle(
+  style: FullStyle | undefined,
+  defaultFlexDirection: FlexDirection = 'row',
+  options: NormalizeStyleOptions = {},
+): CanonicalStyle {
+  if (!style) {
+    return {};
+  }
+
+  const canonical: CanonicalStyle = {};
+  const styleRecord = style as Record<string, unknown>;
+  const explicitDirection = parseExplicitDirection(style.direction);
+  const resolvedDirection: ResolvedDirection =
+    explicitDirection === 'ltr' || explicitDirection === 'rtl'
+      ? explicitDirection
+      : options.resolvedDirection ?? 'ltr';
+  const explicitWritingMode = parseWritingMode(style.writingMode);
+  const resolvedWritingMode = explicitWritingMode ?? options.resolvedWritingMode ?? 'horizontal-tb';
+
+  if (options.includeInheritedValues === true || explicitDirection === 'ltr' || explicitDirection === 'rtl') {
+    canonical.direction = resolvedDirection;
+  }
+  if (options.includeInheritedValues === true || explicitWritingMode !== undefined) {
+    canonical.writingMode = resolvedWritingMode;
+  }
+
+  // ==========================================================================
+  // Dimensions
+  // ==========================================================================
+
+  for (const key of BOX_DIMENSION_KEYS) {
+    setDimension(canonical, key, style[key]);
+  }
+
+  // ==========================================================================
+  // Padding (shorthand first, then specific overrides)
+  // ==========================================================================
+
+  // Handle padding shorthand
+  const padding = parseDimension(style.padding);
+  if (padding) {
+    setDimensionEdges(canonical, PADDING_EDGE_KEYS, padding);
+  }
+
+  // Handle paddingVertical/paddingHorizontal
+  const paddingVertical = parseDimension(style.paddingVertical);
+  if (paddingVertical) {
+    setDimensionValue(canonical, PADDING_KEYS.top, paddingVertical);
+    setDimensionValue(canonical, PADDING_KEYS.bottom, paddingVertical);
+  }
+  const paddingHorizontal = parseDimension(style.paddingHorizontal);
+  if (paddingHorizontal) {
+    setDimensionValue(canonical, PADDING_KEYS.right, paddingHorizontal);
+    setDimensionValue(canonical, PADDING_KEYS.left, paddingHorizontal);
+  }
+
+  const paddingStart = parseDimension(
+    (style.paddingStart ?? style.paddingInlineStart ?? styleRecord['padding-inline-start']) as
+      | DimensionInput
+      | undefined,
+  );
+  if (paddingStart) {
+    assignPaddingEdge(canonical, inlineStartEdge(resolvedDirection, resolvedWritingMode), paddingStart);
+  }
+
+  const paddingEnd = parseDimension(
+    (style.paddingEnd ?? style.paddingInlineEnd ?? styleRecord['padding-inline-end']) as
+      | DimensionInput
+      | undefined,
+  );
+  if (paddingEnd) {
+    assignPaddingEdge(canonical, inlineEndEdge(resolvedDirection, resolvedWritingMode), paddingEnd);
+  }
+
+  // Handle specific padding (highest precedence)
+  for (const key of PADDING_EDGE_KEYS) {
+    setDimension(canonical, key, style[key]);
+  }
+
+  // ==========================================================================
+  // Margin (shorthand first, then specific overrides)
+  // ==========================================================================
+
+  // Handle margin shorthand
+  const margin = parseDimension(style.margin);
+  if (margin) {
+    setDimensionEdges(canonical, MARGIN_EDGE_KEYS, margin);
+  }
+
+  // Handle marginVertical/marginHorizontal
+  const marginVertical = parseDimension(style.marginVertical);
+  if (marginVertical) {
+    setDimensionValue(canonical, MARGIN_KEYS.top, marginVertical);
+    setDimensionValue(canonical, MARGIN_KEYS.bottom, marginVertical);
+  }
+  const marginHorizontal = parseDimension(style.marginHorizontal);
+  if (marginHorizontal) {
+    setDimensionValue(canonical, MARGIN_KEYS.right, marginHorizontal);
+    setDimensionValue(canonical, MARGIN_KEYS.left, marginHorizontal);
+  }
+
+  const marginStart = parseDimension(
+    (style.marginStart ?? style.marginInlineStart ?? styleRecord['margin-inline-start']) as
+      | DimensionInput
+      | undefined,
+  );
+  if (marginStart) {
+    assignMarginEdge(canonical, inlineStartEdge(resolvedDirection, resolvedWritingMode), marginStart);
+  }
+
+  const marginEnd = parseDimension(
+    (style.marginEnd ?? style.marginInlineEnd ?? styleRecord['margin-inline-end']) as
+      | DimensionInput
+      | undefined,
+  );
+  if (marginEnd) {
+    assignMarginEdge(canonical, inlineEndEdge(resolvedDirection, resolvedWritingMode), marginEnd);
+  }
+
+  // Handle specific margin (highest precedence)
+  for (const key of MARGIN_EDGE_KEYS) {
+    setDimension(canonical, key, style[key]);
+  }
+
+  // ==========================================================================
+  // Flexbox
+  // ==========================================================================
+
+  // Handle 'flex' shorthand
+  if (typeof style.flex === 'number' && isFinite(style.flex)) {
+    // CSS spec: flex: N means flexGrow: N, flexShrink: 1, flexBasis: 0
+    canonical.flexGrow = style.flex;
+    canonical.flexShrink = 1;
+    canonical.flexBasis = { type: 'points', value: 0 };
+  }
+
+  // Specific flex properties override shorthand
+  assignNumberStyles(canonical, style, FLEX_NUMBER_ASSIGNMENTS);
+
+  setDimension(canonical, 'flexBasis', style.flexBasis);
+
+  // Flex direction - apply default if not specified
+  if (style.flexDirection !== undefined) {
+    canonical.flexDirection = style.flexDirection;
+  } else if (defaultFlexDirection !== 'row') {
+    // Only include if non-web default
+    canonical.flexDirection = defaultFlexDirection;
+  }
+
+  assignDefinedStyles(canonical, style, FLEX_DIRECT_ASSIGNMENTS);
+
+  // Gap
+  if (typeof style.gap === 'number' && isFinite(style.gap)) {
+    canonical.rowGap = style.gap;
+    canonical.columnGap = style.gap;
+  }
+  assignNumberStyles(canonical, style, GAP_NUMBER_ASSIGNMENTS);
+
+  // ==========================================================================
+  // Position
+  // ==========================================================================
+
+  if (style.position !== undefined) {
+    canonical.positionType = style.position;
+  }
+
+  setDimension(canonical, 'top', style.top);
+
+  const start = parseDimension(
+    (style.start ?? style.insetInlineStart ?? styleRecord['inset-inline-start']) as
+      | DimensionInput
+      | undefined,
+  );
+  if (start) {
+    assignInsetEdge(canonical, inlineStartEdge(resolvedDirection, resolvedWritingMode), start);
+  }
+
+  const end = parseDimension(
+    (style.end ?? style.insetInlineEnd ?? styleRecord['inset-inline-end']) as
+      | DimensionInput
+      | undefined,
+  );
+  if (end) {
+    assignInsetEdge(canonical, inlineEndEdge(resolvedDirection, resolvedWritingMode), end);
+  }
+
+  for (const key of POSITION_TRAILING_EDGE_KEYS) {
+    setDimension(canonical, key, style[key]);
+  }
+
+  if (typeof style.zIndex === 'number' && isFinite(style.zIndex)) {
+    canonical.zIndex = style.zIndex;
+  }
+
+  // ==========================================================================
+  // Transform
+  // ==========================================================================
+
+  if (style.transform) {
+    const transforms = extractTransforms(style.transform);
+    if (transforms.x !== undefined) canonical.transformX = transforms.x;
+    if (transforms.y !== undefined) canonical.transformY = transforms.y;
+    if (transforms.scale !== undefined) canonical.transformScale = transforms.scale;
+    if (transforms.rotate !== undefined) canonical.transformRotate = transforms.rotate;
+  }
+
+  // ==========================================================================
+  // Appearance
+  // ==========================================================================
+
+  if (style.display === 'flex' || style.display === 'grid' || style.display === 'none') {
+    canonical.display = style.display;
+  }
+
+  if (style.backgroundColor) {
+    const color = parseColor(style.backgroundColor);
+    if (color) canonical.backgroundColor = color;
+  }
+
+  assignNumberStyles(canonical, style, APPEARANCE_NUMBER_ASSIGNMENTS);
+
+  if (style.borderColor) {
+    const color = parseColor(style.borderColor);
+    if (color) canonical.borderColor = color;
+  }
+  // Per-side border colors (ENG-22085).
+  if (style.borderTopColor) {
+    const color = parseColor(style.borderTopColor);
+    if (color) canonical.borderTopColor = color;
+  }
+  if (style.borderRightColor) {
+    const color = parseColor(style.borderRightColor);
+    if (color) canonical.borderRightColor = color;
+  }
+  if (style.borderBottomColor) {
+    const color = parseColor(style.borderBottomColor);
+    if (color) canonical.borderBottomColor = color;
+  }
+  if (style.borderLeftColor) {
+    const color = parseColor(style.borderLeftColor);
+    if (color) canonical.borderLeftColor = color;
+  }
+
+  if (style.boxShadow) {
+    const boxShadow = parseBoxShadow(style.boxShadow);
+    if (boxShadow?.color) {
+      canonical.shadowColor = boxShadow.color;
+    }
+    if (boxShadow?.opacity !== undefined) {
+      canonical.shadowOpacity = boxShadow.opacity;
+    }
+    if (boxShadow) {
+      canonical.shadowOffsetX = boxShadow.offsetX;
+      canonical.shadowOffsetY = boxShadow.offsetY;
+      canonical.shadowRadius = boxShadow.radius;
+    }
+  }
+
+  if (style.shadowColor) {
+    const normalizedShadow = splitShadowColor(parseColor(style.shadowColor));
+    if (normalizedShadow.color) {
+      canonical.shadowColor = normalizedShadow.color;
+    }
+    if (normalizedShadow.opacity !== undefined) {
+      canonical.shadowOpacity = normalizedShadow.opacity;
+    }
+  }
+
+  if (
+    typeof style.shadowOffset === 'object' &&
+    style.shadowOffset !== null &&
+    typeof style.shadowOffset.width === 'number' &&
+    isFinite(style.shadowOffset.width) &&
+    typeof style.shadowOffset.height === 'number' &&
+    isFinite(style.shadowOffset.height)
+  ) {
+    canonical.shadowOffsetX = style.shadowOffset.width;
+    canonical.shadowOffsetY = style.shadowOffset.height;
+  }
+
+  assignNumberStyles(canonical, style, SHADOW_NUMBER_ASSIGNMENTS);
+
+  if (style.overflow !== undefined) {
+    canonical.overflow = style.overflow;
+  }
+
+  // ==========================================================================
+  // Typography
+  // ==========================================================================
+
+  if (style.fontFamily !== undefined) {
+    const fontFamily = resolveFontFamilyId(style.fontFamily);
+    if (fontFamily !== undefined) {
+      canonical.fontFamily = fontFamily;
+    }
+  }
+
+  assignNumberStyles(canonical, style, TYPOGRAPHY_NUMBER_ASSIGNMENTS);
+
+  if (style.color) {
+    const color = parseColor(style.color);
+    if (color) canonical.textColor = color;
+  }
+
+  const fontWeight = parseFontWeight(style.fontWeight);
+  if (fontWeight !== undefined) canonical.fontWeight = fontWeight;
+
+  if (style.fontStyle === 'normal' || style.fontStyle === 'italic') {
+    canonical.fontStyle = style.fontStyle;
+  }
+
+  if (typeof style.fontVariantNumeric === 'string') {
+    const fontVariantNumeric = parseFontVariantNumeric(style.fontVariantNumeric);
+    if (fontVariantNumeric !== 0) {
+      canonical.fontVariantNumeric = fontVariantNumeric;
+    }
+  }
+
+  if (style.textAlign !== undefined) {
+    canonical.textAlign = style.textAlign;
+  }
+
+  if (
+    style.textDecorationLine === 'none' ||
+    style.textDecorationLine === 'underline' ||
+    style.textDecorationLine === 'line-through' ||
+    style.textDecorationLine === 'underline line-through'
+  ) {
+    canonical.textDecorationLine = style.textDecorationLine;
+  }
+
+  if (style.ellipsizeMode !== undefined) {
+    canonical.ellipsizeMode = style.ellipsizeMode;
+  }
+
+  return canonical;
+}
+
+/**
+ * Compare two canonical styles and return true if they are equal.
+ *
+ * @param a - First style
+ * @param b - Second style
+ * @returns True if styles are equal
+ */
+export function stylesEqual(a: CanonicalStyle, b: CanonicalStyle): boolean {
+  // Quick reference check
+  if (a === b) return true;
+
+  // Compare all keys
+  const keysA = Object.keys(a) as (keyof CanonicalStyle)[];
+  const keysB = Object.keys(b) as (keyof CanonicalStyle)[];
+
+  if (keysA.length !== keysB.length) return false;
+
+  for (const key of keysA) {
+    const valA = a[key];
+    const valB = b[key];
+
+    if (valA === valB) continue;
+
+    // Deep compare for objects
+    if (typeof valA === 'object' && typeof valB === 'object' && valA !== null && valB !== null) {
+      // Compare dimension values
+      if ('type' in valA && 'type' in valB) {
+        if (valA.type !== valB.type) return false;
+        if ('value' in valA && 'value' in valB) {
+          if (valA.value !== valB.value) return false;
+        }
+        continue;
+      }
+      // Compare RGBA colors
+      if ('r' in valA && 'r' in valB) {
+        if (
+          valA.r !== valB.r ||
+          valA.g !== valB.g ||
+          valA.b !== valB.b ||
+          valA.a !== valB.a
+        ) {
+          return false;
+        }
+        continue;
+      }
+    }
+
+    return false;
+  }
+
+  return true;
+}