canvu-react 0.3.5

package/dist/index.d.cts

@@ -0,0 +1,276 @@
+import { C as Camera2D } from './camera-BwQjm5oh.cjs';
+export { a as Camera2DOptions } from './camera-BwQjm5oh.cjs';
+import { V as VectorSceneItem, A as ArrowEndpointBinding, R as Rect } from './types-CB0TZZuk.cjs';
+export { a as ArrowBindings, b as VectorPathPoint, n as normalizeRect, r as rectsIntersect } from './types-CB0TZZuk.cjs';
+export { D as DEFAULT_STROKE_STYLE, F as FreehandSvgPayload, S as StrokeStyle, a as applyStrokeToItem, b as buildArrowSvg, c as buildDrawDotSvg, d as buildEllipseSvg, e as buildFreehandPathSvg, f as buildLineSvg, g as buildRectSvg, h as computeFreehandSvgPayload, i as createDrawDotItem, j as createEllipseItem, k as createFreehandStrokeItem, l as createImageFromVectorTrace, m as createImageItem, n as createLineItem, o as createRectangleItem, p as createShapeId, q as createTextItem, r as lineEndpointsToLocal, s as rebuildItemSvg, t as resolveStrokeStyle } from './shape-builders-DxPoOecg.cjs';
+
+/**
+ * Embeds the bitmap as a single SVG `<image>` (data URL or blob URL) instead of tracing paths.
+ * Avoids huge path counts and keeps screenshots/photos sharp.
+ */
+/**
+ * Default max width/height (px) before encoding. Larger = sharper zoom / bigger snapshots.
+ * Override per app via {@link loadImageFileAsRasterSceneSource} or `VectorViewport` `imageRasterMaxDimension`.
+ */
+declare const MAX_RASTER_EMBED_DIMENSION = 4096;
+/** How raster pixels are exposed to SVG `<image href>`. */
+type RasterEmbedMode = "dataUrl" | "blobUrl";
+type LoadRasterImageFileOptions = {
+    /** Longest edge (px). Images larger than this are scaled down (canvas). */
+    maxDimension?: number;
+    /**
+     * `dataUrl` — easy to persist (JSON), higher memory use with many large images.
+     * `blobUrl` — lower overhead; **revoke** URLs when items leave the scene (handled by `VectorViewport` for its own loads).
+     */
+    embedMode?: RasterEmbedMode;
+};
+type RasterSceneSource = {
+    /**
+     * Value for SVG `<image href>`: `data:image/...;base64,...` or `blob:https://...`.
+     * Despite the name, `blobUrl` mode stores a blob URL here.
+     */
+    dataUrl: string;
+    width: number;
+    height: number;
+};
+/**
+ * Decodes a file and returns a raster source for {@link createImageItem}.
+ *
+ * - `dataUrl` (default): canvas downscale + base64 (serializable).
+ * - `blobUrl`: uses `URL.createObjectURL(file)` at **full resolution** when the longest edge
+ *   is ≤ `maxDimension`; otherwise downscales like data mode but keeps a blob URL (smaller than base64).
+ */
+declare function loadImageFileAsRasterSceneSource(file: File, maxDimensionOrOptions?: number | LoadRasterImageFileOptions): Promise<RasterSceneSource>;
+
+type ApplePencilNavOptions = {
+    element: HTMLElement;
+    camera: Camera2D;
+    /** Current tool id from your app (e.g. `"hand"` vs `"draw"`). */
+    getCurrentToolId: () => string;
+    onUpdate: () => void;
+    touchPanSensitivity?: number;
+};
+/**
+ * After a **stylus** (`pointerType === "pen"`) has been used, finger touches on the canvas
+ * pan/pinch the camera instead of passing through to drawing tools — similar to iPad behavior
+ * in many design apps. No-op until the first pen contact.
+ *
+ * Compose with {@link attachViewportInput} by calling this **after** it so capture handlers run first,
+ * or use only one of them depending on product needs.
+ */
+declare function attachApplePencilNavigation(options: ApplePencilNavOptions): () => void;
+
+type ViewportInputOptions = {
+    element: HTMLElement;
+    camera: Camera2D;
+    /** Called after any camera mutation so the renderer can redraw. */
+    onUpdate: () => void;
+    /**
+     * Element to attach the wheel listener to. Defaults to `element`.
+     * Useful when an overlay with `pointer-events: auto` sits above `element` and
+     * would otherwise intercept wheel events before they reach the scene container.
+     */
+    wheelElement?: HTMLElement;
+    wheelPanSensitivity?: number;
+    /** Multiplier applied to wheel delta for zoom (with Ctrl/Meta). */
+    wheelZoomSensitivity?: number;
+    touchPanSensitivity?: number;
+    /**
+     * When `true`, pointer events with `pointerType === "touch"` are ignored so another layer
+     * (e.g. `attachApplePencilNavigation`) can handle them without double panning.
+     */
+    touchHandledElsewhere?: boolean;
+    /**
+     * When `false`, one-finger / primary-button drag does **not** pan the camera (e.g. shape tools).
+     * Wheel zoom and two-finger pinch still work.
+     */
+    allowPrimaryPointerPan?: () => boolean;
+};
+/**
+ * Attaches wheel (pan / Ctrl+zoom), pointer drag pan, and two-finger pinch zoom.
+ * Uses `touch-action: none` on `element` — set that in CSS on the same node.
+ *
+ * @returns A dispose function that removes all listeners.
+ */
+declare function attachViewportInput(options: ViewportInputOptions): () => void;
+
+/** Default screen px — converted to world with `/ camera.zoom` when snapping. */
+declare const ARROW_BIND_SNAP_PX = 16;
+declare function isArrowBindTarget(item: VectorSceneItem): boolean;
+/**
+ * If `worldX/worldY` is within `maxDistWorld` of a bindable shape’s boundary,
+ * returns the snapped point on that boundary plus binding metadata.
+ */
+declare function snapArrowEndpointToShape(worldX: number, worldY: number, items: readonly VectorSceneItem[], excludeIds: ReadonlySet<string>, maxDistWorld: number): {
+    world: {
+        x: number;
+        y: number;
+    };
+    binding: ArrowEndpointBinding;
+} | null;
+/**
+ * Recomputes every arrow item that has {@link VectorSceneItem.arrowBind} so endpoints
+ * follow bound shapes (move/resize).
+ */
+declare function resolveArrowBindingsInScene(items: readonly VectorSceneItem[]): readonly VectorSceneItem[];
+/**
+ * Converts a bound arrow to a plain arrow (drops bindings) using the current resolved
+ * geometry so move/resize gestures don’t fight binding resolution.
+ */
+declare function bakeArrowItemToAbsolute(item: VectorSceneItem, items: readonly VectorSceneItem[]): VectorSceneItem;
+
+type HitTestWorldPointOptions = {
+    /** Max distance to a line segment in **world** units (e.g. ~10 / camera.zoom for ~10px on screen). */
+    lineHitWorld?: number;
+    /** When true, locked items are ignored as interaction targets. */
+    ignoreLocked?: boolean;
+};
+/**
+ * Whether `worldX/worldY` hits this item’s visible geometry (stroke/area).
+ */
+declare function itemHitTestWorldPoint(item: VectorSceneItem, worldX: number, worldY: number, options?: HitTestWorldPointOptions): boolean;
+/**
+ * Hit-tests a scene item in world coordinates (top-most = last in array wins if overlapping).
+ */
+declare function hitTestWorldPoint(items: readonly VectorSceneItem[], worldX: number, worldY: number, options?: HitTestWorldPointOptions): VectorSceneItem | null;
+/**
+ * Eraser: IDs of every **unlocked** item hit at this point.
+ * Locked items are ignored so protected background layers do not block erasing editable shapes above them.
+ */
+declare function collectEraserTargetsAtWorldPoint(items: readonly VectorSceneItem[], worldX: number, worldY: number, options?: HitTestWorldPointOptions): string[];
+
+/**
+ * Mutable collection of vector scene items (replace wholesale for simplicity in MVP).
+ */
+declare class VectorScene {
+    private items;
+    getItems(): readonly VectorSceneItem[];
+    /**
+     * Replaces the entire scene contents.
+     */
+    setItems(next: readonly VectorSceneItem[]): void;
+    clear(): void;
+}
+
+/**
+ * Builds the SVG `transform` attribute for mapping world coordinates to viewport CSS pixels.
+ */
+declare function formatCameraTransform(camera: Camera2D): string;
+/**
+ * Transform for item `<g>`: `translate(x,y)` plus optional rotation around the bounds center.
+ * SVG `rotate` uses degrees.
+ */
+declare function formatItemPlacementTransform(item: VectorSceneItem): string;
+type SvgVectorRendererOptions = {
+    /** Root element (typically `position: relative` and fixed size). */
+    container: HTMLElement;
+    scene: VectorScene;
+    camera: Camera2D;
+    /**
+     * When true, the scene SVG ignores pointer events so an overlay can own hit-testing
+     * (interactive selection / resize / placement).
+     */
+    pointerEventsNone?: boolean;
+};
+/**
+ * Renders vector scene items into a single SVG: camera as an outer `<g>` transform,
+ * so geometry stays sharp at any zoom (no fixed-resolution raster).
+ *
+ * Uses incremental DOM updates: keeps a stable `<g>` per visible item id, updates
+ * `innerHTML` only when `childrenSvg` changes, and only adjusts the camera transform
+ * when pan/zoom changes without content edits.
+ */
+declare class SvgVectorRenderer {
+    private readonly container;
+    private readonly scene;
+    private readonly camera;
+    private readonly svg;
+    private readonly rootG;
+    private readonly itemNodeCache;
+    private readonly resizeObserver;
+    constructor(options: SvgVectorRendererOptions);
+    /**
+     * Reads container size, culls items, and updates the SVG (incrementally when possible).
+     */
+    render(): void;
+    private syncVisibleItems;
+    destroy(): void;
+    /** Toggle whether the scene SVG receives pointer events (vs overlay handling them). */
+    setPointerEventsNone(value: boolean): void;
+}
+
+/** Width/height of the shape’s local drawing box (same as `bounds` at creation). */
+type CustomShapeSize = {
+    width: number;
+    height: number;
+};
+/**
+ * How to build the inner SVG (inside the item’s bounding box).
+ *
+ * - **`svg`**: paste-friendly markup. Use `{{w}}`, `{{h}}`, `{{width}}`, or `{{height}}` where the size should go.
+ * - **`render`**: a small function when you prefer code over a string template.
+ */
+type CreateCustomShapeContent = {
+    /**
+     * SVG fragment for `<g>` contents (no outer `<svg>`). Placeholders are replaced with numeric sizes:
+     * `{{w}}`, `{{h}}`, `{{width}}`, `{{height}}`.
+     */
+    svg: string;
+} | {
+    /** Returns inner SVG for the given box size (same coordinate range as `bounds`). */
+    render: (size: CustomShapeSize) => string;
+};
+/**
+ * Replaces `{{w}}`, `{{h}}`, `{{width}}`, and `{{height}}` in a string with the given dimensions.
+ * Use this if you build SVG strings yourself and want the same rules as {@link createCustomShapeItem}.
+ */
+declare function expandCustomShapeTemplate(template: string, width: number, height: number): string;
+/**
+ * Builds the scaled `<g>` wrapper used for `childrenSvg` on custom shapes that support resize.
+ */
+declare function buildCustomShapeChildrenSvg(inner: string, intrinsic: CustomShapeSize, bounds: Rect): string;
+/**
+ * Creates a user-defined shape from SVG markup or a `render` callback.
+ *
+ * Coordinates are **local**: draw from `(0,0)` to `(width, height)` of `bounds`. The library stores an
+ * intrinsic copy so resize handles (when interactive) scale the drawing uniformly.
+ *
+ * @example
+ * ```ts
+ * const star = createCustomShapeItem(createShapeId(), rect, {
+ *   svg: `<polygon points="..." fill="gold" stroke="#b45309" stroke-width="2" />`,
+ * });
+ * ```
+ *
+ * @example Template (good for copy-paste from design tools)
+ * ```ts
+ * createCustomShapeItem(id, rect, {
+ *   svg: `<rect width="{{w}}" height="{{h}}" rx="8" fill="#e0e7ff" stroke="#6366f1" />`,
+ * });
+ * ```
+ */
+declare function createCustomShapeItem(id: string, bounds: Rect, content: CreateCustomShapeContent): VectorSceneItem;
+
+/**
+ * Deep-clones an item with a new id. Rebuilds SVG where the id is embedded (arrow, text, custom).
+ */
+declare function cloneVectorSceneItemWithNewId(item: VectorSceneItem): VectorSceneItem;
+declare function cloneVectorSceneItemsWithNewIds(items: readonly VectorSceneItem[]): VectorSceneItem[];
+
+/**
+ * Returns scene items whose `bounds` intersect the visible world rectangle.
+ *
+ * Uses a uniform grid when there are many items; otherwise a linear filter (faster for
+ * small scenes due to grid build overhead).
+ */
+declare function cullItemsByViewport(items: readonly VectorSceneItem[], visibleWorld: Rect): VectorSceneItem[];
+
+/** Default body font size for vector text (local SVG units). */
+declare const DEFAULT_TEXT_FONT_SIZE = 18;
+/**
+ * Builds SVG `<text>` markup for a text box in local coordinates [0, w] × [0, h].
+ * @param fillColor — Text fill (defaults to blue-gray placeholder / blue body).
+ */
+declare function buildTextSvg(content: string, _width: number, _height: number, fillColor?: string, fontSize?: number): string;
+
+export { ARROW_BIND_SNAP_PX, type ApplePencilNavOptions, ArrowEndpointBinding, Camera2D, type CreateCustomShapeContent, type CustomShapeSize, DEFAULT_TEXT_FONT_SIZE, type LoadRasterImageFileOptions, MAX_RASTER_EMBED_DIMENSION, type RasterEmbedMode, type RasterSceneSource, Rect, SvgVectorRenderer, type SvgVectorRendererOptions, VectorScene, VectorSceneItem, type ViewportInputOptions, attachApplePencilNavigation, attachViewportInput, bakeArrowItemToAbsolute, buildCustomShapeChildrenSvg, buildTextSvg, cloneVectorSceneItemWithNewId, cloneVectorSceneItemsWithNewIds, collectEraserTargetsAtWorldPoint, createCustomShapeItem, cullItemsByViewport, expandCustomShapeTemplate, formatCameraTransform, formatItemPlacementTransform, hitTestWorldPoint, isArrowBindTarget, itemHitTestWorldPoint, loadImageFileAsRasterSceneSource, resolveArrowBindingsInScene, snapArrowEndpointToShape };

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+import { C as Camera2D } from './camera-KwCYYPhm.js';
+export { a as Camera2DOptions } from './camera-KwCYYPhm.js';
+import { V as VectorSceneItem, A as ArrowEndpointBinding, R as Rect } from './types-CB0TZZuk.js';
+export { a as ArrowBindings, b as VectorPathPoint, n as normalizeRect, r as rectsIntersect } from './types-CB0TZZuk.js';
+export { D as DEFAULT_STROKE_STYLE, F as FreehandSvgPayload, S as StrokeStyle, a as applyStrokeToItem, b as buildArrowSvg, c as buildDrawDotSvg, d as buildEllipseSvg, e as buildFreehandPathSvg, f as buildLineSvg, g as buildRectSvg, h as computeFreehandSvgPayload, i as createDrawDotItem, j as createEllipseItem, k as createFreehandStrokeItem, l as createImageFromVectorTrace, m as createImageItem, n as createLineItem, o as createRectangleItem, p as createShapeId, q as createTextItem, r as lineEndpointsToLocal, s as rebuildItemSvg, t as resolveStrokeStyle } from './shape-builders-DTYvub8W.js';
+
+/**
+ * Embeds the bitmap as a single SVG `<image>` (data URL or blob URL) instead of tracing paths.
+ * Avoids huge path counts and keeps screenshots/photos sharp.
+ */
+/**
+ * Default max width/height (px) before encoding. Larger = sharper zoom / bigger snapshots.
+ * Override per app via {@link loadImageFileAsRasterSceneSource} or `VectorViewport` `imageRasterMaxDimension`.
+ */
+declare const MAX_RASTER_EMBED_DIMENSION = 4096;
+/** How raster pixels are exposed to SVG `<image href>`. */
+type RasterEmbedMode = "dataUrl" | "blobUrl";
+type LoadRasterImageFileOptions = {
+    /** Longest edge (px). Images larger than this are scaled down (canvas). */
+    maxDimension?: number;
+    /**
+     * `dataUrl` — easy to persist (JSON), higher memory use with many large images.
+     * `blobUrl` — lower overhead; **revoke** URLs when items leave the scene (handled by `VectorViewport` for its own loads).
+     */
+    embedMode?: RasterEmbedMode;
+};
+type RasterSceneSource = {
+    /**
+     * Value for SVG `<image href>`: `data:image/...;base64,...` or `blob:https://...`.
+     * Despite the name, `blobUrl` mode stores a blob URL here.
+     */
+    dataUrl: string;
+    width: number;
+    height: number;
+};
+/**
+ * Decodes a file and returns a raster source for {@link createImageItem}.
+ *
+ * - `dataUrl` (default): canvas downscale + base64 (serializable).
+ * - `blobUrl`: uses `URL.createObjectURL(file)` at **full resolution** when the longest edge
+ *   is ≤ `maxDimension`; otherwise downscales like data mode but keeps a blob URL (smaller than base64).
+ */
+declare function loadImageFileAsRasterSceneSource(file: File, maxDimensionOrOptions?: number | LoadRasterImageFileOptions): Promise<RasterSceneSource>;
+
+type ApplePencilNavOptions = {
+    element: HTMLElement;
+    camera: Camera2D;
+    /** Current tool id from your app (e.g. `"hand"` vs `"draw"`). */
+    getCurrentToolId: () => string;
+    onUpdate: () => void;
+    touchPanSensitivity?: number;
+};
+/**
+ * After a **stylus** (`pointerType === "pen"`) has been used, finger touches on the canvas
+ * pan/pinch the camera instead of passing through to drawing tools — similar to iPad behavior
+ * in many design apps. No-op until the first pen contact.
+ *
+ * Compose with {@link attachViewportInput} by calling this **after** it so capture handlers run first,
+ * or use only one of them depending on product needs.
+ */
+declare function attachApplePencilNavigation(options: ApplePencilNavOptions): () => void;
+
+type ViewportInputOptions = {
+    element: HTMLElement;
+    camera: Camera2D;
+    /** Called after any camera mutation so the renderer can redraw. */
+    onUpdate: () => void;
+    /**
+     * Element to attach the wheel listener to. Defaults to `element`.
+     * Useful when an overlay with `pointer-events: auto` sits above `element` and
+     * would otherwise intercept wheel events before they reach the scene container.
+     */
+    wheelElement?: HTMLElement;
+    wheelPanSensitivity?: number;
+    /** Multiplier applied to wheel delta for zoom (with Ctrl/Meta). */
+    wheelZoomSensitivity?: number;
+    touchPanSensitivity?: number;
+    /**
+     * When `true`, pointer events with `pointerType === "touch"` are ignored so another layer
+     * (e.g. `attachApplePencilNavigation`) can handle them without double panning.
+     */
+    touchHandledElsewhere?: boolean;
+    /**
+     * When `false`, one-finger / primary-button drag does **not** pan the camera (e.g. shape tools).
+     * Wheel zoom and two-finger pinch still work.
+     */
+    allowPrimaryPointerPan?: () => boolean;
+};
+/**
+ * Attaches wheel (pan / Ctrl+zoom), pointer drag pan, and two-finger pinch zoom.
+ * Uses `touch-action: none` on `element` — set that in CSS on the same node.
+ *
+ * @returns A dispose function that removes all listeners.
+ */
+declare function attachViewportInput(options: ViewportInputOptions): () => void;
+
+/** Default screen px — converted to world with `/ camera.zoom` when snapping. */
+declare const ARROW_BIND_SNAP_PX = 16;
+declare function isArrowBindTarget(item: VectorSceneItem): boolean;
+/**
+ * If `worldX/worldY` is within `maxDistWorld` of a bindable shape’s boundary,
+ * returns the snapped point on that boundary plus binding metadata.
+ */
+declare function snapArrowEndpointToShape(worldX: number, worldY: number, items: readonly VectorSceneItem[], excludeIds: ReadonlySet<string>, maxDistWorld: number): {
+    world: {
+        x: number;
+        y: number;
+    };
+    binding: ArrowEndpointBinding;
+} | null;
+/**
+ * Recomputes every arrow item that has {@link VectorSceneItem.arrowBind} so endpoints
+ * follow bound shapes (move/resize).
+ */
+declare function resolveArrowBindingsInScene(items: readonly VectorSceneItem[]): readonly VectorSceneItem[];
+/**
+ * Converts a bound arrow to a plain arrow (drops bindings) using the current resolved
+ * geometry so move/resize gestures don’t fight binding resolution.
+ */
+declare function bakeArrowItemToAbsolute(item: VectorSceneItem, items: readonly VectorSceneItem[]): VectorSceneItem;
+
+type HitTestWorldPointOptions = {
+    /** Max distance to a line segment in **world** units (e.g. ~10 / camera.zoom for ~10px on screen). */
+    lineHitWorld?: number;
+    /** When true, locked items are ignored as interaction targets. */
+    ignoreLocked?: boolean;
+};
+/**
+ * Whether `worldX/worldY` hits this item’s visible geometry (stroke/area).
+ */
+declare function itemHitTestWorldPoint(item: VectorSceneItem, worldX: number, worldY: number, options?: HitTestWorldPointOptions): boolean;
+/**
+ * Hit-tests a scene item in world coordinates (top-most = last in array wins if overlapping).
+ */
+declare function hitTestWorldPoint(items: readonly VectorSceneItem[], worldX: number, worldY: number, options?: HitTestWorldPointOptions): VectorSceneItem | null;
+/**
+ * Eraser: IDs of every **unlocked** item hit at this point.
+ * Locked items are ignored so protected background layers do not block erasing editable shapes above them.
+ */
+declare function collectEraserTargetsAtWorldPoint(items: readonly VectorSceneItem[], worldX: number, worldY: number, options?: HitTestWorldPointOptions): string[];
+
+/**
+ * Mutable collection of vector scene items (replace wholesale for simplicity in MVP).
+ */
+declare class VectorScene {
+    private items;
+    getItems(): readonly VectorSceneItem[];
+    /**
+     * Replaces the entire scene contents.
+     */
+    setItems(next: readonly VectorSceneItem[]): void;
+    clear(): void;
+}
+
+/**
+ * Builds the SVG `transform` attribute for mapping world coordinates to viewport CSS pixels.
+ */
+declare function formatCameraTransform(camera: Camera2D): string;
+/**
+ * Transform for item `<g>`: `translate(x,y)` plus optional rotation around the bounds center.
+ * SVG `rotate` uses degrees.
+ */
+declare function formatItemPlacementTransform(item: VectorSceneItem): string;
+type SvgVectorRendererOptions = {
+    /** Root element (typically `position: relative` and fixed size). */
+    container: HTMLElement;
+    scene: VectorScene;
+    camera: Camera2D;
+    /**
+     * When true, the scene SVG ignores pointer events so an overlay can own hit-testing
+     * (interactive selection / resize / placement).
+     */
+    pointerEventsNone?: boolean;
+};
+/**
+ * Renders vector scene items into a single SVG: camera as an outer `<g>` transform,
+ * so geometry stays sharp at any zoom (no fixed-resolution raster).
+ *
+ * Uses incremental DOM updates: keeps a stable `<g>` per visible item id, updates
+ * `innerHTML` only when `childrenSvg` changes, and only adjusts the camera transform
+ * when pan/zoom changes without content edits.
+ */
+declare class SvgVectorRenderer {
+    private readonly container;
+    private readonly scene;
+    private readonly camera;
+    private readonly svg;
+    private readonly rootG;
+    private readonly itemNodeCache;
+    private readonly resizeObserver;
+    constructor(options: SvgVectorRendererOptions);
+    /**
+     * Reads container size, culls items, and updates the SVG (incrementally when possible).
+     */
+    render(): void;
+    private syncVisibleItems;
+    destroy(): void;
+    /** Toggle whether the scene SVG receives pointer events (vs overlay handling them). */
+    setPointerEventsNone(value: boolean): void;
+}
+
+/** Width/height of the shape’s local drawing box (same as `bounds` at creation). */
+type CustomShapeSize = {
+    width: number;
+    height: number;
+};
+/**
+ * How to build the inner SVG (inside the item’s bounding box).
+ *
+ * - **`svg`**: paste-friendly markup. Use `{{w}}`, `{{h}}`, `{{width}}`, or `{{height}}` where the size should go.
+ * - **`render`**: a small function when you prefer code over a string template.
+ */
+type CreateCustomShapeContent = {
+    /**
+     * SVG fragment for `<g>` contents (no outer `<svg>`). Placeholders are replaced with numeric sizes:
+     * `{{w}}`, `{{h}}`, `{{width}}`, `{{height}}`.
+     */
+    svg: string;
+} | {
+    /** Returns inner SVG for the given box size (same coordinate range as `bounds`). */
+    render: (size: CustomShapeSize) => string;
+};
+/**
+ * Replaces `{{w}}`, `{{h}}`, `{{width}}`, and `{{height}}` in a string with the given dimensions.
+ * Use this if you build SVG strings yourself and want the same rules as {@link createCustomShapeItem}.
+ */
+declare function expandCustomShapeTemplate(template: string, width: number, height: number): string;
+/**
+ * Builds the scaled `<g>` wrapper used for `childrenSvg` on custom shapes that support resize.
+ */
+declare function buildCustomShapeChildrenSvg(inner: string, intrinsic: CustomShapeSize, bounds: Rect): string;
+/**
+ * Creates a user-defined shape from SVG markup or a `render` callback.
+ *
+ * Coordinates are **local**: draw from `(0,0)` to `(width, height)` of `bounds`. The library stores an
+ * intrinsic copy so resize handles (when interactive) scale the drawing uniformly.
+ *
+ * @example
+ * ```ts
+ * const star = createCustomShapeItem(createShapeId(), rect, {
+ *   svg: `<polygon points="..." fill="gold" stroke="#b45309" stroke-width="2" />`,
+ * });
+ * ```
+ *
+ * @example Template (good for copy-paste from design tools)
+ * ```ts
+ * createCustomShapeItem(id, rect, {
+ *   svg: `<rect width="{{w}}" height="{{h}}" rx="8" fill="#e0e7ff" stroke="#6366f1" />`,
+ * });
+ * ```
+ */
+declare function createCustomShapeItem(id: string, bounds: Rect, content: CreateCustomShapeContent): VectorSceneItem;
+
+/**
+ * Deep-clones an item with a new id. Rebuilds SVG where the id is embedded (arrow, text, custom).
+ */
+declare function cloneVectorSceneItemWithNewId(item: VectorSceneItem): VectorSceneItem;
+declare function cloneVectorSceneItemsWithNewIds(items: readonly VectorSceneItem[]): VectorSceneItem[];
+
+/**
+ * Returns scene items whose `bounds` intersect the visible world rectangle.
+ *
+ * Uses a uniform grid when there are many items; otherwise a linear filter (faster for
+ * small scenes due to grid build overhead).
+ */
+declare function cullItemsByViewport(items: readonly VectorSceneItem[], visibleWorld: Rect): VectorSceneItem[];
+
+/** Default body font size for vector text (local SVG units). */
+declare const DEFAULT_TEXT_FONT_SIZE = 18;
+/**
+ * Builds SVG `<text>` markup for a text box in local coordinates [0, w] × [0, h].
+ * @param fillColor — Text fill (defaults to blue-gray placeholder / blue body).
+ */
+declare function buildTextSvg(content: string, _width: number, _height: number, fillColor?: string, fontSize?: number): string;
+
+export { ARROW_BIND_SNAP_PX, type ApplePencilNavOptions, ArrowEndpointBinding, Camera2D, type CreateCustomShapeContent, type CustomShapeSize, DEFAULT_TEXT_FONT_SIZE, type LoadRasterImageFileOptions, MAX_RASTER_EMBED_DIMENSION, type RasterEmbedMode, type RasterSceneSource, Rect, SvgVectorRenderer, type SvgVectorRendererOptions, VectorScene, VectorSceneItem, type ViewportInputOptions, attachApplePencilNavigation, attachViewportInput, bakeArrowItemToAbsolute, buildCustomShapeChildrenSvg, buildTextSvg, cloneVectorSceneItemWithNewId, cloneVectorSceneItemsWithNewIds, collectEraserTargetsAtWorldPoint, createCustomShapeItem, cullItemsByViewport, expandCustomShapeTemplate, formatCameraTransform, formatItemPlacementTransform, hitTestWorldPoint, isArrowBindTarget, itemHitTestWorldPoint, loadImageFileAsRasterSceneSource, resolveArrowBindingsInScene, snapArrowEndpointToShape };