@fieldnotes/core 0.21.0 → 0.23.0

package/dist/index.cjs

@@ -1933,10 +1933,134 @@ function getTemplateBounds(el) {
     }
   }
 }
+function transferStrokeBounds(prev, next) {
+  if (prev.type !== "stroke" || next.type !== "stroke") return;
+  if (prev.points !== next.points) return;
+  if (prev.position.x !== next.position.x || prev.position.y !== next.position.y) return;
+  const bounds = strokeBoundsCache.get(prev);
+  if (bounds) strokeBoundsCache.set(next, bounds);
+}
 function boundsIntersect(a, b) {
   return a.x <= b.x + b.w && a.x + a.w >= b.x && a.y <= b.y + b.h && a.y + a.h >= b.y;
 }
 
+// src/elements/stroke-smoothing.ts
+var MIN_PRESSURE_SCALE = 0.2;
+function pressureToWidth(pressure, baseWidth) {
+  return baseWidth * (MIN_PRESSURE_SCALE + (1 - MIN_PRESSURE_SCALE) * pressure);
+}
+function simplifyPoints(points, tolerance) {
+  if (points.length <= 2) return points.slice();
+  return rdp(points, 0, points.length - 1, tolerance);
+}
+function rdp(points, start, end, tolerance) {
+  const first = points[start];
+  const last = points[end];
+  if (!first || !last) return [];
+  if (end - start <= 1) return [first, last];
+  let maxDist = 0;
+  let maxIndex = start;
+  for (let i = start + 1; i < end; i++) {
+    const pt = points[i];
+    if (!pt) continue;
+    const dist = perpendicularDistance(pt, first, last);
+    if (dist > maxDist) {
+      maxDist = dist;
+      maxIndex = i;
+    }
+  }
+  if (maxDist <= tolerance) return [first, last];
+  const left = rdp(points, start, maxIndex, tolerance);
+  const right = rdp(points, maxIndex, end, tolerance);
+  return left.concat(right.slice(1));
+}
+function perpendicularDistance(pt, lineStart, lineEnd) {
+  const dx = lineEnd.x - lineStart.x;
+  const dy = lineEnd.y - lineStart.y;
+  const lenSq = dx * dx + dy * dy;
+  if (lenSq === 0) {
+    const ex = pt.x - lineStart.x;
+    const ey = pt.y - lineStart.y;
+    return Math.sqrt(ex * ex + ey * ey);
+  }
+  const num = Math.abs(dy * pt.x - dx * pt.y + lineEnd.x * lineStart.y - lineEnd.y * lineStart.x);
+  return num / Math.sqrt(lenSq);
+}
+function smoothToSegments(points) {
+  if (points.length < 2) return [];
+  if (points.length === 2) {
+    const p0 = points[0];
+    const p1 = points[1];
+    if (!p0 || !p1) return [];
+    const mx = (p0.x + p1.x) / 2;
+    const my = (p0.y + p1.y) / 2;
+    return [{ start: p0, cp1: { x: mx, y: my }, cp2: { x: mx, y: my }, end: p1 }];
+  }
+  const segments = [];
+  const n = points.length;
+  for (let i = 0; i < n - 1; i++) {
+    const p0 = points[Math.max(0, i - 1)];
+    const p1 = points[i];
+    const p2 = points[i + 1];
+    const p3 = points[Math.min(n - 1, i + 2)];
+    if (!p0 || !p1 || !p2 || !p3) continue;
+    const cp1 = {
+      x: p1.x + (p2.x - p0.x) / 6,
+      y: p1.y + (p2.y - p0.y) / 6
+    };
+    const cp2 = {
+      x: p2.x - (p3.x - p1.x) / 6,
+      y: p2.y - (p3.y - p1.y) / 6
+    };
+    segments.push({ start: p1, cp1, cp2, end: p2 });
+  }
+  return segments;
+}
+
+// src/elements/stroke-cache.ts
+var cache = /* @__PURE__ */ new WeakMap();
+var WIDTH_QUANTUM = 0.25;
+function buildWidthBuckets(segments, widths) {
+  if (typeof Path2D === "undefined") return null;
+  const byWidth = /* @__PURE__ */ new Map();
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    const w = widths[i];
+    if (!seg || w === void 0) continue;
+    const q = Math.max(WIDTH_QUANTUM, Math.round(w / WIDTH_QUANTUM) * WIDTH_QUANTUM);
+    let path = byWidth.get(q);
+    if (!path) {
+      path = new Path2D();
+      byWidth.set(q, path);
+    }
+    path.moveTo(seg.start.x, seg.start.y);
+    path.bezierCurveTo(seg.cp1.x, seg.cp1.y, seg.cp2.x, seg.cp2.y, seg.end.x, seg.end.y);
+  }
+  return [...byWidth.entries()].map(([width, path]) => ({ width, path }));
+}
+function computeStrokeSegments(stroke) {
+  const segments = smoothToSegments(stroke.points);
+  const widths = [];
+  for (const seg of segments) {
+    const w = (pressureToWidth(seg.start.pressure, stroke.width) + pressureToWidth(seg.end.pressure, stroke.width)) / 2;
+    widths.push(w);
+  }
+  const data = { segments, widths, buckets: buildWidthBuckets(segments, widths) };
+  cache.set(stroke, data);
+  return data;
+}
+function getStrokeRenderData(stroke) {
+  const cached = cache.get(stroke);
+  if (cached) return cached;
+  return computeStrokeSegments(stroke);
+}
+function transferStrokeRenderData(prev, next) {
+  if (prev.type !== "stroke" || next.type !== "stroke") return;
+  if (prev.points !== next.points) return;
+  const data = cache.get(prev);
+  if (data) cache.set(next, data);
+}
+
 // src/elements/element-store.ts
 var ElementStore = class {
   elements = /* @__PURE__ */ new Map();
@@ -1987,6 +2111,10 @@ var ElementStore = class {
     this.sortedCache = null;
     this._versions.set(id, (this._versions.get(id) ?? 0) + 1);
     const updated = { ...existing, ...partial, id: existing.id, type: existing.type };
+    if (updated.type === "stroke" && existing.type === "stroke") {
+      transferStrokeRenderData(existing, updated);
+      transferStrokeBounds(existing, updated);
+    }
     if (updated.type === "arrow") {
       const arrow = updated;
       arrow.cachedControlPoint = getArrowControlPoint(arrow.from, arrow.to, arrow.bend);
@@ -2030,6 +2158,12 @@ var ElementStore = class {
       this._versions.set(el.id, 0);
       const bounds = getElementBounds(el);
       if (bounds) this.spatialIndex.insert(el.id, bounds);
+      if (el.type === "stroke") {
+        computeStrokeSegments(el);
+      }
+      if (el.type === "arrow" && el.bend !== 0 && !el.cachedControlPoint) {
+        el.cachedControlPoint = getArrowControlPoint(el.from, el.to, el.bend);
+      }
     }
     this.bus.emit("clear", null);
     for (const el of elements) {
@@ -2115,6 +2249,20 @@ var ElementStore = class {
   }
 };
 
+// src/elements/arrow-render-cache.ts
+var cache2 = /* @__PURE__ */ new WeakMap();
+function getArrowRenderGeometry(arrow) {
+  const hit = cache2.get(arrow);
+  if (hit) return hit;
+  const geometry = {
+    controlPoint: arrow.bend !== 0 ? arrow.cachedControlPoint ?? getArrowControlPoint(arrow.from, arrow.to, arrow.bend) : null,
+    tangentStart: getArrowTangentAngle(arrow.from, arrow.to, arrow.bend, 0),
+    tangentEnd: getArrowTangentAngle(arrow.from, arrow.to, arrow.bend, 1)
+  };
+  cache2.set(arrow, geometry);
+  return geometry;
+}
+
 // src/elements/arrow-binding.ts
 var BINDABLE_TYPES = /* @__PURE__ */ new Set(["note", "text", "image", "html", "shape"]);
 function isBindable(element) {
@@ -2235,98 +2383,6 @@ function unbindArrow(arrow, store) {
   return updates;
 }
 
-// src/elements/stroke-smoothing.ts
-var MIN_PRESSURE_SCALE = 0.2;
-function pressureToWidth(pressure, baseWidth) {
-  return baseWidth * (MIN_PRESSURE_SCALE + (1 - MIN_PRESSURE_SCALE) * pressure);
-}
-function simplifyPoints(points, tolerance) {
-  if (points.length <= 2) return points.slice();
-  return rdp(points, 0, points.length - 1, tolerance);
-}
-function rdp(points, start, end, tolerance) {
-  const first = points[start];
-  const last = points[end];
-  if (!first || !last) return [];
-  if (end - start <= 1) return [first, last];
-  let maxDist = 0;
-  let maxIndex = start;
-  for (let i = start + 1; i < end; i++) {
-    const pt = points[i];
-    if (!pt) continue;
-    const dist = perpendicularDistance(pt, first, last);
-    if (dist > maxDist) {
-      maxDist = dist;
-      maxIndex = i;
-    }
-  }
-  if (maxDist <= tolerance) return [first, last];
-  const left = rdp(points, start, maxIndex, tolerance);
-  const right = rdp(points, maxIndex, end, tolerance);
-  return left.concat(right.slice(1));
-}
-function perpendicularDistance(pt, lineStart, lineEnd) {
-  const dx = lineEnd.x - lineStart.x;
-  const dy = lineEnd.y - lineStart.y;
-  const lenSq = dx * dx + dy * dy;
-  if (lenSq === 0) {
-    const ex = pt.x - lineStart.x;
-    const ey = pt.y - lineStart.y;
-    return Math.sqrt(ex * ex + ey * ey);
-  }
-  const num = Math.abs(dy * pt.x - dx * pt.y + lineEnd.x * lineStart.y - lineEnd.y * lineStart.x);
-  return num / Math.sqrt(lenSq);
-}
-function smoothToSegments(points) {
-  if (points.length < 2) return [];
-  if (points.length === 2) {
-    const p0 = points[0];
-    const p1 = points[1];
-    if (!p0 || !p1) return [];
-    const mx = (p0.x + p1.x) / 2;
-    const my = (p0.y + p1.y) / 2;
-    return [{ start: p0, cp1: { x: mx, y: my }, cp2: { x: mx, y: my }, end: p1 }];
-  }
-  const segments = [];
-  const n = points.length;
-  for (let i = 0; i < n - 1; i++) {
-    const p0 = points[Math.max(0, i - 1)];
-    const p1 = points[i];
-    const p2 = points[i + 1];
-    const p3 = points[Math.min(n - 1, i + 2)];
-    if (!p0 || !p1 || !p2 || !p3) continue;
-    const cp1 = {
-      x: p1.x + (p2.x - p0.x) / 6,
-      y: p1.y + (p2.y - p0.y) / 6
-    };
-    const cp2 = {
-      x: p2.x - (p3.x - p1.x) / 6,
-      y: p2.y - (p3.y - p1.y) / 6
-    };
-    segments.push({ start: p1, cp1, cp2, end: p2 });
-  }
-  return segments;
-}
-
-// src/elements/stroke-cache.ts
-var cache = /* @__PURE__ */ new WeakMap();
-function computeStrokeSegments(stroke) {
-  const segments = smoothToSegments(stroke.points);
-  const widths = [];
-  for (const seg of segments) {
-    const w = (pressureToWidth(seg.start.pressure, stroke.width) + pressureToWidth(seg.end.pressure, stroke.width)) / 2;
-    widths.push(w);
-  }
-  const data = { segments, widths };
-  cache.set(stroke, data);
-  return data;
-}
-function getStrokeRenderData(stroke) {
-  const cached = cache.get(stroke);
-  if (cached) return cached;
-  return computeStrokeSegments(stroke);
-}
-
 // src/elements/grid-renderer.ts
 function getSquareGridLines(bounds, cellSize) {
   if (cellSize <= 0) return { verticals: [], horizontals: [] };
@@ -2724,6 +2780,7 @@ var ElementRenderer = class {
   canvasSize = null;
   hexTileCache = null;
   hexTileCacheKey = "";
+  gridBoundsOverride = null;
   setStore(store) {
     this.store = store;
   }
@@ -2739,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);
   }
@@ -2772,21 +2832,29 @@ var ElementRenderer = class {
     ctx.lineCap = "round";
     ctx.lineJoin = "round";
     ctx.globalAlpha = stroke.opacity;
-    const { segments, widths } = getStrokeRenderData(stroke);
-    for (let i = 0; i < segments.length; i++) {
-      const seg = segments[i];
-      const w = widths[i];
-      if (!seg || w === void 0) continue;
-      ctx.lineWidth = w;
-      ctx.beginPath();
-      ctx.moveTo(seg.start.x, seg.start.y);
-      ctx.bezierCurveTo(seg.cp1.x, seg.cp1.y, seg.cp2.x, seg.cp2.y, seg.end.x, seg.end.y);
-      ctx.stroke();
+    const data = getStrokeRenderData(stroke);
+    if (data.buckets) {
+      for (const bucket of data.buckets) {
+        ctx.lineWidth = bucket.width;
+        ctx.stroke(bucket.path);
+      }
+    } else {
+      for (let i = 0; i < data.segments.length; i++) {
+        const seg = data.segments[i];
+        const w = data.widths[i];
+        if (!seg || w === void 0) continue;
+        ctx.lineWidth = w;
+        ctx.beginPath();
+        ctx.moveTo(seg.start.x, seg.start.y);
+        ctx.bezierCurveTo(seg.cp1.x, seg.cp1.y, seg.cp2.x, seg.cp2.y, seg.end.x, seg.end.y);
+        ctx.stroke();
+      }
     }
     ctx.restore();
   }
   renderArrow(ctx, arrow) {
-    const { visualFrom, visualTo } = this.getVisualEndpoints(arrow);
+    const geometry = getArrowRenderGeometry(arrow);
+    const { visualFrom, visualTo } = this.getVisualEndpoints(arrow, geometry);
     ctx.save();
     ctx.strokeStyle = arrow.color;
     ctx.lineWidth = arrow.width;
@@ -2797,17 +2865,18 @@ var ElementRenderer = class {
     ctx.beginPath();
     ctx.moveTo(visualFrom.x, visualFrom.y);
     if (arrow.bend !== 0) {
-      const cp = arrow.cachedControlPoint ?? getArrowControlPoint(arrow.from, arrow.to, arrow.bend);
-      ctx.quadraticCurveTo(cp.x, cp.y, visualTo.x, visualTo.y);
+      const cp = geometry.controlPoint;
+      if (cp) {
+        ctx.quadraticCurveTo(cp.x, cp.y, visualTo.x, visualTo.y);
+      }
     } else {
       ctx.lineTo(visualTo.x, visualTo.y);
     }
     ctx.stroke();
-    this.renderArrowhead(ctx, arrow, visualTo);
+    this.renderArrowhead(ctx, arrow, visualTo, geometry.tangentEnd);
     ctx.restore();
   }
-  renderArrowhead(ctx, arrow, tip) {
-    const angle = getArrowTangentAngle(arrow.from, arrow.to, arrow.bend, 1);
+  renderArrowhead(ctx, arrow, tip, angle) {
     ctx.beginPath();
     ctx.moveTo(tip.x, tip.y);
     ctx.lineTo(
@@ -2822,7 +2891,7 @@ var ElementRenderer = class {
     ctx.fillStyle = arrow.color;
     ctx.fill();
   }
-  getVisualEndpoints(arrow) {
+  getVisualEndpoints(arrow, geometry) {
     let visualFrom = arrow.from;
     let visualTo = arrow.to;
     if (!this.store) return { visualFrom, visualTo };
@@ -2831,7 +2900,7 @@ var ElementRenderer = class {
       if (el) {
         const bounds = getElementBounds(el);
         if (bounds) {
-          const tangentAngle = getArrowTangentAngle(arrow.from, arrow.to, arrow.bend, 0);
+          const tangentAngle = geometry.tangentStart;
           const rayTarget = {
             x: arrow.from.x + Math.cos(tangentAngle) * 1e3,
             y: arrow.from.y + Math.sin(tangentAngle) * 1e3
@@ -2845,7 +2914,7 @@ var ElementRenderer = class {
       if (el) {
         const bounds = getElementBounds(el);
         if (bounds) {
-          const tangentAngle = getArrowTangentAngle(arrow.from, arrow.to, arrow.bend, 1);
+          const tangentAngle = geometry.tangentEnd;
           const rayTarget = {
             x: arrow.to.x - Math.cos(tangentAngle) * 1e3,
             y: arrow.to.y - Math.sin(tangentAngle) * 1e3
@@ -2900,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;
@@ -4209,19 +4278,19 @@ function loadImages(elements) {
   const imageElements = elements.filter(
     (el) => el.type === "image" && "src" in el
   );
-  const cache2 = /* @__PURE__ */ new Map();
-  if (imageElements.length === 0) return Promise.resolve(cache2);
+  const cache3 = /* @__PURE__ */ new Map();
+  if (imageElements.length === 0) return Promise.resolve(cache3);
   return new Promise((resolve) => {
     let remaining = imageElements.length;
     const done = () => {
       remaining--;
-      if (remaining <= 0) resolve(cache2);
+      if (remaining <= 0) resolve(cache3);
     };
     for (const el of imageElements) {
       const img = new Image();
       img.crossOrigin = "anonymous";
       img.onload = () => {
-        cache2.set(el.id, img);
+        cache3.set(el.id, img);
         done();
       };
       img.onerror = done;
@@ -4702,18 +4771,39 @@ var RenderStats = class {
   frameTimes = [];
   frameCount = 0;
   _lastGridMs = 0;
-  recordFrame(durationMs, gridMs) {
+  _lastLayersMs = 0;
+  _lastBackgroundMs = 0;
+  _lastCompositeMs = 0;
+  _lastOverlayMs = 0;
+  recordFrame(durationMs, breakdown) {
     this.frameCount++;
     this.frameTimes.push(durationMs);
     if (this.frameTimes.length > SAMPLE_SIZE) {
       this.frameTimes.shift();
     }
-    if (gridMs !== void 0) this._lastGridMs = gridMs;
+    if (breakdown !== void 0) {
+      if (breakdown.gridMs !== void 0) this._lastGridMs = breakdown.gridMs;
+      if (breakdown.layersMs !== void 0) this._lastLayersMs = breakdown.layersMs;
+      if (breakdown.backgroundMs !== void 0) this._lastBackgroundMs = breakdown.backgroundMs;
+      if (breakdown.compositeMs !== void 0) this._lastCompositeMs = breakdown.compositeMs;
+      if (breakdown.overlayMs !== void 0) this._lastOverlayMs = breakdown.overlayMs;
+    }
   }
   getSnapshot() {
     const times = this.frameTimes;
     if (times.length === 0) {
-      return { fps: 0, avgFrameMs: 0, p95FrameMs: 0, lastFrameMs: 0, lastGridMs: 0, frameCount: 0 };
+      return {
+        fps: 0,
+        avgFrameMs: 0,
+        p95FrameMs: 0,
+        lastFrameMs: 0,
+        lastGridMs: 0,
+        layersMs: 0,
+        backgroundMs: 0,
+        compositeMs: 0,
+        overlayMs: 0,
+        frameCount: 0
+      };
     }
     const avg = times.reduce((a, b) => a + b, 0) / times.length;
     const sorted = [...times].sort((a, b) => a - b);
@@ -4725,6 +4815,10 @@ var RenderStats = class {
       p95FrameMs: Math.round((sorted[p95Index] ?? 0) * 100) / 100,
       lastFrameMs: Math.round(lastFrame * 100) / 100,
       lastGridMs: Math.round(this._lastGridMs * 100) / 100,
+      layersMs: Math.round(this._lastLayersMs * 100) / 100,
+      backgroundMs: Math.round(this._lastBackgroundMs * 100) / 100,
+      compositeMs: Math.round(this._lastCompositeMs * 100) / 100,
+      overlayMs: Math.round(this._lastOverlayMs * 100) / 100,
       frameCount: this.frameCount
     };
   }
@@ -4747,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();
-  lastGridMs = 0;
+  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;
@@ -4771,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;
@@ -4800,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;
@@ -4814,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;
@@ -4850,22 +4938,26 @@ var RenderLoop = class {
     const t0 = performance.now();
     const ctx = this.canvasEl.getContext("2d");
     if (!ctx) return;
+    let layersMs = 0;
+    let compositeMs = 0;
+    let gridMs = 0;
     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);
     this.renderer.setCanvasSize(cssWidth, cssHeight);
     const hasGridElement = this.store.getElementsByType("grid").length > 0;
+    const bgT0 = performance.now();
     if (hasGridElement) {
       ctx.save();
       ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
@@ -4874,19 +4966,20 @@ var RenderLoop = class {
     } else {
       this.background.render(ctx, this.camera);
     }
+    const backgroundMs = performance.now() - bgT0;
     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();
-    const layerElements = /* @__PURE__ */ new Map();
+    this.layerGroups.clear();
     const gridElements = [];
     let domZIndex = 0;
     for (const element of allElements) {
@@ -4909,31 +5002,34 @@ var RenderLoop = class {
         gridElements.push(element);
         continue;
       }
-      let group = layerElements.get(element.layerId);
+      let group = this.layerGroups.get(element.layerId);
       if (!group) {
         group = [];
-        layerElements.set(element.layerId, group);
+        this.layerGroups.set(element.layerId, group);
       }
       group.push(element);
     }
-    for (const [layerId, elements] of layerElements) {
+    for (const [layerId, elements] of this.layerGroups) {
       const isActiveDrawingLayer = layerId === this.activeDrawingLayerId;
       if (!this.layerCache.isDirty(layerId)) {
-        this.compositeLayerCache(ctx, layerId, dpr);
+        const compT0 = performance.now();
+        this.compositeLayerCache(ctx, layerId);
+        compositeMs += performance.now() - compT0;
         continue;
       }
       if (isActiveDrawingLayer) {
-        this.compositeLayerCache(ctx, layerId, dpr);
+        const compT0 = performance.now();
+        this.compositeLayerCache(ctx, layerId);
+        compositeMs += performance.now() - compT0;
         continue;
       }
       const offCtx = this.layerCache.getContext(layerId);
       if (offCtx) {
+        const layerT0 = performance.now();
         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;
@@ -4941,56 +5037,73 @@ var RenderLoop = class {
         }
         offCtx.restore();
         this.layerCache.markClean(layerId);
-        this.compositeLayerCache(ctx, layerId, dpr);
+        layersMs += performance.now() - layerT0;
+        const compT0 = performance.now();
+        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;
       }
-      this.lastGridMs = performance.now() - gridT0;
+      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();
     const activeTool = this.toolManager.activeTool;
     if (activeTool?.renderOverlay) {
       activeTool.renderOverlay(ctx);
     }
+    const overlayMs = performance.now() - overlayT0;
     ctx.restore();
     ctx.restore();
-    this.stats.recordFrame(performance.now() - t0, this.lastGridMs);
+    this.stats.recordFrame(performance.now() - t0, {
+      gridMs,
+      layersMs,
+      backgroundMs,
+      compositeMs,
+      overlayMs
+    });
   }
 };
 
@@ -5005,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;
   }
@@ -5031,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);
     }
@@ -5041,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);
     }
   }
@@ -5057,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 = {}) {
@@ -5133,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,
@@ -5146,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();
@@ -5210,6 +5391,7 @@ var Viewport = class {
   noteEditor;
   historyRecorder;
   toolContext;
+  marginViewport;
   resizeObserver = null;
   _snapToGrid = false;
   _gridSize;
@@ -5402,7 +5584,7 @@ var Viewport = class {
     const id = setInterval(() => {
       const s = this.getRenderStats();
       console.log(
-        `[FieldNotes] fps=${s.fps} frame=${s.avgFrameMs}ms p95=${s.p95FrameMs}ms grid=${s.lastGridMs}ms`
+        `[FieldNotes] fps=${s.fps} frame=${s.avgFrameMs}ms p95=${s.p95FrameMs}ms grid=${s.lastGridMs}ms layers=${s.layersMs}ms comp=${s.compositeMs}ms bg=${s.backgroundMs}ms overlay=${s.overlayMs}ms`
       );
     }, intervalMs);
     return () => clearInterval(id);
@@ -7400,7 +7582,7 @@ var TemplateTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.21.0";
+var VERSION = "0.23.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AddElementCommand,