canvu-react 0.4.63 → 0.4.65

package/dist/{types-C_PMen-D.d.ts → types-BZUp3LpC.d.ts}

@@ -118,6 +118,36 @@ type VectorToolDefinition = {
     ariaLabel?: string;
 };
 
+type ReadOnlyItemClickCandidateDetail = {
+    /** The item Canvu hit-tested under the read-only click. */
+    item: VectorSceneItem;
+    /** World-space pointer location at press time. */
+    worldX: number;
+    worldY: number;
+    /** Viewport/client pointer location at press time. */
+    clientX: number;
+    clientY: number;
+    pointerType: string;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    /** Current viewport items. */
+    items: readonly VectorSceneItem[];
+    /** Selection snapshot before read-only activation handles the click. */
+    selectedIds: readonly string[];
+};
+/**
+ * Controls which items may receive select-mode click activation while
+ * `VectorViewport` is read-only (`interactive={false}`).
+ *
+ * `"custom"` keeps the default high-level behavior: custom placement/tool
+ * items with `onSelectModeItemClick` remain clickable, while regular items do
+ * not become selectable unless the app opts in. Use `"all"` or a predicate for
+ * read-only viewers that still need item selection or item-specific side effects.
+ */
+type ReadOnlyItemClickScope = "custom" | "all" | ((detail: ReadOnlyItemClickCandidateDetail) => boolean);
+
 type ActiveToolStyle = StrokeStyle & {
     toolKind: "draw" | "marker" | "text" | "rect" | "ellipse" | "architectural-cloud" | "line" | "arrow";
     label?: string;
@@ -179,6 +209,47 @@ type SelectModeItemClickDetail = {
     /** Set the viewport selection when activation should also select or clear. */
     setSelectedIds: (ids: readonly string[]) => void;
 };
+
+/**
+ * Read-only interaction exceptions for viewers that should stay immutable while
+ * still allowing explicit activation/selection clicks.
+ *
+ * Canvu-owned editing remains disabled: no placement, draw, move, resize,
+ * rotate, eraser, paste/drop mutation, text editing, handles, or inspector.
+ * Explicit user callbacks may still call `updateItem` when that is the desired
+ * app-level exception.
+ *
+ * @example
+ * ```tsx
+ * <VectorViewport
+ *   interactive={false}
+ *   readOnlyInteraction={{
+ *     itemClicks: "all",
+ *     onItemClick: ({ item, setSelectedIds }) => {
+ *       setSelectedIds([item.id]);
+ *       return "handled";
+ *     },
+ *   }}
+ * />
+ * ```
+ */
+type ReadOnlyInteractionOptions = {
+    /**
+     * Which read-only item clicks Canvu should capture.
+     *
+     * Defaults to `"custom"`, which only activates custom placement/tool items
+     * that provide `onSelectModeItemClick`.
+     */
+    itemClicks?: ReadOnlyItemClickScope;
+    /**
+     * Optional handler for read-only item clicks enabled by `itemClicks`.
+     *
+     * Custom placement `onSelectModeItemClick` handlers run first for their own
+     * items. For non-custom opt-in clicks, returning `undefined` lets Canvu apply
+     * default read-only selection semantics.
+     */
+    onItemClick?: (detail: SelectModeItemClickDetail) => SelectModeItemClickResult;
+};
 /**
  * Best-effort reason attached to a React viewport item change.
  *
@@ -202,6 +273,101 @@ type VectorItemsChangeInfo = {
     itemIds?: readonly string[];
     toolId?: string;
 };
+/**
+ * Interaction categories emitted by the React viewport lifecycle hooks.
+ *
+ * These describe pointer gestures owned by `VectorViewport`, not every possible
+ * input event. Camera pan/zoom, keyboard shortcuts, paste/drop, toolbar clicks,
+ * and custom UI events are intentionally outside this lifecycle.
+ */
+type CanvuInteractionKind = "move" | "resize" | "rotate" | "marquee" | "stroke" | "erase" | "tap" | "place" | "select-mode-item-click";
+/**
+ * World and client coordinates for a viewport interaction sample.
+ *
+ * `start` stays fixed for the accepted gesture. `current` is updated for the
+ * after hook so integrations can compare where the gesture began and ended.
+ */
+type CanvuInteractionPoint = {
+    readonly worldX: number;
+    readonly worldY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+};
+/**
+ * Stable interaction metadata passed to before/after interaction hooks.
+ *
+ * Use this for custom tool behavior that needs to observe or claim a viewport
+ * gesture before Canvu mutates selection, previews, or items. Do not use it to
+ * intercept item-list writes; use `wrapOnItemsChange` when you need exact
+ * document mutation middleware.
+ *
+ * @example
+ * ```tsx
+ * <VectorViewport
+ *   onBeforeInteraction={(detail) =>
+ *     detail.toolId === "review-pin" ? "handled" : undefined
+ *   }
+ * />
+ * ```
+ */
+type CanvuInteractionDetail = {
+    /** Stable id for this accepted pointer gesture. */
+    readonly interactionId: string;
+    /** Canvu interaction category resolved before built-in state changes. */
+    readonly kind: CanvuInteractionKind;
+    /** Active viewport tool when the gesture started. */
+    readonly toolId: string;
+    /** Browser pointer type such as `"mouse"`, `"pen"`, or `"touch"`. */
+    readonly pointerType: string;
+    /** Pointer button reported by the start event. Touch fallbacks use `0`. */
+    readonly button: number;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+    readonly ctrlKey: boolean;
+    /** Pointer position when the interaction started. */
+    readonly start: CanvuInteractionPoint;
+    /** Latest pointer position known to Canvu for this interaction. */
+    readonly current: CanvuInteractionPoint;
+    /** Selection snapshot before Canvu applies this interaction. */
+    readonly selectedIds: readonly string[];
+    /** Primary target item ids when the interaction has known targets. */
+    readonly itemIds: readonly string[];
+    /** Current viewport items when the interaction was accepted. */
+    readonly items: readonly VectorSceneItem[];
+};
+/** Return value that lets a before hook claim a gesture. */
+type CanvuBeforeInteractionResult = "handled" | undefined;
+/**
+ * Runs after Canvu resolves an interaction kind and before built-in mutation.
+ *
+ * Return `"handled"` to claim the gesture. Canvu will prevent the pointer event,
+ * skip later before hooks, skip built-in behavior, and will not emit an after
+ * hook for that gesture.
+ */
+type CanvuBeforeInteractionHook = (detail: CanvuInteractionDetail) => CanvuBeforeInteractionResult;
+/** Final state reported when an accepted interaction leaves Canvu's active state. */
+type CanvuInteractionOutcome = "completed" | "cancelled";
+/**
+ * Metadata passed to after interaction hooks.
+ *
+ * `info` mirrors the best-effort `VectorItemsChangeInfo` used by
+ * `onItemsChange`; it is intentionally advisory and may be omitted when the
+ * gesture did not write items.
+ */
+type CanvuAfterInteractionDetail = CanvuInteractionDetail & {
+    readonly outcome: CanvuInteractionOutcome;
+    readonly info?: VectorItemsChangeInfo;
+};
+/**
+ * Runs once when an accepted Canvu interaction completes or is cancelled.
+ *
+ * Use this for analytics, custom UI cleanup, or tool-specific side effects that
+ * should happen after Canvu's gesture lifecycle finishes. Use
+ * `wrapOnItemsChange` instead when you need to transform or persist item
+ * mutations.
+ */
+type CanvuAfterInteractionHook = (detail: CanvuAfterInteractionDetail) => void;
 /**
  * Imperative API for pan/zoom and integrations (e.g. AI agents following a region).
  * Call {@link requestRender} after mutating the {@link Camera2D} from {@link getCamera}.
@@ -243,8 +409,10 @@ type CustomShapePlacementOptions = {
      * Optional select-mode click handler for items created by this placement.
      *
      * If provided, a plain click on the item in select mode calls this handler instead
-     * of selecting or moving the item. Resize and rotate handles still win first, and
-     * dragging past the tap threshold falls back to normal move behavior.
+     * of selecting or moving the item. Resize and rotate handles still win first in
+     * interactive viewports, and dragging past the tap threshold falls back to normal
+     * move behavior. In read-only viewports, the same click still activates the item
+     * by default, while dragging past the tap threshold cancels activation.
      */
     onSelectModeItemClick?: (detail: SelectModeItemClickDetail) => SelectModeItemClickResult;
 };
