canvu-react 0.4.64 → 0.4.66

package/dist/{types-PsLgDGZT.d.ts → types-B-Jdh-n6.d.ts}

@@ -118,6 +118,175 @@ 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);
+
+/**
+ * Stable ids for Canvu's built-in shape context-menu items.
+ *
+ * Use these with `ShapeContextMenu.itemContributions`, `VectorViewport.contextMenuItems`,
+ * or plugin `contextMenuItems` when replacing a default item without relying on magic strings.
+ */
+declare const SHAPE_CONTEXT_MENU_ITEM_IDS: {
+    readonly cut: "cut";
+    readonly copy: "copy";
+    readonly duplicate: "duplicate";
+    readonly reorderDivider: "reorder-divider";
+    readonly bringToFront: "bring-to-front";
+    readonly bringForward: "bring-forward";
+    readonly sendBackward: "send-backward";
+    readonly sendToBack: "send-to-back";
+    readonly lockDivider: "lock-divider";
+    readonly toggleLock: "toggle-lock";
+    readonly delete: "delete";
+};
+/**
+ * Runtime data and built-in commands exposed to shape context-menu item renderers.
+ *
+ * Use this for small menu item customizations and plugin actions. The built-in action
+ * functions already close the menu after running, matching Canvu's default menu behavior.
+ * For full viewport-level replacement, use {@link VectorViewportProps.contextMenu}.
+ */
+type ShapeContextMenuRenderContext = {
+    /** Viewport client coordinates where the menu opened. */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Selected item ids targeted by this menu. */
+    selectedIds: readonly string[];
+    /** Selected scene items targeted by this menu. */
+    selectedItems: readonly VectorSceneItem[];
+    /** True when every selected item is locked. */
+    allSelectedLocked: boolean;
+    /** True when at least one selected item is locked. */
+    anySelectedLocked: boolean;
+    /** Close the floating context menu without running an action. */
+    close: () => void;
+    /** Cut the selected items to Canvu's internal clipboard, then close the menu. */
+    cut: () => void;
+    /** Copy the selected items to Canvu's internal clipboard, then close the menu. */
+    copy: () => void;
+    /** Duplicate selected items, then close the menu. */
+    duplicate: () => void;
+    /** Toggle lock state for selected items, then close the menu. */
+    toggleLock: () => void;
+    /** Move selected items above all siblings, then close the menu. */
+    bringToFront: () => void;
+    /** Move selected items forward one layer, then close the menu. */
+    bringForward: () => void;
+    /** Move selected items backward one layer, then close the menu. */
+    sendBackward: () => void;
+    /** Move selected items behind all siblings, then close the menu. */
+    sendToBack: () => void;
+    /** Delete selected items, then close the menu. */
+    delete: () => void;
+    /** Alias for {@link ShapeContextMenuRenderContext.delete}. */
+    deleteSelection: () => void;
+};
+/**
+ * One renderable context-menu row, divider, or custom block.
+ *
+ * Items compose by `id`: passing an item with a built-in id such as
+ * `SHAPE_CONTEXT_MENU_ITEM_IDS.copy` replaces that item in place, while new ids append.
+ *
+ * @example
+ * ```tsx
+ * const replaceCopy = {
+ *   id: SHAPE_CONTEXT_MENU_ITEM_IDS.copy,
+ *   render: (ctx) => <button onClick={ctx.copy}>Copy shape ids</button>,
+ * };
+ * ```
+ */
+type ShapeContextMenuItem = {
+    /** Stable id used for merge-by-id replacement and ordering. */
+    id: string;
+    /** Render the item using the current selection and built-in menu actions. */
+    render: (ctx: ShapeContextMenuRenderContext) => ReactNode;
+};
+/**
+ * Props for {@link ShapeContextMenu}.
+ *
+ * Use `itemContributions` for small add-or-replace customizations, `items` when you
+ * want to own the exact base list, and `children` when you want custom contents inside
+ * the floating menu shell. App code usually customizes the menu through
+ * {@link VectorViewportProps.contextMenuItems} instead of rendering this component directly.
+ */
+type ShapeContextMenuProps = {
+    /** Viewport client coordinates (from `clientX` / `clientY`). */
+    x: number;
+    y: number;
+    /** Selected item ids targeted by this menu. */
+    selectedIds?: readonly string[];
+    /** Selected scene items targeted by this menu. */
+    selectedItems?: readonly VectorSceneItem[];
+    /** When true, all selected items are locked and the built-in action is "unlock". */
+    allSelectedLocked?: boolean;
+    onClose: () => void;
+    onToggleLock: () => void;
+    onCut: () => void;
+    onCopy: () => void;
+    onBringToFront: () => void;
+    onBringForward: () => void;
+    onSendBackward: () => void;
+    onSendToBack: () => void;
+    onDuplicate: () => void;
+    onDelete: () => void;
+    /**
+     * Exact base menu item list. Omit to use Canvu's built-in shape actions.
+     *
+     * This replaces the default base list; use `itemContributions` for add-or-replace
+     * customization without duplicating defaults.
+     */
+    items?: readonly ShapeContextMenuItem[];
+    /**
+     * Menu item additions or replacements merged by `id`.
+     *
+     * Matching ids replace the base item in place, new ids append, and later contributions win.
+     * Ignored when `children` are provided because custom children render exact markup.
+     */
+    itemContributions?: readonly ShapeContextMenuItem[];
+    /**
+     * Full custom menu contents. JSX nodes are rendered exactly; a render function receives
+     * the same selection/action context as menu items. Default items are not rendered.
+     */
+    children?: ReactNode | ((ctx: ShapeContextMenuRenderContext) => ReactNode);
+};
+/**
+ * Floating menu for shape actions (reorder, clipboard, lock, delete).
+ *
+ * This is a web-only React component. It renders in a portal, closes on Escape or
+ * outside click, and composes menu rows by `id` unless exact `children` are provided.
+ */
+declare function ShapeContextMenu({ x, y, selectedIds, selectedItems, allSelectedLocked, onClose, onToggleLock, onCut, onCopy, onBringToFront, onBringForward, onSendBackward, onSendToBack, onDuplicate, onDelete, items, itemContributions, children, }: ShapeContextMenuProps): react.ReactPortal | null;
+
 type ActiveToolStyle = StrokeStyle & {
     toolKind: "draw" | "marker" | "text" | "rect" | "ellipse" | "architectural-cloud" | "line" | "arrow";
     label?: string;
@@ -179,6 +348,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.
  *
@@ -338,8 +548,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;
 };
