@vectojs/dom 0.2.0

package/dist/index.mjs

@@ -0,0 +1,551 @@
+// src/eventBridge.ts
+import { VectoJSEvent } from "@vectojs/core";
+var gestureOwner = /* @__PURE__ */ new Map();
+function getGestureOwner(pointerId) {
+  return gestureOwner.get(pointerId);
+}
+var POINTER_EVENTS = [
+  "click",
+  "pointerup",
+  "pointercancel",
+  "pointermove",
+  "wheel"
+];
+var PRESS_EVENTS = ["pointerdown", "mousedown", "touchstart"];
+function attachDOMBridge(el, node, options = {}) {
+  const listeners = [];
+  let mode = options.mode ?? "selection";
+  const on = (type, handler, capture = false) => {
+    el.addEventListener(type, handler, capture);
+    listeners.push({ type, handler, capture });
+  };
+  const pressCapture = (e) => {
+    if (e.type === "pointerdown") {
+      const id = e.pointerId ?? 0;
+      if (!gestureOwner.has(id)) gestureOwner.set(id, "dom");
+      options.onGestureStart?.(node.id, id);
+      node.dispatchEvent(new VectoJSEvent("pointerdown", node, e, true, void 0, "dom"));
+    }
+    if (mode === "selection") e.stopPropagation();
+  };
+  for (const type of PRESS_EVENTS) on(type, pressCapture, true);
+  for (const type of POINTER_EVENTS) {
+    on(type, (e) => {
+      if (type === "pointerup" || type === "pointercancel") {
+        const id = e.pointerId ?? 0;
+        gestureOwner.delete(id);
+        options.onGestureEnd?.(node.id, id);
+      }
+      node.dispatchEvent(new VectoJSEvent(type, node, e, true, void 0, "dom"));
+    });
+  }
+  const hoverEvents = [
+    { native: "mouseenter", vecto: "hover" },
+    { native: "mouseleave", vecto: "pointerleave" }
+  ];
+  for (const { native, vecto } of hoverEvents) {
+    on(native, (e) => {
+      node.dispatchEvent(new VectoJSEvent(vecto, node, e, false, void 0, "dom"));
+    });
+  }
+  for (const type of ["focus", "blur"]) {
+    on(
+      type,
+      (e) => {
+        node.dispatchEvent(new VectoJSEvent(type, node, e, true, void 0, "dom"));
+      },
+      true
+    );
+  }
+  if (options.editable) {
+    const forwardEditable = (e) => {
+      const target = e.target;
+      if (target && "value" in target) options.onNativeInput?.(target.value);
+      node.dispatchEvent(new VectoJSEvent("change", node, e, true, void 0, "dom"));
+    };
+    on("input", forwardEditable);
+    on("change", forwardEditable);
+    on("compositionstart", forwardEditable);
+    on("compositionupdate", forwardEditable);
+    on("compositionend", forwardEditable);
+  }
+  let released = false;
+  return {
+    setInteractionMode(next) {
+      mode = next;
+    },
+    getInteractionMode() {
+      return mode;
+    },
+    release() {
+      if (released) return;
+      released = true;
+      for (const { type, handler, capture } of listeners) {
+        el.removeEventListener(type, handler, capture);
+      }
+      listeners.length = 0;
+    }
+  };
+}
+
+// src/matrix.ts
+function affineToMatrix3d(m) {
+  return `matrix3d(${m.a}, ${m.b}, 0, 0, ${m.c}, ${m.d}, 0, 0, 0, 0, 1, 0, ${m.e}, ${m.f}, 0, 1)`;
+}
+
+// src/DOMProjection.ts
+var DOM_VISUAL_Z_INDEX = "9";
+var DOM_ROOT_ATTR = "data-vecto-dom-root";
+var POOL_CAP_PER_TAG = 8;
+function strProp(node, key) {
+  const value = node[key];
+  return typeof value === "string" ? value : void 0;
+}
+function writeField(cached, key, next, apply, onWrite) {
+  const prev = cached.get(key);
+  const nextKey = next === void 0 ? "@removed" : `@value:${next}`;
+  if (prev === nextKey) return false;
+  cached.set(key, nextKey);
+  apply(next);
+  onWrite?.();
+  return true;
+}
+var textSpec = {
+  tag: "div",
+  create(_node) {
+    const el = document.createElement("div");
+    el.style.userSelect = "text";
+    return el;
+  },
+  sync(node, el, fields) {
+    fields.write("text", strProp(node, "text") ?? "", (v) => {
+      el.textContent = v ?? "";
+    });
+  }
+};
+var buttonSpec = {
+  tag: "button",
+  create(_node) {
+    return document.createElement("button");
+  },
+  sync(node, el, fields) {
+    fields.write("label", strProp(node, "label") ?? "", (v) => {
+      el.textContent = v ?? "";
+    });
+  }
+};
+var inputSpec = {
+  tag: "input",
+  create(_node) {
+    return document.createElement("input");
+  },
+  sync(node, el, fields) {
+    const input = el;
+    if (document.activeElement !== el) {
+      fields.write("value", strProp(node, "value") ?? "", (v) => {
+        input.value = v ?? "";
+      });
+    }
+    fields.write("placeholder", strProp(node, "placeholder"), (v) => {
+      if (v === void 0) input.removeAttribute("placeholder");
+      else input.setAttribute("placeholder", v);
+    });
+  }
+};
+var passthroughSpec = (tag) => ({
+  tag,
+  create(_node) {
+    return document.createElement(tag);
+  },
+  sync(_node, _el, _fields) {
+  }
+});
+var fallbackSpec = passthroughSpec("div");
+var DOMProjection = class {
+  kind = "dom";
+  root = null;
+  sentinel = null;
+  states = /* @__PURE__ */ new Map();
+  pools = /* @__PURE__ */ new Map();
+  kinds = /* @__PURE__ */ new Map();
+  bridgeOptions;
+  /** Nodes owning a live press: `pointerId`s per node id (RFC4 §5 pin source). */
+  activeGestures = /* @__PURE__ */ new Map();
+  mountSeq = 0;
+  stats = {
+    mounts: 0,
+    unmounts: 0,
+    transformWrites: 0,
+    opacityWrites: 0,
+    sizeWrites: 0,
+    contentWrites: 0,
+    poolHits: 0,
+    poolMisses: 0
+  };
+  /**
+   * @param canvas - The scene's canvas. The root is appended to its
+   *   `parentElement` (inserted before `a11yRoot` when present so the
+   *   below-a11y layer holds even on `zIndex` ties). Without a DOM (SSR) or
+   *   without a parent, the backend constructs but never goes resident — the
+   *   walk then falls through to canvas paint.
+   */
+  constructor(canvas, bridgeOptions = {}) {
+    this.bridgeOptions = bridgeOptions;
+    this.kinds.set("text", textSpec);
+    this.kinds.set("button", buttonSpec);
+    this.kinds.set("input", inputSpec);
+    this.kinds.set("container", passthroughSpec("div"));
+    this.kinds.set("transform", passthroughSpec("div"));
+    if (typeof document === "undefined") return;
+    const parent = canvas.parentElement;
+    if (!parent) return;
+    const root = document.createElement("div");
+    root.setAttribute(DOM_ROOT_ATTR, "");
+    root.style.position = "absolute";
+    root.style.top = "0";
+    root.style.left = "0";
+    root.style.width = "100%";
+    root.style.height = "100%";
+    root.style.pointerEvents = "none";
+    root.style.overflow = "hidden";
+    root.style.zIndex = DOM_VISUAL_Z_INDEX;
+    const sentinel = document.createElement("div");
+    sentinel.tabIndex = -1;
+    sentinel.setAttribute("aria-hidden", "true");
+    sentinel.style.position = "absolute";
+    sentinel.style.width = "0";
+    sentinel.style.height = "0";
+    sentinel.style.overflow = "hidden";
+    root.appendChild(sentinel);
+    this.sentinel = sentinel;
+    const a11yRoot = parent.querySelector("[data-vecto-a11y-root]");
+    if (a11yRoot) parent.insertBefore(root, a11yRoot);
+    else parent.appendChild(root);
+    this.root = root;
+  }
+  /** Register (or replace) a custom `domKind` (RFC §4.1 custom nodes). */
+  registerKind(kind, spec) {
+    this.kinds.set(kind, spec);
+  }
+  /** Telemetry counters (cumulative). */
+  getStats() {
+    return { ...this.stats };
+  }
+  /** The DOM-visual root, if constructed (null under SSR). */
+  getRoot() {
+    return this.root;
+  }
+  /** Live element for a resident node, if any. */
+  getElement(nodeId) {
+    return this.states.get(nodeId)?.el;
+  }
+  /**
+   * Whether `node` currently owns an active press on its live element
+   * (`ProjectionBackend.hasActiveGesture`, RFC4 §5). The scene consults this
+   * during `'auto'` negotiation so a node never flips backends mid-gesture.
+   */
+  hasActiveGesture(node) {
+    return (this.activeGestures.get(node.id)?.size ?? 0) > 0;
+  }
+  /** Last ResizeObserver-measured intrinsic size, if observed. */
+  getIntrinsicSize(nodeId) {
+    const state = this.states.get(nodeId);
+    if (!state || state.intrinsicWidth === 0) return void 0;
+    return { width: state.intrinsicWidth, height: state.intrinsicHeight };
+  }
+  /** Resolve the creation spec for a node (custom kinds win; unknown = plain div). */
+  specFor(node) {
+    return this.kinds.get(node.domKind) ?? fallbackSpec;
+  }
+  mount(node) {
+    if (this.states.has(node.id) || !this.root || typeof document === "undefined") return;
+    const spec = this.specFor(node);
+    let el = this.pools.get(spec.tag)?.pop();
+    if (el) {
+      this.stats.poolHits += 1;
+      if (node.domKind === "text") el.style.userSelect = "text";
+      el.style.display = "";
+    } else {
+      this.stats.poolMisses += 1;
+      el = spec.create(node);
+    }
+    el.style.position = "absolute";
+    el.style.left = "0px";
+    el.style.top = "0px";
+    el.style.transformOrigin = "0 0";
+    el.style.pointerEvents = "auto";
+    el.setAttribute("data-vecto-id", node.id);
+    this.root.appendChild(el);
+    const bridge = attachDOMBridge(el, node, {
+      ...this.bridgeOptions,
+      editable: node.domKind === "input" || this.bridgeOptions.editable,
+      onGestureStart: (nodeId, pointerId) => {
+        this.bridgeOptions.onGestureStart?.(nodeId, pointerId);
+        let owned = this.activeGestures.get(nodeId);
+        if (!owned) {
+          owned = /* @__PURE__ */ new Set();
+          this.activeGestures.set(nodeId, owned);
+        }
+        owned.add(pointerId);
+      },
+      onGestureEnd: (nodeId, pointerId) => {
+        this.bridgeOptions.onGestureEnd?.(nodeId, pointerId);
+        const owned = this.activeGestures.get(nodeId);
+        if (owned) {
+          owned.delete(pointerId);
+          if (owned.size === 0) this.activeGestures.delete(nodeId);
+        }
+      },
+      onNativeInput: node.domKind === "input" ? (value) => {
+        node.value = value;
+      } : this.bridgeOptions.onNativeInput
+    });
+    const state = {
+      el,
+      bridge,
+      observer: null,
+      tag: spec.tag,
+      cached: /* @__PURE__ */ new Map(),
+      lastTransform: "",
+      lastOpacity: "",
+      lastWidth: "",
+      lastHeight: "",
+      intrinsicWidth: 0,
+      intrinsicHeight: 0
+    };
+    if (typeof ResizeObserver !== "undefined") {
+      const observer = new ResizeObserver((entries) => {
+        const current = this.states.get(node.id);
+        if (!current) return;
+        for (const entry of entries) {
+          current.intrinsicWidth = entry.contentRect.width || entry.target.offsetWidth;
+          current.intrinsicHeight = entry.contentRect.height || entry.target.offsetHeight;
+        }
+      });
+      observer.observe(el);
+      state.observer = observer;
+    }
+    this.states.set(node.id, state);
+    el.style.zIndex = String(1 + this.mountSeq++);
+    node.domResident = true;
+    this.stats.mounts += 1;
+  }
+  update(node, worldMatrix) {
+    let state = this.states.get(node.id);
+    if (!state) {
+      this.mount(node);
+      state = this.states.get(node.id);
+      if (!state) return;
+    }
+    const transformStr = affineToMatrix3d(worldMatrix);
+    if (state.lastTransform !== transformStr) {
+      state.el.style.transform = transformStr;
+      state.lastTransform = transformStr;
+      this.stats.transformWrites += 1;
+    }
+    let opacity = 1;
+    let cursor = node;
+    let depth = 0;
+    while (cursor && depth < 32) {
+      opacity *= cursor.opacity;
+      cursor = cursor.parent;
+      depth += 1;
+    }
+    const opacityStr = String(opacity);
+    if (state.lastOpacity !== opacityStr) {
+      state.el.style.opacity = opacityStr;
+      state.lastOpacity = opacityStr;
+      this.stats.opacityWrites += 1;
+    }
+    if (node.width > 0 || node.height > 0) {
+      const widthStr = node.width > 0 ? `${node.width}px` : "";
+      const heightStr = node.height > 0 ? `${node.height}px` : "";
+      if (state.lastWidth !== widthStr || state.lastHeight !== heightStr) {
+        state.el.style.width = widthStr;
+        state.el.style.height = heightStr;
+        state.lastWidth = widthStr;
+        state.lastHeight = heightStr;
+        this.stats.sizeWrites += 1;
+      }
+    }
+    const spec = this.specFor(node);
+    const cached = state.cached;
+    const fields = {
+      write: (key, next, apply) => writeField(cached, key, next, apply, () => {
+        this.stats.contentWrites += 1;
+      })
+    };
+    spec.sync(node, state.el, fields);
+  }
+  unmount(node) {
+    const state = this.states.get(node.id);
+    this.activeGestures.delete(node.id);
+    node.domResident = false;
+    if (!state) return;
+    state.bridge.release();
+    if (typeof document !== "undefined") {
+      const active = document.activeElement;
+      if (active && active !== document.body && state.el.contains(active)) {
+        this.sentinel?.focus({ preventScroll: true });
+      }
+    }
+    state.observer?.disconnect();
+    state.el.remove();
+    const pool = this.pools.get(state.tag) ?? [];
+    if (pool.length < POOL_CAP_PER_TAG) {
+      pool.push(state.el);
+      this.pools.set(state.tag, pool);
+    }
+    this.states.delete(node.id);
+    this.stats.unmounts += 1;
+  }
+  /** Unmount every resident node and remove the root (scene teardown). */
+  dispose() {
+    for (const id of [...this.states.keys()]) {
+      const state = this.states.get(id);
+      if (!state) continue;
+      state.bridge.release();
+      state.observer?.disconnect();
+      state.el.remove();
+    }
+    this.states.clear();
+    this.pools.clear();
+    this.activeGestures.clear();
+    this.root?.remove();
+    this.root = null;
+    this.sentinel = null;
+  }
+};
+
+// src/nodes.ts
+import { Entity } from "@vectojs/core";
+var DOMText = class extends Entity {
+  text;
+  constructor(id, text = "", width = 200, height = 24) {
+    super(id);
+    this.text = text;
+    this.width = width;
+    this.height = height;
+    this.domPolicy = "dom";
+    this.domKind = "text";
+    this.interactive = true;
+  }
+  getBounds() {
+    if (this.width <= 0 || this.height <= 0) return null;
+    return { x: 0, y: 0, width: this.width, height: this.height };
+  }
+  isPointInside(globalX, globalY) {
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.width && local.y >= 0 && local.y <= this.height;
+  }
+  render() {
+  }
+  getA11yAttributes() {
+    return { tag: "div", role: "text", label: this.text };
+  }
+};
+var DOMButton = class extends Entity {
+  label;
+  constructor(id, label = "", width = 120, height = 36) {
+    super(id);
+    this.label = label;
+    this.width = width;
+    this.height = height;
+    this.domPolicy = "dom";
+    this.domKind = "button";
+    this.interactive = true;
+  }
+  getBounds() {
+    if (this.width <= 0 || this.height <= 0) return null;
+    return { x: 0, y: 0, width: this.width, height: this.height };
+  }
+  isPointInside(globalX, globalY) {
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.width && local.y >= 0 && local.y <= this.height;
+  }
+  render() {
+  }
+  getA11yAttributes() {
+    return { tag: "button", role: "button", label: this.label };
+  }
+};
+var DOMInput = class extends Entity {
+  value;
+  placeholder;
+  constructor(id, value = "", width = 200, height = 32) {
+    super(id);
+    this.value = value;
+    this.width = width;
+    this.height = height;
+    this.domPolicy = "dom";
+    this.domKind = "input";
+    this.interactive = true;
+  }
+  getBounds() {
+    if (this.width <= 0 || this.height <= 0) return null;
+    return { x: 0, y: 0, width: this.width, height: this.height };
+  }
+  isPointInside(globalX, globalY) {
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.width && local.y >= 0 && local.y <= this.height;
+  }
+  render() {
+  }
+  getA11yAttributes() {
+    return { tag: "input", role: "textbox", label: this.placeholder ?? "input", value: this.value };
+  }
+};
+var DOMContainer = class extends Entity {
+  constructor(id, width = 0, height = 0) {
+    super(id);
+    this.width = width;
+    this.height = height;
+    this.domPolicy = "dom";
+    this.domKind = "container";
+    this.interactive = true;
+  }
+  getBounds() {
+    if (this.width <= 0 || this.height <= 0) return null;
+    return { x: 0, y: 0, width: this.width, height: this.height };
+  }
+  isPointInside(globalX, globalY) {
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.width && local.y >= 0 && local.y <= this.height;
+  }
+  render() {
+  }
+};
+var DOMTransform = class extends Entity {
+  constructor(id) {
+    super(id);
+    this.domPolicy = "dom";
+    this.domKind = "transform";
+    this.interactive = true;
+  }
+  getBounds() {
+    return null;
+  }
+  isPointInside(_globalX, _globalY) {
+    return false;
+  }
+  render() {
+  }
+};
+export {
+  DOMButton,
+  DOMContainer,
+  DOMInput,
+  DOMProjection,
+  DOMText,
+  DOMTransform,
+  DOM_ROOT_ATTR,
+  DOM_VISUAL_Z_INDEX,
+  affineToMatrix3d,
+  attachDOMBridge,
+  getGestureOwner,
+  writeField
+};

