@ccheever/exact-renderer 0.1.0

package/src/protocol/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Protocol Encoding - Public Exports
+ *
+ * This module re-exports the protocol encoding utilities.
+ */
+
+export type { ProtocolEncoder } from './encoder.js';
+export {
+  createProtocolEncoder,
+  setStyle,
+  setTransform,
+  setOpacity,
+  setBackgroundColor,
+  setTransition,
+  setTextContent,
+  setLang,
+  setImageSource,
+  setPlaceholder,
+  setAccessibilityLabel,
+  setToggleValue,
+  setGlassEffect,
+  setTintColor,
+  setDisabled,
+  setShowsScrollIndicator,
+  dispatchProtocol,
+  getScreenDimensions,
+  encodeCreateElement,
+  encodeCreateText,
+  encodeProps,
+  encodeEvents,
+  encodeChildren,
+  encodeDestroy,
+} from './encoder.js';

package/src/reconciler.ts

@@ -0,0 +1,581 @@
+// @system @ref LLP 0007 — React reconciler surface for Exact
+/**
+ * Exact React Reconciler
+ *
+ * This module provides the public API for rendering React elements
+ * to the Exact runtime. It wraps the react-reconciler with our
+ * custom host config.
+ *
+ * Public API:
+ * - render(element): Render a React element tree
+ * - unmount(): Unmount the current tree
+ *
+ * Event Dispatch:
+ * - Events from native are dispatched through __exactDispatchEvent (in host-ops.ts)
+ * - Each framework's reactivity handles updates
+ */
+
+// @ts-ignore - react-reconciler types don't exactly match runtime
+import Reconciler from 'react-reconciler';
+import type { ReactElement } from 'react';
+
+import {
+  __setActiveWindowRenderer,
+  subscribeToRootWindowState,
+  type Unsubscribe,
+} from '@exact/core/window-state';
+import { hostConfig, _clearHandlers } from './host-config.js';
+import {
+  createRoot,
+  destroyRoot,
+  renderErrorFallback,
+  setNativeEventBatcher,
+  syncRootInheritedWindowState,
+  syncRootWindowState,
+  unregisterInspectorRoot,
+  type RootNode,
+} from './host-ops.js';
+import { _resetInspectorState } from './inspector-runtime.js';
+import { _resetNativeViewEventBridgeForTests } from './native-view-events.js';
+import { _resetNodeIdCounter } from './nodes/index.js';
+
+/**
+ * Development mode flag - gate verbose logging.
+ */
+const __DEV__ = process.env.NODE_ENV !== 'production';
+
+// =============================================================================
+// Create Reconciler
+// =============================================================================
+
+/**
+ * Create the React reconciler with our host config.
+ */
+const reconciler = Reconciler(hostConfig);
+type ReconcilerWithSyncInternals = typeof reconciler & {
+  updateContainerSync?: (
+    element: ReactElement | null,
+    fiber: unknown,
+    parentComponent: unknown,
+    callback: () => void,
+  ) => void;
+  flushSyncWork?: () => void;
+  batchedUpdates?: (callback: () => void) => void;
+};
+const reconcilerWithSyncInternals = reconciler as ReconcilerWithSyncInternals;
+if (typeof reconcilerWithSyncInternals.batchedUpdates === 'function') {
+  setNativeEventBatcher((callback) => {
+    reconcilerWithSyncInternals.batchedUpdates!(callback);
+  });
+}
+
+// =============================================================================
+// Root State
+// =============================================================================
+
+/**
+ * The root container node.
+ */
+let rootContainer: RootNode | null = null;
+
+/**
+ * The fiber root for React.
+ */
+let rootFiber: unknown = null;
+
+/**
+ * The currently rendered element (for explicit forceUpdate() replays).
+ */
+let currentElement: ReactElement | null = null;
+let rootWindowStateUnsubscribe: Unsubscribe | null = null;
+
+type RendererDebugState = Partial<{
+  enteredRender: boolean;
+  createdRoot: boolean;
+  updateScheduled: boolean;
+  renderError: string | null;
+}>;
+
+const rendererDebugScope = globalThis as typeof globalThis & {
+  __exactRendererDebugState?: RendererDebugState;
+};
+
+function recordRendererDebugState(patch: RendererDebugState): void {
+  Object.assign(rendererDebugScope.__exactRendererDebugState ??= {}, patch);
+}
+
+// =============================================================================
+// Render State Management
+// =============================================================================
+
+/**
+ * Whether we're currently in the middle of a render.
+ */
+let isRendering = false;
+
+function updateContainerSyncIfAvailable(
+  element: ReactElement | null,
+  fiber: unknown,
+  onComplete: () => void,
+): boolean {
+  if (typeof reconcilerWithSyncInternals.updateContainerSync !== 'function') {
+    return false;
+  }
+
+  reconcilerWithSyncInternals.updateContainerSync(element, fiber, null, onComplete);
+  if (typeof reconcilerWithSyncInternals.flushSyncWork === 'function') {
+    reconcilerWithSyncInternals.flushSyncWork();
+  }
+  return true;
+}
+
+function performContainerUpdate(
+  element: ReactElement | null,
+  fiber: unknown,
+  onComplete: () => void,
+): void {
+  if (updateContainerSyncIfAvailable(element, fiber, onComplete)) {
+    return;
+  }
+
+  if (typeof reconciler.flushSync === 'function') {
+    reconciler.flushSync(() => {
+      reconciler.updateContainer(element, fiber, null, onComplete);
+    });
+    return;
+  }
+
+  reconciler.updateContainer(element, fiber, null, onComplete);
+}
+
+function formatRenderErrorMessage(error: unknown): string {
+  if (__DEV__ && error instanceof Error && error.message) {
+    return `Render error: ${error.message}`;
+  }
+
+  return 'Something went wrong.';
+}
+
+function handleRenderFailure(
+  label: string,
+  container: RootNode | null,
+  clearCurrentElement: () => void,
+  error: unknown
+): void {
+  clearCurrentElement();
+  console.error(`[${label}] Render failed:`, error);
+
+  if (!container) {
+    return;
+  }
+
+  try {
+    renderErrorFallback(container, formatRenderErrorMessage(error));
+  } catch (fallbackError) {
+    console.error(`[${label}] Fallback render failed:`, fallbackError);
+  }
+}
+
+// =============================================================================
+// Event Handling
+// =============================================================================
+
+// Note: Event dispatch is handled in host-ops.ts via __exactDispatchEvent.
+// React state updates should flush through hostConfig.resetAfterCommit().
+
+/**
+ * Trigger an explicit re-render of the current tree.
+ * This is only used for manual forceUpdate() calls and explicit remounts.
+ */
+function triggerRerender(): void {
+  if (!rootFiber || !currentElement) {
+    return;
+  }
+
+  if (isRendering) {
+    return;
+  }
+
+  isRendering = true;
+
+  try {
+    performContainerUpdate(currentElement, rootFiber, () => {
+      isRendering = false;
+    });
+  } catch (error) {
+    isRendering = false;
+    handleRenderFailure('Reconciler', rootContainer, () => {
+      currentElement = null;
+    }, error);
+  }
+}
+
+function subscribeMainRootWindowState(): void {
+  rootWindowStateUnsubscribe?.();
+  if (!rootContainer) {
+    rootWindowStateUnsubscribe = null;
+    return;
+  }
+
+  rootWindowStateUnsubscribe = subscribeToRootWindowState(rootContainer.rootId, () => {
+    if (!rootFiber || !currentElement || isRendering) {
+      if (rootContainer) {
+        syncRootWindowState(rootContainer);
+      }
+      return;
+    }
+
+    syncRootInheritedWindowState(rootContainer);
+  });
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Render a React element tree to the Exact runtime.
+ *
+ * @param element - The React element to render
+ *
+ * @example
+ * ```tsx
+ * import { render } from '@exact/runtime';
+ *
+ * function App() {
+ *   return <div style={{ flex: 1, backgroundColor: '#fff' }}>Hello Exact!</div>;
+ * }
+ *
+ * render(<App />);
+ * ```
+ */
+export function render(element: ReactElement): void {
+  if ((globalThis as any).__exactLoadTimings) (globalThis as any).__exactLoadTimings.renderNativeStart = Date.now();
+  recordRendererDebugState({
+    enteredRender: true,
+    renderError: null,
+  });
+  __setActiveWindowRenderer('react');
+  // Create root container if needed
+  if (!rootContainer) {
+    // Use shared createRoot from host-ops (creates node and registers with native)
+    rootContainer = createRoot(0, 'react');
+    recordRendererDebugState({
+      createdRoot: true,
+    });
+    subscribeMainRootWindowState();
+
+    // @ts-expect-error - createContainer args vary by react-reconciler version
+    rootFiber = reconciler.createContainer(
+      rootContainer,
+      1,      // LegacyRoot (sync rendering) - ConcurrentRoot (0) doesn't work in JSC
+      null,   // hydrationCallbacks
+      false,  // isStrictMode
+      false,  // concurrentUpdatesByDefaultOverride
+      '',     // identifierPrefix
+      (error: Error) => console.error('[Reconciler] Recoverable error:', error),
+      null    // transitionCallbacks
+    );
+  }
+
+  // Store the current element so forceUpdate() can replay it if needed.
+  currentElement = element;
+
+  isRendering = true;
+
+  try {
+    performContainerUpdate(element, rootFiber, () => {
+      isRendering = false;
+    });
+    recordRendererDebugState({
+      updateScheduled: true,
+    });
+  } catch (error) {
+    isRendering = false;
+    recordRendererDebugState({
+      renderError: error instanceof Error ? error.message : String(error),
+    });
+    handleRenderFailure('Reconciler', rootContainer, () => {
+      currentElement = null;
+    }, error);
+  }
+  if ((globalThis as any).__exactLoadTimings) (globalThis as any).__exactLoadTimings.renderNativeEnd = Date.now();
+}
+
+/**
+ * Unmount the current React tree.
+ *
+ * @example
+ * ```tsx
+ * import { render, unmount } from '@exact/runtime';
+ *
+ * render(<App />);
+ *
+ * // Later...
+ * unmount();
+ * ```
+ */
+export function unmount(): void {
+  if (rootFiber) {
+    performContainerUpdate(null, rootFiber, () => {});
+    currentElement = null;
+  }
+}
+
+/**
+ * Fully reset the renderer state.
+ * Clears the root container, fiber, event handlers, and event queue.
+ * Use this for tests or multi-root scenarios that need a clean slate.
+ *
+ * @example
+ * ```tsx
+ * import { render, reset } from '@exact/runtime';
+ *
+ * // Render an app
+ * render(<App />);
+ *
+ * // Reset everything for a fresh start
+ * reset();
+ *
+ * // Render a different app
+ * render(<OtherApp />);
+ * ```
+ */
+export function reset(): void {
+  // Unmount current tree if any
+  if (rootFiber) {
+    performContainerUpdate(null, rootFiber, () => {});
+  }
+  for (const [rootId, instance] of rootInstances) {
+    performContainerUpdate(null, instance.fiber, () => {});
+    instance.unsubscribeWindowState?.();
+    destroyRoot(rootId);
+  }
+  rootInstances.clear();
+
+  // Clear all state
+  if (rootContainer) {
+    destroyRoot(rootContainer.rootId);
+  }
+  rootContainer = null;
+  rootFiber = null;
+  currentElement = null;
+  isRendering = false;
+  rootWindowStateUnsubscribe?.();
+  rootWindowStateUnsubscribe = null;
+
+  // Clear handler registry (in host-ops)
+  _clearHandlers();
+}
+
+/**
+ * Reset the renderer for native bundle replacement without dispatching a
+ * teardown batch to the host.
+ *
+ * The native shell already resets the kernel as part of bundle replacement, so
+ * sending destroy operations from the old JS app is both redundant and risky:
+ * those stale teardown batches can race with the new bundle's initial mount and
+ * leave the fresh kernel tree empty. This path intentionally clears only the
+ * JS-side renderer state.
+ */
+export function prepareForBundleReplacement(): void {
+  for (const instance of rootInstances.values()) {
+    instance.unsubscribeWindowState?.();
+    unregisterInspectorRoot(instance.container.rootId);
+  }
+  rootInstances.clear();
+
+  if (rootContainer) {
+    unregisterInspectorRoot(rootContainer.rootId);
+  }
+
+  rootContainer = null;
+  rootFiber = null;
+  currentElement = null;
+  isRendering = false;
+  rootWindowStateUnsubscribe?.();
+  rootWindowStateUnsubscribe = null;
+
+  _clearHandlers();
+  _resetNativeViewEventBridgeForTests();
+  _resetInspectorState();
+  _resetNodeIdCounter();
+}
+
+/**
+ * Force a re-render of the current element.
+ * Useful for debugging or when external state changes.
+ */
+export function forceUpdate(): void {
+  if (currentElement) {
+    triggerRerender();
+  }
+}
+
+/**
+ * Re-sync viewport/safe-area dependent host state without relying on a React
+ * replay. This is useful when window metrics changed outside the framework's
+ * reactive graph but the mounted tree still needs its inherited layout state
+ * recomputed immediately.
+ */
+export function syncWindowState(rootId?: number): void {
+  if ((rootId === undefined || rootId === 0) && rootContainer) {
+    syncRootInheritedWindowState(rootContainer);
+  }
+
+  for (const [instanceRootId, instance] of rootInstances) {
+    if (instanceRootId === 0) {
+      continue;
+    }
+    if (rootId !== undefined && instanceRootId !== rootId) {
+      continue;
+    }
+    syncRootInheritedWindowState(instance.container);
+  }
+}
+
+/**
+ * Get the current root container (for debugging).
+ * @internal
+ */
+export function _getRootContainer(): RootNode | null {
+  return rootContainer;
+}
+
+/**
+ * Check if a render is in progress.
+ * @internal
+ */
+export function _isRendering(): boolean {
+  return isRendering;
+}
+
+/**
+ * Get the event queue length (for debugging).
+ * @internal
+ * @deprecated Event queue removed - events handled immediately via host-ops
+ */
+export function _getEventQueueLength(): number {
+  return 0;
+}
+
+// =============================================================================
+// Multi-Root API
+// =============================================================================
+
+/**
+ * Per-root state for multi-root support.
+ */
+interface RootInstance {
+  container: RootNode;
+  fiber: unknown;
+  element: ReactElement | null;
+  isRendering: boolean;
+  unsubscribeWindowState: Unsubscribe | null;
+}
+
+const rootInstances = new Map<number, RootInstance>();
+
+/**
+ * An independent rendering surface.
+ * Each ExactRoot has its own React tree, container, and render cycle.
+ */
+export interface ExactRoot {
+  /** The root ID for this rendering surface. */
+  readonly rootId: number;
+
+  /** Render a React element tree into this root. */
+  render(element: ReactElement): void;
+
+  /** Unmount the React tree from this root. */
+  unmount(): void;
+}
+
+/**
+ * Create an independent rendering surface with its own React tree.
+ *
+ * @param rootId - A unique identifier for this root (must be > 0)
+ * @returns An ExactRoot object with render() and unmount() methods
+ *
+ * @example
+ * ```tsx
+ * import { createExactRoot } from '@exact/runtime';
+ *
+ * const root1 = createExactRoot(1);
+ * const root2 = createExactRoot(2);
+ *
+ * root1.render(<Sidebar />);
+ * root2.render(<MainContent />);
+ * ```
+ */
+export function createExactRoot(rootId: number): ExactRoot {
+  __setActiveWindowRenderer('react');
+  if (rootId === 0) {
+    throw new Error('createExactRoot: rootId must be > 0. Use render() for the default root.');
+  }
+  if (rootInstances.has(rootId)) {
+    throw new Error(`createExactRoot: rootId ${rootId} is already in use.`);
+  }
+
+  const container = createRoot(rootId, 'react');
+
+  // @ts-expect-error - createContainer args vary by react-reconciler version
+  const fiber = reconciler.createContainer(
+    container,
+    1,      // LegacyRoot (sync rendering)
+    null,   // hydrationCallbacks
+    false,  // isStrictMode
+    false,  // concurrentUpdatesByDefaultOverride
+    '',     // identifierPrefix
+    (error: Error) => console.error(`[Reconciler:${rootId}] Recoverable error:`, error),
+    null    // transitionCallbacks
+  );
+
+  const instance: RootInstance = {
+    container,
+    fiber,
+    element: null,
+    isRendering: false,
+    unsubscribeWindowState: null,
+  };
+
+  instance.unsubscribeWindowState = subscribeToRootWindowState(rootId, () => {
+    if (!instance.element || instance.isRendering) {
+      syncRootWindowState(instance.container);
+      return;
+    }
+
+    syncRootInheritedWindowState(instance.container);
+  });
+
+  rootInstances.set(rootId, instance);
+
+  return {
+    rootId,
+
+    render(element: ReactElement): void {
+      instance.element = element;
+      instance.isRendering = true;
+
+      try {
+        performContainerUpdate(element, instance.fiber, () => {
+          instance.isRendering = false;
+        });
+      } catch (error) {
+        instance.isRendering = false;
+        handleRenderFailure(`Reconciler:${rootId}`, instance.container, () => {
+          instance.element = null;
+        }, error);
+      }
+    },
+
+    unmount(): void {
+      performContainerUpdate(null, instance.fiber, () => {});
+      instance.element = null;
+      instance.unsubscribeWindowState?.();
+      instance.unsubscribeWindowState = null;
+      rootInstances.delete(rootId);
+      destroyRoot(rootId);
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,11 @@
+export {
+  createExactRoot,
+  forceUpdate,
+  prepareForBundleReplacement,
+  render,
+  reset,
+  syncWindowState,
+  unmount,
+} from './reconciler.js';
+
+export type { ExactRoot } from './reconciler.js';