@vectojs/core 1.7.1 → 1.9.0

package/dist/index.mjs

@@ -3,7 +3,7 @@ import {
   LayoutResultBuffer,
   computeLineSegments,
   createCanvasMeasurer
-} from "./chunk-V7GUWG5C.mjs";
+} from "./chunk-X7I465AQ.mjs";
 import {
   CanvasRenderer,
   SVGRenderer,
@@ -25,13 +25,14 @@ import {
   VectoJSEvent,
   clearCssLineBoxMetrics,
   cssLineBoxBaseline,
-  isTweenConfig
-} from "./chunk-3CODWSF3.mjs";
+  isTweenConfig,
+  prepareContentGrid
+} from "./chunk-J2P6QZJV.mjs";
 import {
   ArabicShaper,
   BidiResolver,
   LayoutWorkerManager
-} from "./chunk-STWPTWO4.mjs";
+} from "./chunk-IESDTEJ4.mjs";
 
 // src/tree/ComputeParticleEntity.ts
 var PARTICLE_STRIDE_FLOATS = 8;
@@ -317,6 +318,297 @@ function parseInlinePx(value) {
   const n = parseFloat(value);
   return Number.isFinite(n) && n > 0 ? n : null;
 }
+function collectTextNodes(root) {
+  const out = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) out.push(n);
+  return out;
+}
+var caretGraphemeSegmenter = typeof Intl !== "undefined" && typeof Intl.Segmenter === "function" ? new Intl.Segmenter(void 0, { granularity: "grapheme" }) : null;
+var caretWordSegmenter = typeof Intl !== "undefined" && typeof Intl.Segmenter === "function" ? new Intl.Segmenter(void 0, { granularity: "word" }) : null;
+function graphemeBoundaries(text) {
+  if (!caretGraphemeSegmenter) {
+    const boundaries2 = [0];
+    for (let offset = 0; offset < text.length; ) {
+      const codePoint = text.codePointAt(offset) ?? 0;
+      offset += codePoint > 65535 ? 2 : 1;
+      boundaries2.push(offset);
+    }
+    return boundaries2;
+  }
+  const boundaries = [0];
+  for (const segment of caretGraphemeSegmenter.segment(text)) {
+    const end = segment.index + segment.segment.length;
+    if (end > boundaries[boundaries.length - 1]) boundaries.push(end);
+  }
+  return boundaries;
+}
+function distanceToRectSquared(rect, x, y) {
+  const dx = x < rect.left ? rect.left - x : x > rect.right ? x - rect.right : 0;
+  const dy = y < rect.top ? rect.top - y : y > rect.bottom ? y - rect.bottom : 0;
+  return dx * dx + dy * dy;
+}
+function nearestOffsetForPoint(node, x, y) {
+  const boundaries = graphemeBoundaries(node.data);
+  const range = document.createRange();
+  let nearest = { offset: boundaries[0] ?? 0, distance: Infinity };
+  for (const offset of boundaries) {
+    range.setStart(node, offset);
+    range.collapse(true);
+    const rect = range.getBoundingClientRect();
+    const distance = distanceToRectSquared(rect, x, y);
+    if (distance < nearest.distance) nearest = { offset, distance };
+  }
+  return nearest;
+}
+function gridCellCaret(cell, localX) {
+  const node = cell.firstChild;
+  if (!(node instanceof Text)) return null;
+  const sourceLength = Number(cell.dataset.vectoGridSourceLength ?? node.data.length);
+  const level = Number(cell.dataset.vectoGridLevel ?? 0);
+  const cellX = Number(cell.dataset.vectoGridX ?? 0);
+  const advance = Number(cell.dataset.vectoGridAdvance ?? 0);
+  const caretOffsets = (cell.dataset.vectoGridCaretOffsets ?? `0,${sourceLength}`).split(",").map(Number).filter((offset) => Number.isInteger(offset) && offset >= 0 && offset <= sourceLength);
+  const visuallyRtl = (level & 1) !== 0;
+  const visualFraction = advance > 0 ? Math.max(0, Math.min(1, (localX - cellX) / advance)) : 0;
+  const sourceFraction = visuallyRtl ? 1 - visualFraction : visualFraction;
+  const caretIndex = Math.round(sourceFraction * Math.max(0, caretOffsets.length - 1));
+  return {
+    node,
+    offset: caretOffsets[caretIndex] ?? 0
+  };
+}
+function nearestGridPositionInLine(line, localX) {
+  let nearest = null;
+  for (const cell of line.querySelectorAll("[data-vecto-grid-cell]")) {
+    const x = Number(cell.dataset.vectoGridX ?? 0);
+    const advance = Number(cell.dataset.vectoGridAdvance ?? 0);
+    if (localX >= x && localX <= x + advance) return gridCellCaret(cell, localX);
+    const distance = localX < x ? x - localX : localX - (x + advance);
+    if (!nearest || distance < nearest.distance) nearest = { cell, distance };
+  }
+  if (!nearest) return null;
+  return gridCellCaret(nearest.cell, localX);
+}
+function parseCssMatrix(transform) {
+  if (!transform || transform === "none") return [1, 0, 0, 1];
+  const values = transform.slice(transform.indexOf("(") + 1, transform.lastIndexOf(")")).split(",").map(Number);
+  return values.length >= 4 && values.slice(0, 4).every(Number.isFinite) ? [values[0], values[1], values[2], values[3]] : [1, 0, 0, 1];
+}
+function clientToGridLocal(contentEl, canvas, clientX, clientY) {
+  const line = contentEl.querySelector("[data-vecto-grid-line]");
+  const originMarker = line?.querySelector('[data-vecto-grid-basis="origin"]');
+  const xMarker = line?.querySelector('[data-vecto-grid-basis="x"]');
+  const yMarker = line?.querySelector('[data-vecto-grid-basis="y"]');
+  if (line && originMarker && xMarker && yMarker) {
+    const origin = originMarker.getBoundingClientRect();
+    const xPoint = xMarker.getBoundingClientRect();
+    const yPoint = yMarker.getBoundingClientRect();
+    const xx = xPoint.left - origin.left;
+    const xy = xPoint.top - origin.top;
+    const yx = yPoint.left - origin.left;
+    const yy = yPoint.top - origin.top;
+    const determinant2 = xx * yy - xy * yx;
+    if (Number.isFinite(determinant2) && Math.abs(determinant2) > 1e-9) {
+      const dx2 = clientX - origin.left;
+      const dy2 = clientY - origin.top;
+      return {
+        x: (Number.parseFloat(line.style.left) || 0) + (yy * dx2 - yx * dy2) / determinant2,
+        y: (Number.parseFloat(line.style.top) || 0) + (-xy * dx2 + xx * dy2) / determinant2
+      };
+    }
+  }
+  const [a, b, c, d] = parseCssMatrix(getComputedStyle(contentEl).transform);
+  const canvasRect = canvas.getBoundingClientRect();
+  const logicalWidth = Number.parseFloat(canvas.style.width) || canvas.clientWidth || canvas.width;
+  const logicalHeight = Number.parseFloat(canvas.style.height) || canvas.clientHeight || canvas.height;
+  const scaleX = logicalWidth > 0 ? canvasRect.width / logicalWidth : 1;
+  const scaleY = logicalHeight > 0 ? canvasRect.height / logicalHeight : 1;
+  const worldX = (clientX - canvasRect.left) / scaleX;
+  const worldY = (clientY - canvasRect.top) / scaleY;
+  const dx = worldX - (Number.parseFloat(contentEl.style.left) || 0);
+  const dy = worldY - (Number.parseFloat(contentEl.style.top) || 0);
+  const determinant = a * d - b * c;
+  if (!Number.isFinite(determinant) || Math.abs(determinant) <= 1e-9) return null;
+  return {
+    x: (d * dx - c * dy) / determinant,
+    y: (-b * dx + a * dy) / determinant
+  };
+}
+function nearestGridPosition(contentEl, canvas, clientX, clientY) {
+  const lines = [...contentEl.querySelectorAll("[data-vecto-grid-line]")];
+  if (lines.length === 0) return null;
+  const [a, b, c, d] = parseCssMatrix(getComputedStyle(contentEl).transform);
+  if (a > 0 && d > 0 && Math.abs(b) <= 1e-9 && Math.abs(c) <= 1e-9) {
+    let nearest2 = null;
+    for (const line of lines) {
+      const rect = line.getBoundingClientRect();
+      const dy = clientY < rect.top ? rect.top - clientY : clientY > rect.bottom ? clientY - rect.bottom : 0;
+      const dx = clientX < rect.left ? rect.left - clientX : clientX > rect.right ? clientX - rect.right : 0;
+      const distance = dy * 4096 + dx;
+      if (!nearest2 || distance < nearest2.distance) nearest2 = { line, distance, rect };
+    }
+    if (!nearest2) return null;
+    const localWidth = Number.parseFloat(nearest2.line.style.width) || 0;
+    const scaleX = localWidth > 0 && nearest2.rect.width > 0 ? nearest2.rect.width / localWidth : 1;
+    const localX = (clientX - nearest2.rect.left) / scaleX;
+    return nearestGridPositionInLine(nearest2.line, localX);
+  }
+  const local = clientToGridLocal(contentEl, canvas, clientX, clientY);
+  if (!local) return null;
+  let nearest = null;
+  for (const line of lines) {
+    const left = Number.parseFloat(line.style.left) || 0;
+    const top = Number.parseFloat(line.style.top) || 0;
+    const width = Number.parseFloat(line.style.width) || 0;
+    const height = Number.parseFloat(line.style.height) || 0;
+    const dy = local.y < top ? top - local.y : local.y > top + height ? local.y - top - height : 0;
+    const dx = local.x < left ? left - local.x : local.x > left + width ? local.x - left - width : 0;
+    const distance = dy * 4096 + dx;
+    if (!nearest || distance < nearest.distance) nearest = { line, distance };
+  }
+  if (!nearest) return null;
+  const lineLeft = Number.parseFloat(nearest.line.style.left) || 0;
+  return nearestGridPositionInLine(nearest.line, local.x - lineLeft);
+}
+function nearestTextPositionInLine(line, x, y) {
+  const texts = collectTextNodes(line);
+  if (texts.length === 0) return null;
+  let nearest = null;
+  for (const node of texts) {
+    const candidate = nearestOffsetForPoint(node, x, y);
+    if (!nearest || candidate.distance < nearest.distance) {
+      let { offset } = candidate;
+      while (offset > 0 && node.data[offset - 1] === "\n") offset--;
+      nearest = { position: { node, offset }, distance: candidate.distance };
+    }
+  }
+  return nearest?.position ?? null;
+}
+function nearestTextPositionInProjection(contentEl, canvas, x, y, eventTarget) {
+  if (contentEl.dataset.vectoContentGrid !== void 0) {
+    return nearestGridPosition(contentEl, canvas, x, y);
+  }
+  let targetLine = eventTarget;
+  while (targetLine && targetLine.parentElement !== contentEl) {
+    if (!contentEl.contains(targetLine)) {
+      targetLine = null;
+      break;
+    }
+    targetLine = targetLine.parentElement;
+  }
+  if (targetLine?.parentElement === contentEl) {
+    return nearestTextPositionInLine(targetLine, x, y);
+  }
+  let bestLine = null;
+  let bestDist = Infinity;
+  for (let i = 0; i < contentEl.children.length; i++) {
+    const child = contentEl.children[i];
+    const rect = child.getBoundingClientRect();
+    if (rect.width <= 0 && rect.height <= 0) continue;
+    const dy = y < rect.top ? rect.top - y : y > rect.bottom ? y - rect.bottom : 0;
+    const dx = x < rect.left ? rect.left - x : x > rect.right ? x - rect.right : 0;
+    const dist = dy * 4096 + dx;
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestLine = child;
+    }
+  }
+  if (bestLine) return nearestTextPositionInLine(bestLine, x, y);
+  return nearestTextPositionInLine(contentEl, x, y);
+}
+function projectionAbsoluteOffset(root, caret) {
+  let offset = 0;
+  for (const node of collectTextNodes(root)) {
+    if (node === caret.node) return offset + Math.min(caret.offset, node.data.length);
+    offset += node.data.length;
+  }
+  return null;
+}
+function projectionCaretAt(root, absoluteOffset, affinity) {
+  const nodes = collectTextNodes(root);
+  if (nodes.length === 0) return null;
+  let remaining = Math.max(0, absoluteOffset);
+  for (let index = 0; index < nodes.length; index++) {
+    const node = nodes[index];
+    if (remaining < node.data.length || remaining === node.data.length && affinity === "backward") {
+      return { node, offset: remaining };
+    }
+    if (remaining === node.data.length && index === nodes.length - 1) {
+      return { node, offset: remaining };
+    }
+    remaining -= node.data.length;
+  }
+  const last = nodes[nodes.length - 1];
+  return { node: last, offset: last.data.length };
+}
+function selectProjectionUnit(selection, root, caret, unit) {
+  const absoluteOffset = projectionAbsoluteOffset(root, caret);
+  const text = root.textContent ?? "";
+  if (absoluteOffset === null || text.length === 0) return false;
+  let start = absoluteOffset;
+  let end = absoluteOffset;
+  if (unit === "line") {
+    for (let index = Math.max(0, absoluteOffset - 1); index >= 0; index--) {
+      if (text[index] === "\n" || text[index] === "\r") {
+        start = index + 1;
+        if (text[index] === "\r" && text[index + 1] === "\n") start++;
+        break;
+      }
+    }
+    const cr = text.indexOf("\r", absoluteOffset);
+    const lf = text.indexOf("\n", absoluteOffset);
+    const separator = [cr, lf].filter((index) => index >= 0).sort((a, b) => a - b)[0];
+    end = separator === void 0 ? text.length : separator;
+  } else if (caretWordSegmenter) {
+    const segments = [...caretWordSegmenter.segment(text)];
+    const selected = segments.find(
+      (segment) => segment.isWordLike && absoluteOffset >= segment.index && absoluteOffset <= segment.index + segment.segment.length
+    ) ?? segments.find((segment) => segment.isWordLike && segment.index >= absoluteOffset) ?? [...segments].reverse().find((segment) => segment.isWordLike);
+    if (selected) {
+      start = selected.index;
+      end = selected.index + selected.segment.length;
+    }
+  } else {
+    const isWord = (character) => /[\p{L}\p{N}_]/u.test(character);
+    while (start > 0 && isWord(text[start - 1])) start--;
+    while (end < text.length && isWord(text[end])) end++;
+  }
+  const anchor = projectionCaretAt(root, start, "forward");
+  const focus = projectionCaretAt(root, end, "backward");
+  if (!anchor || !focus) return false;
+  selection.setBaseAndExtent(anchor.node, anchor.offset, focus.node, focus.offset);
+  return true;
+}
+function extendSelection(selection, anchor, focus) {
+  try {
+    selection.setBaseAndExtent(anchor.node, anchor.offset, focus.node, focus.offset);
+    return;
+  } catch {
+  }
+  try {
+    selection.collapse(anchor.node, anchor.offset);
+    selection.extend(focus.node, focus.offset);
+    return;
+  } catch {
+  }
+  const anchorRange = document.createRange();
+  anchorRange.setStart(anchor.node, anchor.offset);
+  anchorRange.collapse(true);
+  const focusRange = document.createRange();
+  focusRange.setStart(focus.node, focus.offset);
+  focusRange.collapse(true);
+  const range = document.createRange();
+  if (anchorRange.compareBoundaryPoints(Range.START_TO_START, focusRange) <= 0) {
+    range.setStart(anchor.node, anchor.offset);
+    range.setEnd(focus.node, focus.offset);
+  } else {
+    range.setStart(focus.node, focus.offset);
+    range.setEnd(anchor.node, anchor.offset);
+  }
+  selection.removeAllRanges();
+  selection.addRange(range);
+}
 var Scene = class _Scene {
   static webglCreator = null;
   static webgpuManagerClass = null;
@@ -373,7 +665,25 @@ var Scene = class _Scene {
   a11yElements = /* @__PURE__ */ new Map();
   /** DOM nodes mirroring static text content, keyed by entity id. */
   contentElements = /* @__PURE__ */ new Map();
+  /** Pending cold font-calibration frame per projected grid entity. */
+  contentGridCalibrationFrames = /* @__PURE__ */ new Map();
+  /** Detached, untransformed font probes used by the cold calibration pass. */
+  contentGridCalibrationProbes = /* @__PURE__ */ new Map();
+  /** Invalidates grid font calibration after browser font availability changes. */
+  contentFontEpoch = 0;
+  /** Cached Canvas-to-client scale for the current font/viewport epoch. */
+  contentMetricScaleEpoch = -1;
+  contentMetricScaleX = 1;
   contentProjectionEnabled = true;
+  /**
+   * True while a text-selection drag that started on a projection's blank
+   * region (no text node under the press) is being driven manually — the
+   * browser has no native anchor for it, so mousemove extends the Selection
+   * from the position we resolved ourselves.
+   */
+  blankRegionSelectionDrag = false;
+  contentSelectionAnchor = null;
+  contentSelectionEndListener = null;
   // Animation/interactive flags collected during the render walk (tree-walk
   // fusion): the loop reads last frame's answers instead of re-walking the
   // tree up to 4× per tick. Start true so the first tick stays conservative.
@@ -482,16 +792,88 @@ var Scene = class _Scene {
       this.a11yRoot.style.zIndex = "10";
       this.a11yRoot.style.userSelect = "text";
       this.a11yRoot.addEventListener("mousedown", (e) => {
+        if (e.button !== 0) return;
         const target = e.target;
-        if (target !== this.a11yRoot && target.closest("[data-vecto-content]") && getComputedStyle(target.closest("[data-vecto-content]")).pointerEvents === "auto") {
-          this.a11yRoot.style.pointerEvents = "auto";
+        const contentEl = target.closest("[data-vecto-content]");
+        if (target === this.a11yRoot || !contentEl) return;
+        if (getComputedStyle(contentEl).pointerEvents !== "auto") return;
+        const selection = window.getSelection();
+        if (!selection) return;
+        this.a11yRoot.style.pointerEvents = "auto";
+        const resolved = nearestTextPositionInProjection(
+          contentEl,
+          this.canvas,
+          e.clientX,
+          e.clientY,
+          target
+        );
+        if (resolved) {
+          if (e.detail >= 2) {
+            selection.removeAllRanges();
+            selectProjectionUnit(selection, contentEl, resolved, e.detail >= 3 ? "line" : "word");
+            this.endContentSelectionDrag();
+            e.preventDefault();
+            return;
+          }
+          const existingAnchor = e.shiftKey && selection.anchorNode instanceof Text ? { node: selection.anchorNode, offset: selection.anchorOffset } : null;
+          const anchor = existingAnchor && this.a11yRoot.contains(existingAnchor.node) ? existingAnchor : resolved;
+          if (e.shiftKey && existingAnchor) extendSelection(selection, anchor, resolved);
+          else selection.collapse(resolved.node, resolved.offset);
+          this.contentSelectionAnchor = anchor;
+          this.blankRegionSelectionDrag = true;
+          e.preventDefault();
         }
       });
-      const endDrag = () => {
-        if (this.a11yRoot) this.a11yRoot.style.pointerEvents = "none";
-      };
+      this.a11yRoot.addEventListener("dblclick", (e) => {
+        const target = e.target;
+        const contentEl = target.closest("[data-vecto-content]");
+        if (!contentEl || getComputedStyle(contentEl).pointerEvents !== "auto") return;
+        const selection = window.getSelection();
+        const caret = nearestTextPositionInProjection(
+          contentEl,
+          this.canvas,
+          e.clientX,
+          e.clientY,
+          target
+        );
+        if (!selection || !caret) return;
+        selection.removeAllRanges();
+        selectProjectionUnit(selection, contentEl, caret, "word");
+        this.endContentSelectionDrag();
+        e.preventDefault();
+      });
+      this.a11yRoot.addEventListener("mousemove", (e) => {
+        if (!this.blankRegionSelectionDrag) return;
+        const selection = window.getSelection();
+        if (!selection || selection.rangeCount === 0) return;
+        const target = e.target;
+        let contentEl = target.closest("[data-vecto-content]");
+        if (!contentEl) {
+          let bestDistance = Infinity;
+          for (const candidate of this.contentElements.values()) {
+            if (getComputedStyle(candidate).pointerEvents !== "auto") continue;
+            const rect = candidate.getBoundingClientRect();
+            const dx = e.clientX < rect.left ? rect.left - e.clientX : e.clientX > rect.right ? e.clientX - rect.right : 0;
+            const dy = e.clientY < rect.top ? rect.top - e.clientY : e.clientY > rect.bottom ? e.clientY - rect.bottom : 0;
+            const distance = dx * dx + dy * dy;
+            if (distance < bestDistance) {
+              bestDistance = distance;
+              contentEl = candidate;
+            }
+          }
+        }
+        const focus = contentEl ? nearestTextPositionInProjection(contentEl, this.canvas, e.clientX, e.clientY, target) : null;
+        const anchor = this.contentSelectionAnchor;
+        if (focus && anchor) {
+          extendSelection(selection, anchor, focus);
+        }
+      });
+      const endDrag = () => this.endContentSelectionDrag();
       this.a11yRoot.addEventListener("mouseup", endDrag);
       this.a11yRoot.addEventListener("mouseleave", endDrag);
+      window.addEventListener("mouseup", endDrag);
+      window.addEventListener("blur", endDrag);
+      this.contentSelectionEndListener = endDrag;
       if (canvas.parentElement) {
         canvas.parentElement.appendChild(this.a11yRoot);
       }
@@ -534,6 +916,7 @@ var Scene = class _Scene {
     if (typeof document !== "undefined" && document.fonts) {
       this.fontLoadHandler = () => {
         clearCssLineBoxMetrics();
+        this.contentFontEpoch++;
         this.markDirty();
       };
       document.fonts.ready.then(this.fontLoadHandler);
@@ -541,6 +924,18 @@ var Scene = class _Scene {
     }
     this.setupEvents();
   }
+  endContentSelectionDrag() {
+    this.blankRegionSelectionDrag = false;
+    this.contentSelectionAnchor = null;
+    if (this.a11yRoot) this.a11yRoot.style.pointerEvents = "none";
+  }
+  releaseContentSelectionForRebuild(el) {
+    const selection = typeof window !== "undefined" && typeof window.getSelection === "function" ? window.getSelection() : null;
+    const ownsSelection = this.contentSelectionAnchor && el.contains(this.contentSelectionAnchor.node) || (selection?.anchorNode ? el.contains(selection.anchorNode) : false) || (selection?.focusNode ? el.contains(selection.focusNode) : false);
+    if (!ownsSelection) return;
+    this.endContentSelectionDrag();
+    selection?.removeAllRanges();
+  }
   /**
    * Expose the underlying {@link IRenderer} for advanced direct-draw operations.
    *
@@ -571,6 +966,24 @@ var Scene = class _Scene {
     this.root.add(entity);
     return this;
   }
+  clearContentGridState(entityId, el) {
+    const calibrationFrame = this.contentGridCalibrationFrames.get(entityId);
+    if (calibrationFrame !== void 0 && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(calibrationFrame);
+    }
+    this.contentGridCalibrationFrames.delete(entityId);
+    this.contentGridCalibrationProbes.get(entityId)?.remove();
+    this.contentGridCalibrationProbes.delete(entityId);
+    delete el.dataset.vectoGridCalibrationPending;
+    delete el.dataset.vectoGridCalibration;
+    delete el.dataset.vectoGridReady;
+    delete el.dataset.vectoContentGrid;
+    delete el.dataset.vectoGridCarriers;
+    delete el.dataset.vectoGridMaterializeMs;
+    delete el.dataset.vectoGridCalibrationSamples;
+    delete el.dataset.vectoGridCalibrationMs;
+    this.releaseContentSelectionForRebuild(el);
+  }
   removeA11yRecursively(node) {
     if (node.isDOMPortal) {
       node.domElement.remove();
@@ -580,6 +993,7 @@ var Scene = class _Scene {
     }
     const contentEl = this.contentElements.get(node.id);
     if (contentEl) {
+      this.clearContentGridState(node.id, contentEl);
       contentEl.remove();
       this.contentElements.delete(node.id);
       this.a11yNeedsReorder = true;
@@ -661,6 +1075,11 @@ var Scene = class _Scene {
     if (typeof window !== "undefined" && !this.disableWindowResize) {
       window.removeEventListener("resize", this.resizeHandler);
     }
+    if (typeof window !== "undefined" && this.contentSelectionEndListener) {
+      window.removeEventListener("mouseup", this.contentSelectionEndListener);
+      window.removeEventListener("blur", this.contentSelectionEndListener);
+      this.contentSelectionEndListener = null;
+    }
     if (typeof window !== "undefined" && this.canvas && typeof this.canvas.removeEventListener === "function") {
       if (this.pointerMoveListener) {
         this.canvas.removeEventListener("pointermove", this.pointerMoveListener);
@@ -674,6 +1093,15 @@ var Scene = class _Scene {
     this.a11yElements.clear();
     for (const el of this.contentElements.values()) el.remove();
     this.contentElements.clear();
+    if (typeof cancelAnimationFrame === "function") {
+      for (const frame of this.contentGridCalibrationFrames.values()) {
+        cancelAnimationFrame(frame);
+      }
+    }
+    this.contentGridCalibrationFrames.clear();
+    for (const probe of this.contentGridCalibrationProbes.values()) probe.remove();
+    this.contentGridCalibrationProbes.clear();
+    this.endContentSelectionDrag();
     this.pointRenderer?.destroy();
     this.renderer.dispose?.();
     this.glCanvas?.remove();
@@ -958,6 +1386,10 @@ var Scene = class _Scene {
       if (attrs.label !== void 0 && el.getAttribute("aria-label") !== attrs.label) {
         el.setAttribute("aria-label", attrs.label);
       }
+      const semanticPointerEvents = attrs.pointerEvents ?? "auto";
+      if (el.style.pointerEvents !== semanticPointerEvents) {
+        el.style.pointerEvents = semanticPointerEvents;
+      }
       const implicitTabIndex = !isNativelyFocusable(el) && attrs.role && INTERACTIVE_A11Y_ROLES.has(attrs.role) ? 0 : null;
       const desiredTabIndex = attrs.tabIndex ?? implicitTabIndex;
       if (desiredTabIndex === null) {
@@ -1074,6 +1506,7 @@ var Scene = class _Scene {
     let el = this.contentElements.get(node.id);
     if (!projection || !projection.text) {
       if (el) {
+        this.clearContentGridState(node.id, el);
         el.remove();
         this.contentElements.delete(node.id);
         this.a11yNeedsReorder = true;
@@ -1105,13 +1538,19 @@ var Scene = class _Scene {
       this.a11yNeedsReorder = true;
     }
     const lines = projection.lines;
-    if (lines && lines.length > 0) {
+    if (!projection.grid && el.dataset.vectoContentGrid !== void 0) {
+      this.clearContentGridState(node.id, el);
+    }
+    if (projection.grid) {
+      this.syncContentGridProjection(node, el, projection, projection.grid);
+    } else if (lines && lines.length > 0) {
       const signature = JSON.stringify({
         lines,
         fallbackFont: projection.font ?? "",
         fallbackLineHeight: projection.lineHeight ?? 16
       });
       if (el.dataset.vectoProjectionLines !== signature) {
+        this.releaseContentSelectionForRebuild(el);
         el.replaceChildren();
         for (let index = 0; index < lines.length; index++) {
           const line = lines[index];
@@ -1143,13 +1582,21 @@ var Scene = class _Scene {
         el.dataset.vectoProjectionLines = signature;
       }
     } else {
-      if (el.textContent !== projection.text) el.textContent = projection.text;
+      if (el.textContent !== projection.text) {
+        this.releaseContentSelectionForRebuild(el);
+        el.textContent = projection.text;
+      }
       delete el.dataset.vectoProjectionLines;
     }
     const font = projection.font ?? "";
     if (el.style.font !== font) el.style.font = font;
     const lineHeight = projection.lineHeight !== void 0 ? `${projection.lineHeight}px` : "";
     if (el.style.lineHeight !== lineHeight) el.style.lineHeight = lineHeight;
+    const ligatures = projection.ligatures === "none" ? "none" : "";
+    if (el.style.getPropertyValue("font-variant-ligatures") !== ligatures) {
+      el.style.setProperty("font-variant-ligatures", ligatures);
+      el.style.setProperty("font-kerning", ligatures ? "none" : "");
+    }
     const hidden = node.interactive ? "true" : null;
     if (el.getAttribute("aria-hidden") !== hidden) {
       if (hidden) el.setAttribute("aria-hidden", hidden);
@@ -1211,6 +1658,245 @@ var Scene = class _Scene {
     const display = visible ? "" : "none";
     if (el.style.display !== display) el.style.display = display;
   }
+  /**
+   * Materialize a prepared grid in logical source order while positioning each
+   * carrier from the shared canvas geometry. Browser font measurement happens
+   * later in one cold read/write batch, never inside projection synchronization.
+   */
+  syncContentGridProjection(node, el, projection, grid) {
+    if (grid.source !== projection.text) {
+      throw new Error("ContentProjection.grid.source must equal ContentProjection.text");
+    }
+    const signature = `${grid.revision}`;
+    if (el.dataset.vectoContentGrid !== signature) {
+      const materializeStart = typeof performance !== "undefined" ? performance.now() : 0;
+      this.clearContentGridState(node.id, el);
+      el.replaceChildren();
+      const projectionLines = projection.lines ?? [];
+      for (let lineIndex = 0; lineIndex < grid.lines.length; lineIndex++) {
+        const gridLine = grid.lines[lineIndex];
+        const projectedLine = projectionLines[lineIndex];
+        const lineHeight = projectedLine?.lineHeight ?? grid.lineHeight;
+        const baseline = projectedLine?.baseline ?? grid.baseline;
+        const lineFont = projectedLine?.font ?? grid.font;
+        const lineElement = document.createElement("span");
+        lineElement.dir = "ltr";
+        lineElement.dataset.vectoGridLine = `${lineIndex}`;
+        lineElement.style.position = "absolute";
+        lineElement.style.left = `${projectedLine?.x ?? 0}px`;
+        lineElement.style.top = `${(projectedLine?.y ?? lineIndex * grid.lineHeight) + baseline - cssLineBoxBaseline(lineFont, lineHeight)}px`;
+        lineElement.style.width = `${gridLine.width}px`;
+        lineElement.style.height = `${lineHeight}px`;
+        lineElement.style.whiteSpace = "pre";
+        lineElement.style.font = lineFont;
+        lineElement.style.lineHeight = `${lineHeight}px`;
+        if (gridLine.cells.length === 0) {
+          lineElement.textContent = grid.source.slice(gridLine.sourceEnd, gridLine.nextSourceStart);
+        } else {
+          let logicalX = 0;
+          for (let cellIndex = 0; cellIndex < gridLine.cells.length; cellIndex++) {
+            const cell = gridLine.cells[cellIndex];
+            const cellElement = document.createElement("span");
+            cellElement.dir = "ltr";
+            const separator = cellIndex === gridLine.cells.length - 1 ? grid.source.slice(gridLine.sourceEnd, gridLine.nextSourceStart) : "";
+            const sourceText = grid.source.slice(cell.sourceStart, cell.sourceEnd);
+            cellElement.textContent = sourceText + separator;
+            cellElement.dataset.vectoGridCell = `${cellIndex}`;
+            cellElement.dataset.vectoGridSourceLength = `${sourceText.length}`;
+            cellElement.dataset.vectoGridSourceStart = `${cell.sourceStart}`;
+            cellElement.dataset.vectoGridSourceEnd = `${cell.sourceEnd}`;
+            cellElement.dataset.vectoGridCaretOffsets = cell.sourceCaretOffsets.join(",");
+            cellElement.dataset.vectoGridLevel = `${cell.level}`;
+            cellElement.dataset.vectoGridAdvance = `${cell.advance}`;
+            cellElement.dataset.vectoGridX = `${cell.x}`;
+            cellElement.style.position = "relative";
+            cellElement.style.display = "inline-block";
+            cellElement.style.left = `${cell.x - logicalX}px`;
+            cellElement.style.top = "0";
+            cellElement.style.width = `${cell.advance}px`;
+            cellElement.style.height = `${lineHeight}px`;
+            cellElement.style.boxSizing = "border-box";
+            cellElement.style.verticalAlign = "top";
+            cellElement.style.whiteSpace = "pre";
+            cellElement.style.font = lineFont;
+            cellElement.style.lineHeight = `${lineHeight}px`;
+            cellElement.style.transformOrigin = "0 50%";
+            lineElement.appendChild(cellElement);
+            logicalX += cell.advance;
+          }
+        }
+        if (lineIndex === 0) {
+          for (const [basis, left, top] of [
+            ["origin", 0, 0],
+            ["x", 1, 0],
+            ["y", 0, 1]
+          ]) {
+            const marker = document.createElement("span");
+            marker.dataset.vectoGridBasis = basis;
+            marker.setAttribute("aria-hidden", "true");
+            marker.style.position = "absolute";
+            marker.style.left = `${left}px`;
+            marker.style.top = `${top}px`;
+            marker.style.width = "0";
+            marker.style.height = "0";
+            marker.style.pointerEvents = "none";
+            marker.style.userSelect = "none";
+            lineElement.appendChild(marker);
+          }
+        }
+        el.appendChild(lineElement);
+      }
+      el.dataset.vectoProjectionLines = signature;
+      el.dataset.vectoContentGrid = signature;
+      el.dataset.vectoGridCarriers = `${el.querySelectorAll("[data-vecto-grid-cell]").length}`;
+      if (typeof performance !== "undefined") {
+        el.dataset.vectoGridMaterializeMs = `${performance.now() - materializeStart}`;
+      }
+      delete el.dataset.vectoGridCalibration;
+      delete el.dataset.vectoGridReady;
+    }
+    const pageScaleX = this.getContentMetricScaleX();
+    const calibrationKey = `${signature}:${this.contentFontEpoch}:${pageScaleX.toFixed(4)}`;
+    if (el.dataset.vectoGridCalibration !== calibrationKey) {
+      this.scheduleContentGridCalibration(node.id, el, calibrationKey, pageScaleX);
+    }
+  }
+  getContentMetricScaleX() {
+    if (this.contentMetricScaleEpoch === this.contentFontEpoch) {
+      return this.contentMetricScaleX;
+    }
+    const rect = this.canvas.getBoundingClientRect();
+    const inlineWidth = parseInlinePx(this.canvas.style.width);
+    const logicalWidth = inlineWidth ?? (this.canvas.clientWidth || this.width);
+    const scale = logicalWidth > 0 ? rect.width / logicalWidth : 1;
+    this.contentMetricScaleX = Number.isFinite(scale) && scale > 0 ? scale : 1;
+    this.contentMetricScaleEpoch = this.contentFontEpoch;
+    return this.contentMetricScaleX;
+  }
+  scheduleContentGridCalibration(entityId, el, calibrationKey, pageScaleX) {
+    if (typeof requestAnimationFrame !== "function") return;
+    if (el.dataset.vectoGridCalibrationPending === calibrationKey) return;
+    const previous = this.contentGridCalibrationFrames.get(entityId);
+    if (previous !== void 0 && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(previous);
+    }
+    this.contentGridCalibrationProbes.get(entityId)?.remove();
+    this.contentGridCalibrationProbes.delete(entityId);
+    const calibrationStart = typeof performance !== "undefined" ? performance.now() : 0;
+    const probe = document.createElement("div");
+    probe.setAttribute("aria-hidden", "true");
+    probe.dataset.vectoGridProbe = entityId;
+    probe.style.position = "absolute";
+    probe.style.left = "-100000px";
+    probe.style.top = "0";
+    probe.style.width = "100000px";
+    probe.style.height = "1px";
+    probe.style.visibility = "hidden";
+    probe.style.pointerEvents = "none";
+    probe.style.whiteSpace = "pre";
+    probe.style.contain = "layout style paint";
+    const probeOrigin = document.createElement("span");
+    probeOrigin.style.position = "absolute";
+    probeOrigin.style.left = "0";
+    probeOrigin.style.top = "0";
+    const probeX = document.createElement("span");
+    probeX.style.position = "absolute";
+    probeX.style.left = "1px";
+    probeX.style.top = "0";
+    probe.append(probeOrigin, probeX);
+    const measurements = [];
+    const measurementsByKey = /* @__PURE__ */ new Map();
+    for (const target of el.querySelectorAll("[data-vecto-grid-cell]")) {
+      const sourceLength = Number(target.dataset.vectoGridSourceLength ?? 0);
+      const targetWidth = Number(target.dataset.vectoGridAdvance ?? 0);
+      if (sourceLength <= 0 || targetWidth <= 0) continue;
+      const sourceText = target.textContent?.slice(0, sourceLength) ?? "";
+      if (!sourceText) continue;
+      const measurementKey = JSON.stringify([
+        target.style.font,
+        target.style.lineHeight,
+        targetWidth,
+        sourceText
+      ]);
+      const shared = measurementsByKey.get(measurementKey);
+      if (shared) {
+        shared.targets.push(target);
+        continue;
+      }
+      const carrier = document.createElement("span");
+      carrier.dir = "ltr";
+      carrier.style.position = "absolute";
+      carrier.style.left = "0";
+      carrier.style.top = "0";
+      carrier.style.whiteSpace = "pre";
+      carrier.style.font = target.style.font;
+      carrier.style.lineHeight = target.style.lineHeight;
+      carrier.style.fontVariantLigatures = "none";
+      carrier.style.fontKerning = "none";
+      const source = document.createTextNode(sourceText);
+      carrier.appendChild(source);
+      probe.appendChild(carrier);
+      const measurement = { targets: [target], targetWidth, sourceLength, source };
+      measurements.push(measurement);
+      measurementsByKey.set(measurementKey, measurement);
+    }
+    (this.a11yRoot ?? document.body ?? document.documentElement).appendChild(probe);
+    el.dataset.vectoGridCalibrationSamples = `${measurements.length}`;
+    this.contentGridCalibrationProbes.set(entityId, probe);
+    el.dataset.vectoGridCalibrationPending = calibrationKey;
+    delete el.dataset.vectoGridReady;
+    const readFrame = requestAnimationFrame(() => {
+      if (!el.isConnected || el.dataset.vectoGridCalibrationPending !== calibrationKey) {
+        probe.remove();
+        this.contentGridCalibrationProbes.delete(entityId);
+        this.contentGridCalibrationFrames.delete(entityId);
+        return;
+      }
+      const updates = [];
+      const probeOriginRect = probeOrigin.getBoundingClientRect();
+      const probeXRect = probeX.getBoundingClientRect();
+      const basisScale = Math.abs(probeXRect.left - probeOriginRect.left);
+      const projectionPageScaleX = Number.isFinite(basisScale) && basisScale > 0 ? basisScale : pageScaleX;
+      let valid = true;
+      for (const measurement of measurements) {
+        const range = document.createRange();
+        range.setStart(measurement.source, 0);
+        range.setEnd(measurement.source, measurement.sourceLength);
+        const natural = range.getBoundingClientRect().width;
+        if (!Number.isFinite(natural) || natural <= 0) {
+          valid = false;
+          break;
+        }
+        const scale = measurement.targetWidth * projectionPageScaleX / natural;
+        for (const element of measurement.targets) updates.push({ element, scale });
+      }
+      probe.remove();
+      this.contentGridCalibrationProbes.delete(entityId);
+      if (!valid) {
+        delete el.dataset.vectoGridCalibrationPending;
+        this.contentGridCalibrationFrames.delete(entityId);
+        return;
+      }
+      const writeFrame = requestAnimationFrame(() => {
+        if (!el.isConnected || el.dataset.vectoGridCalibrationPending !== calibrationKey) {
+          this.contentGridCalibrationFrames.delete(entityId);
+          return;
+        }
+        for (const { element, scale } of updates) {
+          element.style.transform = Math.abs(scale - 1) <= 1e-3 ? "" : `scaleX(${scale})`;
+        }
+        el.dataset.vectoGridCalibration = calibrationKey;
+        el.dataset.vectoGridReady = "true";
+        if (typeof performance !== "undefined") {
+          el.dataset.vectoGridCalibrationMs = `${performance.now() - calibrationStart}`;
+        }
+        delete el.dataset.vectoGridCalibrationPending;
+        this.contentGridCalibrationFrames.delete(entityId);
+      });
+      this.contentGridCalibrationFrames.set(entityId, writeFrame);
+    });
+    this.contentGridCalibrationFrames.set(entityId, readFrame);
+  }
   enforceA11yDomOrder() {
     if (!this.a11yRoot) return;
     this.fullViewportElements.length = 0;
@@ -1738,6 +2424,7 @@ var Scene = class _Scene {
   resize(width, height) {
     this.width = width;
     this.height = height;
+    this.contentFontEpoch++;
     if (typeof this.renderer.resize === "function") {
       this.renderer.resize(width, height);
     }
@@ -2423,6 +3110,128 @@ async function loadSpline(url) {
   return await res.json();
 }
 
+// src/components/Rect.ts
+var Rect = class extends Entity {
+  fill;
+  stroke;
+  strokeWidth;
+  radius;
+  constructor(opts = {}) {
+    super();
+    this.width = opts.width ?? 0;
+    this.height = opts.height ?? 0;
+    this.fill = opts.fill === void 0 ? "#38bdf8" : opts.fill;
+    this.stroke = opts.stroke ?? null;
+    this.strokeWidth = opts.strokeWidth ?? 1;
+    this.radius = opts.radius ?? 0;
+  }
+  getBounds() {
+    return { x: 0, y: 0, width: this.width, height: this.height };
+  }
+  /**
+   * Solid-fill, square-cornered, unstroked rectangles opt into the GPU
+   * instanced-rect batch (WebGL `pointBackend` only). Any stroke or corner
+   * radius needs the exact Canvas path, so return `null` to fall back to
+   * {@link render}. Read each frame, so an animated `fill` still batches.
+   */
+  getBatchRect() {
+    if (!this.fill || this.stroke || this.radius > 0) return null;
+    return { width: this.width, height: this.height, color: this.fill };
+  }
+  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(renderer) {
+    renderer.beginPath();
+    if (this.radius > 0) {
+      renderer.roundRect(0, 0, this.width, this.height, this.radius);
+    } else {
+      renderer.moveTo(0, 0);
+      renderer.lineTo(this.width, 0);
+      renderer.lineTo(this.width, this.height);
+      renderer.lineTo(0, this.height);
+      renderer.closePath();
+    }
+    if (this.fill) renderer.fill(this.fill);
+    if (this.stroke) renderer.stroke(this.stroke, this.strokeWidth);
+  }
+};
+
+// src/components/Circle.ts
+var Circle = class extends Entity {
+  fill;
+  stroke;
+  strokeWidth;
+  _radius;
+  constructor(opts = {}) {
+    super();
+    this._radius = opts.radius ?? 0;
+    this.fill = opts.fill === void 0 ? "#38bdf8" : opts.fill;
+    this.stroke = opts.stroke ?? null;
+    this.strokeWidth = opts.strokeWidth ?? 1;
+    this.syncBox();
+  }
+  get radius() {
+    return this._radius;
+  }
+  set radius(v) {
+    this._radius = v;
+    this.syncBox();
+  }
+  /** Keep the a11y box (a square around the centered disc) in sync with radius. */
+  syncBox() {
+    this.width = this._radius * 2;
+    this.height = this._radius * 2;
+    this.a11yOffsetX = -this._radius;
+    this.a11yOffsetY = -this._radius;
+  }
+  getBounds() {
+    return {
+      x: -this._radius,
+      y: -this._radius,
+      width: this._radius * 2,
+      height: this._radius * 2
+    };
+  }
+  /**
+   * A solid-fill, unstroked circle opts into the renderer's circle batch
+   * (center = entity origin, radius scaled by world scale). A stroke needs the
+   * exact Canvas path, so return `null` there. Read each frame, so an animated
+   * `fill`/`radius` still batches.
+   */
+  getBatchCircle() {
+    if (!this.fill || this.stroke) return null;
+    return { radius: this._radius, color: this.fill };
+  }
+  isPointInside(globalX, globalY) {
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x * local.x + local.y * local.y <= this._radius * this._radius;
+  }
+  render(renderer) {
+    renderer.beginPath();
+    renderer.arc(0, 0, this._radius, 0, Math.PI * 2);
+    renderer.closePath();
+    if (this.fill) renderer.fill(this.fill);
+    if (this.stroke) renderer.stroke(this.stroke, this.strokeWidth);
+  }
+};
+
+// src/components/Group.ts
+var Group = class extends Entity {
+  constructor(...children) {
+    super();
+    if (children.length > 0) this.add(...children);
+  }
+  isPointInside() {
+    return false;
+  }
+  render(_renderer) {
+  }
+};
+
 // src/math/SpatialHashGrid.ts
 var SpatialHashGrid = class {
   cellSize;
@@ -2624,11 +3433,13 @@ export {
   ArabicShaper,
   BidiResolver,
   CanvasRenderer,
+  Circle,
   ComputeParticleEntity,
   DOMPortalEntity,
   Easing,
   Entity,
   GridTextEntity,
+  Group,
   LayoutEngine,
   LayoutResultBuffer,
   LayoutWorkerManager,
@@ -2644,6 +3455,7 @@ export {
   PARTICLE_OFFSET_VELOCITY_Y,
   PARTICLE_STRIDE_FLOATS,
   REDUCED_MOTION_FPS,
+  Rect,
   SVGEntity,
   SVGRenderer,
   Scene,
@@ -2665,5 +3477,6 @@ export {
   loadSpline,
   parseColorToRGBA,
   polySegmentToBezier,
+  prepareContentGrid,
   sanitizeUrl
 };