@@ -266,6 +434,15 @@ type VectorViewportProps = {
      * Requires `onItemsChange` to persist mutations.
      */
     interactive?: boolean;
+    /**
+     * Read-only click exceptions used when `interactive` is false.
+     *
+     * By default, read-only viewports still allow custom placement/tool items
+     * with `onSelectModeItemClick` to activate. Opt into `"all"` or a predicate
+     * when a read-only viewer should also allow regular item selection/clicks.
+     * Canvu-owned editing stays disabled; only explicit callbacks may mutate.
+     */
+    readOnlyInteraction?: ReadOnlyInteractionOptions;
     /** Selected item ids (order preserved). Empty = none. */
     selectedIds?: readonly string[];
     onSelectionChange?: (ids: string[]) => void;
@@ -278,6 +455,24 @@ type VectorViewportProps = {
      * omit `info`.
      */
     onItemsChange?: (items: VectorSceneItem[], info?: VectorItemsChangeInfo) => void;
+    /**
+     * Runs before a Canvu-owned pointer interaction mutates viewport state.
+     *
+     * Return `"handled"` to claim the gesture and prevent Canvu's built-in
+     * selection, drawing, placement, or resize behavior for that pointerdown.
+     * Prefer this for custom tool behavior. Prefer `wrapOnItemsChange` when your
+     * integration needs document mutation middleware instead.
+     */
+    onBeforeInteraction?: CanvuBeforeInteractionHook;
+    /**
+     * Runs once after an accepted Canvu-owned pointer interaction completes or is
+     * cancelled.
+     *
+     * This is useful for analytics, custom tool cleanup, and UI side effects.
+     * The optional `info` payload is best-effort mutation metadata; continue to use
+     * `wrapOnItemsChange` for exact item-list interception.
+     */
+    onAfterInteraction?: CanvuAfterInteractionHook;
     /**
      * Fires when a link/bookmark item is activated (double-click / double-tap).
      * When omitted, the link opens in a new browser tab by default (web only).
@@ -417,6 +612,19 @@ type CanvasPluginContribution = {
     viewportProps?: Partial<Pick<VectorViewportProps, "remotePresence" | "presenceOverlay">>;
     /** Event callbacks chained into the viewport without manual wiring in app code. */
     callbacks?: Partial<Pick<VectorViewportProps, "onWorldPointerDown" | "onWorldPointerMove" | "onWorldPointerLeave" | "onPlacementPreviewChange" | "onCameraChange">>;
+    /**
+     * Hooks around Canvu-owned pointer interactions.
+     *
+     * Use these for custom tool behavior that needs to observe or claim a gesture
+     * before the viewport mutates state. Use `wrapOnItemsChange` for exact item
+     * mutation middleware.
+     */
+    interactionHooks?: {
+        /** Return `"handled"` to claim the gesture and skip Canvu's built-in behavior. */
+        onBeforeInteraction?: CanvuBeforeInteractionHook;
+        /** Runs once when an accepted gesture completes or is cancelled. */
+        onAfterInteraction?: CanvuAfterInteractionHook;
+    };
     /** Middleware around `onItemsChange` for collaboration, comments, persistence, etc. */
     wrapOnItemsChange?: (nextItems: VectorSceneItem[], ctx: CanvasPluginItemsChangeMiddlewareContext, info?: VectorItemsChangeInfo) => void;
 };
@@ -498,4 +706,4 @@ declare function useCanvuResolvedTools(): VectorToolDefinition[];
  */
 declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
 
-export { useCanvuPluginContribution as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, useCanvuResolvedTools as D, useCanvuViewportContext as E, type PlacementPreview as P, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvasPlugin as a, VectorSelectionInspector as b, type CanvasPluginComponentProps as c, type CanvasPluginContribution as d, type CanvasPluginItemsChangeMiddlewareContext as e, type CanvasPluginRenderContext as f, type CanvuChromeActiveToolStyle as g, CanvuChromeContext as h, type CanvuChromeContextValue as i, type CanvuChromeSelectionStyleChange as j, CanvuPluginContext as k, type CanvuPluginContextValue as l, type CanvuPluginViewportSnapshot as m, type SelectModeItemClickResult as n, type VectorCanvasSpacePosition as o, type VectorItemsChangeInfo as p, type VectorItemsChangeMotive as q, type VectorSelectionInspectorProps as r, VectorViewport as s, type VectorViewportHandle as t, type VectorViewportProps as u, createCanvuPlugin as v, getBoardPositionStyle as w, useCanvuChromeContext as x, useCanvuDocumentContext as y, useCanvuPluginContext as z };
+export { type VectorItemsChangeMotive as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type VectorSelectionInspectorProps as D, VectorViewport as E, type VectorViewportHandle as F, type VectorViewportProps as G, createCanvuPlugin as H, getBoardPositionStyle as I, useCanvuChromeContext as J, useCanvuDocumentContext as K, useCanvuPluginContext as L, useCanvuPluginContribution as M, useCanvuResolvedTools as N, useCanvuViewportContext as O, type PlacementPreview as P, type ReadOnlyInteractionOptions as R, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvuBeforeInteractionHook as a, type CanvuAfterInteractionHook as b, type CanvasPlugin as c, VectorSelectionInspector as d, type CanvasPluginComponentProps as e, type CanvasPluginContribution as f, type CanvasPluginItemsChangeMiddlewareContext as g, type CanvasPluginRenderContext as h, type CanvuAfterInteractionDetail as i, type CanvuBeforeInteractionResult as j, type CanvuChromeActiveToolStyle as k, CanvuChromeContext as l, type CanvuChromeContextValue as m, type CanvuChromeSelectionStyleChange as n, type CanvuInteractionDetail as o, type CanvuInteractionKind as p, type CanvuInteractionOutcome as q, type CanvuInteractionPoint as r, CanvuPluginContext as s, type CanvuPluginContextValue as t, type CanvuPluginViewportSnapshot as u, type ReadOnlyItemClickCandidateDetail as v, type ReadOnlyItemClickScope as w, type SelectModeItemClickResult as x, type VectorCanvasSpacePosition as y, type VectorItemsChangeInfo as z };

package/dist/{types--jCoyZIF.d.cts → types-Bw3REwrb.d.cts}

@@ -118,6 +118,36 @@ type VectorToolDefinition = {
     ariaLabel?: string;
 };
 
+type ReadOnlyItemClickCandidateDetail = {
+    /** The item Canvu hit-tested under the read-only click. */
+    item: VectorSceneItem;
+    /** World-space pointer location at press time. */
+    worldX: number;
+    worldY: number;
+    /** Viewport/client pointer location at press time. */
+    clientX: number;
+    clientY: number;
+    pointerType: string;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    /** Current viewport items. */
+    items: readonly VectorSceneItem[];
+    /** Selection snapshot before read-only activation handles the click. */
+    selectedIds: readonly string[];
+};
+/**
+ * Controls which items may receive select-mode click activation while
+ * `VectorViewport` is read-only (`interactive={false}`).
+ *
+ * `"custom"` keeps the default high-level behavior: custom placement/tool
+ * items with `onSelectModeItemClick` remain clickable, while regular items do
+ * not become selectable unless the app opts in. Use `"all"` or a predicate for
+ * read-only viewers that still need item selection or item-specific side effects.
+ */
+type ReadOnlyItemClickScope = "custom" | "all" | ((detail: ReadOnlyItemClickCandidateDetail) => boolean);
+
 type ActiveToolStyle = StrokeStyle & {
     toolKind: "draw" | "marker" | "text" | "rect" | "ellipse" | "architectural-cloud" | "line" | "arrow";
     label?: string;
@@ -179,6 +209,47 @@ type SelectModeItemClickDetail = {
     /** Set the viewport selection when activation should also select or clear. */
     setSelectedIds: (ids: readonly string[]) => void;
 };
+
+/**
+ * Read-only interaction exceptions for viewers that should stay immutable while
+ * still allowing explicit activation/selection clicks.
+ *
+ * Canvu-owned editing remains disabled: no placement, draw, move, resize,
+ * rotate, eraser, paste/drop mutation, text editing, handles, or inspector.
+ * Explicit user callbacks may still call `updateItem` when that is the desired
+ * app-level exception.
+ *
+ * @example
+ * ```tsx
+ * <VectorViewport
+ *   interactive={false}
+ *   readOnlyInteraction={{
+ *     itemClicks: "all",
+ *     onItemClick: ({ item, setSelectedIds }) => {
+ *       setSelectedIds([item.id]);
+ *       return "handled";
+ *     },
+ *   }}
+ * />
+ * ```
+ */
+type ReadOnlyInteractionOptions = {
+    /**
+     * Which read-only item clicks Canvu should capture.
+     *
+     * Defaults to `"custom"`, which only activates custom placement/tool items
+     * that provide `onSelectModeItemClick`.
+     */
+    itemClicks?: ReadOnlyItemClickScope;
+    /**
+     * Optional handler for read-only item clicks enabled by `itemClicks`.
+     *
+     * Custom placement `onSelectModeItemClick` handlers run first for their own
+     * items. For non-custom opt-in clicks, returning `undefined` lets Canvu apply
+     * default read-only selection semantics.
+     */
+    onItemClick?: (detail: SelectModeItemClickDetail) => SelectModeItemClickResult;
+};
 /**
  * Best-effort reason attached to a React viewport item change.
  *
@@ -202,6 +273,101 @@ type VectorItemsChangeInfo = {
     itemIds?: readonly string[];
     toolId?: string;
 };
+/**
+ * Interaction categories emitted by the React viewport lifecycle hooks.
+ *
+ * These describe pointer gestures owned by `VectorViewport`, not every possible
+ * input event. Camera pan/zoom, keyboard shortcuts, paste/drop, toolbar clicks,
+ * and custom UI events are intentionally outside this lifecycle.
+ */
+type CanvuInteractionKind = "move" | "resize" | "rotate" | "marquee" | "stroke" | "erase" | "tap" | "place" | "select-mode-item-click";
+/**
+ * World and client coordinates for a viewport interaction sample.
+ *
+ * `start` stays fixed for the accepted gesture. `current` is updated for the
+ * after hook so integrations can compare where the gesture began and ended.
+ */
+type CanvuInteractionPoint = {
+    readonly worldX: number;
+    readonly worldY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+};
+/**
+ * Stable interaction metadata passed to before/after interaction hooks.
+ *
+ * Use this for custom tool behavior that needs to observe or claim a viewport
+ * gesture before Canvu mutates selection, previews, or items. Do not use it to
+ * intercept item-list writes; use `wrapOnItemsChange` when you need exact
+ * document mutation middleware.
+ *
+ * @example
+ * ```tsx
+ * <VectorViewport
+ *   onBeforeInteraction={(detail) =>
+ *     detail.toolId === "review-pin" ? "handled" : undefined
+ *   }
+ * />
+ * ```
+ */
+type CanvuInteractionDetail = {
+    /** Stable id for this accepted pointer gesture. */
+    readonly interactionId: string;
+    /** Canvu interaction category resolved before built-in state changes. */
+    readonly kind: CanvuInteractionKind;
+    /** Active viewport tool when the gesture started. */
+    readonly toolId: string;
+    /** Browser pointer type such as `"mouse"`, `"pen"`, or `"touch"`. */
+    readonly pointerType: string;
+    /** Pointer button reported by the start event. Touch fallbacks use `0`. */
+    readonly button: number;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+    readonly ctrlKey: boolean;
+    /** Pointer position when the interaction started. */
+    readonly start: CanvuInteractionPoint;
+    /** Latest pointer position known to Canvu for this interaction. */
+    readonly current: CanvuInteractionPoint;
+    /** Selection snapshot before Canvu applies this interaction. */
+    readonly selectedIds: readonly string[];
+    /** Primary target item ids when the interaction has known targets. */
+    readonly itemIds: readonly string[];
+    /** Current viewport items when the interaction was accepted. */
+    readonly items: readonly VectorSceneItem[];
+};
+/** Return value that lets a before hook claim a gesture. */
+type CanvuBeforeInteractionResult = "handled" | undefined;
+/**
+ * Runs after Canvu resolves an interaction kind and before built-in mutation.
+ *
+ * Return `"handled"` to claim the gesture. Canvu will prevent the pointer event,
+ * skip later before hooks, skip built-in behavior, and will not emit an after
+ * hook for that gesture.
+ */
+type CanvuBeforeInteractionHook = (detail: CanvuInteractionDetail) => CanvuBeforeInteractionResult;
+/** Final state reported when an accepted interaction leaves Canvu's active state. */
+type CanvuInteractionOutcome = "completed" | "cancelled";
+/**
+ * Metadata passed to after interaction hooks.
+ *
+ * `info` mirrors the best-effort `VectorItemsChangeInfo` used by
+ * `onItemsChange`; it is intentionally advisory and may be omitted when the
+ * gesture did not write items.
+ */
+type CanvuAfterInteractionDetail = CanvuInteractionDetail & {
+    readonly outcome: CanvuInteractionOutcome;
+    readonly info?: VectorItemsChangeInfo;
+};
+/**
+ * Runs once when an accepted Canvu interaction completes or is cancelled.
+ *
+ * Use this for analytics, custom UI cleanup, or tool-specific side effects that
+ * should happen after Canvu's gesture lifecycle finishes. Use
+ * `wrapOnItemsChange` instead when you need to transform or persist item
+ * mutations.
+ */
+type CanvuAfterInteractionHook = (detail: CanvuAfterInteractionDetail) => void;
 /**
  * Imperative API for pan/zoom and integrations (e.g. AI agents following a region).
  * Call {@link requestRender} after mutating the {@link Camera2D} from {@link getCamera}.
@@ -243,8 +409,10 @@ type CustomShapePlacementOptions = {
      * Optional select-mode click handler for items created by this placement.
      *
      * If provided, a plain click on the item in select mode calls this handler instead
-     * of selecting or moving the item. Resize and rotate handles still win first, and
-     * dragging past the tap threshold falls back to normal move behavior.
+     * of selecting or moving the item. Resize and rotate handles still win first in
+     * interactive viewports, and dragging past the tap threshold falls back to normal
+     * move behavior. In read-only viewports, the same click still activates the item
+     * by default, while dragging past the tap threshold cancels activation.
      */
     onSelectModeItemClick?: (detail: SelectModeItemClickDetail) => SelectModeItemClickResult;
 };
@@ -266,6 +434,15 @@ type VectorViewportProps = {
      * Requires `onItemsChange` to persist mutations.
      */
     interactive?: boolean;
+    /**
+     * Read-only click exceptions used when `interactive` is false.
+     *
+     * By default, read-only viewports still allow custom placement/tool items
+     * with `onSelectModeItemClick` to activate. Opt into `"all"` or a predicate
+     * when a read-only viewer should also allow regular item selection/clicks.
+     * Canvu-owned editing stays disabled; only explicit callbacks may mutate.
+     */
+    readOnlyInteraction?: ReadOnlyInteractionOptions;
     /** Selected item ids (order preserved). Empty = none. */
     selectedIds?: readonly string[];
     onSelectionChange?: (ids: string[]) => void;
@@ -278,6 +455,24 @@ type VectorViewportProps = {
      * omit `info`.
      */
     onItemsChange?: (items: VectorSceneItem[], info?: VectorItemsChangeInfo) => void;
+    /**
+     * Runs before a Canvu-owned pointer interaction mutates viewport state.
+     *
+     * Return `"handled"` to claim the gesture and prevent Canvu's built-in
+     * selection, drawing, placement, or resize behavior for that pointerdown.
+     * Prefer this for custom tool behavior. Prefer `wrapOnItemsChange` when your
+     * integration needs document mutation middleware instead.
+     */
+    onBeforeInteraction?: CanvuBeforeInteractionHook;
+    /**
+     * Runs once after an accepted Canvu-owned pointer interaction completes or is
+     * cancelled.
+     *
+     * This is useful for analytics, custom tool cleanup, and UI side effects.
+     * The optional `info` payload is best-effort mutation metadata; continue to use
+     * `wrapOnItemsChange` for exact item-list interception.
+     */
+    onAfterInteraction?: CanvuAfterInteractionHook;
     /**
      * Fires when a link/bookmark item is activated (double-click / double-tap).
      * When omitted, the link opens in a new browser tab by default (web only).
@@ -417,6 +612,19 @@ type CanvasPluginContribution = {
     viewportProps?: Partial<Pick<VectorViewportProps, "remotePresence" | "presenceOverlay">>;
     /** Event callbacks chained into the viewport without manual wiring in app code. */
     callbacks?: Partial<Pick<VectorViewportProps, "onWorldPointerDown" | "onWorldPointerMove" | "onWorldPointerLeave" | "onPlacementPreviewChange" | "onCameraChange">>;
+    /**
+     * Hooks around Canvu-owned pointer interactions.
+     *
+     * Use these for custom tool behavior that needs to observe or claim a gesture
+     * before the viewport mutates state. Use `wrapOnItemsChange` for exact item
+     * mutation middleware.
+     */
+    interactionHooks?: {
+        /** Return `"handled"` to claim the gesture and skip Canvu's built-in behavior. */
+        onBeforeInteraction?: CanvuBeforeInteractionHook;
+        /** Runs once when an accepted gesture completes or is cancelled. */
+        onAfterInteraction?: CanvuAfterInteractionHook;
+    };
     /** Middleware around `onItemsChange` for collaboration, comments, persistence, etc. */
     wrapOnItemsChange?: (nextItems: VectorSceneItem[], ctx: CanvasPluginItemsChangeMiddlewareContext, info?: VectorItemsChangeInfo) => void;
 };
@@ -498,4 +706,4 @@ declare function useCanvuResolvedTools(): VectorToolDefinition[];
  */
 declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
 
-export { useCanvuPluginContribution as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, useCanvuResolvedTools as D, useCanvuViewportContext as E, type PlacementPreview as P, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvasPlugin as a, VectorSelectionInspector as b, type CanvasPluginComponentProps as c, type CanvasPluginContribution as d, type CanvasPluginItemsChangeMiddlewareContext as e, type CanvasPluginRenderContext as f, type CanvuChromeActiveToolStyle as g, CanvuChromeContext as h, type CanvuChromeContextValue as i, type CanvuChromeSelectionStyleChange as j, CanvuPluginContext as k, type CanvuPluginContextValue as l, type CanvuPluginViewportSnapshot as m, type SelectModeItemClickResult as n, type VectorCanvasSpacePosition as o, type VectorItemsChangeInfo as p, type VectorItemsChangeMotive as q, type VectorSelectionInspectorProps as r, VectorViewport as s, type VectorViewportHandle as t, type VectorViewportProps as u, createCanvuPlugin as v, getBoardPositionStyle as w, useCanvuChromeContext as x, useCanvuDocumentContext as y, useCanvuPluginContext as z };
+export { type VectorItemsChangeMotive as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type VectorSelectionInspectorProps as D, VectorViewport as E, type VectorViewportHandle as F, type VectorViewportProps as G, createCanvuPlugin as H, getBoardPositionStyle as I, useCanvuChromeContext as J, useCanvuDocumentContext as K, useCanvuPluginContext as L, useCanvuPluginContribution as M, useCanvuResolvedTools as N, useCanvuViewportContext as O, type PlacementPreview as P, type ReadOnlyInteractionOptions as R, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvuBeforeInteractionHook as a, type CanvuAfterInteractionHook as b, type CanvasPlugin as c, VectorSelectionInspector as d, type CanvasPluginComponentProps as e, type CanvasPluginContribution as f, type CanvasPluginItemsChangeMiddlewareContext as g, type CanvasPluginRenderContext as h, type CanvuAfterInteractionDetail as i, type CanvuBeforeInteractionResult as j, type CanvuChromeActiveToolStyle as k, CanvuChromeContext as l, type CanvuChromeContextValue as m, type CanvuChromeSelectionStyleChange as n, type CanvuInteractionDetail as o, type CanvuInteractionKind as p, type CanvuInteractionOutcome as q, type CanvuInteractionPoint as r, CanvuPluginContext as s, type CanvuPluginContextValue as t, type CanvuPluginViewportSnapshot as u, type ReadOnlyItemClickCandidateDetail as v, type ReadOnlyItemClickScope as w, type SelectModeItemClickResult as x, type VectorCanvasSpacePosition as y, type VectorItemsChangeInfo as z };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "canvu-react",
-	"version": "0.4.63",
+	"version": "0.4.65",
 	"description": "Vector-first infinite canvas (SVG) with pan, zoom, React bindings, and optional plugins",
 	"license": "MIT",
 	"type": "module",