@mocanvas/editor 4.13.0 → 4.15.0

package/ARCHITECTURE.md

@@ -233,9 +233,13 @@ engine.selection_bounds(ptr_handles, len) -> ptr to 4 f32
    level-of-detail quads until a later frame reaches them.
 4. Append transformed vertices into the frame vertex buffer, batching by
    texture. Shapes flagged `OVERLAY` skip the mesh and go into the overlay list.
-5. TS uploads the buffers (unless the engine reports them unchanged) and draws. Overlay list is diffed against the React
-   overlay layer, which positions DOM shapes with `transform` and passes
-   pointer events through except when editing.
+5. TS uploads the buffers (unless the engine reports them unchanged) and draws. The overlay list
+   gains the shapes that left the viewport recently (a bounded LRU,
+   `options.overlayRetainLimit`) and is diffed against the React overlay layer,
+   which positions DOM shapes with `transform`, hides the retained ones with
+   `content-visibility: hidden`, and passes pointer events through except when
+   editing. The camera is a transform on the layer, written by a signal
+   reaction: a pan or zoom frame is no React render at all.
 
 Stroke widths are in page units and scale with zoom, so meshes never need
 retessellation while zooming. Dash patterns (`dash` style word: 0 solid,

package/COMPAT.md

@@ -98,7 +98,10 @@ work is**, not in the symbol tables above.
 
 `canCull` is absent from the class but honoured where it matters: a util that
 implements it and returns `false` keeps its shape in the DOM overlay while the
-shape is off screen (4.12.4), and out of `getCulledShapes()`.
+shape is off screen (4.12.4), and out of `getCulledShapes()`. Every other overlay
+shape that leaves the viewport stays mounted but hidden until
+`options.overlayRetainLimit` newer ones displace it; the option is mocanvas's
+own.
 
 You can measure a real application against this surface rather than trusting the
 tables: `scripts/compat-parity.mjs` type-checks a consumer app with `tldraw`

package/CUSTOM_SHAPES.md

@@ -197,6 +197,40 @@ geometry bounds, with `pointerEvents: "none"` unless the shape is being edited.
 Render in shape-local space starting at `(0, 0)`; do not apply the camera or
 the shape transform yourself.
 
+**When it re-renders.** The body is a function of the shape's `props` and
+`meta`: it re-renders when either changes, and when a signal it read during its
+last render changes (`useValue`, `editor.get*`). Moving, rotating or fading the
+shape changes only the wrapper's transform and opacity, so a body that reads
+`shape.x`, `shape.y`, `shape.rotation` or `shape.opacity` sees the value from its
+last render. Read the position through a signal if you need it.
+A pan or zoom re-renders nothing: the camera is a transform on the overlay layer.
+
+**Off screen.** A body is mounted while its shape is on screen. When the shape
+leaves the viewport it stays mounted, hidden with `content-visibility: hidden`,
+until `options.overlayRetainLimit` (default 256) more recently culled shapes
+push it out; coming back on screen then costs a style change, not a remount.
+`0` unmounts at the viewport edge. A util whose `canCull()` returns `false` is
+never unmounted and never hidden for being off screen.
+
+**The zoom in your CSS.** `--mocanvas-zoom` and `--mocanvas-scale` are live on
+the canvas container, but the overlay declares them as constants so that a zoom
+does not restyle every node of every mounted shape — the single largest cost of
+a zoom gesture on a board of DOM cards. A shape whose own CSS reads them says so:
+
+```ts
+class CardUtil extends BaseBoxShapeUtil<CardShape> {
+  override usesCameraCssVars() {
+    return true // this card counter-scales its label
+  }
+}
+```
+
+That shape then gets the live values on its own wrapper, and its subtree is the
+only one that restyles on a zoom. `options.overlayCameraCssVars: "inherit"`
+turns the mechanism off altogether, for an app that would rather pay than name
+its shapes. Everything outside the overlay — your own chrome, panels, menus —
+reads the live values as before.
+
 ### `getIndicatorPath` — the selection outline
 
 ```ts

package/MIGRATION.md

@@ -273,7 +273,7 @@ it. Two groups are worth knowing about:
 
 | tldraw token | What you get |
 | --- | --- |
-| `--tl-zoom`, `--tl-scale` | Real values. mocanvas now stamps `--mocanvas-zoom` and `--mocanvas-scale` on the canvas container and restamps them on zoom, so `calc()` rules that hold a constant on-screen size keep working. |
+| `--tl-zoom`, `--tl-scale` | Real values. mocanvas stamps `--mocanvas-zoom` and `--mocanvas-scale` on the canvas container and restamps them on zoom, so `calc()` rules that hold a constant on-screen size keep working. Inside the DOM overlay they are constants unless the shape's util says `usesCameraCssVars()` — a tldraw shape whose CSS counter-scales with `--tl-scale` needs that line, or `options.overlayCameraCssVars: "inherit"`. |
 | `--tl-color-overlay`, `--tl-color-background-overlay`, `--tl-color-warn` | A static fallback. mocanvas has no equivalent, so these do not follow your theme — set them yourself if they matter. |
 
 Everything else maps onto a themed mocanvas variable and follows a theme swap

package/dist/index.d.ts

@@ -3483,6 +3483,19 @@ declare abstract class ShapeUtil<T extends UnknownShape = UnknownShape, D extend
     getRenderStyle(_shape: T): StyleWords | null;
     /** Whether the shape should be drawn by the DOM overlay even if it has a render style (e.g. while editing). */
     needsOverlay(shape: T): boolean;
+    /**
+     * Whether this shape's own CSS reads `--mocanvas-zoom` / `--mocanvas-scale`.
+     *
+     * The overlay stops those variables inheriting into mounted shapes, because a
+     * custom property that changes on every zoom frame restyles every node below
+     * it — the cost of a zoom on a board of DOM cards. A shape that says `true`
+     * here gets the live values on its own wrapper, and pays that restyle for
+     * itself: the counter-scaled label, the hairline that must stay 1px.
+     *
+     * Default `false`. `options.overlayCameraCssVars: "inherit"` turns the whole
+     * mechanism off for an app that would rather not name its shapes.
+     */
+    usesCameraCssVars(_shape: T): boolean;
     /**
      * Whether `component` should be rendered in the DOM overlay *in addition to*
      * the GPU geometry (e.g. a text label on a filled shape).
@@ -8313,6 +8326,41 @@ interface EditorConfig extends TldrawOptions {
      * enough to debounce at all, and how much movement is worth publishing.
      */
     debouncedZoomOctaves: number;
+    /**
+     * How many DOM-overlay shapes that left the viewport stay mounted, hidden, so
+     * coming back into view costs a style change instead of a React remount.
+     *
+     * The engine culls the overlay to the viewport exactly, so without this every
+     * card that crosses the viewport edge during a pan or a zoom is unmounted and
+     * rebuilt from nothing when the gesture comes back — on a board of heavy React
+     * cards, dozens of remounts per gesture. Retained shapes are the most recently
+     * culled ones (least recently visible are evicted first), they are listed in
+     * {@link Editor.getOverlayRetainedShapeIds}, and the canvas hides them with
+     * `content-visibility: hidden`, which keeps their DOM and layout but skips
+     * their rendering.
+     *
+     * The bound is the memory cost: up to this many shapes' DOM is kept alive off
+     * screen. `0` turns retention off and unmounts at the edge, as every release before
+     * this option did.
+     */
+    overlayRetainLimit: number;
+    /**
+     * Whether the DOM overlay lets `--mocanvas-zoom` / `--mocanvas-scale` inherit
+     * into the shapes below it.
+     *
+     * `"cut"` (the default) has the overlay declare them as constants, so the
+     * container's — rewritten on every frame of a zoom — stop there. A changed
+     * inherited custom property restyles every descendant, and on a board of
+     * mounted DOM cards that is every node of every shape: 41 ms of style
+     * recalculation per zoom step over 1,000 live cards, against 0.1 ms with the
+     * inheritance cut (`apps/bench`, `dom-overlay.mjs`).
+     *
+     * A shape that reads the live zoom in its own CSS says so with
+     * `ShapeUtil.usesCameraCssVars()` and gets the real values on its wrapper.
+     * `"inherit"` restores the old behaviour for an app whose shape CSS reads the
+     * variables and that would rather pay than name the shapes.
+     */
+    overlayCameraCssVars: "cut" | "inherit";
 }
 declare const DEFAULT_EDITOR_CONFIG: EditorConfig;
 interface HitTestOptions {
@@ -8431,6 +8479,15 @@ declare class Editor extends EventEmitter<EditorEvents> {
     private readonly _frameEpoch;
     private readonly _overlayShapeIds;
     private readonly _overlayClips;
+    private readonly _overlayRetained;
+    /**
+     * Overlay shapes the engine culled that are still mounted, oldest first: a
+     * `Map` iterates in insertion order, which is the LRU order eviction wants.
+     * Each carries the clip it had when it was last on screen.
+     */
+    private readonly overlayRetained;
+    /** Last frame's on-screen overlay shapes (engine list plus kept ones), with their clips. */
+    private overlayOnScreen;
     private readonly _isDisposed;
     private readonly _lastFrame;
     private readonly _cameraOptions;
@@ -8515,8 +8572,18 @@ declare class Editor extends EventEmitter<EditorEvents> {
         culled: number;
         ms: number;
     };
-    /** Shapes the DOM overlay must render this frame, in draw order. */
+    /**
+     * Shapes the DOM overlay must keep mounted this frame, in draw order: the ones
+     * on screen, plus those listed by {@link getOverlayRetainedShapeIds}, which are
+     * off screen and mounted only so that coming back does not rebuild them.
+     */
     getOverlayShapeIds(): readonly ShapeId[];
+    /**
+     * The subset of {@link getOverlayShapeIds} that the engine culled and the
+     * overlay keeps mounted but hidden — see `options.overlayRetainLimit`. Empty
+     * when nothing is retained.
+     */
+    getOverlayRetainedShapeIds(): ReadonlySet<ShapeId>;
     /**
      * Page-space clip rects for the overlay shapes, parallel to
      * `getOverlayShapeIds()`; `undefined` where the shape is unclipped.
@@ -9088,6 +9155,27 @@ declare class Editor extends EventEmitter<EditorEvents> {
      * ancestors give it, on screen or off, so its DOM never changes shape at the viewport edge.
      */
     private keepUncullableOverlay;
+    /**
+     * Keep the overlay shapes that just left the viewport mounted, up to
+     * `options.overlayRetainLimit`, and put the whole list in paint order.
+     *
+     * A shape that the engine stops reporting moves into a bounded LRU; one that
+     * comes back moves out of it. Either way its entry in the list — and so its
+     * React element and DOM — is untouched; only its retained flag flips. The list
+     * is sorted by paint rank whenever anything is retained, so a shape crossing
+     * the viewport edge never changes position among its siblings either: React
+     * would move its DOM for that, and moving a node with an iframe in it reloads
+     * the iframe.
+     *
+     * Returns the retained ids, which the canvas hides.
+     */
+    private retainCulledOverlay;
+    /**
+     * Every shape on the current page by paint order. Recomputed when a shape
+     * record changes — not when the camera moves, which is when the overlay
+     * needs it.
+     */
+    private readonly _paintRank;
     /**
      * Device-pixel scale at which rasterized textures (text labels) should be
      * drawn: the device pixel ratio times the zoom, bucketed to powers of two.

package/dist/index.js

@@ -1,10 +1,10 @@
-import { atom, computed, unsafe__withoutCapture, transact, react } from '@mocanvas/state';
+import { atom, react, computed, unsafe__withoutCapture, transact } from '@mocanvas/state';
 export { AtomMap, atom, computed, react, reactor, transact, transaction } from '@mocanvas/state';
 import { createRecordType, isIndexKey, createMigrationIds, uniqueId, isRecordsDiffEmpty, squashRecordDiffs, reverseRecordsDiff, sortByIndex, getIndexAbove, ZERO_INDEX_KEY, getIndexBetween, getIndexBelow, getIndicesAbove, indexKeyToZKey, parseMigrationId, createMigrationSequence, StoreSchema, Store } from '@mocanvas/store';
 export { ZERO_INDEX_KEY, createComputedCache, getGraphemeLength, getGraphemes, getIndexAbove, getIndexBelow, getIndexBetween, getIndices, getIndicesAbove, getIndicesBelow, getIndicesBetween, iterateGraphemes, sortByIndex } from '@mocanvas/store';
 import { PATH_OP, FLAG, GEO_FLAG, EngineBridge, VERTEX_FLOATS, BATCH_WORDS, readClip } from '@mocanvas/wasm';
 export { EngineBridge, FLAG, GEO_FLAG, GEO_KIND, PATH_OP, getLoadedEngine, loadEngine, loadEngineSync } from '@mocanvas/wasm';
-import { createContext, useEffect, useRef, useLayoutEffect, useContext, Component, useMemo, useId, useCallback, useState } from 'react';
+import { createContext, useEffect, useRef, useLayoutEffect, memo, useContext, Component, useMemo, useId, useCallback, useState } from 'react';
 import { track as track$1, useValue } from '@mocanvas/state/react';
 export { track, useAtom, useComputed, useQuickReactor, useReactor, useStateTracking, useValue } from '@mocanvas/state/react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -7849,7 +7849,12 @@ var DEFAULT_EDITOR_CONFIG = {
   backgroundColor: [0.976, 0.98, 0.984, 1],
   // SEMANTICS-ASSUMED: half an octave is the smallest zoom change a rasteriser
   // should care about.
-  debouncedZoomOctaves: 0.5
+  debouncedZoomOctaves: 0.5,
+  // SEMANTICS-ASSUMED: a few screens' worth of cards on a dense board. Measured
+  // in apps/bench (`dom-overlay.mjs`): a pan or zoom there and back stops
+  // remounting at this size; the cost is the DOM of this many off-screen shapes.
+  overlayRetainLimit: 256,
+  overlayCameraCssVars: "cut"
 };
 var RAD_PER_DEG = Math.PI / 180;
 var WHEEL_ZOOM_DELTA_CAP = 50;
@@ -7949,6 +7954,15 @@ var Editor = class extends EventEmitter {
   _frameEpoch;
   _overlayShapeIds;
   _overlayClips;
+  _overlayRetained;
+  /**
+   * Overlay shapes the engine culled that are still mounted, oldest first: a
+   * `Map` iterates in insertion order, which is the LRU order eviction wants.
+   * Each carries the clip it had when it was last on screen.
+   */
+  overlayRetained = /* @__PURE__ */ new Map();
+  /** Last frame's on-screen overlay shapes (engine list plus kept ones), with their clips. */
+  overlayOnScreen = /* @__PURE__ */ new Map();
   _isDisposed;
   _lastFrame;
   _cameraOptions;
@@ -8015,6 +8029,7 @@ var Editor = class extends EventEmitter {
     });
     this._overlayShapeIds = atom("editor.overlayShapeIds", []);
     this._overlayClips = atom("editor.overlayClips", []);
+    this._overlayRetained = atom("editor.overlayRetained", EMPTY_ID_SET);
     this._isDisposed = atom("editor.isDisposed", false);
     this._isMounted = atom("editor.isMounted", false);
     this._lastFrame = atom("editor.lastFrame", { drawn: 0, culled: 0, ms: 0 });
@@ -8209,10 +8224,22 @@ var Editor = class extends EventEmitter {
   getLastFrameStats() {
     return this._lastFrame.get();
   }
-  /** Shapes the DOM overlay must render this frame, in draw order. */
+  /**
+   * Shapes the DOM overlay must keep mounted this frame, in draw order: the ones
+   * on screen, plus those listed by {@link getOverlayRetainedShapeIds}, which are
+   * off screen and mounted only so that coming back does not rebuild them.
+   */
   getOverlayShapeIds() {
     return this._overlayShapeIds.get();
   }
+  /**
+   * The subset of {@link getOverlayShapeIds} that the engine culled and the
+   * overlay keeps mounted but hidden — see `options.overlayRetainLimit`. Empty
+   * when nothing is retained.
+   */
+  getOverlayRetainedShapeIds() {
+    return this._overlayRetained.get();
+  }
   /**
    * Page-space clip rects for the overlay shapes, parallel to
    * `getOverlayShapeIds()`; `undefined` where the shape is unclipped.
@@ -10350,10 +10377,12 @@ var Editor = class extends EventEmitter {
       }
     }
     unsafe__withoutCapture(() => this.keepUncullableOverlay(ids, clips));
+    const retained = unsafe__withoutCapture(() => this.retainCulledOverlay(ids, clips));
     unsafe__withoutCapture(() => {
       const prev = this._overlayShapeIds.get();
       if (prev.length !== ids.length || prev.some((id, i) => id !== ids[i])) this._overlayShapeIds.set(ids);
       if (!sameClips(this._overlayClips.get(), clips)) this._overlayClips.set(clips);
+      if (!sameIdSet(this._overlayRetained.get(), retained)) this._overlayRetained.set(retained);
       const ms = performance.now() - t0;
       this._lastFrame.set({ drawn: frame.drawn, culled: frame.culled, ms });
       this.emit("frame", { drawn: frame.drawn, culled: frame.culled, ms });
@@ -10383,6 +10412,69 @@ var Editor = class extends EventEmitter {
       clips.push(entry.clip);
     }
   }
+  /**
+   * Keep the overlay shapes that just left the viewport mounted, up to
+   * `options.overlayRetainLimit`, and put the whole list in paint order.
+   *
+   * A shape that the engine stops reporting moves into a bounded LRU; one that
+   * comes back moves out of it. Either way its entry in the list — and so its
+   * React element and DOM — is untouched; only its retained flag flips. The list
+   * is sorted by paint rank whenever anything is retained, so a shape crossing
+   * the viewport edge never changes position among its siblings either: React
+   * would move its DOM for that, and moving a node with an iframe in it reloads
+   * the iframe.
+   *
+   * Returns the retained ids, which the canvas hides.
+   */
+  retainCulledOverlay(ids, clips) {
+    const limit = Math.max(0, Math.floor(this.options.overlayRetainLimit));
+    const lastOnScreen = this.overlayOnScreen;
+    const onScreen = /* @__PURE__ */ new Map();
+    for (let i = 0; i < ids.length; i++) onScreen.set(ids[i], clips[i]);
+    this.overlayOnScreen = onScreen;
+    const retainedMap = this.overlayRetained;
+    if (limit === 0) {
+      retainedMap.clear();
+      return EMPTY_ID_SET;
+    }
+    for (const id of onScreen.keys()) retainedMap.delete(id);
+    for (const [id, clip] of lastOnScreen) {
+      if (onScreen.has(id)) continue;
+      retainedMap.delete(id);
+      retainedMap.set(id, clip);
+    }
+    if (retainedMap.size === 0) return EMPTY_ID_SET;
+    const pageId = this.getCurrentPageId();
+    for (const id of [...retainedMap.keys()]) {
+      const shape = this.getShape(id);
+      if (!shape || !this.overlayFlaggedIds.has(id) || this.getAncestorPageId(shape) !== pageId || isShapeHidden(this, shape)) {
+        retainedMap.delete(id);
+      }
+    }
+    while (retainedMap.size > limit) retainedMap.delete(retainedMap.keys().next().value);
+    if (retainedMap.size === 0) return EMPTY_ID_SET;
+    const rank = this._paintRank.get();
+    const entries = [];
+    for (const [id, clip] of onScreen) entries.push({ id, clip });
+    for (const [id, clip] of retainedMap) entries.push({ id, clip });
+    const rankOf = (id) => rank.get(id) ?? Number.MAX_SAFE_INTEGER;
+    entries.sort((a, b) => rankOf(a.id) - rankOf(b.id));
+    ids.length = 0;
+    clips.length = 0;
+    for (const entry of entries) {
+      ids.push(entry.id);
+      clips.push(entry.clip);
+    }
+    return new Set(retainedMap.keys());
+  }
+  /**
+   * Every shape on the current page by paint order. Recomputed when a shape
+   * record changes — not when the camera moves, which is when the overlay
+   * needs it.
+   */
+  _paintRank = computed("editor.paintRank", () => {
+    return new Map(this.getCurrentPageShapesSorted().map((shape, index) => [shape.id, index]));
+  });
   // ---- textures ----------------------------------------------------------
   /**
    * Device-pixel scale at which rasterized textures (text labels) should be
@@ -11622,6 +11714,13 @@ var Editor = class extends EventEmitter {
   /** Which menus are open right now. Backed by the `instance` session record. */
   menus = new MenuManager(this);
 };
+var EMPTY_ID_SET = /* @__PURE__ */ new Set();
+function sameIdSet(a, b) {
+  if (a === b) return true;
+  if (a.size !== b.size) return false;
+  for (const id of a) if (!b.has(id)) return false;
+  return true;
+}
 function sameClips(a, b) {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) {
@@ -13813,6 +13912,21 @@ var ShapeUtil = class {
   needsOverlay(shape) {
     return this.editor.getEditingShapeId() === shape.id;
   }
+  /**
+   * Whether this shape's own CSS reads `--mocanvas-zoom` / `--mocanvas-scale`.
+   *
+   * The overlay stops those variables inheriting into mounted shapes, because a
+   * custom property that changes on every zoom frame restyles every node below
+   * it — the cost of a zoom on a board of DOM cards. A shape that says `true`
+   * here gets the live values on its own wrapper, and pays that restyle for
+   * itself: the counter-scaled label, the hairline that must stay 1px.
+   *
+   * Default `false`. `options.overlayCameraCssVars: "inherit"` turns the whole
+   * mechanism off for an app that would rather not name its shapes.
+   */
+  usesCameraCssVars(_shape) {
+    return false;
+  }
   /**
    * Whether `component` should be rendered in the DOM overlay *in addition to*
    * the GPU geometry (e.g. a text label on a filled shape).
@@ -15174,10 +15288,8 @@ function CanvasBody({ editor, className, style, children, components, indicatorO
   const cursor = useValue("cursor", () => cssCursor(editor.getInstanceState().cursor.type), [editor]);
   const hasChromeContextMenu = useEditorComponents().ContextMenu != null;
   const themeVars = useThemeCssVars(editor);
-  const cameraVars = useCameraCssVars(editor);
+  useCameraCssVarsOnElement(editor, containerRef, style);
   const isGridMode = useValue("isGridMode", () => editor.getInstanceState().isGridMode, [editor]);
-  const camera = useValue("camera", () => editor.getCamera(), [editor]);
-  const gridSize = useValue("gridSize", () => editor.getDocumentSettings().gridSize, [editor]);
   const Grid = components?.Grid === void 0 ? DefaultGrid : components.Grid;
   const Indicators = components?.Indicators ?? DefaultIndicators;
   const Brush = components?.Brush ?? (hasOverlay(editor, "brush") ? null : DefaultBrush);
@@ -15188,7 +15300,7 @@ function CanvasBody({ editor, className, style, children, components, indicatorO
     {
       ref: containerRef,
       className: className ? `mocanvas ${className}` : "mocanvas",
-      style: { ...containerStyle, background: backgroundFor(editor), ...themeVars, ...cameraVars, ...style, cursor },
+      style: { ...containerStyle, background: backgroundFor(editor), ...themeVars, ...style, cursor },
       tabIndex: 0,
       onPointerDown: events.onPointerDown,
       onPointerMove: events.onPointerMove,
@@ -15198,7 +15310,7 @@ function CanvasBody({ editor, className, style, children, components, indicatorO
       "data-testid": "mocanvas-container",
       children: [
         Background ? /* @__PURE__ */ jsx(Background, { editor }) : null,
-        Grid !== null && isGridMode ? /* @__PURE__ */ jsx(Grid, { x: camera.x, y: camera.y, z: camera.z, size: gridSize }) : null,
+        Grid !== null && isGridMode ? /* @__PURE__ */ jsx(GridLayer, { editor, Grid }) : null,
         /* @__PURE__ */ jsx("canvas", { ref: canvasRef, style: { ...layerStyle, display: "block" } }),
         /* @__PURE__ */ jsx(OverlayLayer, { editor }),
         /* @__PURE__ */ jsx(IndicatorCanvas, { editor, util: indicatorOverlayUtil ?? ShapeIndicatorCompositor }),
@@ -15264,45 +15376,102 @@ function IndicatorCanvas({ editor, util }) {
   }, [editor, overlay]);
   return /* @__PURE__ */ jsx("canvas", { ref: canvasRef, style: { ...layerStyle, pointerEvents: "none", display: "block" } });
 }
+function useCameraCssVarsOnElement(editor, ref, style) {
+  const own = style;
+  const ownZoom = own?.["--mocanvas-zoom"] !== void 0;
+  const ownScale = own?.["--mocanvas-scale"] !== void 0;
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    return react("canvas.cameraCssVars", () => {
+      const vars = getCameraCssVars(editor.getZoomLevel());
+      if (!ownZoom) el.style.setProperty("--mocanvas-zoom", vars["--mocanvas-zoom"]);
+      if (!ownScale) el.style.setProperty("--mocanvas-scale", vars["--mocanvas-scale"]);
+    });
+  }, [editor, ref, ownZoom, ownScale]);
+}
+function useCameraCssVarsOnShape(editor, enabled) {
+  const ref = useRef(null);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (!enabled) {
+      el.style.removeProperty("--mocanvas-zoom");
+      el.style.removeProperty("--mocanvas-scale");
+      return;
+    }
+    return react("canvas.shapeCameraCssVars", () => {
+      const vars = getCameraCssVars(editor.getZoomLevel());
+      el.style.setProperty("--mocanvas-zoom", vars["--mocanvas-zoom"]);
+      el.style.setProperty("--mocanvas-scale", vars["--mocanvas-scale"]);
+    });
+  }, [editor, enabled]);
+  return ref;
+}
+var GridLayer = track$1(function GridLayer2({ editor, Grid }) {
+  const camera = editor.getCamera();
+  const size = editor.getDocumentSettings().gridSize;
+  return /* @__PURE__ */ jsx(Grid, { x: camera.x, y: camera.y, z: camera.z, size });
+});
 var OverlayLayer = track$1(function OverlayLayer2({ editor }) {
   const ids = editor.getOverlayShapeIds();
   const clips = editor.getOverlayClips();
-  const cam = editor.getCamera();
+  const retained = editor.getOverlayRetainedShapeIds();
   const editingId = editor.getEditingShapeId();
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      className: "mocanvas-overlay",
-      style: {
-        ...layerStyle,
-        pointerEvents: "none",
-        transformOrigin: "0 0",
-        transform: `scale(${cam.z}) translate(${cam.x}px, ${cam.y}px)`
+  const ref = useRef(null);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    return react("canvas.overlayTransform", () => {
+      const cam = editor.getCamera();
+      el.style.transform = `scale(${cam.z}) translate(${cam.x}px, ${cam.y}px)`;
+    });
+  }, [editor]);
+  const cut = editor.options.overlayCameraCssVars !== "inherit";
+  return /* @__PURE__ */ jsx("div", { ref, className: "mocanvas-overlay", style: cut ? overlayLayerStyleCut : overlayLayerStyle, children: ids.map((id, i) => {
+    const shape = editor.getShape(id);
+    if (!shape) return null;
+    return /* @__PURE__ */ jsx(
+      OverlayShape,
+      {
+        editor,
+        shape,
+        isEditing: editingId === id,
+        clip: clips[i],
+        isRetained: retained.has(id)
       },
-      children: ids.map((id, i) => {
-        const shape = editor.getShape(id);
-        if (!shape) return null;
-        return /* @__PURE__ */ jsx(OverlayShape, { editor, shape, isEditing: editingId === id, clip: clips[i] }, id);
-      })
-    }
-  );
+      id
+    );
+  }) });
 });
+var overlayLayerStyle = { ...layerStyle, pointerEvents: "none", transformOrigin: "0 0" };
+var overlayLayerStyleCut = {
+  ...overlayLayerStyle,
+  ["--mocanvas-zoom"]: "1",
+  ["--mocanvas-scale"]: "1"
+};
+var RETAINED_STYLE = { contentVisibility: "hidden", visibility: "hidden" };
 var OverlayShape = track$1(function OverlayShape2({
   editor,
   shape,
   isEditing,
-  clip
+  clip,
+  isRetained
 }) {
   const util = editor.getShapeUtil(shape);
   const m = editor.getShapePageTransform(shape);
   const bounds = editor.getShapeGeometryBounds(shape);
+  const asksForCamera = util.usesCameraCssVars?.(shape) === true;
+  const cameraRef = useCameraCssVarsOnShape(editor, asksForCamera);
   const offset = clip ? `translate(${-clip[0]}px, ${-clip[1]}px) ` : "";
   const el = /* @__PURE__ */ jsx(
     "div",
     {
+      ref: cameraRef,
       className: "mocanvas-shape",
       "data-shape-id": shape.id,
       "data-shape-type": shape.type,
+      "data-retained": isRetained && !clip ? "true" : void 0,
       style: {
         position: "absolute",
         left: 0,
@@ -15312,7 +15481,8 @@ var OverlayShape = track$1(function OverlayShape2({
         transformOrigin: "0 0",
         transform: `${offset}matrix(${m.a}, ${m.b}, ${m.c}, ${m.d}, ${m.e}, ${m.f})`,
         opacity: shape.opacity,
-        pointerEvents: isEditing ? "auto" : "none"
+        pointerEvents: isEditing ? "auto" : "none",
+        ...isRetained && !clip ? RETAINED_STYLE : null
       },
       children: /* @__PURE__ */ jsxs(ShapeBoundary, { shape, children: [
         /* @__PURE__ */ jsx(ShapeBody, { editor, shape }),
@@ -15325,6 +15495,7 @@ var OverlayShape = track$1(function OverlayShape2({
     "div",
     {
       className: "mocanvas-shape-clip",
+      "data-retained": isRetained ? "true" : void 0,
       style: {
         position: "absolute",
         left: clip[0],
@@ -15332,7 +15503,8 @@ var OverlayShape = track$1(function OverlayShape2({
         width: Math.max(0, clip[2] - clip[0]),
         height: Math.max(0, clip[3] - clip[1]),
         overflow: "hidden",
-        pointerEvents: "none"
+        pointerEvents: "none",
+        ...isRetained ? RETAINED_STYLE : null
       },
       children: el
     }
@@ -15374,9 +15546,10 @@ var DefaultIndicators = track$1(function DefaultIndicators2({ editor }) {
   const bounds = editor.getSelectionPageBounds();
   const hovered = editor.getHoveredShape();
   const selected = editor.getSelectedShapes();
+  const tool = editor.getCurrentToolId();
+  if (!bounds && selected.length === 0 && !(hovered && tool === "select")) return null;
   const cam = editor.getCamera();
   const z = cam.z;
-  const tool = editor.getCurrentToolId();
   const toScreen = (x, y) => [(x + cam.x) * z, (y + cam.y) * z];
   const items = [];
   const indicatorFor = (shape, key, stroke) => {
@@ -15502,9 +15675,19 @@ var DefaultBrush = track$1(function DefaultBrush2({ editor }) {
     }
   );
 });
-var ShapeBody = track$1(function ShapeBody2({ editor, shape }) {
-  return /* @__PURE__ */ jsx(Fragment, { children: editor.getShapeUtil(shape).component(shape) });
-});
+var ShapeBody = track$1(
+  memo(
+    function ShapeBody2({ editor, shape }) {
+      return /* @__PURE__ */ jsx(Fragment, { children: editor.getShapeUtil(shape).component(shape) });
+    },
+    // A body is a function of its shape's content, not of where the shape is:
+    // the wrapper above carries position, rotation and opacity as a transform.
+    // Comparing the whole record re-rendered every card under a drag on every
+    // frame, though nothing it draws had changed. Signals the body reads still
+    // re-render it through `track`.
+    (prev, next) => prev.editor === next.editor && prev.shape.id === next.shape.id && prev.shape.type === next.shape.type && prev.shape.props === next.shape.props && prev.shape.meta === next.shape.meta
+  )
+);
 function ShapeBoundary({ shape, children }) {
   const Fallback = useErrorSlot("ShapeErrorFallback", DefaultShapeErrorFallback);
   return /* @__PURE__ */ jsx(