cursors: anchor to content when container has a CSS transform (#116)

* cursors: anchor to content when container has a CSS transform

Reads the cursor container's live CSS transform matrix and stores cursor
coordinates in container-local space, so collaborators with different
pan/zoom agree on which word/element a cursor is hovering. Default
(document.body, no transform) is unchanged.

Used by the fridge to fix cursors not following words across users with
different pinch-zoom and pan states.

Also: require a changeset for any change under packages/.

* cursors: spell out transform-origin: 0 0 assumption

* docs: cursors — anchoring to a transformed canvas (container option)

Author: spencerc99

.changeset/cursor-transformed-container.md

@@ -0,0 +1,5 @@
+---
+"playhtml": patch
+---
+
+Cursors now anchor to content when the cursor `container` has its own CSS transform (e.g. a pannable, zoomable canvas). The library reads the live transform matrix from `getComputedStyle()` and stores cursor coordinates in the container's local coordinate space, so two clients with different pan/zoom agree on a cursor's content position; each viewer's CSS transform then maps that position to their own viewport pixels. Default behavior is unchanged when `container` is `document.body` (no transform → identity matrix).

CLAUDE.md

@@ -147,7 +147,7 @@ Bun handles workspace linking automatically. Changes across packages are immedia
 ## Commit & PR Guidelines
 
 - **Commits:** Short imperative subject; scope paths when helpful (e.g., `react:`, `extension:`). Group mechanical changes separately.
-- **Changesets:** Use `bun run changeset` when user-facing packages change. Config in `.changeset/config.json` (public access, patch for internal deps).
+- **Changesets:** ALWAYS add a changeset whenever you modify code under `packages/` (core libraries: `playhtml`, `@playhtml/react`, `@playhtml/common`). Create the file directly in `.changeset/<short-slug>.md` with the standard frontmatter (`"<package>": patch|minor|major`) and a one-paragraph user-facing description of the change and why. `bun run changeset` is the interactive equivalent. Config in `.changeset/config.json` (public access, patch for internal deps). Skip changesets only for changes outside `packages/` (website, extension, docs, internal-docs).
 - **Releases:** `bun run version-packages` then `bun run release` (builds + publishes via changesets).
 - **PRs:** Include summary, rationale, screenshots for UI/site/extension changes, reproduction for fixes, and link issues.
 

apps/docs/src/content/docs/data/presence/cursors.md

@@ -177,6 +177,62 @@ cursors: {
 }
 ```
 
+### `container`
+
+Where playhtml mounts cursor DOM (and the cursor stylesheet). Defaults to `document.body`. Two reasons to set it:
+
+1. **Surviving SPA navigation.** If your framework swaps `document.body` on route changes (Astro ViewTransitions, htmx boost, Turbo), pass a container you mark as persistent so cursors don't get blown away. See [navigation](/docs/advanced/navigation/).
+2. **Anchoring cursors to a pannable / zoomable canvas.** If the container has its own CSS `transform` (e.g. you implement pinch-zoom and pan by setting `transform: translate(...) scale(...)` on a wrapper), playhtml stores cursor coordinates in that container's local space — so two viewers with different pan/zoom agree on which content a cursor is hovering. See the next section.
+
+**Type:** `HTMLElement | string | (() => HTMLElement | null) | React.RefObject<HTMLElement>`
+
+## Anchoring cursors to a transformed canvas
+
+If your page implements its own pan and zoom by applying a CSS transform to a wrapper element, the default cursor behavior doesn't do what you want: cursors are stored in viewport pixels, so when one user pans, their cursor for everyone else lands at the wrong word / shape / cell. The fix is one option:
+
+```js
+playhtml.init({
+  cursors: {
+    enabled: true,
+    container: ".canvas",  // your transformed wrapper
+  },
+});
+```
+
+When `container` resolves to a non-`document.body` element, playhtml reads its live transform matrix from `getComputedStyle()` on every pointer event:
+
+- **Storage** is the container's local (pre-transform) coordinate space. Two clients with different pan/zoom now agree on cursor positions.
+- **Rendering** mounts cursors inside the container with `position: absolute`. The container's own CSS transform composes them into each viewer's viewport pixels for free — no JavaScript per-frame repositioning, no resize-event nudging.
+
+### Requirements
+
+- The container must be `position: relative` (or any non-`static` position) so absolute children anchor to it.
+- The container should use **`transform-origin: 0 0`**. This is the standard for canvas-style apps; with any other origin, cursor positions will be shifted by the origin offset. If you need a different visual origin, pre-bake the offset into the matrix's translate component instead of changing `transform-origin`.
+- Only 2D affine transforms are supported (translate, scale, rotate, skew). 3D transforms aren't read.
+- Local-cursor proximity / visibility math, the cursor SVG icon, and `getCursorStyle` continue to work unchanged.
+
+### Example: Fridge Poetry
+
+The [`website/fridge.tsx`](https://github.com/spencerc99/playhtml/blob/main/website/fridge.tsx) demo (live at [playhtml.fun/fridge](https://playhtml.fun/fridge)) uses this pattern. Each user pans and pinch-zooms `.content` independently. With `container: ".content"`, when one user hovers the word "love," every other user sees their cursor glued to "love" in their own view, regardless of their own pan or zoom state.
+
+```tsx
+<PlayProvider
+  initOptions={{
+    cursors: {
+      enabled: true,
+      container: ".content",
+    },
+  }}
+>
+  <div className="content">
+    {/* pan/zoom transform applied here via React state */}
+    {words.map(w => <FridgeWord key={w.id} {...w} />)}
+  </div>
+</PlayProvider>
+```
+
+The transform itself (e.g. `translate(panX, panY) scale(scale)`) is applied however you like — inline `style.transform`, a CSS class, or a CSS variable. playhtml just reads it.
+
 ## Global Cursor API
 
 Cursors expose a global `window.cursors` object for accessing user presence data.

apps/docs/src/content/docs/reference/init-options.md

@@ -146,7 +146,10 @@ interface CursorOptions {
 }
 ```
 
-`container` is only needed when your framework swaps `document.body` on navigation (Astro ViewTransitions, htmx boost, Turbo). Mark the container with the framework's persist directive (e.g. `transition:persist`) and cursors survive navigation. See [navigation](/docs/advanced/navigation/) for examples.
+Set `container` for either of two reasons:
+
+1. **Surviving SPA navigation.** If your framework swaps `document.body` on route changes (Astro ViewTransitions, htmx boost, Turbo), mark the container with the framework's persist directive (e.g. `transition:persist`). See [navigation](/docs/advanced/navigation/).
+2. **Anchoring cursors to a transformed canvas.** If the container has its own CSS `transform` (pannable / zoomable wrapper), playhtml stores cursor coords in the container's local space so collaborators with different pan/zoom agree on a cursor's content position. See [Anchoring cursors to a transformed canvas](/docs/data/presence/cursors/#anchoring-cursors-to-a-transformed-canvas) and the [fridge demo](https://github.com/spencerc99/playhtml/blob/main/website/fridge.tsx).
 
 Minimal opt-in:
 

packages/playhtml/src/cursors/__tests__/cursor-transformed-container.test.ts

@@ -0,0 +1,150 @@
+// ABOUTME: Verifies cursor coords round-trip through a transformed container.
+// ABOUTME: Stubs DOMMatrixReadOnly because jsdom doesn't ship it.
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import * as Y from "yjs";
+import { CursorClientAwareness } from "../cursor-client";
+
+// Minimal DOMMatrixReadOnly polyfill for tests. Supports the affine subset
+// (translate + scale) that the fridge uses; that's all the production code
+// invokes on the matrix.
+class TestMatrix {
+  a = 1;
+  b = 0;
+  c = 0;
+  d = 1;
+  e = 0;
+  f = 0;
+  constructor(init?: string) {
+    if (!init || init === "none") return;
+    // Accept "matrix(a, b, c, d, e, f)" — the form getComputedStyle returns.
+    const match = /matrix\(([^)]+)\)/.exec(init);
+    if (match) {
+      const [a, b, c, d, e, f] = match[1].split(",").map((s) => parseFloat(s.trim()));
+      Object.assign(this, { a, b, c, d, e, f });
+      return;
+    }
+    // Accept "translate(Xpx, Ypx) scale(S)" for convenience.
+    const tx = /translate\(([-\d.]+)px,\s*([-\d.]+)px\)/.exec(init);
+    const sc = /scale\(([-\d.]+)\)/.exec(init);
+    if (tx) {
+      this.e = parseFloat(tx[1]);
+      this.f = parseFloat(tx[2]);
+    }
+    if (sc) {
+      this.a = parseFloat(sc[1]);
+      this.d = parseFloat(sc[1]);
+    }
+  }
+  inverse(): TestMatrix {
+    const m = new TestMatrix();
+    m.a = 1 / this.a;
+    m.d = 1 / this.d;
+    m.e = -this.e / this.a;
+    m.f = -this.f / this.d;
+    return m;
+  }
+  transformPoint(p: { x: number; y: number }): { x: number; y: number } {
+    return { x: this.a * p.x + this.c * p.y + this.e, y: this.b * p.x + this.d * p.y + this.f };
+  }
+}
+
+function makeFakeProvider() {
+  const doc = new Y.Doc();
+  const listeners: Array<(args: any) => void> = [];
+  const awareness: any = {
+    _states: new Map<number, Record<string, unknown>>(),
+    getStates() {
+      return this._states;
+    },
+    setLocalState() {},
+    setLocalStateField(field: string, value: unknown) {
+      const local = (this._states.get(this.clientID) as Record<string, unknown>) ?? {};
+      local[field] = value;
+      this._states.set(this.clientID, local);
+    },
+    getLocalState() {
+      return this._states.get(this.clientID) ?? null;
+    },
+    on(_event: string, cb: (args: any) => void) {
+      listeners.push(cb);
+    },
+    off() {},
+    emit(args: any) {
+      listeners.forEach((cb) => cb(args));
+    },
+    clientID: 1,
+    doc,
+  };
+  return { doc, awareness, on() {}, off() {} } as any;
+}
+
+describe("transformed cursor container", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    document.head.querySelectorAll("#playhtml-cursor-styles").forEach((n) => n.remove());
+    vi.stubGlobal("DOMMatrixReadOnly", TestMatrix);
+  });
+
+  it("client→storage→client round-trips through a translate+scale container", () => {
+    const container = document.createElement("div");
+    container.id = "fridge-content";
+    document.body.appendChild(container);
+
+    // Stub the parts of the DOM that aren't implemented in jsdom.
+    container.getBoundingClientRect = () =>
+      ({ left: 100, top: 50, width: 0, height: 0, right: 0, bottom: 0, x: 100, y: 50, toJSON() {} }) as DOMRect;
+    vi.spyOn(window, "getComputedStyle").mockImplementation(
+      () => ({ transform: "translate(20px, 30px) scale(2)" }) as CSSStyleDeclaration,
+    );
+
+    const provider = makeFakeProvider();
+    const client = new CursorClientAwareness(provider, {
+      enabled: true,
+      coordinateMode: "absolute",
+      container: "#fridge-content",
+      playerIdentity: {
+        publicKey: "pk-test",
+        playerStyle: { colorPalette: ["#ff0000"] },
+      } as any,
+    });
+
+    // Access the private helpers via the instance for the round-trip check.
+    const c2s = (client as any).clientToStorage.bind(client);
+    const s2c = (client as any).storageToClient.bind(client);
+
+    const stored = c2s(300, 200);
+    const back = s2c(stored.x, stored.y);
+    expect(back.x).toBeCloseTo(300, 5);
+    expect(back.y).toBeCloseTo(200, 5);
+
+    // Container's getBoundingClientRect already reflects its transform —
+    // rect.left = 100 means the post-transform top-left is at viewport
+    // (100, 50). Translate is already absorbed in the rect, so the inverse
+    // is purely (clientX - rect.left) / scale. With scale=2:
+    //   (300 - 100) / 2 = 100
+    //   (200 - 50) / 2  = 75
+    expect(stored.x).toBeCloseTo(100, 5);
+    expect(stored.y).toBeCloseTo(75, 5);
+
+    client.destroy();
+  });
+
+  it("falls through to default coords when the container is document.body", () => {
+    const provider = makeFakeProvider();
+    const client = new CursorClientAwareness(provider, {
+      enabled: true,
+      coordinateMode: "absolute",
+      // container undefined → resolves to document.body → identity branch
+      playerIdentity: {
+        publicKey: "pk-test-2",
+        playerStyle: { colorPalette: ["#00ff00"] },
+      } as any,
+    });
+    const c2s = (client as any).clientToStorage.bind(client);
+    const stored = c2s(500, 400);
+    // In absolute mode with no scroll/zoom, document coords == client coords.
+    expect(stored.x).toBeCloseTo(500, 5);
+    expect(stored.y).toBeCloseTo(400, 5);
+    client.destroy();
+  });
+});