@tldraw/editor 4.6.0-canary.75bb66f25b8f → 4.6.0-canary.7ab4bb6f4099

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (302) hide show
  1. package/dist-cjs/index.d.ts +920 -112
  2. package/dist-cjs/index.js +22 -6
  3. package/dist-cjs/index.js.map +3 -3
  4. package/dist-cjs/lib/TldrawEditor.js +59 -14
  5. package/dist-cjs/lib/TldrawEditor.js.map +3 -3
  6. package/dist-cjs/lib/components/LiveCollaborators.js +1 -0
  7. package/dist-cjs/lib/components/LiveCollaborators.js.map +2 -2
  8. package/dist-cjs/lib/components/MenuClickCapture.js +99 -38
  9. package/dist-cjs/lib/components/MenuClickCapture.js.map +2 -2
  10. package/dist-cjs/lib/components/default-components/CanvasShapeIndicators.js +10 -3
  11. package/dist-cjs/lib/components/default-components/CanvasShapeIndicators.js.map +3 -3
  12. package/dist-cjs/lib/components/default-components/DefaultCanvas.js +5 -2
  13. package/dist-cjs/lib/components/default-components/DefaultCanvas.js.map +2 -2
  14. package/dist-cjs/lib/components/default-components/DefaultShapeIndicator.js +1 -1
  15. package/dist-cjs/lib/components/default-components/DefaultShapeIndicator.js.map +2 -2
  16. package/dist-cjs/lib/components/default-components/DefaultShapeIndicators.js +1 -0
  17. package/dist-cjs/lib/components/default-components/DefaultShapeIndicators.js.map +2 -2
  18. package/dist-cjs/lib/config/{createTLUser.js → createTLCurrentUser.js} +9 -9
  19. package/dist-cjs/lib/config/createTLCurrentUser.js.map +7 -0
  20. package/dist-cjs/lib/config/createTLStore.js +30 -0
  21. package/dist-cjs/lib/config/createTLStore.js.map +2 -2
  22. package/dist-cjs/lib/config/defaultAssets.js +36 -0
  23. package/dist-cjs/lib/config/defaultAssets.js.map +7 -0
  24. package/dist-cjs/lib/editor/Editor.js +389 -13
  25. package/dist-cjs/lib/editor/Editor.js.map +3 -3
  26. package/dist-cjs/lib/editor/assets/AssetUtil.js +67 -0
  27. package/dist-cjs/lib/editor/assets/AssetUtil.js.map +7 -0
  28. package/dist-cjs/lib/editor/bindings/BindingUtil.js +1 -0
  29. package/dist-cjs/lib/editor/bindings/BindingUtil.js.map +1 -1
  30. package/dist-cjs/lib/editor/managers/ClickManager/ClickManager.js +1 -0
  31. package/dist-cjs/lib/editor/managers/ClickManager/ClickManager.js.map +1 -1
  32. package/dist-cjs/lib/editor/managers/EdgeScrollManager/EdgeScrollManager.js +1 -0
  33. package/dist-cjs/lib/editor/managers/EdgeScrollManager/EdgeScrollManager.js.map +1 -1
  34. package/dist-cjs/lib/editor/managers/FocusManager/FocusManager.js +1 -0
  35. package/dist-cjs/lib/editor/managers/FocusManager/FocusManager.js.map +1 -1
  36. package/dist-cjs/lib/editor/managers/FontManager/FontManager.js +2 -0
  37. package/dist-cjs/lib/editor/managers/FontManager/FontManager.js.map +2 -2
  38. package/dist-cjs/lib/editor/managers/HistoryManager/HistoryManager.js +2 -0
  39. package/dist-cjs/lib/editor/managers/HistoryManager/HistoryManager.js.map +1 -1
  40. package/dist-cjs/lib/editor/managers/InputsManager/InputsManager.js +12 -0
  41. package/dist-cjs/lib/editor/managers/InputsManager/InputsManager.js.map +2 -2
  42. package/dist-cjs/lib/editor/managers/PerformanceManager/PerformanceApiAdapter.js +80 -0
  43. package/dist-cjs/lib/editor/managers/PerformanceManager/PerformanceApiAdapter.js.map +7 -0
  44. package/dist-cjs/lib/editor/managers/PerformanceManager/PerformanceManager.js +466 -0
  45. package/dist-cjs/lib/editor/managers/PerformanceManager/PerformanceManager.js.map +7 -0
  46. package/dist-cjs/lib/editor/managers/PerformanceManager/perf-types.js +17 -0
  47. package/dist-cjs/lib/editor/managers/PerformanceManager/perf-types.js.map +7 -0
  48. package/dist-cjs/lib/editor/managers/ScribbleManager/ScribbleManager.js +1 -0
  49. package/dist-cjs/lib/editor/managers/ScribbleManager/ScribbleManager.js.map +1 -1
  50. package/dist-cjs/lib/editor/managers/SnapManager/BoundsSnaps.js +1 -0
  51. package/dist-cjs/lib/editor/managers/SnapManager/BoundsSnaps.js.map +1 -1
  52. package/dist-cjs/lib/editor/managers/SnapManager/HandleSnaps.js +1 -0
  53. package/dist-cjs/lib/editor/managers/SnapManager/HandleSnaps.js.map +1 -1
  54. package/dist-cjs/lib/editor/managers/SnapManager/SnapManager.js +2 -1
  55. package/dist-cjs/lib/editor/managers/SnapManager/SnapManager.js.map +2 -2
  56. package/dist-cjs/lib/editor/managers/SpatialIndexManager/SpatialIndexManager.js +5 -4
  57. package/dist-cjs/lib/editor/managers/SpatialIndexManager/SpatialIndexManager.js.map +2 -2
  58. package/dist-cjs/lib/editor/managers/TextManager/TextManager.js +1 -0
  59. package/dist-cjs/lib/editor/managers/TextManager/TextManager.js.map +1 -1
  60. package/dist-cjs/lib/editor/managers/ThemeManager/ThemeManager.js +107 -0
  61. package/dist-cjs/lib/editor/managers/ThemeManager/ThemeManager.js.map +7 -0
  62. package/dist-cjs/lib/editor/managers/ThemeManager/defaultThemes.js +586 -0
  63. package/dist-cjs/lib/editor/managers/ThemeManager/defaultThemes.js.map +7 -0
  64. package/dist-cjs/lib/editor/managers/TickManager/TickManager.js +1 -0
  65. package/dist-cjs/lib/editor/managers/TickManager/TickManager.js.map +1 -1
  66. package/dist-cjs/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.js +8 -4
  67. package/dist-cjs/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.js.map +2 -2
  68. package/dist-cjs/lib/editor/shapes/BaseFrameLikeShapeUtil.js +76 -0
  69. package/dist-cjs/lib/editor/shapes/BaseFrameLikeShapeUtil.js.map +7 -0
  70. package/dist-cjs/lib/editor/shapes/ShapeUtil.js +32 -2
  71. package/dist-cjs/lib/editor/shapes/ShapeUtil.js.map +2 -2
  72. package/dist-cjs/lib/editor/shapes/group/GroupShapeUtil.js +1 -1
  73. package/dist-cjs/lib/editor/shapes/group/GroupShapeUtil.js.map +2 -2
  74. package/dist-cjs/lib/editor/shapes/shared/getPerfectDashProps.js +6 -0
  75. package/dist-cjs/lib/editor/shapes/shared/getPerfectDashProps.js.map +2 -2
  76. package/dist-cjs/lib/editor/tools/StateNode.js +15 -17
  77. package/dist-cjs/lib/editor/tools/StateNode.js.map +2 -2
  78. package/dist-cjs/lib/editor/types/SvgExportContext.js.map +2 -2
  79. package/dist-cjs/lib/editor/types/clipboard-types.js.map +1 -1
  80. package/dist-cjs/lib/editor/types/external-content.js.map +1 -1
  81. package/dist-cjs/lib/exports/ExportDelay.js +1 -0
  82. package/dist-cjs/lib/exports/ExportDelay.js.map +1 -1
  83. package/dist-cjs/lib/exports/StyleEmbedder.js +1 -0
  84. package/dist-cjs/lib/exports/StyleEmbedder.js.map +1 -1
  85. package/dist-cjs/lib/exports/getSvgJsx.js +14 -8
  86. package/dist-cjs/lib/exports/getSvgJsx.js.map +2 -2
  87. package/dist-cjs/lib/globals/environment.js +18 -1
  88. package/dist-cjs/lib/globals/environment.js.map +2 -2
  89. package/dist-cjs/lib/hooks/useCanvasEvents.js +25 -4
  90. package/dist-cjs/lib/hooks/useCanvasEvents.js.map +2 -2
  91. package/dist-cjs/lib/hooks/{useIsDarkMode.js → useColorMode.js} +14 -10
  92. package/dist-cjs/lib/hooks/useColorMode.js.map +7 -0
  93. package/dist-cjs/lib/hooks/useCursor.js +3 -7
  94. package/dist-cjs/lib/hooks/useCursor.js.map +2 -2
  95. package/dist-cjs/lib/hooks/useDarkMode.js +4 -4
  96. package/dist-cjs/lib/hooks/useDarkMode.js.map +2 -2
  97. package/dist-cjs/lib/hooks/useGestureEvents.js +171 -127
  98. package/dist-cjs/lib/hooks/useGestureEvents.js.map +3 -3
  99. package/dist-cjs/lib/options.js +5 -0
  100. package/dist-cjs/lib/options.js.map +2 -2
  101. package/dist-cjs/lib/primitives/Vec.js +3 -0
  102. package/dist-cjs/lib/primitives/Vec.js.map +1 -1
  103. package/dist-cjs/lib/primitives/geometry/Circle2d.js +1 -0
  104. package/dist-cjs/lib/primitives/geometry/Circle2d.js.map +1 -1
  105. package/dist-cjs/lib/primitives/geometry/Ellipse2d.js +1 -0
  106. package/dist-cjs/lib/primitives/geometry/Ellipse2d.js.map +1 -1
  107. package/dist-cjs/lib/primitives/geometry/Geometry2d.js +4 -1
  108. package/dist-cjs/lib/primitives/geometry/Geometry2d.js.map +2 -2
  109. package/dist-cjs/lib/primitives/geometry/Stadium2d.js +1 -0
  110. package/dist-cjs/lib/primitives/geometry/Stadium2d.js.map +1 -1
  111. package/dist-cjs/lib/utils/EditorAtom.js +2 -0
  112. package/dist-cjs/lib/utils/EditorAtom.js.map +1 -1
  113. package/dist-cjs/lib/utils/reparenting.js +2 -1
  114. package/dist-cjs/lib/utils/reparenting.js.map +2 -2
  115. package/dist-cjs/lib/utils/richText.js.map +2 -2
  116. package/dist-cjs/lib/utils/runtime.js +2 -1
  117. package/dist-cjs/lib/utils/runtime.js.map +2 -2
  118. package/dist-cjs/lib/utils/sync/TLLocalSyncClient.js +2 -0
  119. package/dist-cjs/lib/utils/sync/TLLocalSyncClient.js.map +1 -1
  120. package/dist-cjs/lib/utils/sync/hardReset.js +0 -8
  121. package/dist-cjs/lib/utils/sync/hardReset.js.map +2 -2
  122. package/dist-cjs/version.js +3 -3
  123. package/dist-cjs/version.js.map +1 -1
  124. package/dist-esm/index.d.mts +920 -112
  125. package/dist-esm/index.mjs +30 -10
  126. package/dist-esm/index.mjs.map +2 -2
  127. package/dist-esm/lib/TldrawEditor.mjs +62 -14
  128. package/dist-esm/lib/TldrawEditor.mjs.map +3 -3
  129. package/dist-esm/lib/components/LiveCollaborators.mjs +1 -0
  130. package/dist-esm/lib/components/LiveCollaborators.mjs.map +2 -2
  131. package/dist-esm/lib/components/MenuClickCapture.mjs +100 -39
  132. package/dist-esm/lib/components/MenuClickCapture.mjs.map +2 -2
  133. package/dist-esm/lib/components/default-components/CanvasShapeIndicators.mjs +10 -3
  134. package/dist-esm/lib/components/default-components/CanvasShapeIndicators.mjs.map +3 -3
  135. package/dist-esm/lib/components/default-components/DefaultCanvas.mjs +5 -2
  136. package/dist-esm/lib/components/default-components/DefaultCanvas.mjs.map +2 -2
  137. package/dist-esm/lib/components/default-components/DefaultShapeIndicator.mjs +1 -1
  138. package/dist-esm/lib/components/default-components/DefaultShapeIndicator.mjs.map +2 -2
  139. package/dist-esm/lib/components/default-components/DefaultShapeIndicators.mjs +1 -0
  140. package/dist-esm/lib/components/default-components/DefaultShapeIndicators.mjs.map +2 -2
  141. package/dist-esm/lib/config/{createTLUser.mjs → createTLCurrentUser.mjs} +6 -6
  142. package/dist-esm/lib/config/createTLCurrentUser.mjs.map +7 -0
  143. package/dist-esm/lib/config/createTLStore.mjs +36 -1
  144. package/dist-esm/lib/config/createTLStore.mjs.map +2 -2
  145. package/dist-esm/lib/config/defaultAssets.mjs +16 -0
  146. package/dist-esm/lib/config/defaultAssets.mjs.map +7 -0
  147. package/dist-esm/lib/editor/Editor.mjs +391 -13
  148. package/dist-esm/lib/editor/Editor.mjs.map +3 -3
  149. package/dist-esm/lib/editor/assets/AssetUtil.mjs +47 -0
  150. package/dist-esm/lib/editor/assets/AssetUtil.mjs.map +7 -0
  151. package/dist-esm/lib/editor/bindings/BindingUtil.mjs +1 -0
  152. package/dist-esm/lib/editor/bindings/BindingUtil.mjs.map +1 -1
  153. package/dist-esm/lib/editor/managers/ClickManager/ClickManager.mjs +1 -0
  154. package/dist-esm/lib/editor/managers/ClickManager/ClickManager.mjs.map +1 -1
  155. package/dist-esm/lib/editor/managers/EdgeScrollManager/EdgeScrollManager.mjs +1 -0
  156. package/dist-esm/lib/editor/managers/EdgeScrollManager/EdgeScrollManager.mjs.map +1 -1
  157. package/dist-esm/lib/editor/managers/FocusManager/FocusManager.mjs +1 -0
  158. package/dist-esm/lib/editor/managers/FocusManager/FocusManager.mjs.map +1 -1
  159. package/dist-esm/lib/editor/managers/FontManager/FontManager.mjs +2 -0
  160. package/dist-esm/lib/editor/managers/FontManager/FontManager.mjs.map +2 -2
  161. package/dist-esm/lib/editor/managers/HistoryManager/HistoryManager.mjs +2 -0
  162. package/dist-esm/lib/editor/managers/HistoryManager/HistoryManager.mjs.map +1 -1
  163. package/dist-esm/lib/editor/managers/InputsManager/InputsManager.mjs +12 -0
  164. package/dist-esm/lib/editor/managers/InputsManager/InputsManager.mjs.map +2 -2
  165. package/dist-esm/lib/editor/managers/PerformanceManager/PerformanceApiAdapter.mjs +60 -0
  166. package/dist-esm/lib/editor/managers/PerformanceManager/PerformanceApiAdapter.mjs.map +7 -0
  167. package/dist-esm/lib/editor/managers/PerformanceManager/PerformanceManager.mjs +438 -0
  168. package/dist-esm/lib/editor/managers/PerformanceManager/PerformanceManager.mjs.map +7 -0
  169. package/dist-esm/lib/editor/managers/PerformanceManager/perf-types.mjs +1 -0
  170. package/dist-esm/lib/editor/managers/PerformanceManager/perf-types.mjs.map +7 -0
  171. package/dist-esm/lib/editor/managers/ScribbleManager/ScribbleManager.mjs +1 -0
  172. package/dist-esm/lib/editor/managers/ScribbleManager/ScribbleManager.mjs.map +1 -1
  173. package/dist-esm/lib/editor/managers/SnapManager/BoundsSnaps.mjs +1 -0
  174. package/dist-esm/lib/editor/managers/SnapManager/BoundsSnaps.mjs.map +1 -1
  175. package/dist-esm/lib/editor/managers/SnapManager/HandleSnaps.mjs +1 -0
  176. package/dist-esm/lib/editor/managers/SnapManager/HandleSnaps.mjs.map +1 -1
  177. package/dist-esm/lib/editor/managers/SnapManager/SnapManager.mjs +2 -1
  178. package/dist-esm/lib/editor/managers/SnapManager/SnapManager.mjs.map +2 -2
  179. package/dist-esm/lib/editor/managers/SpatialIndexManager/SpatialIndexManager.mjs +5 -4
  180. package/dist-esm/lib/editor/managers/SpatialIndexManager/SpatialIndexManager.mjs.map +2 -2
  181. package/dist-esm/lib/editor/managers/TextManager/TextManager.mjs +1 -0
  182. package/dist-esm/lib/editor/managers/TextManager/TextManager.mjs.map +1 -1
  183. package/dist-esm/lib/editor/managers/ThemeManager/ThemeManager.mjs +89 -0
  184. package/dist-esm/lib/editor/managers/ThemeManager/ThemeManager.mjs.map +7 -0
  185. package/dist-esm/lib/editor/managers/ThemeManager/defaultThemes.mjs +568 -0
  186. package/dist-esm/lib/editor/managers/ThemeManager/defaultThemes.mjs.map +7 -0
  187. package/dist-esm/lib/editor/managers/TickManager/TickManager.mjs +1 -0
  188. package/dist-esm/lib/editor/managers/TickManager/TickManager.mjs.map +1 -1
  189. package/dist-esm/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.mjs +8 -4
  190. package/dist-esm/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.mjs.map +2 -2
  191. package/dist-esm/lib/editor/shapes/BaseFrameLikeShapeUtil.mjs +56 -0
  192. package/dist-esm/lib/editor/shapes/BaseFrameLikeShapeUtil.mjs.map +7 -0
  193. package/dist-esm/lib/editor/shapes/ShapeUtil.mjs +32 -2
  194. package/dist-esm/lib/editor/shapes/ShapeUtil.mjs.map +2 -2
  195. package/dist-esm/lib/editor/shapes/group/GroupShapeUtil.mjs +1 -1
  196. package/dist-esm/lib/editor/shapes/group/GroupShapeUtil.mjs.map +2 -2
  197. package/dist-esm/lib/editor/shapes/shared/getPerfectDashProps.mjs +6 -0
  198. package/dist-esm/lib/editor/shapes/shared/getPerfectDashProps.mjs.map +2 -2
  199. package/dist-esm/lib/editor/tools/StateNode.mjs +15 -17
  200. package/dist-esm/lib/editor/tools/StateNode.mjs.map +2 -2
  201. package/dist-esm/lib/editor/types/SvgExportContext.mjs.map +2 -2
  202. package/dist-esm/lib/exports/ExportDelay.mjs +1 -0
  203. package/dist-esm/lib/exports/ExportDelay.mjs.map +1 -1
  204. package/dist-esm/lib/exports/StyleEmbedder.mjs +1 -0
  205. package/dist-esm/lib/exports/StyleEmbedder.mjs.map +1 -1
  206. package/dist-esm/lib/exports/getSvgJsx.mjs +14 -11
  207. package/dist-esm/lib/exports/getSvgJsx.mjs.map +2 -2
  208. package/dist-esm/lib/globals/environment.mjs +18 -1
  209. package/dist-esm/lib/globals/environment.mjs.map +2 -2
  210. package/dist-esm/lib/hooks/useCanvasEvents.mjs +25 -4
  211. package/dist-esm/lib/hooks/useCanvasEvents.mjs.map +2 -2
  212. package/dist-esm/lib/hooks/useColorMode.mjs +19 -0
  213. package/dist-esm/lib/hooks/useColorMode.mjs.map +7 -0
  214. package/dist-esm/lib/hooks/useCursor.mjs +3 -7
  215. package/dist-esm/lib/hooks/useCursor.mjs.map +2 -2
  216. package/dist-esm/lib/hooks/useDarkMode.mjs +4 -4
  217. package/dist-esm/lib/hooks/useDarkMode.mjs.map +2 -2
  218. package/dist-esm/lib/hooks/useGestureEvents.mjs +171 -127
  219. package/dist-esm/lib/hooks/useGestureEvents.mjs.map +3 -3
  220. package/dist-esm/lib/options.mjs +5 -0
  221. package/dist-esm/lib/options.mjs.map +2 -2
  222. package/dist-esm/lib/primitives/Vec.mjs +3 -0
  223. package/dist-esm/lib/primitives/Vec.mjs.map +1 -1
  224. package/dist-esm/lib/primitives/geometry/Circle2d.mjs +1 -0
  225. package/dist-esm/lib/primitives/geometry/Circle2d.mjs.map +1 -1
  226. package/dist-esm/lib/primitives/geometry/Ellipse2d.mjs +1 -0
  227. package/dist-esm/lib/primitives/geometry/Ellipse2d.mjs.map +1 -1
  228. package/dist-esm/lib/primitives/geometry/Geometry2d.mjs +4 -1
  229. package/dist-esm/lib/primitives/geometry/Geometry2d.mjs.map +2 -2
  230. package/dist-esm/lib/primitives/geometry/Stadium2d.mjs +1 -0
  231. package/dist-esm/lib/primitives/geometry/Stadium2d.mjs.map +1 -1
  232. package/dist-esm/lib/utils/EditorAtom.mjs +2 -0
  233. package/dist-esm/lib/utils/EditorAtom.mjs.map +1 -1
  234. package/dist-esm/lib/utils/reparenting.mjs +2 -1
  235. package/dist-esm/lib/utils/reparenting.mjs.map +2 -2
  236. package/dist-esm/lib/utils/richText.mjs.map +2 -2
  237. package/dist-esm/lib/utils/runtime.mjs +2 -1
  238. package/dist-esm/lib/utils/runtime.mjs.map +2 -2
  239. package/dist-esm/lib/utils/sync/TLLocalSyncClient.mjs +2 -0
  240. package/dist-esm/lib/utils/sync/TLLocalSyncClient.mjs.map +1 -1
  241. package/dist-esm/lib/utils/sync/hardReset.mjs +0 -8
  242. package/dist-esm/lib/utils/sync/hardReset.mjs.map +2 -2
  243. package/dist-esm/version.mjs +3 -3
  244. package/dist-esm/version.mjs.map +1 -1
  245. package/editor.css +13 -37
  246. package/package.json +8 -9
  247. package/src/index.ts +36 -8
  248. package/src/lib/TldrawEditor.tsx +98 -19
  249. package/src/lib/components/LiveCollaborators.tsx +8 -2
  250. package/src/lib/components/MenuClickCapture.tsx +129 -49
  251. package/src/lib/components/default-components/CanvasShapeIndicators.tsx +14 -3
  252. package/src/lib/components/default-components/DefaultCanvas.tsx +6 -2
  253. package/src/lib/components/default-components/DefaultShapeIndicator.tsx +2 -2
  254. package/src/lib/components/default-components/DefaultShapeIndicators.tsx +2 -0
  255. package/src/lib/config/{createTLUser.ts → createTLCurrentUser.ts} +6 -6
  256. package/src/lib/config/createTLStore.ts +57 -2
  257. package/src/lib/config/defaultAssets.ts +19 -0
  258. package/src/lib/editor/Editor.ts +527 -42
  259. package/src/lib/editor/assets/AssetUtil.ts +85 -0
  260. package/src/lib/editor/managers/FontManager/FontManager.test.ts +9 -2
  261. package/src/lib/editor/managers/FontManager/FontManager.ts +1 -67
  262. package/src/lib/editor/managers/InputsManager/InputsManager.ts +12 -0
  263. package/src/lib/editor/managers/PerformanceManager/PerformanceApiAdapter.ts +82 -0
  264. package/src/lib/editor/managers/PerformanceManager/PerformanceManager.test.ts +522 -0
  265. package/src/lib/editor/managers/PerformanceManager/PerformanceManager.ts +583 -0
  266. package/src/lib/editor/managers/PerformanceManager/perf-types.ts +196 -0
  267. package/src/lib/editor/managers/SnapManager/SnapManager.test.ts +13 -2
  268. package/src/lib/editor/managers/SnapManager/SnapManager.ts +1 -1
  269. package/src/lib/editor/managers/SpatialIndexManager/SpatialIndexManager.ts +4 -4
  270. package/src/lib/editor/managers/ThemeManager/ThemeManager.ts +116 -0
  271. package/src/lib/editor/managers/ThemeManager/defaultThemes.ts +605 -0
  272. package/src/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.test.ts +25 -31
  273. package/src/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.ts +7 -5
  274. package/src/lib/editor/shapes/BaseFrameLikeShapeUtil.tsx +121 -0
  275. package/src/lib/editor/shapes/ShapeUtil.ts +50 -3
  276. package/src/lib/editor/shapes/group/GroupShapeUtil.tsx +1 -1
  277. package/src/lib/editor/shapes/shared/getPerfectDashProps.ts +7 -0
  278. package/src/lib/editor/tools/StateNode.ts +16 -18
  279. package/src/lib/editor/types/SvgExportContext.tsx +5 -0
  280. package/src/lib/editor/types/clipboard-types.ts +2 -1
  281. package/src/lib/editor/types/external-content.ts +1 -0
  282. package/src/lib/exports/getSvgJsx.tsx +23 -16
  283. package/src/lib/globals/environment.ts +18 -0
  284. package/src/lib/hooks/useCanvasEvents.ts +40 -3
  285. package/src/lib/hooks/{useIsDarkMode.ts → useColorMode.ts} +9 -5
  286. package/src/lib/hooks/useCursor.ts +3 -7
  287. package/src/lib/hooks/useDarkMode.ts +4 -4
  288. package/src/lib/hooks/useGestureEvents.ts +240 -168
  289. package/src/lib/options.ts +122 -0
  290. package/src/lib/primitives/Box.test.ts +30 -0
  291. package/src/lib/primitives/geometry/Geometry2d.test.ts +21 -0
  292. package/src/lib/primitives/geometry/Geometry2d.ts +2 -1
  293. package/src/lib/utils/reparenting.ts +6 -2
  294. package/src/lib/utils/richText.ts +1 -1
  295. package/src/lib/utils/runtime.ts +3 -1
  296. package/src/lib/utils/sync/hardReset.ts +0 -8
  297. package/src/version.ts +3 -3
  298. package/dist-cjs/lib/config/createTLUser.js.map +0 -7
  299. package/dist-cjs/lib/hooks/useIsDarkMode.js.map +0 -7
  300. package/dist-esm/lib/config/createTLUser.mjs.map +0 -7
  301. package/dist-esm/lib/hooks/useIsDarkMode.mjs +0 -15
  302. package/dist-esm/lib/hooks/useIsDarkMode.mjs.map +0 -7
