@vectojs/core 1.38.1 → 1.39.1

package/README.md

@@ -1,18 +1,12 @@
 # @vectojs/core
 
-> Scene, layout, interaction, text, rendering, and semantic projection for canvas-native interfaces.
-
-[![npm](https://img.shields.io/npm/v/@vectojs/core?color=22d3ee)](https://www.npmjs.com/package/@vectojs/core)
-[![CI](https://github.com/vectojs/vectojs/actions/workflows/ci.yml/badge.svg)](https://github.com/vectojs/vectojs/actions/workflows/ci.yml)
-[![MIT](https://img.shields.io/badge/license-MIT-6366f1.svg)](https://github.com/vectojs/vectojs/blob/main/LICENSE)
-
-`@vectojs/core` is the runtime beneath VectoJS. It owns the retained `Scene`/`Entity` tree, affine
-transforms, render scheduling, layout, text flow, spatial hit-testing, event propagation, renderer
-backends, and the accessibility/automation projection layer.
-
-[Core guide](https://vectojs.org/learn/core-scene/) ·
-[API reference](https://vectojs.org/reference/core-api/) ·
-[Main repository](https://github.com/vectojs/vectojs)
+`@vectojs/core` is the runtime at the root of the VectoJS dependency graph: a retained
+`Scene`/`Entity` scene graph (the Virtual Math Tree) that renders to a single canvas, with
+transforms, render scheduling, spatial hit-testing, DOM-like event propagation, layout and text
+engines, Canvas/SVG/WebGL/WebGPU renderer backends, and the accessibility/automation projection
+layer. It is also the composition point of the framework — it depends on and re-exports
+`@vectojs/layout`, `@vectojs/text`, `@vectojs/math`, and `@vectojs/animation`, so `@vectojs/ui`
+and every higher-level package build directly on it.
 
 ## Install
 
@@ -20,7 +14,7 @@ backends, and the accessibility/automation projection layer.
 bun add @vectojs/core
 ```
 
-## Minimal scene
+## Usage
 
 ```ts
 import { Entity, type IRenderer, Scene } from '@vectojs/core';
@@ -57,124 +51,38 @@ scene.add(new Dot().setPosition(80, 80));
 scene.start();
 ```
 
-## Runtime building blocks
-
-| Area        | Main APIs                                       | Purpose                                                                |
-| ----------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
-| Scene graph | `Scene`, `Entity`                               | ownership, transforms, lifecycle, update/render traversal              |
-| Layout      | `LayoutEngine`, layout subpath                  | prepared text/rich-text layout, wrapping, exclusions, reusable buffers |
-| Interaction | entity events, `SpatialHashGrid`                | hit-testing and DOM-like capture/bubble dispatch                       |
-| Text        | `TextEntity`, `MSDFTextEntity`, `SplineEntity`  | Canvas text, GPU text, and mathematical curves                         |
-| Rendering   | `IRenderer`, `CanvasRenderer`, renderer subpath | backend-neutral drawing contract and concrete renderers                |
-| GPU paths   | WebGL point batching, WebGPU particles          | high-volume points/rects and compute-driven particles                  |
-| Semantics   | `A11yAttributes`, Scene projection              | role/name/state, native inputs, screen readers, Playwright/agents      |
-| Animation   | `animate`, springs, transitions, `Scene.step()` | real-time or deterministic fixed-step motion                           |
-
-## Scene lifecycle
-
-```ts
-const scene = new Scene(canvas, {
-  maxFPS: 60,
-  pointBackend: 'canvas', // or 'webgl'
-  particleBackend: 'cpu', // or 'webgpu' when supported
-});
-scene.renderMode = 'onDemand'; // redraw only when dirty
-
-scene.resize(width, height); // logical CSS pixels
-scene.markDirty();
-scene.start();
-scene.stop();
-scene.step(1000 / 60); // deterministic single step
-scene.destroy(); // release renderers, workers, observers, and semantic DOM
-```
-
-Always call `destroy()` when a framework component unmounts. A `Scene` owns browser observers,
-renderer resources, layout work, and projected DOM nodes.
-
-## Package entry points
-
-```ts
-import { Scene, Entity } from '@vectojs/core';
-import { LayoutEngine } from '@vectojs/core/layout';
-import type { IRenderer } from '@vectojs/core/renderer';
-import { TextEntity } from '@vectojs/core/text';
-```
-
-Both ESM and CommonJS outputs are published with TypeScript declarations.
-
-## Accessibility and automation
-
-Canvas pixels have no semantics. Interactive entities can implement `getA11yAttributes()`; the
-Scene projects transparent DOM nodes over their world-space bounds and forwards native input back
-into the VectoJS event system.
-
-This projection is intentionally thin. Applications still own accessible names, keyboard behavior,
-focus order, contrast, and correct control semantics. See the
-[accessibility guide](https://vectojs.org/learn/accessibility/).
-
-Non-control workspaces that own keyboard shortcuts can opt into focus order
-explicitly: return `{ role: 'region', label: 'Canvas workspace', tabIndex: 0 }`.
-The Scene refreshes the projected `tabindex` when attributes change. Keep native
-text inputs and editable content in charge of their own editing shortcuts.
-
-Interactive projected nodes capture the active pointer on `pointerdown` and route
-`pointermove`, `pointerup`, and `pointercancel` through normal VMT capture/bubble propagation.
-Treat `pointercancel` as rollback: discard transient gesture state and do not create durable
-history. Pointer capture is released safely on both completion paths.
-
-## Static content projection
-
-Canvas-rendered text can opt into browser-native find, translation, selection, and copy without
-turning the application into a DOM layout. Override `getContentProjection()` on the owning Entity;
-the Scene creates a transparent, position-synchronized mirror while the VMT remains authoritative:
-
-```ts
-class SelectableLabel extends Entity {
-  getContentProjection() {
-    return {
-      text: 'Selectable canvas text',
-      font: '18px Inter',
-      lineHeight: 24,
-      selectable: true,
-    };
-  }
-}
-```
-
-`selectable` controls whether the mirror receives pointer input. The Scene keeps projection order
-aligned with VMT order, removes descendant mirrors with their subtree, and hides mirrors fully
-outside the viewport or a `clipChildren` ancestor. Tooling can inspect the currently materialized
-node with `scene.getContentElement(entityId)`. Virtualized or non-materialized off-viewport text is
-not searchable until the application brings it into the active scene.
-
-Code-like renderers can compile their logical source once with `prepareContentGrid()` and return the
-same immutable plan as `ContentProjection.grid`. The plan retains UTF-16 source ranges, legal
-grapheme carets, CR/LF ownership, tab stops, wide CJK/emoji advances, Arabic shaping, and Unicode
-bidi positions. Scene projects those cells in logical source order, performs font calibration in a
-cold offscreen batch, and uses the plan's local geometry for pointer selection even when the entity
-is rotated, scaled, or the page is zoomed.
-
-Selection routing preserves forward/reverse drag direction, Shift extension, word and line
-selection, and exact clipboard source. Projection rebuild/removal/destroy paths release active
-selection and pending calibration ownership before replacing DOM carriers.
-
-## Performance model
-
-Useful levers include on-demand rendering, viewport culling, spatial hashing, prepared text layout,
-typed reusable buffers, batched WebGL points, and optional WebGPU particle compute. None makes every
-workload allocation-free or GPU-bound; profile the renderer and entity types used by your app.
-
-Run the repository benchmarks with `bun run benchmark`, `bun run compare:dom`, and
-`bun run compare`. Prepared-grid scaling can be measured independently with
-`bun run --cwd packages/core benchmark:grid`; benchmark timing is release evidence rather than a
-wall-clock CI gate.
-
-## Related packages
-
-- [`@vectojs/ui`](https://github.com/vectojs/vectojs/tree/main/packages/ui) — high-level accessible components
-- [`@vectojs/three`](https://github.com/vectojs/vectojs/tree/main/packages/three) — Three.js/WebXR projection and raycast routing
-- [`@vectojs/video-exporter`](https://github.com/vectojs/vectojs/tree/main/packages/video-exporter) — deterministic H.264 capture
-
-## License
-
-[MIT](https://github.com/vectojs/vectojs/blob/main/LICENSE) © 2026 Xuepoo
+## Highlights
+
+- Retained `Scene`/`Entity` tree with affine transforms, capture/bubble event dispatch,
+  viewport culling, and dirty-flag `renderMode: 'onDemand'` rendering; `scene.step(dt)` drives a
+  deterministic frame for tests and video export.
+- Backend-neutral `IRenderer` drawing contract with modular backends: `CanvasRenderer`,
+  `SVGRenderer`, batched WebGL points (`WebGLPointRenderer`), and WebGPU particle compute
+  (`WebGPUParticleSystemManager`) — registered on load via `Scene.register*`, selected through
+  `pointBackend` / `particleBackend` options.
+- Optional Rust WASM kernels (`crates/vectojs-core-rs`) hot-swapped per subsystem with
+  `scene.enableWasmTransforms / enableWasmHitTest / enableWasmAnimBatching / enableWasmParticles`;
+  fallible exports return `WASM_STATUS` codes (`OK`/`CAPACITY`/`UNINITIALIZED`/`BAD_RUN`/
+  `OVERFLOW`) so any rejected batch degrades to the JS path instead of rendering half-written state.
+- Semantic accessibility projection: entities implementing `getA11yAttributes()` get transparent,
+  position-synchronized DOM mirrors for screen readers, keyboard users, Playwright, and AI agents;
+  static text opts into browser-native selection/find/copy through `getContentProjection()` and
+  Core's prepared content grid (`prepareContentGrid()`).
+- Entity-based text renderers stay here because they extend `Entity`: `TextEntity`,
+  `GridTextEntity`, GPU-resolved `MSDFTextEntity` (off-thread layout via `LayoutWorkerManager`),
+  `SVGEntity`, and `DOMPortalEntity`.
+- The standalone engines are re-exported from this barrel and remain available as subpaths, so
+  existing imports keep working:
+  `@vectojs/core/layout`, `@vectojs/core/text`, `@vectojs/core/renderer`.
+- Lifecycle ownership is explicit: a `Scene` owns renderers, workers, observers, and projected DOM
+  nodes; `scene.destroy()` releases all of them.
+
+> Documents @vectojs/core@1.39.0.
+
+## Documentation
+
+- [Core Scene architecture](https://vectojs.org/learn/core-scene/)
+- [`@vectojs/core` API reference](https://vectojs.org/reference/core-api/)
+- [`Entity` reference](https://vectojs.org/reference/core-entity/)
+- [Renderers reference](https://vectojs.org/reference/core-renderer/)
+- [Accessibility & automation guide](https://vectojs.org/learn/accessibility/)

package/dist/{chunk-QVTCKWDO.mjs → chunk-7PYD5UDX.mjs}

@@ -398,6 +398,18 @@ var Entity = class {
   }
   /** Attach a single child (the O(1) common path). See {@link add}. */
   _addOne(child) {
+    if (child === this) {
+      throw new Error(`Entity.add(): cannot add entity "${child.id}" under itself.`);
+    }
+    let ancestor = this.parent;
+    while (ancestor) {
+      if (ancestor === child) {
+        throw new Error(
+          `Entity.add(): cannot add entity "${child.id}" under "${this.id}" \u2014 an entity cannot be added under its own descendant.`
+        );
+      }
+      ancestor = ancestor.parent;
+    }
     if (child.parent) child.parent.remove(child);
     child.parent = this;
     this.children.push(child);
@@ -485,6 +497,19 @@ var Entity = class {
    * @example entity.animate({ x: 400, opacity: 0 }, 500);
    */
   animate(targetProps, durationMs) {
+    if (!Number.isFinite(durationMs) || durationMs <= 0) {
+      for (const key in targetProps) {
+        const end = targetProps[key];
+        if (typeof end !== "number") continue;
+        if (ANIMATABLE_PROPS.has(key)) {
+          this._applyAnimated(key, end);
+        } else {
+          this[key] = end;
+        }
+      }
+      this.scene?.markDirty({ entity: this.id, reason: "animation-start" });
+      return this;
+    }
     (this.animations ??= []).push({
       target: targetProps,
       duration: durationMs,
@@ -566,6 +591,11 @@ var Entity = class {
     const from = this._currentOf(prop);
     const driver = isTweenConfig(cfg) ? new TweenDriver(from, to, cfg) : new SpringDriver(from, to, cfg === "spring" ? {} : cfg);
     (this._drivers ??= /* @__PURE__ */ new Map()).set(prop, driver);
+    const s = this.scene;
+    if (s && this._driversTickedFrame === s.currentFrame && s._updateWalkDt !== null) {
+      driver.tick(s._updateWalkDt);
+      this._applyDriverTick(prop, driver);
+    }
     this.scene?.markDirty({ entity: this.id, reason: "driver-added" });
     this.scene?._registerActiveDriverEntity(this);
   }
@@ -652,10 +682,6 @@ var Entity = class {
       this._applyAnimated(prop, driver.value);
     }
   }
-  /** Internal: true if this entity currently has any active property driver. */
-  _hasActiveDrivers() {
-    return !!this._drivers && this._drivers.size > 0;
-  }
   /**
    * Advance the entity's internal state for one frame.
    *
@@ -1024,6 +1050,14 @@ var Entity = class {
    * Accumulated world rotation: this entity's own `rotation` plus
    * that of every ancestor.
    *
+   * Valid only under positive scales: the sum models the composed matrix
+   * `T*S*R` correctly while every ancestor's `scaleX`/`scaleY` is positive,
+   * but a mirrored (negative-scale) ancestor flips handedness, which an
+   * additive sum cannot represent — the result is then off by the mirror.
+   * For mirror-safe rotation, derive the angle from
+   * {@link getWorldTransform}'s matrix (e.g. `atan2(b, a)`), as SVGEntity's
+   * signed-scale handling already does.
+   *
    * @returns The accumulated world rotation in radians.
    */
   getWorldRotation() {
@@ -1242,7 +1276,6 @@ var MSDFTextEntity = class extends Entity {
   // long-lived shared atlas image would retain the whole entity.
   atlasDecodeTarget = null;
   atlasDecodeHandler = null;
-  rgbColorCache = /* @__PURE__ */ new Map();
   fontStringCache = [];
   layoutResult = null;
   /**
@@ -1429,7 +1462,12 @@ var MSDFTextEntity = class extends Entity {
       shaped.push(String.fromCodePoint(res.codePoints[i]));
     }
     const sourceWithoutNewlines = this.text.replace(/\n/g, "");
-    if (this.textAlign !== "left" || shaped.join("") !== sourceWithoutNewlines || res.yCoords.length !== res.codePoints.length) {
+    if (this.textAlign !== "left" || // The layout worker breaks lines on \n only, so a \r survives as a real
+    // glyph — a phantom ~1em advance at every CRLF line end — yet would
+    // still compare equal below after \n is stripped from both sides. The
+    // contract promises the coarse branch whenever the reply cannot
+    // reproduce the source exactly, and that includes any \r (#692).
+    this.text.includes("\r") || shaped.join("") !== sourceWithoutNewlines || res.yCoords.length !== res.codePoints.length) {
       this.projectionLines = [];
       return;
     }
@@ -1438,9 +1476,19 @@ var MSDFTextEntity = class extends Entity {
     const desc = metrics?.descender ?? -0.2;
     const actualLineHeight = this.lineHeight ?? this.fontSize * (asc - desc);
     const baseline = asc * this.fontSize;
-    const srcIdx = [];
-    for (let i = 0; i < this.text.length; i++) {
-      if (this.text[i] !== "\n") srcIdx.push(i);
+    const srcStart = [];
+    const srcEnd = [];
+    {
+      let cursor = 0;
+      while (cursor < this.text.length) {
+        const code = this.text.codePointAt(cursor);
+        const width = code > 65535 ? 2 : 1;
+        if (code !== 10) {
+          srcStart.push(cursor);
+          srcEnd.push(cursor + width);
+        }
+        cursor += width;
+      }
     }
     const glyphsByLine = /* @__PURE__ */ new Map();
     let maxIdx = -1;
@@ -1456,8 +1504,8 @@ var MSDFTextEntity = class extends Entity {
     let previousEnd = 0;
     for (let i = 0; i <= maxIdx; i++) {
       const glyphs = glyphsByLine.get(i) ?? [];
-      const start = glyphs.length > 0 ? srcIdx[glyphs[0]] : previousEnd;
-      const end = glyphs.length > 0 ? srcIdx[glyphs[glyphs.length - 1]] + 1 : start;
+      const start = glyphs.length > 0 ? srcStart[glyphs[0]] : previousEnd;
+      const end = glyphs.length > 0 ? srcEnd[glyphs[glyphs.length - 1]] : start;
       starts.push(start);
       ends.push(end);
       previousEnd = Math.max(previousEnd, end);
@@ -1510,7 +1558,6 @@ var MSDFTextEntity = class extends Entity {
         const code = this.layoutResult.codePoints[i];
         const nodeX = this.layoutResult.xCoords[i];
         const nodeY = this.layoutResult.yCoords[i];
-        const packedStyle = this.layoutResult.packedStyles[i];
         const def = this.font.getGlyph(code);
         if (!def || !def.atlasBounds || !def.planeBounds) continue;
         const { atlasBounds: ab, planeBounds: pb } = def;
@@ -1524,15 +1571,6 @@ var MSDFTextEntity = class extends Entity {
         const glyphH = (pb.top - pb.bottom) * this.fontSize * worldScaleY;
         const v0 = this.font.data.atlas.yOrigin === "bottom" ? 1 - ab.top / ah : ab.top / ah;
         const v1 = this.font.data.atlas.yOrigin === "bottom" ? 1 - ab.bottom / ah : ab.bottom / ah;
-        const colorVal = packedStyle >>> 8;
-        let runColor = this.rgbColorCache.get(colorVal);
-        if (!runColor) {
-          const r = colorVal >> 16 & 255;
-          const g = colorVal >> 8 & 255;
-          const b = colorVal & 255;
-          runColor = `rgb(${r},${g},${b})`;
-          this.rgbColorCache.set(colorVal, runColor);
-        }
         scene.pointRenderer.addGlyph(
           glyphX,
           glyphY,
@@ -1542,7 +1580,7 @@ var MSDFTextEntity = class extends Entity {
           v0,
           ab.right / aw,
           v1,
-          runColor,
+          this.color,
           worldOpacity,
           worldRot
         );
@@ -1562,16 +1600,7 @@ var MSDFTextEntity = class extends Entity {
       const nodeY = this.layoutResult.yCoords[i];
       const packedStyle = this.layoutResult.packedStyles[i];
       const fontString = this.fontStringCache[packedStyle & 3];
-      const colorVal = packedStyle >>> 8;
-      let runColor = this.rgbColorCache.get(colorVal);
-      if (!runColor) {
-        const r = colorVal >> 16 & 255;
-        const g = colorVal >> 8 & 255;
-        const b = colorVal & 255;
-        runColor = `rgb(${r},${g},${b})`;
-        this.rgbColorCache.set(colorVal, runColor);
-      }
-      renderer.fillText(String.fromCodePoint(code), nodeX, nodeY, fontString, runColor);
+      renderer.fillText(String.fromCodePoint(code), nodeX, nodeY, fontString, this.color);
     }
   }
   destroy() {
@@ -1586,11 +1615,32 @@ var SVG_NAMESPACE = "http://www.w3.org/2000/svg";
 function isSvgWhitespace(ch) {
   return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
 }
+function findSvgTagEnd(source, from) {
+  let quote = null;
+  for (let i = from; i < source.length; i++) {
+    const ch = source[i];
+    if (quote !== null) {
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === ">") {
+      return i;
+    }
+  }
+  return -1;
+}
+function isPercentDimension(value) {
+  return value.trim().endsWith("%");
+}
+function viewBoxDimensions(value) {
+  const parts = value.split(/[\s,]+/).map(parseFloat);
+  return parts.length === 4 && parts.every(Number.isFinite) ? { width: parts[2], height: parts[3] } : null;
+}
 function readSvgAttribute(source, name) {
   const lowerSource = source.toLowerCase();
   const svgStart = lowerSource.indexOf("<svg");
   if (svgStart < 0) return null;
-  const tagEnd = source.indexOf(">", svgStart + 4);
+  const tagEnd = findSvgTagEnd(source, svgStart + 4);
   if (tagEnd < 0) return null;
   const tag = source.slice(svgStart + 4, tagEnd);
   const lowerTag = tag.toLowerCase();
@@ -1662,14 +1712,14 @@ var SVGEntity = class extends Entity {
           const wAttr = svgEl.getAttribute("width");
           const hAttr = svgEl.getAttribute("height");
           const vbAttr = svgEl.getAttribute("viewBox");
-          if (wAttr && hAttr) {
+          if (wAttr && hAttr && !isPercentDimension(wAttr) && !isPercentDimension(hAttr)) {
             width = parseFloat(wAttr) || 100;
             height = parseFloat(hAttr) || 100;
           } else if (vbAttr) {
-            const parts = vbAttr.split(/[\s,]+/).map(parseFloat);
-            if (parts.length === 4) {
-              width = parts[2];
-              height = parts[3];
+            const dims = viewBoxDimensions(vbAttr);
+            if (dims) {
+              width = dims.width;
+              height = dims.height;
             }
           }
         }
@@ -1681,14 +1731,14 @@ var SVGEntity = class extends Entity {
       const wAttr = readSvgAttribute(this.svgSource, "width");
       const hAttr = readSvgAttribute(this.svgSource, "height");
       const vbAttr = readSvgAttribute(this.svgSource, "viewBox");
-      if (wAttr && hAttr) {
+      if (wAttr && hAttr && !isPercentDimension(wAttr) && !isPercentDimension(hAttr)) {
         width = parseFloat(wAttr) || 100;
         height = parseFloat(hAttr) || 100;
       } else if (vbAttr) {
-        const parts = vbAttr.split(/[\s,]+/).map(parseFloat);
-        if (parts.length === 4) {
-          width = parts[2];
-          height = parts[3];
+        const dims = viewBoxDimensions(vbAttr);
+        if (dims) {
+          width = dims.width;
+          height = dims.height;
         }
       }
     }