@ccheever/exact-renderer 0.1.0

package/src/jsx-augmentations.ts

@@ -0,0 +1,54 @@
+/**
+ * Framework JSX augmentations.
+ *
+ * RFC 0043 expands Exact's web-style surface beyond the original small tag
+ * set. React and Solid still source their intrinsic-element typings from their
+ * own framework packages, so we augment those packages here with the Exact
+ * interaction props that the runtime accepts on DOM-like tags.
+ *
+ * This module is imported for its side effects by the renderer entrypoints so
+ * the augmentations are present anywhere the adapter packages are used.
+ */
+
+import type {} from 'react';
+import type {} from 'solid-js';
+
+import type { PressEvent } from './types.js';
+
+declare module 'react' {
+  interface HTMLAttributes<T> {
+    onPress?: (event: PressEvent) => void;
+    onPressIn?: (event: PressEvent) => void;
+    onPressOut?: (event: PressEvent) => void;
+    onLongPress?: (event: PressEvent) => void;
+  }
+
+  interface InputHTMLAttributes<T> {
+    onChangeText?: (text: string) => void;
+  }
+
+  interface TextareaHTMLAttributes<T> {
+    onChangeText?: (text: string) => void;
+  }
+}
+
+declare module 'solid-js' {
+  namespace JSX {
+    interface HTMLAttributes<T> {
+      onPress?: (event: PressEvent) => void;
+      onPressIn?: (event: PressEvent) => void;
+      onPressOut?: (event: PressEvent) => void;
+      onLongPress?: (event: PressEvent) => void;
+    }
+
+    interface InputHTMLAttributes<T> {
+      onChangeText?: (text: string) => void;
+    }
+
+    interface TextareaHTMLAttributes<T> {
+      onChangeText?: (text: string) => void;
+    }
+  }
+}
+
+export {};

package/src/keyboard-avoidance.ts

