@ccheever/exact-renderer 0.1.0

package/src/__tests__/window-hooks.test.tsx

@@ -0,0 +1,447 @@
+import React, { act } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { MAIN_WINDOW_ID } from '@exact/core';
+
+import { Text } from '../components.js';
+import { _clearHandlers } from '../host-config.js';
+import { getRootNode } from '../inspector.js';
+import { NodeKind, _resetNodeIdCounter } from '../nodes/index.js';
+import { _getRootContainer, render, reset } from '../reconciler.js';
+import {
+  _resetWindowRuntimeForTests,
+  getWindowViewportForRoot,
+  subscribeToRootWindowState,
+  window as exactWindow,
+  windows,
+} from '../../../../js/src/window-management.js';
+import {
+  emitDesktopHostEvent,
+  setDesktopHostBridge,
+} from '../../../../js/src/desktop-platform.js';
+import {
+  useKeyboardState,
+  useSafeAreaInsets,
+  useWindowFocused,
+  useWindowSize,
+  useWindowState,
+} from '../../../../js/src/window-hooks.js';
+
+interface ExactRuntimeMock {
+  dispatch: ReturnType<typeof vi.fn>;
+  screenWidth: number;
+  screenHeight: number;
+  screenScale?: number;
+  safeAreaInsets?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+  };
+}
+
+interface ExactGlobals {
+  exact?: ExactRuntimeMock;
+  __exactViewportChanged?: (width?: number, height?: number) => void;
+  __exactSafeAreaInsetsChanged?: (
+    top?: number,
+    right?: number,
+    bottom?: number,
+    left?: number,
+  ) => void;
+  __exactKeyboardStateChanged?: (update: {
+    occlusion?: {
+      x?: number;
+      y?: number;
+      width?: number;
+      height?: number;
+    };
+    visible?: boolean;
+    progress?: number;
+    animating?: boolean;
+    mode?: 'docked' | 'floating' | 'split' | 'undocked';
+    animationCurve?: number;
+    animationDurationMs?: number;
+    interactive?: boolean;
+    accessoryHeight?: number;
+    source?: 'software' | 'hardware';
+  }) => void;
+  IS_REACT_ACT_ENVIRONMENT?: boolean;
+}
+
+function getRenderedText(): string | undefined {
+  const root = _getRootContainer();
+  expect(root).not.toBeNull();
+
+  const child = root!.children[0];
+  expect(child).toBeDefined();
+  expect(child?.kind).toBe(NodeKind.Element);
+
+  if (!child || child.kind !== NodeKind.Element) {
+    throw new Error('Expected root child to be a Text element.');
+  }
+
+  return child.props.textContent as string | undefined;
+}
+
+function getRenderedTextForRoot(rootId: number): string | undefined {
+  const root = getRootNode(rootId);
+  expect(root).not.toBeNull();
+
+  const child = root!.children[0];
+  expect(child).toBeDefined();
+  expect(child?.kind).toBe(NodeKind.Element);
+
+  if (!child || child.kind !== NodeKind.Element) {
+    throw new Error('Expected root child to be a Text element.');
+  }
+
+  return child.props.textContent as string | undefined;
+}
+
+function WindowProbe(): React.ReactElement {
+  const size = useWindowSize();
+  const state = useWindowState();
+  const focused = useWindowFocused();
+  const insets = useSafeAreaInsets();
+  const keyboard = useKeyboardState();
+
+  return (
+    <Text>
+      {`${size.width}x${size.height}|${state}|${focused ? 'focused' : 'blurred'}|${insets.top}/${insets.right}/${insets.bottom}/${insets.left}|${keyboard.visible ? 'keyboard' : 'nokeyboard'}|${keyboard.occlusion.height}`}
+    </Text>
+  );
+}
+
+function SecondaryWindowProbe(): React.ReactElement {
+  const size = useWindowSize();
+  const insets = useSafeAreaInsets();
+  return <Text>{`secondary:${size.width}x${size.height}|${insets.top}/${insets.right}/${insets.bottom}/${insets.left}`}</Text>;
+}
+
+describe('window hooks', () => {
+  let dispatch: ReturnType<typeof vi.fn>;
+
+  beforeEach(async () => {
+    dispatch = vi.fn();
+
+    const globals = globalThis as typeof globalThis & ExactGlobals;
+    globals.IS_REACT_ACT_ENVIRONMENT = true;
+    globals.exact = {
+      dispatch,
+      screenWidth: 393,
+      screenHeight: 852,
+      screenScale: 2,
+      safeAreaInsets: {
+        top: 0,
+        right: 0,
+        bottom: 0,
+        left: 0,
+      },
+    };
+
+    _resetNodeIdCounter();
+    _clearHandlers();
+    await act(async () => {
+      reset();
+    });
+    setDesktopHostBridge(undefined);
+    _resetWindowRuntimeForTests();
+  });
+
+  afterEach(async () => {
+    await act(async () => {
+      reset();
+    });
+    _clearHandlers();
+    _resetNodeIdCounter();
+    setDesktopHostBridge(undefined);
+    _resetWindowRuntimeForTests();
+
+    const globals = globalThis as typeof globalThis & ExactGlobals;
+    delete globals.exact;
+    delete globals.IS_REACT_ACT_ENVIRONMENT;
+  });
+
+  it('re-renders on viewport changes and emits resize events', async () => {
+    const resizeSpy = vi.fn();
+    const unsubscribe = exactWindow.on('resize', resizeSpy);
+
+    await act(async () => {
+      render(<WindowProbe />);
+    });
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(getRenderedText()).toBe('393x852|normal|focused|0/0/0/0|nokeyboard|0');
+
+    const globals = globalThis as typeof globalThis & ExactGlobals;
+    globals.exact!.screenWidth = 800;
+    globals.exact!.screenHeight = 600;
+
+    await act(async () => {
+      globals.__exactViewportChanged?.(800, 600);
+    });
+
+    expect(dispatch).toHaveBeenCalledTimes(2);
+    expect(getRenderedText()).toBe('800x600|normal|focused|0/0/0/0|nokeyboard|0');
+    expect(resizeSpy).toHaveBeenCalledWith({
+      width: 800,
+      height: 600,
+    });
+
+    unsubscribe();
+  });
+
+  it('mirrors viewport updates into the attached desktop main-window snapshot', async () => {
+    let mainWindowSnapshot = {
+      id: 'main-native',
+      rootId: 0,
+      title: 'Facet Lab',
+      size: { width: 480, height: 960 },
+      position: { x: 120, y: 80 },
+      state: 'normal' as const,
+      isFocused: true,
+      isVisible: true,
+      display: {
+        id: 'display-main',
+        size: { width: 1440, height: 900 },
+        workArea: { x: 0, y: 0, width: 1440, height: 860 },
+        scaleFactor: 2,
+      },
+      safeAreaInsets: { top: 0, right: 0, bottom: 0, left: 0 },
+      devicePixelRatio: 2,
+    };
+
+    setDesktopHostBridge({
+      windows: {
+        getSnapshot(windowId) {
+          return windowId === MAIN_WINDOW_ID || windowId === 'main-native'
+            ? mainWindowSnapshot
+            : null;
+        },
+        call: vi.fn(),
+      },
+    });
+
+    act(() => {
+      emitDesktopHostEvent('windows', 'windowOpened', mainWindowSnapshot);
+    });
+
+    expect(getWindowViewportForRoot(0)).toEqual({
+      width: 480,
+      height: 960,
+    });
+
+    const rootListener = vi.fn();
+    const unsubscribe = subscribeToRootWindowState(0, rootListener);
+
+    const globals = globalThis as typeof globalThis & ExactGlobals;
+    globals.exact!.screenWidth = 676;
+    globals.exact!.screenHeight = 960;
+    mainWindowSnapshot = {
+      ...mainWindowSnapshot,
+      size: { width: 676, height: 960 },
+    };
+
+    await act(async () => {
+      globals.__exactViewportChanged?.(676, 960);
+    });
+
+    expect(getWindowViewportForRoot(0)).toEqual({
+      width: 676,
+      height: 960,
+    });
+    expect(rootListener).toHaveBeenCalled();
+
+    unsubscribe();
+  });
+
+  it('updates safe area state when host safe area callbacks fire', async () => {
+    await act(async () => {
+      render(<WindowProbe />);
+    });
+
+    const globals = globalThis as typeof globalThis & ExactGlobals;
+
+    await act(async () => {
+      globals.__exactSafeAreaInsetsChanged?.(12, 4, 8, 2);
+    });
+
+    expect(getRenderedText()).toBe('393x852|normal|focused|12/4/8/2|nokeyboard|0');
+    expect(exactWindow.safeAreaInsets).toEqual({
+      top: 12,
+      right: 4,
+      bottom: 8,
+      left: 2,
+    });
+  });
+
+  it('updates keyboard state when host keyboard callbacks fire', async () => {
+    await act(async () => {
+      render(<WindowProbe />);
+    });
+
+    const globals = globalThis as typeof globalThis & ExactGlobals;
+    await act(async () => {
+      globals.__exactKeyboardStateChanged?.({
+        visible: true,
+        mode: 'docked',
+        progress: 1,
+        occlusion: {
+          x: 0,
+          y: 516,
+          width: 393,
+          height: 336,
+        },
+      });
+    });
+
+    expect(getRenderedText()).toBe('393x852|normal|focused|0/0/0/0|keyboard|336');
+  });
+
+  it('renders secondary roots against their own window snapshots', async () => {
+    let secondarySnapshot = {
+      id: 'secondary',
+      rootId: 1,
+      title: 'Inspector',
+      size: { width: 640, height: 480 },
+      position: { x: 120, y: 80 },
+      state: 'normal' as const,
+      isFocused: true,
+      isVisible: true,
+      display: {
+        id: 'display-2',
+        size: { width: 1440, height: 900 },
+        workArea: { x: 0, y: 0, width: 1440, height: 860 },
+        scaleFactor: 2,
+      },
+      safeAreaInsets: { top: 6, right: 0, bottom: 10, left: 0 },
+      devicePixelRatio: 2,
+    };
+
+    setDesktopHostBridge({
+      windows: {
+        open(config) {
+          secondarySnapshot = {
+            ...secondarySnapshot,
+            rootId: config.rootId,
+            title: config.title ?? secondarySnapshot.title,
+          };
+          return secondarySnapshot;
+        },
+        getSnapshot(windowId) {
+          return windowId === 'secondary'
+            ? secondarySnapshot
+            : null;
+        },
+        call: vi.fn(),
+      },
+    });
+
+    await act(async () => {
+      await windows.open({
+        title: 'Inspector',
+        render: () => <SecondaryWindowProbe />,
+      });
+    });
+
+    expect(windows.count).toBe(2);
+    expect(getRenderedTextForRoot(1)).toBe('secondary:640x480|6/0/10/0');
+
+    secondarySnapshot = {
+      ...secondarySnapshot,
+      size: { width: 900, height: 700 },
+    };
+
+    await act(async () => {
+      emitDesktopHostEvent('windows', 'windowChanged', secondarySnapshot);
+    });
+
+    expect(getRenderedTextForRoot(1)).toBe('secondary:900x700|6/0/10/0');
+  });
+
+  it('tears down secondary roots when host close confirmation observes a missing snapshot', async () => {
+    vi.useFakeTimers();
+
+    let closed = false;
+    const bridgeCall = vi.fn((windowId: string, method: string) => {
+      if (windowId === 'secondary' && method === 'close') {
+        closed = true;
+      }
+    });
+
+    setDesktopHostBridge({
+      windows: {
+        open(config) {
+          return {
+            id: 'secondary',
+            rootId: config.rootId,
+            title: 'Inspector',
+            size: { width: 640, height: 480 },
+            position: { x: 120, y: 80 },
+            state: 'normal' as const,
+            isFocused: true,
+            isVisible: true,
+            display: {
+              id: 'display-2',
+              size: { width: 1440, height: 900 },
+              workArea: { x: 0, y: 0, width: 1440, height: 860 },
+              scaleFactor: 2,
+            },
+            safeAreaInsets: { top: 0, right: 0, bottom: 0, left: 0 },
+            devicePixelRatio: 2,
+          };
+        },
+        getSnapshot(windowId) {
+          if (windowId !== 'secondary' || closed) {
+            return null;
+          }
+
+          return {
+            id: 'secondary',
+            rootId: 1,
+            title: 'Inspector',
+            size: { width: 640, height: 480 },
+            position: { x: 120, y: 80 },
+            state: 'normal' as const,
+            isFocused: true,
+            isVisible: true,
+            display: {
+              id: 'display-2',
+              size: { width: 1440, height: 900 },
+              workArea: { x: 0, y: 0, width: 1440, height: 860 },
+              scaleFactor: 2,
+            },
+            safeAreaInsets: { top: 0, right: 0, bottom: 0, left: 0 },
+            devicePixelRatio: 2,
+          };
+        },
+        call: bridgeCall,
+      },
+    });
+
+    let secondaryWindow = windows.get('secondary');
+    expect(secondaryWindow).toBeUndefined();
+
+    await act(async () => {
+      secondaryWindow = await windows.open({
+        title: 'Inspector',
+        render: () => <SecondaryWindowProbe />,
+      });
+    });
+
+    expect(windows.count).toBe(2);
+    expect(getRootNode(1)).not.toBeNull();
+
+    await act(async () => {
+      secondaryWindow?.close();
+      vi.runAllTimers();
+    });
+
+    expect(bridgeCall).toHaveBeenCalledWith('secondary', 'close');
+    expect(windows.count).toBe(1);
+    expect(windows.get('secondary')).toBeUndefined();
+    expect(getRootNode(1)).toBeNull();
+
+    vi.useRealTimers();
+  });
+});