@@ -1,5 +1,6 @@
1
1
  import { Atom } from '@tldraw/state';
2
2
  import { AtomSet } from '@tldraw/store';
3
+ import { Awaitable } from '@tldraw/utils';
3
4
  import { BoxModel } from '@tldraw/tlschema';
4
5
  import { ComponentType } from 'react';
5
6
  import { Computed } from '@tldraw/state';
@@ -56,9 +57,12 @@ import { TLCamera } from '@tldraw/tlschema';
56
57
  import { TLCreateShapePartial } from '@tldraw/tlschema';
57
58
  import { TLCursor } from '@tldraw/tlschema';
58
59
  import { TLCursorType } from '@tldraw/tlschema';
60
+ import { TLDefaultColor } from '@tldraw/tlschema';
61
+ import { TLDefaultColorStyle } from '@tldraw/tlschema';
59
62
  import { TLDefaultDashStyle } from '@tldraw/tlschema';
60
63
  import { TLDefaultHorizontalAlignStyle } from '@tldraw/tlschema';
61
64
  import { TLDocument } from '@tldraw/tlschema';
65
+ import { TLFontFace } from '@tldraw/tlschema';
62
66
  import { TLGroupShape } from '@tldraw/tlschema';
63
67
  import { TLHandle } from '@tldraw/tlschema';
