@tldraw/editor 4.6.0-canary.ab4e1d4fd85b → 4.6.0-canary.abd30e51f1f3

package/dist-cjs/index.d.ts

@@ -220,6 +220,54 @@ export declare abstract class BaseBoxShapeUtil<Shape extends TLBaseBoxShape> ext
     getInterpolatedProps(startShape: Shape, endShape: Shape, t: number): Shape['props'];
 }
 
+/**
+ * A base class for frame-like shapes — containers that clip their children,
+ * require full-brush selection, block erasure from inside, and support
+ * drag-and-drop reparenting.
+ *
+ * Extending this class is the easiest way to create a custom frame-like shape.
+ * It provides sensible defaults for all frame-like behaviors:
+ *
+ * - `isFrameLike()` returns `true`
+ * - `providesBackgroundForChildren()` returns `true`
+ * - `canReceiveNewChildrenOfType()` returns `true` unless the container is locked
+ * - `getClipPath()` returns the shape geometry's vertices
+ * - `onDragShapesIn()` reparents shapes into the frame (with index restoration)
+ * - `onDragShapesOut()` reparents shapes back to the page
+ *
+ * All methods can be overridden for custom behavior.
+ *
+ * @example
+ * ```ts
+ * class MyContainerUtil extends BaseFrameLikeShapeUtil<MyContainerShape> {
+ *   static override type = 'my-container' as const
+ *   static override props = myContainerShapeProps
+ *
+ *   override getDefaultProps() {
+ *     return { w: 300, h: 200 }
+ *   }
+ *
+ *   override component(shape: MyContainerShape) {
+ *     return <SVGContainer>...</SVGContainer>
+ *   }
+ *
+ *   override indicator(shape: MyContainerShape) {
+ *     return <rect width={shape.props.w} height={shape.props.h} />
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class BaseFrameLikeShapeUtil<Shape extends TLBaseBoxShape> extends BaseBoxShapeUtil<Shape> {
+    isFrameLike(_shape: Shape): boolean;
+    providesBackgroundForChildren(): boolean;
+    canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
+    getClipPath(shape: Shape): undefined | Vec[];
+    onDragShapesIn(shape: Shape, draggingShapes: TLShape[], { initialParentIds, initialIndices }: TLDragShapesInInfo): void;
+    onDragShapesOut(shape: Shape, draggingShapes: TLShape[], info: TLDragShapesOutInfo): void;
+}
+
 /** @public */
 export declare interface BatchMeasurementRequest {
     html: string;
@@ -996,6 +1044,7 @@ export declare const defaultTldrawOptions: {
     readonly onBeforePasteFromClipboard: undefined;
     readonly onClipboardPasteRaw: undefined;
     readonly quickZoomPreservesScreenBounds: true;
+    readonly rightClickPanning: true;
     readonly snapThreshold: 8;
     readonly spacebarPanning: true;
     readonly temporaryAssetPreviewLifetimeMs: 180000;
@@ -1004,6 +1053,7 @@ export declare const defaultTldrawOptions: {
     readonly tooltipDelayMs: 700;
     readonly uiCoarseDragDistanceSquared: 625;
     readonly uiDragDistanceSquared: 16;
+    readonly useCanvasIndicators: true;
     readonly zoomToFitPadding: 128;
 };
 
@@ -1166,6 +1216,12 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @public
      */
     readonly snaps: SnapManager;
+    /**
+     * A manager for performance measurement hooks.
+     *
+     * @public
+     */
+    readonly performance: PerformanceManager;
     /* Excluded from this release type: _spatialIndex */
     /**
      * A manager for the any asynchronous events and making sure they're
@@ -3116,6 +3172,20 @@ export declare class Editor extends EventEmitter<TLEventMap> {
         type: T['type'];
     }>;
     isShapeOfType<T extends TLShape = TLShape>(shapeId: TLShapeId, type: T['type']): boolean;
+    /**
+     * Get whether a shape behaves like a frame — a container that has child
+     * shapes, requires full-brush selection, blocks erasure from inside, etc.
+     *
+     * @example
+     * ```ts
+     * const isFrameLike = editor.isShapeFrameLike(someShape)
+     * ```
+     *
+     * @param shape - The shape (or shape id) to test.
+     *
+     * @public
+     */
+    isShapeFrameLike(shape: TLShape | TLShapeId): boolean;
     /**
      * Get a shape by its id.
      *
@@ -4775,7 +4845,7 @@ export declare class GroupShapeUtil extends ShapeUtil<TLGroupShape> {
     static type: "group";
     static props: RecordProps<TLGroupShape>;
     static migrations: TLPropsMigrations;
-    hideSelectionBoundsFg(): boolean;
+    hideSelectionBoundsFg(shape: TLGroupShape): boolean;
     canBind(): boolean;
     canResize(): boolean;
     canResizeChildren(): boolean;
@@ -5061,6 +5131,12 @@ export declare class InputsManager {
     get isPointing(): boolean;
     set isPointing(isPointing: boolean);
     /* Excluded from this release type: setIsPointing */
+    private _isRightPointing;
+    /**
+     * Whether the user is right-click pointing (before drag threshold).
+     */
+    getIsRightPointing(): boolean;
+    /* Excluded from this release type: setIsRightPointing */
     private _isPinching;
     /**
      * Whether the user is pinching.
@@ -5417,6 +5493,94 @@ export declare function parseDeepLinkString(deepLinkString: string): TLDeepLink;
 /** @public */
 export declare type PerfectDashTerminal = 'none' | 'outset' | 'skip';
 
+/**
+ * Optional adapter that pipes PerformanceManager events into browser
+ * `performance.mark()` / `performance.measure()` for DevTools integration.
+ *
+ * Tree-shakeable — only included if imported.
+ *
+ * @example
+ * ```ts
+ * const adapter = new PerformanceApiAdapter(editor.performance)
+ * // ... later
+ * adapter.dispose()
+ * ```
+ *
+ * @public
+ */
+export declare class PerformanceApiAdapter {
+    private cleanups;
+    constructor(perfManager: PerformanceManager);
+    /** Remove all listeners and stop piping events. @public */
+    dispose(): void;
+}
+
+/**
+ * Manages performance event subscriptions for the editor. Available as `editor.performance`.
+ *
+ * Listeners are lazy — internal editor hooks (frame, shape events) are only attached while
+ * at least one subscriber exists, so there is zero overhead when unused.
+ *
+ * @example
+ * ```ts
+ * const unsub = editor.performance.on('interaction-end', (event) => {
+ *   console.log(`${event.name}: ${event.fps.toFixed(1)} fps, p95=${event.p95FrameTime.toFixed(1)}ms`)
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare class PerformanceManager {
+    /* Excluded from this release type: emitter */
+    private editor;
+    private activeInteraction;
+    private activeCamera;
+    private frameCleanup;
+    private shapeCreatedCleanup;
+    private shapeEditedCleanup;
+    private shapeDeletedCleanup;
+    private loafObserver;
+    constructor(editor: Editor);
+    /**
+     * Subscribe to a performance event. Returns an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsub = editor.performance.on('interaction-end', (event) => {
+     *   sendToAnalytics({ name: event.name, fps: event.fps, p95: event.p95FrameTime })
+     * })
+     * // later: unsub()
+     * ```
+     *
+     * @public
+     */
+    on<K extends keyof TLPerfEventMap>(event: K, fn: (...args: TLPerfEventMap[K]) => void): () => void;
+    /**
+     * Subscribe to a performance event once. The listener is removed after the first invocation.
+     * Returns an unsubscribe function for early removal.
+     *
+     * @public
+     */
+    once<K extends keyof TLPerfEventMap>(event: K, fn: (...args: TLPerfEventMap[K]) => void): () => void;
+    /* Excluded from this release type: dispose */
+    /* Excluded from this release type: _notifyInteractionStart */
+    /* Excluded from this release type: _notifyInteractionEnd */
+    /* Excluded from this release type: _notifyCameraOperation */
+    /* Excluded from this release type: _notifyUndoRedo */
+    private _startCameraSession;
+    private _endCameraSession;
+    private _onFrame;
+    private _onShapesCreated;
+    private _onShapesEdited;
+    private _onShapesDeleted;
+    private _startLoafObserver;
+    private _stopLoafObserver;
+    private _needsFrameListener;
+    private _needsLoafObserver;
+    private _maybeAttachLazyListeners;
+    private _maybeDetachLazyListeners;
+}
+
 /**
  * Find the approximate perimeter of an ellipse.
  *
@@ -6008,7 +6172,7 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      *
      * @public
      */
-    canBind(_opts: TLShapeUtilCanBindOpts): boolean;
+    canBind(opts: TLShapeUtilCanBindOpts): boolean;
     /**
      * Whether the shape can be double clicked to edit.
      *
@@ -6142,6 +6306,14 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      * @public
      */
     isAspectRatioLocked(shape: Shape): boolean;
+    /**
+     * Whether the shape behaves like a frame — a container that has child shapes,
+     * requires full-brush selection, blocks erasure from inside, etc.
+     *
+     * @param shape - The shape.
+     * @public
+     */
+    isFrameLike(_shape: Shape): boolean;
     /**
      * By default, the bounds of an image export are the bounds of all the shapes it contains, plus
      * some padding. If an export includes a shape where `isExportBoundsContainer` is true, then the
@@ -6189,7 +6361,7 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      * @param type - The shape type.
      * @public
      */
-    canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
+    canReceiveNewChildrenOfType(shape: Shape, type: TLShape['type']): boolean;
     /**
      * Get the shape as an SVG object.
      *
@@ -6632,6 +6804,8 @@ export declare abstract class StateNode implements Partial<TLEventHandlers> {
     static children?: () => TLStateNodeConstructor[];
     static isLockable: boolean;
     static useCoalescedEvents: boolean;
+    /** Set to `true` in subclasses to emit interaction-start/end performance events when this state is entered/exited. */
+    static trackPerformance: boolean;
     id: string;
     type: 'branch' | 'leaf' | 'root';
     shapeType?: string;
@@ -7005,6 +7179,29 @@ export declare interface TLCameraConstraints {
     };
 }
 
