react-img-cutout 1.0.0

package/README.md

@@ -0,0 +1,263 @@
+# react-img-cutout
+
+`react-img-cutout` provides a simple, composable component for creating interactive image regions. 
+It enables pixel-perfect interaction using transparent PNG cutouts, while also supporting standard bounding boxes and polygons for geometric shapes. 
+
+
+
+https://github.com/user-attachments/assets/4e4413b6-362a-4023-91f1-44452ea0c605
+
+
+
+## Quick Start
+
+### 1) Install
+
+```bash
+npm install react-img-cutout
+```
+
+Peer dependencies:
+- `react >= 18`
+- `react-dom >= 18`
+
+### 2) Render a viewer
+
+```tsx
+import { CutoutViewer } from "react-img-cutout"
+
+export function ProductHero() {
+  return (
+    <CutoutViewer
+      mainImage="/images/main.png"
+      mainImageAlt="Product scene"
+      effect="elevate"
+      onSelect={(id) => console.log("selected:", id)}
+    >
+      <CutoutViewer.Cutout
+        id="shoe"
+        src="/images/cutouts/shoe.png"
+        label="Shoe"
+      >
+        <CutoutViewer.Overlay placement="top-center">
+          <button>View details</button>
+        </CutoutViewer.Overlay>
+      </CutoutViewer.Cutout>
+
+      <CutoutViewer.Cutout
+        id="bag"
+        src="/images/cutouts/bag.png"
+        label="Bag"
+      />
+
+      {/* No image needed — define regions with coordinates */}
+      <CutoutViewer.BBoxCutout
+        id="logo"
+        bounds={{ x: 0.05, y: 0.05, w: 0.15, h: 0.1 }}
+        label="Logo"
+      />
+
+      <CutoutViewer.PolygonCutout
+        id="accent"
+        points={[[0.7, 0.2], [0.9, 0.2], [0.85, 0.5], [0.65, 0.45]]}
+        label="Accent"
+      />
+    </CutoutViewer>
+  )
+}
+```
+
+## Cutout Types
+
+The library supports three different cutout types, each suited for different use cases.
+
+### Image Cutout (`CutoutViewer.Cutout`)
+
+The original cutout type — uses a transparent PNG aligned to the same coordinate
+space as the main image. Hit-testing is performed per-pixel using the alpha channel.
+
+```tsx
+<CutoutViewer.Cutout
+  id="shoe"
+  src="/images/cutouts/shoe.png"
+  label="Shoe"
+>
+  <CutoutViewer.Overlay placement="top-center">
+    <button>View details</button>
+  </CutoutViewer.Overlay>
+</CutoutViewer.Cutout>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique identifier for the cutout |
+| `src` | `string` | URL of the cutout image (transparent PNG, same resolution as `mainImage`) |
+| `label` | `string?` | Human-readable label (used as `alt` text) |
+| `effect` | `HoverEffectPreset \| HoverEffect?` | Override the viewer-level hover effect for this cutout |
+| `renderLayer` | `(props: RenderLayerProps) => ReactNode?` | Custom renderer replacing the default `<img>` |
+| `children` | `ReactNode?` | Overlay content |
+
+### Bounding Box Cutout (`CutoutViewer.BBoxCutout`)
+
+Defines a rectangular region using normalized 0–1 coordinates. No image
+required — the component renders a styled rectangle. Ideal for highlighting
+areas of the image programmatically (e.g. from object-detection output).
+
+```tsx
+<CutoutViewer.BBoxCutout
+  id="face"
+  bounds={{ x: 0.3, y: 0.1, w: 0.2, h: 0.25 }}
+  label="Face"
+>
+  <CutoutViewer.Overlay placement="top-center">
+    <span>Detected face</span>
+  </CutoutViewer.Overlay>
+</CutoutViewer.BBoxCutout>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique identifier for the cutout |
+| `bounds` | `{ x, y, w, h }` | Normalized 0–1 bounding box (`x` and `y` are the top-left corner) |
+| `label` | `string?` | Human-readable label |
+| `effect` | `HoverEffectPreset \| HoverEffect?` | Override the viewer-level hover effect for this cutout |
+| `renderLayer` | `(props: RenderLayerProps) => ReactNode?` | Custom renderer replacing the default rectangle |
+| `children` | `ReactNode?` | Overlay content |
+
+### Polygon Cutout (`CutoutViewer.PolygonCutout`)
+
+Defines an arbitrary closed shape using an array of `[x, y]` normalized 0–1
+points. Rendered as an SVG `<polygon>`. Great for non-rectangular regions such
+as segmentation masks or hand-drawn annotations.
+
+```tsx
+<CutoutViewer.PolygonCutout
+  id="lake"
+  points={[
+    [0.2, 0.6],
+    [0.5, 0.55],
+    [0.6, 0.7],
+    [0.35, 0.8],
+  ]}
+  label="Lake"
+>
+  <CutoutViewer.Overlay placement="center">
+    <span>Lake area</span>
+  </CutoutViewer.Overlay>
+</CutoutViewer.PolygonCutout>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique identifier for the cutout |
+| `points` | `[number, number][]` | Array of normalized 0–1 `[x, y]` points forming a closed path |
+| `label` | `string?` | Human-readable label |
+| `effect` | `HoverEffectPreset \| HoverEffect?` | Override the viewer-level hover effect for this cutout |
+| `renderLayer` | `(props: RenderLayerProps) => ReactNode?` | Custom renderer replacing the default SVG polygon |
+| `children` | `ReactNode?` | Overlay content |
+
+## Public API
+
+- `CutoutViewer`
+  - Props: `mainImage`, `mainImageAlt`, `effect`, `enabled`, `showAll`,
+    `alphaThreshold`, `hoverLeaveDelay`, `onHover`, `onActiveChange`, `onSelect`
+- `CutoutViewer.Cutout` — image-based cutout (alpha hit-testing)
+- `CutoutViewer.BBoxCutout` — bounding-box cutout (rectangular region)
+- `CutoutViewer.PolygonCutout` — polygon cutout (arbitrary closed shape)
+- `CutoutViewer.Overlay`
+  - Props: `placement`, `className`, `style`
+- `useCutout()`
+  - Read nearest cutout state (`id`, `bounds`, `isActive`, `isHovered`, `isSelected`, `effect`)
+- `hoverEffects`
+  - Built-in presets: `elevate`, `glow`, `lift`, `subtle`, `trace`, `shimmer`
+- `defineKeyframes(name, css)` — helper for declaring CSS `@keyframes` in custom effects
+
+## How It Works
+
+- **Image cutouts** are loaded into an offscreen canvas; opaque bounds and alpha
+  data are computed once for pixel-level hit-testing.
+- **BBox cutouts** use simple point-in-rect checks against normalized coordinates.
+- **Polygon cutouts** use a ray-casting algorithm for point-in-polygon testing.
+- Pointer positions are normalized to the container and hit-tested from front to back.
+- Click locks selection; clicking empty space clears selection.
+- Overlays are positioned from normalized cutout bounds using one of 9 placements.
+
+## Important Implementation Notes
+
+- Use transparent PNG/WebP cutouts aligned to the same coordinate space as `mainImage`.
+- Best results come from matching cutout resolution to the base image resolution.
+- BBox and Polygon cutouts do not require any image — they are defined purely by coordinates.
+- Geometry cutouts (BBox/Polygon) are invisible when idle and appear on hover/selection,
+  unlike image cutouts which blend naturally with the background.
+- If a cutout image cannot be read from canvas (for example, CORS restrictions),
+  hit testing for that cutout gracefully falls back and does not crash.
+- The component does not require Tailwind to render correctly.
+
+## Effects
+
+Pass a preset name or a fully custom `HoverEffect` object to the `effect` prop.
+
+### Built-in presets
+
+| Preset | Description |
+|--------|-------------|
+| `elevate` | Lifts the hovered cutout with a blue glow and deep shadow |
+| `glow` | Warm glow around the hovered cutout, no lift |
+| `lift` | Strong lift with deep shadow, no color glow |
+| `subtle` | Minimal — dims non-hovered cutouts with no animation |
+| `trace` | A white dash continuously traces the cutout border |
+| `shimmer` | style brightness flash that sweeps over the hovered subject |
+
+### Custom static effects
+
+```tsx
+import { CutoutViewer, type HoverEffect } from "react-img-cutout"
+
+const customEffect: HoverEffect = {
+  name: "neon",
+  transition: "all 0.4s ease",
+  mainImageHovered: { filter: "brightness(0.2) grayscale(1)" },
+  vignetteStyle: { background: "rgba(0,0,0,0.45)" },
+  cutoutActive: { transform: "scale(1.03)", opacity: 1 },
+  cutoutInactive: { transform: "scale(1)", opacity: 0.35 },
+  cutoutIdle: { transform: "scale(1)", opacity: 1 },
+}
+```
+
+### Custom animated effects
+
+Use `defineKeyframes` to declare CSS `@keyframes` that the viewer injects
+automatically. Reference the keyframe `name` in any `animation` property.
+
+```tsx
+import { defineKeyframes, type HoverEffect } from "react-img-cutout"
+
+const pulse = defineKeyframes("my-pulse", `
+  0%, 100% { transform: scale(1);    filter: brightness(1);    }
+  50%      { transform: scale(1.06); filter: brightness(1.15); }
+`)
+
+const pulseEffect: HoverEffect = {
+  name: "pulse",
+  transition: "all 0.4s ease",
+  keyframes: [pulse],
+  mainImageHovered: { filter: "brightness(0.3)" },
+  vignetteStyle: { background: "rgba(0,0,0,0.4)" },
+  cutoutActive: {
+    animation: `${pulse.name} 1.2s ease-in-out infinite`,
+    opacity: 1,
+  },
+  cutoutInactive: { opacity: 0.3 },
+  cutoutIdle: { opacity: 1 },
+}
+```
+
+Geometry cutouts (BBox / Polygon) also support `strokeDasharray` and
+`animation` on their `geometryActive` style for SVG-level animations
+like the built-in trace effect.
+
+## Local Development
+
+- `npm run storybook` for interactive component testing
+- `npm run lint` for lint checks
+- `npm run build:lib` to generate `dist/` for npm

package/dist/components/cutout-viewer/cutout-viewer.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode, type ReactElement, type CSSProperties } from "react";
+import { type HoverEffectPreset, type HoverEffect } from "./hover-effects";
+import { Cutout } from "./cutouts/image/cutout";
+import { BBoxCutout } from "./cutouts/bbox/bbox-cutout";
+import { PolygonCutout } from "./cutouts/polygon/polygon-cutout";
+import { CutoutOverlay } from "./cutouts/cutout-overlay";
+export interface CutoutViewerProps {
+    /** URL of the main background image */
+    mainImage: string;
+    /** Accessible alt text for the main image */
+    mainImageAlt?: string;
+    /** Hover effect preset name or a custom HoverEffect object */
+    effect?: HoverEffectPreset | HoverEffect;
+    /** Whether the hover interaction is enabled (default: true) */
+    enabled?: boolean;
+    /** When true, all cutouts show their active/hovered state simultaneously */
+    showAll?: boolean;
+    /** Minimum alpha value 0-255 for pixel hit-testing (default: 30) */
+    alphaThreshold?: number;
+    /** Delay in ms before the hover state clears after leaving a cutout (default: 150) */
+    hoverLeaveDelay?: number;
+    /**
+     * Composable children — use `<CutoutViewer.Cutout>` to declare cutout layers.
+     * Other elements are rendered on top of the viewer.
+     */
+    children?: ReactNode;
+    /** Additional className on the root container */
+    className?: string;
+    /** Additional inline style on the root container */
+    style?: CSSProperties;
+    /** Callback when a cutout is hovered (not selected) */
+    onHover?: (cutoutId: string | null) => void;
+    /** Callback when a cutout becomes active (hovered or selected) */
+    onActiveChange?: (cutoutId: string | null) => void;
+    /** Callback when a cutout is clicked / selected */
+    onSelect?: (cutoutId: string | null) => void;
+}
+type CutoutViewerComponent = ((props: CutoutViewerProps) => ReactElement) & {
+    Cutout: typeof Cutout;
+    BBoxCutout: typeof BBoxCutout;
+    PolygonCutout: typeof PolygonCutout;
+    Overlay: typeof CutoutOverlay;
+};
+export declare const CutoutViewer: CutoutViewerComponent;
+export {};

package/dist/components/cutout-viewer/cutouts/bbox/bbox-cutout.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import { type HoverEffect, type HoverEffectPreset } from "../../hover-effects";
+import type { RenderLayerProps } from "../image/cutout";
+export interface BBoxCutoutProps {
+    /** Unique identifier for this cutout */
+    id: string;
+    /** Normalized 0-1 bounding box coordinates */
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Human-readable label */
+    label?: string;
+    /** Override the viewer-level hover effect for this specific cutout */
+    effect?: HoverEffectPreset | HoverEffect;
+    /** Children rendered inside this cutout's context (e.g. `<Overlay>`) */
+    children?: ReactNode;
+    /** Custom renderer for the cutout layer. When provided, replaces the default rendering. */
+    renderLayer?: (props: RenderLayerProps) => ReactNode;
+}
+export declare function BBoxCutout({ id, bounds: defBounds, label, effect: effectOverride, children, renderLayer, }: BBoxCutoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/cutouts/bbox/bbox-hit-test-strategy.d.ts

@@ -0,0 +1,7 @@
+import type { CutoutBounds, HitTestStrategy, BoundingBoxCutoutDefinition } from "../../hit-test-strategy";
+export declare class RectHitTestStrategy implements HitTestStrategy {
+    id: string;
+    bounds: CutoutBounds;
+    constructor(def: BoundingBoxCutoutDefinition);
+    hitTest(nx: number, ny: number): boolean;
+}

package/dist/components/cutout-viewer/cutouts/cutout-context.d.ts

@@ -0,0 +1,17 @@
+import type { CutoutBounds } from "../hit-test-strategy";
+import type { HoverEffect } from "../hover-effects";
+export interface CutoutContextValue {
+    id: string;
+    label?: string;
+    bounds: CutoutBounds;
+    isActive: boolean;
+    isHovered: boolean;
+    isSelected: boolean;
+    effect: HoverEffect;
+}
+export declare const CutoutContext: import("react").Context<CutoutContextValue | null>;
+/**
+ * Access the state of the nearest parent `<CutoutViewer.Cutout>`.
+ * Must be used inside a `<CutoutViewer.Cutout>`.
+ */
+export declare function useCutout(): CutoutContextValue;

package/dist/components/cutout-viewer/cutouts/cutout-overlay.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode, type CSSProperties } from "react";
+export type Placement = "top-left" | "top-center" | "top-right" | "center-left" | "center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
+export interface CutoutOverlayProps {
+    /**
+     * Where to position the overlay relative to the cutout's bounding box.
+     * @default "top-center"
+     */
+    placement?: Placement;
+    /** Content to render inside the overlay */
+    children: ReactNode;
+    /** Additional className */
+    className?: string;
+    /** Additional inline styles (merged after placement styles) */
+    style?: CSSProperties;
+}
+/**
+ * Renders custom UI positioned relative to the parent `<CutoutViewer.Cutout>`'s
+ * opaque bounding box. The overlay is visible when its cutout is active (hovered
+ * or selected), or always visible in `showAll` mode.
+ *
+ * @example
+ * <CutoutViewer.Cutout id="face" src="/face.png" label="Face">
+ *   <CutoutViewer.Overlay placement="top-center">
+ *     <button>View Profile</button>
+ *   </CutoutViewer.Overlay>
+ * </CutoutViewer.Cutout>
+ */
+export declare function CutoutOverlay({ placement, children, className, style, }: CutoutOverlayProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/cutouts/image/cutout.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import type { CutoutBounds } from "../../hit-test-strategy";
+import { type HoverEffect, type HoverEffectPreset } from "../../hover-effects";
+export interface RenderLayerProps {
+    isActive: boolean;
+    isHovered: boolean;
+    isSelected: boolean;
+    bounds: CutoutBounds;
+    effect: HoverEffect;
+}
+export interface CutoutProps {
+    /** Unique identifier for this cutout */
+    id: string;
+    /** URL of the cutout image (transparent PNG, same resolution as mainImage) */
+    src: string;
+    /** Human-readable label */
+    label?: string;
+    /** Override the viewer-level hover effect for this specific cutout */
+    effect?: HoverEffectPreset | HoverEffect;
+    /** Children rendered inside this cutout's context (e.g. `<Overlay>`) */
+    children?: ReactNode;
+    /** Custom renderer for the cutout layer. When provided, replaces the default `<img>` rendering. */
+    renderLayer?: (props: RenderLayerProps) => ReactNode;
+}
+export declare function Cutout({ id, src, label, effect: effectOverride, children, renderLayer }: CutoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/cutouts/image/image-hit-test-strategy.d.ts

@@ -0,0 +1,61 @@
+import type { CutoutBounds, HitTestStrategy, ImageCutoutDefinition } from "../../hit-test-strategy";
+/**
+ * Hit-test strategy for image-based (alpha mask) cutouts.
+ *
+ * Instead of using geometric shapes, this strategy detects whether the cursor
+ * is over a **visible (non-transparent) pixel** in a cutout image. This is
+ * useful for irregularly shaped cutouts where polygons would be too complex.
+ *
+ * Overall flow:
+ * 1. **prepare()** — loads the cutout image, draws it onto an offscreen canvas,
+ *    reads the pixel data, and extracts just the alpha channel into a compact
+ *    buffer. It also computes a tight bounding box around the visible pixels.
+ * 2. **hitTest(nx, ny)** — given a normalized mouse position (0-1), first does
+ *    a cheap bounding-box check, then looks up the exact pixel in the alpha
+ *    buffer to decide if the point is over a visible part of the image.
+ */
+export declare class ImageHitTestStrategy implements HitTestStrategy {
+    id: string;
+    bounds: CutoutBounds;
+    /** URL of the cutout mask image */
+    private src;
+    /** Alpha value (0-255) a pixel must exceed to be considered "visible" */
+    private threshold;
+    /** Pre-extracted alpha channel — one byte per pixel, for fast lookups */
+    private alpha;
+    /** Source image dimensions (pixels) — needed to map normalized coords to pixel indices */
+    private width;
+    private height;
+    constructor(def: ImageCutoutDefinition, threshold: number);
+    /**
+     * Loads the cutout image and pre-computes the alpha buffer + bounding box.
+     *
+     * Steps:
+     * 1. Create an <img> element and wait for it to load.
+     * 2. Draw the image onto a temporary offscreen <canvas>.
+     * 3. Read the raw RGBA pixel data from the canvas.
+     * 4. Extract only the alpha channel into a compact buffer (see `extractAlpha`).
+     * 5. Compute the tight bounding box of visible pixels (see `computeBoundsFromAlpha`).
+     *
+     * If the canvas is CORS-tainted (image from a different origin without proper
+     * headers), reading pixel data will throw. In that case we fall back to an
+     * empty alpha buffer, which means hitTest will always return false.
+     */
+    prepare(): Promise<void>;
+    /**
+     * Tests whether the normalized point (nx, ny) is over a visible pixel.
+     *
+     * Three-phase approach:
+     * 1. **Alpha buffer check** — if the buffer is empty (image failed to load or
+     *    was CORS-tainted), return false immediately.
+     * 2. **Bounding-box check** — reject points outside the pre-computed AABB of
+     *    visible pixels (very cheap).
+     * 3. **Per-pixel alpha lookup** — convert the normalized coordinates to pixel
+     *    indices, look up the alpha value in the pre-extracted buffer, and compare
+     *    it against the threshold.
+     *
+     * @param nx - normalized x-coordinate (0-1, relative to the image width)
+     * @param ny - normalized y-coordinate (0-1, relative to the image height)
+     */
+    hitTest(nx: number, ny: number): boolean;
+}

package/dist/components/cutout-viewer/cutouts/polygon/polygon-cutout.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import { type HoverEffect, type HoverEffectPreset } from "../../hover-effects";
+import type { RenderLayerProps } from "../image/cutout";
+export interface PolygonCutoutProps {
+    /** Unique identifier for this cutout */
+    id: string;
+    /** Array of [x, y] normalized 0-1 points forming a closed path */
+    points: [number, number][];
+    /** Human-readable label */
+    label?: string;
+    /** Override the viewer-level hover effect for this specific cutout */
+    effect?: HoverEffectPreset | HoverEffect;
+    /** Children rendered inside this cutout's context (e.g. `<Overlay>`) */
+    children?: ReactNode;
+    /** Custom renderer for the cutout layer. When provided, replaces the default SVG rendering. */
+    renderLayer?: (props: RenderLayerProps) => ReactNode;
+}
+export declare function PolygonCutout({ id, points: defPoints, label, effect: effectOverride, children, renderLayer, }: PolygonCutoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/cutout-viewer/cutouts/polygon/polygon-hit-test-strategy.d.ts

@@ -0,0 +1,28 @@
+import type { CutoutBounds, HitTestStrategy, PolygonCutoutDefinition } from "../../hit-test-strategy";
+/**
+ * Hit-test strategy for polygon-shaped cutouts.
+ *
+ * On construction it pre-computes an axis-aligned bounding box (AABB) from the
+ * polygon vertices. During hit testing it first checks the cheap AABB test to
+ * quickly reject points that are clearly outside, then falls back to the more
+ * expensive ray-casting test only when needed.
+ */
+export declare class PolygonHitTestStrategy implements HitTestStrategy {
+    id: string;
+    bounds: CutoutBounds;
+    private points;
+    constructor(def: PolygonCutoutDefinition);
+    /**
+     * Tests whether the normalized point (nx, ny) is inside this polygon.
+     *
+     * Two-phase approach for performance:
+     * 1. **Bounding-box check** — if the point is outside the AABB, return false
+     *    immediately (very cheap).
+     * 2. **Ray-cast check** — run the full point-in-polygon algorithm for precise
+     *    hit detection only if the point passed the bounding-box check.
+     *
+     * @param nx - normalized x-coordinate (0-1, relative to the image width)
+     * @param ny - normalized y-coordinate (0-1, relative to the image height)
+     */
+    hitTest(nx: number, ny: number): boolean;
+}

package/dist/components/cutout-viewer/hit-test-strategy.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Normalized bounding box (0-1 range) of the opaque pixels in a cutout.
+ * Values represent fractions of the image dimensions.
+ */
+export interface CutoutBounds {
+    /** Left edge as a fraction of image width (0-1) */
+    x: number;
+    /** Top edge as a fraction of image height (0-1) */
+    y: number;
+    /** Width as a fraction of image width (0-1) */
+    w: number;
+    /** Height as a fraction of image height (0-1) */
+    h: number;
+}
+interface BaseCutoutDefinition {
+    id: string;
+    label?: string;
+}
+export interface ImageCutoutDefinition extends BaseCutoutDefinition {
+    type: "image";
+    /** Transparent PNG, same resolution as the main image */
+    src: string;
+}
+export interface BoundingBoxCutoutDefinition extends BaseCutoutDefinition {
+    type: "bbox";
+    /** Normalized 0-1 coordinates */
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface PolygonCutoutDefinition extends BaseCutoutDefinition {
+    type: "polygon";
+    /** Array of [x, y] normalized points forming a closed path */
+    points: [number, number][];
+}
+export type CutoutDefinition = ImageCutoutDefinition | BoundingBoxCutoutDefinition | PolygonCutoutDefinition;
+export interface HitTestStrategy {
+    /** Cutout identifier */
+    id: string;
+    /** Returns true if the normalized point (nx, ny) in [0,1] is inside this cutout */
+    hitTest(nx: number, ny: number): boolean;
+    /** Pre-computed bounding box (normalized 0-1) */
+    bounds: CutoutBounds;
+    /** Optional async setup (e.g., image loading) */
+    prepare?(): Promise<void>;
+    /** Cleanup */
+    dispose?(): void;
+}
+export { ImageHitTestStrategy } from "./cutouts/image/image-hit-test-strategy";
+export { RectHitTestStrategy } from "./cutouts/bbox/bbox-hit-test-strategy";
+export { PolygonHitTestStrategy } from "./cutouts/polygon/polygon-hit-test-strategy";
+export declare function createHitTestStrategy(def: CutoutDefinition, alphaThreshold: number): HitTestStrategy;