@tldraw/editor 5.3.0-next.fc37bd96825b → 5.3.0

package/src/lib/utils/collaborators.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { isCursorInViewport } from './collaborators'
+
+// The viewport (page coords) all cases test against; zoom 1 so the 12/16px margins map 1:1.
+const viewport = { minX: 0, minY: 0, maxX: 100, maxY: 100 }
+
+describe('isCursorInViewport', () => {
+	it('is true for a cursor well inside the viewport', () => {
+		expect(isCursorInViewport({ x: 50, y: 50 }, viewport, 1)).toBe(true)
+	})
+
+	it('keeps a cursor just past the left/top edges (12/16px margin)', () => {
+		expect(isCursorInViewport({ x: -11, y: 50 }, viewport, 1)).toBe(true) // within 12 of left
+		expect(isCursorInViewport({ x: -13, y: 50 }, viewport, 1)).toBe(false) // past it
+		expect(isCursorInViewport({ x: 50, y: -15 }, viewport, 1)).toBe(true) // within 16 of top
+		expect(isCursorInViewport({ x: 50, y: -17 }, viewport, 1)).toBe(false) // past it
+	})
+
+	it('culls a cursor beyond the right/bottom edges', () => {
+		// Asymmetric with the left/top edges: the max checks subtract the margin rather than add
+		// it, so the cull starts *inside* the far edge (maxX - 12, maxY - 16) — a known quirk
+		// carried over from the pre-canvas implementation.
+		expect(isCursorInViewport({ x: 87, y: 50 }, viewport, 1)).toBe(true) // < maxX - 12 (88)
+		expect(isCursorInViewport({ x: 89, y: 50 }, viewport, 1)).toBe(false) // > 88, culled
+		expect(isCursorInViewport({ x: 50, y: 83 }, viewport, 1)).toBe(true) // < maxY - 16 (84)
+		expect(isCursorInViewport({ x: 50, y: 85 }, viewport, 1)).toBe(false) // > 84, culled
+	})
+
+	it('scales the margins by zoom', () => {
+		// At zoom 2 the left margin is 12/2 = 6px, so -7 is now culled where -11 survived at zoom 1.
+		expect(isCursorInViewport({ x: -5, y: 50 }, viewport, 2)).toBe(true)
+		expect(isCursorInViewport({ x: -7, y: 50 }, viewport, 2)).toBe(false)
+	})
+})

package/src/lib/utils/collaborators.ts

@@ -0,0 +1,25 @@
+import { VecLike } from '../primitives/Vec'
+
+/**
+ * Whether a collaborator's cursor (page coords) is inside the viewport, with a small margin for the
+ * cursor glyph so it isn't culled the instant its hotspot crosses the edge.
+ *
+ * Single source of truth for the cursor/hint split: the DOM cursor layer renders a collaborator
+ * when this is true, and `CollaboratorHintOverlayUtil` draws the viewport-edge hint when it's
+ * false. Sharing the predicate keeps those two exhaustive and mutually exclusive — a margin change
+ * can't open a dead zone (neither renders) or a double-render (both).
+ *
+ * @public
+ */
+export function isCursorInViewport(
+	cursor: VecLike,
+	viewport: { minX: number; minY: number; maxX: number; maxY: number },
+	zoom: number
+): boolean {
+	return !(
+		cursor.x < viewport.minX - 12 / zoom ||
+		cursor.y < viewport.minY - 16 / zoom ||
+		cursor.x > viewport.maxX - 12 / zoom ||
+		cursor.y > viewport.maxY - 16 / zoom
+	)
+}

package/src/lib/utils/getHtmlLayerTransform.ts