+/**
+ * Emitted when a camera operation ends (after a 50ms debounce), with aggregated frame time stats.
+ * @public
+ */
+export declare interface TLCameraEndPerfEvent extends TLPerfFrameTimeStats {
+    /** Whether this was a pan or zoom operation. */
+    type: 'panning' | 'zooming';
+    /** Total shapes on the current page. */
+    shapeCount: number;
+    /** Number of shapes visible (not culled) in the viewport. */
+    visibleShapeCount: number;
+    /** Number of shapes culled (off-screen) from rendering. */
+    culledShapeCount: number;
+    /** Viewport width in screen pixels. */
+    viewportWidth: number;
+    /** Viewport height in screen pixels. */
+    viewportHeight: number;
+    /** Camera zoom level (`camera.z`) at session end. */
+    zoomLevel: number;
+    /** `performance.now()` when the camera session ended. */
+    timestamp: number;
+}
+
 /** @public */
 export declare interface TLCameraMoveOptions {
     /** Whether to move the camera immediately, rather than on the next tick. */
@@ -7043,6 +7240,17 @@ export declare interface TLCameraOptions {
     constraints?: TLCameraConstraints;
 }
 
+/**
+ * Emitted when a camera operation (pan or zoom) begins.
+ * @public
+ */
+export declare interface TLCameraStartPerfEvent {
+    /** Whether this is a pan or zoom operation. */
+    type: 'panning' | 'zooming';
+    /** `performance.now()` when the camera session started. */
+    timestamp: number;
+}
+
 /** @public */
 export declare type TLCancelEvent = (info: TLCancelEventInfo) => void;
 
@@ -7530,6 +7738,12 @@ export declare interface TldrawOptions {
      * When false, the spacebar will not pan the camera.
      */
     readonly spacebarPanning: boolean;
+    /**
+     * Whether to allow right-click + drag to pan the camera. When true, right-click + drag pans the
+     * camera and a static right-click opens the context menu at the release position. When false,
+     * right-click opens the context menu on press (no drag-to-pan).
+     */
+    readonly rightClickPanning: boolean;
     /**
      * The default padding (in pixels) used when zooming to fit content in the viewport.
      * This affects methods like `zoomToFit()`, `zoomToSelection()`, and `zoomToBounds()`.
@@ -7572,6 +7786,12 @@ export declare interface TldrawOptions {
      * viewport's page dimensions regardless of overview zoom changes.
      */
     readonly quickZoomPreservesScreenBounds: boolean;
+    /**
+     * Whether to use 2D canvas rendering for shape indicators. When true (default),
+     * shapes that support it will render indicators on a 2D canvas for better
+     * performance. When false, all indicators use legacy SVG rendering.
+     */
+    readonly useCanvasIndicators: boolean;
     /**
      * Called before content is written to the clipboard during a copy or cut operation.
      * Receives the serialized content (shapes, bindings, assets) and can filter or transform
@@ -7981,6 +8201,21 @@ export declare interface TLFilesExternalContent extends TLBaseExternalContent {
     ignoreParent?: boolean;
 }
 
+/**
+ * Emitted every animation frame when at least one `'frame'` listener is registered.
+ * @public
+ */
+export declare interface TLFramePerfEvent {
+    /** Time since the last frame in ms. */
+    elapsed: number;
+    /** Total shapes on the current page. */
+    shapeCount: number;
+    /** Number of shapes culled (off-screen) from rendering. */
+    culledShapeCount: number;
+    /** Number of shapes visible (not culled) in the viewport. */
+    visibleShapeCount: number;
+}
+
 /** Additional options for the {@link ShapeUtil.getGeometry} method.
  *
  * @public
@@ -8123,6 +8358,38 @@ export declare type TLIndicatorPath = {
     path: Path2D;
 } | Path2D;
 
+/**
+ * Emitted when an interaction state is exited, with aggregated frame time stats.
+ * @public
+ */
+export declare interface TLInteractionEndPerfEvent extends TLPerfFrameTimeStats {
+    /** The state node id (e.g. `'translating'`). */
+    name: string;
+    /** Full tool path (e.g. `'select.translating'`). */
+    path: string;
+    /** Total shapes on the current page. */
+    shapeCount: number;
+    /** Breakdown of selected shape types at interaction start (e.g. `{ geo: 2, draw: 1 }`). */
+    selectedShapeTypes: Record<string, number>;
+    /** Camera zoom level (`camera.z`) at interaction end. */
+    zoomLevel: number;
+    /** `performance.now()` when the interaction ended. */
+    timestamp: number;
+}
+
+/**
+ * Emitted when an interaction state (e.g. translating, resizing) is entered.
+ * @public
+ */
+export declare interface TLInteractionStartPerfEvent {
+    /** The state node id (e.g. `'translating'`). */
+    name: string;
+    /** Full tool path (e.g. `'select.translating'`). */
+    path: string;
+    /** `performance.now()` when the interaction started. */
+    timestamp: number;
+}
+
 /** @public */
 export declare type TLInterruptEvent = (info: TLInterruptEventInfo) => void;
 
@@ -8370,6 +8637,94 @@ export declare const tlmenus: {
  */
 export declare type TLOnMountHandler = (editor: Editor) => (() => undefined | void) | undefined | void;
 
+/**
+ * Map of all performance event names to their payload types.
+ * Used with {@link PerformanceManager.on} and {@link PerformanceManager.once}.
+ * @public
+ */
+export declare interface TLPerfEventMap {
+    /** An interaction state was entered. */
+    'interaction-start': [TLInteractionStartPerfEvent];
+    /** An interaction state was exited, with aggregated frame time stats. */
+    'interaction-end': [TLInteractionEndPerfEvent];
+    /** A camera operation (pan/zoom) began. */
+    'camera-start': [TLCameraStartPerfEvent];
+    /** A camera operation ended (after debounce), with aggregated frame time stats. */
+    'camera-end': [TLCameraEndPerfEvent];
+    /** Shapes were created. */
+    'shapes-created': [TLShapeOperationPerfEvent];
+    /** Shapes were updated. */
+    'shapes-updated': [TLShapeOperationPerfEvent];
+    /** Shapes were deleted. */
+    'shapes-deleted': [TLShapeOperationPerfEvent];
+    /** An animation frame was rendered. Only fires when listeners are registered. */
+    frame: [TLFramePerfEvent];
+    /** An undo operation was performed. */
+    undo: [TLUndoRedoPerfEvent];
+    /** A redo operation was performed. */
+    redo: [TLUndoRedoPerfEvent];
+}
+
+/**
+ * Common frame time statistics shared by interaction and camera end events.
+ * @public
+ */
+export declare interface TLPerfFrameTimeStats {
+    /** Total duration of the session in ms. */
+    duration: number;
+    /** Average frames per second during the session. */
+    fps: number;
+    /** Total number of frames recorded. */
+    frameCount: number;
+    /** Mean frame duration in ms. */
+    avgFrameTime: number;
+    /** Median (p50) frame duration in ms. */
+    medianFrameTime: number;
+    /** 95th percentile frame duration in ms. */
+    p95FrameTime: number;
+    /** 99th percentile frame duration in ms. */
+    p99FrameTime: number;
+    /** Shortest frame duration in ms. */
+    minFrameTime: number;
+    /** Longest frame duration in ms. */
+    maxFrameTime: number;
+    /** Raw frame durations for local analysis. Exclude when sending to analytics. */
+    frameTimes: number[];
+    /**
+     * Long animation frames observed during this period (Chromium 123+).
+     * Only present when the browser supports the Long Animation Frames API and
+     * at least one long frame was observed.
+     * Exclude when sending to analytics — entries are large and contain script URLs.
+     */
+    longAnimationFrames?: TLPerfLongAnimationFrame[];
+}
+
+/**
+ * A long animation frame observed by the browser during an interaction.
+ * Available only in browsers that support the Long Animation Frames API (Chromium 123+).
+ * @public
+ */
+export declare interface TLPerfLongAnimationFrame {
+    /** Frame start time (relative to timeOrigin). */
+    startTime: number;
+    /** Total frame duration in ms. */
+    duration: number;
+    /** Time the main thread was blocked in ms. */
+    blockingDuration: number;
+    /** Scripts that contributed to the long frame. */
+    scripts: TLPerfLongAnimationFrameScript[];
+}
+
+/** A script attribution entry from a long animation frame. @public */
+export declare interface TLPerfLongAnimationFrameScript {
+    /** The script source URL (may be empty for inline scripts). */
+    sourceURL: string;
+    /** The function name or invoker description. */
+    invoker: string;
+    /** Time spent in this script in ms. */
+    duration: number;
+}
+
 /** @public */
 export declare type TLPinchEvent = (info: TLPinchEventInfo) => void;
 
@@ -8557,6 +8912,21 @@ export declare interface TLShapeIndicatorsProps {
     showAll?: boolean;
 }
 
+/**
+ * Emitted when shapes are created, updated, or deleted.
+ * @public
+ */
+export declare interface TLShapeOperationPerfEvent {
+    /** The operation type. */
+    operation: 'create' | 'delete' | 'update';
+    /** Number of shapes affected. */
+    count: number;
+    /** Breakdown by shape type (e.g. `{ geo: 2, draw: 1 }`). */
+    shapeTypes: Record<string, number>;
+    /** `performance.now()` when the operation occurred. */
+    timestamp: number;
+}
+
 /**
  * Options passed to {@link ShapeUtil.canBeLaidOut}.
  *
@@ -8642,6 +9012,7 @@ export declare interface TLStateNodeConstructor {
     children?(): TLStateNodeConstructor[];
     isLockable: boolean;
     useCoalescedEvents: boolean;
+    trackPerformance: boolean;
 }
 
 /** @public */
@@ -8819,6 +9190,19 @@ export declare interface TLTldrawExternalContentSource {
     data: TLContent;
 }
 
+/**
+ * Emitted after an undo or redo operation.
+ * @public
+ */
+export declare interface TLUndoRedoPerfEvent {
+    /** Whether this was an undo or redo. */
+    type: 'redo' | 'undo';
+    /** Number of undo steps remaining. */
+    undoDepth: number;
+    /** Number of redo steps remaining. */
+    redoDepth: number;
+}
+
 /** @public */
 export declare interface TLUpdatePointerOptions {
     /** Whether to update the pointer immediately, rather than on the next tick. */

package/dist-cjs/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   AssetUtil: () => import_AssetUtil.AssetUtil,
   BaseBoxShapeTool: () => import_BaseBoxShapeTool.BaseBoxShapeTool,
   BaseBoxShapeUtil: () => import_BaseBoxShapeUtil.BaseBoxShapeUtil,
+  BaseFrameLikeShapeUtil: () => import_BaseFrameLikeShapeUtil.BaseFrameLikeShapeUtil,
   BindingUtil: () => import_BindingUtil.BindingUtil,
   BoundsSnaps: () => import_BoundsSnaps.BoundsSnaps,
   Box: () => import_Box.Box,
@@ -82,6 +83,8 @@ __export(index_exports, {
   OptionalErrorBoundary: () => import_ErrorBoundary.OptionalErrorBoundary,
   PI: () => import_utils2.PI,
   PI2: () => import_utils2.PI2,
+  PerformanceApiAdapter: () => import_PerformanceApiAdapter.PerformanceApiAdapter,
+  PerformanceManager: () => import_PerformanceManager.PerformanceManager,
   Point2d: () => import_Point2d.Point2d,
   Polygon2d: () => import_Polygon2d.Polygon2d,
   Polyline2d: () => import_Polyline2d.Polyline2d,
@@ -301,8 +304,11 @@ var import_TextManager = require("./lib/editor/managers/TextManager/TextManager"
 var import_defaultThemes = require("./lib/editor/managers/ThemeManager/defaultThemes");
 var import_ThemeManager = require("./lib/editor/managers/ThemeManager/ThemeManager");
 var import_TickManager = require("./lib/editor/managers/TickManager/TickManager");
+var import_PerformanceApiAdapter = require("./lib/editor/managers/PerformanceManager/PerformanceApiAdapter");
+var import_PerformanceManager = require("./lib/editor/managers/PerformanceManager/PerformanceManager");
 var import_UserPreferencesManager = require("./lib/editor/managers/UserPreferencesManager/UserPreferencesManager");
 var import_BaseBoxShapeUtil = require("./lib/editor/shapes/BaseBoxShapeUtil");
+var import_BaseFrameLikeShapeUtil = require("./lib/editor/shapes/BaseFrameLikeShapeUtil");
 var import_GroupShapeUtil = require("./lib/editor/shapes/group/GroupShapeUtil");
 var import_ShapeUtil = require("./lib/editor/shapes/ShapeUtil");
 var import_getPerfectDashProps = require("./lib/editor/shapes/shared/getPerfectDashProps");
@@ -385,7 +391,7 @@ var import_uniq = require("./lib/utils/uniq");
 var import_defaultThemes2 = require("./lib/editor/managers/ThemeManager/defaultThemes");
 (0, import_utils.registerTldrawLibraryVersion)(
   "@tldraw/editor",
-  "4.6.0-canary.ab4e1d4fd85b",
+  "4.6.0-canary.abd30e51f1f3",
   "cjs"
 );
 //# sourceMappingURL=index.js.map