Rimitive Adapter

AdapterConfig Type

Define types for your adapter to get autocomplete in el():

type AdapterConfig = {
  props: object; // Maps tag names to prop types
  elements: object; // Maps tag names to node types
  events: object; // Maps event names to event types
  baseElement: object; // Base node type for this adapter
};

Minimal Adapter Example

A simple in-memory adapter for testing or non-DOM environments:

import type { Adapter, AdapterConfig } from '@rimitive/view/adapter';

type SimpleNode = {
  type: string;
  props: Record<string, unknown>;
  children: SimpleNode[];
};

type SimpleAdapterConfig = AdapterConfig & {
  props: Record<string, Record<string, unknown>>;
  elements: Record<string, SimpleNode>;
  events: Record<string, Event>;
  baseElement: SimpleNode;
};

function createSimpleAdapter(): Adapter<SimpleAdapterConfig> {
  return {
    createNode: (type, props) => ({
      type,
      props: { ...props },
      children: [],
    }),

    setAttribute: (node, key, value) => {
      node.props[key] = value;
    },

    appendChild: (parent, child) => {
      parent.children.push(child);
    },

    removeChild: (parent, child) => {
      const idx = parent.children.indexOf(child);
      if (idx !== -1) parent.children.splice(idx, 1);
    },

    insertBefore: (parent, child, reference) => {
      if (reference === null) {
        parent.children.push(child);
      } else {
        const idx = parent.children.indexOf(reference);
        if (idx !== -1) {
          parent.children.splice(idx, 0, child);
        } else {
          parent.children.push(child);
        }
      }
    },
  };
}

Canvas Adapter Example

A more complex adapter for 2D canvas rendering:

import type { Adapter, AdapterConfig } from '@rimitive/view/adapter';

type CanvasNode = {
  type: 'rect' | 'circle' | 'text' | 'group';
  x: number;
  y: number;
  width?: number;
  height?: number;
  radius?: number;
  fill?: string;
  stroke?: string;
  value?: string;
  children: CanvasNode[];
  parent: CanvasNode | null;
};

type CanvasAdapterConfig = AdapterConfig & {
  props: {
    rect: {
      x?: number;
      y?: number;
      width?: number;
      height?: number;
      fill?: string;
    };
    circle: { x?: number; y?: number; radius?: number; fill?: string };
    text: { x?: number; y?: number; value?: string; fill?: string };
    group: { x?: number; y?: number };
  };
  elements: {
    rect: CanvasNode;
    circle: CanvasNode;
    text: CanvasNode;
    group: CanvasNode;
  };
  events: Record<string, never>;
  baseElement: CanvasNode;
};

function createCanvasAdapter(
  ctx: CanvasRenderingContext2D
): Adapter<CanvasAdapterConfig> {
  let needsRedraw = false;
  let root: CanvasNode | null = null;

  function scheduleRedraw() {
    if (needsRedraw) return;
    needsRedraw = true;
    requestAnimationFrame(() => {
      needsRedraw = false;
      if (root) render(root);
    });
  }

  function render(node: CanvasNode, offsetX = 0, offsetY = 0) {
    const x = (node.x ?? 0) + offsetX;
    const y = (node.y ?? 0) + offsetY;

    switch (node.type) {
      case 'rect':
        if (node.fill) {
          ctx.fillStyle = node.fill;
          ctx.fillRect(x, y, node.width ?? 0, node.height ?? 0);
        }
        break;
      case 'circle':
        ctx.beginPath();
        ctx.arc(x, y, node.radius ?? 0, 0, Math.PI * 2);
        if (node.fill) {
          ctx.fillStyle = node.fill;
          ctx.fill();
        }
        break;
      case 'text':
        if (node.fill) ctx.fillStyle = node.fill;
        ctx.fillText(node.value ?? '', x, y);
        break;
    }

    for (const child of node.children) {
      render(child, x, y);
    }
  }

  return {
    createNode: (type, props) => {
      const node: CanvasNode = {
        type: type as CanvasNode['type'],
        x: 0,
        y: 0,
        children: [],
        parent: null,
        ...props,
      };
      return node;
    },

    setAttribute: (node, key, value) => {
      (node as Record<string, unknown>)[key] = value;
      scheduleRedraw();
    },

    appendChild: (parent, child) => {
      child.parent = parent;
      parent.children.push(child);
      if (!root) root = parent;
      scheduleRedraw();
    },

    removeChild: (parent, child) => {
      const idx = parent.children.indexOf(child);
      if (idx !== -1) {
        parent.children.splice(idx, 1);
        child.parent = null;
      }
      scheduleRedraw();
    },

    insertBefore: (parent, child, reference) => {
      child.parent = parent;
      if (reference === null) {
        parent.children.push(child);
      } else {
        const idx = parent.children.indexOf(reference);
        parent.children.splice(
          idx !== -1 ? idx : parent.children.length,
          0,
          child
        );
      }
      if (!root) root = parent;
      scheduleRedraw();
    },
  };
}

