@mocanvas/compat 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/compat.css

@@ -0,0 +1,96 @@
+/**
+ * tldraw's CSS custom properties, mapped onto mocanvas's.
+ *
+ * `@mocanvas/compat` aliases the *symbols* an app imports. It did not alias the
+ * custom properties an app's stylesheets read, and that gap is invisible to
+ * every check a migration runs: TypeScript sees nothing, the build succeeds,
+ * the tests pass, and the regression is a white outline that quietly stopped
+ * being drawn. Import this alongside the package alias and a stylesheet
+ * written against tldraw keeps resolving.
+ *
+ *     import "@mocanvas/mocanvas/mocanvas.css"
+ *     import "@mocanvas/compat/compat.css"
+ *
+ * ## Every declaration carries a literal fallback, on purpose
+ *
+ * A `var()` that resolves to nothing makes the whole declaration invalid — so
+ * one missing token does not just lose its own colour, it takes the rule it
+ * appears in with it, and in a `calc()` it takes the entire property. Every
+ * mapping below therefore ends in a concrete value. A token mocanvas has no
+ * equivalent for still resolves to something defensible rather than poisoning
+ * the rule around it.
+ *
+ * ## What this cannot give you
+ *
+ * The tokens below marked "no equivalent" resolve to a static fallback, which
+ * keeps your CSS valid but is not the value tldraw would have computed. They
+ * are listed in MIGRATION.md §7 so you can decide what to do about each.
+ *
+ * Scoped to `.mocanvas` rather than `:root` so an app that still renders a real
+ * tldraw editor somewhere on the page keeps its own values.
+ */
+
+.mocanvas,
+.tl-container {
+  /* ---- camera ---------------------------------------------------------
+   * The two that are computed, not themed. `--tl-zoom` is the camera's zoom
+   * and `--tl-scale` its reciprocal — what a rule multiplies by to hold a
+   * constant on-screen size while the canvas zooms.
+   */
+  --tl-zoom: var(--mocanvas-zoom, 1);
+  --tl-scale: var(--mocanvas-scale, 1);
+
+  /* ---- surfaces and text ---------------------------------------------- */
+  --tl-color-background: var(--mocanvas-background, #f9fafb);
+  --tl-color-low: var(--mocanvas-background, #f9fafb);
+  --tl-color-panel: var(--mocanvas-ui-panel, #ffffff);
+  --tl-color-panel-contrast: var(--mocanvas-ui-text, #1d1d1d);
+  --tl-color-text: var(--mocanvas-ui-text, #1d1d1d);
+  --tl-color-text-1: var(--mocanvas-ui-text, #1d1d1d);
+  --tl-color-text-3: var(--mocanvas-ui-muted, #9a9a9a);
+  --tl-color-text-shadow: var(--mocanvas-background, #f9fafb);
+  --tl-color-divider: var(--mocanvas-ui-panel-border, #e8e8e8);
+  --tl-color-muted-1: var(--mocanvas-ui-hover, rgba(0, 0, 0, 0.04));
+  --tl-color-muted-2: var(--mocanvas-ui-active, rgba(0, 0, 0, 0.08));
+  --tl-color-hint: var(--mocanvas-snap, #bd5b16);
+  --tl-color-focus: var(--mocanvas-ui-accent, #2f80ed);
+
+  /* ---- selection ------------------------------------------------------
+   * `--tl-color-selected-contrast` is the one whose absence was found by eye:
+   * the chevron cursor draws its outline in it, and an empty value removed the
+   * outline without failing anything.
+   */
+  --tl-color-selected: var(--mocanvas-selection, #2f80ed);
+  --tl-color-selected-contrast: var(--mocanvas-selection-fg, #ffffff);
+  --tl-color-selection-fill: var(--mocanvas-brush-fill, rgba(47, 128, 237, 0.08));
+  --tl-color-selection-stroke: var(--mocanvas-selection, #2f80ed);
+  --tl-color-brush-fill: var(--mocanvas-brush-fill, rgba(47, 128, 237, 0.08));
+  --tl-color-brush-stroke: var(--mocanvas-brush-stroke, rgba(47, 128, 237, 0.4));
+  --tl-color-grid: var(--mocanvas-grid, #d4d4d4);
+  --tl-color-laser: #ff0000; /* no equivalent: the laser colour is not on the ramp */
+  --tl-color-cursor: var(--mocanvas-selection, #2f80ed);
+  --tl-color-note-border: rgba(0, 0, 0, 0.08); /* no equivalent */
+
+  /* ---- chrome ---------------------------------------------------------- */
+  --tl-color-primary: var(--mocanvas-ui-accent, #2f80ed);
+  --tl-color-background-secondary: var(--mocanvas-ui-dock, #ffffff);
+  --tl-font-draw: var(--mocanvas-ui-font, ui-sans-serif, system-ui, sans-serif);
+  --tl-font-sans: var(--mocanvas-ui-font, ui-sans-serif, system-ui, sans-serif);
+  --tl-font-mono: var(--mocanvas-ui-mono, ui-monospace, monospace);
+  --tl-radius: var(--mocanvas-ui-radius, 10px);
+  --tl-shadow-1: var(--mocanvas-ui-shadow, 0 1px 2px rgba(0, 0, 0, 0.12));
+  --tl-shadow-2: var(--mocanvas-ui-shadow, 0 2px 6px rgba(0, 0, 0, 0.14));
+  --tl-space-1: 4px;
+  --tl-space-2: 8px;
+  --tl-space-3: 12px;
+  --tl-space-4: 16px;
+
+  /* ---- no equivalent ---------------------------------------------------
+   * Static fallbacks. They keep a migrated rule valid; they are not values
+   * mocanvas computes, and it will not notice if you need a different one.
+   */
+  --tl-color-overlay: rgba(0, 0, 0, 0.2);
+  --tl-color-background-overlay: rgba(0, 0, 0, 0.2);
+  --tl-color-warn: #e03131;
+  --tl-color-accent: var(--mocanvas-ui-accent, #2f80ed);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocanvas/compat",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "TL-prefixed aliases over the mocanvas API, for projects migrating an existing tldraw app.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Symbio Digital",
@@ -16,6 +16,7 @@
     "node": ">=22.12.0"
   },
   "files": [
+    "compat.css",
     "dist",
     "README.md",
     "LICENSE",
@@ -27,13 +28,19 @@
     "MIGRATION.md",
     "UI.md"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
+    },
+    "./compat.css": {
+      "style": "./compat.css",
+      "default": "./compat.css"
     },
     "./package.json": "./package.json"
   },
@@ -41,10 +48,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@mocanvas/editor": "4.1.0",
-    "@mocanvas/mocanvas": "4.1.0",
-    "@mocanvas/store": "4.1.0",
-    "@mocanvas/state": "4.1.0"
+    "@mocanvas/mocanvas": "4.2.0",
+    "@mocanvas/editor": "4.2.0",
+    "@mocanvas/state": "4.2.0",
+    "@mocanvas/store": "4.2.0"
   },
   "devDependencies": {
     "@types/react": "^19.1.0",