@@ -0,0 +1,217 @@
+import type { Point } from '@exact/core/agent/types';
+import { hostCallBridge } from '@exact/core/host-call-bridge';
+import { getKeyboardStateForRoot } from '@exact/core/window-state';
+
+type InspectorTargeting = Pick<
+  typeof import('./inspector.js'),
+  'resolveElement' | 'resolveTargetDetails' | 'setScrollOffset'
+>;
+
+const focusedInputsByRoot = new Map<number, number>();
+
+function inspectorGlobal(): typeof globalThis & {
+  __exactRendererInspectorTargeting?: InspectorTargeting;
+} {
+  return globalThis as typeof globalThis & {
+    __exactRendererInspectorTargeting?: InspectorTargeting;
+  };
+}
+
+function getLoadedInspectorTargeting(): InspectorTargeting | null {
+  return inspectorGlobal().__exactRendererInspectorTargeting ?? null;
+}
+
+function loadInspectorTargeting(): Promise<InspectorTargeting> {
+  const loaded = getLoadedInspectorTargeting();
+  if (loaded) {
+    return Promise.resolve(loaded);
+  }
+
+  const specifier = './inspector.js';
+  return import(/* @vite-ignore */ specifier).then((inspector) => {
+    const targeting: InspectorTargeting = {
+      resolveElement: inspector.resolveElement,
+      resolveTargetDetails: inspector.resolveTargetDetails,
+      setScrollOffset: inspector.setScrollOffset,
+    };
+    inspectorGlobal().__exactRendererInspectorTargeting = targeting;
+    return targeting;
+  });
+}
+
+function framesIntersect(
+  left: { x: number; y: number; width: number; height: number },
+  right: { x: number; y: number; width: number; height: number },
+): boolean {
+  return !(
+    left.x + left.width <= right.x ||
+    right.x + right.width <= left.x ||
+    left.y + left.height <= right.y ||
+    right.y + right.height <= left.y
+  );
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function readAutoScrollDelta(
+  inspector: InspectorTargeting,
+  rootId: number,
+  focusedViewId: number,
+): {
+  scrollViewId: number;
+  desiredOffset: Point;
+  currentOffset: Point;
+  contentSize: { width: number; height: number };
+  viewportSize: { width: number; height: number };
+} | null {
+  const keyboard = getKeyboardStateForRoot(rootId);
+  if (!keyboard.visible || keyboard.interactive) {
+    return null;
+  }
+
+  const target = inspector.resolveTargetDetails({
+    rootId,
+    viewId: focusedViewId,
+  });
+  if (!target || target.scrollChain.length === 0) {
+    return null;
+  }
+
+  const nearestScroll = target.scrollChain[0];
+  const scrollContainer = inspector.resolveElement({
+    rootId,
+    viewId: nearestScroll.viewId,
+  });
+  if (!scrollContainer) {
+    return null;
+  }
+
+  if (
+    keyboard.mode !== 'docked' &&
+    !framesIntersect(target.frame, keyboard.occlusion)
+  ) {
+    return null;
+  }
+
+  const padding = 12;
+  const visibleTop = scrollContainer.frame.y + padding;
+  let visibleBottom = scrollContainer.frame.y + scrollContainer.frame.height - padding;
+  if (framesIntersect(scrollContainer.frame, keyboard.occlusion)) {
+    visibleBottom = Math.min(visibleBottom, keyboard.occlusion.y - padding);
+  }
+
+  let deltaY = 0;
+  if (target.frame.y < visibleTop) {
+    deltaY = target.frame.y - visibleTop;
+  } else if (target.frame.y + target.frame.height > visibleBottom) {
+    deltaY = target.frame.y + target.frame.height - visibleBottom;
+  }
+
+  if (deltaY === 0) {
+    return null;
+  }
+
+  const maxOffsetY = Math.max(
+    0,
+    nearestScroll.contentSize.height - nearestScroll.viewportSize.height,
+  );
+
+  return {
+    scrollViewId: nearestScroll.viewId,
+    currentOffset: nearestScroll.currentOffset,
+    desiredOffset: {
+      x: nearestScroll.currentOffset.x,
+      y: clamp(nearestScroll.currentOffset.y + deltaY, 0, maxOffsetY),
+    },
+    contentSize: nearestScroll.contentSize,
+    viewportSize: nearestScroll.viewportSize,
+  };
+}
+
+export function noteFocusedInput(rootId: number, viewId: number): void {
+  focusedInputsByRoot.set(rootId, viewId);
+}
+
+export function clearFocusedInput(rootId: number, viewId?: number): void {
+  if (viewId == null || focusedInputsByRoot.get(rootId) === viewId) {
+    focusedInputsByRoot.delete(rootId);
+  }
+}
+
+/**
+ * Runs after a commit so the latest layout and keyboard state are both visible.
+ *
+ * The RFC’s ownership rule is intentionally conservative here: only the nearest
+ * scroll ancestor is allowed to respond, and interactive keyboard dismissal is
+ * explicitly ignored so the runtime does not fight the user.
+ */
+export function syncKeyboardAvoidanceAfterCommit(rootId: number): void {
+  const focusedViewId = focusedInputsByRoot.get(rootId);
+  if (typeof focusedViewId !== 'number') {
+    return;
+  }
+
+  const loadedInspector = getLoadedInspectorTargeting();
+  if (loadedInspector) {
+    syncKeyboardAvoidanceAfterCommitWithInspector(rootId, focusedViewId, loadedInspector);
+    return;
+  }
+
+  void syncKeyboardAvoidanceAfterCommitAsync(rootId, focusedViewId).catch((error) => {
+    console.error('[ExactKeyboardAvoidance] failed to load inspector targeting:', error);
+  });
+}
+
+async function syncKeyboardAvoidanceAfterCommitAsync(
+  rootId: number,
+  focusedViewId: number,
+): Promise<void> {
+  const inspector = await loadInspectorTargeting();
+  syncKeyboardAvoidanceAfterCommitWithInspector(rootId, focusedViewId, inspector);
+}
+
+function syncKeyboardAvoidanceAfterCommitWithInspector(
+  rootId: number,
+  focusedViewId: number,
+  inspector: InspectorTargeting,
+): void {
+  const plan = readAutoScrollDelta(inspector, rootId, focusedViewId);
+  if (!plan) {
+    return;
+  }
+
+  if (
+    plan.desiredOffset.x === plan.currentOffset.x &&
+    plan.desiredOffset.y === plan.currentOffset.y
+  ) {
+    return;
+  }
+
+  const hostCall = hostCallBridge();
+  if (hostCall) {
+    try {
+      hostCall(
+        'agent.scroll',
+        JSON.stringify({
+          rootId,
+          viewId: plan.scrollViewId,
+          waitForIdle: false,
+          offset: plan.desiredOffset,
+          contentSize: plan.contentSize,
+          viewportSize: plan.viewportSize,
+        }),
+      );
+      return;
+    } catch {
+      // Fall through to the local inspector-side scroll model.
+    }
+  }
+
+  inspector.setScrollOffset(plan.scrollViewId, plan.desiredOffset);
+}
+
+export function resetKeyboardAvoidanceState(): void {
+  focusedInputsByRoot.clear();
+}

package/src/native-primitives.ts

@@ -0,0 +1,43 @@
+import { createElement } from 'react';
+import type { FC } from 'react';
+
+import type {
+  ContainerProps,
+  PressableElementProps,
+  ScrollContainerProps,
+  TextElementProps,
+} from './types.js';
+
+export const View: FC<ContainerProps> = function ExactNativeView(props) {
+  return createElement('View', props);
+};
+
+export const Text: FC<TextElementProps> = function ExactNativeText(props) {
+  return createElement('Text', props);
+};
+
+export const Pressable: FC<PressableElementProps> = function ExactNativePressable(
+  props,
+) {
+  return createElement('Pressable', props);
+};
+
+export const ScrollView: FC<ScrollContainerProps> = function ExactNativeScrollView(
+  props,
+) {
+  return createElement('ScrollView', props);
+};
+
+export const List: FC<ScrollContainerProps> = function ExactNativeList(props) {
+  return createElement('List', props);
+};
+
+export const SelectionGroup: FC<ContainerProps> = function ExactNativeSelectionGroup(
+  props,
+) {
+  return createElement('View', {
+    ...props,
+    selectable: props.selectable ?? 'contain',
+    __exactComponentName: props.__exactComponentName ?? 'SelectionGroup',
+  });
+};

package/src/native-view-events.ts

@@ -0,0 +1,322 @@
+import { EventType } from '@exact/core/protocol/opcodes';
+
+interface NativeViewEventHandler {
+  moduleName: string;
+  handle(eventName: string, payload: unknown): boolean;
+}
+
+interface NativeViewModuleEventBridgeState {
+  installed: boolean;
+  baseDispatcher?: ExactModuleEventDispatcher;
+  nativeViewHandlers: Map<number, NativeViewEventHandler>;
+}
+
+type ExactModuleEventDispatcher = (
+  moduleName: string,
+  eventName: string,
+  nodeIdOrPayload?: unknown,
+  payloadMaybe?: unknown,
+) => void;
+
+interface NativeViewEventGlobalScope {
+  __exactModuleEvent?: ExactModuleEventDispatcher;
+  __exactModuleEventHandlers?: Map<string, (eventName: string, payload: unknown) => void>;
+  __exactNativeViewModuleEventBridgeState?: NativeViewModuleEventBridgeState;
+}
+
+function globalScope(): typeof globalThis & NativeViewEventGlobalScope {
+  return globalThis as typeof globalThis & NativeViewEventGlobalScope;
+}
+
+function getBridgeState(): NativeViewModuleEventBridgeState {
+  const scope = globalScope();
+
+  if (scope.__exactNativeViewModuleEventBridgeState) {
+    return scope.__exactNativeViewModuleEventBridgeState;
+  }
+
+  const state: NativeViewModuleEventBridgeState = {
+    installed: false,
+    baseDispatcher: undefined,
+    nativeViewHandlers: new Map(),
+  };
+  scope.__exactNativeViewModuleEventBridgeState = state;
+  return state;
+}
+
+function decodeNativeViewEventPayload(payload: unknown): unknown {
+  // Native Exact views send MessagePack so controls can report structured
+  // values without paying the JSON stringify/parse tax on every interaction.
+  // Keep the decoder local and tiny: RFC 0073 only needs the basic scalar/map
+  // surface used by the first-party slider/toggle modules.
+  const bytes =
+    payload instanceof Uint8Array
+      ? payload
+      : payload instanceof ArrayBuffer
+        ? new Uint8Array(payload)
+        : null;
+
+  if (!bytes) {
+    return payload;
+  }
+
+  try {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let offset = 0;
+    const textDecoder = new TextDecoder();
+
+    const ensureAvailable = (length: number): void => {
+      if (offset + length > bytes.byteLength) {
+        throw new Error('Unexpected end of MessagePack data');
+      }
+    };
+
+    const readBytes = (length: number): Uint8Array => {
+      ensureAvailable(length);
+      const start = offset;
+      offset += length;
+      return bytes.subarray(start, start + length);
+    };
+
+    const readUint8 = (): number => {
+      ensureAvailable(1);
+      return bytes[offset++]!;
+    };
+
+    const readUint16 = (): number => {
+      ensureAvailable(2);
+      const value = view.getUint16(offset, false);
+      offset += 2;
+      return value;
+    };
+
+    const readUint32 = (): number => {
+      ensureAvailable(4);
+      const value = view.getUint32(offset, false);
+      offset += 4;
+      return value;
+    };
+
+    const readInt8 = (): number => {
+      ensureAvailable(1);
+      const value = view.getInt8(offset);
+      offset += 1;
+      return value;
+    };
+
+    const readInt16 = (): number => {
+      ensureAvailable(2);
+      const value = view.getInt16(offset, false);
+      offset += 2;
+      return value;
+    };
+
+    const readInt32 = (): number => {
+      ensureAvailable(4);
+      const value = view.getInt32(offset, false);
+      offset += 4;
+      return value;
+    };
+
+    const readFloat32 = (): number => {
+      ensureAvailable(4);
+      const value = view.getFloat32(offset, false);
+      offset += 4;
+      return value;
+    };
+
+    const readFloat64 = (): number => {
+      ensureAvailable(8);
+      const value = view.getFloat64(offset, false);
+      offset += 8;
+      return value;
+    };
+
+    const decodeValue = (): unknown => {
+      const byte = readUint8();
+
+      if (byte <= 0x7f) {
+        return byte;
+      }
+      if (byte >= 0xe0) {
+        return byte - 256;
+      }
+      if ((byte & 0xf0) === 0x80) {
+        return decodeMap(byte & 0x0f);
+      }
+      if ((byte & 0xf0) === 0x90) {
+        return decodeArray(byte & 0x0f);
+      }
+      if ((byte & 0xe0) === 0xa0) {
+        return textDecoder.decode(readBytes(byte & 0x1f));
+      }
+
+      switch (byte) {
+        case 0xc0:
+          return null;
+        case 0xc2:
+          return false;
+        case 0xc3:
+          return true;
+        case 0xc4:
+          return readBytes(readUint8());
+        case 0xc5:
+          return readBytes(readUint16());
+        case 0xc6:
+          return readBytes(readUint32());
+        case 0xca:
+          return readFloat32();
+        case 0xcb:
+          return readFloat64();
+        case 0xcc:
+          return readUint8();
+        case 0xcd:
+          return readUint16();
+        case 0xce:
+          return readUint32();
+        case 0xd0:
+          return readInt8();
+        case 0xd1:
+          return readInt16();
+        case 0xd2:
+          return readInt32();
+        case 0xd9:
+          return textDecoder.decode(readBytes(readUint8()));
+        case 0xda:
+          return textDecoder.decode(readBytes(readUint16()));
+        case 0xdb:
+          return textDecoder.decode(readBytes(readUint32()));
+        case 0xdc:
+          return decodeArray(readUint16());
+        case 0xdd:
+          return decodeArray(readUint32());
+        case 0xde:
+          return decodeMap(readUint16());
+        case 0xdf:
+          return decodeMap(readUint32());
+        default:
+          throw new Error(`Unknown MessagePack type: 0x${byte.toString(16)}`);
+      }
+    };
+
+    const decodeArray = (length: number): unknown[] => {
+      const result: unknown[] = [];
+      for (let index = 0; index < length; index += 1) {
+        result.push(decodeValue());
+      }
+      return result;
+    };
+
+    const decodeMap = (length: number): Record<string, unknown> => {
+      const result: Record<string, unknown> = {};
+      for (let index = 0; index < length; index += 1) {
+        const key = decodeValue();
+        result[String(key)] = decodeValue();
+      }
+      return result;
+    };
+
+    return decodeValue();
+  } catch (error) {
+    console.warn('[NativeViewEvents] Failed to decode MessagePack payload.', error);
+    return payload;
+  }
+}
+
+function dispatchNativeViewModuleEvent(
+  moduleName: string,
+  eventName: string,
+  nodeId: number,
+  payload: unknown,
+): boolean {
+  const handler = getBridgeState().nativeViewHandlers.get(nodeId);
+  if (!handler || handler.moduleName !== moduleName) {
+    return false;
+  }
+
+  const decodedPayload = decodeNativeViewEventPayload(payload);
+  return handler.handle(eventName, decodedPayload);
+}
+
+function installModuleEventBridge(): void {
+  const state = getBridgeState();
+  const scope = globalScope();
+  if (state.installed) {
+    return;
+  }
+
+  if (typeof scope.__exactModuleEventHandlers === 'undefined') {
+    scope.__exactModuleEventHandlers = new Map();
+  }
+
+  const existingDispatcher = scope.__exactModuleEvent;
+  state.baseDispatcher =
+    typeof existingDispatcher === 'function'
+      ? existingDispatcher
+      : undefined;
+
+  scope.__exactModuleEvent = (
+    moduleName: string,
+    eventName: string,
+    nodeIdOrPayload?: unknown,
+    payloadMaybe?: unknown,
+  ) => {
+    const hasNodeId = typeof nodeIdOrPayload === 'number';
+    const nodeId = hasNodeId ? nodeIdOrPayload as number : undefined;
+    const payload = hasNodeId ? payloadMaybe : nodeIdOrPayload;
+
+    if (
+      typeof nodeId === 'number' &&
+      dispatchNativeViewModuleEvent(moduleName, eventName, nodeId, payload)
+    ) {
+      return;
+    }
+
+    if (state.baseDispatcher) {
+      // Preserve any pre-existing dispatcher that libraries installed before the
+      // renderer loaded. Older handlers only expect a 3-argument shape, so only
+      // forward the node id to dispatchers that explicitly opted into it.
+      if (hasNodeId && state.baseDispatcher.length >= 4) {
+        state.baseDispatcher(moduleName, eventName, nodeId, payload);
+        return;
+      }
+      state.baseDispatcher(moduleName, eventName, payload);
+      return;
+    }
+
+    scope.__exactModuleEventHandlers?.get(moduleName)?.(eventName, payload);
+  };
+
+  state.installed = true;
+}
+
+export function registerNativeViewEventHandler(
+  nodeId: number,
+  moduleName: string,
+  handler: NativeViewEventHandler['handle'],
+): void {
+  installModuleEventBridge();
+  getBridgeState().nativeViewHandlers.set(nodeId, {
+    moduleName,
+    handle: handler,
+  });
+}
+
+export function unregisterNativeViewEventHandler(nodeId: number): void {
+  getBridgeState().nativeViewHandlers.delete(nodeId);
+}
+
+export function _resetNativeViewEventBridgeForTests(): void {
+  const state = getBridgeState();
+  const scope = globalScope();
+  state.nativeViewHandlers.clear();
+  state.baseDispatcher = undefined;
+  state.installed = false;
+  delete scope.__exactModuleEvent;
+  delete scope.__exactModuleEventHandlers;
+  delete scope.__exactNativeViewModuleEventBridgeState;
+}
+
+installModuleEventBridge();
+
+export { EventType };

package/src/native-view.ts

@@ -0,0 +1,60 @@
+import { createElement } from 'react';
+import type { FC, ReactNode } from 'react';
+
+import type {
+  BaseProps,
+  NativeViewSelectionGesturePolicy,
+  NativeViewSelectionTier,
+  ViewStyle,
+} from './types.js';
+import { registerNativeViewTag } from './tags/index.js';
+
+export interface NativeViewSelectionDef {
+  readonly tier: NativeViewSelectionTier;
+  readonly gesturePolicy?: NativeViewSelectionGesturePolicy;
+}
+
+export interface NativeViewRuntimeDef {
+  readonly moduleName: string;
+  readonly propKeys: readonly string[];
+  readonly selection?: NativeViewSelectionDef;
+  readonly displayName?: string;
+}
+
+export type NativeViewComponentProps<Props extends Record<string, unknown> = Record<string, unknown>> =
+  BaseProps & {
+    style?: ViewStyle;
+    children?: ReactNode;
+  } & Props;
+
+function getDisplayName(moduleName: string): string {
+  const lastSegment = moduleName.split('.').pop();
+  return lastSegment && lastSegment.length > 0
+    ? lastSegment
+    : moduleName;
+}
+
+export function createNativeViewComponent<Props extends Record<string, unknown>>(
+  def: NativeViewRuntimeDef,
+): FC<NativeViewComponentProps<Props>> {
+  const tag = registerNativeViewTag({
+    moduleName: def.moduleName,
+    propKeys: [...def.propKeys],
+    selection: def.selection
+      ? {
+          tier: def.selection.tier,
+          gesturePolicy:
+            def.selection.tier === 'delegated'
+              ? (def.selection.gesturePolicy ?? 'internal')
+              : def.selection.gesturePolicy,
+        }
+      : undefined,
+  });
+
+  const NativeViewComponent = (
+    props: NativeViewComponentProps<Props>,
+  ) => createElement(tag, props as Record<string, unknown>);
+
+  NativeViewComponent.displayName = def.displayName ?? getDisplayName(def.moduleName);
+  return NativeViewComponent;
+}