Using Adapters with View Modules

Pass your adapter to view module factories:

import { compose } from '@rimitive/core';
import {
  SignalModule,
  ComputedModule,
  EffectModule,
} from '@rimitive/signals/extend';
import { createElModule } from '@rimitive/view/el';
import { createMapModule } from '@rimitive/view/map';
import { createMatchModule } from '@rimitive/view/match';
import { MountModule } from '@rimitive/view/deps/mount';

// Create your adapter
const adapter = createCanvasAdapter(ctx);

// Compose with view modules
const svc = compose(
  SignalModule,
  ComputedModule,
  EffectModule,
  createElModule(adapter),
  createMapModule(adapter),
  createMatchModule(adapter),
  MountModule
);

const { el, map, mount } = svc;

// Now el() creates canvas nodes instead of DOM nodes
const scene = el('group')(
  el('rect').props({ x: 10, y: 10, width: 100, height: 50, fill: 'blue' }),
  el('circle').props({ x: 200, y: 50, radius: 25, fill: 'red' })
);

Lifecycle Hooks

Use lifecycle hooks for advanced use cases:

Animation Example

const animatedAdapter: Adapter<DOMAdapterConfig> = {
  ...createDOMAdapter(),

  beforeDestroy: (ref, parent) => {
    if (ref.element instanceof HTMLElement) {
      ref.element.classList.add('exiting');
      // Note: actual animation delay requires more infrastructure
    }
  },

  onDestroy: (ref, parent) => {
    console.log('Node removed:', ref.element);
  },
};

Cross-Renderer Composition

The parentContext parameter in createNode enables nested renderers:

createNode: (type, props, parentContext) => {
  // parentContext.element is the parent node
  // parentContext.adapter is the parent's adapter (if different)

  // A canvas adapter nested in DOM could create a <canvas> element
  // when it detects a DOM parent context
  if (parentContext?.adapter !== this && type === 'canvas-root') {
    return document.createElement('canvas');
  }

  return createCanvasNode(type, props);
};

Built-in Adapters

Rimitive provides these adapters:

Testing Custom Adapters

Use the test adapter pattern for adapter tests:

import { describe, it, expect } from 'vitest';

describe('CanvasAdapter', () => {
  it('creates nodes with correct type', () => {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d')!;
    const adapter = createCanvasAdapter(ctx);

    const rect = adapter.createNode('rect', { x: 10, y: 20 });

    expect(rect.type).toBe('rect');
    expect(rect.x).toBe(10);
    expect(rect.y).toBe(20);
  });

  it('builds tree structure', () => {
    const adapter = createCanvasAdapter(ctx);
    const group = adapter.createNode('group');
    const rect = adapter.createNode('rect');

    adapter.appendChild(group, rect);

    expect(group.children).toContain(rect);
    expect(rect.parent).toBe(group);
  });
});

Hydration Adapter Pattern

The hydration adapter demonstrates a fundamentally different approach: reusing existing DOM instead of creating new nodes. This is essential for SSR where the HTML already exists.

