@fieldnotes/core 0.22.0 → 0.23.0

package/dist/index.d.cts

@@ -603,6 +603,8 @@ interface ViewportOptions {
         src: string;
         elementIds: string[];
     }) => void;
+    /** CSS-pixel margin cached beyond the viewport. Default `256`. Set `0` to disable. */
+    panBufferMargin?: number;
 }
 declare class Viewport {
     private readonly container;
@@ -622,6 +624,7 @@ declare class Viewport {
     private readonly noteEditor;
     private readonly historyRecorder;
     readonly toolContext: ToolContext;
+    private readonly marginViewport;
     private resizeObserver;
     private _snapToGrid;
     private readonly _gridSize;
@@ -708,11 +711,18 @@ declare class ElementRenderer {
     private canvasSize;
     private hexTileCache;
     private hexTileCacheKey;
+    private gridBoundsOverride;
     setStore(store: ElementStore): void;
     setOnImageLoad(callback: () => void): void;
     setOnImageError(callback: (src: string) => void): void;
     setCamera(camera: Camera): void;
     setCanvasSize(w: number, h: number): void;
+    setGridBoundsOverride(bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    } | null): void;
     isDomElement(element: CanvasElement): boolean;
     renderCanvasElement(ctx: CanvasRenderingContext2D, element: CanvasElement): void;
     private renderStroke;
@@ -1251,6 +1261,6 @@ declare class UpdateLayerCommand implements Command {
     undo(_store: ElementStore): void;
 }
 
-declare const VERSION = "0.22.0";
+declare const VERSION = "0.23.0";
 
 export { type ActiveFormats, AddElementCommand, type ArrowElement, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, Background, type BackgroundOptions, type BackgroundPattern, BatchCommand, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, CreateLayerCommand, DEFAULT_FONT_SIZE_PRESETS, DEFAULT_NOTE_FONT_SIZE, DoubleTapDetector, type DoubleTapDetectorOptions, ElementRenderer, ElementStore, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, EventBus, type ExportImageOptions, type FilterAction, type FilteredEvent, type FilteredUpEvent, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryRecorder, HistoryStack, type HistoryStackOptions, type HtmlElement, type ImageElement, ImageTool, type ImageToolOptions, InputFilter, InputHandler, type InputHandlerOptions, type Layer, LayerManager, MeasureTool, type MeasureToolOptions, type Measurement, NoteEditor, type NoteEditorOptions, type NoteElement, NoteTool, type NoteToolOptions, NoteToolbar, PencilTool, type PencilToolOptions, type Point, type PointerState, Quadtree, RemoveElementCommand, RemoveLayerCommand, type RenderStatsSnapshot, SelectTool, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StrokeElement, type StrokePoint, type StyledRun, type TemplateElement, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, UpdateElementCommand, UpdateLayerCommand, VERSION, Viewport, type ViewportOptions, boundsIntersect, clearStaleBindings, createArrow, createGrid, createHtmlElement, createId, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportState, findBindTarget, findBoundArrows, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getEdgeIntersection, getElementBounds, getElementCenter, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInSquare, getHexDistance, isBindable, isNearBezier, isNoteContentEmpty, parseState, sanitizeNoteHtml, setFontSize, smartSnap, snapPoint, snapToHexCenter, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline, unbindArrow, updateBoundArrow };

package/dist/index.d.ts

@@ -603,6 +603,8 @@ interface ViewportOptions {
         src: string;
         elementIds: string[];
     }) => void;
+    /** CSS-pixel margin cached beyond the viewport. Default `256`. Set `0` to disable. */
+    panBufferMargin?: number;
 }
 declare class Viewport {
     private readonly container;
@@ -622,6 +624,7 @@ declare class Viewport {
     private readonly noteEditor;
     private readonly historyRecorder;
     readonly toolContext: ToolContext;
+    private readonly marginViewport;
     private resizeObserver;
     private _snapToGrid;
     private readonly _gridSize;
@@ -708,11 +711,18 @@ declare class ElementRenderer {
     private canvasSize;
     private hexTileCache;
     private hexTileCacheKey;
+    private gridBoundsOverride;
     setStore(store: ElementStore): void;
     setOnImageLoad(callback: () => void): void;
     setOnImageError(callback: (src: string) => void): void;
     setCamera(camera: Camera): void;
     setCanvasSize(w: number, h: number): void;
+    setGridBoundsOverride(bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    } | null): void;
     isDomElement(element: CanvasElement): boolean;
     renderCanvasElement(ctx: CanvasRenderingContext2D, element: CanvasElement): void;
     private renderStroke;
@@ -1251,6 +1261,6 @@ declare class UpdateLayerCommand implements Command {
     undo(_store: ElementStore): void;
 }
 
-declare const VERSION = "0.22.0";
+declare const VERSION = "0.23.0";
 
 export { type ActiveFormats, AddElementCommand, type ArrowElement, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, Background, type BackgroundOptions, type BackgroundPattern, BatchCommand, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, CreateLayerCommand, DEFAULT_FONT_SIZE_PRESETS, DEFAULT_NOTE_FONT_SIZE, DoubleTapDetector, type DoubleTapDetectorOptions, ElementRenderer, ElementStore, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, EventBus, type ExportImageOptions, type FilterAction, type FilteredEvent, type FilteredUpEvent, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryRecorder, HistoryStack, type HistoryStackOptions, type HtmlElement, type ImageElement, ImageTool, type ImageToolOptions, InputFilter, InputHandler, type InputHandlerOptions, type Layer, LayerManager, MeasureTool, type MeasureToolOptions, type Measurement, NoteEditor, type NoteEditorOptions, type NoteElement, NoteTool, type NoteToolOptions, NoteToolbar, PencilTool, type PencilToolOptions, type Point, type PointerState, Quadtree, RemoveElementCommand, RemoveLayerCommand, type RenderStatsSnapshot, SelectTool, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StrokeElement, type StrokePoint, type StyledRun, type TemplateElement, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, UpdateElementCommand, UpdateLayerCommand, VERSION, Viewport, type ViewportOptions, boundsIntersect, clearStaleBindings, createArrow, createGrid, createHtmlElement, createId, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportState, findBindTarget, findBoundArrows, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getEdgeIntersection, getElementBounds, getElementCenter, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInSquare, getHexDistance, isBindable, isNearBezier, isNoteContentEmpty, parseState, sanitizeNoteHtml, setFontSize, smartSnap, snapPoint, snapToHexCenter, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline, unbindArrow, updateBoundArrow };

package/dist/index.js

@@ -2670,6 +2670,7 @@ var ElementRenderer = class {
   canvasSize = null;
   hexTileCache = null;
   hexTileCacheKey = "";
+  gridBoundsOverride = null;
   setStore(store) {
     this.store = store;
   }
@@ -2685,6 +2686,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);
   }
@@ -2855,20 +2859,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;
@@ -4727,19 +4731,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;
@@ -4751,9 +4750,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;
@@ -4780,7 +4777,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;
@@ -4794,30 +4793,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;
@@ -4836,14 +4834,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);
@@ -4862,13 +4860,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();
@@ -4905,13 +4903,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;
       }
@@ -4921,9 +4919,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;
@@ -4933,48 +4929,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();
@@ -5006,15 +5008,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;
   }
@@ -5032,7 +5030,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);
     }
@@ -5042,13 +5040,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);
     }
   }
@@ -5058,6 +5055,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 = {}) {
@@ -5134,10 +5200,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,
@@ -5147,7 +5216,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();
@@ -5211,6 +5281,7 @@ var Viewport = class {
   noteEditor;
   historyRecorder;
   toolContext;
+  marginViewport;
   resizeObserver = null;
   _snapToGrid = false;
   _gridSize;
@@ -7401,7 +7472,7 @@ var TemplateTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.22.0";
+var VERSION = "0.23.0";
 export {
   AddElementCommand,
   ArrowTool,