@fieldnotes/core 0.22.0 → 0.23.0

package/dist/index.cjs

@@ -2780,6 +2780,7 @@ var ElementRenderer = class {
   canvasSize = null;
   hexTileCache = null;
   hexTileCacheKey = "";
+  gridBoundsOverride = null;
   setStore(store) {
     this.store = store;
   }
@@ -2795,6 +2796,9 @@ var ElementRenderer = class {
   setCanvasSize(w, h) {
     this.canvasSize = { w, h };
   }
+  setGridBoundsOverride(bounds) {
+    this.gridBoundsOverride = bounds;
+  }
   isDomElement(element) {
     return DOM_ELEMENT_TYPES.has(element.type);
   }
@@ -2965,20 +2969,20 @@ var ElementRenderer = class {
     }
   }
   renderGrid(ctx, grid) {
-    if (!this.canvasSize) return;
+    const canvasSize = this.canvasSize;
+    if (!canvasSize) return;
     const cam = this.camera;
     if (!cam) return;
-    const topLeft = cam.screenToWorld({ x: 0, y: 0 });
-    const bottomRight = cam.screenToWorld({
-      x: this.canvasSize.w,
-      y: this.canvasSize.h
-    });
-    const bounds = {
-      minX: topLeft.x,
-      minY: topLeft.y,
-      maxX: bottomRight.x,
-      maxY: bottomRight.y
-    };
+    const bounds = this.gridBoundsOverride ?? (() => {
+      const topLeft = cam.screenToWorld({ x: 0, y: 0 });
+      const bottomRight = cam.screenToWorld({ x: canvasSize.w, y: canvasSize.h });
+      return {
+        minX: topLeft.x,
+        minY: topLeft.y,
+        maxX: bottomRight.x,
+        maxY: bottomRight.y
+      };
+    })();
     if (grid.gridType === "hex") {
       const dpr = typeof devicePixelRatio !== "undefined" ? devicePixelRatio : 1;
       const scale = cam.zoom * dpr;
@@ -4837,19 +4841,14 @@ var RenderLoop = class {
   layerManager;
   domNodeManager;
   layerCache;
+  marginViewport;
   activeDrawingLayerId = null;
-  lastZoom;
-  lastCamX;
-  lastCamY;
+  gridCacheDirty = true;
+  // set on recenter/viewport-change; consumed by the grid block
   stats = new RenderStats();
   layerGroups = /* @__PURE__ */ new Map();
   gridCacheCanvas = null;
   gridCacheCtx = null;
-  gridCacheZoom = -1;
-  gridCacheCamX = -Infinity;
-  gridCacheCamY = -Infinity;
-  gridCacheWidth = 0;
-  gridCacheHeight = 0;
   lastGridRef = null;
   constructor(deps) {
     this.canvasEl = deps.canvasEl;
@@ -4861,9 +4860,7 @@ var RenderLoop = class {
     this.layerManager = deps.layerManager;
     this.domNodeManager = deps.domNodeManager;
     this.layerCache = deps.layerCache;
-    this.lastZoom = deps.camera.zoom;
-    this.lastCamX = deps.camera.position.x;
-    this.lastCamY = deps.camera.position.y;
+    this.marginViewport = deps.marginViewport;
   }
   requestRender() {
     this.needsRender = true;
@@ -4890,7 +4887,9 @@ var RenderLoop = class {
   setCanvasSize(width, height) {
     this.canvasEl.width = width;
     this.canvasEl.height = height;
-    this.layerCache.resize(this.canvasEl.clientWidth, this.canvasEl.clientHeight);
+    const dpr = typeof devicePixelRatio !== "undefined" ? devicePixelRatio : 1;
+    this.marginViewport.setViewport(width / dpr, height / dpr, dpr);
+    this.layerCache.resize();
   }
   setActiveDrawingLayer(layerId) {
     this.activeDrawingLayerId = layerId;
@@ -4904,30 +4903,29 @@ var RenderLoop = class {
   getStats() {
     return this.stats.getSnapshot();
   }
-  compositeLayerCache(ctx, layerId, dpr) {
+  compositeLayerCache(ctx, layerId) {
     const cached = this.layerCache.getCanvas(layerId);
+    const offset = this.marginViewport.compositeOffset(
+      this.camera.position.x,
+      this.camera.position.y
+    );
     ctx.save();
-    ctx.scale(1 / this.camera.zoom, 1 / this.camera.zoom);
-    ctx.translate(-this.camera.position.x, -this.camera.position.y);
-    ctx.scale(1 / dpr, 1 / dpr);
-    ctx.drawImage(cached, 0, 0);
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.drawImage(cached, offset.x, offset.y);
     ctx.restore();
   }
-  ensureGridCache(cssWidth, cssHeight, dpr) {
-    if (this.gridCacheCanvas !== null && this.gridCacheWidth === cssWidth && this.gridCacheHeight === cssHeight) {
+  ensureGridCache() {
+    const w = this.marginViewport.physicalWidth();
+    const h = this.marginViewport.physicalHeight();
+    if (this.gridCacheCanvas !== null && this.gridCacheCanvas.width === w && this.gridCacheCanvas.height === h) {
       return;
     }
-    const physWidth = Math.round(cssWidth * dpr);
-    const physHeight = Math.round(cssHeight * dpr);
     if (typeof OffscreenCanvas !== "undefined") {
-      this.gridCacheCanvas = new OffscreenCanvas(
-        physWidth,
-        physHeight
-      );
+      this.gridCacheCanvas = new OffscreenCanvas(w, h);
     } else if (typeof document !== "undefined") {
       const el = document.createElement("canvas");
-      el.width = physWidth;
-      el.height = physHeight;
+      el.width = w;
+      el.height = h;
       this.gridCacheCanvas = el;
     } else {
       this.gridCacheCanvas = null;
@@ -4946,14 +4944,14 @@ var RenderLoop = class {
     const dpr = typeof devicePixelRatio !== "undefined" ? devicePixelRatio : 1;
     const cssWidth = this.canvasEl.clientWidth;
     const cssHeight = this.canvasEl.clientHeight;
+    this.marginViewport.setViewport(cssWidth, cssHeight, dpr);
     const currentZoom = this.camera.zoom;
     const currentCamX = this.camera.position.x;
     const currentCamY = this.camera.position.y;
-    if (currentZoom !== this.lastZoom || currentCamX !== this.lastCamX || currentCamY !== this.lastCamY) {
+    if (this.marginViewport.needsRecenter(currentCamX, currentCamY, currentZoom)) {
+      this.marginViewport.recenter(currentCamX, currentCamY, currentZoom);
       this.layerCache.markAllDirty();
-      this.lastZoom = currentZoom;
-      this.lastCamX = currentCamX;
-      this.lastCamY = currentCamY;
+      this.gridCacheDirty = true;
     }
     ctx.save();
     ctx.scale(dpr, dpr);
@@ -4972,13 +4970,13 @@ var RenderLoop = class {
     ctx.save();
     ctx.translate(this.camera.position.x, this.camera.position.y);
     ctx.scale(this.camera.zoom, this.camera.zoom);
-    const visibleRect = this.camera.getVisibleRect(cssWidth, cssHeight);
-    const margin = Math.max(visibleRect.w, visibleRect.h) * 0.1;
+    const cullBounds = this.marginViewport.cachedWorldBounds();
+    const cullPad = Math.max(cullBounds.w, cullBounds.h) * 0.05;
     const cullingRect = {
-      x: visibleRect.x - margin,
-      y: visibleRect.y - margin,
-      w: visibleRect.w + margin * 2,
-      h: visibleRect.h + margin * 2
+      x: cullBounds.x - cullPad,
+      y: cullBounds.y - cullPad,
+      w: cullBounds.w + cullPad * 2,
+      h: cullBounds.h + cullPad * 2
     };
     const allElements = this.store.getAll();
     this.layerGroups.clear();
@@ -5015,13 +5013,13 @@ var RenderLoop = class {
       const isActiveDrawingLayer = layerId === this.activeDrawingLayerId;
       if (!this.layerCache.isDirty(layerId)) {
         const compT0 = performance.now();
-        this.compositeLayerCache(ctx, layerId, dpr);
+        this.compositeLayerCache(ctx, layerId);
         compositeMs += performance.now() - compT0;
         continue;
       }
       if (isActiveDrawingLayer) {
         const compT0 = performance.now();
-        this.compositeLayerCache(ctx, layerId, dpr);
+        this.compositeLayerCache(ctx, layerId);
         compositeMs += performance.now() - compT0;
         continue;
       }
@@ -5031,9 +5029,7 @@ var RenderLoop = class {
         const offCanvas = this.layerCache.getCanvas(layerId);
         offCtx.clearRect(0, 0, offCanvas.width, offCanvas.height);
         offCtx.save();
-        offCtx.scale(dpr, dpr);
-        offCtx.translate(this.camera.position.x, this.camera.position.y);
-        offCtx.scale(this.camera.zoom, this.camera.zoom);
+        this.marginViewport.applyRenderTransform(offCtx);
         for (const element of elements) {
           const elBounds = getElementBounds(element);
           if (elBounds && !boundsIntersect(elBounds, cullingRect)) continue;
@@ -5043,48 +5039,54 @@ var RenderLoop = class {
         this.layerCache.markClean(layerId);
         layersMs += performance.now() - layerT0;
         const compT0 = performance.now();
-        this.compositeLayerCache(ctx, layerId, dpr);
+        this.compositeLayerCache(ctx, layerId);
         compositeMs += performance.now() - compT0;
       }
     }
     if (gridElements.length > 0) {
       const gridT0 = performance.now();
       const gridRef = gridElements[0];
-      const gridCacheHit = this.gridCacheCanvas !== null && currentZoom === this.gridCacheZoom && currentCamX === this.gridCacheCamX && currentCamY === this.gridCacheCamY && cssWidth === this.gridCacheWidth && cssHeight === this.gridCacheHeight && gridRef === this.lastGridRef;
-      if (gridCacheHit) {
-        ctx.save();
-        ctx.setTransform(1, 0, 0, 1, 0, 0);
-        ctx.drawImage(this.gridCacheCanvas, 0, 0);
-        ctx.restore();
-      } else {
-        this.ensureGridCache(cssWidth, cssHeight, dpr);
+      const gridDirty = this.gridCacheDirty || gridRef !== this.lastGridRef;
+      if (gridDirty) {
+        this.ensureGridCache();
         if (this.gridCacheCtx && this.gridCacheCanvas) {
+          const cb = this.marginViewport.cachedWorldBounds();
+          this.renderer.setGridBoundsOverride({
+            minX: cb.x,
+            minY: cb.y,
+            maxX: cb.x + cb.w,
+            maxY: cb.y + cb.h
+          });
           const gc = this.gridCacheCtx;
           gc.clearRect(0, 0, this.gridCacheCanvas.width, this.gridCacheCanvas.height);
           gc.save();
-          gc.scale(dpr, dpr);
-          gc.translate(currentCamX, currentCamY);
-          gc.scale(currentZoom, currentZoom);
-          for (const grid of gridElements) {
-            this.renderer.renderCanvasElement(gc, grid);
-          }
-          gc.restore();
-          ctx.save();
-          ctx.setTransform(1, 0, 0, 1, 0, 0);
-          ctx.drawImage(this.gridCacheCanvas, 0, 0);
-          ctx.restore();
-        } else {
-          for (const grid of gridElements) {
-            this.renderer.renderCanvasElement(ctx, grid);
+          this.marginViewport.applyRenderTransform(gc);
+          try {
+            for (const grid of gridElements) {
+              this.renderer.renderCanvasElement(gc, grid);
+            }
+          } finally {
+            gc.restore();
+            this.renderer.setGridBoundsOverride(null);
           }
         }
-        this.gridCacheZoom = currentZoom;
-        this.gridCacheCamX = currentCamX;
-        this.gridCacheCamY = currentCamY;
-        this.gridCacheWidth = cssWidth;
-        this.gridCacheHeight = cssHeight;
+        this.gridCacheDirty = false;
         this.lastGridRef = gridRef;
       }
+      if (this.gridCacheCanvas) {
+        const offset = this.marginViewport.compositeOffset(
+          this.camera.position.x,
+          this.camera.position.y
+        );
+        ctx.save();
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        ctx.drawImage(this.gridCacheCanvas, offset.x, offset.y);
+        ctx.restore();
+      } else {
+        for (const grid of gridElements) {
+          this.renderer.renderCanvasElement(ctx, grid);
+        }
+      }
       gridMs = performance.now() - gridT0;
     }
     const overlayT0 = performance.now();
@@ -5116,15 +5118,11 @@ function createOffscreenCanvas(width, height) {
   return canvas;
 }
 var LayerCache = class {
+  constructor(viewport) {
+    this.viewport = viewport;
+  }
   canvases = /* @__PURE__ */ new Map();
   dirtyFlags = /* @__PURE__ */ new Map();
-  width;
-  height;
-  constructor(width, height) {
-    const dpr = typeof devicePixelRatio !== "undefined" ? devicePixelRatio : 1;
-    this.width = Math.round(width * dpr);
-    this.height = Math.round(height * dpr);
-  }
   isDirty(layerId) {
     return this.dirtyFlags.get(layerId) !== false;
   }
@@ -5142,7 +5140,7 @@ var LayerCache = class {
   getCanvas(layerId) {
     let canvas = this.canvases.get(layerId);
     if (!canvas) {
-      canvas = createOffscreenCanvas(this.width, this.height);
+      canvas = createOffscreenCanvas(this.viewport.physicalWidth(), this.viewport.physicalHeight());
       this.canvases.set(layerId, canvas);
       this.dirtyFlags.set(layerId, true);
     }
@@ -5152,13 +5150,12 @@ var LayerCache = class {
     const canvas = this.getCanvas(layerId);
     return canvas.getContext("2d");
   }
-  resize(width, height) {
-    const dpr = typeof devicePixelRatio !== "undefined" ? devicePixelRatio : 1;
-    this.width = Math.round(width * dpr);
-    this.height = Math.round(height * dpr);
+  resize() {
+    const w = this.viewport.physicalWidth();
+    const h = this.viewport.physicalHeight();
     for (const [id, canvas] of this.canvases) {
-      canvas.width = this.width;
-      canvas.height = this.height;
+      canvas.width = w;
+      canvas.height = h;
       this.dirtyFlags.set(id, true);
     }
   }
@@ -5168,6 +5165,75 @@ var LayerCache = class {
   }
 };
 
+// src/canvas/margin-viewport.ts
+var MarginViewport = class {
+  constructor(marginPx) {
+    this.marginPx = marginPx;
+  }
+  cssW = 0;
+  cssH = 0;
+  dpr = 1;
+  anchorCamX = 0;
+  anchorCamY = 0;
+  anchorZoom = Number.NaN;
+  // sentinel → first needsRecenter is true
+  viewportDirty = true;
+  setMargin(marginPx) {
+    if (marginPx !== this.marginPx) {
+      this.marginPx = marginPx;
+      this.viewportDirty = true;
+    }
+  }
+  setViewport(cssW, cssH, dpr) {
+    if (cssW !== this.cssW || cssH !== this.cssH || dpr !== this.dpr) {
+      this.cssW = cssW;
+      this.cssH = cssH;
+      this.dpr = dpr;
+      this.viewportDirty = true;
+    }
+  }
+  physicalWidth() {
+    return Math.round((this.cssW + 2 * this.marginPx) * this.dpr);
+  }
+  physicalHeight() {
+    return Math.round((this.cssH + 2 * this.marginPx) * this.dpr);
+  }
+  needsRecenter(camX, camY, zoom) {
+    return this.viewportDirty || zoom !== this.anchorZoom || Math.abs(camX - this.anchorCamX) > this.marginPx || Math.abs(camY - this.anchorCamY) > this.marginPx;
+  }
+  recenter(camX, camY, zoom) {
+    this.anchorCamX = camX;
+    this.anchorCamY = camY;
+    this.anchorZoom = zoom;
+    this.viewportDirty = false;
+  }
+  /** Applies dpr scale + anchor-relative world transform. setViewport must have been called first. */
+  applyRenderTransform(ctx) {
+    ctx.scale(this.dpr, this.dpr);
+    ctx.translate(this.marginPx + this.anchorCamX, this.marginPx + this.anchorCamY);
+    ctx.scale(this.anchorZoom, this.anchorZoom);
+  }
+  // Device-px destination for drawImage(cache, x, y).
+  // A world point P sits in the cache at CSS x `margin + anchorCamX + P*zoom`; it must land on
+  // screen at `camX + P*zoom`; so the blit offset is `camX - anchorCamX - margin` (CSS) * dpr.
+  compositeOffset(camX, camY) {
+    return {
+      x: (camX - this.anchorCamX - this.marginPx) * this.dpr,
+      y: (camY - this.anchorCamY - this.marginPx) * this.dpr
+    };
+  }
+  // World-space bounds of the whole cached region at the anchor (cull rect for re-renders).
+  cachedWorldBounds() {
+    const z = this.anchorZoom;
+    return {
+      x: (-this.marginPx - this.anchorCamX) / z,
+      y: (-this.marginPx - this.anchorCamY) / z,
+      w: (this.cssW + 2 * this.marginPx) / z,
+      h: (this.cssH + 2 * this.marginPx) / z
+    };
+  }
+};
+
 // src/canvas/viewport.ts
 var Viewport = class {
   constructor(container, options = {}) {
@@ -5244,10 +5310,13 @@ var Viewport = class {
     this.interactMode = new InteractMode({
       getNode: (id) => this.domNodeManager.getNode(id)
     });
-    const layerCache = new LayerCache(
+    this.marginViewport = new MarginViewport(options.panBufferMargin ?? 256);
+    this.marginViewport.setViewport(
       this.canvasEl.clientWidth || 800,
-      this.canvasEl.clientHeight || 600
+      this.canvasEl.clientHeight || 600,
+      typeof devicePixelRatio !== "undefined" ? devicePixelRatio : 1
     );
+    const layerCache = new LayerCache(this.marginViewport);
     this.renderLoop = new RenderLoop({
       canvasEl: this.canvasEl,
       camera: this.camera,
@@ -5257,7 +5326,8 @@ var Viewport = class {
       toolManager: this.toolManager,
       layerManager: this.layerManager,
       domNodeManager: this.domNodeManager,
-      layerCache
+      layerCache,
+      marginViewport: this.marginViewport
     });
     this.unsubCamera = this.camera.onChange(() => {
       this.applyCameraTransform();
@@ -5321,6 +5391,7 @@ var Viewport = class {
   noteEditor;
   historyRecorder;
   toolContext;
+  marginViewport;
   resizeObserver = null;
   _snapToGrid = false;
   _gridSize;
@@ -7511,7 +7582,7 @@ var TemplateTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.22.0";
+var VERSION = "0.23.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AddElementCommand,