@mocanvas/editor 4.12.3 → 4.13.0

package/COMPAT.md

@@ -96,6 +96,10 @@ predicates (`canTabTo`, `canResizeChildren`, `canBeLaidOut`, `canCull`,
 `canEditInReadonly`, …) and `createShapeForAsset`. **That is where the remaining
 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()`.
+
 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`
 remapped onto `@mocanvas/compat` and reports what breaks, grouped by symbol.

package/dist/index.d.ts

@@ -8438,6 +8438,8 @@ declare class Editor extends EventEmitter<EditorEvents> {
     private syncedPageId;
     /** Shapes whose last write to the engine threw; they are warned about once. */
     private readonly brokenShapeIds;
+    /** Shapes on the synced page the engine reports to the DOM overlay (`FLAG.OVERLAY` or `FLAG.LABEL`). */
+    private readonly overlayFlaggedIds;
     /** Handle of the camera animation in flight, if any. */
     private cameraAnimation;
     /**
@@ -8614,6 +8616,18 @@ declare class Editor extends EventEmitter<EditorEvents> {
     updateCurrentPageState(partial: Partial<Omit<InstancePageState, "id" | "typeName" | "pageId">>): this;
     private readonly _allShapes;
     private readonly _currentPageShapes;
+    /**
+     * The DOM-overlay shapes whose util opts out of culling (`canCull() === false`), each with the
+     * clip its ancestors give it, plus the paint rank of every shape on the page; `null` when there
+     * are none.
+     *
+     * The engine reports only the overlay shapes inside the viewport, so without this a shape that
+     * must outlive the viewport — a live embed, a playing video — was unmounted the moment it was
+     * panned or zoomed out of view, and rebuilt when it came back. Recomputed whenever a shape record
+     * on the page changes — every frame of a drag, but never for a camera move — and never at all
+     * when no registered util implements `canCull`.
+     */
+    private readonly _keptOverlay;
     private readonly _currentPageShapeIds;
     /**
      * One shape by id.
@@ -9066,6 +9080,14 @@ declare class Editor extends EventEmitter<EditorEvents> {
     private writeEngineGeometry;
     /** Build and draw one frame. Called by the canvas component inside rAF. */
     renderFrame(backend: RenderBackend): FrameBuffers;
+    /**
+     * Add the overlay shapes that may not be culled to this frame's overlay list, off screen or not,
+     * and put the whole list in paint order. The order must not depend on what is on screen: a shape
+     * that changes place among its siblings is moved in the DOM by React, which restyles and lays out
+     * all of it — the very cost keeping it mounted avoids. A kept shape always carries the clip its
+     * ancestors give it, on screen or off, so its DOM never changes shape at the viewport edge.
+     */
+    private keepUncullableOverlay;
     /**
      * 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

@@ -7956,6 +7956,8 @@ var Editor = class extends EventEmitter {
   syncedPageId = null;
   /** Shapes whose last write to the engine threw; they are warned about once. */
   brokenShapeIds = /* @__PURE__ */ new Set();
+  /** Shapes on the synced page the engine reports to the DOM overlay (`FLAG.OVERLAY` or `FLAG.LABEL`). */
+  overlayFlaggedIds = /* @__PURE__ */ new Set();
   /** Handle of the camera animation in flight, if any. */
   cameraAnimation;
   /**
@@ -8441,6 +8443,45 @@ var Editor = class extends EventEmitter {
     const pageId = this.getCurrentPageId();
     return this._allShapes.get().filter((s) => this.getAncestorPageId(s) === pageId);
   });
+  /**
+   * The DOM-overlay shapes whose util opts out of culling (`canCull() === false`), each with the
+   * clip its ancestors give it, plus the paint rank of every shape on the page; `null` when there
+   * are none.
+   *
+   * The engine reports only the overlay shapes inside the viewport, so without this a shape that
+   * must outlive the viewport — a live embed, a playing video — was unmounted the moment it was
+   * panned or zoomed out of view, and rebuilt when it came back. Recomputed whenever a shape record
+   * on the page changes — every frame of a drag, but never for a camera move — and never at all
+   * when no registered util implements `canCull`.
+   */
+  _keptOverlay = computed("editor.keptOverlay", () => {
+    const optsOut = Object.values(this.shapeUtils).some(
+      (util) => typeof util.canCull === "function"
+    );
+    if (!optsOut) return null;
+    const sorted = this.getCurrentPageShapesSorted();
+    const ids = [];
+    const clips = /* @__PURE__ */ new Map();
+    for (const shape of sorted) {
+      if (!this.overlayFlaggedIds.has(shape.id)) continue;
+      const util = this.shapeUtils[shape.type];
+      if (!util?.canCull || util.canCull(shape)) continue;
+      if (isShapeHidden(this, shape)) continue;
+      const mask = this.getShapeMask(shape);
+      let clip;
+      if (mask !== void 0) {
+        if (mask.length === 0) continue;
+        const box = Box.FromPoints(mask.map((p) => new Vec(p.x, p.y)));
+        const bounds = this.getShapePageBounds(shape);
+        if (!bounds || !bounds.collides(box)) continue;
+        clip = [box.minX, box.minY, box.maxX, box.maxY];
+      }
+      ids.push(shape.id);
+      clips.set(shape.id, clip);
+    }
+    if (ids.length === 0) return null;
+    return { ids, clips, rank: new Map(sorted.map((shape, index) => [shape.id, index])) };
+  });
   _currentPageShapeIds = computed("editor.currentPageShapeIds", () => {
     return new Set(this._currentPageShapes.get().map((s) => s.id));
   });
@@ -10142,6 +10183,7 @@ var Editor = class extends EventEmitter {
     }
     for (const rec of Object.values(changes.removed)) {
       if (rec.typeName !== "shape") continue;
+      this.overlayFlaggedIds.delete(rec.id);
       const h = this.handles.release(rec.id);
       if (h !== void 0) {
         this.engine.cmd.remove(h);
@@ -10158,6 +10200,7 @@ var Editor = class extends EventEmitter {
       if (next.typeName !== "shape" || prev.typeName !== "shape") continue;
       const onPage = this.getAncestorPageId(next) === pageId;
       if (!onPage) {
+        this.overlayFlaggedIds.delete(next.id);
         const h = this.handles.release(next.id);
         if (h !== void 0) {
           this.engine.cmd.remove(h);
@@ -10195,6 +10238,7 @@ var Editor = class extends EventEmitter {
   syncPage(pageId) {
     this.syncedPageId = pageId;
     this.handles.clear();
+    this.overlayFlaggedIds.clear();
     this.engine.cmd.clear();
     for (const shape of this.getCurrentPageShapesSorted()) {
       this.writeShapeToEngine(shape, true);
@@ -10244,6 +10288,8 @@ var Editor = class extends EventEmitter {
     } else {
       flags |= FLAG.OVERLAY;
     }
+    if (flags & (FLAG.OVERLAY | FLAG.LABEL)) this.overlayFlaggedIds.add(shape.id);
+    else this.overlayFlaggedIds.delete(shape.id);
     const bw = engineGeometry?.w ?? geometry?.bounds.w ?? 0;
     const bh = engineGeometry?.h ?? geometry?.bounds.h ?? 0;
     this.engine.cmd.upsert(h, this.kindId(shape.type), parent, zlo, zhi, flags, shape.x, shape.y, shape.rotation, bw, bh);
@@ -10303,6 +10349,7 @@ var Editor = class extends EventEmitter {
         clips.push(o.clip);
       }
     }
+    unsafe__withoutCapture(() => this.keepUncullableOverlay(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);
@@ -10314,6 +10361,28 @@ var Editor = class extends EventEmitter {
     });
     return frame;
   }
+  /**
+   * Add the overlay shapes that may not be culled to this frame's overlay list, off screen or not,
+   * and put the whole list in paint order. The order must not depend on what is on screen: a shape
+   * that changes place among its siblings is moved in the DOM by React, which restyles and lays out
+   * all of it — the very cost keeping it mounted avoids. A kept shape always carries the clip its
+   * ancestors give it, on screen or off, so its DOM never changes shape at the viewport edge.
+   */
+  keepUncullableOverlay(ids, clips) {
+    const kept = this._keptOverlay.get();
+    if (!kept) return;
+    const entries = ids.map((id, i) => ({ id, clip: kept.clips.has(id) ? kept.clips.get(id) : clips[i] }));
+    const present = new Set(ids);
+    for (const id of kept.ids) if (!present.has(id)) entries.push({ id, clip: kept.clips.get(id) });
+    const rank = (id) => kept.rank.get(id) ?? Number.MAX_SAFE_INTEGER;
+    entries.sort((a, b) => rank(a.id) - rank(b.id));
+    ids.length = 0;
+    clips.length = 0;
+    for (const entry of entries) {
+      ids.push(entry.id);
+      clips.push(entry.clip);
+    }
+  }
   // ---- textures ----------------------------------------------------------
   /**
    * Device-pixel scale at which rasterized textures (text labels) should be