@mocanvas/wasm 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocanvas/wasm",
-  "version": "4.13.0",
+  "version": "4.15.0",
   "description": "Typed loader and zero-copy bridge over the mocanvas Rust/WebAssembly engine.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Symbio Digital",