package/dist/matrix.d.ts

@@ -0,0 +1,16 @@
+import type { AffineTransform } from '@vectojs/core';
+/**
+ * Embed a 2D world affine matrix as a CSS `matrix3d()` string (RFC §5 rule 1).
+ *
+ * The affine `[a c e; b d f; 0 0 1]` becomes the 4x4 column-major
+ * `matrix3d(a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, e, f, 0, 1)`. One code path for
+ * 2D and camera-composed 3D scenes (uniformity preferred over the portal
+ * path's `matrix(...)`; per-frame string cost at realistic DOM-node counts is
+ * unmeasured — RFC §11 risk 4 — so this stays behind the same per-field
+ * dirty check the portals use, and steady-state frames write nothing).
+ *
+ * Correctness note: the browser renders the element (selection highlight,
+ * caret, focus ring, children) _first_ and transforms the rendered result
+ * after, which is why selection keeps its perspective shape under rotation.
+ */
+export declare function affineToMatrix3d(m: AffineTransform): string;

package/dist/nodes.d.ts

@@ -0,0 +1,62 @@
+import { Entity, type A11yAttributes, type Bounds } from '@vectojs/core';
+/**
+ * P1 prototype node set (RFC §3/§4.1, research P1): explicit per-node opt-in
+ * only — each class sets `domPolicy = 'dom'` in its constructor. `'auto'`
+ * switching heuristics are CTX-0601 and out of scope.
+ *
+ * All five render as no-ops on canvas: while resident, the live element owns
+ * the visuals (the Scene walk skips canvas paint for resident leaves). If the
+ * backend is absent (SSR) the walk falls through to canvas — where these paint
+ * nothing — and `getA11yAttributes` keeps the transparent-mirror fallback
+ * meaningful if the policy flips back to `'canvas'`.
+ */
+/** Selectable/copyable prose → `div` with `user-select: text`. */
+export declare class DOMText extends Entity {
+    text: string;
+    constructor(id?: string, text?: string, width?: number, height?: number);
+    getBounds(): Bounds | null;
+    isPointInside(globalX: number, globalY: number): boolean;
+    render(): void;
+    getA11yAttributes(): A11yAttributes;
+}
+/** Native pressable control → `button`. Clicks arrive via the event bridge. */
+export declare class DOMButton extends Entity {
+    label: string;
+    constructor(id?: string, label?: string, width?: number, height?: number);
+    getBounds(): Bounds | null;
+    isPointInside(globalX: number, globalY: number): boolean;
+    render(): void;
+    getA11yAttributes(): A11yAttributes;
+}
+/**
+ * Native text entry → `input`. Typing and IME composition work with zero
+ * framework key handling; the bridge syncs the element value back onto
+ * {@link value} and forwards `VectoJSEvent('change')`.
+ */
+export declare class DOMInput extends Entity {
+    value: string;
+    placeholder?: string;
+    constructor(id?: string, value?: string, width?: number, height?: number);
+    getBounds(): Bounds | null;
+    isPointInside(globalX: number, globalY: number): boolean;
+    render(): void;
+    getA11yAttributes(): A11yAttributes;
+}
+/**
+ * Grouping node → plain `div`. Non-leaf residents keep the walk recursing so
+ * opted-in descendants stay synced; canvas-policy children paint at the same
+ * world coordinates, so mixed subtrees compose.
+ */
+export declare class DOMContainer extends Entity {
+    constructor(id?: string, width?: number, height?: number);
+    getBounds(): Bounds | null;
+    isPointInside(globalX: number, globalY: number): boolean;
+    render(): void;
+}
+/** Transform-only grouping node → pass-through `div` (position/rotation/scale). */
+export declare class DOMTransform extends Entity {
+    constructor(id?: string);
+    getBounds(): Bounds | null;
+    isPointInside(_globalX: number, _globalY: number): boolean;
+    render(): void;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vectojs/dom",
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "DOM visual projection backend for VectoJS (RFC2 P1): selected subtrees materialize as live HTMLElements positioned by their world matrix.",
+  "keywords": [
+    "dom",
+    "projection",
+    "accessibility",
+    "vectojs",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vectojs/vectojs.git",
+    "directory": "packages/dom"
+  },
+  "bugs": {
+    "url": "https://github.com/vectojs/vectojs/issues"
+  },
+  "homepage": "https://github.com/vectojs/vectojs#readme",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "(cd ../core && bun run build) && tsup src/index.ts --format cjs,esm --external @vectojs/core --clean && tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vectojs/core": "^1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "esbuild": "^0.28.1",
+    "jsdom": "^30.0.1",
+    "tsup": "^8.3.5",
+    "vitest": "^4.1.11"
+  }
+}