@vectojs/core 1.20.0 → 1.21.0

package/dist/{chunk-YLH7F4ZV.js → chunk-AGP4VLF4.js}

@@ -964,6 +964,38 @@ var Entity = (_class2 = class {
    *
    * @returns The {@link A11yAttributes} for this entity's shadow node.
    */
+  /**
+   * Describe this entity's own debug surface for DevTools.
+   *
+   * Returns `null` by default, meaning "nothing beyond the generic `Entity`
+   * fields the inspector already shows". Override in a component to expose the
+   * state that makes it inspectable — see {@link DevtoolsDescriptor}.
+   *
+   * Called only while a panel is inspecting this entity, never per frame, so it
+   * may compute values that would be too expensive to track continuously.
+   *
+   * @returns A descriptor, or `null` to opt out.
+   */
+  getDevtoolsDescriptor() {
+    return null;
+  }
+  /**
+   * Which of a child's properties this entity computes during layout.
+   *
+   * Returns an empty array by default, meaning "this entity does not position its
+   * children". A container that lays out children — `Stack`, `Table`, `Tabs` —
+   * overrides it so tooling can mark those values as parent-owned: editing `x` on
+   * a `Stack` child is reverted by the next layout, and knowing that in advance is
+   * the difference between a confusing tool and a correct one.
+   *
+   * @param child - The child being asked about. Containers whose control depends
+   *   on the child (a `Table` cell versus its header) can answer per child.
+   * @returns Property names this entity overwrites on that child.
+   */
+  getLayoutControlledProperties(child) {
+    void child;
+    return [];
+  }
   getA11yAttributes() {
     return {};
   }

package/dist/{chunk-TJCXB2F6.mjs → chunk-FRMLD4PP.mjs}

@@ -962,6 +962,38 @@ var Entity = class {
    *
    * @returns The {@link A11yAttributes} for this entity's shadow node.
    */
+  /**
+   * Describe this entity's own debug surface for DevTools.
+   *
+   * Returns `null` by default, meaning "nothing beyond the generic `Entity`
+   * fields the inspector already shows". Override in a component to expose the
+   * state that makes it inspectable — see {@link DevtoolsDescriptor}.
+   *
+   * Called only while a panel is inspecting this entity, never per frame, so it
+   * may compute values that would be too expensive to track continuously.
+   *
+   * @returns A descriptor, or `null` to opt out.
+   */
+  getDevtoolsDescriptor() {
+    return null;
+  }
+  /**
+   * Which of a child's properties this entity computes during layout.
+   *
+   * Returns an empty array by default, meaning "this entity does not position its
+   * children". A container that lays out children — `Stack`, `Table`, `Tabs` —
+   * overrides it so tooling can mark those values as parent-owned: editing `x` on
+   * a `Stack` child is reverted by the next layout, and knowing that in advance is
+   * the difference between a confusing tool and a correct one.
+   *
+   * @param child - The child being asked about. Containers whose control depends
+   *   on the child (a `Table` cell versus its header) can answer per child.
+   * @returns Property names this entity overwrites on that child.
+   */
+  getLayoutControlledProperties(child) {
+    void child;
+    return [];
+  }
   getA11yAttributes() {
     return {};
   }

package/dist/{chunk-L4SWVP2H.js → chunk-GKSCJ6AF.js}

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4;const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5;const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
 
 // src/renderer/CanvasRenderer.ts
 var TWO_PI = Math.PI * 2;
@@ -212,6 +212,11 @@ var CanvasRenderer = (_class = class _CanvasRenderer {
     this.ctx.drawImage(source, dx, dy, dw, dh);
   }
   /** @inheritdoc */
+  drawImageRect(source, sx, sy, sw, sh, dx, dy, dw, dh) {
+    this.flush();
+    this.ctx.drawImage(source, sx, sy, sw, sh, dx, dy, dw, dh);
+  }
+  /** @inheritdoc */
   fillCircle(cx, cy, radius, color, alpha = 1) {
     if (this.batchActive && (color !== this.batchColor || alpha !== this.batchAlpha)) {
       this.flush();
@@ -1809,15 +1814,201 @@ var WebGPUParticleSystemManager = (_class3 = class {
   }
 }, _class3);
 
+// src/renderer/GlyphRasterAtlas.ts
+var HARD_MAX_SIZE = 8192;
+var PAD = 2;
+var GlyphRasterAtlas = (_class4 = class {
+  __init35() {this.slots = /* @__PURE__ */ new Map()}
+  
+  
+  __init36() {this.canvas = null}
+  __init37() {this.ctx = null}
+  /**
+   * Shelf packing: glyphs land left-to-right on a row, then a new row starts.
+   * A monospace grid produces near-uniform widths, so shelves waste very little
+   * and cost one comparison per insert — a real 2D packer would buy nothing here.
+   */
+  __init38() {this.penX = PAD}
+  __init39() {this.penY = PAD}
+  __init40() {this.rowHeight = 0}
+  __init41() {this._hits = 0}
+  __init42() {this._misses = 0}
+  __init43() {this._resets = 0}
+  constructor(options = {}) {;_class4.prototype.__init35.call(this);_class4.prototype.__init36.call(this);_class4.prototype.__init37.call(this);_class4.prototype.__init38.call(this);_class4.prototype.__init39.call(this);_class4.prototype.__init40.call(this);_class4.prototype.__init41.call(this);_class4.prototype.__init42.call(this);_class4.prototype.__init43.call(this);
+    this.dpr = Math.max(1, _nullishCoalesce(options.dpr, () => ( 1)));
+    this.maxSize = Math.min(HARD_MAX_SIZE, Math.max(256, _nullishCoalesce(options.maxSize, () => ( 2048))));
+  }
+  /** Live instrumentation snapshot. */
+  get stats() {
+    return {
+      hits: this._hits,
+      misses: this._misses,
+      size: this.slots.size,
+      resets: this._resets
+    };
+  }
+  /**
+   * The atlas canvas, to pass as the blit source.
+   *
+   * `null` until the first successful {@link get}, and in any non-DOM context.
+   */
+  get source() {
+    return this.canvas;
+  }
+  ensureCanvas() {
+    if (this.ctx) return true;
+    if (typeof document === "undefined") return false;
+    const canvas = document.createElement("canvas");
+    canvas.width = this.maxSize;
+    canvas.height = this.maxSize;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return false;
+    this.canvas = canvas;
+    this.ctx = ctx;
+    return true;
+  }
+  /**
+   * Look up a glyph, rasterizing it into the atlas on first request.
+   *
+   * @param font - Full CSS `font` shorthand, used for measuring and painting.
+   * @param color - CSS color baked into the pixels.
+   * @param glyph - A single grapheme cluster. Long strings are rejected
+   *   (`null`): they defeat the atlas's fixed-slot packing and belong in
+   *   `fillText` or {@link TextRasterCache}.
+   * @returns The slot, or `null` when the caller must fall back to `fillText`
+   *   (headless, unrasterizable, or too large to pack).
+   */
+  get(font, color, glyph) {
+    const key = font + "\0" + color + "\0" + glyph;
+    const existing = this.slots.get(key);
+    if (existing !== void 0) {
+      if (existing) this._hits++;
+      return existing;
+    }
+    this._misses++;
+    if (glyph.length === 0 || glyph.length > 8) {
+      this.slots.set(key, null);
+      return null;
+    }
+    if (!this.ensureCanvas()) return null;
+    const ctx = this.ctx;
+    ctx.font = font;
+    const metrics = ctx.measureText(glyph);
+    const advance = metrics.width;
+    const ascent = metrics.actualBoundingBoxAscent || metrics.fontBoundingBoxAscent || advance * 0.9;
+    const descent = metrics.actualBoundingBoxDescent || metrics.fontBoundingBoxDescent || advance * 0.25;
+    const left = metrics.actualBoundingBoxLeft || 0;
+    const right = metrics.actualBoundingBoxRight || advance;
+    const offsetX = Math.ceil(left) + PAD;
+    const offsetY = Math.ceil(ascent) + PAD;
+    const w = offsetX + Math.ceil(right) + PAD;
+    const h = offsetY + Math.ceil(descent) + PAD;
+    if (!(w > 0) || !(h > 0)) {
+      this.slots.set(key, null);
+      return null;
+    }
+    const dpr = this.dpr;
+    const dw = Math.ceil(w * dpr);
+    const dh = Math.ceil(h * dpr);
+    if (dw + PAD * 2 > this.maxSize || dh + PAD * 2 > this.maxSize) {
+      this.slots.set(key, null);
+      return null;
+    }
+    if (this.penX + dw + PAD > this.maxSize) {
+      this.penX = PAD;
+      this.penY += this.rowHeight + PAD;
+      this.rowHeight = 0;
+    }
+    if (this.penY + dh + PAD > this.maxSize) {
+      this.reset();
+      if (!this.ensureCanvas()) return null;
+      this.ctx.font = font;
+    }
+    const sx = this.penX;
+    const sy = this.penY;
+    const c = this.ctx;
+    c.save();
+    c.translate(sx, sy);
+    if (dpr !== 1) c.scale(dpr, dpr);
+    c.font = font;
+    c.textBaseline = "alphabetic";
+    c.fillStyle = color;
+    c.fillText(glyph, offsetX, offsetY);
+    c.restore();
+    this.penX += dw + PAD;
+    if (dh > this.rowHeight) this.rowHeight = dh;
+    const slot = {
+      sx,
+      sy,
+      sw: dw,
+      sh: dh,
+      w,
+      h,
+      offsetX,
+      offsetY,
+      glyph,
+      font,
+      advance,
+      left,
+      right
+    };
+    this.slots.set(key, slot);
+    return slot;
+  }
+  /**
+   * Find the slot occupying a source position, or `null`.
+   *
+   * The inverse of {@link get}: it maps a blit back to the glyph it drew. Exists
+   * for instrumentation — a test or devtool that traces `drawImage` calls sees
+   * only a source rect, and needs this to recover which cluster was painted and
+   * with what metrics. Linear over resident slots, so it is a diagnostic, not a
+   * per-frame call.
+   */
+  slotAt(sx, sy) {
+    for (const slot of this.slots.values()) {
+      if (slot && slot.sx === sx && slot.sy === sy) return slot;
+    }
+    return null;
+  }
+  /**
+   * Drop every glyph and reuse the canvas.
+   *
+   * Call after a font or theme change: slots are keyed by `(font, color, glyph)`
+   * so stale entries are never *returned* wrongly, but they do occupy space.
+   */
+  reset() {
+    this.slots.clear();
+    this.penX = PAD;
+    this.penY = PAD;
+    this.rowHeight = 0;
+    this._resets++;
+    if (this.ctx && this.canvas) {
+      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    }
+  }
+  /** Release the backing canvas and all slots. */
+  destroy() {
+    this.slots.clear();
+    this.canvas = null;
+    this.ctx = null;
+    this.penX = PAD;
+    this.penY = PAD;
+    this.rowHeight = 0;
+    this._hits = 0;
+    this._misses = 0;
+    this._resets = 0;
+  }
+}, _class4);
+
 // src/renderer/TextRasterCache.ts
-var TextRasterCache = (_class4 = class {
-  __init35() {this.cache = /* @__PURE__ */ new Map()}
+var TextRasterCache = (_class5 = class {
+  __init44() {this.cache = /* @__PURE__ */ new Map()}
   
   
-  __init36() {this.scratchCtx = null}
-  __init37() {this._hits = 0}
-  __init38() {this._misses = 0}
-  constructor(options = {}) {;_class4.prototype.__init35.call(this);_class4.prototype.__init36.call(this);_class4.prototype.__init37.call(this);_class4.prototype.__init38.call(this);
+  __init45() {this.scratchCtx = null}
+  __init46() {this._hits = 0}
+  __init47() {this._misses = 0}
+  constructor(options = {}) {;_class5.prototype.__init44.call(this);_class5.prototype.__init45.call(this);_class5.prototype.__init46.call(this);_class5.prototype.__init47.call(this);
     this.maxEntries = Math.max(1, _nullishCoalesce(options.maxEntries, () => ( 4096)));
     this.dpr = Math.max(1, _nullishCoalesce(options.dpr, () => ( 1)));
   }
@@ -1892,7 +2083,8 @@ var TextRasterCache = (_class4 = class {
     this._hits = 0;
     this._misses = 0;
   }
-}, _class4);
+}, _class5);
+
 
 
 
@@ -1903,4 +2095,4 @@ var TextRasterCache = (_class4 = class {
 
 
 
-exports.CanvasRenderer = CanvasRenderer; exports.sanitizeUrl = sanitizeUrl; exports.isSafeUrl = isSafeUrl; exports.SVGRenderer = SVGRenderer; exports.parseColorToRGBA = parseColorToRGBA; exports.createWebGLPointRenderer = createWebGLPointRenderer; exports.WebGPUParticleSystemManager = WebGPUParticleSystemManager; exports.TextRasterCache = TextRasterCache;
+exports.CanvasRenderer = CanvasRenderer; exports.sanitizeUrl = sanitizeUrl; exports.isSafeUrl = isSafeUrl; exports.SVGRenderer = SVGRenderer; exports.parseColorToRGBA = parseColorToRGBA; exports.createWebGLPointRenderer = createWebGLPointRenderer; exports.WebGPUParticleSystemManager = WebGPUParticleSystemManager; exports.GlyphRasterAtlas = GlyphRasterAtlas; exports.TextRasterCache = TextRasterCache;

package/dist/{chunk-QS3CUV7H.mjs → chunk-RTENOAYT.mjs}

@@ -210,6 +210,11 @@ var CanvasRenderer = class _CanvasRenderer {
     this.ctx.drawImage(source, dx, dy, dw, dh);
   }
   /** @inheritdoc */
+  drawImageRect(source, sx, sy, sw, sh, dx, dy, dw, dh) {
+    this.flush();
+    this.ctx.drawImage(source, sx, sy, sw, sh, dx, dy, dw, dh);
+  }
+  /** @inheritdoc */
   fillCircle(cx, cy, radius, color, alpha = 1) {
     if (this.batchActive && (color !== this.batchColor || alpha !== this.batchAlpha)) {
       this.flush();
@@ -1807,6 +1812,192 @@ var WebGPUParticleSystemManager = class {
   }
 };
 
+// src/renderer/GlyphRasterAtlas.ts
+var HARD_MAX_SIZE = 8192;
+var PAD = 2;
+var GlyphRasterAtlas = class {
+  slots = /* @__PURE__ */ new Map();
+  dpr;
+  maxSize;
+  canvas = null;
+  ctx = null;
+  /**
+   * Shelf packing: glyphs land left-to-right on a row, then a new row starts.
+   * A monospace grid produces near-uniform widths, so shelves waste very little
+   * and cost one comparison per insert — a real 2D packer would buy nothing here.
+   */
+  penX = PAD;
+  penY = PAD;
+  rowHeight = 0;
+  _hits = 0;
+  _misses = 0;
+  _resets = 0;
+  constructor(options = {}) {
+    this.dpr = Math.max(1, options.dpr ?? 1);
+    this.maxSize = Math.min(HARD_MAX_SIZE, Math.max(256, options.maxSize ?? 2048));
+  }
+  /** Live instrumentation snapshot. */
+  get stats() {
+    return {
+      hits: this._hits,
+      misses: this._misses,
+      size: this.slots.size,
+      resets: this._resets
+    };
+  }
+  /**
+   * The atlas canvas, to pass as the blit source.
+   *
+   * `null` until the first successful {@link get}, and in any non-DOM context.
+   */
+  get source() {
+    return this.canvas;
+  }
+  ensureCanvas() {
+    if (this.ctx) return true;
+    if (typeof document === "undefined") return false;
+    const canvas = document.createElement("canvas");
+    canvas.width = this.maxSize;
+    canvas.height = this.maxSize;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return false;
+    this.canvas = canvas;
+    this.ctx = ctx;
+    return true;
+  }
+  /**
+   * Look up a glyph, rasterizing it into the atlas on first request.
+   *
+   * @param font - Full CSS `font` shorthand, used for measuring and painting.
+   * @param color - CSS color baked into the pixels.
+   * @param glyph - A single grapheme cluster. Long strings are rejected
+   *   (`null`): they defeat the atlas's fixed-slot packing and belong in
+   *   `fillText` or {@link TextRasterCache}.
+   * @returns The slot, or `null` when the caller must fall back to `fillText`
+   *   (headless, unrasterizable, or too large to pack).
+   */
+  get(font, color, glyph) {
+    const key = font + "\0" + color + "\0" + glyph;
+    const existing = this.slots.get(key);
+    if (existing !== void 0) {
+      if (existing) this._hits++;
+      return existing;
+    }
+    this._misses++;
+    if (glyph.length === 0 || glyph.length > 8) {
+      this.slots.set(key, null);
+      return null;
+    }
+    if (!this.ensureCanvas()) return null;
+    const ctx = this.ctx;
+    ctx.font = font;
+    const metrics = ctx.measureText(glyph);
+    const advance = metrics.width;
+    const ascent = metrics.actualBoundingBoxAscent || metrics.fontBoundingBoxAscent || advance * 0.9;
+    const descent = metrics.actualBoundingBoxDescent || metrics.fontBoundingBoxDescent || advance * 0.25;
+    const left = metrics.actualBoundingBoxLeft || 0;
+    const right = metrics.actualBoundingBoxRight || advance;
+    const offsetX = Math.ceil(left) + PAD;
+    const offsetY = Math.ceil(ascent) + PAD;
+    const w = offsetX + Math.ceil(right) + PAD;
+    const h = offsetY + Math.ceil(descent) + PAD;
+    if (!(w > 0) || !(h > 0)) {
+      this.slots.set(key, null);
+      return null;
+    }
+    const dpr = this.dpr;
+    const dw = Math.ceil(w * dpr);
+    const dh = Math.ceil(h * dpr);
+    if (dw + PAD * 2 > this.maxSize || dh + PAD * 2 > this.maxSize) {
+      this.slots.set(key, null);
+      return null;
+    }
+    if (this.penX + dw + PAD > this.maxSize) {
+      this.penX = PAD;
+      this.penY += this.rowHeight + PAD;
+      this.rowHeight = 0;
+    }
+    if (this.penY + dh + PAD > this.maxSize) {
+      this.reset();
+      if (!this.ensureCanvas()) return null;
+      this.ctx.font = font;
+    }
+    const sx = this.penX;
+    const sy = this.penY;
+    const c = this.ctx;
+    c.save();
+    c.translate(sx, sy);
+    if (dpr !== 1) c.scale(dpr, dpr);
+    c.font = font;
+    c.textBaseline = "alphabetic";
+    c.fillStyle = color;
+    c.fillText(glyph, offsetX, offsetY);
+    c.restore();
+    this.penX += dw + PAD;
+    if (dh > this.rowHeight) this.rowHeight = dh;
+    const slot = {
+      sx,
+      sy,
+      sw: dw,
+      sh: dh,
+      w,
+      h,
+      offsetX,
+      offsetY,
+      glyph,
+      font,
+      advance,
+      left,
+      right
+    };
+    this.slots.set(key, slot);
+    return slot;
+  }
+  /**
+   * Find the slot occupying a source position, or `null`.
+   *
+   * The inverse of {@link get}: it maps a blit back to the glyph it drew. Exists
+   * for instrumentation — a test or devtool that traces `drawImage` calls sees
+   * only a source rect, and needs this to recover which cluster was painted and
+   * with what metrics. Linear over resident slots, so it is a diagnostic, not a
+   * per-frame call.
+   */
+  slotAt(sx, sy) {
+    for (const slot of this.slots.values()) {
+      if (slot && slot.sx === sx && slot.sy === sy) return slot;
+    }
+    return null;
+  }
+  /**
+   * Drop every glyph and reuse the canvas.
+   *
+   * Call after a font or theme change: slots are keyed by `(font, color, glyph)`
+   * so stale entries are never *returned* wrongly, but they do occupy space.
+   */
+  reset() {
+    this.slots.clear();
+    this.penX = PAD;
+    this.penY = PAD;
+    this.rowHeight = 0;
+    this._resets++;
+    if (this.ctx && this.canvas) {
+      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    }
+  }
+  /** Release the backing canvas and all slots. */
+  destroy() {
+    this.slots.clear();
+    this.canvas = null;
+    this.ctx = null;
+    this.penX = PAD;
+    this.penY = PAD;
+    this.rowHeight = 0;
+    this._hits = 0;
+    this._misses = 0;
+    this._resets = 0;
+  }
+};
+
 // src/renderer/TextRasterCache.ts
 var TextRasterCache = class {
   cache = /* @__PURE__ */ new Map();
@@ -1900,5 +2091,6 @@ export {
   parseColorToRGBA,
   createWebGLPointRenderer,
   WebGPUParticleSystemManager,
+  GlyphRasterAtlas,
   TextRasterCache
 };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './renderer/WebGLPointRenderer';
 export * from './renderer/WebGPUParticleSystemManager';
 export * from './renderer/colorParse';
 export * from './renderer/url';
+export * from './renderer/GlyphRasterAtlas';
 export * from './renderer/TextRasterCache';
 export * from './tree/Entity';
 export * from './tree/Scene';