package/src/adapter-contract.ts

@@ -0,0 +1,68 @@
+/**
+ * RFC 0043 Adapter Contract
+ *
+ * These types document the shared renderer surface that every Exact adapter or
+ * compatibility layer targets. The implementation remains in `host-ops.ts`,
+ * but centralizing the contract here gives tests and downstream adapters a
+ * stable import path.
+ */
+
+import type { ElementNode, RootNode, TextNode } from './nodes/node.js';
+import type { TagConfig } from './tags/index.js';
+
+/**
+ * Shared host operations available to framework adapters.
+ */
+export interface ExactAdapterHostOps {
+  createInstance(type: string, props: Record<string, unknown>): ElementNode;
+  createTextInstance(text: string): TextNode;
+  appendChild(parent: ElementNode | RootNode, child: ElementNode | TextNode): void;
+  insertBefore(
+    parent: ElementNode | RootNode,
+    child: ElementNode | TextNode,
+    beforeChild: ElementNode | TextNode,
+  ): void;
+  removeChild(parent: ElementNode | RootNode, child: ElementNode | TextNode): void;
+  detachChild(parent: ElementNode | RootNode, child: ElementNode | TextNode): void;
+  updateInstanceProps(
+    instance: ElementNode,
+    oldProps: Record<string, unknown>,
+    newProps: Record<string, unknown>,
+  ): void;
+  updateTextContent(instance: TextNode, text: string): void;
+  commitBatch(root: RootNode): void;
+  createRoot(rootId?: number, owner?: string): RootNode;
+  destroyRoot(rootId: number): void;
+  clearContainer(root: RootNode): void;
+  registerHandler(fn: Function): number;
+  unregisterHandler(
+    id: number,
+    nodeId?: number,
+    eventType?: number,
+    rootId?: number,
+  ): void;
+  getTagConfig(tag: string): TagConfig | null;
+}
+
+/**
+ * Public root handle every stateful adapter exposes.
+ */
+export interface ExactAdapterRoot<TTree = unknown> {
+  readonly rootId: number;
+  render(tree: TTree): void;
+  unmount(): void;
+}
+
+/**
+ * Public adapter lifecycle surface.
+ */
+export interface ExactAdapterOps<
+  TTree = unknown,
+  TRoot extends ExactAdapterRoot<TTree> = ExactAdapterRoot<TTree>,
+> {
+  readonly name: string;
+  render(tree: TTree): void | (() => void);
+  createExactRoot(rootId: number): TRoot;
+  reset(): void;
+  unmount?(): void;
+}