64
68
  import { TLImageAsset } from '@tldraw/tlschema';
@@ -80,8 +84,15 @@ import { TLStore } from '@tldraw/tlschema';
80
84
  import { TLStoreProps } from '@tldraw/tlschema';
81
85
  import { TLStoreSchema } from '@tldraw/tlschema';
82
86
  import { TLStoreSnapshot } from '@tldraw/tlschema';
87
+ import { TLTheme } from '@tldraw/tlschema';
88
+ import { TLThemeColors } from '@tldraw/tlschema';
89
+ import { TLThemeId } from '@tldraw/tlschema';
90
+ import { TLThemes } from '@tldraw/tlschema';
91
+ import { TLUnknownAsset } from '@tldraw/tlschema';
83
92
  import { TLUnknownBinding } from '@tldraw/tlschema';
84
93
  import { TLUnknownShape } from '@tldraw/tlschema';
94
+ import { TLUser } from '@tldraw/tlschema';
95
+ import { TLUserStore } from '@tldraw/tlschema';
85
96
  import { TLVideoAsset } from '@tldraw/tlschema';
86
97
  import { UnknownRecord } from '@tldraw/store';
87
98
  import { VecModel } from '@tldraw/tlschema';
@@ -144,6 +155,51 @@ export declare class Arc2d extends Geometry2d {
144
155
  */
145
156
  export declare function areAnglesCompatible(a: number, b: number): boolean;
146
157
 
158
+ /**
159
+ * Abstract base class for defining asset-type-specific behavior.
160
+ *
161
+ * Each asset type (image, video, bookmark, etc.) has a corresponding AssetUtil that handles
162
+ * type-specific operations like determining supported MIME types and creating assets from files.
163
+ *
164
+ * @public
165
+ */
166
+ export declare abstract class AssetUtil<Asset extends TLAsset = TLAsset> {
167
+ editor: Editor;
168
+ /** Configure this asset util's {@link AssetUtil.options | `options`}. */
169
+ static configure<T extends TLAssetUtilConstructor<any, any>>(this: T, options: T extends new (...args: any[]) => {
170
+ options: infer Options;
171
+ } ? Partial<Options> : never): T;
172
+ constructor(editor: Editor);
173
+ /**
174
+ * Options for this asset util. Override this to provide customization options for your asset.
175
+ * Use {@link AssetUtil.configure} to customize existing asset utils.
176
+ */
177
+ options: {};
178
+ static props?: RecordProps<TLUnknownAsset>;
179
+ static migrations?: LegacyMigrations | MigrationSequence | TLPropsMigrations;
180
+ /**
181
+ * The type of the asset util, which should match the asset's type.
182
+ */
183
+ static type: string;
184
+ /**
185
+ * Get the default props for an asset of this type.
186
+ */
187
+ abstract getDefaultProps(): Asset['props'];
188
+ /**
189
+ * Get the MIME types that this asset type supports.
190
+ * Return an empty array if this asset type doesn't support files (e.g. bookmarks).
191
+ */
192
+ getSupportedMimeTypes(): readonly string[];
193
+ /**
194
+ * Check whether this asset type accepts a given MIME type.
195
+ */
196
+ acceptsMimeType(mimeType: string): boolean;
197
+ /**
198
+ * Create an asset from a file. Return null if this asset type can't handle the file.
199
+ */
200
+ getAssetFromFile(_file: File, _assetId: TLAssetId): Promise<Asset | null>;
201
+ }
202
+
147
203
  /** @public */
148
204
  export declare function average(A: VecLike, B: VecLike): string;
149
205
 
@@ -164,6 +220,54 @@ export declare abstract class BaseBoxShapeUtil<Shape extends TLBaseBoxShape> ext
164
220
  getInterpolatedProps(startShape: Shape, endShape: Shape, t: number): Shape['props'];
165
221
  }
166
222
 
223
+ /**
224
+ * A base class for frame-like shapes — containers that clip their children,
225
+ * require full-brush selection, block erasure from inside, and support
226
+ * drag-and-drop reparenting.
227
+ *
228
+ * Extending this class is the easiest way to create a custom frame-like shape.
229
+ * It provides sensible defaults for all frame-like behaviors:
230
+ *
231
+ * - `isFrameLike()` returns `true`
232
+ * - `providesBackgroundForChildren()` returns `true`
233
+ * - `canReceiveNewChildrenOfType()` returns `true` unless the container is locked
234
+ * - `getClipPath()` returns the shape geometry's vertices
235
+ * - `onDragShapesIn()` reparents shapes into the frame (with index restoration)
236
+ * - `onDragShapesOut()` reparents shapes back to the page
237
+ *
238
+ * All methods can be overridden for custom behavior.
239
+ *
240
+ * @example
241
+ * ```ts
242
+ * class MyContainerUtil extends BaseFrameLikeShapeUtil<MyContainerShape> {
243
+ * static override type = 'my-container' as const
244
+ * static override props = myContainerShapeProps
245
+ *
246
+ * override getDefaultProps() {
247
+ * return { w: 300, h: 200 }
248
+ * }
249
+ *
250
+ * override component(shape: MyContainerShape) {
251
+ * return <SVGContainer>...</SVGContainer>
252
+ * }
253
+ *
254
+ * override indicator(shape: MyContainerShape) {
255
+ * return <rect width={shape.props.w} height={shape.props.h} />
256
+ * }
257
+ * }
258
+ * ```
259
+ *
260
+ * @public
261
+ */
262
+ export declare abstract class BaseFrameLikeShapeUtil<Shape extends TLBaseBoxShape> extends BaseBoxShapeUtil<Shape> {
263
+ isFrameLike(_shape: Shape): boolean;
264
+ providesBackgroundForChildren(): boolean;
265
+ canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
266
+ getClipPath(shape: Shape): undefined | Vec[];
267
+ onDragShapesIn(shape: Shape, draggingShapes: TLShape[], { initialParentIds, initialIndices }: TLDragShapesInInfo): void;
268
+ onDragShapesOut(shape: Shape, draggingShapes: TLShape[], info: TLDragShapesOutInfo): void;
269
+ }
270
+
167
271
  /** @public */