@@ -361,6 +573,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;
@@ -427,6 +648,25 @@ type VectorViewportProps = {
      * Use this to reposition or theme the default left-side style panel without replacing it.
      */
     selectionInspectorProps?: Pick<VectorSelectionInspectorProps, "className" | "style">;
+    /**
+     * Shape context-menu additions or replacements merged by `id` after built-ins and plugins.
+     *
+     * Use this for app-level customization such as replacing
+     * `SHAPE_CONTEXT_MENU_ITEM_IDS.copy` or adding one extra command. Matching ids
+     * replace earlier items in place; new ids append. For exact full replacement,
+     * use `contextMenu`.
+     */
+    contextMenuItems?: readonly ShapeContextMenuItem[];
+    /**
+     * Full replacement for the shape context menu, or `null` to disable it.
+     *
+     * The render context includes the merged item list so a custom renderer can reuse
+     * Canvu/plugin/app item composition while owning all markup. Omit this prop to
+     * render the built-in {@link ShapeContextMenu}.
+     */
+    contextMenu?: ((ctx: ShapeContextMenuRenderContext & {
+        items: readonly ShapeContextMenuItem[];
+    }) => ReactNode) | null;
     /**
      * Plug and play board extensions.
      *
@@ -524,6 +764,13 @@ type CanvasPluginContribution = {
     tools?: readonly VectorToolDefinition[];
     /** Transform the resolved tool list (reorder, replace, or filter existing tools). */
     toolTransform?: (tools: VectorToolDefinition[]) => VectorToolDefinition[];
+    /**
+     * Additional shape context-menu items merged by id after Canvu's built-ins.
+     *
+     * Matching ids replace existing items in place, new ids append, and plugin order
+     * determines tie-breaking before app-level `VectorViewport.contextMenuItems`.
+     */
+    contextMenuItems?: readonly ShapeContextMenuItem[];
     /** Multiple custom placements contributed by plugins; the active one is resolved by `toolId`. */
     customPlacements?: readonly CustomShapePlacementOptions[];
     /** Simple viewport prop overrides owned by the plugin runtime. */
@@ -624,4 +871,4 @@ declare function useCanvuResolvedTools(): VectorToolDefinition[];
  */
 declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
 
-export { VectorViewport as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type VectorViewportHandle as D, type VectorViewportProps as E, createCanvuPlugin as F, getBoardPositionStyle as G, useCanvuChromeContext as H, useCanvuDocumentContext as I, useCanvuPluginContext as J, useCanvuPluginContribution as K, useCanvuResolvedTools as L, useCanvuViewportContext as M, type PlacementPreview as P, 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 SelectModeItemClickResult as v, type VectorCanvasSpacePosition as w, type VectorItemsChangeInfo as x, type VectorItemsChangeMotive as y, type VectorSelectionInspectorProps as z };
+export { type ShapeContextMenuItem as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type ShapeContextMenuProps as D, type ShapeContextMenuRenderContext as E, type VectorCanvasSpacePosition as F, type VectorItemsChangeInfo as G, type VectorItemsChangeMotive as H, type VectorSelectionInspectorProps as I, VectorViewport as J, type VectorViewportHandle as K, type VectorViewportProps as L, createCanvuPlugin as M, getBoardPositionStyle as N, useCanvuChromeContext as O, type PlacementPreview as P, useCanvuDocumentContext as Q, type ReadOnlyInteractionOptions as R, SHAPE_CONTEXT_MENU_ITEM_IDS as S, useCanvuPluginContext as T, useCanvuPluginContribution as U, type VectorToolDefinition as V, type WorldPointerDownDetail as W, useCanvuResolvedTools as X, useCanvuViewportContext as Y, 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 SelectModeItemClickDetail as x, type SelectModeItemClickResult as y, ShapeContextMenu as z };

package/dist/{types-Ce4-OZbd.d.cts → types-D5d-3dvz.d.cts}

@@ -118,6 +118,175 @@ 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);
+
+/**
+ * Stable ids for Canvu's built-in shape context-menu items.
+ *
+ * Use these with `ShapeContextMenu.itemContributions`, `VectorViewport.contextMenuItems`,
+ * or plugin `contextMenuItems` when replacing a default item without relying on magic strings.
+ */
+declare const SHAPE_CONTEXT_MENU_ITEM_IDS: {
+    readonly cut: "cut";
+    readonly copy: "copy";
+    readonly duplicate: "duplicate";
+    readonly reorderDivider: "reorder-divider";
+    readonly bringToFront: "bring-to-front";
+    readonly bringForward: "bring-forward";
+    readonly sendBackward: "send-backward";
+    readonly sendToBack: "send-to-back";
+    readonly lockDivider: "lock-divider";
+    readonly toggleLock: "toggle-lock";
+    readonly delete: "delete";
+};
+/**
+ * Runtime data and built-in commands exposed to shape context-menu item renderers.
+ *
+ * Use this for small menu item customizations and plugin actions. The built-in action
+ * functions already close the menu after running, matching Canvu's default menu behavior.
+ * For full viewport-level replacement, use {@link VectorViewportProps.contextMenu}.
+ */
+type ShapeContextMenuRenderContext = {
+    /** Viewport client coordinates where the menu opened. */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Selected item ids targeted by this menu. */
+    selectedIds: readonly string[];
+    /** Selected scene items targeted by this menu. */
+    selectedItems: readonly VectorSceneItem[];
+    /** True when every selected item is locked. */
+    allSelectedLocked: boolean;
+    /** True when at least one selected item is locked. */
+    anySelectedLocked: boolean;
+    /** Close the floating context menu without running an action. */
+    close: () => void;
+    /** Cut the selected items to Canvu's internal clipboard, then close the menu. */
+    cut: () => void;
+    /** Copy the selected items to Canvu's internal clipboard, then close the menu. */
+    copy: () => void;
+    /** Duplicate selected items, then close the menu. */
+    duplicate: () => void;
+    /** Toggle lock state for selected items, then close the menu. */
+    toggleLock: () => void;
+    /** Move selected items above all siblings, then close the menu. */
+    bringToFront: () => void;
+    /** Move selected items forward one layer, then close the menu. */
+    bringForward: () => void;
+    /** Move selected items backward one layer, then close the menu. */
+    sendBackward: () => void;
+    /** Move selected items behind all siblings, then close the menu. */
+    sendToBack: () => void;
+    /** Delete selected items, then close the menu. */
+    delete: () => void;
+    /** Alias for {@link ShapeContextMenuRenderContext.delete}. */
+    deleteSelection: () => void;
+};
+/**
+ * One renderable context-menu row, divider, or custom block.
+ *
+ * Items compose by `id`: passing an item with a built-in id such as
+ * `SHAPE_CONTEXT_MENU_ITEM_IDS.copy` replaces that item in place, while new ids append.
+ *
+ * @example
+ * ```tsx
+ * const replaceCopy = {
+ *   id: SHAPE_CONTEXT_MENU_ITEM_IDS.copy,
+ *   render: (ctx) => <button onClick={ctx.copy}>Copy shape ids</button>,
+ * };
+ * ```
+ */
+type ShapeContextMenuItem = {
+    /** Stable id used for merge-by-id replacement and ordering. */
+    id: string;
+    /** Render the item using the current selection and built-in menu actions. */
+    render: (ctx: ShapeContextMenuRenderContext) => ReactNode;
+};
+/**
+ * Props for {@link ShapeContextMenu}.
+ *
+ * Use `itemContributions` for small add-or-replace customizations, `items` when you
+ * want to own the exact base list, and `children` when you want custom contents inside
+ * the floating menu shell. App code usually customizes the menu through
+ * {@link VectorViewportProps.contextMenuItems} instead of rendering this component directly.
+ */
+type ShapeContextMenuProps = {
+    /** Viewport client coordinates (from `clientX` / `clientY`). */
+    x: number;
+    y: number;
+    /** Selected item ids targeted by this menu. */
+    selectedIds?: readonly string[];
+    /** Selected scene items targeted by this menu. */
+    selectedItems?: readonly VectorSceneItem[];
+    /** When true, all selected items are locked and the built-in action is "unlock". */
+    allSelectedLocked?: boolean;
+    onClose: () => void;
+    onToggleLock: () => void;
+    onCut: () => void;
+    onCopy: () => void;
+    onBringToFront: () => void;
+    onBringForward: () => void;
+    onSendBackward: () => void;
+    onSendToBack: () => void;
+    onDuplicate: () => void;
+    onDelete: () => void;
+    /**
+     * Exact base menu item list. Omit to use Canvu's built-in shape actions.
+     *
+     * This replaces the default base list; use `itemContributions` for add-or-replace
+     * customization without duplicating defaults.
+     */
+    items?: readonly ShapeContextMenuItem[];
+    /**
+     * Menu item additions or replacements merged by `id`.
+     *
+     * Matching ids replace the base item in place, new ids append, and later contributions win.
+     * Ignored when `children` are provided because custom children render exact markup.
+     */
+    itemContributions?: readonly ShapeContextMenuItem[];
+    /**
+     * Full custom menu contents. JSX nodes are rendered exactly; a render function receives
+     * the same selection/action context as menu items. Default items are not rendered.
+     */
+    children?: ReactNode | ((ctx: ShapeContextMenuRenderContext) => ReactNode);
+};
+/**
+ * Floating menu for shape actions (reorder, clipboard, lock, delete).
+ *
+ * This is a web-only React component. It renders in a portal, closes on Escape or
+ * outside click, and composes menu rows by `id` unless exact `children` are provided.
+ */
+declare function ShapeContextMenu({ x, y, selectedIds, selectedItems, allSelectedLocked, onClose, onToggleLock, onCut, onCopy, onBringToFront, onBringForward, onSendBackward, onSendToBack, onDuplicate, onDelete, items, itemContributions, children, }: ShapeContextMenuProps): react.ReactPortal | null;
+
 type ActiveToolStyle = StrokeStyle & {
     toolKind: "draw" | "marker" | "text" | "rect" | "ellipse" | "architectural-cloud" | "line" | "arrow";
     label?: string;
@@ -179,6 +348,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.
  *
@@ -338,8 +548,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;
 };
