@vanduo-oss/vd3-cbun 1.3.2 → 1.4.1

package/dist/hex-grid/index.js

@@ -128,22 +128,54 @@ function getTerrainColor(terrainType) {
 }
 
 // src/hex-grid/core.js
-var VD_HEX_VERSION = "1.0.1";
+var VD_HEX_VERSION = "1.1.0";
 var ZOOM_MIN = 0.3;
 var ZOOM_MAX = 3;
 var ZOOM_FACTOR = 0.1;
 var DRAG_THRESHOLD = 2;
+var FAST_RENDER_LIMIT = 8e3;
+var SHARP_IDLE_MS = 120;
+var MAX_PIXEL_RATIO = 2;
+var MIN_BUCKET_SIZE = 64;
+var now = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 var VdHexGrid = class {
-  constructor({ element, canvas, size = 30, width = 10, height = 10, rotation = 0 }) {
+  constructor({
+    element,
+    canvas,
+    size = 30,
+    width = 10,
+    height = 10,
+    rotation = 0,
+    pixelRatio = "auto",
+    cull = true
+  }) {
     this.element = element;
     this.canvas = canvas;
     this.size = size;
     this.width = width;
     this.height = height;
     this.rotation = rotation;
+    this.pixelRatio = pixelRatio;
+    this.cull = cull;
     this.hexes = /* @__PURE__ */ new Map();
     this.selectedHex = null;
     this.listeners = {};
+    this._bucketSize = Math.max(size * 2, MIN_BUCKET_SIZE);
+    this._index = /* @__PURE__ */ new Map();
+    this._gestureCancel = null;
+    this._sharpTimer = null;
+    this._frameCanvas = null;
+    this._frameCtx = null;
+    this._frameTransform = null;
+    this._stats = {
+      total: 0,
+      visible: 0,
+      drawn: 0,
+      mode: "sharp",
+      lastRenderMs: 0,
+      pixelRatio: 1,
+      scale: 1
+    };
     this.transform = { x: 0, y: 0, scale: 1 };
     this.dragging = false;
     this.lastPos = null;
@@ -203,6 +235,14 @@ var VdHexGrid = class {
    */
   destroy() {
     this._teardownEvents();
+    this._cancelGestureRender();
+    if (this._sharpTimer) {
+      clearTimeout(this._sharpTimer);
+      this._sharpTimer = null;
+    }
+    this._frameCanvas = null;
+    this._frameCtx = null;
+    this._frameTransform = null;
     if (this._themeObserver) {
       this._themeObserver.disconnect();
       this._themeObserver = null;
@@ -213,6 +253,195 @@ var VdHexGrid = class {
       this._themeMediaHandler = null;
     }
   }
+  /**
+   * Resolve the effective device-pixel-ratio multiplier.
+   * @returns {number}
+   */
+  _resolvePixelRatio() {
+    const requested = this.pixelRatio;
+    if (requested === "auto" || requested == null) {
+      const dpr = typeof window !== "undefined" && typeof window.devicePixelRatio === "number" ? window.devicePixelRatio : 1;
+      return Math.max(1, Math.min(dpr || 1, MAX_PIXEL_RATIO));
+    }
+    const n = Number(requested);
+    return Number.isFinite(n) && n > 0 ? n : 1;
+  }
+  /** Request an animation frame, returning a cancel function. */
+  _requestFrame(callback) {
+    if (typeof requestAnimationFrame === "function") {
+      const id2 = requestAnimationFrame(callback);
+      return () => cancelAnimationFrame(id2);
+    }
+    const id = setTimeout(callback, 16);
+    return () => clearTimeout(id);
+  }
+  /** Cancel a pending gesture frame, if any. */
+  _cancelGestureRender() {
+    if (this._gestureCancel) {
+      this._gestureCancel();
+      this._gestureCancel = null;
+    }
+  }
+  /**
+   * Coalesce gesture-driven transform changes into at most one render/frame.
+   */
+  _scheduleGestureRender() {
+    if (this._gestureCancel) return;
+    this._gestureCancel = this._requestFrame(() => {
+      this._gestureCancel = null;
+      this._renderGesture();
+    });
+  }
+  /**
+   * Schedule a sharp culled re-render after the gesture goes idle.
+   */
+  _scheduleSharpRender() {
+    if (this._sharpTimer) clearTimeout(this._sharpTimer);
+    this._sharpTimer = setTimeout(() => {
+      this._sharpTimer = null;
+      this._render();
+    }, SHARP_IDLE_MS);
+  }
+  /** Render the current gesture frame (fast blit or sharp, adaptively). */
+  _renderGesture() {
+    const visible = this.cull ? this._computeVisibleHexes() : null;
+    const count = visible ? visible.length : this.hexes.size;
+    if (count > FAST_RENDER_LIMIT && this._frameCanvas) {
+      this._blitFrame();
+    } else {
+      this._render(visible);
+    }
+    this._scheduleSharpRender();
+  }
+  /**
+   * Blit the last sharp frame snapshot offset/scaled for the current transform.
+   * The snapshot is in screen (CSS) space at `_frameTransform`; this maps the
+   * pixel under the old transform to its position under the current transform.
+   */
+  _blitFrame() {
+    const frame = this._frameCanvas;
+    const from = this._frameTransform;
+    if (!frame || !from || !frame.width || !frame.height) {
+      this._render();
+      return;
+    }
+    const rect = this.canvas.getBoundingClientRect();
+    const displayWidth = rect.width || 800;
+    const displayHeight = rect.height || 400;
+    const ratio = this._resolvePixelRatio();
+    const { x, y, scale } = this.transform;
+    const k = scale / (from.scale || 1);
+    const bx = x - k * from.x;
+    const by = y - k * from.y;
+    this.ctx.setTransform(1, 0, 0, 1, 0, 0);
+    this.ctx.fillStyle = this.themeColors.bgPrimary;
+    this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+    this.ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+    this.ctx.drawImage(
+      frame,
+      0,
+      0,
+      frame.width,
+      frame.height,
+      bx,
+      by,
+      displayWidth * k,
+      displayHeight * k
+    );
+    this.ctx.setTransform(1, 0, 0, 1, 0, 0);
+    this._stats.mode = "fast";
+    this._stats.pixelRatio = ratio;
+    this._stats.scale = scale;
+    this._stats.lastRenderMs = 0;
+  }
+  /**
+   * Capture the current canvas into the offscreen frame snapshot.
+   */
+  _captureFrame() {
+    const w = this.canvas.width;
+    const h2 = this.canvas.height;
+    if (!w || !h2) return;
+    if (!this._frameCanvas) {
+      this._frameCanvas = typeof document !== "undefined" ? document.createElement("canvas") : null;
+      if (!this._frameCanvas) return;
+    }
+    const frame = this._frameCanvas;
+    if (frame.width !== w) frame.width = w;
+    if (frame.height !== h2) frame.height = h2;
+    const fctx = frame.getContext("2d");
+    if (!fctx) return;
+    this._frameCtx = fctx;
+    fctx.setTransform(1, 0, 0, 1, 0, 0);
+    fctx.clearRect(0, 0, w, h2);
+    fctx.drawImage(this.canvas, 0, 0);
+    this._frameTransform = { ...this.transform };
+  }
+  /**
+   * Compute the cells intersecting the current viewport (always culled by the
+   * viewport, independent of the `cull` render switch). Uses the spatial bucket
+   * index when present.
+   * @returns {HexCell[]}
+   */
+  _computeVisibleHexes() {
+    const rect = this.canvas.getBoundingClientRect();
+    const displayWidth = rect.width || 800;
+    const displayHeight = rect.height || 400;
+    const { x, y, scale } = this.transform;
+    const minX = -x / scale - this.size;
+    const maxX = (displayWidth - x) / scale + this.size;
+    const minY = -y / scale - this.size;
+    const maxY = (displayHeight - y) / scale + this.size;
+    if (!this._index || this._index.size === 0) return this.getAllHexes();
+    const bs = this._bucketSize;
+    const bx0 = Math.floor(minX / bs);
+    const bx1 = Math.floor(maxX / bs);
+    const by0 = Math.floor(minY / bs);
+    const by1 = Math.floor(maxY / bs);
+    const out = [];
+    for (let by = by0; by <= by1; by++) {
+      for (let bx = bx0; bx <= bx1; bx++) {
+        const bucket = this._index.get(`${bx},${by}`);
+        if (!bucket) continue;
+        for (let i = 0; i < bucket.length; i++) {
+          const hex = bucket[i];
+          if (hex.x >= minX && hex.x <= maxX && hex.y >= minY && hex.y <= maxY) {
+            out.push(hex);
+          }
+        }
+      }
+    }
+    return out;
+  }
+  /**
+   * Get the cells intersecting the current viewport, sorted by row then column.
+   * @returns {HexCell[]}
+   */
+  getVisibleHexes() {
+    return this._computeVisibleHexes().sort((a, b) => a.r - b.r || a.q - b.q);
+  }
+  /**
+   * Last-frame render metrics.
+   * @returns {{total: number, visible: number, drawn: number, mode: string, lastRenderMs: number, pixelRatio: number, scale: number}}
+   */
+  getRenderStats() {
+    return { ...this._stats };
+  }
+  /**
+   * Set the device-pixel-ratio multiplier and re-render (no grid regeneration).
+   * @param {number|'auto'} ratio
+   */
+  setPixelRatio(ratio) {
+    this.pixelRatio = ratio;
+    this._render();
+  }
+  /**
+   * Toggle viewport culling and re-render (no grid regeneration).
+   * @param {boolean} cull
+   */
+  setCull(cull) {
+    this.cull = !!cull;
+    this._render();
+  }
   /**
    * Convert screen coordinates to world coordinates
    */
@@ -240,6 +469,8 @@ var VdHexGrid = class {
    */
   _generateGrid() {
     this.hexes.clear();
+    this._bucketSize = Math.max(this.size * 2, MIN_BUCKET_SIZE);
+    this._index = /* @__PURE__ */ new Map();
     for (let r = 0; r < this.height; r++) {
       const qOffset = Math.floor(r / 2);
       for (let q = -qOffset; q < this.width - qOffset; q++) {
@@ -256,6 +487,15 @@ var VdHexGrid = class {
           data: {}
         };
         this.hexes.set(`${q},${r}`, hex);
+        const bx = Math.floor(hex.x / this._bucketSize);
+        const by = Math.floor(hex.y / this._bucketSize);
+        const key = `${bx},${by}`;
+        let bucket = this._index.get(key);
+        if (!bucket) {
+          bucket = [];
+          this._index.set(key, bucket);
+        }
+        bucket.push(hex);
       }
     }
   }
@@ -267,29 +507,55 @@ var VdHexGrid = class {
     this.selectedHex = this.hexes.get(`${this.selectedHex.q},${this.selectedHex.r}`) ?? null;
   }
   /**
-   * Render the hex grid on canvas
+   * Render the hex grid on canvas (synchronous sharp render).
+   *
+   * @param {HexCell[]|null} [precomputedVisible] - Visible cells to draw when
+   *   culling is on; computed from the viewport when omitted.
    */
-  _render() {
+  _render(precomputedVisible) {
+    const started = now();
     const rect = this.canvas.getBoundingClientRect();
     const displayWidth = rect.width || 800;
     const displayHeight = rect.height || 400;
-    this.canvas.width = displayWidth;
-    this.canvas.height = displayHeight;
+    const ratio = this._resolvePixelRatio();
+    const bufferWidth = Math.max(1, Math.round(displayWidth * ratio));
+    const bufferHeight = Math.max(1, Math.round(displayHeight * ratio));
+    if (this.canvas.width !== bufferWidth) this.canvas.width = bufferWidth;
+    if (this.canvas.height !== bufferHeight) this.canvas.height = bufferHeight;
+    this.ctx.setTransform(1, 0, 0, 1, 0, 0);
     this.ctx.fillStyle = this.themeColors.bgPrimary;
     this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+    this.ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
     this.ctx.save();
     this.ctx.translate(this.transform.x, this.transform.y);
     this.ctx.scale(this.transform.scale, this.transform.scale);
-    this.hexes.forEach((hex) => {
+    const visible = this.cull && this._index && this._index.size > 0 ? precomputedVisible || this._computeVisibleHexes() : null;
+    let drawn = 0;
+    const drawHex = (hex) => {
       this._drawHex(hex);
+      drawn += 1;
       if (this.customRenderCallback) {
         this.customRenderCallback(this.ctx, hex, this.size);
       }
-    });
+    };
+    if (visible) {
+      for (let i = 0; i < visible.length; i++) drawHex(visible[i]);
+    } else {
+      this.hexes.forEach(drawHex);
+    }
     if (this.selectedHex) {
       this._drawHex(this.selectedHex, true);
     }
     this.ctx.restore();
+    this.ctx.setTransform(1, 0, 0, 1, 0, 0);
+    this._stats.total = this.hexes.size;
+    this._stats.visible = visible ? visible.length : this.hexes.size;
+    this._stats.drawn = drawn;
+    this._stats.mode = "sharp";
+    this._stats.pixelRatio = ratio;
+    this._stats.scale = this.transform.scale;
+    this._stats.lastRenderMs = now() - started;
+    this._captureFrame();
   }
   /**
    * Draw a single hex
@@ -355,11 +621,20 @@ var VdHexGrid = class {
         this.transform.x += dx;
         this.transform.y += dy;
         this.lastPos = cur;
-        this._render();
+        this._scheduleGestureRender();
       },
       // Pan - pointer up / leave (shared stopDrag)
       pointerup: () => {
+        const wasDragging = this.dragging;
         this.dragging = false;
+        if (wasDragging) {
+          this._cancelGestureRender();
+          if (this._sharpTimer) {
+            clearTimeout(this._sharpTimer);
+            this._sharpTimer = null;
+          }
+          this._render();
+        }
         if (!this.hasMoved) {
           this.canvas.style.cursor = "pointer";
         }
@@ -386,7 +661,7 @@ var VdHexGrid = class {
         this.transform.x = mouse.x - (mouse.x - this.transform.x) * scaleDiff;
         this.transform.y = mouse.y - (mouse.y - this.transform.y) * scaleDiff;
         this.transform.scale = newScale;
-        this._render();
+        this._scheduleGestureRender();
         this._emit("zoom", { scale: this.transform.scale });
       },
       // Touch events for pinch-to-zoom
@@ -411,12 +686,18 @@ var VdHexGrid = class {
           this.transform.x = center.x - (center.x - this.transform.x) * scaleDiff;
           this.transform.y = center.y - (center.y - this.transform.y) * scaleDiff;
           this.transform.scale = newScale;
-          this._render();
+          this._scheduleGestureRender();
           this._emit("zoom", { scale: this.transform.scale });
         }
       },
       touchend: () => {
         this.touchState.touches = [];
+        this._cancelGestureRender();
+        if (this._sharpTimer) {
+          clearTimeout(this._sharpTimer);
+          this._sharpTimer = null;
+        }
+        this._render();
       },
       // Cursor style
       mouseenter: () => {
@@ -867,7 +1148,11 @@ var VdHexGrid2 = defineComponent({
     /** Grid rows (number of hexes). */
     height: { type: Number, default: 10 },
     /** Grid rotation (radians). */
-    rotation: { type: Number, default: 0 }
+    rotation: { type: Number, default: 0 },
+    /** Canvas backing-store multiplier: a number or `'auto'` (default). */
+    pixelRatio: { type: [Number, String], default: "auto" },
+    /** Viewport culling (default true). */
+    cull: { type: Boolean, default: true }
   },
   emits: ["select", "zoom", "pan", "ready"],
   setup(props, { emit, expose }) {
@@ -879,7 +1164,9 @@ var VdHexGrid2 = defineComponent({
         size: props.size,
         width: props.width,
         height: props.height,
-        rotation: props.rotation
+        rotation: props.rotation,
+        pixelRatio: props.pixelRatio,
+        cull: props.cull
       });
       FORWARDED_EVENTS.forEach((name) => {
         instance.on(name, (data) => emit(name, data));
@@ -902,6 +1189,14 @@ var VdHexGrid2 = defineComponent({
       () => props.rotation,
       (v) => instance && instance.setRotation(v)
     );
+    watch(
+      () => props.pixelRatio,
+      (v) => instance && instance.setPixelRatio(v)
+    );
+    watch(
+      () => props.cull,
+      (v) => instance && instance.setCull(v)
+    );
     onBeforeUnmount(() => {
       if (instance) {
         instance.destroy();