@mmapp/player-core 0.1.0-alpha.1

package/src/testing/nrt-types.ts

@@ -0,0 +1,230 @@
+/**
+ * NRT (Normalized Render Trace) — platform-agnostic representation of rendered UI.
+ *
+ * NRT captures the semantic structure of a rendered workflow view,
+ * abstracting away platform-specific rendering details. This enables:
+ *
+ * 1. Cross-platform testing (browser, iOS, terminal all produce same NRT)
+ * 2. Visual regression detection without screenshots
+ * 3. Accessibility auditing (every visible element has semantic info)
+ * 4. LLM-based test generation (structured, predictable format)
+ *
+ * Usage:
+ *   const nrt = exportNRT(renderedTree);
+ *   expect(nrt.root.children).toHaveLength(3);
+ *   expect(findNode(nrt, 'submit-button').events?.click.target.transition).toBe('submit');
+ */
+
+// =============================================================================
+// Core Types
+// =============================================================================
+
+/**
+ * A complete Normalized Render Trace snapshot.
+ */
+export interface NRT {
+  /** NRT format version. */
+  version: 1;
+  /** The root node of the rendered tree. */
+  root: NRTNode;
+  /** Currently focused element ID (if applicable). */
+  focus?: string;
+  /** Navigation state (if router workflow is active). */
+  nav?: NRTNavState;
+  /** Timestamp of the snapshot. */
+  timestamp?: string;
+  /** Workflow state at time of capture. */
+  workflowState?: string;
+  /** Instance ID if bound to a specific instance. */
+  instanceId?: string;
+}
+
+/**
+ * A single node in the NRT tree.
+ */
+export interface NRTNode {
+  /** Unique ID within the tree. */
+  id: string;
+  /** Component type (e.g., 'Stack', 'Button', 'Text', 'TextInput'). */
+  type: string;
+  /** Text content (for text-bearing elements). */
+  text?: string;
+  /** Current value (for input elements). */
+  value?: unknown;
+  /** Whether this node is visible. */
+  visible: boolean;
+  /** Whether this node is enabled/interactive. */
+  enabled?: boolean;
+  /** Whether this node has focus. */
+  focused?: boolean;
+  /** Semantic role (for accessibility). */
+  role?: string;
+  /** Accessibility label. */
+  label?: string;
+  /** Key-value props that affect behavior (not styling). */
+  props?: Record<string, unknown>;
+  /** Interactive events this node can receive. */
+  events?: Record<string, NRTEvent>;
+  /** Child nodes. */
+  children: NRTNode[];
+  /** Data binding expression (if bound to workflow data). */
+  binding?: string;
+  /** Condition that controls visibility. */
+  visibleWhen?: string;
+}
+
+/**
+ * An interactive event on an NRT node.
+ */
+export interface NRTEvent {
+  /** What kind of action this event triggers. */
+  kind: 'transition' | 'mutation' | 'navigation' | 'custom';
+  /** Target workflow operation. */
+  target: NRTEventTarget;
+}
+
+/**
+ * Target of an NRT event.
+ */
+export interface NRTEventTarget {
+  /** Workflow slug. */
+  workflow?: string;
+  /** Transition name to fire. */
+  transition?: string;
+  /** Mutation type (create, update, delete). */
+  mutation?: string;
+  /** Navigation path. */
+  path?: string;
+  /** Custom handler name. */
+  handler?: string;
+}
+
+/**
+ * Navigation state for router-bound NRT.
+ */
+export interface NRTNavState {
+  /** Current route state name. */
+  routeState: string;
+  /** Current URL path. */
+  path: string;
+  /** Route parameters. */
+  params: Record<string, string>;
+}
+
+// =============================================================================
+// Comparison Types
+// =============================================================================
+
+/**
+ * Result of comparing two NRT snapshots.
+ */
+export interface NRTDiff {
+  /** Whether the two snapshots are semantically equivalent. */
+  equal: boolean;
+  /** List of differences found. */
+  changes: NRTChange[];
+}
+
+/**
+ * A single difference between two NRT snapshots.
+ */
+export interface NRTChange {
+  /** Type of change. */
+  type: 'added' | 'removed' | 'modified';
+  /** Path to the changed node (e.g., 'root.children[0].children[1]'). */
+  path: string;
+  /** Node ID if available. */
+  nodeId?: string;
+  /** What changed. */
+  field: string;
+  /** Previous value (for modified/removed). */
+  oldValue?: unknown;
+  /** New value (for modified/added). */
+  newValue?: unknown;
+}
+
+// =============================================================================
+// Utilities
+// =============================================================================
+
+/**
+ * Creates an empty NRT snapshot.
+ */
+export function createEmptyNRT(): NRT {
+  return {
+    version: 1,
+    root: {
+      id: 'root',
+      type: 'Root',
+      visible: true,
+      children: [],
+    },
+  };
+}
+
+/**
+ * Finds a node by ID in the NRT tree.
+ */
+export function findNode(nrt: NRT, nodeId: string): NRTNode | undefined {
+  return findNodeRecursive(nrt.root, nodeId);
+}
+
+function findNodeRecursive(node: NRTNode, nodeId: string): NRTNode | undefined {
+  if (node.id === nodeId) return node;
+  for (const child of node.children) {
+    const found = findNodeRecursive(child, nodeId);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+/**
+ * Finds all visible nodes in the NRT tree.
+ */
+export function findVisibleNodes(nrt: NRT): NRTNode[] {
+  const result: NRTNode[] = [];
+  collectVisible(nrt.root, result);
+  return result;
+}
+
+function collectVisible(node: NRTNode, result: NRTNode[]): void {
+  if (node.visible) {
+    result.push(node);
+    for (const child of node.children) {
+      collectVisible(child, result);
+    }
+  }
+}
+
+/**
+ * Finds all interactive nodes (nodes with events) in the NRT tree.
+ */
+export function findInteractiveNodes(nrt: NRT): NRTNode[] {
+  const result: NRTNode[] = [];
+  collectInteractive(nrt.root, result);
+  return result;
+}
+
+function collectInteractive(node: NRTNode, result: NRTNode[]): void {
+  if (node.events && Object.keys(node.events).length > 0) {
+    result.push(node);
+  }
+  for (const child of node.children) {
+    collectInteractive(child, result);
+  }
+}
+
+/**
+ * Counts total nodes in the NRT tree.
+ */
+export function countNodes(nrt: NRT): number {
+  return countNodesRecursive(nrt.root);
+}
+
+function countNodesRecursive(node: NRTNode): number {
+  let count = 1;
+  for (const child of node.children) {
+    count += countNodesRecursive(child);
+  }
+  return count;
+}