@vectojs/dom 0.2.0

package/dist/DOMProjection.d.ts

@@ -0,0 +1,112 @@
+import type { AffineTransform, Entity, ProjectionBackend } from '@vectojs/core';
+import { type DOMBridgeOptions } from './eventBridge';
+/** Layer of the DOM-visual root: the `portalRoot` family, below a11y (RFC §7). */
+export declare const DOM_VISUAL_Z_INDEX = "9";
+/** Attribute marking the DOM-visual root and every projected element. */
+export declare const DOM_ROOT_ATTR = "data-vecto-dom-root";
+/** Telemetry counters (also the dirty-check assertions tests pin). */
+export interface DOMProjectionStats {
+    mounts: number;
+    unmounts: number;
+    transformWrites: number;
+    opacityWrites: number;
+    sizeWrites: number;
+    contentWrites: number;
+    poolHits: number;
+    poolMisses: number;
+}
+/**
+ * Dirty-checked field writer handed to kind specs (RFC §4.2,
+ * `A11yAttributes` precedent: `undefined` removes, values write only on
+ * change). Returns true when the DOM was actually touched.
+ */
+export interface DOMSyncFields {
+    write(key: string, next: string | undefined, apply: (value: string | undefined) => void): boolean;
+}
+/**
+ * Creation + content contract for one `domKind` (RFC §4.1 step 1).
+ *
+ * This registry is the boundary-rule answer to "custom nodes supply
+ * `createDOMElement()`": that method cannot live on core `Entity` (it would be
+ * new `HTMLElement` surface in core), so custom kinds register here per
+ * projection instance. `sync` must touch the DOM only on change (via
+ * `fields`) so steady-state frames write nothing (RFC §4.2).
+ */
+export interface DOMKindSpec {
+    /** Element tag (pool key; must match what `create` returns). */
+    tag: string;
+    /** Create (not pool — pooling is the backend's job) the element for `node`. */
+    create(node: Entity): HTMLElement;
+    /** Sync node content/attributes into `el`, dirty-checked via `fields`. */
+    sync(node: Entity, el: HTMLElement, fields: DOMSyncFields): void;
+}
+/**
+ * Single-field dirty check behind {@link DOMSyncFields}. `undefined` means
+ * "remove" and is cached distinctly from any string, so a removed-then-absent
+ * field does not re-apply every frame.
+ */
+export declare function writeField(cached: Map<string, string>, key: string, next: string | undefined, apply: (value: string | undefined) => void, onWrite?: () => void): boolean;
+/**
+ * The `DOMProjection` (`'dom'`) backend (RFC §§4/5/6/7, P1 prototype).
+ *
+ * The scene keeps owning nodes, layout, visibility, lifecycle, and events;
+ * this backend owns _how a `'dom'`-policy node appears_: one live
+ * `HTMLElement` per resident node under a dedicated root, positioned per frame
+ * by the node's world matrix as CSS `matrix3d()` with `transform-origin: 0 0`.
+ *
+ * Layer rule (RFC §7): cross-backend ordering is layer-based, never
+ * pixel-depth-based. The root joins the `portalRoot` family at `zIndex 9`,
+ * below `a11yRoot` at 10 — a projected node at `position.z = -500` still
+ * paints over canvas content, by design, with no per-pixel occlusion.
+ *
+ * Only 100% browser/display zoom is supported (inherited CSS3DRenderer limit,
+ * RFC §5 rule 5): non-100% zoom misaligns `matrix3d` spacing (upstream
+ * `mrdoob/three.js#3225`). Documented, not fixed.
+ */
+export declare class DOMProjection implements ProjectionBackend {
+    readonly kind: 'dom';
+    private root;
+    private sentinel;
+    private readonly states;
+    private readonly pools;
+    private readonly kinds;
+    private readonly bridgeOptions;
+    /** Nodes owning a live press: `pointerId`s per node id (RFC4 §5 pin source). */
+    private readonly activeGestures;
+    private mountSeq;
+    private readonly stats;
+    /**
+     * @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: HTMLCanvasElement, bridgeOptions?: DOMBridgeOptions);
+    /** Register (or replace) a custom `domKind` (RFC §4.1 custom nodes). */
+    registerKind(kind: string, spec: DOMKindSpec): void;
+    /** Telemetry counters (cumulative). */
+    getStats(): DOMProjectionStats;
+    /** The DOM-visual root, if constructed (null under SSR). */
+    getRoot(): HTMLDivElement | null;
+    /** Live element for a resident node, if any. */
+    getElement(nodeId: string): HTMLElement | undefined;
+    /**
+     * 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: Entity): boolean;
+    /** Last ResizeObserver-measured intrinsic size, if observed. */
+    getIntrinsicSize(nodeId: string): {
+        width: number;
+        height: number;
+    } | undefined;
+    /** Resolve the creation spec for a node (custom kinds win; unknown = plain div). */
+    private specFor;
+    mount(node: Entity): void;
+    update(node: Entity, worldMatrix: AffineTransform): void;
+    unmount(node: Entity): void;
+    /** Unmount every resident node and remove the root (scene teardown). */
+    dispose(): void;
+}