Key differences from standard adapters:

1. createNode walks existing DOM instead of creating elements
2. Position tracking via a mutable path[] array
3. Structure validation throws HydrationMismatch on mismatches
4. Fragment marker handling skips SSR comment markers

import type { Adapter } from '@rimitive/view/adapter';
import type { DOMAdapterConfig } from '@rimitive/view/adapters/dom';

class HydrationMismatch extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'HydrationMismatch';
  }
}

function createHydrationAdapter(
  containerEl: HTMLElement
): Adapter<DOMAdapterConfig> {
  // Mutable position - path[i] is child index at depth i
  const path: number[] = [];

  function getNodeAtPath(root: Node, indices: number[]): Node {
    let node = root;
    for (const index of indices) {
      node = node.childNodes[index];
      if (!node) throw new HydrationMismatch(`No child at index ${index}`);
    }
    return node;
  }

  return {
    createNode: (type, props) => {
      // Text nodes - reuse existing
      if (type === 'text') {
        const node = getNodeAtPath(containerEl, path);
        if (node.nodeType !== 3) {
          throw new HydrationMismatch(`Expected text, got ${node.nodeName}`);
        }
        // Update text if needed
        const text = (props?.value as string) ?? '';
        if (node.textContent !== text) node.textContent = text;
        // Advance to next sibling
        path[path.length - 1]++;
        return node;
      }

      // Element nodes - validate and reuse
      const node = getNodeAtPath(containerEl, path);
      if (
        node.nodeType !== 1 ||
        (node as Element).tagName.toLowerCase() !== type
      ) {
        throw new HydrationMismatch(
          `Expected <${type}>, got <${(node as Element).tagName}>`
        );
      }
      // Enter element's children
      path.push(0);
      return node;
    },

    setAttribute: (node, key, value) => {
      // Attach event handlers and update dynamic props
      if (node.nodeType === 3 && key === 'value') {
        node.textContent = String(value);
        return;
      }
      Reflect.set(node, key, value);
    },

    appendChild: (parent, child) => {
      // Element already attached - this is the "exit" signal
      if (child.nodeType === 1 && child.parentNode === parent) {
        path.pop(); // Exit element's children
        path[path.length - 1]++; // Advance to next sibling
      }
    },

    removeChild: () => {}, // No-op during hydration

    insertBefore: (parent, child) => {
      // Same exit signal as appendChild
      if (child.nodeType === 1 && child.parentNode === parent) {
        path.pop();
        path[path.length - 1]++;
      }
    },
  };
}

Mode Switching

After hydration completes, switch to a standard adapter for dynamic updates:

function createSwitchableAdapter(
  hydrateAdapter: Adapter<DOMAdapterConfig>,
  fallbackAdapter: Adapter<DOMAdapterConfig>
): Adapter<DOMAdapterConfig> & { switchToFallback: () => void } {
  let current = hydrateAdapter;

  return {
    createNode: (type, props) => current.createNode(type, props),
    setAttribute: (node, key, value) => current.setAttribute(node, key, value),
    appendChild: (parent, child) => current.appendChild(parent, child),
    removeChild: (parent, child) => current.removeChild(parent, child),
    insertBefore: (parent, child, ref) =>
      current.insertBefore(parent, child, ref),

    switchToFallback: () => {
      current = fallbackAdapter;
    },
  };
}

// Usage
const adapter = createSwitchableAdapter(
  createHydrationAdapter(container),
  createDOMAdapter()
);

// After hydration
adapter.switchToFallback();

When to Create a Custom Adapter

Good candidates:

• Canvas/WebGL rendering
• Terminal/CLI interfaces
• Native mobile (React Native-style)
• Game engines
• PDF generation
• Custom component systems
• Hydration for custom SSR solutions

Not necessary for:

• Standard web apps (use DOM adapter)
• Server rendering (use SSR adapter)
• Testing (use test adapter)
• Standard hydration (use @rimitive/ssr)