168
272
  export declare interface BatchMeasurementRequest {
169
273
  html: string;
@@ -717,6 +821,12 @@ export declare function createDeepLinkString(deepLink: TLDeepLink): string;
717
821
  */
718
822
  export declare function createSessionStateSnapshotSignal(store: TLStore): Signal<null | TLSessionStateSnapshot>;
719
823
 
824
+ /** @public */
825
+ export declare function createTLCurrentUser(opts?: {
826
+ setUserPreferences?: ((userPreferences: TLUserPreferences) => void) | undefined;
827
+ userPreferences?: Signal<TLUserPreferences, unknown> | undefined;
828
+ }): TLCurrentUser;
829
+
720
830
  /**
721
831
  * A helper for creating a TLStore schema from either an object with shapeUtils, bindingUtils, and
722
832
  * migrations, or a schema.
@@ -734,13 +844,7 @@ export declare function createTLSchemaFromUtils(opts: TLStoreSchemaOptions): Sto
734
844
  *
735
845
  * @public
736
846
  */
737
- export declare function createTLStore({ initialData, defaultName, id, assets, onMount, collaboration, ...rest }?: TLStoreOptions): TLStore;
738
-
739
- /** @public */
740
- export declare function createTLUser(opts?: {
741
- setUserPreferences?: ((userPreferences: TLUserPreferences) => void) | undefined;
742
- userPreferences?: Signal<TLUserPreferences, unknown> | undefined;
743
- }): TLUser;
847
+ export declare function createTLStore({ initialData, defaultName, id, assets, users, onMount, collaboration, themes, ...rest }?: TLStoreOptions): TLStore;
744
848
 
745
849
  /** @public */
746
850
  export declare class CubicBezier2d extends Polyline2d {
@@ -815,6 +919,13 @@ export declare interface DebugFlagDefaults<T> {
815
919
 
816
920
  /* Excluded from this release type: DEFAULT_CAMERA_OPTIONS */
817
921
 
922
+ /**
923
+ * The default theme definition containing color palettes for both light and dark modes.
924
+ *
925
+ * @public
926
+ */
927
+ export declare const DEFAULT_THEME: TLTheme;
928
+
818
929
  /** @public @react */
819
930
  export declare function DefaultBackground(): JSX.Element;
820
931
 
@@ -929,7 +1040,11 @@ export declare const defaultTldrawOptions: {
929
1040
  readonly maxShapesPerPage: 4000;
930
1041
  readonly multiClickDurationMs: 200;
931
1042
  readonly nonce: undefined;
1043
+ readonly onBeforeCopyToClipboard: undefined;
1044
+ readonly onBeforePasteFromClipboard: undefined;
1045
+ readonly onClipboardPasteRaw: undefined;
932
1046
  readonly quickZoomPreservesScreenBounds: true;
1047
+ readonly rightClickPanning: true;
933
1048
  readonly snapThreshold: 8;
934
1049
  readonly spacebarPanning: true;
935
1050
  readonly temporaryAssetPreviewLifetimeMs: 180000;
@@ -938,6 +1053,7 @@ export declare const defaultTldrawOptions: {
938
1053
  readonly tooltipDelayMs: 700;
939
1054
  readonly uiCoarseDragDistanceSquared: 625;
940
1055
  readonly uiDragDistanceSquared: 16;
1056
+ readonly useCanvasIndicators: true;
941
1057
  readonly zoomToFitPadding: 128;
942
1058
  };
943
1059
 
@@ -959,6 +1075,9 @@ export declare const defaultUserPreferences: Readonly<{
959
1075
  name: "";
960
1076
  }>;
961
1077
 
1078
+ /** @public */
1079
+ export declare const defaultUserStore: TLUserStore;
1080
+
962
1081
  /**
963
1082
  * Convert degrees to radians.
964
1083
  *
@@ -1034,7 +1153,7 @@ export declare class EdgeScrollManager {
1034
1153
  /** @public */
1035
1154
  export declare class Editor extends EventEmitter<TLEventMap> {
1036
1155
  readonly id: string;
1037
- constructor({ store, user, shapeUtils, bindingUtils, tools, getContainer, cameraOptions, initialState, autoFocus, inferDarkMode, options: _options, textOptions: _textOptions, getShapeVisibility, fontAssetUrls }: TLEditorOptions);
1156
+ constructor({ store, user, shapeUtils, bindingUtils, assetUtils: assetUtilConstructors, tools, getContainer, cameraOptions, initialState, autoFocus, options: _options, textOptions: _textOptions, getShapeVisibility, colorScheme, fontAssetUrls, themes, initialTheme }: TLEditorOptions);
1038
1157
  private readonly _getShapeVisibility?;
1039
1158
  private getIsShapeHiddenCache;
1040
1159
  isShapeHidden(shapeOrId: TLShape | TLShapeId): boolean;
@@ -1097,7 +1216,13 @@ export declare class Editor extends EventEmitter<TLEventMap> {
1097
1216
  * @public
1098
1217
  */
1099
1218
  readonly snaps: SnapManager;
1100
- private readonly _spatialIndex;
1219
+ /**
1220
+ * A manager for performance measurement hooks.
1221
+ *
1222
+ * @public
1223
+ */
1224
+ readonly performance: PerformanceManager;
1225
+ /* Excluded from this release type: _spatialIndex */
1101
1226
  /**
1102
1227
  * A manager for the any asynchronous events and making sure they're
1103
1228
  * cleaned up upon disposal.
@@ -1116,6 +1241,7 @@ export declare class Editor extends EventEmitter<TLEventMap> {
1116
1241
  * @public
1117
1242
  */
1118
1243
  readonly user: UserPreferencesManager;
1244
+ /* Excluded from this release type: _themeManager */
1119
1245
  /**
1120
1246
  * A helper for measuring text.
1121
1247
  *
@@ -1166,6 +1292,83 @@ export declare class Editor extends EventEmitter<TLEventMap> {
1166
1292
  * @public
1167
1293
  */
1168
1294
  dispose(): void;
1295
+ /**
1296
+ * Get the current color mode (`'light'` or `'dark'`), based on the user's dark mode preference.
1297
+ *
1298
+ * @public
1299
+ */
1300
+ getColorMode(): 'dark' | 'light';
1301
+ /**
1302
+ * Set the color mode. Note that this is a convenience method that passes the mode to
1303
+ * `user.updateUserPreferences`, which is the source of truth for the user's color mode preference.
1304
+ *
1305
+ * @public
1306
+ */
1307
+ setColorMode(mode: 'dark' | 'light'): this;
1308
+ /**
1309
+ * Get the id of the current theme.
1310
+ *
1311
+ * @public
1312
+ */
1313
+ getCurrentThemeId(): TLThemeId;
1314
+ /**
1315
+ * Get the current theme definition.
1316
+ *
1317
+ * @public
1318
+ */
1319
+ getCurrentTheme(): TLTheme;
1320
+ /**
1321
+ * Set the current theme by id.
1322
+ *
1323
+ * @public
1324
+ */
1325
+ setCurrentTheme(id: TLThemeId): this;
1326
+ /**
1327
+ * Get all registered theme definitions.
1328
+ *
1329
+ * @public
1330
+ */
1331
+ getThemes(): TLThemes;
1332
+ /**
1333
+ * Get a single theme definition by id.
1334
+ *
1335
+ * @public
1336
+ */
1337
+ getTheme(id: TLThemeId): TLTheme | undefined;
1338
+ /**
1339
+ * Replace all theme definitions, or update them via a callback that receives a deep copy.
1340
+ * The `'default'` theme must always be present in the result.
1341
+ *
1342
+ * @example
1343
+ * ```ts
1344
+ * // Replace all themes
1345
+ * editor.updateThemes({ default: myDefaultTheme, ocean: myOceanTheme })
1346
+ *
1347
+ * // Update via callback
1348
+ * editor.updateThemes((themes) => {
1349
+ * delete themes.ocean
1350
+ * return themes
1351
+ * })
1352
+ * ```
1353
+ *
1354
+ * @public
1355
+ */
1356
+ updateThemes(themes: ((themes: TLThemes) => TLThemes) | TLThemes): this;
1357
+ /**
1358
+ * Register or update a single theme definition. The theme is keyed by its `id` property.
1359
+ *
1360
+ * @example
1361
+ * ```ts
1362
+ * // Override a property on the default theme
1363
+ * editor.updateTheme({ ...editor.getTheme('default')!, fontSize: 24 })
1364
+ *
1365
+ * // Register a new theme
1366
+ * editor.updateTheme({ id: 'ocean', ...myOceanTheme })
1367
+ * ```
1368
+ *
1369
+ * @public
1370
+ */
1371
+ updateTheme(theme: TLTheme): this;
1169
1372
  /**
1170
1373
  * A map of shape utility classes (TLShapeUtils) by shape type.
1171
1374
  *
@@ -1174,6 +1377,7 @@ export declare class Editor extends EventEmitter<TLEventMap> {
1174
1377
  shapeUtils: {
1175
1378
  readonly [K in string]?: ShapeUtil<TLShape>;
1176
1379
  };
1380
+ /* Excluded from this release type: _shapeUtilsByAssetType */
1177
1381
  styleProps: {
1178
1382
  [key: string]: Map<StyleProp<any>, string>;
1179
1383
  };
@@ -1205,6 +1409,15 @@ export declare class Editor extends EventEmitter<TLEventMap> {
1205
1409
  hasShapeUtil(shape: TLShape | TLShapePartial<TLShape>): boolean;
1206
1410
  hasShapeUtil(type: TLShape['type']): boolean;
1207
1411
  hasShapeUtil<T extends ShapeUtil>(type: T extends ShapeUtil<infer R> ? R['type'] : string): boolean;
1412
+ /**
1413
+ * Get the shape util that handles the given asset type.
1414
+ * Returns the shape util whose {@link ShapeUtil.handledAssetTypes} includes
1415
+ * the given asset type, or undefined if none matches.
1416
+ *
1417
+ * @param assetType - The asset type string.
1418
+ * @public
1419
+ */
1420
+ getShapeUtilForAssetType(assetType: string): ShapeUtil | undefined;
1208
1421
  /**
1209
1422
  * A map of shape utility classes (TLShapeUtils) by shape type.
1210
1423
  *
@@ -1235,6 +1448,40 @@ export declare class Editor extends EventEmitter<TLEventMap> {
1235
1448
  type: S['type'];
1236
1449
  } | S): BindingUtil<S>;
1237
1450
  getBindingUtil<T extends BindingUtil>(type: T extends BindingUtil<infer R> ? R['type'] : string): T;
1451
+ /**
1452
+ * A map of asset utility classes by asset type.
1453
+ *
1454
+ * @public
1455
+ */
1456
+ assetUtils: {
1457
+ readonly [K in string]?: AssetUtil<TLAsset>;
1458
+ };
1459
+ /**
1460
+ * Get an asset util from an asset or asset type.
1461
+ *
1462
+ * @param arg - An asset, asset type string, or object with type.
1463
+ *
1464
+ * @public
1465
+ */
1466
+ getAssetUtil<S extends TLAsset>(asset: {
1467
+ type: S['type'];
1468
+ } | S): AssetUtil<S>;
1469
+ getAssetUtil(type: string): AssetUtil;
1470
+ /**
1471
+ * Returns true if the editor has an asset util for the given asset type.
1472
+ *
1473
+ * @public
1474
+ */
1475
+ hasAssetUtil(arg: {
1476
+ type: string;
1477
+ } | string): boolean;
1478
+ /**
1479
+ * Get the asset util that accepts the given MIME type.
1480
+ * Returns null if no registered asset util accepts the MIME type.
1481
+ *
1482
+ * @public
1483
+ */
1484
+ getAssetUtilForMimeType(mimeType: string): AssetUtil | null;
1238
1485
  /**
1239
1486
  * A manager for the editor's history.
1240
1487
  *
@@ -2265,6 +2512,32 @@ export declare class Editor extends EventEmitter<TLEventMap> {
2265
2512
  * @public
2266
2513
  */
2267
2514
  getCollaboratorsOnCurrentPage(): TLInstancePresence[];
2515
+ /**
2516
+ * Get the current user's ID for attribution purposes.
2517
+ * Also ensures a `user:` record exists in the store for the current user.
2518
+ * Returns `null` when the user store has no current user.
2519
+ *
2520
+ * @public
2521
+ */
2522
+ getAttributionUserId(): null | string;
2523
+ /* Excluded from this release type: _ensureUserRecord */
2524
+ /**
2525
+ * Resolve a display name for a user ID. Asks the
2526
+ * {@link @tldraw/tlschema#TLUserStore} first (the app's source of truth),
2527
+ * falling back to the `user:` record in the store.
2528
+ *
2529
+ * @public
2530
+ */
2531
+ getAttributionDisplayName(userId: null | string): null | string;
2532
+ /**
2533
+ * Resolve a user record by ID. Asks the
2534
+ * {@link @tldraw/tlschema#TLUserStore} first (the app's source of truth),
2535
+ * falling back to the `user:` record in the store.
2536
+ *
2537
+ * @public
2538
+ */
2539
+ getAttributionUser(userId: null | string): null | TLUser;
2540
+ /* Excluded from this release type: _getReferencedUserIds */
2268
2541
  private _isLockedOnFollowingUser;
2269
2542
  /**
2270
2543
  * Start viewport-following a user.
@@ -2899,6 +3172,20 @@ export declare class Editor extends EventEmitter<TLEventMap> {
2899
3172
  type: T['type'];
2900
3173
  }>;
2901
3174
  isShapeOfType<T extends TLShape = TLShape>(shapeId: TLShapeId, type: T['type']): boolean;
3175
+ /**
3176
+ * Get whether a shape behaves like a frame — a container that has child
3177
+ * shapes, requires full-brush selection, blocks erasure from inside, etc.
3178
+ *
3179
+ * @example
3180
+ * ```ts
3181
+ * const isFrameLike = editor.isShapeFrameLike(someShape)
3182
+ * ```
3183
+ *
3184
+ * @param shape - The shape (or shape id) to test.
3185
+ *
3186
+ * @public
3187
+ */
3188
+ isShapeFrameLike(shape: TLShape | TLShapeId): boolean;
2902
3189
  /**
2903
3190
  * Get a shape by its id.
2904
3191
  *
@@ -4359,6 +4646,35 @@ export declare interface Geometry2dOptions extends TransformedGeometry2dOptions
4359
4646
  */
4360
4647
  export declare function getArcMeasure(A: number, B: number, sweepFlag: number, largeArcFlag: number): number;
4361
4648
 
4649
+ /**
4650
+ * Resolves a color style value to its actual CSS color string for a given theme and variant.
4651
+ * If the color is not a default theme color, returns the color value as-is.
4652
+ *
4653
+ * @param colors - The color palette for the current color mode (e.g. `theme.colors[colorMode]`)
4654
+ * @param color - The color style value to resolve
4655
+ * @param variant - Which variant of the color to return (solid, fill, pattern, etc.)
4656
+ * @returns The CSS color string for the specified color and variant
4657
+ *
4658
+ * @example
4659
+ * ```ts
4660
+ * import { getColorValue } from 'tldraw'
4661
+ *
4662
+ * const colors = editor.getCurrentTheme().colors[editor.getColorMode()]
4663
+ *
4664
+ * // Get the solid variant of red
4665
+ * const redSolid = getColorValue(colors, 'red', 'solid') // '#e03131'
4666
+ *
4667
+ * // Get the fill variant of blue
4668
+ * const blueFill = getColorValue(colors, 'blue', 'fill') // '#4465e9'
4669
+ *
4670
+ * // Custom color passes through unchanged
4671
+ * const customColor = getColorValue(colors, '#ff0000', 'solid') // '#ff0000'
4672
+ * ```
4673
+ *
4674
+ * @public
4675
+ */
4676
+ export declare function getColorValue(colors: TLThemeColors, color: string | TLDefaultColorStyle, variant: keyof TLDefaultColor): string;
4677
+
4362
4678
  /** @public */
4363
4679
  export declare function getCursor(cursor: TLCursorType, rotation?: number, color?: string): string;
4364
4680
 
@@ -4529,7 +4845,7 @@ export declare class GroupShapeUtil extends ShapeUtil<TLGroupShape> {
4529
4845
  static type: "group";
4530
4846
  static props: RecordProps<TLGroupShape>;
4531
4847
  static migrations: TLPropsMigrations;
4532
- hideSelectionBoundsFg(): boolean;
4848
+ hideSelectionBoundsFg(shape: TLGroupShape): boolean;
4533
4849
  canBind(): boolean;
4534
4850
  canResize(): boolean;
4535
4851
  canResizeChildren(): boolean;
@@ -4815,6 +5131,12 @@ export declare class InputsManager {
4815
5131
  get isPointing(): boolean;
4816
5132
  set isPointing(isPointing: boolean);
4817
5133
  /* Excluded from this release type: setIsPointing */
5134
+ private _isRightPointing;
5135
+ /**
5136
+ * Whether the user is right-click pointing (before drag threshold).
5137
+ */
5138
+ getIsRightPointing(): boolean;
5139
+ /* Excluded from this release type: setIsRightPointing */
4818
5140
  private _isPinching;
4819
5141
  /**
4820
5142
  * Whether the user is pinching.
@@ -5171,6 +5493,94 @@ export declare function parseDeepLinkString(deepLinkString: string): TLDeepLink;
5171
5493
  /** @public */
5172
5494
  export declare type PerfectDashTerminal = 'none' | 'outset' | 'skip';
5173
5495
 
5496
+ /**
5497
+ * Optional adapter that pipes PerformanceManager events into browser
5498
+ * `performance.mark()` / `performance.measure()` for DevTools integration.
5499
+ *
5500
+ * Tree-shakeable — only included if imported.
5501
+ *
5502
+ * @example
5503
+ * ```ts
5504
+ * const adapter = new PerformanceApiAdapter(editor.performance)
5505
+ * // ... later
5506
+ * adapter.dispose()
5507
+ * ```
5508
+ *
5509
+ * @public
5510
+ */
5511
+ export declare class PerformanceApiAdapter {
5512
+ private cleanups;
5513
+ constructor(perfManager: PerformanceManager);
5514
+ /** Remove all listeners and stop piping events. @public */
5515
+ dispose(): void;
5516
+ }
5517
+
5518
+ /**
5519
+ * Manages performance event subscriptions for the editor. Available as `editor.performance`.
5520
+ *
5521
+ * Listeners are lazy — internal editor hooks (frame, shape events) are only attached while
5522
+ * at least one subscriber exists, so there is zero overhead when unused.
5523
+ *
5524
+ * @example
5525
+ * ```ts
5526
+ * const unsub = editor.performance.on('interaction-end', (event) => {
5527
+ * console.log(`${event.name}: ${event.fps.toFixed(1)} fps, p95=${event.p95FrameTime.toFixed(1)}ms`)
5528
+ * })
5529
+ * ```
5530
+ *
5531
+ * @public
5532
+ */
5533
+ export declare class PerformanceManager {
5534
+ /* Excluded from this release type: emitter */
5535
+ private editor;
5536
+ private activeInteraction;
5537
+ private activeCamera;
5538
+ private frameCleanup;
5539
+ private shapeCreatedCleanup;
5540
+ private shapeEditedCleanup;
5541
+ private shapeDeletedCleanup;
5542
+ private loafObserver;
5543
+ constructor(editor: Editor);
5544
+ /**
5545
+ * Subscribe to a performance event. Returns an unsubscribe function.
5546
+ *
5547
+ * @example
5548
+ * ```ts
5549
+ * const unsub = editor.performance.on('interaction-end', (event) => {
5550
+ * sendToAnalytics({ name: event.name, fps: event.fps, p95: event.p95FrameTime })
5551
+ * })
5552
+ * // later: unsub()
5553
+ * ```
5554
+ *
5555
+ * @public
5556
+ */
5557
+ on<K extends keyof TLPerfEventMap>(event: K, fn: (...args: TLPerfEventMap[K]) => void): () => void;
5558
+ /**
5559
+ * Subscribe to a performance event once. The listener is removed after the first invocation.
5560
+ * Returns an unsubscribe function for early removal.
5561
+ *
5562
+ * @public
5563
+ */
5564
+ once<K extends keyof TLPerfEventMap>(event: K, fn: (...args: TLPerfEventMap[K]) => void): () => void;
5565
+ /* Excluded from this release type: dispose */
5566
+ /* Excluded from this release type: _notifyInteractionStart */
5567
+ /* Excluded from this release type: _notifyInteractionEnd */
5568
+ /* Excluded from this release type: _notifyCameraOperation */
5569
+ /* Excluded from this release type: _notifyUndoRedo */
5570
+ private _startCameraSession;
5571
+ private _endCameraSession;
5572
+ private _onFrame;
5573
+ private _onShapesCreated;
5574
+ private _onShapesEdited;
5575
+ private _onShapesDeleted;
5576
+ private _startLoafObserver;
5577
+ private _stopLoafObserver;
5578
+ private _needsFrameListener;
5579
+ private _needsLoafObserver;
5580
+ private _maybeAttachLazyListeners;
5581
+ private _maybeDetachLazyListeners;
5582
+ }
5583
+
5174
5584
  /**
5175
5585
  * Find the approximate perimeter of an ellipse.
5176
5586
  *
@@ -5365,6 +5775,16 @@ export declare function resizeScaled(shape: TLBaseShape<any, {
5365
5775
  y: number;
5366
5776
  };
5367
5777
 
5778
+ /**
5779
+ * Resolve a partial set of user-provided themes into a complete `TLThemes`
5780
+ * record by merging with `DEFAULT_THEME`. The result is suitable for passing to
5781
+ * `registerColorsFromThemes`, `registerFontsFromThemes`, and the
5782
+ * `ThemeManager` constructor.
5783
+ *
5784
+ * @public
5785
+ */
5786
+ export declare function resolveThemes(themes?: Partial<TLThemes>): TLThemes;
5787
+
5368
5788
  /** @public */
5369
5789
  export declare type RichTextFontVisitor = (node: TiptapNode, state: RichTextFontVisitorState, addFont: (font: TLFontFace) => void) => RichTextFontVisitorState;
5370
5790
 
@@ -5646,12 +6066,32 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
5646
6066
  * @public
5647
6067
  */
5648
6068
  static type: string;
6069
+ /**
6070
+ * The asset types that this shape can be created from.
6071
+ * When a file is dropped on the canvas, the editor finds the shape util
6072
+ * whose `handledAssetTypes` includes the asset's type and calls
6073
+ * {@link ShapeUtil.createShapeForAsset} to produce the shape.
6074
+ *
6075
+ * @public
6076
+ */
6077
+ static handledAssetTypes?: readonly string[];
5649
6078
  /**
5650
6079
  * Get the default props for a shape.
5651
6080
  *
5652
6081
  * @public
5653
6082
  */
5654
6083
  abstract getDefaultProps(): Shape['props'];
6084
+ /**
6085
+ * Create a shape partial for placing an asset on the canvas.
6086
+ * Only called for shapes whose constructor declares matching
6087
+ * {@link ShapeUtil.handledAssetTypes | `handledAssetTypes`}.
6088
+ *
6089
+ * @param asset - The asset to create a shape for.
6090
+ * @param position - Where to place the shape.
6091
+ * @returns A shape partial, or null if this shape can't be created for the asset.
6092
+ * @public
6093
+ */
6094
+ createShapeForAsset?(asset: TLAsset, position: VecModel): null | TLShapePartial;
5655
6095
  /**
5656
6096
  * Get the shape's geometry.
5657
6097
  *
@@ -5732,7 +6172,7 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
5732
6172
  *
5733
6173
  * @public
5734
6174
  */
5735
- canBind(_opts: TLShapeUtilCanBindOpts): boolean;
6175
+ canBind(opts: TLShapeUtilCanBindOpts): boolean;
5736
6176
  /**
5737
6177
  * Whether the shape can be double clicked to edit.
5738
6178
  *
@@ -5866,6 +6306,14 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
5866
6306
  * @public
5867
6307
  */
5868
6308
  isAspectRatioLocked(shape: Shape): boolean;
6309
+ /**
6310
+ * Whether the shape behaves like a frame — a container that has child shapes,
6311
+ * requires full-brush selection, blocks erasure from inside, etc.
6312
+ *
6313
+ * @param shape - The shape.
6314
+ * @public
6315
+ */
6316
+ isFrameLike(_shape: Shape): boolean;
5869
6317
  /**
5870
6318
  * By default, the bounds of an image export are the bounds of all the shapes it contains, plus
5871
6319
  * some padding. If an export includes a shape where `isExportBoundsContainer` is true, then the
@@ -5913,7 +6361,7 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
5913
6361
  * @param type - The shape type.
5914
6362
  * @public
5915
6363
  */
5916
- canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
6364
+ canReceiveNewChildrenOfType(shape: Shape, type: TLShape['type']): boolean;
5917
6365
  /**
5918
6366
  * Get the shape as an SVG object.
5919
6367
  *
@@ -5953,6 +6401,14 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
5953
6401
  */
5954
6402
  getHandleSnapGeometry(shape: Shape): HandleSnapGeometry;
5955
6403
  getText(shape: Shape): string | undefined;
6404
+ /**
6405
+ * Return user IDs referenced in shape-specific props.
6406
+ * Used when copying shapes to include referenced users on the clipboard.
6407
+ * Override this if your shape stores user IDs in custom props.
6408
+ *
6409
+ * @public
6410
+ */
6411
+ getReferencedUserIds(shape: Shape): string[];
5956
6412
  getAriaDescriptor(shape: Shape): string | undefined;
5957
6413
  /**
5958
6414
  * A callback called just before a shape is created. This method provides a last chance to modify
@@ -6348,6 +6804,8 @@ export declare abstract class StateNode implements Partial<TLEventHandlers> {
6348
6804
  static children?: () => TLStateNodeConstructor[];
6349
6805
  static isLockable: boolean;
6350
6806
  static useCoalescedEvents: boolean;
6807
+ /** Set to `true` in subclasses to emit interaction-start/end performance events when this state is entered/exited. */
6808
+ static trackPerformance: boolean;
6351
6809
  id: string;
6352
6810
  type: 'branch' | 'leaf' | 'root';
6353
6811
  shapeType?: string;
@@ -6482,6 +6940,10 @@ export declare interface SvgExportContext {
6482
6940
  * Whether the export should be in dark mode.
6483
6941
  */
6484
6942
  readonly isDarkMode: boolean;
6943
+ /**
6944
+ * The color mode to use for this export.
6945
+ */
6946
+ readonly colorMode: 'dark' | 'light';
6485
6947
  /**
6486
6948
  * The scale of the export - how much CSS pixels will be scaled up/down by.
6487
6949
  */
@@ -6552,6 +7014,47 @@ export declare class TextManager {
6552
7014
  }[];
6553
7015
  }
6554
7016
 
7017
+ /**
7018
+ * Manages the editor's color themes.
7019
+ *
7020
+ * Stores named theme definitions (each containing light and dark color palettes
7021
+ * alongside shared properties like font size). The current theme is resolved by
7022
+ * combining the current theme name with the user's color mode preference.
7023
+ *
7024
+ * **Terminology:**
7025
+ * - **Theme** (`TLTheme`): A named set of colors and typographic values for both light and dark modes.
7026
+ * - **Color mode** (`'light' | 'dark'`): The resolved appearance mode, derived from the user's
7027
+ * `colorScheme` preference (`'light' | 'dark' | 'system'`). Access via `getColorMode()`.
7028
+ *
7029
+ * @public
7030
+ */
7031
+ export declare class ThemeManager {
7032
+ private readonly editor;
7033
+ private readonly _themes;
7034
+ private readonly _currentThemeId;
7035
+ constructor(editor: Editor, options: {
7036
+ initial: TLThemeId;
7037
+ themes: TLThemes;
7038
+ });
7039
+ /** Get the current color mode based on the user's dark mode preference. */
7040
+ getColorMode(): 'dark' | 'light';
7041
+ /** Get all registered theme definitions. */
7042
+ getThemes(): TLThemes;
7043
+ /** Get a single theme definition by id. */
7044
+ getTheme(id: TLThemeId): TLTheme | undefined;
7045
+ /** Get the id of the current theme. */
7046
+ getCurrentThemeId(): TLThemeId;
7047
+ getCurrentTheme(): TLTheme;
7048
+ /** Set the current theme by id. The theme must have been previously registered. */
7049
+ setCurrentTheme(id: TLThemeId): void;
7050
+ /** Replace all theme definitions, or update them via a callback that receives a deep copy. */
7051
+ updateThemes(themes: ((themes: TLThemes) => TLThemes) | TLThemes): void;
7052
+ /** Register or update a named theme definition. */
7053
+ updateTheme(theme: TLTheme): void;
7054
+ /** Clean up any resources held by the manager. */
7055
+ dispose(): void;
7056
+ }
7057
+
6555
7058
  /* Excluded from this release type: TickManager */
6556
7059
 
6557
7060
  /**
@@ -6570,12 +7073,23 @@ export declare type TiptapNode = Node_2;
6570
7073
  /** @public */
6571
7074
  export declare type TLAdjacentDirection = 'down' | 'left' | 'next' | 'prev' | 'right' | 'up';
6572
7075
 
7076
+ /** @public */
7077
+ export declare type TLAnyAssetUtilConstructor = TLAssetUtilConstructor<any>;
7078
+
6573
7079
  /** @public */
6574
7080
  export declare type TLAnyBindingUtilConstructor = TLBindingUtilConstructor<any>;
6575
7081
 
6576
7082
  /** @public */
6577
7083
  export declare type TLAnyShapeUtilConstructor = TLShapeUtilConstructor<any>;
6578
7084
 
7085
+ /** @public */
7086
+ export declare interface TLAssetUtilConstructor<T extends TLAsset = TLAsset, U extends AssetUtil<T> = AssetUtil<T>> {
7087
+ new (editor: Editor): U;
7088
+ type: T['type'];
7089
+ props?: RecordProps<T>;
7090
+ migrations?: LegacyMigrations | MigrationSequence | TLPropsMigrations;
7091
+ }
7092
+
6579
7093
  /** @public */
6580
7094
  export declare type TLBaseBoxShape = ExtractShapeByProps<{
6581
7095
  h: number;
@@ -6665,6 +7179,29 @@ export declare interface TLCameraConstraints {
6665
7179
  };
6666
7180
  }
6667
7181
 
7182
+ /**
7183
+ * Emitted when a camera operation ends (after a 50ms debounce), with aggregated frame time stats.
7184
+ * @public
7185
+ */
7186
+ export declare interface TLCameraEndPerfEvent extends TLPerfFrameTimeStats {
7187
+ /** Whether this was a pan or zoom operation. */
7188
+ type: 'panning' | 'zooming';
7189
+ /** Total shapes on the current page. */
7190
+ shapeCount: number;
7191
+ /** Number of shapes visible (not culled) in the viewport. */
7192
+ visibleShapeCount: number;
7193
+ /** Number of shapes culled (off-screen) from rendering. */
7194
+ culledShapeCount: number;
7195
+ /** Viewport width in screen pixels. */
7196
+ viewportWidth: number;
7197
+ /** Viewport height in screen pixels. */
7198
+ viewportHeight: number;
7199
+ /** Camera zoom level (`camera.z`) at session end. */
7200
+ zoomLevel: number;
7201
+ /** `performance.now()` when the camera session ended. */
7202
+ timestamp: number;
7203
+ }
7204
+
6668
7205
  /** @public */
6669
7206
  export declare interface TLCameraMoveOptions {
6670
7207
  /** Whether to move the camera immediately, rather than on the next tick. */
@@ -6703,6 +7240,17 @@ export declare interface TLCameraOptions {
6703
7240
  constraints?: TLCameraConstraints;
6704
7241
  }
6705
7242
 
7243
+ /**
7244
+ * Emitted when a camera operation (pan or zoom) begins.
7245
+ * @public
7246
+ */
7247
+ export declare interface TLCameraStartPerfEvent {
7248
+ /** Whether this is a pan or zoom operation. */
7249
+ type: 'panning' | 'zooming';
7250
+ /** `performance.now()` when the camera session started. */
7251
+ timestamp: number;
7252
+ }
7253
+
6706
7254
  /** @public */
6707
7255
  export declare type TLCancelEvent = (info: TLCancelEventInfo) => void;
6708
7256
 
@@ -6736,6 +7284,40 @@ export declare type TLCLickEventName = 'double_click' | 'quadruple_click' | 'tri
6736
7284
  /** @public */
6737
7285
  export declare type TLClickState = 'idle' | 'overflow' | 'pendingDouble' | 'pendingOverflow' | 'pendingQuadruple' | 'pendingTriple';
6738
7286
 
7287
+ /**
7288
+ * Raw clipboard paste payload, before tldraw parses clipboard contents into {@link TLExternalContent}.
7289
+ *
7290
+ * - `native-event`: from the `paste` event — `clipboardData` is available synchronously (unlike async
7291
+ * `navigator.clipboard.read()`).
7292
+ * - `clipboard-read`: from an explicit `navigator.clipboard.read()` call — only `ClipboardItem[]`
7293
+ * exists
7294
+ * (no `DataTransfer`).
7295
+ *
7296
+ * @public
7297
+ */
7298
+ export declare type TLClipboardPasteRawInfo = {
7299
+ readonly clipboardData: DataTransfer | null;
7300
+ readonly editor: Editor;
7301
+ readonly event: ClipboardEvent;
7302
+ readonly point: undefined | VecLike;
7303
+ readonly source: 'native-event';
7304
+ } | {
7305
+ readonly clipboardItems: readonly ClipboardItem[];
7306
+ readonly editor: Editor;
7307
+ readonly point: undefined | VecLike;
7308
+ readonly source: 'clipboard-read';
7309
+ };
7310
+
7311
+ /**
7312
+ * Identifies how a clipboard write was triggered (copy vs cut, keyboard vs menu).
7313
+ *
7314
+ * @public
7315
+ */
7316
+ export declare interface TLClipboardWriteInfo {
7317
+ readonly operation: 'copy' | 'cut';
7318
+ readonly source: 'menu' | 'native';
7319
+ }
7320
+
6739
7321
  /** @public */
6740
7322
  export declare interface TLCollaboratorHintProps {
6741
7323
  userId: string;
@@ -6763,6 +7345,7 @@ export declare interface TLContent {
6763
7345
  rootShapeIds: TLShapeId[];
6764
7346
  assets: TLAsset[];
6765
7347
  schema: SerializedSchema;
7348
+ users?: TLUser[];
6766
7349
  }
6767
7350
 
6768
7351
  /**
@@ -6784,6 +7367,12 @@ export declare interface TLCropInfo<T extends TLShape> {
6784
7367
  aspectRatioLocked?: boolean;
6785
7368
  }
6786
7369
 
7370
+ /** @public */
7371
+ export declare interface TLCurrentUser {
7372
+ readonly userPreferences: Signal<TLUserPreferences>;
7373
+ readonly setUserPreferences: (userPreferences: TLUserPreferences) => void;
7374
+ }
7375
+
6787
7376
  /** @public */
6788
7377
  export declare interface TLCursorProps {
6789
7378
  userId: string;
@@ -6884,6 +7473,10 @@ export declare interface TldrawEditorBaseProps {
6884
7473
  * An array of binding utils to use in the editor.
6885
7474
  */
6886
7475
  bindingUtils?: readonly TLAnyBindingUtilConstructor[];
7476
+ /**
7477
+ * An array of asset utils to use in the editor.
7478
+ */
7479
+ assetUtils?: readonly TLAnyAssetUtilConstructor[];
6887
7480
  /**
6888
7481
  * An array of tools to add to the editor's state chart.
6889
7482
  */
@@ -6911,11 +7504,23 @@ export declare interface TldrawEditorBaseProps {
6911
7504
  /**
6912
7505
  * The user interacting with the editor.
6913
7506
  */
6914
- user?: TLUser;
7507
+ user?: TLCurrentUser;
7508
+ /**
7509
+ * The editor's color scheme. Defaults to `'light'`.
7510
+ *
7511
+ * - `'light'` - Always use light mode.
7512
+ * - `'dark'` - Always use dark mode.
7513
+ * - `'system'` - Follow the OS color scheme preference.
7514
+ */
7515
+ colorScheme?: 'dark' | 'light' | 'system';
7516
+ /**
7517
+ * Named themes for the editor.
7518
+ */
7519
+ themes?: Partial<TLThemes>;
6915
7520
  /**
6916
- * Whether to infer dark mode from the user's OS. Defaults to false.
7521
+ * The id of the initially active theme. Defaults to `'default'`.
6917
7522
  */
6918
- inferDarkMode?: boolean;
7523
+ initialTheme?: TLThemeId;
6919
7524
  /**
6920
7525
  * Camera options for the editor.
6921
7526
  *
@@ -7133,6 +7738,12 @@ export declare interface TldrawOptions {
7133
7738
  * When false, the spacebar will not pan the camera.
7134
7739
  */
7135
7740
  readonly spacebarPanning: boolean;
7741
+ /**
7742
+ * Whether to allow right-click + drag to pan the camera. When true, right-click + drag pans the
7743
+ * camera and a static right-click opens the context menu at the release position. When false,
7744
+ * right-click opens the context menu on press (no drag-to-pan).
7745
+ */
7746
+ readonly rightClickPanning: boolean;
7136
7747
  /**
7137
7748
  * The default padding (in pixels) used when zooming to fit content in the viewport.
7138
7749
  * This affects methods like `zoomToFit()`, `zoomToSelection()`, and `zoomToBounds()`.
@@ -7175,6 +7786,78 @@ export declare interface TldrawOptions {
7175
7786
  * viewport's page dimensions regardless of overview zoom changes.
7176
7787
  */
7177
7788
  readonly quickZoomPreservesScreenBounds: boolean;
7789
+ /**
7790
+ * Whether to use 2D canvas rendering for shape indicators. When true (default),
7791
+ * shapes that support it will render indicators on a 2D canvas for better
7792
+ * performance. When false, all indicators use legacy SVG rendering.
7793
+ */
7794
+ readonly useCanvasIndicators: boolean;
7795
+ /**
7796
+ * Called before content is written to the clipboard during a copy or cut operation.
7797
+ * Receives the serialized content (shapes, bindings, assets) and can filter or transform
7798
+ * it before it reaches the clipboard.
7799
+ *
7800
+ * Return a modified `TLContent` object to change what is copied or cut. Return `false` to
7801
+ * cancel the clipboard write (for cut, the selected shapes are not removed). Return `void`
7802
+ * (or `undefined`) to pass through unchanged. You may return a `Promise` of those values if
7803
+ * the hook is async.
7804
+ *
7805
+ * @example
7806
+ * ```tsx
7807
+ * // Filter out "locked" shapes from copy
7808
+ * onBeforeCopyToClipboard({ content, operation }) {
7809
+ * return {
7810
+ * ...content,
7811
+ * shapes: content.shapes.filter(s => !s.meta.locked),
7812
+ * rootShapeIds: content.rootShapeIds.filter(id =>
7813
+ * content.shapes.find(s => s.id === id && !s.meta.locked)
7814
+ * ),
7815
+ * }
7816
+ * }
7817
+ * ```
7818
+ */
7819
+ onBeforeCopyToClipboard?(info: {
7820
+ content: TLContent;
7821
+ editor: Editor;
7822
+ } & TLClipboardWriteInfo): Awaitable<false | TLContent | void>;
7823
+ /**
7824
+ * Called before pasted content is processed and shapes are created. Receives the parsed
7825
+ * external content from the clipboard and can filter, transform, or cancel it.
7826
+ *
7827
+ * Return `false` to cancel the paste. Return a modified content object to transform it.
7828
+ * Return `void` (or `undefined`) to pass through unchanged. You may return a `Promise` of
7829
+ * those values if the hook is async.
7830
+ *
7831
+ * This only fires for clipboard paste operations (keyboard shortcuts and menu actions),
7832
+ * not for file drops or programmatic `putExternalContent` calls.
7833
+ *
7834
+ * @example
7835
+ * ```tsx
7836
+ * // Block pasting of image files
7837
+ * onBeforePasteFromClipboard({ content }) {
7838
+ * if (content.type === 'files') {
7839
+ * const nonImages = content.files.filter(f => !f.type.startsWith('image/'))
7840
+ * if (nonImages.length === 0) return false
7841
+ * return { ...content, files: nonImages }
7842
+ * }
7843
+ * }
7844
+ * ```
7845
+ */
7846
+ onBeforePasteFromClipboard?(info: {
7847
+ content: TLExternalContent<unknown>;
7848
+ editor: Editor;
7849
+ point?: VecLike;
7850
+ source: 'clipboard-read' | 'native-event';
7851
+ }): Awaitable<false | TLExternalContent<unknown> | void>;
7852
+ /**
7853
+ * Called first for keyboard and menu paste, **before** tldraw handles or parses clipboard data
7854
+ * (and before {@link TldrawOptions.onBeforePasteFromClipboard}).
7855
+ *
7856
+ * Return `false` to cancel tldraw's default paste handling for this gesture (same convention as
7857
+ * {@link TldrawOptions.onBeforePasteFromClipboard}). Use this when you handle paste yourself from
7858
+ * raw clipboard data, or to block the gesture entirely. Return `void` (or `undefined`) to continue.
7859
+ */
7860
+ onClipboardPasteRaw?(info: TLClipboardPasteRawInfo): false | void;
7178
7861
  /**
7179
7862
  * Called when content is dropped on the canvas. Provides the page position
7180
7863
  * where the drop occurred and the underlying drag event object.
@@ -7242,18 +7925,17 @@ export declare interface TLEditorOptions {
7242
7925
  */
7243
7926
  bindingUtils: readonly TLAnyBindingUtilConstructor[];
7244
7927
  /**
7245
- * An array of tools to use in the editor. These will be used to handle events and manage user interactions in the editor.
7928
+ * An array of asset utils to use in the editor. These will be used to handle asset-type-specific behavior.
7246
7929
  */
7247
- tools: readonly TLStateNodeConstructor[];
7930
+ assetUtils?: readonly TLAnyAssetUtilConstructor[];
7248
7931
  /**
7249
- * Should return a containing html element which has all the styles applied to the editor. If not
7250
- * given, the body element will be used.
7932
+ * An array of tools to use in the editor. These will be used to handle events and manage user interactions in the editor.
7251
7933
  */
7252
- getContainer(): HTMLElement;
7934
+ tools: readonly TLStateNodeConstructor[];
7253
7935
  /**
7254
7936
  * A user defined externally to replace the default user.
7255
7937
  */
7256
- user?: TLUser;
7938
+ user?: TLCurrentUser;
7257
7939
  /**
7258
7940
  * The editor's initial active tool (or other state node id).
7259
7941
  */
@@ -7262,27 +7944,15 @@ export declare interface TLEditorOptions {
7262
7944
  * Whether to automatically focus the editor when it mounts.
7263
7945
  */
7264
7946
  autoFocus?: boolean;
7265
- /**
7266
- * Whether to infer dark mode from the user's system preferences. Defaults to false.
7267
- */
7268
- inferDarkMode?: boolean;
7269
- /**
7270
- * Options for the editor's camera.
7271
- *
7272
- * @deprecated Use `options.cameraOptions` instead. This will be removed in a future release.
7273
- */
7274
- cameraOptions?: Partial<TLCameraOptions>;
7275
- options?: Partial<TldrawOptions>;
7276
- /**
7277
- * Text options for the editor.
7278
- *
7279
- * @deprecated Use `options.text` instead. This prop will be removed in a future release.
7280
- */
7281
- textOptions?: TLTextOptions;
7282
7947
  licenseKey?: string;
7283
7948
  fontAssetUrls?: {
7284
7949
  [key: string]: string | undefined;
7285
7950
  };
7951
+ /**
7952
+ * Should return a containing html element which has all the styles applied to the editor. If not
7953
+ * given, the body element will be used.
7954
+ */
7955
+ getContainer(): HTMLElement;
7286
7956
  /**
7287
7957
  * Provides a way to hide shapes.
7288
7958
  *
@@ -7299,6 +7969,40 @@ export declare interface TLEditorOptions {
7299
7969
  * @param editor - The editor instance.
7300
7970
  */
7301
7971
  getShapeVisibility?(shape: TLShape, editor: Editor): 'hidden' | 'inherit' | 'visible' | null | undefined;
7972
+ /**
7973
+ * Named theme definitions for the editor. Each theme contains shared
7974
+ * properties (font size, line height, stroke width) and color palettes
7975
+ * for both light and dark modes.
7976
+ */
7977
+ themes?: Partial<TLThemes>;
7978
+ /**
7979
+ * The id of the initially active theme. Defaults to `'default'`.
7980
+ */
7981
+ initialTheme?: TLThemeId;
7982
+ /**
7983
+ * The editor's color scheme preference, controls the default color mode. Defaults to `'light'`.
7984
+ *
7985
+ * - `'light'` - Always use light mode.
7986
+ * - `'dark'` - Always use dark mode.
7987
+ * - `'system'` - Follow the OS color scheme preference.
7988
+ */
7989
+ colorScheme?: 'dark' | 'light' | 'system';
7990
+ /**
7991
+ * Additional configuration options for the tldraw editor.
7992
+ */
7993
+ options?: Partial<TldrawOptions>;
7994
+ /**
7995
+ * Options for the editor's camera.
7996
+ *
7997
+ * @deprecated Use `options.cameraOptions` instead. This will be removed in a future release.
7998
+ */
7999
+ cameraOptions?: Partial<TLCameraOptions>;
8000
+ /**
8001
+ * Text options for the editor.
8002
+ *
8003
+ * @deprecated Use `options.text` instead. This prop will be removed in a future release.
8004
+ */
8005
+ textOptions?: TLTextOptions;
7302
8006
  }
7303
8007
 
7304
8008
  /**
@@ -7357,6 +8061,7 @@ export declare const tlenv: {
7357
8061
  */
7358
8062
  export declare const tlenvReactive: Atom< {
7359
8063
  isCoarsePointer: boolean;
8064
+ supportsP3ColorSpace: boolean;
7360
8065
  }, unknown>;
7361
8066
 
7362
8067
  /** @public */
@@ -7485,6 +8190,7 @@ export declare interface TLFileReplaceExternalContent extends TLBaseExternalCont
7485
8190
  type: 'file-replace';
7486
8191
  file: File;
7487
8192
  shapeId: TLShapeId;
8193
+ /** @deprecated This field is no longer used by the default handler. It may be removed in a future version. */
7488
8194
  isImage: boolean;
7489
8195
  }
7490
8196
 
@@ -7496,69 +8202,18 @@ export declare interface TLFilesExternalContent extends TLBaseExternalContent {
7496
8202
  }
7497
8203
 
7498
8204
  /**
7499
- * A font face that can be used in the editor. The properties of this are largely the same as the
7500
- * ones in the
7501
- * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face | css `@font-face` rule}.
7502
- * @public
7503
- */
7504
- export declare interface TLFontFace {
7505
- /**
7506
- * How this font can be referred to in CSS.
7507
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family | `font-family`}.
7508
- */
7509
- readonly family: string;
7510
- /**
7511
- * The source of the font. This
7512
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`}.
7513
- */
7514
- readonly src: TLFontFaceSource;
7515
- /**
7516
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override | `ascent-override`}.
7517
- */
7518
- readonly ascentOverride?: string;
7519
- /**
7520
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override | `descent-override`}.
7521
- */
7522
- readonly descentOverride?: string;
7523
- /**
7524
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch | `font-stretch`}.
7525
- */
7526
- readonly stretch?: string;
7527
- /**
7528
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style | `font-style`}.
7529
- */
7530
- readonly style?: string;
7531
- /**
7532
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight | `font-weight`}.
7533
- */
7534
- readonly weight?: string;
7535
- /**
7536
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-feature-settings | `font-feature-settings`}.
7537
- */
7538
- readonly featureSettings?: string;
7539
- /**
7540
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/line-gap-override | `line-gap-override`}.
7541
- */
7542
- readonly lineGapOverride?: string;
7543
- /**
7544
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range | `unicode-range`}.
7545
- */
7546
- readonly unicodeRange?: string;
7547
- }
7548
-
7549
- /**
7550
- * Represents the `src` property of a {@link TLFontFace}.
7551
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`} for details of the properties here.
8205
+ * Emitted every animation frame when at least one `'frame'` listener is registered.
7552
8206
  * @public
7553
8207
  */
7554
- export declare interface TLFontFaceSource {
7555
- /**
7556
- * A URL from which to load the font. If the value here is a key in
7557
- * {@link tldraw#TLEditorAssetUrls.fonts}, the value from there will be used instead.
7558
- */
7559
- url: string;
7560
- format?: string;
7561
- tech?: string;
8208
+ export declare interface TLFramePerfEvent {
8209
+ /** Time since the last frame in ms. */
8210
+ elapsed: number;
8211
+ /** Total shapes on the current page. */
8212
+ shapeCount: number;
8213
+ /** Number of shapes culled (off-screen) from rendering. */
8214
+ culledShapeCount: number;
8215
+ /** Number of shapes visible (not culled) in the viewport. */
8216
+ visibleShapeCount: number;
7562
8217
  }
7563
8218
 
7564
8219
  /** Additional options for the {@link ShapeUtil.getGeometry} method.
@@ -7703,6 +8358,38 @@ export declare type TLIndicatorPath = {
7703
8358
  path: Path2D;
7704
8359
  } | Path2D;
7705
8360
 
8361
+ /**
8362
+ * Emitted when an interaction state is exited, with aggregated frame time stats.
8363
+ * @public
8364
+ */
8365
+ export declare interface TLInteractionEndPerfEvent extends TLPerfFrameTimeStats {
8366
+ /** The state node id (e.g. `'translating'`). */
8367
+ name: string;
8368
+ /** Full tool path (e.g. `'select.translating'`). */
8369
+ path: string;
8370
+ /** Total shapes on the current page. */
8371
+ shapeCount: number;
8372
+ /** Breakdown of selected shape types at interaction start (e.g. `{ geo: 2, draw: 1 }`). */
8373
+ selectedShapeTypes: Record<string, number>;
8374
+ /** Camera zoom level (`camera.z`) at interaction end. */
8375
+ zoomLevel: number;
8376
+ /** `performance.now()` when the interaction ended. */
8377
+ timestamp: number;
8378
+ }
8379
+
8380
+ /**
8381
+ * Emitted when an interaction state (e.g. translating, resizing) is entered.
8382
+ * @public
8383
+ */
8384
+ export declare interface TLInteractionStartPerfEvent {
8385
+ /** The state node id (e.g. `'translating'`). */
8386
+ name: string;
8387
+ /** Full tool path (e.g. `'select.translating'`). */
8388
+ path: string;
8389
+ /** `performance.now()` when the interaction started. */
8390
+ timestamp: number;
8391
+ }
8392
+
7706
8393
  /** @public */
7707
8394
  export declare type TLInterruptEvent = (info: TLInterruptEventInfo) => void;
7708
8395
 
@@ -7950,6 +8637,94 @@ export declare const tlmenus: {
7950
8637
  */
7951
8638
  export declare type TLOnMountHandler = (editor: Editor) => (() => undefined | void) | undefined | void;
7952
8639
 
8640
+ /**
8641
+ * Map of all performance event names to their payload types.
8642
+ * Used with {@link PerformanceManager.on} and {@link PerformanceManager.once}.
8643
+ * @public
8644
+ */
8645
+ export declare interface TLPerfEventMap {
8646
+ /** An interaction state was entered. */
8647
+ 'interaction-start': [TLInteractionStartPerfEvent];
8648
+ /** An interaction state was exited, with aggregated frame time stats. */
8649
+ 'interaction-end': [TLInteractionEndPerfEvent];
8650
+ /** A camera operation (pan/zoom) began. */
8651
+ 'camera-start': [TLCameraStartPerfEvent];
8652
+ /** A camera operation ended (after debounce), with aggregated frame time stats. */
8653
+ 'camera-end': [TLCameraEndPerfEvent];
8654
+ /** Shapes were created. */
8655
+ 'shapes-created': [TLShapeOperationPerfEvent];
8656
+ /** Shapes were updated. */
8657
+ 'shapes-updated': [TLShapeOperationPerfEvent];
8658
+ /** Shapes were deleted. */
8659
+ 'shapes-deleted': [TLShapeOperationPerfEvent];
8660
+ /** An animation frame was rendered. Only fires when listeners are registered. */
8661
+ frame: [TLFramePerfEvent];
8662
+ /** An undo operation was performed. */
8663
+ undo: [TLUndoRedoPerfEvent];
8664
+ /** A redo operation was performed. */
8665
+ redo: [TLUndoRedoPerfEvent];
8666
+ }
8667
+
8668
+ /**
8669
+ * Common frame time statistics shared by interaction and camera end events.
8670
+ * @public
8671
+ */
8672
+ export declare interface TLPerfFrameTimeStats {
8673
+ /** Total duration of the session in ms. */
8674
+ duration: number;
8675
+ /** Average frames per second during the session. */
8676
+ fps: number;
8677
+ /** Total number of frames recorded. */
8678
+ frameCount: number;
8679
+ /** Mean frame duration in ms. */
8680
+ avgFrameTime: number;
8681
+ /** Median (p50) frame duration in ms. */
8682
+ medianFrameTime: number;
8683
+ /** 95th percentile frame duration in ms. */
8684
+ p95FrameTime: number;
8685
+ /** 99th percentile frame duration in ms. */
8686
+ p99FrameTime: number;
8687
+ /** Shortest frame duration in ms. */
8688
+ minFrameTime: number;
8689
+ /** Longest frame duration in ms. */
8690
+ maxFrameTime: number;
8691
+ /** Raw frame durations for local analysis. Exclude when sending to analytics. */
8692
+ frameTimes: number[];
8693
+ /**
8694
+ * Long animation frames observed during this period (Chromium 123+).
8695
+ * Only present when the browser supports the Long Animation Frames API and
8696
+ * at least one long frame was observed.
8697
+ * Exclude when sending to analytics — entries are large and contain script URLs.
8698
+ */
8699
+ longAnimationFrames?: TLPerfLongAnimationFrame[];
8700
+ }
8701
+
8702
+ /**
8703
+ * A long animation frame observed by the browser during an interaction.
8704
+ * Available only in browsers that support the Long Animation Frames API (Chromium 123+).
8705
+ * @public
8706
+ */
8707
+ export declare interface TLPerfLongAnimationFrame {
8708
+ /** Frame start time (relative to timeOrigin). */
8709
+ startTime: number;
8710
+ /** Total frame duration in ms. */
8711
+ duration: number;
8712
+ /** Time the main thread was blocked in ms. */
8713
+ blockingDuration: number;
8714
+ /** Scripts that contributed to the long frame. */
8715
+ scripts: TLPerfLongAnimationFrameScript[];
8716
+ }
8717
+
8718
+ /** A script attribution entry from a long animation frame. @public */
8719
+ export declare interface TLPerfLongAnimationFrameScript {
8720
+ /** The script source URL (may be empty for inline scripts). */
8721
+ sourceURL: string;
8722
+ /** The function name or invoker description. */
8723
+ invoker: string;
8724
+ /** Time spent in this script in ms. */
8725
+ duration: number;
8726
+ }
8727
+
7953
8728
  /** @public */
7954
8729
  export declare type TLPinchEvent = (info: TLPinchEventInfo) => void;
7955
8730
 
@@ -8137,6 +8912,21 @@ export declare interface TLShapeIndicatorsProps {
8137
8912
  showAll?: boolean;
8138
8913
  }
8139
8914
 
8915
+ /**
8916
+ * Emitted when shapes are created, updated, or deleted.
8917
+ * @public
8918
+ */
8919
+ export declare interface TLShapeOperationPerfEvent {
8920
+ /** The operation type. */
8921
+ operation: 'create' | 'delete' | 'update';
8922
+ /** Number of shapes affected. */
8923
+ count: number;
8924
+ /** Breakdown by shape type (e.g. `{ geo: 2, draw: 1 }`). */
8925
+ shapeTypes: Record<string, number>;
8926
+ /** `performance.now()` when the operation occurred. */
8927
+ timestamp: number;
8928
+ }
8929
+
8140
8930
  /**
8141
8931
  * Options passed to {@link ShapeUtil.canBeLaidOut}.
8142
8932
  *
@@ -8194,6 +8984,7 @@ export declare interface TLShapeUtilConstructor<T extends TLShape, U extends Sha
8194
8984
  type: T['type'];
8195
8985
  props?: RecordProps<T>;
8196
8986
  migrations?: LegacyMigrations | MigrationSequence | TLPropsMigrations;
8987
+ handledAssetTypes?: readonly string[];
8197
8988
  }
8198
8989
 
8199
8990
  /** @public */
@@ -8221,6 +9012,7 @@ export declare interface TLStateNodeConstructor {
8221
9012
  children?(): TLStateNodeConstructor[];
8222
9013
  isLockable: boolean;
8223
9014
  useCoalescedEvents: boolean;
9015
+ trackPerformance: boolean;
8224
9016
  }
8225
9017
 
8226
9018
  /** @public */
@@ -8233,6 +9025,14 @@ export declare interface TLStoreBaseOptions {
8233
9025
  defaultName?: string;
8234
9026
  /** How should this store upload & resolve assets? */
8235
9027
  assets?: TLAssetStore;
9028
+ /**
9029
+ * Named theme definitions. When provided, custom color names are automatically
9030
+ * registered before the store is constructed so persisted data with those
9031
+ * colors passes validation on load.
9032
+ */
9033
+ themes?: Partial<TLThemes>;
9034
+ /** How should this store resolve users for attribution? */
9035
+ users?: TLUserStore;
8236
9036
  /** Called when the store is connected to an {@link @tldraw/editor#Editor}. */
8237
9037
  onMount?(editor: Editor): (() => void) | void;
8238
9038
  }
@@ -8252,6 +9052,7 @@ export declare type TLStoreOptions = TLStoreBaseOptions & {
8252
9052
 
8253
9053
  /** @public */
8254
9054
  export declare type TLStoreSchemaOptions = {
9055
+ assetUtils?: readonly TLAnyAssetUtilConstructor[];
8255
9056
  bindingUtils?: readonly TLAnyBindingUtilConstructor[];
8256
9057
  migrations?: readonly MigrationSequence[];
8257
9058
  records?: Record<string, CustomRecordInfo>;
@@ -8389,6 +9190,19 @@ export declare interface TLTldrawExternalContentSource {
8389
9190
  data: TLContent;
8390
9191
  }
8391
9192
 
9193
+ /**
9194
+ * Emitted after an undo or redo operation.
9195
+ * @public
9196
+ */
9197
+ export declare interface TLUndoRedoPerfEvent {
9198
+ /** Whether this was an undo or redo. */
9199
+ type: 'redo' | 'undo';
9200
+ /** Number of undo steps remaining. */
9201
+ undoDepth: number;
9202
+ /** Number of redo steps remaining. */
9203
+ redoDepth: number;
9204
+ }
9205
+
8392
9206
  /** @public */
8393
9207
  export declare interface TLUpdatePointerOptions {
8394
9208
  /** Whether to update the pointer immediately, rather than on the next tick. */
@@ -8420,12 +9234,6 @@ export declare interface TLUrlExternalContent extends TLBaseExternalContent {
8420
9234
  url: string;
8421
9235
  }
8422
9236
 
8423
- /** @public */
8424
- export declare interface TLUser {
8425
- readonly userPreferences: Signal<TLUserPreferences>;
8426
- readonly setUserPreferences: (userPreferences: TLUserPreferences) => void;
8427
- }
8428
-
8429
9237
  /**
8430
9238
  * A user of tldraw
8431
9239
  *
@@ -8526,6 +9334,9 @@ export declare function uniq<T>(array: {
8526
9334
  readonly length: number;
8527
9335
  } | null | undefined): T[];
8528
9336
 
9337
+ /** @public */
9338
+ export declare function useColorMode(): 'dark' | 'light';
9339
+
8529
9340
  /** @public */
8530
9341
  export declare function useContainer(): HTMLElement;
8531
9342
 
@@ -8564,9 +9375,6 @@ export declare function useGlobalMenuIsOpen(id: string, onChange?: (isOpen: bool
8564
9375
  /** @public */
8565
9376
  export declare function useIsCropping(shapeId: TLShapeId): boolean;
8566
9377
 
8567
- /** @public */
8568
- export declare function useIsDarkMode(): boolean;
8569
-
8570
9378
  /** @public */
8571
9379
  export declare function useIsEditing(shapeId: TLShapeId): boolean;
8572
9380
 
@@ -8604,11 +9412,11 @@ export declare function usePresence(userId: string): null | TLInstancePresence;
8604
9412
  /** @public */
8605
9413
  export declare class UserPreferencesManager {
8606
9414
  private readonly user;
8607
- private readonly inferDarkMode;
9415
+ private readonly colorScheme;
8608
9416
  systemColorScheme: Atom<"dark" | "light", unknown>;
8609
9417
  disposables: Set<() => void>;
8610
9418
  dispose(): void;
8611
- constructor(user: TLUser, inferDarkMode: boolean);
9419
+ constructor(user: TLCurrentUser, colorScheme: 'dark' | 'light' | 'system');
8612
9420
  updateUserPreferences(userPreferences: Partial<TLUserPreferences>): void;
8613
9421
  getUserPreferences(): {
8614
9422
  animationSpeed: number;
@@ -8679,10 +9487,10 @@ export declare function useSvgExportContext(): null | SvgExportContext;
8679
9487
  /**
8680
9488
  * @public
8681
9489
  */
8682
- export declare function useTldrawUser(opts: {
9490
+ export declare function useTldrawCurrentUser(opts: {
8683
9491
  setUserPreferences?: (userPreferences: TLUserPreferences) => void;
8684
9492
  userPreferences?: Signal<TLUserPreferences> | TLUserPreferences;
8685
- }): TLUser;
9493
+ }): TLCurrentUser;
8686
9494
 
8687
9495
  /** @public */
8688
9496
  export declare function useTLSchemaFromUtils(opts: TLStoreSchemaOptions): StoreSchema<TLRecord, TLStoreProps>;