@vectojs/core 1.20.0 → 1.22.0

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

@@ -1,4 +1,19 @@
 // src/renderer/CanvasRenderer.ts
+function emptyDrawCounters() {
+  return {
+    fills: 0,
+    strokes: 0,
+    texts: 0,
+    images: 0,
+    circles: 0,
+    flushes: 0,
+    saves: 0,
+    restores: 0,
+    clips: 0,
+    stateSwitches: 0,
+    overdrawRatio: 0
+  };
+}
 var TWO_PI = Math.PI * 2;
 function getDevicePixelRatio() {
   return typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
@@ -39,6 +54,17 @@ var CanvasRenderer = class _CanvasRenderer {
   batchCount = 0;
   _cachedFont = "";
   _cachedFill = "";
+  /** Backend discriminator; see {@link IRenderer.kind}. */
+  kind = "canvas2d";
+  /**
+   * Draw counters, allocated only once counting is enabled.
+   *
+   * Null when off, so the guard on every op is a single null test and an inactive
+   * renderer carries no counter object at all.
+   */
+  counters = null;
+  /** Accumulated primitive area, kept separately so the ratio is derived on read. */
+  drawnArea = 0;
   /**
    * @param canvas - The target canvas. Its backing store is resized to the
    *   logical size × devicePixelRatio.
@@ -135,19 +161,47 @@ var CanvasRenderer = class _CanvasRenderer {
     return this.contextLost;
   }
   /** @inheritdoc */
+  /** @inheritdoc */
+  setDrawCounters(enabled) {
+    if (!enabled) {
+      this.counters = null;
+      this.drawnArea = 0;
+      return;
+    }
+    if (!this.counters) this.counters = emptyDrawCounters();
+  }
+  /** @inheritdoc */
+  getDrawCounters() {
+    if (!this.counters) return null;
+    const area = this.width * this.height;
+    return {
+      ...this.counters,
+      // Derived on read rather than maintained: the ratio is only meaningful
+      // against the current surface size, which can change under resize.
+      overdrawRatio: area > 0 ? Math.round(this.drawnArea / area * 100) / 100 : 0
+    };
+  }
+  /** @inheritdoc */
+  clearDrawCounters() {
+    if (this.counters) this.counters = emptyDrawCounters();
+    this.drawnArea = 0;
+  }
   clear() {
     if (this.contextLost) return;
     this.flush();
+    if (this.counters) this.drawnArea = 0;
     this.ctx.clearRect(0, 0, this.width, this.height);
   }
   /** @inheritdoc */
   save() {
     this.flush();
+    if (this.counters) this.counters.saves++;
     this.ctx.save();
   }
   /** @inheritdoc */
   restore() {
     this.flush();
+    if (this.counters) this.counters.restores++;
     this.ctx.restore();
     this._cachedFont = "";
     this._cachedFill = "";
@@ -171,6 +225,7 @@ var CanvasRenderer = class _CanvasRenderer {
   /** @inheritdoc */
   clip(x, y, width, height) {
     this.flush();
+    if (this.counters) this.counters.clips++;
     this.ctx.beginPath();
     this.ctx.rect(x, y, width, height);
     this.ctx.clip();
@@ -207,9 +262,22 @@ var CanvasRenderer = class _CanvasRenderer {
   /** @inheritdoc */
   drawImage(source, dx, dy, dw, dh) {
     this.flush();
+    if (this.counters) {
+      this.counters.images++;
+      this.drawnArea += Math.abs(dw * dh);
+    }
     this.ctx.drawImage(source, dx, dy, dw, dh);
   }
   /** @inheritdoc */
+  drawImageRect(source, sx, sy, sw, sh, dx, dy, dw, dh) {
+    this.flush();
+    if (this.counters) {
+      this.counters.images++;
+      this.drawnArea += Math.abs(dw * dh);
+    }
+    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();
@@ -220,6 +288,10 @@ var CanvasRenderer = class _CanvasRenderer {
       this.batchColor = color;
       this.batchAlpha = alpha;
     }
+    if (this.counters) {
+      this.counters.circles++;
+      this.drawnArea += Math.PI * radius * radius;
+    }
     this.ctx.moveTo(cx + radius, cy);
     this.ctx.arc(cx, cy, radius, 0, TWO_PI);
     this.batchCount++;
@@ -228,6 +300,7 @@ var CanvasRenderer = class _CanvasRenderer {
   /** @inheritdoc */
   flush() {
     if (!this.batchActive) return;
+    if (this.counters) this.counters.flushes++;
     this.ctx.globalAlpha = this.batchAlpha;
     this.ctx.fillStyle = this.batchColor;
     this.ctx.fill();
@@ -238,7 +311,9 @@ var CanvasRenderer = class _CanvasRenderer {
   /** @inheritdoc */
   fill(color) {
     this.flush();
+    if (this.counters) this.counters.fills++;
     if (this._cachedFill !== color) {
+      if (this.counters) this.counters.stateSwitches++;
       this.ctx.fillStyle = color;
       this._cachedFill = color;
     }
@@ -247,6 +322,7 @@ var CanvasRenderer = class _CanvasRenderer {
   /** @inheritdoc */
   stroke(color, lineWidth = 1) {
     this.flush();
+    if (this.counters) this.counters.strokes++;
     this.ctx.strokeStyle = color;
     this.ctx.lineWidth = lineWidth;
     this.ctx.lineCap = "round";
@@ -256,11 +332,14 @@ var CanvasRenderer = class _CanvasRenderer {
   /** @inheritdoc */
   fillText(text, x, y, font, color) {
     this.flush();
+    if (this.counters) this.counters.texts++;
     if (this._cachedFont !== font) {
+      if (this.counters) this.counters.stateSwitches++;
       this.ctx.font = font;
       this._cachedFont = font;
     }
     if (this._cachedFill !== color) {
+      if (this.counters) this.counters.stateSwitches++;
       this.ctx.fillStyle = color;
       this._cachedFill = color;
     }
@@ -371,6 +450,8 @@ function fontFamilyFromShorthand(font, sizeToken) {
   return family || "sans-serif";
 }
 var SVGRenderer = class {
+  /** Backend discriminator; see {@link IRenderer.kind}. */
+  kind = "svg";
   width;
   height;
   buffer = [];
@@ -1223,6 +1304,12 @@ function createWebGLPointRenderer(canvas) {
   let spriteCount = 0;
   let glyphData = new Float32Array(FLOATS_PER_SPRITE_VERT * VERTS_PER_QUAD * 1024);
   let glyphCount = 0;
+  let frameDrawCalls = 0;
+  let lastFrameDrawCalls = 0;
+  let totalDrawCalls = 0;
+  let atlasSwitches = 0;
+  let circleQuadFallbacks = 0;
+  let circlePoints = 0;
   let circleQuadData = new Float32Array(FLOATS_PER_SPRITE_VERT * VERTS_PER_QUAD * 64);
   let circleQuadCount = 0;
   let logicalW = 0;
@@ -1245,6 +1332,7 @@ function createWebGLPointRenderer(canvas) {
     gl.uniform1f(gURange, distanceRange);
     ensureQuadIndices(glyphCount);
     gl.drawElements(gl.TRIANGLES, glyphCount * INDICES_PER_QUAD, gl.UNSIGNED_INT, 0);
+    frameDrawCalls++;
     gl.bindVertexArray(null);
     glyphCount = 0;
   };
@@ -1261,7 +1349,23 @@ function createWebGLPointRenderer(canvas) {
       canvas.style.height = `${height}px`;
       gl.viewport(0, 0, canvas.width, canvas.height);
     },
+    stats() {
+      return {
+        drawCalls: lastFrameDrawCalls,
+        totalDrawCalls,
+        atlasSwitches,
+        // Fixed at creation: five programs compiled once, never per frame, so
+        // these are capability facts rather than counters.
+        programs: 5,
+        textures: (texture ? 1 : 0) + (msdfTexture ? 1 : 0),
+        circleQuadFallbacks,
+        circlePoints
+      };
+    },
     begin() {
+      lastFrameDrawCalls = frameDrawCalls;
+      totalDrawCalls += frameDrawCalls;
+      frameDrawCalls = 0;
       pointCount = 0;
       rectCount = 0;
       spriteCount = 0;
@@ -1314,6 +1418,7 @@ function createWebGLPointRenderer(canvas) {
         distanceRange = range;
         return;
       }
+      atlasSwitches++;
       drawGlyphs();
       distanceRange = range;
       if (!msdfTexture) {
@@ -1356,6 +1461,7 @@ function createWebGLPointRenderer(canvas) {
     addCircle(x, y, radius, color, alpha = 1) {
       const needsQuad = logicalW > 0 && (x < radius || y < radius || x > logicalW - radius || y > logicalH - radius) || radius * 2 * dpr > maxPointSize;
       if (needsQuad) {
+        circleQuadFallbacks++;
         const stride = FLOATS_PER_SPRITE_VERT * VERTS_PER_QUAD;
         circleQuadData = grow(circleQuadData, (circleQuadCount + 1) * stride);
         const rgba = parseColorToRGBA(color);
@@ -1380,6 +1486,7 @@ function createWebGLPointRenderer(canvas) {
         circleQuadCount++;
         return;
       }
+      circlePoints++;
       pointData = grow(pointData, (pointCount + 1) * FLOATS_PER_POINT);
       const [r, g, b, a] = parseColorToRGBA(color);
       const o = pointCount * FLOATS_PER_POINT;
@@ -1421,6 +1528,7 @@ function createWebGLPointRenderer(canvas) {
         gl.uniform2f(rURes, logicalW, logicalH);
         ensureQuadIndices(rectCount);
         gl.drawElements(gl.TRIANGLES, rectCount * INDICES_PER_QUAD, gl.UNSIGNED_INT, 0);
+        frameDrawCalls++;
       }
       if (pointCount > 0) {
         gl.useProgram(pointProgram);
@@ -1434,6 +1542,7 @@ function createWebGLPointRenderer(canvas) {
         gl.uniform2f(pURes, logicalW, logicalH);
         gl.uniform1f(pUDpr, dpr);
         gl.drawArrays(gl.POINTS, 0, pointCount);
+        frameDrawCalls++;
       }
       if (circleQuadCount > 0) {
         const floats = circleQuadCount * VERTS_PER_QUAD * FLOATS_PER_SPRITE_VERT;
@@ -1444,6 +1553,7 @@ function createWebGLPointRenderer(canvas) {
         gl.uniform2f(cURes, logicalW, logicalH);
         ensureQuadIndices(circleQuadCount);
         gl.drawElements(gl.TRIANGLES, circleQuadCount * INDICES_PER_QUAD, gl.UNSIGNED_INT, 0);
+        frameDrawCalls++;
       }
       if (spriteCount > 0 && texture) {
         const floats = spriteCount * VERTS_PER_QUAD * FLOATS_PER_SPRITE_VERT;
@@ -1457,6 +1567,7 @@ function createWebGLPointRenderer(canvas) {
         gl.uniform2f(sURes, logicalW, logicalH);
         ensureQuadIndices(spriteCount);
         gl.drawElements(gl.TRIANGLES, spriteCount * INDICES_PER_QUAD, gl.UNSIGNED_INT, 0);
+        frameDrawCalls++;
       }
       gl.bindVertexArray(null);
       drawGlyphs();
@@ -1807,6 +1918,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 +2197,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';