@ccheever/exact-renderer 0.1.0

package/src/index.ts

@@ -0,0 +1,278 @@
+// @system @ref LLP 0007 — Renderer-facing behavior primitives
+/**
+ * Exact Renderer
+ *
+ * Main entry point for the Exact React renderer.
+ *
+ * This module provides:
+ * - render/unmount functions for mounting React trees
+ * - Primitive components (web-style and RN-style)
+ * - Type definitions for props and styles
+ *
+ * @example
+ * ```tsx
+ * import React from 'react';
+ * import { render, View, Text, Pressable } from '@exact/runtime';
+ *
+ * function App() {
+ *   const [count, setCount] = React.useState(0);
+ *
+ *   return (
+ *     <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+ *       <Text style={{ fontSize: 24 }}>Count: {count}</Text>
+ *       <Pressable
+ *         style={{ padding: 16, backgroundColor: '#007AFF', borderRadius: 8 }}
+ *         onPress={() => setCount(c => c + 1)}
+ *       >
+ *         <Text style={{ color: '#fff' }}>Increment</Text>
+ *       </Pressable>
+ *     </View>
+ *   );
+ * }
+ *
+ * render(<App />);
+ * ```
+ */
+
+import './jsx-augmentations.js';
+
+// =============================================================================
+// Render Functions
+// =============================================================================
+
+export {
+  render,
+  unmount,
+  forceUpdate,
+  syncWindowState,
+  reset,
+  createExactRoot,
+  prepareForBundleReplacement,
+} from './reconciler.js';
+export type { ExactRoot } from './reconciler.js';
+// Keep the root barrel native-safe. Optional DOM/framework adapters belong on
+// explicit subpaths so native startup does not eagerly import them.
+export type { ExactDOMHandle } from './dom-shim.js';
+
+// =============================================================================
+// Web-Style Components
+// =============================================================================
+
+export {
+  div,
+  span,
+  text,
+  img,
+  input,
+  button,
+  toggle,
+} from './components.js';
+
+// =============================================================================
+// React Native-Style Components
+// =============================================================================
+
+export {
+  View,
+  Text,
+  Image,
+  Svg,
+  SelectionGroup,
+  List,
+  ScrollView,
+  TextInput,
+  Pressable,
+  Toggle,
+  Switch,
+} from './components.js';
+export {
+  createNativeViewComponent,
+} from './native-view.js';
+
+// =============================================================================
+// Style Types
+// =============================================================================
+
+export type {
+  // Style types
+  ViewStyle,
+  FullStyle,
+  FlexStyle,
+  LayoutStyle,
+  SpacingStyle,
+  PositionStyle,
+  AppearanceStyle,
+  TransformStyle,
+  TransitionStyle,
+  TextStyle,
+  TransitionPropertyName,
+  TransitionPhase,
+  TransitionEasingName,
+  CubicBezierEasing,
+  TransitionEasing,
+  TimingTransition,
+  SpringTransition,
+  NoneTransition,
+  TransitionConfig,
+  TransitionMap,
+  StyleTransition,
+
+  // Dimension types
+  DimensionValue,
+  DimensionInput,
+
+  // Flexbox types
+  FlexDirection,
+  FlexWrap,
+  JustifyContent,
+  AlignItems,
+  AlignSelf,
+  AlignContent,
+
+  // Other types
+  PositionType,
+  Overflow,
+  Display,
+  SafeAreaEdge,
+  SafeAreaEdgeMode,
+  SafeAreaInsetProp,
+  SafeAreaProp,
+  SafeAreaRegionSet,
+  FontWeight,
+  FontStyle,
+  TextAlign,
+  EllipsizeMode,
+  SelectableMode,
+  NativeViewSelectionTier,
+  NativeViewSelectionGesturePolicy,
+  ResizeMode,
+  ImageColorScheme,
+  ImageCandidate,
+  ImageThemeTreatment,
+  ColorSchemeImageSource,
+  ImagePlaceholder,
+  ImageLoading,
+  ImageObjectFit,
+  ImageSource,
+  SvgSource,
+} from './types.js';
+
+// =============================================================================
+// Component Prop Types
+// =============================================================================
+
+export type {
+  // Base props
+  BaseProps,
+  ContainerProps,
+  TextElementProps,
+  ImageElementProps,
+  RNImageProps,
+  SvgProps,
+  PressableElementProps,
+  ScrollContainerProps,
+  TextInputProps,
+  ToggleProps,
+
+  // Event types
+  PressEvent,
+  ScrollEvent,
+  ChangeEvent,
+  ToggleChangeEvent,
+  TransitionEndEvent,
+} from './types.js';
+
+// =============================================================================
+// Internal/Advanced Exports
+// =============================================================================
+//
+// These exports are intended for advanced usage, testing, or building custom
+// renderers. They are not part of the stable public API and may change.
+//
+// =============================================================================
+
+/**
+ * Internal types for custom renderer implementations.
+ * @internal
+ */
+export type {
+  RGBAColor,
+  CanonicalStyle,
+  CanonicalProps,
+  CanonicalTagType,
+  WebTagType,
+  RNTagType,
+  TagType,
+} from './types.js';
+export type {
+  NativeViewComponentProps,
+  NativeViewRuntimeDef,
+  NativeViewSelectionDef,
+} from './native-view.js';
+
+/**
+ * Style utilities for parsing and normalizing styles.
+ * @internal
+ */
+export { parseColor, isValidColor, colorToHex, colorToRgba } from './style/index.js';
+export {
+  normalizeStyle,
+  normalizeTransition,
+  stylesEqual,
+  transitionsEqual,
+  parseDimension,
+  parseFontWeight,
+} from './style/index.js';
+
+/**
+ * Props utilities for normalizing component props.
+ * @internal
+ */
+export { normalizeProps, propsEqual, extractTextContent } from './props/index.js';
+
+export {
+  CSSVariableProvider,
+  useCSSVariables,
+  extractCSSVariables,
+} from './css-variable-context.js';
+export type { CSSVariableMap } from './css-variable-context.js';
+
+export {
+  GroupStateProvider,
+  useGroupStates,
+  extractGroupName,
+} from './group-context.js';
+
+export {
+  createPeerStore,
+  usePeerStore,
+  usePeerState,
+  extractPeerName,
+} from './peer-context.js';
+export type { PeerStore } from './peer-context.js';
+export type {
+  ExactAdapterHostOps,
+  ExactAdapterOps,
+  ExactAdapterRoot,
+} from './adapter-contract.js';
+export type { ExactSvelteRoot } from './svelte.js';
+
+/**
+ * Tag configuration utilities.
+ * @internal
+ */
+export { getTagConfig, isValidTag, isWebTag, isRNTag } from './tags/index.js';
+
+/**
+ * Internal debugging utilities.
+ * These are prefixed with underscore and should not be used in production code.
+ * @internal
+ */
+export {
+  _getRootContainer,
+  _isRendering,
+  _getEventQueueLength,
+} from './reconciler.js';
+
+export { _getEncoder, _clearHandlers, getHandler } from './host-config.js';
+export { NodeKind, _resetNodeIdCounter } from './nodes/index.js';

