@ccheever/exact-renderer 0.1.0

package/src/props/normalize.ts

@@ -0,0 +1,816 @@
+/**
+ * Prop Normalization
+ *
+ * This module converts user-provided props into the canonical
+ * internal format used by the protocol encoder.
+ *
+ * Design Principles:
+ * - Web props are processed with web semantics (src, alt, etc.)
+ * - RN props are processed with RN semantics (source, resizeMode)
+ * - Clear prop extraction for different element types
+ */
+
+import type {
+  AccessibilityActionDescriptor,
+  CanonicalProps,
+  CanonicalTagType,
+  ColorSchemeImageSource,
+  ImagePlaceholder,
+  ResizeMode,
+  ImageSource,
+  SelectableMode,
+  SvgSource,
+} from '../types.js';
+import { isAssetRef } from '@exact/core/assets-fonts-state';
+import { lowerTextPropsToParagraphSpec } from '../text/paragraph-lowering.js';
+import {
+  resolveImagePlaceholderForNative,
+  resolveImageSourceForNative,
+  warnIfImageMissingAlt,
+} from '../image-source.js';
+import { resolveSvgSourceForNative } from '../svg-source.js';
+
+/**
+ * Extract text content from children.
+ * Handles both string children and nested text.
+ *
+ * @param children - The children prop
+ * @returns The text content string, or undefined if not text
+ */
+export function extractTextContent(children: unknown): string | undefined {
+  if (children === null || children === undefined) {
+    return undefined;
+  }
+
+  if (typeof children === 'string') {
+    return children;
+  }
+
+  if (typeof children === 'number') {
+    return String(children);
+  }
+
+  if (typeof children === 'boolean') {
+    // React ignores booleans
+    return undefined;
+  }
+
+  // Array of children - concatenate text
+  if (Array.isArray(children)) {
+    const parts: string[] = [];
+    for (const child of children) {
+      const text = extractTextContent(child);
+      if (text !== undefined) {
+        parts.push(text);
+      }
+    }
+    return parts.length > 0 ? parts.join('') : undefined;
+  }
+
+  if (typeof children === 'object' && children !== null && 'props' in children) {
+    const props = (children as { props?: unknown }).props;
+    if (typeof props === 'object' && props !== null && 'children' in props) {
+      return extractTextContent((props as { children?: unknown }).children);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract image source from web-style props.
+ *
+ * @param props - The props object
+ * @returns The image source URL, or undefined
+ */
+export function extractWebImageSource(props: Record<string, unknown>): string | undefined {
+  const themed = imageSourceFromThemeProps(props);
+  if (themed) {
+    return resolveImageSourceForNative(themed);
+  }
+
+  const src = props.src;
+  if (typeof src === 'string' && src.length > 0) {
+    return src;
+  }
+  if (typeof src === 'object' && src !== null) {
+    return resolveImageSourceForNative(src as ImageSource);
+  }
+  return undefined;
+}
+
+/**
+ * Extract image source from RN-style props.
+ *
+ * @param props - The props object
+ * @returns The image source URL, or undefined
+ */
+export function extractRNImageSource(props: Record<string, unknown>): string | undefined {
+  const themed = imageSourceFromThemeProps(props);
+  if (themed) {
+    return resolveImageSourceForNative(themed);
+  }
+
+  const source = props.source as ImageSource | undefined;
+  if (!source) {
+    return undefined;
+  }
+
+  return resolveImageSourceForNative(source);
+}
+
+function imageSourceFromThemeProps(props: Record<string, unknown>): ColorSchemeImageSource | undefined {
+  const light = typeof props.lightSrc === 'string' && props.lightSrc.length > 0
+    ? props.lightSrc
+    : undefined;
+  const dark = typeof props.darkSrc === 'string' && props.darkSrc.length > 0
+    ? props.darkSrc
+    : undefined;
+  if (!light && !dark) {
+    return undefined;
+  }
+
+  return {
+    ...(light ? { light } : {}),
+    ...(dark ? { dark } : {}),
+    ...(typeof props.src === 'string' && props.src.length > 0 ? { fallback: props.src } : {}),
+  };
+}
+
+function extractSvgSource(props: Record<string, unknown>): string | undefined {
+  const source = props.source as SvgSource | undefined;
+  if (!source) {
+    return undefined;
+  }
+
+  if (typeof source === 'string' && source.length > 0) {
+    return source;
+  }
+
+  if (isAssetRef(source)) {
+    return source.url;
+  }
+
+  if (typeof source === 'object' && source !== null && typeof source.uri === 'string' && source.uri.length > 0) {
+    return source.uri;
+  }
+
+  return undefined;
+}
+
+function extractSelectableMode(value: unknown): SelectableMode | undefined {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  if (value === 'contain' || value === 'all') {
+    return value;
+  }
+
+  return undefined;
+}
+
+function readBooleanProp(
+  props: Record<string, unknown>,
+  key: string
+): boolean | undefined {
+  return typeof props[key] === 'boolean' ? props[key] as boolean : undefined;
+}
+
+/**
+ * Compose the Liquid Glass inputs (`glassEffect`, `glass`, `glassVariant`,
+ * `glassTint`, `glassInteractive`) into the single `glassEffect` spec string
+ * the protocol carries. Returns `undefined` when no glass input is present at
+ * all (the caller keeps any boolean glassEffect the toggle path set, so the
+ * legacy truthy `"true"` value survives for native controls) and the explicit
+ * `"false"` spec for an explicit off — see the removal note in the body.
+ *
+ * Spec grammar: `<variant>` (`true` | `regular` | `clear`) optionally followed
+ * by `;tint=<color>` and/or `;interactive`. Examples: `"regular"`, `"clear"`,
+ * `"regular;tint=#7c4dffaa"`, `"clear;tint=#ff8800;interactive"`.
+ */
+function composeGlassSpec(
+  props: Record<string, unknown>,
+  existing: CanonicalProps['glassEffect'],
+): string | boolean | undefined {
+  // `glass` is the Contract alias for `glassEffect`; accept either, and accept a
+  // string value (`glass="clear"`) as both enable + variant.
+  const enableRaw = props.glassEffect ?? props.glass;
+  // An explicit off wins even when a variant/tint is present, so a single
+  // `glass={flag}` toggle can switch a fully-specified surface on and off.
+  // Emit the explicit "false" spec rather than dropping the prop: the
+  // protocol's prop encoding has no removal op, so an omitted `glassEffect`
+  // leaves a previously glassy node's stale spec live on the native side and
+  // the material never tears down (ENG-22484 iOS visual pass). Both native
+  // parsers (`applyGlassSpec`) and the web fallback read "false" as off.
+  if (enableRaw === false || enableRaw === 'false') {
+    return 'false';
+  }
+  const variantInput =
+    readStringProp(props, 'glassVariant') ??
+    (typeof enableRaw === 'string' ? enableRaw : undefined);
+  const tint = readStringProp(props, 'glassTint');
+  const interactive = readBooleanProp(props, 'glassInteractive') === true;
+  const enabled =
+    enableRaw === true ||
+    typeof enableRaw === 'string' ||
+    variantInput !== undefined ||
+    tint !== undefined ||
+    interactive ||
+    existing === true ||
+    (typeof existing === 'string' && existing.length > 0 && existing !== 'false');
+  if (!enabled) {
+    return undefined;
+  }
+  const hasRefinement =
+    variantInput !== undefined || tint !== undefined || interactive;
+  if (!hasRefinement) {
+    // Bare enable: keep glassEffect a plain boolean. The encoder stringifies it
+    // to "true" (which the native toggle's `is_truthy` check matches and the
+    // container glass parser reads as the regular variant), so nothing is lost
+    // and the toggle path's boolean contract is preserved.
+    return true;
+  }
+  const variant = variantInput === 'clear' ? 'clear' : 'regular';
+  const parts = [variant];
+  if (tint !== undefined) {
+    parts.push(`tint=${tint}`);
+  }
+  if (interactive) {
+    parts.push('interactive');
+  }
+  return parts.join(';');
+}
+
+function readStringProp(
+  props: Record<string, unknown>,
+  key: string
+): string | undefined {
+  return typeof props[key] === 'string' && (props[key] as string).length > 0
+    ? props[key] as string
+    : undefined;
+}
+
+function readNumberProp(
+  props: Record<string, unknown>,
+  key: string
+): number | undefined {
+  return typeof props[key] === 'number' && isFinite(props[key] as number)
+    ? props[key] as number
+    : undefined;
+}
+
+type PropAliasKind = 'string' | 'rawString' | 'boolean' | 'number' | 'truncNumber';
+type PropAliasEncoding = readonly [keyof CanonicalProps, PropAliasKind, ...string[]];
+
+const TEST_ID_PROP_ALIASES: readonly PropAliasEncoding[] = [
+  ['testId', 'string', 'testId', 'testID', 'data-testid', 'data-test-id'],
+];
+
+const COMMON_PROP_ALIASES: readonly PropAliasEncoding[] = [
+  ['inert', 'boolean', 'inert'],
+  ['scrollLocked', 'boolean', 'scrollLocked'],
+  ['portalTarget', 'string', 'portalTarget'],
+  ['accessibilityRole', 'string', 'accessibilityRole', 'role'],
+  ['accessibilityHint', 'string', 'accessibilityHint', 'aria-description'],
+  ['accessibilityModal', 'boolean', 'accessibilityModal', 'aria-modal'],
+  ['accessibilityExpanded', 'boolean', 'accessibilityExpanded', 'aria-expanded'],
+  ['accessibilitySelected', 'boolean', 'accessibilitySelected', 'aria-selected'],
+  ['accessibilityDisabled', 'boolean', 'accessibilityDisabled', 'aria-disabled'],
+  ['accessibilityLive', 'string', 'accessibilityLive', 'aria-live'],
+  ['accessibilityValueNow', 'number', 'accessibilityValueNow', 'aria-valuenow'],
+  ['accessibilityValueMin', 'number', 'accessibilityValueMin', 'aria-valuemin'],
+  ['accessibilityValueMax', 'number', 'accessibilityValueMax', 'aria-valuemax'],
+  ['accessibilityValueText', 'string', 'accessibilityValueText', 'aria-valuetext'],
+  ['nativeID', 'string', 'nativeID', 'id'],
+  ['href', 'string', 'href'],
+  ['accessibilityLabelledBy', 'string', 'accessibilityLabelledBy', 'aria-labelledby'],
+  ['accessibilityDescribedBy', 'string', 'accessibilityDescribedBy', 'aria-describedby'],
+  ['accessibilityBusy', 'boolean', 'accessibilityBusy', 'aria-busy'],
+  ['accessibilityElementsHidden', 'boolean', 'accessibilityElementsHidden', 'aria-hidden'],
+  ['accessibilityHeadingLevel', 'truncNumber', 'accessibilityHeadingLevel', 'aria-level'],
+  ['accessibilitySynthetic', 'boolean', 'accessibilitySynthetic'],
+  ['allowFontScaling', 'boolean', 'allowFontScaling'],
+  ['maxFontSizeMultiplier', 'number', 'maxFontSizeMultiplier'],
+  ['minimumFontSize', 'number', 'minimumFontSize'],
+  ['__exactPresencePhase', 'string', '__exactPresencePhase'],
+  ['__exactPortalLevel', 'string', '__exactPortalLevel'],
+  ['__exactPortalPresentation', 'string', '__exactPortalPresentation'],
+  ['__exactDismissableLayer', 'boolean', '__exactDismissableLayer'],
+  ['__exactDismissAction', 'string', '__exactDismissAction'],
+  ['__exactFocusRestore', 'boolean', '__exactFocusRestore'],
+  ['__exactAnchorTarget', 'string', '__exactAnchorTarget'],
+  ['__exactAnchorPlacement', 'string', '__exactAnchorPlacement'],
+  ['__exactAnchorStrategy', 'string', '__exactAnchorStrategy'],
+  ['__exactAnchorOffset', 'number', '__exactAnchorOffset'],
+  ['__exactComponentName', 'string', '__exactComponentName'],
+  ['__exactComponentSlot', 'string', '__exactComponentSlot'],
+  ['__exactSourceFilePath', 'string', '__exactSourceFilePath'],
+  ['__exactVariantProps', 'string', '__exactVariantProps'],
+  ['__exactInteractionState', 'string', '__exactInteractionState'],
+  ['__exactRenderMode', 'string', '__exactRenderMode'],
+  ['disabled', 'boolean', 'disabled'],
+  ['disabledReason', 'rawString', 'disabledReason'],
+  ['agentSummary', 'rawString', 'agentSummary'],
+];
+
+const AGENT_ID_PROP_ALIASES: readonly PropAliasEncoding[] = [
+  ['agentId', 'rawString', 'agentId'],
+];
+
+function readAliasProp(
+  props: Record<string, unknown>,
+  encoding: PropAliasEncoding,
+): unknown {
+  const kind = encoding[1];
+  for (let index = 2; index < encoding.length; index += 1) {
+    const key = encoding[index] as string;
+    const value =
+      kind === 'string'
+        ? readStringProp(props, key)
+        : kind === 'rawString'
+          ? (typeof props[key] === 'string' ? props[key] as string : undefined)
+          : kind === 'boolean'
+            ? readBooleanProp(props, key)
+            : readNumberProp(props, key);
+
+    if (value !== undefined) {
+      return kind === 'truncNumber' ? Math.trunc(value as number) : value;
+    }
+  }
+  return undefined;
+}
+
+function assignPropAliases(
+  canonical: CanonicalProps,
+  props: Record<string, unknown>,
+  encodings: readonly PropAliasEncoding[],
+): void {
+  const target = canonical as Record<string, unknown>;
+  for (const encoding of encodings) {
+    const value = readAliasProp(props, encoding);
+    if (value !== undefined) {
+      target[encoding[0]] = value;
+    }
+  }
+}
+
+function normalizeAccessibilityActions(
+  value: unknown,
+): string | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const actions = value
+    .filter((candidate): candidate is AccessibilityActionDescriptor => (
+      typeof candidate === 'object' &&
+      candidate !== null &&
+      typeof (candidate as AccessibilityActionDescriptor).name === 'string'
+    ))
+    .map((candidate) => ({
+      name: candidate.name.trim(),
+      label:
+        typeof candidate.label === 'string' && candidate.label.trim().length > 0
+          ? candidate.label.trim()
+          : undefined,
+    }))
+    .filter((candidate) => candidate.name.length > 0);
+
+  if (actions.length === 0) {
+    return undefined;
+  }
+
+  return JSON.stringify(actions);
+}
+
+function normalizeAccessibilityOrder(
+  value: unknown,
+): string | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const order = value
+    .map((candidate) => {
+      if (typeof candidate === 'string') {
+        return candidate.trim();
+      }
+      if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+        return String(candidate);
+      }
+      return '';
+    })
+    .filter((candidate) => candidate.length > 0);
+
+  if (order.length === 0) {
+    return undefined;
+  }
+
+  return JSON.stringify(order);
+}
+
+/**
+ * Map web objectFit to RN-style resizeMode.
+ */
+function mapObjectFitToResizeMode(
+  objectFit: string | undefined
+): ResizeMode | undefined {
+  switch (objectFit) {
+    case 'cover':
+    case 'contain':
+      return objectFit;
+    case 'fill':
+      return 'stretch';
+    case 'none':
+      return 'center';
+    case 'scale-down':
+      return 'contain';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Extract resize mode from props.
+ *
+ * @param props - The props object
+ * @param isRNStyle - Whether to use RN prop names
+ * @returns The resize mode, or undefined
+ */
+export function extractResizeMode(
+  props: Record<string, unknown>,
+  isRNStyle: boolean
+): ResizeMode | undefined {
+  if (isRNStyle) {
+    const resizeMode = props.resizeMode;
+    if (
+      resizeMode === 'cover' ||
+      resizeMode === 'contain' ||
+      resizeMode === 'stretch' ||
+      resizeMode === 'center'
+    ) {
+      return resizeMode;
+    }
+  }
+
+  const objectFit = props.objectFit;
+  return typeof objectFit === 'string'
+    ? mapObjectFitToResizeMode(objectFit)
+    : undefined;
+}
+
+/**
+ * Normalize props for an element into canonical format.
+ *
+ * @param tagType - The canonical tag type
+ * @param props - The user-provided props
+ * @param isRNStyle - Whether to use RN prop names
+ * @returns The normalized canonical props
+ */
+export function normalizeProps(
+  tagType: CanonicalTagType,
+  props: Record<string, unknown>,
+  isRNStyle: boolean
+): CanonicalProps {
+  const canonical: CanonicalProps = {};
+
+  switch (tagType) {
+    case 'text': {
+      const paragraph = lowerTextPropsToParagraphSpec(props);
+      if (paragraph !== null) {
+        canonical.textContent = paragraph.plainText;
+      } else if (typeof props.textContent === 'string') {
+        canonical.textContent = props.textContent;
+      }
+      break;
+    }
+
+    case 'image': {
+      warnIfImageMissingAlt({
+        alt: typeof props.alt === 'string' ? props.alt : undefined,
+        decorative: props.decorative === true,
+        source: (imageSourceFromThemeProps(props) ?? (isRNStyle ? props.source : props.src)) as ImageSource | undefined,
+        testID: typeof props.testID === 'string' ? props.testID : undefined,
+      });
+
+      // Extract image source
+      if (isRNStyle) {
+        const source = extractRNImageSource(props);
+        if (source) {
+          canonical.imageSource = source;
+        }
+      } else {
+        const source = extractWebImageSource(props);
+        if (source) {
+          canonical.imageSource = source;
+        }
+      }
+
+      // Inline-SVG glyphs (Contract `image svgSource=...`, the dom-mirror's
+      // `svgSource` host prop) carry their artwork as markup rather than a
+      // `src`. The DOM mirror inlines that markup into a live `<svg>`; native
+      // cannot, so resolve it to a `data:image/svg+xml` URI the image pipeline
+      // loads, and forward `tintColor` as the glyph color (read for image
+      // nodes by the AppKit/UIKit presenters). A raster `src`, if present,
+      // wins.
+      if (canonical.imageSource === undefined && props.svgSource !== undefined) {
+        const svgImageSource = resolveSvgSourceForNative(props.svgSource as SvgSource);
+        if (svgImageSource !== undefined) {
+          canonical.imageSource = svgImageSource;
+          if (typeof props.tintColor === 'string') {
+            canonical.tintColor = props.tintColor;
+          }
+        }
+      }
+
+      // Extract resize mode
+      const resizeMode = extractResizeMode(props, isRNStyle);
+      if (resizeMode) {
+        canonical.resizeMode = resizeMode;
+      }
+
+      const placeholder = resolveImagePlaceholderForNative(
+        props.placeholder as ImagePlaceholder | undefined,
+      );
+      if (placeholder) {
+        canonical.placeholder = placeholder;
+      }
+      break;
+    }
+
+    case 'svg': {
+      warnIfImageMissingAlt({
+        alt: typeof props.alt === 'string' ? props.alt : undefined,
+        decorative: props.decorative === true,
+        source: props.source as ImageSource | undefined,
+        testID: typeof props.testID === 'string' ? props.testID : undefined,
+      });
+
+      const source = extractSvgSource(props);
+      if (source) {
+        canonical.svgSource = source;
+      }
+
+      const resizeMode = extractResizeMode(props, true);
+      if (resizeMode) {
+        canonical.resizeMode = resizeMode;
+      }
+
+      if (typeof props.tintColor === 'string') {
+        canonical.tintColor = props.tintColor;
+      }
+
+      if (typeof props.objectPosition === 'string' && props.objectPosition.trim().length > 0) {
+        canonical.svgObjectPosition = props.objectPosition.trim();
+      }
+
+      if (typeof props.pixelDensity === 'number' && isFinite(props.pixelDensity) && props.pixelDensity > 0) {
+        canonical.svgPixelDensity = String(props.pixelDensity);
+      }
+
+      if (typeof props.colors === 'object' && props.colors !== null) {
+        const colorEntries = Object.entries(props.colors as Record<string, unknown>)
+          .filter(([key, value]) => key.startsWith('--') && typeof value === 'string');
+        if (colorEntries.length > 0) {
+          canonical.svgColors = JSON.stringify(Object.fromEntries(colorEntries));
+        }
+      }
+      break;
+    }
+
+    case 'video': {
+      if (typeof props.videoPlayerId === 'string' && props.videoPlayerId.length > 0) {
+        canonical.videoPlayerId = props.videoPlayerId;
+      }
+
+      if (typeof props.videoViewConfig === 'string' && props.videoViewConfig.length > 0) {
+        canonical.videoViewConfig = props.videoViewConfig;
+      }
+      break;
+    }
+
+    case 'input': {
+      // Text input props
+      if (typeof props.value === 'string') {
+        canonical.value = props.value;
+      } else if (typeof props.defaultValue === 'string') {
+        canonical.value = props.defaultValue;
+      }
+
+      if (typeof props.placeholder === 'string') {
+        canonical.placeholder = props.placeholder;
+      }
+
+      if (typeof props.editable === 'boolean') {
+        canonical.editable = props.editable;
+      }
+
+      if (typeof props.multiline === 'boolean') {
+        canonical.multiline = props.multiline;
+      }
+
+      if (typeof props.maxLength === 'number' && props.maxLength > 0) {
+        canonical.maxLength = props.maxLength;
+      }
+
+      if (typeof props.secureTextEntry === 'boolean') {
+        canonical.secureTextEntry = props.secureTextEntry;
+      }
+      break;
+    }
+
+    case 'scroll':
+    case 'list': {
+      // Scroll container props
+      if (typeof props.horizontal === 'boolean') {
+        canonical.horizontal = props.horizontal;
+      }
+
+      // Combine indicator visibility
+      const showsV = props.showsVerticalScrollIndicator;
+      const showsH = props.showsHorizontalScrollIndicator;
+      if (typeof showsV === 'boolean' || typeof showsH === 'boolean') {
+        canonical.showsScrollIndicator = showsV !== false && showsH !== false;
+      }
+      break;
+    }
+
+    case 'view':
+    case 'nativeView':
+    case 'pressable':
+      // View and pressable don't have special props
+      break;
+
+    case 'toggle': {
+      // Toggle/switch props
+      if (typeof props.value === 'boolean') {
+        canonical.toggleValue = props.value;
+      } else if (typeof props.defaultValue === 'boolean') {
+        canonical.toggleValue = props.defaultValue;
+      }
+
+      if (typeof props.glassEffect === 'boolean') {
+        canonical.glassEffect = props.glassEffect;
+      }
+
+      if (typeof props.tintColor === 'string') {
+        canonical.tintColor = props.tintColor;
+      }
+
+      if (typeof props.disabled === 'boolean') {
+        canonical.disabled = props.disabled;
+      }
+
+      // Extract label from children or label prop
+      const label = typeof props.label === 'string'
+        ? props.label
+        : extractTextContent(props.children);
+      if (label !== undefined) {
+        canonical.textContent = label;
+      }
+      break;
+    }
+  }
+
+  const selectable = extractSelectableMode(props.selectable);
+  if (selectable !== undefined) {
+    canonical.selectable = selectable;
+  }
+
+  if (typeof props.lang === 'string' && props.lang.trim().length > 0) {
+    canonical.lang = props.lang.trim();
+  }
+
+  if (typeof props.selectionCopyText === 'string') {
+    canonical.selectionCopyText = props.selectionCopyText;
+  }
+
+  if (
+    tagType === 'input' &&
+    typeof props.selection === 'object' &&
+    props.selection !== null
+  ) {
+    const selection = props.selection as { start?: unknown; end?: unknown };
+    if (
+      typeof selection.start === 'number' &&
+      typeof selection.end === 'number' &&
+      Number.isFinite(selection.start) &&
+      Number.isFinite(selection.end) &&
+      selection.start >= 0 &&
+      selection.end >= 0
+    ) {
+      canonical.selectionStart = selection.start;
+      canonical.selectionEnd = selection.end;
+    }
+  }
+
+  // Common props
+
+  // Liquid Glass (Apple iOS 26 / macOS 26). The `glass*` inputs compose into a
+  // single `glassEffect` spec string that rides the existing PropId.GlassEffect
+  // wire prop. The bare-boolean form stays `true` so the native toggle's truthy
+  // check keeps working; richer forms ("regular"/"clear" + ;tint= + ;interactive)
+  // are parsed by the native host and the web fallback. The toggle case above
+  // may already have set a boolean glassEffect — only override when there is a
+  // container-glass refinement to encode.
+  const glassSpec = composeGlassSpec(props, canonical.glassEffect);
+  if (glassSpec !== undefined) {
+    canonical.glassEffect = glassSpec;
+  }
+
+  assignPropAliases(canonical, props, TEST_ID_PROP_ALIASES);
+
+  // Accessibility
+  if (props.decorative === true) {
+    canonical.accessibilityLabel = '';
+  } else if (typeof props.accessibilityLabel === 'string') {
+    canonical.accessibilityLabel = props.accessibilityLabel;
+  } else if (typeof props['aria-label'] === 'string') {
+    canonical.accessibilityLabel = props['aria-label'];
+  } else if (typeof props.alt === 'string') {
+    // Web alt attribute maps to accessibility label
+    canonical.accessibilityLabel = props.alt;
+  }
+
+  if (props.focusScope !== undefined && (typeof props.focusScope === 'boolean' || typeof props.focusScope === 'string')) {
+    canonical.focusScope = props.focusScope;
+  }
+
+  assignPropAliases(canonical, props, COMMON_PROP_ALIASES);
+
+  if (
+    typeof props.accessibilityChecked === 'boolean' ||
+    props.accessibilityChecked === 'mixed'
+  ) {
+    canonical.accessibilityChecked = props.accessibilityChecked;
+  } else if (
+    typeof props['aria-checked'] === 'boolean' ||
+    props['aria-checked'] === 'mixed'
+  ) {
+    canonical.accessibilityChecked = props['aria-checked'] as boolean | 'mixed';
+  }
+
+  const focusable =
+    readBooleanProp(props, 'focusable') ??
+    (typeof props.tabIndex === 'number' ? props.tabIndex >= 0 : undefined);
+  if (focusable !== undefined) {
+    canonical.focusable = focusable;
+  }
+
+  if (typeof props.tabIndex === 'number' && Number.isFinite(props.tabIndex)) {
+    canonical.tabIndex = Math.trunc(props.tabIndex);
+  }
+
+  const accessibilityActions = normalizeAccessibilityActions(props.accessibilityActions);
+  if (accessibilityActions !== undefined) {
+    canonical.accessibilityActions = accessibilityActions;
+  }
+
+  const accessibilityOrder = normalizeAccessibilityOrder(props.accessibilityOrder);
+  if (accessibilityOrder !== undefined) {
+    canonical.accessibilityOrder = accessibilityOrder;
+  }
+
+  // `agentSemantics` follows the same renderer-local rule as `agentSummary`,
+  // but it carries structured metadata. Keep it serialized so CanonicalProps
+  // stays shallow and the props equality check remains a cheap string compare.
+  if (props.agentSemantics != null && typeof props.agentSemantics === 'object') {
+    try {
+      const serialized = JSON.stringify(props.agentSemantics);
+      if (typeof serialized === 'string') {
+        canonical.agentSemantics = serialized;
+      }
+    } catch {
+      // Ignore non-serializable metadata rather than letting authoring-only
+      // hints break rendering. The app surface simply falls back to heuristics.
+    }
+  }
+
+  assignPropAliases(canonical, props, AGENT_ID_PROP_ALIASES);
+
+  return canonical;
+}
+
+/**
+ * Compare two canonical props and return true if they are equal.
+ *
+ * @param a - First props
+ * @param b - Second props
+ * @returns True if props are equal
+ */
+export function propsEqual(a: CanonicalProps, b: CanonicalProps): boolean {
+  // Quick reference check
+  if (a === b) return true;
+
+  const keysA = Object.keys(a) as (keyof CanonicalProps)[];
+  const keysB = Object.keys(b) as (keyof CanonicalProps)[];
+
+  if (keysA.length !== keysB.length) return false;
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+}