package/dist/eventBridge.d.ts

@@ -0,0 +1,57 @@
+import { type Entity } from '@vectojs/core';
+/**
+ * Interaction policy for projected elements (RFC §6 layer 2).
+ *
+ * - `'selection'`: content-interaction mode. Presses mean "select text / press
+ *   button / type" and never reach the scene's camera/gesture handlers (the
+ *   demo's Selection mode: left goes to content).
+ * - `'orbit'`: scene-gesture mode. Presses pass through to camera handlers
+ *   (the demo's Orbit mode: left rotates).
+ */
+export type DOMInteractionMode = 'selection' | 'orbit';
+/** Options for {@link attachDOMBridge}. */
+export interface DOMBridgeOptions {
+    /**
+     * Native `input`/`change` (and IME composition) on the element forward as
+     * `VectoJSEvent('change')`, mirroring the a11y input-mirror contract whose
+     * payload is `{ value, ... }`. Set for editable kinds only.
+     */
+    editable?: boolean;
+    /**
+     * Called with the element's current value on every native `input` event
+     * (before the `'change'` dispatch), so the node can sync without the bridge
+     * knowing the node's shape.
+     */
+    onNativeInput?: (value: string) => void;
+    /** Starting interaction mode (default `'selection'`). */
+    mode?: DOMInteractionMode;
+    /**
+     * Called when a press elects this node as the gesture owner for a
+     * `pointerId` (RFC4 §5 never-flip-inside-gesture: the scene pins the node's
+     * backend until the matching end). Paired with {@link onGestureEnd}.
+     */
+    onGestureStart?: (nodeId: string, pointerId: number) => void;
+    /**
+     * Called when the owning gesture releases (`pointerup`/`pointercancel`),
+     * unpinning what {@link onGestureStart} pinned. A release can arrive
+     * without a start on this element (press began outside, released inside),
+     * so the consumer must tolerate an unmatched end.
+     */
+    onGestureEnd?: (nodeId: string, pointerId: number) => void;
+}
+/** Handle returned by {@link attachDOMBridge}. */
+export interface DOMBridgeHandle {
+    /** Switch the §6 layer-2 policy at runtime. */
+    setInteractionMode(mode: DOMInteractionMode): void;
+    /** Current policy. */
+    getInteractionMode(): DOMInteractionMode;
+    /** Remove every listener this bridge installed. Idempotent. */
+    release(): void;
+}
+/** Test/contract introspection: who owns `pointerId`, if anyone. */
+export declare function getGestureOwner(pointerId: number): string | undefined;
+/**
+ * Bridge native DOM events on a projected element into the Vecto event system.
+ * Idempotent release; safe to re-attach after an unmount cycle.
+ */
+export declare function attachDOMBridge(el: HTMLElement, node: Entity, options?: DOMBridgeOptions): DOMBridgeHandle;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@vectojs/dom` — DOM visual projection backend for VectoJS (RFC2 P1).
+ *
+ * The scene graph keeps owning nodes, layout, visibility, lifecycle, and
+ * events; selected subtrees (explicit per-node `domPolicy === 'dom'` opt-in)
+ * materialize as live `HTMLElement`s positioned by their world matrix. Depends
+ * on `@vectojs/core`, never the reverse.
+ */
+export { DOMProjection, writeField, DOM_VISUAL_Z_INDEX, DOM_ROOT_ATTR } from './DOMProjection';
+export type { DOMProjectionStats, DOMKindSpec, DOMSyncFields } from './DOMProjection';
+export { attachDOMBridge, getGestureOwner } from './eventBridge';
+export type { DOMInteractionMode, DOMBridgeOptions, DOMBridgeHandle } from './eventBridge';
+export { affineToMatrix3d } from './matrix';
+export { DOMText, DOMButton, DOMInput, DOMContainer, DOMTransform } from './nodes';