@ccheever/exact-renderer 0.1.0

package/src/nodes/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Host Node Model - Public Exports
+ *
+ * This module re-exports the host node types and factory functions.
+ */
+
+export {
+  // Types
+  NodeKind,
+  DirtyFlags,
+  type BaseNode,
+  type RootNode,
+  type ElementNode,
+  type TextNode,
+  type HostNode,
+
+  // Factory functions
+  createRootNode,
+  createElementNode,
+  createTextNode,
+
+  // Relationship helpers
+  setParent,
+  appendChild,
+  insertBefore,
+  removeChild,
+  clearChildren,
+  getChildIds,
+
+  // Dirty flag helpers
+  markStyleDirty,
+  markPropsDirty,
+  markEventsDirty,
+  clearDirtyFlags,
+  isDirty,
+  hasDirtyFlag,
+
+  // Internal (for testing)
+  _resetNodeIdCounter,
+  _peekNextNodeId,
+} from './node.js';

package/src/nodes/node.ts

@@ -0,0 +1,531 @@
+/**
+ * Base Node Interface
+ *
+ * This module defines the core node interface used by the reconciler
+ * to represent elements in the host tree. All node types implement
+ * this interface.
+ *
+ * Design Principles:
+ * - Immutable IDs for stable identity
+ * - Clear parent-child relationships
+ * - Explicit dirty flags for efficient updates
+ * - Separation between structural and content mutations
+ */
+
+import type { EventType } from '@exact/core/protocol/opcodes';
+import type { ParagraphSpec } from '@exact/text';
+import type {
+  CanonicalTagType,
+  CanonicalStyle,
+  CanonicalProps,
+  CanonicalTransitionMap,
+  EventBinding,
+  ResolvedDirection,
+  ResolvedSafeAreaState,
+  SafeAreaPropagationState,
+  WritingMode,
+} from '../types.js';
+
+/**
+ * Node type discriminator for type-safe branching.
+ */
+export const NodeKind = {
+  Root: 0,
+  Element: 1,
+  Text: 2,
+} as const;
+
+export type NodeKind = (typeof NodeKind)[keyof typeof NodeKind];
+
+/**
+ * Dirty flags for tracking what needs to be synchronized.
+ * These are bit flags that can be combined.
+ */
+export const DirtyFlags = {
+  None: 0,
+  /** Style properties have changed */
+  Style: 1 << 0,
+  /** Props have changed (text content, image source, etc.) */
+  Props: 1 << 1,
+  /** Children have changed (added, removed, reordered) */
+  Children: 1 << 2,
+  /** Events have changed (handlers added/removed) */
+  Events: 1 << 3,
+  /** Node is newly created and needs full initialization */
+  Created: 1 << 4,
+  /** All flags set - full sync needed */
+  All: (1 << 0) | (1 << 1) | (1 << 2) | (1 << 3) | (1 << 4),
+} as const;
+
+export type DirtyFlags = (typeof DirtyFlags)[keyof typeof DirtyFlags];
+
+/**
+ * Base interface for all host nodes.
+ *
+ * The node hierarchy is:
+ * - RootNode: The container node (ID 0)
+ * - ElementNode: View, Text, Image, etc.
+ * - TextNode: Raw text content (children of Text elements)
+ */
+export interface BaseNode {
+  /**
+   * Discriminator for type-safe branching.
+   */
+  readonly kind: NodeKind;
+
+  /**
+   * Unique numeric ID for this node.
+   * IDs are assigned at creation and never change.
+   * ID 0 is reserved for the root container.
+   */
+  readonly id: number;
+
+  /**
+   * Parent node, or null for the root.
+   */
+  parent: BaseNode | null;
+
+  /**
+   * Dirty flags indicating what needs to be synchronized.
+   */
+  dirtyFlags: DirtyFlags;
+}
+
+/**
+ * Root node - the container for the entire tree.
+ * For single-root apps, id=0. For multi-root, each root gets a unique id.
+ */
+export interface RootNode extends BaseNode {
+  readonly kind: typeof NodeKind.Root;
+  readonly id: number;
+  parent: null;
+
+  /**
+   * The root ID for multi-root support (0 = default single root).
+   */
+  readonly rootId: number;
+
+  /**
+   * Children of the root node.
+   */
+  children: ElementNode[];
+}
+
+/**
+ * Element node - represents a view, text, image, etc.
+ */
+export interface ElementNode extends BaseNode {
+  readonly kind: typeof NodeKind.Element;
+
+  /**
+   * The canonical tag type for this element.
+   */
+  readonly tagType: CanonicalTagType;
+
+  /**
+   * The original tag name as specified in JSX.
+   * Used for debugging and dev tools.
+   */
+  readonly originalTag: string;
+
+  /**
+   * Whether this element uses RN semantics (column default, etc.)
+   */
+  readonly isRNStyle: boolean;
+
+  /**
+   * Current normalized style.
+   */
+  style: CanonicalStyle;
+
+  /**
+   * Resolved inherited direction for this element.
+   */
+  resolvedDirection: ResolvedDirection;
+
+  /**
+   * Resolved inherited writing mode for this element.
+   */
+  resolvedWritingMode: WritingMode;
+
+  /**
+   * Resolved inherited language tag for this element.
+   */
+  resolvedLang: string;
+
+  /**
+   * Current normalized props.
+   */
+  props: CanonicalProps;
+
+  /**
+   * Canonical paragraph lowering for text-like elements.
+   * Non-text elements keep this null.
+   */
+  paragraphSpec: ParagraphSpec | null;
+
+  /**
+   * Stable cache key for the lowered paragraph.
+   * Non-text elements keep this null.
+   */
+  paragraphKey: string | null;
+
+  /**
+   * Current normalized transition metadata.
+   */
+  transitions: CanonicalTransitionMap;
+
+  /**
+   * Safe-area work derived by the renderer. This stays local to JS so
+   * diagnostics and auto-scroll logic can inspect the resolved behavior.
+   */
+  safeAreaState: ResolvedSafeAreaState | null;
+
+  /**
+   * Safe-area context that descendants inherit from this node after any
+   * consumption performed here.
+   */
+  propagatedSafeArea: SafeAreaPropagationState | null;
+
+  /**
+   * Child element nodes.
+   */
+  children: (ElementNode | TextNode)[];
+
+  /**
+   * Event bindings for this element.
+   */
+  events: Map<EventType, EventBinding>;
+
+  /**
+   * Per-node escape hatch for adapters that need press semantics on a tag that
+   * is normally not press-capable. RFC 0043 uses this for DOM-shim click
+   * auto-promotion without mutating the global tag map.
+   */
+  pressOverride?: boolean;
+
+  /**
+   * Original props as passed from React (for diffing).
+   */
+  originalProps: Record<string, unknown>;
+}
+
+/**
+ * Text node - raw text content inside a Text element.
+ */
+export interface TextNode extends BaseNode {
+  readonly kind: typeof NodeKind.Text;
+
+  /**
+   * The text content.
+   */
+  text: string;
+}
+
+/**
+ * Union type for all node types.
+ */
+export type HostNode = RootNode | ElementNode | TextNode;
+
+// =============================================================================
+// Node Factory Functions
+// =============================================================================
+
+/**
+ * Global node ID counter. Starts at 1 because 0 is reserved for root.
+ */
+let nextNodeId = 1;
+
+/**
+ * Reset the node ID counter. Only for testing.
+ * @internal
+ */
+export function _resetNodeIdCounter(): void {
+  nextNodeId = 1;
+}
+
+/**
+ * Get the next node ID without incrementing.
+ * @internal
+ */
+export function _peekNextNodeId(): number {
+  return nextNodeId;
+}
+
+/**
+ * Create a new root node.
+ *
+ * @param rootId - Root ID for multi-root support (default 0 = single root).
+ *   When rootId=0, the node ID is 0 (backwards compatible).
+ *   When rootId>0, a new unique node ID is allocated.
+ */
+export function createRootNode(rootId: number = 0): RootNode {
+  const id = rootId === 0 ? 0 : nextNodeId++;
+  return {
+    kind: NodeKind.Root,
+    id,
+    rootId,
+    parent: null,
+    children: [],
+    dirtyFlags: DirtyFlags.Created,
+  };
+}
+
+/**
+ * Create a new element node.
+ *
+ * @param tagType - The canonical tag type
+ * @param originalTag - The original tag name from JSX
+ * @param isRNStyle - Whether to use RN semantics
+ * @param props - The original props from React
+ */
+export function createElementNode(
+  tagType: CanonicalTagType,
+  originalTag: string,
+  isRNStyle: boolean,
+  props: Record<string, unknown>
+): ElementNode {
+  const id = nextNodeId++;
+  return {
+    kind: NodeKind.Element,
+    id,
+    tagType,
+    originalTag,
+    isRNStyle,
+    parent: null,
+    style: {},
+    resolvedDirection: 'ltr',
+    resolvedWritingMode: 'horizontal-tb',
+    resolvedLang: '',
+    props: {},
+    paragraphSpec: null,
+    paragraphKey: null,
+    transitions: {},
+    safeAreaState: null,
+    propagatedSafeArea: null,
+    children: [],
+    events: new Map(),
+    pressOverride: undefined,
+    originalProps: props,
+    dirtyFlags: DirtyFlags.Created,
+  };
+}
+
+/**
+ * Create a new text node.
+ *
+ * @param text - The text content
+ */
+export function createTextNode(text: string): TextNode {
+  const id = nextNodeId++;
+  return {
+    kind: NodeKind.Text,
+    id,
+    parent: null,
+    text,
+    dirtyFlags: DirtyFlags.Created,
+  };
+}
+
+// =============================================================================
+// Node Relationship Helpers
+// =============================================================================
+
+/**
+ * Set a node's parent and mark children as dirty on the parent.
+ */
+export function setParent(node: ElementNode | TextNode, parent: BaseNode | null): void {
+  node.parent = parent;
+}
+
+/**
+ * Child lookups use plain Array#indexOf below this size (allocation-free).
+ * Above it, a per-parent index map is built lazily so appending n fresh
+ * children is O(n) instead of O(n^2).
+ */
+const CHILD_INDEX_CACHE_THRESHOLD = 64;
+
+/**
+ * Lazily built child -> index caches for large parents. Kept out of the node
+ * shape (WeakMap keyed by parent) so node objects stay plain data and the
+ * cache disappears with the parent. Any mid-array mutation invalidates the
+ * parent's cache; appends of new children extend it in place.
+ */
+const childIndexCaches = new WeakMap<RootNode | ElementNode, Map<ElementNode | TextNode, number>>();
+
+function indexOfChild(parent: RootNode | ElementNode, child: ElementNode | TextNode): number {
+  const children = parent.children;
+  if (children.length < CHILD_INDEX_CACHE_THRESHOLD) {
+    return children.indexOf(child as any);
+  }
+
+  let cache = childIndexCaches.get(parent);
+  if (!cache) {
+    cache = new Map();
+    for (let index = 0; index < children.length; index++) {
+      cache.set(children[index]!, index);
+    }
+    childIndexCaches.set(parent, cache);
+  }
+  return cache.get(child) ?? -1;
+}
+
+function invalidateChildIndexCache(parent: RootNode | ElementNode): void {
+  childIndexCaches.delete(parent);
+}
+
+function extendChildIndexCache(parent: RootNode | ElementNode, child: ElementNode | TextNode): void {
+  const cache = childIndexCaches.get(parent);
+  if (cache) {
+    cache.set(child, parent.children.length - 1);
+  }
+}
+
+/**
+ * Add a child to a parent node.
+ * Returns true if the child was added or moved, false if it was already last.
+ */
+export function appendChild(
+  parent: RootNode | ElementNode,
+  child: ElementNode | TextNode
+): boolean {
+  const existingIndex = indexOfChild(parent, child);
+  if (existingIndex !== -1) {
+    if (existingIndex === parent.children.length - 1) {
+      return false;
+    }
+    parent.children.splice(existingIndex, 1);
+    parent.children.push(child as any);
+    invalidateChildIndexCache(parent);
+    setParent(child, parent);
+    parent.dirtyFlags |= DirtyFlags.Children;
+    return true;
+  }
+
+  // Add the child
+  parent.children.push(child as any);
+  extendChildIndexCache(parent, child);
+  setParent(child, parent);
+  parent.dirtyFlags |= DirtyFlags.Children;
+
+  return true;
+}
+
+/**
+ * Insert a child before another child.
+ * Returns true if inserted, false if before child not found.
+ */
+export function insertBefore(
+  parent: RootNode | ElementNode,
+  child: ElementNode | TextNode,
+  beforeChild: ElementNode | TextNode
+): boolean {
+  const beforeIndex = indexOfChild(parent, beforeChild);
+  if (beforeIndex === -1) {
+    // Before child not found, append instead
+    return appendChild(parent, child);
+  }
+
+  // Remove if already present elsewhere
+  const existingIndex = indexOfChild(parent, child);
+  if (existingIndex !== -1) {
+    parent.children.splice(existingIndex, 1);
+  }
+
+  // Insert before
+  const adjustedIndex = existingIndex !== -1 && existingIndex < beforeIndex
+    ? beforeIndex - 1
+    : beforeIndex;
+  parent.children.splice(adjustedIndex, 0, child as any);
+  invalidateChildIndexCache(parent);
+  setParent(child, parent);
+  parent.dirtyFlags |= DirtyFlags.Children;
+
+  return true;
+}
+
+/**
+ * Remove a child from a parent node.
+ * Returns true if removed, false if not found.
+ */
+export function removeChild(
+  parent: RootNode | ElementNode,
+  child: ElementNode | TextNode
+): boolean {
+  const index = indexOfChild(parent, child);
+  if (index === -1) {
+    return false;
+  }
+
+  parent.children.splice(index, 1);
+  invalidateChildIndexCache(parent);
+  setParent(child, null);
+  parent.dirtyFlags |= DirtyFlags.Children;
+
+  return true;
+}
+
+/**
+ * Clear all children from a node.
+ */
+export function clearChildren(parent: RootNode | ElementNode): void {
+  for (const child of parent.children) {
+    setParent(child, null);
+  }
+  parent.children = [];
+  invalidateChildIndexCache(parent);
+  parent.dirtyFlags |= DirtyFlags.Children;
+}
+
+/**
+ * Get the child IDs for a node.
+ */
+export function getChildIds(parent: RootNode | ElementNode): number[] {
+  return parent.children.map(child => child.id);
+}
+
+// =============================================================================
+// Node Dirty Flag Helpers
+// =============================================================================
+
+/**
+ * Mark a node as having dirty style.
+ */
+export function markStyleDirty(node: ElementNode): void {
+  node.dirtyFlags |= DirtyFlags.Style;
+}
+
+/**
+ * Mark a node as having dirty props.
+ */
+export function markPropsDirty(node: ElementNode | TextNode): void {
+  node.dirtyFlags |= DirtyFlags.Props;
+}
+
+/**
+ * Mark a node as having dirty events.
+ */
+export function markEventsDirty(node: ElementNode): void {
+  node.dirtyFlags |= DirtyFlags.Events;
+}
+
+/**
+ * Clear all dirty flags on a node.
+ */
+export function clearDirtyFlags(node: BaseNode): void {
+  node.dirtyFlags = DirtyFlags.None;
+}
+
+/**
+ * Check if a node has any dirty flags.
+ */
+export function isDirty(node: BaseNode): boolean {
+  return node.dirtyFlags !== DirtyFlags.None;
+}
+
+/**
+ * Check if a node has a specific dirty flag.
+ */
+export function hasDirtyFlag(node: BaseNode, flag: DirtyFlags): boolean {
+  return (node.dirtyFlags & flag) !== 0;
+}