@@ -361,6 +573,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;
@@ -427,6 +648,25 @@ type VectorViewportProps = {
      * Use this to reposition or theme the default left-side style panel without replacing it.
      */
     selectionInspectorProps?: Pick<VectorSelectionInspectorProps, "className" | "style">;
+    /**
+     * Shape context-menu additions or replacements merged by `id` after built-ins and plugins.
+     *
+     * Use this for app-level customization such as replacing
+     * `SHAPE_CONTEXT_MENU_ITEM_IDS.copy` or adding one extra command. Matching ids
+     * replace earlier items in place; new ids append. For exact full replacement,
+     * use `contextMenu`.
+     */
+    contextMenuItems?: readonly ShapeContextMenuItem[];
+    /**
+     * Full replacement for the shape context menu, or `null` to disable it.
+     *
+     * The render context includes the merged item list so a custom renderer can reuse
+     * Canvu/plugin/app item composition while owning all markup. Omit this prop to
+     * render the built-in {@link ShapeContextMenu}.
+     */
+    contextMenu?: ((ctx: ShapeContextMenuRenderContext & {
+        items: readonly ShapeContextMenuItem[];
+    }) => ReactNode) | null;
     /**
      * Plug and play board extensions.
      *
@@ -524,6 +764,13 @@ type CanvasPluginContribution = {
     tools?: readonly VectorToolDefinition[];
     /** Transform the resolved tool list (reorder, replace, or filter existing tools). */
     toolTransform?: (tools: VectorToolDefinition[]) => VectorToolDefinition[];
+    /**
+     * Additional shape context-menu items merged by id after Canvu's built-ins.
+     *
+     * Matching ids replace existing items in place, new ids append, and plugin order
+     * determines tie-breaking before app-level `VectorViewport.contextMenuItems`.
+     */
+    contextMenuItems?: readonly ShapeContextMenuItem[];
     /** Multiple custom placements contributed by plugins; the active one is resolved by `toolId`. */
     customPlacements?: readonly CustomShapePlacementOptions[];
     /** Simple viewport prop overrides owned by the plugin runtime. */
@@ -624,4 +871,4 @@ declare function useCanvuResolvedTools(): VectorToolDefinition[];
  */
 declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
 
-export { VectorViewport as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type VectorViewportHandle as D, type VectorViewportProps as E, createCanvuPlugin as F, getBoardPositionStyle as G, useCanvuChromeContext as H, useCanvuDocumentContext as I, useCanvuPluginContext as J, useCanvuPluginContribution as K, useCanvuResolvedTools as L, useCanvuViewportContext as M, type PlacementPreview as P, 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 SelectModeItemClickResult as v, type VectorCanvasSpacePosition as w, type VectorItemsChangeInfo as x, type VectorItemsChangeMotive as y, type VectorSelectionInspectorProps as z };
+export { type ShapeContextMenuItem as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type ShapeContextMenuProps as D, type ShapeContextMenuRenderContext as E, type VectorCanvasSpacePosition as F, type VectorItemsChangeInfo as G, type VectorItemsChangeMotive as H, type VectorSelectionInspectorProps as I, VectorViewport as J, type VectorViewportHandle as K, type VectorViewportProps as L, createCanvuPlugin as M, getBoardPositionStyle as N, useCanvuChromeContext as O, type PlacementPreview as P, useCanvuDocumentContext as Q, type ReadOnlyInteractionOptions as R, SHAPE_CONTEXT_MENU_ITEM_IDS as S, useCanvuPluginContext as T, useCanvuPluginContribution as U, type VectorToolDefinition as V, type WorldPointerDownDetail as W, useCanvuResolvedTools as X, useCanvuViewportContext as Y, 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 SelectModeItemClickDetail as x, type SelectModeItemClickResult as y, ShapeContextMenu as z };

package/package.json

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