@mocanvas/editor 4.14.0 → 4.15.1

package/CUSTOM_SHAPES.md

@@ -212,6 +212,25 @@ 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).
@@ -8331,6 +8344,23 @@ interface EditorConfig extends TldrawOptions {
      * 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 {

package/dist/index.js

@@ -7853,7 +7853,8 @@ var DEFAULT_EDITOR_CONFIG = {
   // 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
+  overlayRetainLimit: 256,
+  overlayCameraCssVars: "cut"
 };
 var RAD_PER_DEG = Math.PI / 180;
 var WHEEL_ZOOM_DELTA_CAP = 50;
@@ -13911,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).
@@ -15374,6 +15390,24 @@ function useCameraCssVarsOnElement(editor, ref, style) {
     });
   }, [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;
@@ -15393,7 +15427,8 @@ var OverlayLayer = track$1(function OverlayLayer2({ editor }) {
       el.style.transform = `scale(${cam.z}) translate(${cam.x}px, ${cam.y}px)`;
     });
   }, [editor]);
-  return /* @__PURE__ */ jsx("div", { ref, className: "mocanvas-overlay", style: overlayLayerStyle, children: ids.map((id, i) => {
+  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(
@@ -15410,6 +15445,11 @@ var OverlayLayer = track$1(function OverlayLayer2({ editor }) {
   }) });
 });
 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,
@@ -15421,10 +15461,13 @@ var OverlayShape = track$1(function OverlayShape2({
   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,