@@ -0,0 +1,22 @@
+import { modulate } from '@tldraw/utils'
+import type { Editor } from '../editor/Editor'
+import { toDomPrecision } from '../primitives/utils'
+
+/**
+ * The CSS `transform` that puts a 1px-sized html layer into page space under the current camera.
+ * Shared by every camera-tracked DOM layer (the canvas's shape layer, the collaborator cursor
+ * layer) so they line up exactly and can't drift apart.
+ *
+ * The offset compensates for the layer's 1px width/height when zoomed, so it registers precisely
+ * with the other layers.
+ *
+ * @internal
+ */
+export function getHtmlLayerTransform(editor: Editor): string {
+	const { x, y, z } = editor.getCamera()
+	const offset =
+		z >= 1 ? modulate(z, [1, 8], [0.125, 0.5], true) : modulate(z, [0.1, 1], [-2, 0.125], true)
+	return `scale(${toDomPrecision(z)}) translate(${toDomPrecision(x + offset)}px,${toDomPrecision(
+		y + offset
+	)}px)`
+}

package/src/version.ts

@@ -1,9 +1,9 @@
 // This file is automatically generated by internal/scripts/refresh-assets.ts.
 // Do not edit manually. Or do, I'm a comment, not a cop.
 
-export const version = '5.3.0-next.fc37bd96825b'
+export const version = '5.3.0'
 export const publishDates = {
 	major: '2026-05-06T16:28:18.473Z',
-	minor: '2026-07-22T09:05:06.008Z',
-	patch: '2026-07-22T09:05:06.008Z',
+	minor: '2026-08-05T11:39:54.978Z',
+	patch: '2026-08-05T11:39:54.978Z',
 }

package/dist-cjs/lib/hooks/usePassThroughMouseOverEvents.js

@@ -1,51 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var usePassThroughMouseOverEvents_exports = {};
-__export(usePassThroughMouseOverEvents_exports, {
-  usePassThroughMouseOverEvents: () => usePassThroughMouseOverEvents
-});
-module.exports = __toCommonJS(usePassThroughMouseOverEvents_exports);
-var import_react = require("react");
-var import_dom = require("../utils/dom");
-var import_useContainer = require("./useContainer");
-var import_useEditor = require("./useEditor");
-function usePassThroughMouseOverEvents(ref) {
-  if (!ref) throw Error("usePassThroughWheelEvents must be passed a ref");
-  const container = (0, import_useContainer.useContainer)();
-  const editor = (0, import_useEditor.useMaybeEditor)();
-  (0, import_react.useEffect)(() => {
-    function onMouseOver(e) {
-      if (!editor?.getInstanceState().isFocused) return;
-      if (e.isSpecialRedispatchedEvent) return;
-      (0, import_dom.preventDefault)(e);
-      const cvs = container.querySelector(".tl-canvas");
-      if (!cvs) return;
-      const newEvent = new PointerEvent(e.type, e);
-      newEvent.isSpecialRedispatchedEvent = true;
-      cvs.dispatchEvent(newEvent);
-    }
-    const elm = ref.current;
-    if (!elm) return;
-    elm.addEventListener("mouseover", onMouseOver, { passive: false });
-    return () => {
-      elm.removeEventListener("mouseover", onMouseOver);
-    };
-  }, [container, editor, ref]);
-}
-//# sourceMappingURL=usePassThroughMouseOverEvents.js.map