package/src/inspector-runtime.ts

@@ -0,0 +1,244 @@
+import type {
+  AgentEvent,
+  ElementRef,
+  ElementRefInfo,
+  Frame,
+  Point,
+  RootInfo,
+  ViewNode,
+} from '@exact/core/agent/types';
+import {
+  recordCommitTimestamp,
+  resetAgentInteractionStateTracking,
+} from '@exact/core/agent/interaction-state';
+
+import type { ElementNode, HostNode, RootNode } from './nodes/node.js';
+import { NodeKind } from './nodes/node.js';
+import { getScreenDimensions } from './protocol/index.js';
+
+type InspectorListener = (event: AgentEvent) => void;
+type CommitAnalyzer = (root: RootNode) => void;
+type ResetHook = () => void;
+
+interface SnapshotRecord {
+  snapshotId: string;
+  rootId: number;
+  stateVersion: number;
+  timestamp: number;
+  frameCount: number;
+  refs: Record<ElementRef, ElementRefInfo>;
+  tree?: ViewNode;
+}
+
+interface SharedInspectorState {
+  roots: Map<number, RootNode>;
+  listeners: Set<InspectorListener>;
+  snapshots: Map<string, SnapshotRecord>;
+  snapshotOrder: string[];
+  textOverrides: Map<number, string>;
+  toggleOverrides: Map<number, boolean>;
+  valueOverrides: Map<number, unknown>;
+  scrollOffsets: Map<number, Point>;
+  snapshotCounter: number;
+  stateVersion: number;
+  frameCount: number;
+  lastCommitAt: number;
+}
+
+type InspectorGlobal = typeof globalThis & {
+  __exactRendererInspectorState?: SharedInspectorState;
+  __exactRendererCommitAnalyzers?: Set<CommitAnalyzer>;
+  __exactRendererInspectorResetHooks?: Set<ResetHook>;
+};
+
+function inspectorGlobal(): InspectorGlobal {
+  return globalThis as InspectorGlobal;
+}
+
+function getSharedInspectorState(): SharedInspectorState {
+  const scope = inspectorGlobal();
+  if (scope.__exactRendererInspectorState) {
+    return scope.__exactRendererInspectorState;
+  }
+
+  const state: SharedInspectorState = {
+    roots: new Map<number, RootNode>(),
+    listeners: new Set<InspectorListener>(),
+    snapshots: new Map<string, SnapshotRecord>(),
+    snapshotOrder: [],
+    textOverrides: new Map<number, string>(),
+    toggleOverrides: new Map<number, boolean>(),
+    valueOverrides: new Map<number, unknown>(),
+    scrollOffsets: new Map<number, Point>(),
+    snapshotCounter: 0,
+    stateVersion: 0,
+    frameCount: 0,
+    lastCommitAt: 0,
+  };
+  scope.__exactRendererInspectorState = state;
+  return state;
+}
+
+const sharedState = getSharedInspectorState();
+const roots = sharedState.roots;
+const listeners = sharedState.listeners;
+const snapshots = sharedState.snapshots;
+const snapshotOrder = sharedState.snapshotOrder;
+const textOverrides = sharedState.textOverrides;
+const toggleOverrides = sharedState.toggleOverrides;
+const valueOverrides = sharedState.valueOverrides;
+const scrollOffsets = sharedState.scrollOffsets;
+
+function currentTimestamp(): number {
+  return Date.now();
+}
+
+function makeRootInfo(root: RootNode): RootInfo {
+  const { width, height } = getScreenDimensions(root.rootId);
+  return {
+    rootId: root.rootId,
+    label: root.rootId === 0 ? 'Main' : `Root ${root.rootId}`,
+    size: {
+      width,
+      height,
+    },
+  };
+}
+
+function emit(event: AgentEvent): void {
+  for (const listener of listeners) {
+    try {
+      listener(event);
+    } catch (error) {
+      console.error('[RendererInspector] listener failed:', error);
+    }
+  }
+}
+
+function collectChangedViews(root: RootNode): number[] {
+  const collected: number[] = [];
+  const collect = (node: HostNode): void => {
+    collected.push(node.id);
+    if (node.kind === NodeKind.Element || node.kind === NodeKind.Root) {
+      for (const child of node.children) {
+        collect(child);
+      }
+    }
+  };
+
+  collect(root);
+  return collected;
+}
+
+function commitAnalyzers(): Set<CommitAnalyzer> {
+  const scope = inspectorGlobal();
+  if (!scope.__exactRendererCommitAnalyzers) {
+    scope.__exactRendererCommitAnalyzers = new Set<CommitAnalyzer>();
+  }
+  return scope.__exactRendererCommitAnalyzers;
+}
+
+function resetHooks(): Set<ResetHook> {
+  const scope = inspectorGlobal();
+  if (!scope.__exactRendererInspectorResetHooks) {
+    scope.__exactRendererInspectorResetHooks = new Set<ResetHook>();
+  }
+  return scope.__exactRendererInspectorResetHooks;
+}
+
+export function registerInspectorCommitAnalyzer(analyzer: CommitAnalyzer): () => void {
+  const analyzers = commitAnalyzers();
+  analyzers.add(analyzer);
+  return () => {
+    analyzers.delete(analyzer);
+  };
+}
+
+export function registerInspectorResetHook(hook: ResetHook): () => void {
+  const hooks = resetHooks();
+  hooks.add(hook);
+  return () => {
+    hooks.delete(hook);
+  };
+}
+
+export function registerRoot(root: RootNode): void {
+  roots.set(root.rootId, root);
+  sharedState.stateVersion += 1;
+  const rootInfo = makeRootInfo(root);
+  emit({
+    type: 'connect',
+    rootId: root.rootId,
+    label: rootInfo.label,
+    size: rootInfo.size,
+  });
+}
+
+export function unregisterRoot(rootId: number): void {
+  if (!roots.delete(rootId)) {
+    return;
+  }
+  sharedState.stateVersion += 1;
+  emit({
+    type: 'disconnect',
+    reason: `root:${rootId}:unregistered`,
+    exitCode: null,
+    signal: null,
+  });
+}
+
+export function notifyCommit(
+  root: RootNode,
+  options: {
+    changedViews?: Iterable<number>;
+    analyzeWarnings?: boolean;
+  } = {},
+): void {
+  roots.set(root.rootId, root);
+  sharedState.frameCount += 1;
+  sharedState.stateVersion += 1;
+  sharedState.lastCommitAt = currentTimestamp();
+  recordCommitTimestamp(sharedState.lastCommitAt);
+
+  if (options.analyzeWarnings !== false) {
+    for (const analyzer of commitAnalyzers()) {
+      analyzer(root);
+    }
+  }
+
+  if (listeners.size === 0) {
+    return;
+  }
+
+  emit({
+    type: 'render',
+    frameCount: sharedState.frameCount,
+    changedViews:
+      options.changedViews !== undefined
+        ? Array.from(options.changedViews)
+        : collectChangedViews(root),
+  });
+}
+
+export function _resetInspectorState(): void {
+  roots.clear();
+  listeners.clear();
+  snapshots.clear();
+  snapshotOrder.length = 0;
+  resetAgentInteractionStateTracking();
+  for (const hook of resetHooks()) {
+    try {
+      hook();
+    } catch (error) {
+      console.error('[RendererInspector] reset hook failed:', error);
+    }
+  }
+  textOverrides.clear();
+  toggleOverrides.clear();
+  valueOverrides.clear();
+  scrollOffsets.clear();
+  sharedState.snapshotCounter = 0;
+  sharedState.stateVersion = 0;
+  sharedState.frameCount = 0;
+  sharedState.lastCommitAt = 0;
+}