@ccheever/exact-renderer 0.1.0

package/src/vue.ts

@@ -0,0 +1,535 @@
+/**
+ * Exact Vue Renderer
+ *
+ * This module provides the Vue adapter for the Exact runtime.
+ * It uses @vue/runtime-core's createRenderer to map Vue's rendering
+ * operations to Exact's host operations.
+ *
+ * Usage:
+ * ```ts
+ * import { createApp } from './renderer/vue';
+ * import App from './vue-app';
+ *
+ * createApp(App).mount();
+ * ```
+ *
+ * Note: Vue components should use render functions (h) rather than
+ * template syntax for universal rendering.
+ */
+
+import { createRenderer, type RendererOptions, nextTick } from '@vue/runtime-core';
+
+import {
+  __setActiveWindowRenderer,
+  subscribeToRootWindowState,
+} from '@exact/core';
+import {
+  // Types
+  type ElementNode,
+  type TextNode,
+  type RootNode,
+
+  // Instance creation
+  createInstance,
+  createTextInstance,
+  createRoot,
+
+  // Tree operations
+  appendChild,
+  insertBefore,
+  removeChild,
+
+  // Updates
+  updateInstanceProps,
+  updateTextContent,
+  commitBatch,
+  destroyRoot,
+  syncRootWindowState,
+
+  // Node operations
+  NodeKind,
+
+  // Handler registry
+  _clearHandlers,
+} from './host-ops.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+type ExactNode = ElementNode | TextNode;
+type ExactParentNode = ElementNode | RootNode;
+type OptionalWindowRendererKind = 'solid' | 'vue';
+
+interface WindowRendererRoot {
+  render(content: unknown): void;
+  unmount(): void;
+}
+
+interface RootState {
+  container: RootNode;
+  hasRenderedOnce: boolean;
+  commitScheduled: boolean;
+  claimed: boolean;
+  unsubscribeWindowState: (() => void) | null;
+}
+
+const rootStates = new Map<number, RootState>();
+
+function registerOptionalWindowRenderer(
+  renderer: OptionalWindowRendererKind,
+  createRoot: (rootId: number) => WindowRendererRoot,
+): void {
+  const globalScope = globalThis as typeof globalThis & {
+    __exactOptionalWindowRenderers?:
+      Partial<Record<OptionalWindowRendererKind, (rootId: number) => WindowRendererRoot>>;
+  };
+  const registry = globalScope.__exactOptionalWindowRenderers ??= {};
+  registry[renderer] = createRoot;
+}
+
+function getRootContainerForNode(node: ExactNode | RootNode | null | undefined): RootNode | null {
+  let current = node;
+  while (current) {
+    if (current.kind === NodeKind.Root) {
+      return current;
+    }
+    current = current.parent as ExactNode | RootNode | null;
+  }
+  return null;
+}
+
+function getRootStateForNode(node: ExactNode | RootNode | null | undefined): RootState | null {
+  const container = getRootContainerForNode(node);
+  return container
+    ? rootStates.get(container.rootId) ?? null
+    : null;
+}
+
+function getOrCreateRootState(rootId: number): RootState {
+  let rootState = rootStates.get(rootId);
+  if (!rootState) {
+    rootState = {
+      container: createRoot(rootId, 'vue'),
+      hasRenderedOnce: false,
+      commitScheduled: false,
+      claimed: false,
+      unsubscribeWindowState:
+        typeof subscribeToRootWindowState === 'function'
+          ? subscribeToRootWindowState(rootId, () => {
+              if (rootState) {
+                syncRootWindowState(rootState.container);
+              }
+            })
+          : null,
+    };
+    rootStates.set(rootId, rootState);
+  }
+  return rootState;
+}
+
+function scheduleCommitForRoot(rootState: RootState | null): void {
+  if (!rootState || rootState.commitScheduled) {
+    return;
+  }
+
+  rootState.commitScheduled = true;
+  queueMicrotask(() => {
+    rootState.commitScheduled = false;
+    commitBatch(rootState.container);
+  });
+}
+
+function scheduleCommitForNode(node: ExactNode | RootNode | null | undefined): void {
+  scheduleCommitForRoot(getRootStateForNode(node));
+}
+
+// =============================================================================
+// Vue Custom Renderer Options
+// =============================================================================
+
+/**
+ * Vue renderer options that map Vue's rendering operations
+ * to Exact's host operations.
+ */
+const rendererOptions: RendererOptions<ExactNode, ExactParentNode> = {
+  /**
+   * Create a new element node.
+   */
+  createElement(type: string): ElementNode {
+    return createInstance(type, {});
+  },
+
+  /**
+   * Create a new text node.
+   */
+  createText(text: string): TextNode {
+    return createTextInstance(text);
+  },
+
+  /**
+   * Create a comment node (not used in Exact, return empty text).
+   */
+  createComment(text: string): TextNode {
+    // Comments aren't rendered in Exact, but Vue requires this
+    return createTextInstance('');
+  },
+
+  /**
+   * Set the text content of a text node.
+   */
+  setText(node: TextNode, text: string): void {
+    if (node.kind === NodeKind.Text) {
+      updateTextContent(node, text);
+      scheduleCommitForNode(node);
+    }
+  },
+
+  /**
+   * Set text content of an element.
+   * Vue calls this when an element has a single text child (e.g., h('text', {}, 'Hello')).
+   * We create/update a text node child to hold the content.
+   */
+  setElementText(node: ElementNode, text: string): void {
+
+    if (node.kind !== NodeKind.Element) {
+      return;
+    }
+
+    // Check if we already have a text node child we can update
+    const existingTextChild = node.children.find(
+      (child): child is TextNode => child.kind === NodeKind.Text
+    );
+
+    if (existingTextChild) {
+      // Update existing text node
+      updateTextContent(existingTextChild, text);
+    } else {
+      // Clear any existing children and add a text node
+      // Note: We need to properly remove existing children
+      while (node.children.length > 0) {
+        const child = node.children[0];
+        removeChild(node, child);
+      }
+
+      // Create and append new text node
+      const textNode = createTextInstance(text);
+      appendChild(node, textNode);
+    }
+
+    // Schedule commit
+    scheduleCommitForNode(node);
+  },
+
+  /**
+   * Insert a child into a parent.
+   */
+  insert(child: ExactNode, parent: ExactParentNode, anchor?: ExactNode | null): void {
+    if (anchor) {
+      insertBefore(parent, child, anchor);
+    } else {
+      appendChild(parent, child);
+    }
+    scheduleCommitForNode(parent);
+  },
+
+  /**
+   * Remove a child from its parent.
+   */
+  remove(child: ExactNode): void {
+    const parent = child.parent;
+    if (parent && (parent.kind === NodeKind.Element || parent.kind === NodeKind.Root)) {
+      const parentNode = parent as ExactParentNode;
+      removeChild(parentNode, child);
+      scheduleCommitForNode(parentNode);
+    }
+  },
+
+  /**
+   * Get the parent of a node.
+   */
+  parentNode(node: ExactNode): ExactParentNode | null {
+    return (node.parent as ExactParentNode) ?? null;
+  },
+
+  /**
+   * Get the next sibling of a node.
+   */
+  nextSibling(node: ExactNode): ExactNode | null {
+    const parent = node.parent;
+    if (!parent || (parent.kind !== NodeKind.Element && parent.kind !== NodeKind.Root)) {
+      return null;
+    }
+
+    const parentElement = parent as ExactParentNode;
+    const index = parentElement.children.indexOf(node as ElementNode);
+    if (index >= 0 && index < parentElement.children.length - 1) {
+      return parentElement.children[index + 1] as ExactNode;
+    }
+    return null;
+  },
+
+  /**
+   * Patch element props.
+   */
+  patchProp(
+    el: ElementNode,
+    key: string,
+    prevValue: unknown,
+    nextValue: unknown
+  ): void {
+    if (el.kind !== NodeKind.Element) {
+      return;
+    }
+
+    // Build new props object with the updated property
+    const newProps = { ...el.originalProps, [key]: nextValue };
+
+    // Use the shared updateInstanceProps
+    updateInstanceProps(el, el.originalProps || {}, newProps);
+
+    scheduleCommitForNode(el);
+  },
+
+  /**
+   * Clone a node (required but not commonly used).
+   */
+  cloneNode(node: ElementNode): ElementNode {
+    // Create a new instance with the same type and props
+    return createInstance(node.originalTag, node.originalProps || {});
+  },
+
+  /**
+   * Insert static content (for v-html, not used in Exact).
+   */
+  insertStaticContent(): [ExactNode, ExactNode] {
+    // Return dummy nodes - static content not supported
+    const node = createTextInstance('');
+    return [node, node];
+  },
+};
+
+// =============================================================================
+// Create the Vue Renderer
+// =============================================================================
+
+const { render: vueRender, createApp: vueCreateApp } = createRenderer(rendererOptions);
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Create a Vue application instance for Exact.
+ *
+ * @param rootComponent - The root Vue component
+ * @param rootProps - Optional props for the root component
+ * @returns A Vue app instance with a custom mount method
+ *
+ * @example
+ * ```ts
+ * import { createApp, ref, h } from './renderer/vue';
+ *
+ * const App = {
+ *   setup() {
+ *     const count = ref(0);
+ *     return () => h('div', { style: { flex: 1 } }, [
+ *       h('text', {}, `Count: ${count.value}`)
+ *     ]);
+ *   }
+ * };
+ *
+ * createApp(App).mount();
+ * ```
+ */
+export function createApp(rootComponent: any, rootProps?: Record<string, unknown>) {
+  __setActiveWindowRenderer?.('vue');
+  const rootState = getOrCreateRootState(0);
+
+  const app = vueCreateApp(rootComponent, rootProps);
+
+  // Override mount to use our root container
+  const originalMount = app.mount;
+  app.mount = () => {
+    const proxy = originalMount(rootState.container as unknown as any);
+
+    // Commit the initial batch to native
+    commitBatch(rootState.container);
+    rootState.hasRenderedOnce = true;
+
+    return proxy;
+  };
+
+  return app;
+}
+
+/**
+ * Render a Vue vnode directly to the Exact runtime.
+ *
+ * Note: Vue's component-level reactivity (watchEffect, component render effects)
+ * doesn't work properly with custom renderers. Use this with a raw `effect` from
+ * @vue/reactivity to trigger re-renders when reactive state changes.
+ *
+ * @param vnode - The Vue vnode to render
+ * @returns A cleanup function
+ *
+ * @example
+ * ```ts
+ * import { effect } from '@vue/reactivity';
+ * import { render, ref, h } from './renderer/vue';
+ *
+ * const count = ref(0);
+ * effect(() => {
+ *   render(h('text', {}, `Count: ${count.value}`));
+ * });
+ * ```
+ */
+export function render(vnode: any): () => void {
+  __setActiveWindowRenderer?.('vue');
+  const rootState = getOrCreateRootState(0);
+
+  vueRender(vnode, rootState.container as unknown as any);
+
+  // First render: commit immediately to bind events.
+  // Subsequent renders: scheduleCommit in patchProp/setElementText handles commits.
+  if (!rootState.hasRenderedOnce) {
+    commitBatch(rootState.container);
+    rootState.hasRenderedOnce = true;
+  }
+
+  return () => {
+    vueRender(null, rootState.container as unknown as any);
+  };
+}
+
+export interface ExactRoot {
+  readonly rootId: number;
+  render(vnode: any): void;
+  unmount(): void;
+}
+
+export function createExactRoot(rootId: number): ExactRoot {
+  if (rootId === 0) {
+    throw new Error('createExactRoot: rootId must be > 0. Use render() for the default root.');
+  }
+
+  const rootState = getOrCreateRootState(rootId);
+  if (rootState.claimed) {
+    throw new Error(`createExactRoot: rootId ${rootId} is already in use.`);
+  }
+  rootState.claimed = true;
+
+  return {
+    rootId,
+
+    render(vnode: any): void {
+      __setActiveWindowRenderer?.('vue');
+      vueRender(vnode, rootState.container as unknown as any);
+      if (!rootState.hasRenderedOnce) {
+        commitBatch(rootState.container);
+        rootState.hasRenderedOnce = true;
+      }
+    },
+
+    unmount(): void {
+      vueRender(null, rootState.container as unknown as any);
+      rootStates.delete(rootId);
+      rootState.unsubscribeWindowState?.();
+      rootState.unsubscribeWindowState = null;
+      destroyRoot(rootId);
+    },
+  };
+}
+
+registerOptionalWindowRenderer(
+  'vue',
+  createExactRoot as (rootId: number) => WindowRendererRoot,
+);
+
+/**
+ * Fully reset the renderer state.
+ */
+export function reset(): void {
+  for (const [rootId, rootState] of rootStates) {
+    vueRender(null, rootState.container as unknown as any);
+    rootState.unsubscribeWindowState?.();
+    rootState.unsubscribeWindowState = null;
+    destroyRoot(rootId);
+  }
+  rootStates.clear();
+  _clearHandlers();
+}
+
+// =============================================================================
+// Re-exports from Vue
+// =============================================================================
+
+// Composition API
+export {
+  ref,
+  reactive,
+  readonly,
+  computed,
+  watch,
+  watchEffect,
+  watchPostEffect,
+  watchSyncEffect,
+
+  // Lifecycle
+  onMounted,
+  onUpdated,
+  onUnmounted,
+  onBeforeMount,
+  onBeforeUpdate,
+  onBeforeUnmount,
+
+  // Dependency Injection
+  provide,
+  inject,
+
+  // Utilities
+  unref,
+  toRef,
+  toRefs,
+  isRef,
+  isReactive,
+  isReadonly,
+  isProxy,
+  shallowRef,
+  triggerRef,
+  shallowReactive,
+  shallowReadonly,
+  toRaw,
+  markRaw,
+  effectScope,
+  getCurrentScope,
+  onScopeDispose,
+  nextTick,
+
+  // Render helpers
+  h,
+  createVNode,
+  mergeProps,
+  cloneVNode,
+  isVNode,
+  resolveComponent,
+  resolveDirective,
+  withDirectives,
+
+  // Async
+  defineAsyncComponent,
+
+  // Special components
+  Fragment,
+  Teleport,
+  Suspense,
+  KeepAlive,
+
+  // Types
+  type Ref,
+  type ComputedRef,
+  type ShallowRef,
+  type UnwrapRef,
+  type Component,
+  type VNode,
+} from '@vue/runtime-core';

package/src/web-host.ts

@@ -0,0 +1,19 @@
+// @system @ref LLP 0201 W1 / LLP 0202 H1 — production Contract web host CSR.
+
+import {
+  installContractWebHost as installContractWebHostBase,
+  type ContractWebHostHandle,
+  type ContractWebHostOptions,
+} from './dom-mirror.js';
+import { installDomHydrationAdopterFactory } from './dom-hydration.js';
+
+export type { ContractWebHostHandle, ContractWebHostOptions };
+
+export function installContractWebHost(
+  options: ContractWebHostOptions = {},
+): ContractWebHostHandle | null {
+  if (options.hydrate) {
+    installDomHydrationAdopterFactory();
+  }
+  return installContractWebHostBase(options);
+}