canvu-react 0.3.6 → 0.3.8

package/dist/types-CpqlbbCP.d.ts

@@ -0,0 +1,691 @@
+import * as react from 'react';
+import { CSSProperties, ReactNode, RefObject } from 'react';
+import { V as VectorSceneItem, R as Rect } from './types-CB0TZZuk.js';
+import { C as Camera2D } from './camera-KwCYYPhm.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { S as StrokeStyle } from './shape-builders-DTYvub8W.js';
+
+/**
+ * Kind of binary selected through the built-in canvu asset ingestion flow.
+ *
+ * Use this to branch your backend upload logic when images and PDFs should be
+ * stored differently.
+ */
+type VectorViewportAssetKind = "image" | "pdf";
+/**
+ * Original browser `File` intercepted from the built-in asset flow.
+ *
+ * This is the high-level hook for apps that want canvu to keep its native file
+ * UX while still uploading the raw binary to their backend or object storage.
+ *
+ * The same request shape is also reused by
+ * {@link ingestAssetFilesToSceneItems}, so custom import flows and the native
+ * viewport UX can share one backend contract.
+ */
+type VectorViewportAssetUploadRequest = {
+    /** Original browser file before canvu converts it into scene items. */
+    file: File;
+    /** High-level bucket for routing image vs PDF upload behavior. */
+    kind: VectorViewportAssetKind;
+};
+/**
+ * Persisted metadata returned by a custom asset upload.
+ *
+ * The returned `pluginData` is shallow-merged into every `VectorSceneItem`
+ * created from the uploaded file, making it available to custom persistence
+ * adapters and later hydration flows.
+ *
+ * @example
+ * ```ts
+ * const assetStore: VectorViewportAssetStore = {
+ *   async upload({ file, kind }) {
+ *     const form = new FormData();
+ *     form.append("file", file);
+ *     form.append("kind", kind);
+ *
+ *     const response = await fetch("/api/canvu/assets", {
+ *       method: "POST",
+ *       body: form,
+ *     });
+ *
+ *     const asset = await response.json();
+ *     return {
+ *       pluginData: {
+ *         assetId: asset.id,
+ *         assetKey: asset.key,
+ *         mimeType: file.type,
+ *       },
+ *     };
+ *   },
+ *   async resolve({ assetIds }) {
+ *     const response = await fetch("/api/canvu/assets/resolve", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify({ assetIds }),
+ *     });
+ *
+ *     return response.json();
+ *   },
+ * };
+ * ```
+ */
+type VectorViewportAssetUploadResult = {
+    /**
+     * Opaque persisted metadata attached to created items.
+     *
+     * Use this for asset ids, bucket keys, original file names, or any backend
+     * reference needed to rehydrate the binary later from your own persistence
+     * adapter.
+     */
+    pluginData?: VectorSceneItem["pluginData"];
+};
+/**
+ * Request to resolve persisted asset ids back into runtime URLs.
+ *
+ * This is useful inside custom persistence adapters when you want to rehydrate
+ * signed URLs or CDN URLs after loading a snapshot.
+ */
+type VectorViewportAssetResolveRequest = {
+    assetIds: string[];
+};
+/**
+ * Runtime URL payload returned by a custom asset resolver.
+ */
+type VectorViewportAssetResolveResult = Record<string, {
+    url: string;
+    thumbnailUrl?: string;
+}>;
+/**
+ * High-level hook for apps that want to persist raw binaries out-of-band while
+ * keeping canvu's built-in file UX.
+ *
+ * `upload` is used by the built-in file picker / drag-and-drop flow and by
+ * {@link ingestAssetFilesToSceneItems}. `resolve` is optional for custom
+ * persistence adapters and future hydration flows.
+ */
+type VectorViewportAssetStore = {
+    upload: (request: VectorViewportAssetUploadRequest) => Promise<VectorViewportAssetUploadResult | undefined>;
+    resolve?: (request: VectorViewportAssetResolveRequest) => Promise<VectorViewportAssetResolveResult>;
+};
+
+type CanvuChromeActiveToolStyle = StrokeStyle & {
+    toolKind: "draw" | "marker";
+    label?: string;
+};
+type CanvuChromeSelectionStyleChange = (patch: {
+    stroke: string;
+    strokeWidth: number;
+    strokeOpacity?: number;
+}) => void;
+/**
+ * Runtime data and handlers shared with floating board chrome (e.g. {@link NavMenu},
+ * {@link VectorSelectionInspector}). Populated by `VectorViewport` and consumed via
+ * {@link useCanvuChromeContext}.
+ */
+type CanvuChromeContextValue = {
+    camera: Camera2D | null;
+    viewportWidth: number;
+    viewportHeight: number;
+    items: readonly VectorSceneItem[];
+    selectedItems: readonly VectorSceneItem[];
+    interactive: boolean;
+    canEditSelection: boolean;
+    activeToolStyle: CanvuChromeActiveToolStyle | null;
+    onSelectionStyleChange: CanvuChromeSelectionStyleChange | null;
+    zoomPercent: number;
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onUndo: () => void;
+    onRedo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    onRequestRender: () => void;
+};
+declare const CanvuChromeContext: react.Context<CanvuChromeContextValue | null>;
+/** Returns the current chrome context or `null` when used outside `VectorViewport`. */
+declare function useCanvuChromeContext(): CanvuChromeContextValue | null;
+
+type PlacementPreview = {
+    kind: "rect" | "ellipse";
+    rect: Rect;
+}
+/** Multi-select drag (world rect), like image crop / rubber-band selection. */
+ | {
+    kind: "marquee";
+    rect: Rect;
+} | {
+    kind: "line" | "arrow";
+    start: {
+        x: number;
+        y: number;
+    };
+    end: {
+        x: number;
+        y: number;
+    };
+} | {
+    kind: "stroke";
+    tool: "draw" | "marker" | "laser";
+    points: {
+        x: number;
+        y: number;
+    }[];
+};
+
+type ActiveToolStyle = StrokeStyle & {
+    toolKind: "draw" | "marker";
+    label?: string;
+};
+/**
+ * Color + stroke-width inspector for the current selection (or active drawing tool style).
+ * When rendered inside `VectorViewport` (e.g. via the `selectionInspector` slot), `items`,
+ * `activeToolStyle`, and `onChange` default to values from {@link CanvuChromeContext};
+ * pass any prop to override.
+ */
+type VectorSelectionInspectorProps = {
+    /** Selected items that support stroke/fill styling (caller may filter). */
+    items?: readonly VectorSceneItem[];
+    /** Optional active tool style shown even without a selection. */
+    activeToolStyle?: ActiveToolStyle | null;
+    /** Apply stroke / width / opacity to every item in `items`. */
+    onChange?: CanvuChromeSelectionStyleChange;
+    /** Anchor preset. Defaults to top-left. */
+    position?: BoardComponentPosition;
+    /** Distance (px) from anchored edges. @default 12 */
+    inset?: number;
+    /** @default 24 */
+    zIndex?: number;
+    className?: string;
+    /** Merged on top of position-derived styles for custom tweaks. */
+    style?: CSSProperties;
+};
+/**
+ * Color + stroke width for the current selection. Supports multiple selected shapes: one change applies to all.
+ */
+declare function VectorSelectionInspector({ items: itemsProp, activeToolStyle: activeToolStyleProp, onChange: onChangeProp, position, inset, zIndex, className, style, }: VectorSelectionInspectorProps): react_jsx_runtime.JSX.Element | null;
+
+type VectorCanvasSlotProps = {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * Anchor presets for floating board components.
+ *
+ * Names are `<edge>-<position-along-edge>`:
+ * - `top-*` / `bottom-*` anchor to the top or bottom edge.
+ * - `left-*` / `right-*` anchor to the left or right edge.
+ *
+ * Corner aliases are equivalent (e.g. `top-left` and `left-top` resolve to the same anchor),
+ * but kept distinct so callers can pick whichever reads best in their layout (a vertical
+ * strip might prefer `left-top`; a horizontal strip prefers `top-left`).
+ */
+type BoardComponentPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "left-top" | "left-center" | "left-bottom" | "right-top" | "right-center" | "right-bottom" | "center" | "fill";
+/** @deprecated Use {@link BoardComponentPosition}. */
+type VectorCanvasSpacePosition = BoardComponentPosition;
+/**
+ * Compute absolute-position CSS for a board component anchor preset.
+ * Returns `position`, `zIndex`, and the relevant edge offsets / transforms.
+ * Callers merge the result with their own style/className overrides.
+ */
+declare function getBoardPositionStyle(position: BoardComponentPosition, inset?: number, zIndex?: number): CSSProperties;
+type VectorCanvasSpaceProps = VectorCanvasSlotProps & {
+    position?: BoardComponentPosition;
+    /** @default 12 */
+    inset?: number;
+    /** @default 40 */
+    zIndex?: number;
+    /** Pointer events value on the content wrapper. @default "auto" */
+    contentPointerEvents?: CSSProperties["pointerEvents"];
+};
+/**
+ * Full-viewport column shell for a vector canvas (header + body with stage).
+ * Use with {@link VectorCanvasBody}, {@link VectorCanvasMain}. Pass `toolbar` on {@link VectorViewport};
+ * Compose the floating tool strip with {@link VectorCanvasToolbar} around {@link VectorToolbar} (see example below).
+ */
+declare function VectorCanvasRoot({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
+/** Optional top chrome (title, hints, toggles). */
+declare function VectorCanvasHeader({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
+/** Fills remaining space below the header (typically one {@link VectorCanvasMain}). */
+declare function VectorCanvasBody({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
+/**
+ * Stretch area for {@link VectorViewport} (or any child that should fill the stage).
+ */
+declare function VectorCanvasMain({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
+/**
+ * Flex child that fills {@link VectorCanvasMain} and gives {@link VectorViewport} a bounded height
+ * (white surface by default). Omit if you set the background on `Main` or the viewport yourself.
+ */
+declare function VectorCanvasViewportSurface({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
+type VectorCanvasToolbarProps = {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Anchor preset. @default "bottom-center" */
+    position?: BoardComponentPosition;
+    /** Distance (px) from the anchored edge(s). @default 12 */
+    inset?: number;
+    /** @default 30 */
+    zIndex?: number;
+};
+/**
+ * Floating strip anchor for {@link VectorToolbar} or custom controls. Defaults to bottom-center.
+ * Renders `pointer-events: none` on the shell and `auto` on children so the canvas keeps receiving hits outside the bar.
+ * Pass as the `toolbar` prop of `VectorViewport`; pick a different `position` for top / side anchoring.
+ * Z-index defaults to 30 so the strip stays above zoom controls.
+ */
+declare function VectorCanvasToolbar({ children, className, style, position, inset, zIndex, }: VectorCanvasToolbarProps): react_jsx_runtime.JSX.Element;
+/**
+ * Absolute canvas-aligned space for floating UI such as chats, rosters, inspectors, and overlays.
+ * Use this instead of ad-hoc wrapper divs or plugin hosts when a feature can be expressed as React nodes.
+ */
+declare function VectorCanvasSpace({ children, className, style, position, inset, zIndex, contentPointerEvents, }: VectorCanvasSpaceProps): react_jsx_runtime.JSX.Element;
+/**
+ * Namespaced layout primitives for composing a vector canvas shell without ad-hoc wrapper divs.
+ *
+ * @example
+ * ```tsx
+ * <VectorCanvas.Root>
+ *   <VectorCanvas.Header>…</VectorCanvas.Header>
+ *   <VectorCanvas.Body>
+ *     <VectorCanvas.Main>
+ *       <VectorCanvas.ViewportSurface>
+ *         <VectorViewport
+ *           toolbar={
+ *             <VectorCanvas.Toolbar>
+ *               <VectorToolbar … />
+ *             </VectorCanvas.Toolbar>
+ *           }
+ *           …
+ *         />
+ *       </VectorCanvas.ViewportSurface>
+ *     </VectorCanvas.Main>
+ *   </VectorCanvas.Body>
+ * </VectorCanvas.Root>
+ * ```
+ */
+declare const VectorCanvas: {
+    readonly Root: typeof VectorCanvasRoot;
+    readonly Header: typeof VectorCanvasHeader;
+    readonly Body: typeof VectorCanvasBody;
+    readonly Main: typeof VectorCanvasMain;
+    readonly ViewportSurface: typeof VectorCanvasViewportSurface;
+    readonly Toolbar: typeof VectorCanvasToolbar;
+    readonly Space: typeof VectorCanvasSpace;
+    readonly NavMenu: typeof NavMenu;
+    readonly SelectionInspector: typeof VectorSelectionInspector;
+};
+
+/**
+ * Floating bottom-bar combining zoom controls, undo/redo, and an expandable minimap.
+ * When rendered inside `VectorViewport` (e.g. via the `navMenu` slot), data props default
+ * to values from {@link CanvuChromeContext}; pass any prop to override.
+ */
+type NavMenuProps = {
+    camera?: Camera2D;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    items?: readonly VectorSceneItem[];
+    zoomPercent?: number;
+    onZoomIn?: () => void;
+    onZoomOut?: () => void;
+    onUndo?: () => void;
+    onRedo?: () => void;
+    canUndo?: boolean;
+    canRedo?: boolean;
+    onRequestRender?: () => void;
+    /** Anchor preset. Defaults to bottom-left. */
+    position?: BoardComponentPosition;
+    /** Distance (px) from anchored edges. @default 12 */
+    inset?: number;
+    /** @default 23 */
+    zIndex?: number;
+    className?: string;
+    /** Merged on top of position-derived styles for custom tweaks. */
+    style?: CSSProperties;
+};
+declare function NavMenu({ camera: cameraProp, viewportWidth: viewportWidthProp, viewportHeight: viewportHeightProp, items: itemsProp, zoomPercent: zoomPercentProp, onZoomIn: onZoomInProp, onZoomOut: onZoomOutProp, onUndo: onUndoProp, onRedo: onRedoProp, canUndo: canUndoProp, canRedo: canRedoProp, onRequestRender: onRequestRenderProp, position, inset, zIndex, className, style, }: NavMenuProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Describes one entry in {@link VectorToolbar}.
+ */
+type VectorToolDefinition = {
+    /** Stable id passed to `onChange` (e.g. `"hand"`, `"rect"`). */
+    id: string;
+    /** Visible label and default accessible name. */
+    label: string;
+    /**
+     * English (or other) name for the hover tooltip only. Defaults to {@link label}.
+     */
+    tooltipLabel?: string;
+    /** Optional icon; if omitted, the label text is shown. */
+    icon?: ReactNode;
+    /** Shown in `aria-keyshortcuts` when set (informational only). */
+    shortcutHint?: string;
+    /** Extra `aria-label` when you need more than `label`. */
+    ariaLabel?: string;
+};
+
+type RealtimeConnectionState = "connecting" | "connected" | "reconnecting" | "offline" | "error";
+/**
+ * In-progress freehand stroke from a remote peer (before it becomes a committed `VectorSceneItem`).
+ */
+type RemotePresenceMarkupStroke = {
+    readonly points: readonly {
+        readonly x: number;
+        readonly y: number;
+    }[];
+    readonly tool: "draw" | "pencil" | "brush" | "marker" | "laser";
+};
+/**
+ * One connected participant. Your WebSocket layer maps server messages → this shape;
+ * {@link VectorViewport} renders it in world space.
+ */
+type RemotePresencePeer = {
+    readonly id: string;
+    /** Stable color for cursor + stroke (e.g. `#2563eb`). If omitted, a hue is derived from `id`. */
+    readonly color?: string;
+    /** Short display name near the cursor. */
+    readonly displayName?: string;
+    /** Optional profile image / avatar URL for richer collaboration UIs. */
+    readonly image?: string;
+    /** Last known pointer position in **world** units, or `null` if off-canvas / idle. */
+    readonly cursor: {
+        readonly x: number;
+        readonly y: number;
+    } | null;
+    /** Optional live stroke while the peer is drawing (same semantics as local placement preview). */
+    readonly markupStroke?: RemotePresenceMarkupStroke | null;
+    /** Connection-scoped id when collaboration is backed by a realtime session. */
+    readonly clientId?: string;
+    /** Stable participant identity when collaboration is backed by a realtime session. */
+    readonly peerId?: string;
+    /** Room/session id when provided by the collaboration transport. */
+    readonly roomId?: string;
+    /** Lifecycle timestamps in epoch milliseconds. */
+    readonly joinedAt?: number;
+    readonly lastSeenAt?: number;
+    /** Distinguishes the local participant from remote peers. */
+    readonly isSelf?: boolean;
+    /** Optional active tool hint for richer presence UIs. */
+    readonly activeTool?: string;
+    /** Session-level connection state, useful for richer rosters. */
+    readonly connectionState?: RealtimeConnectionState;
+};
+type PresenceOverlayRenderContext = {
+    camera: Camera2D;
+    /** Bumps when the camera changes so overlays stay aligned with the scene. */
+    cameraVersion: number;
+};
+
+type WorldPointerDownDetail = {
+    worldX: number;
+    worldY: number;
+    toolId: string;
+    pointerType: string;
+};
+/**
+ * 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}.
+ */
+type VectorViewportHandle = {
+    /** The live camera instance, or `null` before mount / after unmount. */
+    getCamera: () => Camera2D | null;
+    /**
+     * Re-run SVG + overlay after changing `x`, `y`, or `zoom` on the camera from {@link getCamera}.
+     */
+    requestRender: () => void;
+    /** CSS pixel size of the scene surface (`clientWidth` / `clientHeight`). */
+    getViewportSize: () => {
+        width: number;
+        height: number;
+    };
+    /**
+     * Sets pan/zoom so `worldRect` fits in the viewport with optional margin (fraction of rect size per side, default `0.08`).
+     */
+    fitWorldRect: (worldRect: Rect, options?: {
+        padding?: number;
+    }) => void;
+};
+/** Drag-to-place a custom shape (same interaction as rectangle). Use with `createCustomShapeItem` from `canvu`. */
+type CustomShapePlacementOptions = {
+    toolId: string;
+    createItem: (args: {
+        id: string;
+        bounds: Rect;
+    }) => VectorSceneItem;
+};
+type VectorViewportProps = {
+    /** Vector items to draw (SVG fragments). */
+    items: readonly VectorSceneItem[];
+    className?: string;
+    /** Accessible name for the application region. */
+    ariaLabel: string;
+    /**
+     * When `applePencilNav` is true, used with `attachApplePencilNavigation` to decide
+     * when finger touches navigate (e.g. `"hand"` vs `"draw"`).
+     */
+    toolId?: string;
+    /** Enable Apple Pencil vs finger split (optional). */
+    applePencilNav?: boolean;
+    /**
+     * When true, selection, drag-to-move, resize handles, and drag-to-create shapes are enabled.
+     * Requires `onItemsChange` to persist mutations.
+     */
+    interactive?: boolean;
+    /** Selected item ids (order preserved). Empty = none. */
+    selectedIds?: readonly string[];
+    onSelectionChange?: (ids: string[]) => void;
+    onItemsChange?: (items: VectorSceneItem[]) => void;
+    /**
+     * Fires on primary pointer down on the viewport in **world** coordinates.
+     * Not called when `toolId` is `"hand"` (use that tool for panning).
+     * Ignored when `interactive` is true (placement uses drag-to-define).
+     */
+    onWorldPointerDown?: (detail: WorldPointerDownDetail) => void;
+    /**
+     * Floating UI above the scene. Compose with `VectorCanvas.Toolbar` + {@link VectorToolbar}
+     * so the strip anchors at the bottom center (`data-slot="vector-canvas-toolbar"`).
+     */
+    toolbar?: ReactNode;
+    /**
+     * Floating bottom-left zoom / undo / minimap bar. Omit to render the default `NavMenu`.
+     * Pass `<VectorCanvas.NavMenu position="..." />` to relocate or style it. Pass `null` to hide it.
+     */
+    navMenu?: ReactNode | null;
+    /**
+     * Floating selection / active-tool style inspector. Omit to render the default `VectorSelectionInspector`.
+     * Pass `<VectorCanvas.SelectionInspector position="..." />` to relocate or style it. Pass `null` to hide it.
+     */
+    selectionInspector?: ReactNode | null;
+    /**
+     * Props forwarded to the built-in {@link VectorSelectionInspector}.
+     *
+     * Use this to reposition or theme the default left-side style panel without replacing it.
+     */
+    selectionInspectorProps?: Pick<VectorSelectionInspectorProps, "className" | "style">;
+    /**
+     * Plug and play board extensions.
+     *
+     * First-party plugins such as `chatbotPlugin(...)` and `realtimeCollaborationPlugin(...)`
+     * should be passed here. Advanced authors can create their own plugins with `createCanvuPlugin(...)`.
+     */
+    plugins?: readonly CanvasPlugin[];
+    /**
+     * Called after the scene/camera redraw (pan, zoom, items update, or {@link VectorViewportHandle.requestRender}).
+     * Can fire often during gestures — throttle/debounce if needed.
+     */
+    onCameraChange?: () => void;
+    /**
+     * When `interactive` is true, enables drag (or tap) placement for `toolId`, like built-in shapes.
+     * Implement `createItem` with `createCustomShapeItem` from `canvu`.
+     */
+    customPlacement?: CustomShapePlacementOptions;
+    /**
+     * Multiple custom placements contributed by plugins or app code.
+     *
+     * When both `customPlacement` and `customPlacements` are provided, they are combined and the active
+     * placement is resolved by the current `toolId`.
+     */
+    customPlacements?: readonly CustomShapePlacementOptions[];
+    /**
+     * Optional asset persistence bridge for the built-in image/file flow.
+     *
+     * Use this when you want canvu to keep its native file picker and drag-and-drop
+     * behavior, while also uploading the original binary to your backend or bucket.
+     * Returned `pluginData` is persisted on every created item from that file.
+     *
+     * This is a high-level persistence hook. For fully custom ingestion UIs or
+     * imports that start outside the viewport, prefer
+     * `ingestAssetFilesToSceneItems(...)` so your app reuses the same pipeline as
+     * canvu's native file tool.
+     */
+    assetStore?: VectorViewportAssetStore;
+    /**
+     * When false (default), finishing a draw/place/erase gesture requests switching back to `autoResetToolTo`.
+     * Use with controlled tool state (`onToolChangeRequest`) to keep "select-after-use" behavior.
+     */
+    toolLocked?: boolean;
+    /** Tool id requested after one-shot actions complete. Default `"select"`. */
+    autoResetToolTo?: string;
+    /** Called when viewport requests a tool change (e.g. auto reset to select). */
+    onToolChangeRequest?: (toolId: string) => void;
+    /**
+     * Remote participants (cursors + optional in-progress strokes). Renders a world-space overlay
+     * below the local interaction layer. Transport is your app (WebSocket, party server, …).
+     */
+    remotePresence?: readonly RemotePresencePeer[];
+    /**
+     * Replace the default presence layer (e.g. custom cursors). When set, `remotePresence` is not
+     * rendered unless you read it from the parent closure inside this callback.
+     */
+    presenceOverlay?: (ctx: PresenceOverlayRenderContext) => ReactNode;
+    /**
+     * Throttled pointer position in **world** space while the cursor moves over the viewport
+     * (for broadcasting your cursor). Pair with `onWorldPointerLeave`.
+     */
+    onWorldPointerMove?: (world: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Fires when the pointer leaves the viewport (clear your broadcast cursor). */
+    onWorldPointerLeave?: () => void;
+    /**
+     * Fires when drag placement preview updates (rect, line, freehand stroke, …). Use it to broadcast
+     * {@link RemotePresencePeer.markupStroke} for other participants while drawing.
+     */
+    onPlacementPreviewChange?: (preview: PlacementPreview | null) => void;
+};
+/**
+ * Full-viewport vector canvas: SVG rendering + pan/zoom/pinch + optional Apple Pencil navigation.
+ * Pass a `className` that includes `touch-action: none` (e.g. Tailwind `touch-none`) on the viewport.
+ */
+declare const VectorViewport: react.ForwardRefExoticComponent<VectorViewportProps & react.RefAttributes<VectorViewportHandle>>;
+
+type CanvasPluginRenderContext = {
+    /** Live viewport handle when the plugin needs camera or viewport size. */
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+};
+type CanvasPluginItemsChangeMiddlewareContext = {
+    /** Current board items before the pending change is applied. */
+    currentItems: readonly VectorSceneItem[];
+    /** Continue the item change pipeline. */
+    next: NonNullable<VectorViewportProps["onItemsChange"]>;
+    /** Original consumer callback passed to `VectorViewport`. */
+    consumerOnItemsChange?: VectorViewportProps["onItemsChange"];
+    /** Live viewport handle for advanced integrations. */
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+};
+type CanvasPluginContribution = {
+    /** Additional tools injected into the board toolbar/runtime. */
+    tools?: readonly VectorToolDefinition[];
+    /** Transform the resolved tool list (reorder, replace, or filter existing tools). */
+    toolTransform?: (tools: VectorToolDefinition[]) => VectorToolDefinition[];
+    /** 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. */
+    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">>;
+    /** Middleware around `onItemsChange` for collaboration, comments, persistence, etc. */
+    wrapOnItemsChange?: (nextItems: VectorSceneItem[], ctx: CanvasPluginItemsChangeMiddlewareContext) => void;
+};
+type CanvasPluginComponentProps = {
+    /** Stable plugin id so the component can register contributions. */
+    pluginId: string;
+};
+type CanvasPlugin = {
+    /** Stable id, e.g. `canvu.plugin.chatbot`. */
+    id: string;
+    /**
+     * Legacy/simple rendering path for purely visual plugins.
+     *
+     * Prefer `Component` for plugins that need hooks, document integration, tools, or runtime contributions.
+     */
+    render?: (ctx: CanvasPluginRenderContext) => ReactNode;
+    /**
+     * Preferred plugin entrypoint for first-party and advanced plugins.
+     *
+     * The component can use hooks and register contributions through `useCanvuPluginContribution`.
+     */
+    Component?: (props: CanvasPluginComponentProps) => ReactNode;
+};
+type CanvuPluginViewportSnapshot = Pick<VectorViewportProps, "items" | "onItemsChange" | "toolId" | "interactive" | "toolLocked" | "onToolChangeRequest">;
+type CanvuPluginContextValue = {
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+    viewport: CanvuPluginViewportSnapshot;
+    resolvedTools: VectorToolDefinition[];
+    registerContribution: (pluginId: string, contribution: CanvasPluginContribution) => void;
+    unregisterContribution: (pluginId: string) => void;
+};
+declare const CanvuPluginContext: react.Context<CanvuPluginContextValue | null>;
+/**
+ * Creates a typed canvu plugin descriptor.
+ *
+ * Use this helper when authoring custom plugins so your editor can infer the plugin shape
+ * and surface better hover documentation for the returned object.
+ */
+declare function createCanvuPlugin(plugin: CanvasPlugin): CanvasPlugin;
+/**
+ * Returns the low-level canvu plugin runtime context.
+ *
+ * This is an advanced API for custom plugin authors. Prefer first-party plugin factories such as
+ * `chatbotPlugin(...)` and `realtimeCollaborationPlugin(...)` for the common path.
+ */
+declare function useCanvuPluginContext(): CanvuPluginContextValue;
+/**
+ * Returns the current viewport-facing board state exposed to plugins.
+ *
+ * Use this when a custom plugin needs access to items, the active tool, or the consumer's
+ * `onToolChangeRequest` callback.
+ */
+declare function useCanvuViewportContext(): {
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+    viewport: CanvuPluginViewportSnapshot;
+};
+/**
+ * Returns the board document context exposed to plugins.
+ *
+ * This hook is intended for advanced plugins that need to read items or integrate with the board's
+ * `onItemsChange` lifecycle.
+ */
+declare function useCanvuDocumentContext(): {
+    items: readonly VectorSceneItem[];
+    onItemsChange?: VectorViewportProps["onItemsChange"];
+};
+/**
+ * Returns the tool list already resolved by the plugin runtime.
+ *
+ * `VectorToolbar` consumes this automatically when you omit its `tools` prop, so most apps do not
+ * need this hook directly.
+ */
+declare function useCanvuResolvedTools(): VectorToolDefinition[];
+/**
+ * Registers non-visual plugin contributions with the current `VectorViewport` runtime.
+ *
+ * Use this inside `plugin.Component` when you want to inject tools, pointer/camera behavior, or
+ * document middleware without requiring the consumer to wire hooks manually.
+ */
+declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
+
+export { VectorSelectionInspector as A, type BoardComponentPosition as B, type CanvasPlugin as C, type VectorSelectionInspectorProps as D, VectorViewport as E, type VectorViewportAssetResolveRequest as F, type VectorViewportAssetResolveResult as G, type VectorViewportAssetUploadRequest as H, type VectorViewportAssetUploadResult as I, type VectorViewportHandle as J, type VectorViewportProps as K, createCanvuPlugin as L, getBoardPositionStyle as M, NavMenu as N, useCanvuChromeContext as O, type PlacementPreview as P, useCanvuDocumentContext as Q, useCanvuPluginContext as R, useCanvuPluginContribution as S, useCanvuResolvedTools as T, useCanvuViewportContext as U, type VectorViewportAssetKind as V, type WorldPointerDownDetail as W, type RemotePresenceMarkupStroke as X, type RemotePresencePeer as Y, type RealtimeConnectionState as Z, type PresenceOverlayRenderContext as _, type VectorViewportAssetStore as a, type VectorToolDefinition 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 CustomShapePlacementOptions as n, type NavMenuProps as o, VectorCanvas as p, VectorCanvasBody as q, VectorCanvasHeader as r, VectorCanvasMain as s, VectorCanvasRoot as t, type VectorCanvasSlotProps as u, type VectorCanvasSpacePosition as v, type VectorCanvasSpaceProps as w, VectorCanvasToolbar as x, type VectorCanvasToolbarProps as y, VectorCanvasViewportSurface as z };