@mocanvas/wasm 4.1.0 → 4.2.0

package/MIGRATION.md

@@ -253,6 +253,40 @@ during the zero-rename step. Under pnpm's strict `node_modules` that means
 adding `@mocanvas/mocanvas` to your own dependencies alongside
 `@mocanvas/compat`.
 
+**If your own CSS reads tldraw's custom properties, add a second line:**
+
+```ts
+import "@mocanvas/compat/compat.css"
+```
+
+This is the half of the compat layer that nothing checks for you. The package
+alias covers the symbols TypeScript sees; it cannot cover the `--tl-*` names in
+your stylesheets. Without it a migration goes green — build, types, tests — and
+the damage shows up only to the eye, because a `var()` that resolves to nothing
+does not fail, it deletes the declaration it sits in (and inside `calc()`, the
+whole property). One consumer found it as a cursor whose white outline had
+quietly stopped being drawn.
+
+`compat.css` maps tldraw's tokens onto mocanvas's and gives **every** one a
+literal fallback, so a token with no counterpart cannot take a rule down with
+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-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
+or a flip to dark. The stylesheet is scoped to `.mocanvas` rather than `:root`,
+so a page that still renders a real tldraw editor somewhere keeps its own
+values.
+
+**Next.js**: an app coming from tldraw almost certainly lists it in
+`serverExternalPackages`. Next matches that by package name, so leaving
+`@mocanvas/mocanvas` in the list turns `…/mocanvas.css` into a request Node has
+to resolve — and Node has no loader for `.css`. Take mocanvas out of the list
+entirely; there is nothing in it that needs to be external.
+
 ### Step 2 — drop the prefixes
 
 Once the app builds and runs against `@mocanvas/compat`, rename `TLFoo` →
@@ -663,6 +697,8 @@ aspirational.
 | `ShapeUtil.toSvg`, `ShapeUtil.toBackgroundSvg` | Not `ShapeUtil` members. Custom shapes contribute to SVG export through `registerShapeSvgRenderer(type, renderer)`; without one they fall back to `geometryFallbackSvg`. |
 | Sync protocol | Wire compatibility with tldraw's own sync protocol is not planned. `@mocanvas/sync` is a working transport of its own — presence records, `store.mergeRemoteChanges`, and a relay — but it does not speak tldraw's wire format. |
 | `image` shape on the GPU | The texture path exists in the engine (`StyleWords.texture` + `uploadTexture`) but the `image` shape still draws an `<img>` in the DOM overlay. |
+| `FrameShapeUtil` default size | mocanvas creates a frame at **160×90**; tldraw creates one at 320×180. Same aspect, half the size. It only bites code that creates a frame *programmatically* without passing `w`/`h` — drawing one with the tool sizes it from the drag either way. Pass explicit dimensions if the size matters to you. Aligning the default is a behaviour change and is not being made in a patch release. |
+| An unregistered shape type in `store.put()` | Accepted, deliberately, and confirmed rather than fixed. A `.tldr` written by a build that knows a shape type this one does not must survive a load/save round trip instead of being dropped on the next save, so an unknown `type` passes its props through untouched. Its *other* fields are still validated — `x` must be a number whatever the type is — and a type you did register is validated in full. See `COMPAT.md`. |
 | Text rendering | DOM overlay. Glyph-atlas text in WASM is phase 3. |
 | GPU frame clipping | The `CLIP` flag and `isClipShape` hook are wired end to end, but no built-in shape enables it yet (phase 3). |
 | WebGPU backend | Phase 3. WebGL2 is the only backend today, behind `RenderBackend`. |

package/package.json

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