package/dist-cjs/lib/hooks/usePassThroughMouseOverEvents.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/lib/hooks/usePassThroughMouseOverEvents.ts"],
-  "sourcesContent": ["import { RefObject, useEffect } from 'react'\nimport { preventDefault } from '../utils/dom'\nimport { useContainer } from './useContainer'\nimport { useMaybeEditor } from './useEditor'\n\n/** @public */\nexport function usePassThroughMouseOverEvents(ref: RefObject<HTMLElement | null>) {\n\tif (!ref) throw Error('usePassThroughWheelEvents must be passed a ref')\n\tconst container = useContainer()\n\tconst editor = useMaybeEditor()\n\n\tuseEffect(() => {\n\t\tfunction onMouseOver(e: MouseEvent) {\n\t\t\tif (!editor?.getInstanceState().isFocused) return\n\t\t\tif ((e as any).isSpecialRedispatchedEvent) return\n\t\t\tpreventDefault(e)\n\t\t\tconst cvs = container.querySelector('.tl-canvas')\n\t\t\tif (!cvs) return\n\t\t\tconst newEvent = new PointerEvent(e.type, e as any)\n\t\t\t;(newEvent as any).isSpecialRedispatchedEvent = true\n\t\t\tcvs.dispatchEvent(newEvent)\n\t\t}\n\n\t\tconst elm = ref.current\n\t\tif (!elm) return\n\n\t\telm.addEventListener('mouseover', onMouseOver, { passive: false })\n\t\treturn () => {\n\t\t\telm.removeEventListener('mouseover', onMouseOver)\n\t\t}\n\t}, [container, editor, ref])\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAqC;AACrC,iBAA+B;AAC/B,0BAA6B;AAC7B,uBAA+B;AAGxB,SAAS,8BAA8B,KAAoC;AACjF,MAAI,CAAC,IAAK,OAAM,MAAM,gDAAgD;AACtE,QAAM,gBAAY,kCAAa;AAC/B,QAAM,aAAS,iCAAe;AAE9B,8BAAU,MAAM;AACf,aAAS,YAAY,GAAe;AACnC,UAAI,CAAC,QAAQ,iBAAiB,EAAE,UAAW;AAC3C,UAAK,EAAU,2BAA4B;AAC3C,qCAAe,CAAC;AAChB,YAAM,MAAM,UAAU,cAAc,YAAY;AAChD,UAAI,CAAC,IAAK;AACV,YAAM,WAAW,IAAI,aAAa,EAAE,MAAM,CAAQ;AACjD,MAAC,SAAiB,6BAA6B;AAChD,UAAI,cAAc,QAAQ;AAAA,IAC3B;AAEA,UAAM,MAAM,IAAI;AAChB,QAAI,CAAC,IAAK;AAEV,QAAI,iBAAiB,aAAa,aAAa,EAAE,SAAS,MAAM,CAAC;AACjE,WAAO,MAAM;AACZ,UAAI,oBAAoB,aAAa,WAAW;AAAA,IACjD;AAAA,EACD,GAAG,CAAC,WAAW,QAAQ,GAAG,CAAC;AAC5B;",
-  "names": []
-}

package/dist-esm/lib/hooks/usePassThroughMouseOverEvents.mjs

@@ -1,31 +0,0 @@
-import { useEffect } from "react";
-import { preventDefault } from "../utils/dom.mjs";
-import { useContainer } from "./useContainer.mjs";
-import { useMaybeEditor } from "./useEditor.mjs";
-function usePassThroughMouseOverEvents(ref) {
-  if (!ref) throw Error("usePassThroughWheelEvents must be passed a ref");
-  const container = useContainer();
-  const editor = useMaybeEditor();
-  useEffect(() => {
-    function onMouseOver(e) {
-      if (!editor?.getInstanceState().isFocused) return;
-      if (e.isSpecialRedispatchedEvent) return;
-      preventDefault(e);
-      const cvs = container.querySelector(".tl-canvas");
-      if (!cvs) return;
-      const newEvent = new PointerEvent(e.type, e);
-      newEvent.isSpecialRedispatchedEvent = true;
-      cvs.dispatchEvent(newEvent);
-    }
-    const elm = ref.current;
-    if (!elm) return;
-    elm.addEventListener("mouseover", onMouseOver, { passive: false });
-    return () => {
-      elm.removeEventListener("mouseover", onMouseOver);
-    };
-  }, [container, editor, ref]);
-}
-export {
-  usePassThroughMouseOverEvents
-};
-//# sourceMappingURL=usePassThroughMouseOverEvents.mjs.map

