@ccheever/exact-renderer 0.1.0

package/src/dom-mirror.ts

@@ -0,0 +1,1459 @@
+// @system @ref LLP 0157 — DOM mirror: a web host for host-ops adapters.
+//
+// Framework adapters built on the shared host-ops layer (Solid, Vue,
+// Svelte, Contract) emit binary protocol batches that only a platform host
+// consumes (`exact.dispatch`). On a plain browser tab no host exists, so
+// those surfaces render nothing — only the React-DOM path has pixels.
+//
+// The mirror closes that gap for development surfaces: after every commit
+// it reconciles the JS-side host-ops node tree (ElementNode/TextNode with
+// `originalProps`) into real DOM under the app container, mapping RN-style
+// styles to CSS (browser flexbox does the layout) and wiring DOM events
+// back into the adapters' handler props — including hover, which the
+// protocol path cannot deliver today.
+//
+// Scope: a development-grade mirror for labs and demos on the plain-web
+// path. It deliberately skips the binary protocol (no decode); the node
+// tree is already in process. When a real host is present
+// (`exact.dispatch` is a function), installation is a no-op so the
+// platform keeps ownership of pixels.
+
+import { colorToRgba, parseColor } from '@exact/core/style/color';
+
+import {
+  isSafeHostDomAttr,
+  lowerHostAttrs,
+  type DomTagName,
+  type HostSemanticAttrs,
+} from './attrs.js';
+import {
+  getHostChannelStyleApplier,
+  setHostChannelStyleApplier,
+  type HostChannelStyleApplier,
+} from './host-ops.js';
+import { getRuntimeImageColorScheme } from './image-source.js';
+import type { ElementNode, RootNode, TextNode } from './nodes/node.js';
+import { NodeKind } from './nodes/node.js';
+
+export type DomMirrorHostChild = ElementNode | TextNode;
+type HostChild = DomMirrorHostChild;
+
+interface DomMirrorRegistry {
+  sync(root: RootNode): void;
+  remove(rootId: number): void;
+}
+
+export interface DomIdentityRegistry {
+  elementForViewId(viewId: number): HTMLElement | null;
+  viewIdForTarget(target: EventTarget | null): number | null;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __exactDomMirror: DomMirrorRegistry | undefined;
+  // eslint-disable-next-line no-var
+  var __exactDomIdentity: DomIdentityRegistry | undefined;
+  // eslint-disable-next-line no-var
+  var __exactDomHydrationAdopterFactory:
+    | ((options: DomHydrationAdopterFactoryOptions) => DomHydrationAdopter | null)
+    | undefined;
+}
+
+export interface DomMirrorOptions {
+  /** Container for root 0 (default: #exact-root, else document.body). */
+  container?: HTMLElement;
+  /** Install even when a protocol host (exact.dispatch) is present. */
+  force?: boolean;
+  /** Optional DOM adoption data for a pre-rendered Contract web root. */
+  hydrate?: DomHydrationOptions;
+}
+
+export interface DomMirrorHandle {
+  dispose(): void;
+}
+
+export interface DomHydrationManifestLike {
+  version?: number;
+  rootId?: number;
+  nodes?: Array<{
+    nodeId?: string;
+    domPath?: number[];
+    kind?: string;
+    tag?: string;
+    textGuard?: string;
+  }>;
+}
+
+export interface DomHydrationResult {
+  rootId: number;
+  adoptedNodes: number;
+  recreatedNodes: number;
+  mismatches: string[];
+}
+
+export interface DomHydrationOptions {
+  rootId: number;
+  manifest: DomHydrationManifestLike;
+  onResult?: (result: DomHydrationResult) => void;
+}
+
+export interface DomHydrationAdopterFactoryOptions {
+  hydrate: DomHydrationOptions;
+  markMirrored(node: Node): void;
+}
+
+export interface DomHydrationAdopter {
+  adoptRootContainer(
+    rootId: number,
+    base: HTMLElement,
+    rootAttribute: string,
+  ): HTMLElement | null;
+  adoptDom(
+    child: DomMirrorHostChild,
+    rootId: number,
+    rootContainer: HTMLElement,
+    desiredTag?: DomTagName,
+  ): Node | null;
+  report(rootId: number): void;
+}
+
+export interface ContractWebHostOptions extends DomMirrorOptions {}
+
+export interface ContractWebHostHandle extends DomMirrorHandle {}
+
+interface DomHostRuntimeOptions {
+  exposeDevIdentity: boolean;
+  rootAttribute: 'data-exact-mirror-root' | 'data-exact-contract-host-root';
+}
+
+function asDomNode(target: EventTarget | null): Node | null {
+  if (
+    target &&
+    typeof target === 'object' &&
+    'parentNode' in target &&
+    'nodeType' in target
+  ) {
+    return target as Node;
+  }
+  return null;
+}
+
+function hasProtocolHost(): boolean {
+  const runtime = globalThis as typeof globalThis & {
+    exact?: { dispatch?: unknown };
+  };
+  return typeof runtime.exact?.dispatch === 'function';
+}
+
+// ---------------------------------------------------------------------------
+// Style conversion: RN-ish style objects -> CSS
+// ---------------------------------------------------------------------------
+
+const UNITLESS = new Set([
+  'flex',
+  'flexGrow',
+  'flexShrink',
+  'opacity',
+  'zIndex',
+  'fontWeight',
+  'aspectRatio',
+  'order',
+]);
+
+const TRANSITION_PROPERTY_CSS: Record<string, string> = {
+  opacity: 'opacity',
+  transform: 'transform',
+  backgroundColor: 'background-color',
+  borderRadius: 'border-radius',
+};
+
+function cssEasing(easing: unknown): string {
+  if (Array.isArray(easing) && easing.length === 4) {
+    return `cubic-bezier(${easing.join(', ')})`;
+  }
+  switch (easing) {
+    case 'easeIn':
+      return 'ease-in';
+    case 'easeOut':
+      return 'ease-out';
+    case 'easeInOut':
+      return 'ease-in-out';
+    case 'linear':
+    default:
+      return 'linear';
+  }
+}
+
+// Shared with web-primitives.tsx so the React-DOM path and the mirror agree
+// on how Exact transition maps / transform arrays become CSS.
+export function cssTransition(value: unknown): string | null {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const parts: string[] = [];
+  for (const [property, config] of Object.entries(value as Record<string, unknown>)) {
+    const cssProperty = TRANSITION_PROPERTY_CSS[property];
+    if (!cssProperty || !config || typeof config !== 'object') {
+      continue;
+    }
+    const transition = config as { type?: string; duration?: number; easing?: unknown };
+    if (transition.type === 'none') {
+      continue;
+    }
+    if (transition.type === 'spring') {
+      // Springs approximate to a fast ease-out curve on the mirror.
+      parts.push(`${cssProperty} ${transition.duration ?? 300}ms cubic-bezier(0.22, 1, 0.36, 1)`);
+    } else {
+      parts.push(`${cssProperty} ${transition.duration ?? 200}ms ${cssEasing(transition.easing)}`);
+    }
+  }
+  return parts.length > 0 ? parts.join(', ') : null;
+}
+
+export function cssTransform(value: unknown): string | null {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const parts: string[] = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== 'object') {
+      continue;
+    }
+    for (const [op, amount] of Object.entries(entry as Record<string, unknown>)) {
+      if (op === 'translateX' || op === 'translateY') {
+        parts.push(`${op}(${typeof amount === 'number' ? `${amount}px` : String(amount)})`);
+      } else if (op === 'scale' || op === 'scaleX' || op === 'scaleY') {
+        parts.push(`${op}(${String(amount)})`);
+      } else if (op === 'rotate') {
+        parts.push(`rotate(${String(amount)})`);
+      }
+    }
+  }
+  return parts.length > 0 ? parts.join(' ') : null;
+}
+
+function cssValue(name: string, value: unknown): string {
+  if (typeof value === 'number') {
+    return UNITLESS.has(name) ? String(value) : `${value}px`;
+  }
+  if (Array.isArray(value)) {
+    // e.g. fontFamily stacks
+    return value.join(', ');
+  }
+  return String(value);
+}
+
+function readPositiveLineCount(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? Math.trunc(value)
+    : undefined;
+}
+
+function applyTextLineClampStyles(
+  el: HTMLElement,
+  element: ElementNode,
+  props: Record<string, unknown>,
+): void {
+  if (!TEXT_TAGS.has(element.originalTag)) {
+    return;
+  }
+
+  const styleObject =
+    typeof props.style === 'object' && props.style !== null
+      ? (props.style as Record<string, unknown>)
+      : undefined;
+  const numberOfLines =
+    readPositiveLineCount(props.numberOfLines) ??
+    readPositiveLineCount(styleObject?.numberOfLines) ??
+    readPositiveLineCount(element.style.numberOfLines);
+  if (numberOfLines == null) {
+    return;
+  }
+
+  if (numberOfLines === 1) {
+    el.style.setProperty('display', 'block');
+    el.style.setProperty('overflow', 'hidden');
+    el.style.setProperty('text-overflow', 'ellipsis');
+    el.style.setProperty('white-space', 'nowrap');
+    return;
+  }
+
+  el.style.setProperty('display', '-webkit-box');
+  el.style.setProperty('-webkit-line-clamp', String(numberOfLines));
+  el.style.setProperty('-webkit-box-orient', 'vertical');
+  el.style.setProperty('overflow', 'hidden');
+}
+
+/** Expands RN-only shorthand/composite props into CSS-compatible entries. */
+function convertStyle(style: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!style) {
+    return out;
+  }
+
+  let shadow: { x?: number; y?: number; blur?: number; color?: string; opacity?: number } | null = null;
+
+  for (const [name, value] of Object.entries(style)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    switch (name) {
+      case 'transition': {
+        const converted = cssTransition(value);
+        if (converted) {
+          out.transition = converted;
+        }
+        break;
+      }
+      case 'transform': {
+        const converted = cssTransform(value);
+        if (converted) {
+          out.transform = converted;
+        }
+        break;
+      }
+      case 'paddingHorizontal':
+        out.paddingLeft = cssValue('paddingLeft', value);
+        out.paddingRight = cssValue('paddingRight', value);
+        break;
+      case 'paddingVertical':
+        out.paddingTop = cssValue('paddingTop', value);
+        out.paddingBottom = cssValue('paddingBottom', value);
+        break;
+      case 'marginHorizontal':
+        out.marginLeft = cssValue('marginLeft', value);
+        out.marginRight = cssValue('marginRight', value);
+        break;
+      case 'marginVertical':
+        out.marginTop = cssValue('marginTop', value);
+        out.marginBottom = cssValue('marginBottom', value);
+        break;
+      case 'shadowColor':
+        shadow = { ...(shadow ?? {}), color: String(value) };
+        break;
+      case 'shadowOffset': {
+        const offset = value as { width?: number; height?: number };
+        shadow = { ...(shadow ?? {}), x: offset?.width ?? 0, y: offset?.height ?? 0 };
+        break;
+      }
+      case 'shadowRadius':
+        shadow = { ...(shadow ?? {}), blur: Number(value) };
+        break;
+      case 'shadowOpacity':
+        // Folded into the color only when no boxShadow string is present.
+        shadow = { ...(shadow ?? {}), opacity: Number(value) };
+        break;
+      case 'textAlignVertical':
+      case 'numberOfLines':
+      case 'fontVariant':
+        break; // no direct CSS equivalent worth approximating here
+      case 'borderWidth':
+        out.borderWidth = cssValue(name, value);
+        out.borderStyle = 'solid';
+        break;
+      case 'borderBottomWidth':
+        out.borderBottomWidth = cssValue(name, value);
+        out.borderBottomStyle = 'solid';
+        break;
+      case 'borderLeftWidth':
+        out.borderLeftWidth = cssValue(name, value);
+        out.borderLeftStyle = 'solid';
+        break;
+      default:
+        out[name] = cssValue(name, value);
+        break;
+    }
+  }
+
+  if (!out.boxShadow && shadow && (shadow.blur ?? 0) > 0 && shadow.color) {
+    const opacity = Math.max(0, Math.min(shadow.opacity ?? 1, 1));
+    const parsed = parseColor(shadow.color);
+    const cssColor = parsed
+      ? colorToRgba({ ...parsed, a: Math.round(parsed.a * opacity) })
+      : shadow.color;
+    out.boxShadow = `${shadow.x ?? 0}px ${shadow.y ?? 0}px ${shadow.blur}px ${cssColor}`;
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Tag mapping + per-tag defaults
+// ---------------------------------------------------------------------------
+
+const RN_CONTAINER_TAGS = new Set(['View', 'ScrollView', 'Pressable', 'List']);
+const WEB_CONTAINER_TAGS = new Set([
+  'a',
+  'div',
+  'section',
+  'main',
+  'article',
+  'blockquote',
+  'pre',
+  'hr',
+  'nav',
+  'aside',
+  'header',
+  'footer',
+  'form',
+  'label',
+]);
+const TEXT_TAGS = new Set(['Text', 'text', 'span', 'p', 'code', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+// Semantic elements whose user-agent stylesheet margins must be zeroed so web
+// layout matches the kernel/Taffy layout (which has no UA stylesheet). `tagName`
+// is uppercase. Heading margins (`h1..h6`) were the missing case behind
+// ENG-22092: web headings inherited `margin-block: <factor>em` from the UA
+// sheet while native had none, so vertical spacing diverged. Surfaces that want
+// heading spacing set it explicitly (the blog uses `headingMarginBlock`).
+const UA_MARGIN_RESET_TAGS = new Set(['BLOCKQUOTE', 'PRE', 'HR', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6']);
+
+function defaultDomTagFor(node: ElementNode): DomTagName {
+  const tag = node.originalTag;
+  const props = (node.originalProps ?? {}) as Record<string, unknown>;
+  if (tag === 'Pressable' || tag === 'button' || tag === 'a') {
+    return 'button';
+  }
+  if (tag === 'TextInput' || tag === 'input' || tag === 'textarea') {
+    return props.multiline ? 'textarea' : 'input';
+  }
+  if (tag === 'Toggle' || tag === 'Switch' || tag === 'toggle') {
+    return 'input';
+  }
+  if (tag === 'Image' || tag === 'img') {
+    if (typeof props.svgSource === 'string' && props.svgSource.trim().length > 0) {
+      return 'span';
+    }
+    return 'img';
+  }
+  if (TEXT_TAGS.has(tag)) {
+    return tag === 'Text' || tag === 'text' || tag === 'p' ? 'span' : (tag as DomTagName);
+  }
+  if (WEB_CONTAINER_TAGS.has(tag)) {
+    return tag as DomTagName;
+  }
+  return 'div';
+}
+
+function semanticAttrsFromProps(props: Record<string, unknown>): HostSemanticAttrs | undefined {
+  const tag = props.__exactSemanticTag;
+  return typeof tag === 'string' && tag.length > 0 ? { tag } : undefined;
+}
+
+function loweredAttrsFor(node: ElementNode) {
+  const props = (node.originalProps ?? {}) as Record<string, unknown>;
+  return lowerHostAttrs(
+    { tag: node.originalTag, props },
+    semanticAttrsFromProps(props),
+    { defaultTag: defaultDomTagFor(node) },
+  );
+}
+
+function domTagFor(node: ElementNode): DomTagName {
+  return loweredAttrsFor(node).tag;
+}
+
+// True when an interactive node sits directly inside a text element, i.e. it is
+// part of an inline run — a markdown link or footnote reference inside a
+// paragraph's `text`. Such a node must flow inline rather than become a
+// block-level flex container. A standalone link/button (e.g. a footnote
+// back-link inside a `row`) has a non-text parent and keeps its flex layout.
+function isInlineTextFlowChild(node: ElementNode): boolean {
+  const parent = node.parent;
+  if (!parent || parent.kind !== NodeKind.Element) {
+    return false;
+  }
+  return TEXT_TAGS.has((parent as ElementNode).originalTag);
+}
+
+function applyTagDefaults(el: HTMLElement, node: ElementNode): void {
+  const tag = node.originalTag;
+  const style = el.style as unknown as Record<string, string>;
+  style.boxSizing = 'border-box';
+
+  if (RN_CONTAINER_TAGS.has(tag)) {
+    style.display = 'flex';
+    style.flexDirection = 'column';
+    style.alignItems = 'stretch';
+    style.position = 'relative';
+    style.minWidth = '0';
+    style.minHeight = '0';
+    // ENG-22199: RN/Yoga (and the kernel/Taffy path via buildDefaultCanonicalStyle
+    // for RN-style tags) default flexShrink to 0 — flex items keep their content
+    // size and overflow rather than shrinking. CSS flexbox defaults flexShrink to
+    // 1, so a bare `row`/`column` inside an overflowing flex column would shrink
+    // below its content (down to min-height:0, set just above) and collapse to
+    // height 0 while its children paint at full size, overlapping the next
+    // sibling. Matching the RN default keeps the mirror's layout consistent with
+    // native and with initial render. Explicit `flex`/`shrink`/`grow` styles are
+    // applied after these defaults and still win (e.g. the ScrollView flex below).
+    style.flexShrink = '0';
+  }
+  if (tag === 'ScrollView') {
+    style.overflowY = 'auto';
+    style.flex = '1 1 0%';
+    style.width = '100%';
+    style.minHeight = '0';
+  }
+  if (WEB_CONTAINER_TAGS.has(tag)) {
+    style.display = 'flex';
+    style.flexDirection = 'row';
+    style.position = 'relative';
+  }
+  if (UA_MARGIN_RESET_TAGS.has(el.tagName)) {
+    style.margin = '0';
+  }
+  if (el.tagName === 'PRE') {
+    style.whiteSpace = 'pre-wrap';
+    style.font = 'inherit';
+  }
+  if (el.tagName === 'HR') {
+    style.border = 'none';
+    style.display = 'block';
+  }
+  if (TEXT_TAGS.has(tag)) {
+    style.whiteSpace = 'pre-wrap';
+  }
+  if (el.tagName === 'BUTTON') {
+    el.setAttribute('type', 'button');
+    style.display = 'flex';
+    style.flexDirection = 'column';
+    style.alignItems = 'stretch';
+    style.position = 'relative';
+    style.background = 'transparent';
+    style.border = 'none';
+    style.margin = '0';
+    style.padding = '0';
+    style.font = 'inherit';
+    style.color = 'inherit';
+    style.textAlign = 'inherit';
+    style.cursor = 'pointer';
+  }
+  if (el.tagName === 'A') {
+    style.display = 'flex';
+    style.flexDirection = 'column';
+    style.alignItems = 'stretch';
+    style.position = 'relative';
+    style.color = 'inherit';
+    style.textDecoration = 'none';
+    style.cursor = 'pointer';
+  }
+  if (tag === 'Toggle' || tag === 'Switch' || tag === 'toggle') {
+    el.setAttribute('type', 'checkbox');
+  }
+  if ((el.tagName === 'INPUT' && el.getAttribute('type') !== 'checkbox') || el.tagName === 'TEXTAREA') {
+    // Form controls do not inherit typography from their parents in the UA
+    // stylesheet; without this an unstyled input renders UA-black text on
+    // themed dark surfaces (Design Mode panel inputs). Explicit color/font
+    // styles still win — node styles are applied after tag defaults.
+    style.font = 'inherit';
+    style.color = 'inherit';
+  }
+
+  // ENG-22115: An interactive node (a link or button) that sits inside a text
+  // element is part of an inline run — e.g. a markdown link inside a paragraph.
+  // The flex-container defaults above (display:flex; flex-direction:column)
+  // make it a block-level box, so on web the link broke onto its own line with
+  // weird breaks before and after it, while macOS rendered it inline. Native
+  // flattens text + link children into a single inline run via static-text
+  // composition; the web analog is to let the element flow inline. Applied
+  // last so it overrides the BUTTON/A/Pressable flex defaults set above, and
+  // node styles (applied after tag defaults) can still override it.
+  if ((el.tagName === 'A' || el.tagName === 'BUTTON') && isInlineTextFlowChild(node)) {
+    style.display = 'inline';
+    style.flexDirection = '';
+    style.alignItems = '';
+    style.minWidth = '';
+    style.minHeight = '';
+    style.flexShrink = '';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Props -> attributes
+// ---------------------------------------------------------------------------
+
+function isMirrorDevMode(): 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';
+}
+
+function clearElementAttributes(el: HTMLElement): void {
+  for (const name of el.getAttributeNames()) {
+    el.removeAttribute(name);
+  }
+}
+
+function shouldApplyHostAttr(name: string, value: unknown): boolean {
+  if (name === 'style' || name === 'children' || name === 'ref' || name === 'key') {
+    return false;
+  }
+  if (value === undefined || value === null) {
+    return false;
+  }
+  if (typeof value === 'function') {
+    return false;
+  }
+  if (typeof value === 'object') {
+    return false;
+  }
+  if (!isSafeHostDomAttr(name, value)) {
+    return false;
+  }
+  return true;
+}
+
+function applyHostAttr(el: HTMLElement, name: string, value: unknown): void {
+  if (!shouldApplyHostAttr(name, value)) {
+    return;
+  }
+  if (name === 'className') {
+    el.setAttribute('class', String(value));
+    return;
+  }
+  if (name === 'htmlFor') {
+    el.setAttribute('for', String(value));
+    return;
+  }
+  if (name === 'tabIndex') {
+    el.tabIndex = Number(value);
+    return;
+  }
+  if (typeof value === 'boolean') {
+    if (name.startsWith('aria-')) {
+      el.setAttribute(name, String(value));
+      return;
+    }
+    if (value === false) {
+      return;
+    }
+    if (name === 'inert') {
+      (el as HTMLElement & { inert?: boolean }).inert = true;
+    }
+    el.setAttribute(name, '');
+    return;
+  }
+  el.setAttribute(name, String(value));
+}
+
+let nextInlineSvgTitleId = 1;
+
+function svgParserConstructor(): typeof DOMParser | undefined {
+  const runtimeParser = (globalThis as typeof globalThis & { DOMParser?: typeof DOMParser }).DOMParser;
+  if (runtimeParser) {
+    return runtimeParser;
+  }
+  return (globalThis as typeof globalThis & { window?: { DOMParser?: typeof DOMParser } }).window?.DOMParser;
+}
+
+function parseInlineSvg(markup: string): SVGSVGElement | null {
+  const template = document.createElement('template');
+  template.innerHTML = markup.trim();
+  const templateSvg = template.content.firstElementChild;
+  if (templateSvg && templateSvg.tagName.toLowerCase() === 'svg') {
+    return document.adoptNode(templateSvg) as unknown as SVGSVGElement;
+  }
+
+  const Parser = svgParserConstructor();
+  if (Parser) {
+    const parsed = new Parser().parseFromString(markup, 'image/svg+xml');
+    if (parsed.querySelector('parsererror')) {
+      return null;
+    }
+    const svg = parsed.documentElement;
+    if (!svg || svg.tagName.toLowerCase() !== 'svg') {
+      return null;
+    }
+    return document.adoptNode(svg) as unknown as SVGSVGElement;
+  }
+  return null;
+}
+
+function mapSvgObjectPosition(objectPosition: unknown): string {
+  if (typeof objectPosition !== 'string' || objectPosition.trim().length === 0) {
+    return 'xMidYMid';
+  }
+
+  const tokens = objectPosition.toLowerCase().trim().split(/\s+/).filter(Boolean);
+  let horizontal: 'xMin' | 'xMid' | 'xMax' = 'xMid';
+  let vertical: 'YMin' | 'YMid' | 'YMax' = 'YMid';
+
+  for (const token of tokens) {
+    if (token === 'left') {
+      horizontal = 'xMin';
+    } else if (token === 'right') {
+      horizontal = 'xMax';
+    } else if (token === 'top') {
+      vertical = 'YMin';
+    } else if (token === 'bottom') {
+      vertical = 'YMax';
+    } else if (token === 'center') {
+      if (!tokens.some((value) => value === 'left' || value === 'right')) {
+        horizontal = 'xMid';
+      }
+      if (!tokens.some((value) => value === 'top' || value === 'bottom')) {
+        vertical = 'YMid';
+      }
+    }
+  }
+
+  return `${horizontal}${vertical}`;
+}
+
+function applyInlineSvgSizing(svg: SVGSVGElement, props: Record<string, unknown>): void {
+  const fit = props.objectFit ?? 'contain';
+  const alignment = mapSvgObjectPosition(props.objectPosition);
+  if (fit === 'cover') {
+    svg.setAttribute('preserveAspectRatio', `${alignment} slice`);
+  } else if (fit === 'fill') {
+    svg.setAttribute('preserveAspectRatio', 'none');
+  } else if (fit === 'none') {
+    svg.setAttribute('preserveAspectRatio', alignment);
+  } else {
+    svg.setAttribute('preserveAspectRatio', `${alignment} meet`);
+  }
+}
+
+function applyInlineSvgTint(svg: SVGSVGElement, tintColor: unknown): void {
+  if (typeof tintColor !== 'string' || tintColor.length === 0) {
+    return;
+  }
+
+  svg.style.color = tintColor;
+  const paintedNodes = svg.querySelectorAll<SVGElement>('[fill], [stroke]');
+  paintedNodes.forEach((node) => {
+    const fill = node.getAttribute('fill');
+    if (fill && fill !== 'none' && !fill.startsWith('url(')) {
+      node.setAttribute('fill', 'currentColor');
+    }
+
+    const stroke = node.getAttribute('stroke');
+    if (stroke && stroke !== 'none' && !stroke.startsWith('url(')) {
+      node.setAttribute('stroke', 'currentColor');
+    }
+  });
+}
+
+function applyInlineSvgAccessibility(svg: SVGSVGElement, props: Record<string, unknown>): void {
+  if (props.decorative === true) {
+    svg.setAttribute('aria-hidden', 'true');
+    return;
+  }
+
+  const label = typeof props.alt === 'string' && props.alt.length > 0
+    ? props.alt
+    : typeof props.accessibilityLabel === 'string' && props.accessibilityLabel.length > 0
+      ? props.accessibilityLabel
+      : undefined;
+  if (!label) {
+    return;
+  }
+
+  svg.setAttribute('role', 'img');
+  let title = svg.querySelector<SVGElement>('title');
+  if (!title) {
+    title = document.createElementNS('http://www.w3.org/2000/svg', 'title') as SVGElement;
+    svg.prepend(title);
+  }
+  title.textContent = label;
+  const titleId = `exact-svg-title-${nextInlineSvgTitleId++}`;
+  title.setAttribute('id', titleId);
+  svg.setAttribute('aria-labelledby', titleId);
+}
+
+function applyInlineSvgHost(el: HTMLElement, props: Record<string, unknown>): void {
+  const markup = typeof props.svgSource === 'string' ? props.svgSource : undefined;
+  if (!markup || markup.trim().length === 0) {
+    while (el.firstChild) {
+      el.removeChild(el.firstChild);
+    }
+    return;
+  }
+
+  const style = el.style as unknown as Record<string, string>;
+  style.display = 'block';
+  style.boxSizing = 'border-box';
+  style.overflow = 'hidden';
+
+  while (el.firstChild) {
+    el.removeChild(el.firstChild);
+  }
+
+  const svg = parseInlineSvg(markup);
+  if (!svg) {
+    return;
+  }
+
+  svg.style.display = 'block';
+  svg.style.width = '100%';
+  svg.style.height = '100%';
+  applyInlineSvgSizing(svg, props);
+  applyInlineSvgTint(svg, props.tintColor);
+  applyInlineSvgAccessibility(svg, props);
+  el.appendChild(svg);
+}
+
+function applyProps(el: HTMLElement, node: ElementNode, runtime: DomHostRuntimeOptions): void {
+  const props = (node.originalProps ?? {}) as Record<string, unknown>;
+  const lowered = loweredAttrsFor(node);
+
+  // Design Mode D0 (LLP 0158): dev-only DOM → host-node identity so the
+  // overlay can hit-test real pixels back to renderer nodes.
+  clearElementAttributes(el);
+  if (runtime.exposeDevIdentity && isMirrorDevMode()) {
+    el.setAttribute('data-exact-view-id', String(node.id));
+  }
+
+  // Reset previous inline styles, then defaults + converted style.
+  applyTagDefaults(el, node);
+  const css = convertStyle(props.style as Record<string, unknown> | undefined);
+  const style = el.style as unknown as Record<string, string>;
+  for (const [name, value] of Object.entries(css)) {
+    style[name] = value;
+  }
+  applyTextLineClampStyles(el, node, props);
+
+  for (const [name, value] of Object.entries(lowered.attrs)) {
+    applyHostAttr(el, name, value);
+  }
+
+  if (props.focusScope === 'trapped') {
+    el.setAttribute('data-exact-focus-scope', 'trapped');
+    if (props.__exactFocusRestore === true) {
+      el.setAttribute('data-exact-focus-restore', 'true');
+    }
+    if (!el.hasAttribute('tabindex')) {
+      el.tabIndex = -1;
+    }
+  }
+
+  if (el.tagName === 'BUTTON' || el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+    (el as HTMLButtonElement).disabled = props.disabled === true;
+  }
+
+  if (el.tagName === 'INPUT' && el.getAttribute('type') === 'checkbox') {
+    (el as HTMLInputElement).checked = props.value === true || props.checked === true;
+  } else if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+    const input = el as HTMLInputElement;
+    if (props.placeholder != null) {
+      input.setAttribute('placeholder', String(props.placeholder));
+    }
+    if (props.secureTextEntry === true) {
+      input.setAttribute('type', 'password');
+    }
+    const value = props.value;
+    if (value !== undefined && input.value !== String(value ?? '')) {
+      input.value = String(value ?? '');
+    }
+  }
+
+  if (el.tagName === 'IMG') {
+    const img = el as HTMLImageElement;
+    applyThemeImageProps(img, props);
+    const resolvedSrc = resolveThemeImageSrc(props);
+    if (resolvedSrc != null && isSafeHostDomAttr('src', resolvedSrc)) {
+      img.setAttribute('src', resolvedSrc);
+    } else if (props.src != null && isSafeHostDomAttr('src', props.src)) {
+      img.setAttribute('src', String(props.src));
+    }
+    if (props.decorative === true) {
+      img.setAttribute('alt', '');
+    } else if (props.alt != null) {
+      img.setAttribute('alt', String(props.alt));
+    } else if (props.accessibilityLabel != null) {
+      img.setAttribute('alt', String(props.accessibilityLabel));
+    }
+  } else if (el.tagName === 'SPAN' && typeof props.svgSource === 'string') {
+    applyInlineSvgHost(el, props);
+  }
+}
+
+function applyThemeImageProps(img: HTMLImageElement, props: Record<string, unknown>): void {
+  const lightSrc = stringProp(props.lightSrc);
+  const darkSrc = stringProp(props.darkSrc);
+  const rawTreatment = stringProp(props.themeTreatment);
+  const treatment = rawTreatment === 'none' ? undefined : rawTreatment;
+
+  setOrRemoveAttr(img, 'data-light-src', lightSrc);
+  setOrRemoveAttr(img, 'data-dark-src', darkSrc);
+  setOrRemoveAttr(img, 'data-exact-theme-treatment', treatment);
+  if (lightSrc || darkSrc || treatment) {
+    img.setAttribute('data-exact-theme-image', 'color-scheme');
+  } else {
+    img.removeAttribute('data-exact-theme-image');
+  }
+}
+
+function resolveThemeImageSrc(props: Record<string, unknown>): string | undefined {
+  const src = stringProp(props.src);
+  const lightSrc = stringProp(props.lightSrc);
+  const darkSrc = stringProp(props.darkSrc);
+  if (!lightSrc && !darkSrc) {
+    return src;
+  }
+
+  const scheme = getRuntimeImageColorScheme();
+  return scheme === 'dark'
+    ? darkSrc ?? src ?? lightSrc
+    : lightSrc ?? src ?? darkSrc;
+}
+
+function stringProp(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function setOrRemoveAttr(el: HTMLElement, name: string, value: string | undefined): void {
+  if (value != null) {
+    el.setAttribute(name, value);
+  } else {
+    el.removeAttribute(name);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Focus scopes: Contract overlay metadata -> real browser focus behavior
+// ---------------------------------------------------------------------------
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+function activeElement(): HTMLElement | null {
+  const active = document.activeElement;
+  return active && typeof (active as HTMLElement).focus === 'function'
+    ? (active as HTMLElement)
+    : null;
+}
+
+function focusableDescendants(scope: HTMLElement): HTMLElement[] {
+  const nodes = scope.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+  const focusables: HTMLElement[] = [];
+  for (let index = 0; index < nodes.length; index += 1) {
+    const candidate = nodes.item(index);
+    if (
+      !candidate.hasAttribute('disabled') &&
+      candidate.getAttribute('aria-hidden') !== 'true' &&
+      candidate.tabIndex >= 0
+    ) {
+      focusables.push(candidate);
+    }
+  }
+  return focusables;
+}
+
+function focusTargetForScope(scope: HTMLElement): HTMLElement {
+  return focusableDescendants(scope)[0] ?? scope;
+}
+
+function trapTabKey(scope: HTMLElement, event: KeyboardEvent): void {
+  const focusables = focusableDescendants(scope);
+  if (focusables.length === 0) {
+    event.preventDefault();
+    scope.focus();
+    return;
+  }
+
+  const active = activeElement();
+  const index = active ? focusables.indexOf(active) : -1;
+  if (event.shiftKey) {
+    if (index <= 0) {
+      event.preventDefault();
+      focusables[focusables.length - 1]?.focus();
+    }
+    return;
+  }
+
+  if (index === -1 || index === focusables.length - 1) {
+    event.preventDefault();
+    focusables[0]?.focus();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Events: DOM -> adapter handler props (read lazily at event time, so
+// updated handlers and interaction behaviors keep working without rewiring)
+// ---------------------------------------------------------------------------
+
+function handler(node: ElementNode, name: string): ((...args: unknown[]) => void) | null {
+  const props = (node.originalProps ?? {}) as Record<string, unknown>;
+  const candidate = props[name];
+  return typeof candidate === 'function' ? (candidate as (...args: unknown[]) => void) : null;
+}
+
+function syncControlledInputValue(el: HTMLInputElement | HTMLTextAreaElement, node: ElementNode): void {
+  const props = (node.originalProps ?? {}) as Record<string, unknown>;
+  const value = props.value;
+  if (value === undefined) {
+    return;
+  }
+  const controlledValue = String(value ?? '');
+  if (el.value !== controlledValue) {
+    el.value = controlledValue;
+  }
+}
+
+// LLP 0281 stage 0 (LLP 0275 A1): element-local pointer payload for the
+// Contract pointer event attrs. The envelope carries the pinned sample
+// (element-local coordinates) plus the element box so a rated publish can
+// normalize to fractions without a second geometry read.
+function pointerEnvelope(el: HTMLElement, event: Event, phase: string): Record<string, unknown> {
+  const pointer = event as PointerEvent;
+  const rect = el.getBoundingClientRect();
+  return {
+    sample: {
+      x: (pointer.clientX ?? 0) - rect.left,
+      y: (pointer.clientY ?? 0) - rect.top,
+      pointerId: pointer.pointerId ?? -1,
+      pointerType: pointer.pointerType || 'mouse',
+      buttons: pointer.buttons ?? 0,
+      pressure: pointer.pressure ?? 0,
+    },
+    element: { width: rect.width, height: rect.height },
+    phase,
+    timeStampMs: event.timeStamp,
+  };
+}
+
+function dispatchPointerHandler(
+  el: HTMLElement,
+  node: ElementNode,
+  event: Event,
+  phase: string,
+  handlerProp: string,
+): void {
+  const pointerHandler = handler(node, handlerProp);
+  if (pointerHandler) {
+    pointerHandler(pointerEnvelope(el, event, phase));
+  }
+}
+
+function wireEvents(el: HTMLElement, node: ElementNode): void {
+  el.addEventListener('click', (event) => {
+    if ((node.originalProps as Record<string, unknown>)?.disabled === true) {
+      return;
+    }
+    handler(node, 'onPress')?.({ type: 'press', nativeEvent: event });
+  });
+  el.addEventListener('pointerdown', (event) => {
+    handler(node, 'onPressIn')?.({ type: 'pressin' });
+    // The capture affordance (LLP 0275 A2): explicit `pointerCapture=true`
+    // captures the pointer on down, web-platform style, so a drag keeps
+    // streaming to this element after the pointer leaves its box.
+    const props = (node.originalProps ?? {}) as Record<string, unknown>;
+    if (props.pointerCapture === true) {
+      const pointerId = (event as PointerEvent).pointerId;
+      if (typeof pointerId === 'number' && typeof el.setPointerCapture === 'function') {
+        try {
+          el.setPointerCapture(pointerId);
+        } catch {
+          // Capture is best-effort (the pointer may already be gone).
+        }
+      }
+    }
+    dispatchPointerHandler(el, node, event, 'pointerdown', 'onPointerDown');
+  });
+  el.addEventListener('pointerup', (event) => {
+    handler(node, 'onPressOut')?.({ type: 'pressout' });
+    dispatchPointerHandler(el, node, event, 'pointerup', 'onPointerUp');
+  });
+  el.addEventListener('pointermove', (event) => {
+    dispatchPointerHandler(el, node, event, 'pointermove', 'onPointerMove');
+  });
+  el.addEventListener('pointercancel', (event) => {
+    dispatchPointerHandler(el, node, event, 'pointercancel', 'onPointerCancel');
+  });
+  el.addEventListener('pointerenter', (event) => {
+    handler(node, 'onHoverIn')?.({ type: 'hoverin' });
+    handler(node, 'onMouseEnter')?.({ type: 'mouseenter' });
+    dispatchPointerHandler(el, node, event, 'pointerenter', 'onPointerEnter');
+  });
+  el.addEventListener('pointerleave', (event) => {
+    handler(node, 'onPressOut')?.({ type: 'pressout' });
+    handler(node, 'onHoverOut')?.({ type: 'hoverout' });
+    handler(node, 'onMouseLeave')?.({ type: 'mouseleave' });
+    dispatchPointerHandler(el, node, event, 'pointerleave', 'onPointerLeave');
+  });
+  el.addEventListener('focus', () => {
+    handler(node, 'onFocus')?.({ type: 'focus' });
+  });
+  el.addEventListener('blur', () => {
+    handler(node, 'onBlur')?.({ type: 'blur' });
+  });
+  el.addEventListener('keydown', (event) => {
+    if ((node.originalProps as Record<string, unknown>)?.focusScope === 'trapped') {
+      const key = (event as KeyboardEvent).key;
+      if (key === 'Tab') {
+        trapTabKey(el, event as KeyboardEvent);
+      }
+    }
+    handler(node, 'onKeyDown')?.({ key: (event as KeyboardEvent).key });
+  });
+
+  if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+    el.addEventListener('input', () => {
+      const input = el as HTMLInputElement;
+      if (input.getAttribute('type') === 'checkbox') {
+        return;
+      }
+      handler(node, 'onChangeText')?.(input.value);
+      handler(node, 'onChange')?.({ value: input.value, nativeEvent: { text: input.value } });
+      syncControlledInputValue(input, node);
+    });
+    el.addEventListener('change', () => {
+      const input = el as HTMLInputElement;
+      if (input.getAttribute('type') !== 'checkbox') {
+        return;
+      }
+      handler(node, 'onChange')?.({ value: input.checked, nativeEvent: { value: input.checked } });
+      handler(node, 'onValueChange')?.(input.checked);
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reconciliation
+// ---------------------------------------------------------------------------
+
+const MIRRORED = Symbol('exactDomMirror');
+
+interface MirroredDomNode extends Node {
+  [MIRRORED]?: true;
+}
+
+function installDomHost(
+  options: DomMirrorOptions,
+  runtime: DomHostRuntimeOptions,
+): DomMirrorHandle | null {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  if (hasProtocolHost() && options.force !== true) {
+    // A real platform host owns pixels; the mirror stays out of the way.
+    return null;
+  }
+
+  const domByNode = new WeakMap<HostChild, MirroredDomNode>();
+  const domByViewId = new Map<number, HTMLElement>();
+  const viewIdByDom = new WeakMap<Node, number>();
+  const appliedProps = new WeakMap<ElementNode, unknown>();
+  const appliedText = new WeakMap<TextNode, string>();
+  // LLP 0281 §3.3 — channel-driven style values (transform/opacity sinks).
+  // Applied straight to the DOM node, bypassing the reactive flush; kept
+  // here so applyProps (which resets inline styles) re-applies them after
+  // any ordinary prop update.
+  const channelStyles = new WeakMap<ElementNode, Record<string, unknown>>();
+  const rootContainers = new Map<number, HTMLElement>();
+  const wiredDomNodes = new WeakSet<HTMLElement>();
+  const focusScopes = new Map<HTMLElement, { previous: HTMLElement | null; restore: boolean }>();
+  const hydrationAdopter = options.hydrate
+    ? globalThis.__exactDomHydrationAdopterFactory?.({
+        hydrate: options.hydrate,
+        markMirrored(node) {
+          (node as MirroredDomNode)[MIRRORED] = true;
+        },
+      }) ?? null
+    : null;
+  let disposed = false;
+
+  const baseContainer = (): HTMLElement =>
+    options.container ?? (document.getElementById('exact-root') as HTMLElement | null) ?? document.body;
+
+  const previousIdentity = globalThis.__exactDomIdentity;
+  const identityRegistry: DomIdentityRegistry = {
+    elementForViewId(viewId: number): HTMLElement | null {
+      const element = domByViewId.get(viewId) ?? null;
+      if (element?.isConnected) {
+        return element;
+      }
+      return previousIdentity?.elementForViewId(viewId) ?? null;
+    },
+    viewIdForTarget(target: EventTarget | null): number | null {
+      let node = asDomNode(target);
+      while (node) {
+        const id = viewIdByDom.get(node);
+        if (typeof id === 'number') {
+          return id;
+        }
+        node = node.parentNode;
+      }
+      return previousIdentity?.viewIdForTarget(target) ?? null;
+    },
+  };
+  globalThis.__exactDomIdentity = identityRegistry;
+
+  function containerFor(rootId: number): HTMLElement {
+    let container = rootContainers.get(rootId);
+    if (!container || !container.isConnected) {
+      const adopted = hydrationAdopter?.adoptRootContainer(
+        rootId,
+        baseContainer(),
+        runtime.rootAttribute,
+      );
+      if (adopted) {
+        (adopted as MirroredDomNode)[MIRRORED] = true;
+        rootContainers.set(rootId, adopted);
+        return adopted;
+      }
+      container = document.createElement('div');
+      (container as MirroredDomNode)[MIRRORED] = true;
+      container.setAttribute(runtime.rootAttribute, String(rootId));
+      const style = container.style as unknown as Record<string, string>;
+      style.display = 'flex';
+      style.flexDirection = 'column';
+      style.alignItems = 'stretch';
+      style.width = '100%';
+      style.height = '100%';
+      style.minHeight = '0';
+      // Platform parity: native renders unstyled text in the system font, so
+      // the mirror's default must be the system sans stack — not the
+      // browser's serif fallback. Nodes that set fontFamily still win.
+      style.fontFamily =
+        "-apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', system-ui, 'Helvetica Neue', sans-serif";
+      baseContainer().appendChild(container);
+      rootContainers.set(rootId, container);
+    }
+    return container;
+  }
+
+  function syncFocusScopes(rootContainer: HTMLElement): void {
+    const currentNodes = rootContainer.querySelectorAll<HTMLElement>('[data-exact-focus-scope="trapped"]');
+    const current = new Set<HTMLElement>();
+    for (let index = 0; index < currentNodes.length; index += 1) {
+      current.add(currentNodes.item(index));
+    }
+
+    for (const [scope, state] of focusScopes) {
+      if (scope.isConnected && current.has(scope)) {
+        continue;
+      }
+      focusScopes.delete(scope);
+      if (state.restore && state.previous?.isConnected) {
+        state.previous.focus();
+      }
+    }
+
+    for (const scope of current) {
+      if (focusScopes.has(scope)) {
+        continue;
+      }
+      const previous = activeElement();
+      focusScopes.set(scope, {
+        previous: previous && !scope.contains(previous) ? previous : null,
+        restore: scope.getAttribute('data-exact-focus-restore') === 'true',
+      });
+      focusTargetForScope(scope).focus();
+    }
+  }
+
+  function wireEventsOnce(el: HTMLElement, node: ElementNode): void {
+    if (wiredDomNodes.has(el)) {
+      return;
+    }
+    wiredDomNodes.add(el);
+    wireEvents(el, node);
+  }
+
+  // LLP 0281 §3.3 — write one channel-driven style value onto the DOM node
+  // (compositor-only work: transform/opacity), through the same style
+  // conversion applyProps uses so values mean the same thing on both paths.
+  function writeChannelStyle(el: HTMLElement, styleProp: string, value: unknown): void {
+    const css = convertStyle({ [styleProp]: value });
+    const style = el.style as unknown as Record<string, string>;
+    for (const [name, cssValue] of Object.entries(css)) {
+      style[name] = cssValue;
+    }
+  }
+
+  function reapplyChannelStyles(el: HTMLElement, node: ElementNode): void {
+    const pending = channelStyles.get(node);
+    if (!pending) {
+      return;
+    }
+    for (const [styleProp, value] of Object.entries(pending)) {
+      writeChannelStyle(el, styleProp, value);
+    }
+  }
+
+  // The host channel-application seam (LLP 0281 stage 0): the Contract
+  // runtime routes channel style sinks here so per-frame pointer motion
+  // never runs a reactive flush or a host-ops prop diff. Values are
+  // recorded per node and re-applied after ordinary prop updates (which
+  // reset inline styles).
+  const channelApplier: HostChannelStyleApplier = (target, styleProp, value) => {
+    const node = target as ElementNode;
+    if (!node || typeof node !== 'object' || node.kind !== NodeKind.Element) {
+      return false;
+    }
+    let pending = channelStyles.get(node);
+    if (!pending) {
+      pending = {};
+      channelStyles.set(node, pending);
+    }
+    pending[styleProp] = value;
+    const dom = domByNode.get(node) as HTMLElement | undefined;
+    if (dom) {
+      writeChannelStyle(dom, styleProp, value);
+    }
+    // Recorded even when the node has no DOM yet — ensureDom applies it on
+    // first sync, so early channel writes are never lost.
+    return true;
+  };
+  const previousChannelApplier = getHostChannelStyleApplier();
+  setHostChannelStyleApplier(channelApplier);
+
+  function ensureDom(
+    child: HostChild,
+    rootId: number,
+    rootContainer: HTMLElement,
+  ): MirroredDomNode {
+    if (child.kind === NodeKind.Text) {
+      const textNode = child as TextNode;
+      let dom = domByNode.get(textNode);
+      if (!dom) {
+        dom = (hydrationAdopter?.adoptDom(textNode, rootId, rootContainer) as MirroredDomNode | null) ??
+          (document.createTextNode(textNode.text) as MirroredDomNode);
+        dom[MIRRORED] = true;
+        domByNode.set(textNode, dom);
+        appliedText.set(textNode, textNode.text);
+      } else if (appliedText.get(textNode) !== textNode.text) {
+        dom.nodeValue = textNode.text;
+        appliedText.set(textNode, textNode.text);
+      }
+      return dom;
+    }
+
+    const element = child as ElementNode;
+    let dom = domByNode.get(element) as (HTMLElement & MirroredDomNode) | undefined;
+    const desiredTag = domTagFor(element);
+    if (!dom || dom.localName !== desiredTag) {
+      const previous = dom;
+      dom = (hydrationAdopter?.adoptDom(
+        element,
+        rootId,
+        rootContainer,
+        desiredTag,
+      ) as HTMLElement & MirroredDomNode | null) ??
+        (document.createElement(desiredTag) as HTMLElement & MirroredDomNode);
+      dom[MIRRORED] = true;
+      domByNode.set(element, dom);
+      wireEventsOnce(dom, element);
+      if (previous?.parentNode) {
+        previous.parentNode.replaceChild(dom, previous);
+      }
+      applyProps(dom, element, runtime);
+      appliedProps.set(element, element.originalProps);
+      reapplyChannelStyles(dom, element);
+    } else if (appliedProps.get(element) !== element.originalProps) {
+      applyProps(dom, element, runtime);
+      appliedProps.set(element, element.originalProps);
+      reapplyChannelStyles(dom, element);
+    }
+    domByViewId.set(element.id, dom);
+    viewIdByDom.set(dom, element.id);
+
+    reconcileChildren(element.children as HostChild[], dom, rootId, rootContainer);
+    return dom;
+  }
+
+  function reconcileChildren(
+    children: HostChild[],
+    domParent: HTMLElement,
+    rootId: number,
+    rootContainer: HTMLElement,
+  ): void {
+    const desired = children.map((child) => ensureDom(child, rootId, rootContainer));
+    const desiredSet = new Set<Node>(desired);
+
+    // Remove mirror-owned DOM children that no longer correspond to a node.
+    for (const existing of Array.from(domParent.childNodes)) {
+      if ((existing as MirroredDomNode)[MIRRORED] && !desiredSet.has(existing)) {
+        domParent.removeChild(existing);
+      }
+    }
+
+    // Put the survivors in order with minimal moves.
+    let cursor = domParent.firstChild;
+    for (const next of desired) {
+      while (cursor && !(cursor as MirroredDomNode)[MIRRORED]) {
+        cursor = cursor.nextSibling;
+      }
+      if (cursor === next) {
+        cursor = cursor.nextSibling;
+        continue;
+      }
+      domParent.insertBefore(next, cursor);
+    }
+  }
+
+  const registry: DomMirrorRegistry = {
+    sync(root: RootNode): void {
+      if (disposed) {
+        return;
+      }
+      const rootContainer = containerFor(root.rootId);
+      reconcileChildren(root.children as HostChild[], rootContainer, root.rootId, rootContainer);
+      hydrationAdopter?.report(root.rootId);
+      syncFocusScopes(rootContainer);
+    },
+    remove(rootId: number): void {
+      const container = rootContainers.get(rootId);
+      container?.parentNode?.removeChild(container);
+      rootContainers.delete(rootId);
+      syncFocusScopes(document.body);
+    },
+  };
+
+  globalThis.__exactDomMirror = registry;
+
+  return {
+    dispose(): void {
+      disposed = true;
+      if (globalThis.__exactDomMirror === registry) {
+        globalThis.__exactDomMirror = undefined;
+      }
+      if (globalThis.__exactDomIdentity === identityRegistry) {
+        globalThis.__exactDomIdentity = previousIdentity;
+      }
+      if (getHostChannelStyleApplier() === channelApplier) {
+        setHostChannelStyleApplier(previousChannelApplier);
+      }
+      for (const container of rootContainers.values()) {
+        container.parentNode?.removeChild(container);
+      }
+      domByViewId.clear();
+      rootContainers.clear();
+    },
+  };
+}
+
+export function installDomMirror(options: DomMirrorOptions = {}): DomMirrorHandle | null {
+  return installDomHost(options, {
+    exposeDevIdentity: true,
+    rootAttribute: 'data-exact-mirror-root',
+  });
+}
+
+export function installContractWebHost(
+  options: ContractWebHostOptions = {},
+): ContractWebHostHandle | null {
+  return installDomHost(options, {
+    exposeDevIdentity: false,
+    rootAttribute: 'data-exact-contract-host-root',
+  });
+}