package/src/peer-context.ts

@@ -0,0 +1,100 @@
+/**
+ * Peer state store for Tailwind peer-* modifiers (RFC 0024 Phase 4).
+ *
+ * A view with `className="peer"` writes its interaction state to a ref-based
+ * sibling store. Subsequent sibling views with `peer-hover:*` classes subscribe
+ * to this store via useSyncExternalStore.
+ *
+ * Named peers (`peer/email`) get separate store entries so multiple peers in
+ * the same parent don't conflict.
+ */
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+import type { InteractionState } from './classname-contract.js';
+
+const DEFAULT_INTERACTION: InteractionState = Object.freeze({
+  hovered: false,
+  focused: false,
+  active: false,
+  focusVisible: false,
+});
+
+export interface PeerStore {
+  getState(name: string | null): InteractionState | undefined;
+  setState(name: string | null, state: InteractionState): void;
+  subscribe(callback: () => void): () => void;
+}
+
+/**
+ * Create a PeerStore. Typically held as a ref on the parent component.
+ */
+export function createPeerStore(): PeerStore {
+  const states = new Map<string | null, InteractionState>();
+  const listeners = new Set<() => void>();
+
+  return {
+    getState(name) {
+      return states.get(name);
+    },
+    setState(name, state) {
+      const current = states.get(name);
+      if (
+        current &&
+        current.hovered === state.hovered &&
+        current.focused === state.focused &&
+        current.active === state.active &&
+        current.focusVisible === state.focusVisible
+      ) {
+        return;
+      }
+      states.set(name, state);
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe(callback) {
+      listeners.add(callback);
+      return () => { listeners.delete(callback); };
+    },
+  };
+}
+
+/**
+ * Hook to create and maintain a PeerStore for a parent component.
+ */
+export function usePeerStore(): PeerStore {
+  const ref = useRef<PeerStore | null>(null);
+  if (!ref.current) {
+    ref.current = createPeerStore();
+  }
+  return ref.current;
+}
+
+/**
+ * Hook for a subsequent sibling to subscribe to peer state changes.
+ */
+export function usePeerState(store: PeerStore, name: string | null): InteractionState {
+  const subscribe = useCallback(
+    (callback: () => void) => store.subscribe(callback),
+    [store],
+  );
+  const getSnapshot = useCallback(
+    () => store.getState(name) ?? DEFAULT_INTERACTION,
+    [store, name],
+  );
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+/**
+ * Check if a className string includes "peer" or "peer/{name}".
+ * Returns the peer name (null for unnamed) or undefined if not a peer.
+ */
+const WS_RE = /\s+/;
+
+export function extractPeerName(className: string): string | null | undefined {
+  const tokens = className.split(WS_RE);
+  for (const token of tokens) {
+    if (token === 'peer') return null;
+    if (token.startsWith('peer/')) return token.slice(5);
+  }
+  return undefined;
+}

package/src/primitives.native.ts

@@ -0,0 +1,8 @@
+export {
+  Pressable,
+  List,
+  ScrollView,
+  SelectionGroup,
+  Text,
+  View,
+} from './native-primitives.js';

package/src/primitives.ts

@@ -0,0 +1,8 @@
+export {
+  Pressable,
+  List,
+  ScrollView,
+  SelectionGroup,
+  Text,
+  View,
+} from './components.js';

package/src/props/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Prop Normalization - Public Exports
+ *
+ * This module re-exports the prop normalization utilities.
+ */
+
+export {
+  extractTextContent,
+  extractWebImageSource,
+  extractRNImageSource,
+  extractResizeMode,
+  normalizeProps,
+  propsEqual,
+} from './normalize.js';