package/dist-esm/lib/hooks/usePassThroughMouseOverEvents.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/lib/hooks/usePassThroughMouseOverEvents.ts"],
-  "sourcesContent": ["import { RefObject, useEffect } from 'react'\nimport { preventDefault } from '../utils/dom'\nimport { useContainer } from './useContainer'\nimport { useMaybeEditor } from './useEditor'\n\n/** @public */\nexport function usePassThroughMouseOverEvents(ref: RefObject<HTMLElement | null>) {\n\tif (!ref) throw Error('usePassThroughWheelEvents must be passed a ref')\n\tconst container = useContainer()\n\tconst editor = useMaybeEditor()\n\n\tuseEffect(() => {\n\t\tfunction onMouseOver(e: MouseEvent) {\n\t\t\tif (!editor?.getInstanceState().isFocused) return\n\t\t\tif ((e as any).isSpecialRedispatchedEvent) return\n\t\t\tpreventDefault(e)\n\t\t\tconst cvs = container.querySelector('.tl-canvas')\n\t\t\tif (!cvs) return\n\t\t\tconst newEvent = new PointerEvent(e.type, e as any)\n\t\t\t;(newEvent as any).isSpecialRedispatchedEvent = true\n\t\t\tcvs.dispatchEvent(newEvent)\n\t\t}\n\n\t\tconst elm = ref.current\n\t\tif (!elm) return\n\n\t\telm.addEventListener('mouseover', onMouseOver, { passive: false })\n\t\treturn () => {\n\t\t\telm.removeEventListener('mouseover', onMouseOver)\n\t\t}\n\t}, [container, editor, ref])\n}\n"],
-  "mappings": "AAAA,SAAoB,iBAAiB;AACrC,SAAS,sBAAsB;AAC/B,SAAS,oBAAoB;AAC7B,SAAS,sBAAsB;AAGxB,SAAS,8BAA8B,KAAoC;AACjF,MAAI,CAAC,IAAK,OAAM,MAAM,gDAAgD;AACtE,QAAM,YAAY,aAAa;AAC/B,QAAM,SAAS,eAAe;AAE9B,YAAU,MAAM;AACf,aAAS,YAAY,GAAe;AACnC,UAAI,CAAC,QAAQ,iBAAiB,EAAE,UAAW;AAC3C,UAAK,EAAU,2BAA4B;AAC3C,qBAAe,CAAC;AAChB,YAAM,MAAM,UAAU,cAAc,YAAY;AAChD,UAAI,CAAC,IAAK;AACV,YAAM,WAAW,IAAI,aAAa,EAAE,MAAM,CAAQ;AACjD,MAAC,SAAiB,6BAA6B;AAChD,UAAI,cAAc,QAAQ;AAAA,IAC3B;AAEA,UAAM,MAAM,IAAI;AAChB,QAAI,CAAC,IAAK;AAEV,QAAI,iBAAiB,aAAa,aAAa,EAAE,SAAS,MAAM,CAAC;AACjE,WAAO,MAAM;AACZ,UAAI,oBAAoB,aAAa,WAAW;AAAA,IACjD;AAAA,EACD,GAAG,CAAC,WAAW,QAAQ,GAAG,CAAC;AAC5B;",
-  "names": []
-}

package/src/lib/hooks/usePassThroughMouseOverEvents.ts

@@ -1,32 +0,0 @@
-import { RefObject, useEffect } from 'react'
-import { preventDefault } from '../utils/dom'
-import { useContainer } from './useContainer'
-import { useMaybeEditor } from './useEditor'
-
-/** @public */
-export function usePassThroughMouseOverEvents(ref: RefObject<HTMLElement | null>) {
-	if (!ref) throw Error('usePassThroughWheelEvents must be passed a ref')
-	const container = useContainer()
-	const editor = useMaybeEditor()
-
-	useEffect(() => {
-		function onMouseOver(e: MouseEvent) {
-			if (!editor?.getInstanceState().isFocused) return
-			if ((e as any).isSpecialRedispatchedEvent) return
-			preventDefault(e)
-			const cvs = container.querySelector('.tl-canvas')
-			if (!cvs) return
-			const newEvent = new PointerEvent(e.type, e as any)
-			;(newEvent as any).isSpecialRedispatchedEvent = true
-			cvs.dispatchEvent(newEvent)
-		}
-
-		const elm = ref.current
-		if (!elm) return
-
-		elm.addEventListener('mouseover', onMouseOver, { passive: false })
-		return () => {
-			elm.removeEventListener('mouseover', onMouseOver)
-		}
-	}, [container, editor, ref])
-}