@mocanvas/store 4.13.0 → 4.14.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,21 @@ 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.
+
 ### `getIndicatorPath` — the selection outline
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocanvas/store",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "The mocanvas document model: reactive records, schema, migrations and .tldr file IO.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Symbio Digital",
@@ -54,7 +54,7 @@
   "dependencies": {
     "fractional-indexing": "^3.2.0",
     "nanoid": "^5.1.0",
-    "@mocanvas/state": "4.13.0"
+    "@mocanvas/state": "4.14.0"
   },
   "scripts": {
     "build": "tsup",