kviewer 0.0.4 → 0.0.6

package/dist/runtime/components/ViewerBar.vue

@@ -3,7 +3,7 @@
     <!-- Top navigation bar -->
     <div class="flex items-center h-[40px] px-3 gap-2 bg-elevated/50">
       <UPopover>
-        <UButton icon="i-lucide-menu" variant="ghost" color="neutral" size="xs" />
+        <UButton icon="i-lucide-menu" variant="ghost" color="neutral" size="xs" data-testid="viewer-menu" />
         <template #content>
           <div class="p-1">
             <UButton
@@ -13,6 +13,7 @@
               color="neutral"
               size="xs"
               class="w-full justify-start"
+              data-testid="viewer-download"
               @click="onDownload"
             />
           </div>
@@ -57,9 +58,6 @@
 <script setup>
 import { ref } from "vue";
 import { useViewerState } from "../composables/useViewerState";
-import { getTimestampString } from "../annotation/engine/utils";
-import { downloadPdfBytes } from "../annotation/pdf-export/download";
-import { exportAnnotationsToPdf } from "../annotation/pdf-export/export";
 import PageSettings from "./tools/PageSettings.vue";
 import ZoomControls from "./tools/ZoomControls.vue";
 import HandTool from "./tools/HandTool.vue";
@@ -76,16 +74,7 @@ function bumpStyleVersion() {
 }
 async function onDownload() {
   try {
-    if (!state.doc.value || !state.painter.value) return;
-    const bytes = await exportAnnotationsToPdf({
-      pdfData: await state.doc.value.getData(),
-      annotations: state.painter.value.getData(),
-      options: {
-        flatten: false,
-        preserveOriginalAnnotations: false
-      }
-    });
-    downloadPdfBytes(bytes, `annotated_${getTimestampString()}.pdf`);
+    await state.downloadPdf();
   } catch (error) {
     console.error("Failed to export PDF from menu action", error);
   }

package/dist/runtime/components/ViewerTabs.d.vue.ts

@@ -16,6 +16,8 @@ export interface ViewerTabItem {
     viewMode?: ViewMode;
     /** Zoom override for this document. */
     zoom?: number;
+    /** Enable shape detection for this document. */
+    shapeDetection?: boolean;
 }
 export interface AddTabOptions {
     /** Insert at specific index. Defaults to end. */
@@ -38,6 +40,8 @@ type __VLS_Props = {
     textLayer?: boolean;
     /** When true, all viewers are in view-only mode. */
     readonly?: boolean;
+    /** Enable shape detection on all Viewer instances. Can be overridden per tab. */
+    shapeDetection?: boolean;
     /** Default view mode for tabs without a per-tab override. */
     viewMode?: ViewMode;
     /** Default zoom for tabs without a per-tab override. */
@@ -148,6 +152,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         closable?: boolean | undefined;
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
+        shapeDetection?: boolean | undefined;
     };
 }, __VLS_33: {
     tab: {
@@ -246,6 +251,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         closable?: boolean | undefined;
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
+        shapeDetection?: boolean | undefined;
     };
 }, __VLS_35: {};
 type __VLS_Slots = {} & {
@@ -361,6 +367,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         closable?: boolean | undefined;
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
+        shapeDetection?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:activeTab": (id: string) => any;
@@ -372,7 +379,15 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     "onTab-added"?: ((tab: ViewerTabItem) => any) | undefined;
     "onTab-close"?: ((id: string) => any) | undefined;
     "onTab-removed"?: ((id: string) => any) | undefined;
-}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+}>, {
+    userName: string;
+    zoom: number;
+    stamps: StampDefinition[];
+    signatureHandlers: SignatureHandlers;
+    viewMode: ViewMode;
+    defaultActiveTab: string;
+    minTabs: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/ViewerTabs.vue

@@ -15,6 +15,7 @@
           :class="[
   tab.id === activeTabId ? 'bg-elevated text-highlighted border-b-2 border-b-primary' : 'text-muted hover:text-highlighted hover:bg-elevated/80'
 ]"
+          :data-testid="'tab-' + tab.id"
           @click="activateTab(tab.id)"
         >
           <UIcon
@@ -30,6 +31,7 @@
             color="neutral"
             class="opacity-0 group-hover:opacity-100 transition-opacity -mr-1"
             :class="{ 'opacity-100': tab.id === activeTabId }"
+            :data-testid="'tab-close-' + tab.id"
             @click.stop="removeTab(tab.id)"
           />
         </button>
@@ -38,31 +40,31 @@
       </div>
     </ClientOnly>
 
-    <!-- Viewer container -->
+    <!-- Viewer container — only the active tab is rendered -->
     <div class="flex-1 relative overflow-hidden">
       <div
-        v-for="tab in tabs"
-        v-show="tab.id === activeTabId"
-        :key="tab.id"
+        v-if="activeTab"
+        :key="activeTab.id"
         class="absolute inset-0"
       >
         <Viewer
-          :ref="(el) => setViewerRef(tab.id, el)"
-          :source="tab.source"
-          :active="tab.id === activeTabId"
+          :ref="(el) => setViewerRef(activeTab.id, el)"
+          :source="activeTab.source"
+          :active="true"
           :stamps="stamps"
           :text-layer="textLayer"
           :user-name="userName"
           :signature-handlers="signatureHandlers"
-          :view-mode="tab.viewMode ?? viewMode"
-          :zoom="tab.zoom ?? zoom"
+          :view-mode="activeTab.viewMode ?? viewMode"
+          :zoom="activeTab.zoom ?? zoom"
           :readonly="readonly"
+          :shape-detection="activeTab.shapeDetection ?? shapeDetection"
         >
           <template v-if="$slots.header" #header>
-            <slot name="header" :tab="tab" />
+            <slot name="header" :tab="activeTab" />
           </template>
           <template v-if="$slots.footer" #footer>
-            <slot name="footer" :tab="tab" />
+            <slot name="footer" :tab="activeTab" />
           </template>
         </Viewer>
       </div>
@@ -76,7 +78,7 @@
 </template>
 
 <script setup>
-import { ref, watch } from "vue";
+import { ref, computed, watch, nextTick } from "vue";
 import Viewer from "./Viewer.vue";
 const props = defineProps({
   items: { type: Array, required: true },
@@ -86,6 +88,7 @@ const props = defineProps({
   signatureHandlers: { type: Object, required: false, default: void 0 },
   textLayer: { type: Boolean, required: false },
   readonly: { type: Boolean, required: false },
+  shapeDetection: { type: Boolean, required: false },
   viewMode: { type: String, required: false, default: "fit-width" },
   zoom: { type: Number, required: false, default: 1 },
   minTabs: { type: Number, required: false, default: 0 }
@@ -99,14 +102,37 @@ const tabs = ref([...props.items]);
 const activeTabId = ref(
   props.defaultActiveTab ?? props.items[0]?.id ?? ""
 );
+const activeTab = computed(
+  () => tabs.value.find((t) => t.id === activeTabId.value) ?? null
+);
 const viewerRefs = /* @__PURE__ */ new Map();
+const savedAnnotations = /* @__PURE__ */ new Map();
 function setViewerRef(id, el) {
   if (el) {
     viewerRefs.set(id, el);
+    const saved = savedAnnotations.get(id);
+    if (saved && saved.length > 0) {
+      nextTick(() => {
+        const viewer = el;
+        if (typeof viewer.importAnnotations === "function") {
+          viewer.importAnnotations(saved, { mode: "merge" }).catch(() => {
+          });
+        }
+      });
+    }
   } else {
     viewerRefs.delete(id);
   }
 }
+function saveViewerState(id) {
+  const viewer = viewerRefs.get(id);
+  if (viewer && typeof viewer.getAnnotations === "function") {
+    const annotations = viewer.getAnnotations();
+    if (annotations.length > 0) {
+      savedAnnotations.set(id, annotations);
+    }
+  }
+}
 watch(
   () => props.items,
   (newItems) => {
@@ -139,6 +165,7 @@ function removeTab(id) {
   emit("tab-close", id);
   tabs.value.splice(index, 1);
   viewerRefs.delete(id);
+  savedAnnotations.delete(id);
   if (activeTabId.value === id) {
     const newIndex = Math.min(index, tabs.value.length - 1);
     activeTabId.value = tabs.value[newIndex]?.id ?? "";
@@ -151,6 +178,9 @@ function removeTab(id) {
 }
 function activateTab(id) {
   if (tabs.value.some((t) => t.id === id)) {
+    if (activeTabId.value && activeTabId.value !== id) {
+      saveViewerState(activeTabId.value);
+    }
     activeTabId.value = id;
     emit("update:activeTab", id);
   }

package/dist/runtime/components/ViewerTabs.vue.d.ts

@@ -16,6 +16,8 @@ export interface ViewerTabItem {
     viewMode?: ViewMode;
     /** Zoom override for this document. */
     zoom?: number;
+    /** Enable shape detection for this document. */
+    shapeDetection?: boolean;
 }
 export interface AddTabOptions {
     /** Insert at specific index. Defaults to end. */
@@ -38,6 +40,8 @@ type __VLS_Props = {
     textLayer?: boolean;
     /** When true, all viewers are in view-only mode. */
     readonly?: boolean;
+    /** Enable shape detection on all Viewer instances. Can be overridden per tab. */
+    shapeDetection?: boolean;
     /** Default view mode for tabs without a per-tab override. */
     viewMode?: ViewMode;
     /** Default zoom for tabs without a per-tab override. */
@@ -148,6 +152,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         closable?: boolean | undefined;
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
+        shapeDetection?: boolean | undefined;
     };
 }, __VLS_33: {
     tab: {
@@ -246,6 +251,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         closable?: boolean | undefined;
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
+        shapeDetection?: boolean | undefined;
     };
 }, __VLS_35: {};
 type __VLS_Slots = {} & {
@@ -361,6 +367,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         closable?: boolean | undefined;
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
+        shapeDetection?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:activeTab": (id: string) => any;
@@ -372,7 +379,15 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     "onTab-added"?: ((tab: ViewerTabItem) => any) | undefined;
     "onTab-close"?: ((id: string) => any) | undefined;
     "onTab-removed"?: ((id: string) => any) | undefined;
-}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+}>, {
+    userName: string;
+    zoom: number;
+    stamps: StampDefinition[];
+    signatureHandlers: SignatureHandlers;
+    viewMode: ViewMode;
+    defaultActiveTab: string;
+    minTabs: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/form-fields/FormCheckbox.vue

@@ -1,5 +1,36 @@
 <template>
-  <div class="kviewer-form-checkbox">
+  <!-- Detected shape: custom × icon on transparent background -->
+  <div
+    v-if="isDetected"
+    class="kviewer-form-checkbox kviewer-form-checkbox--detected"
+    :class="{
+  'kviewer-form-checkbox--circle': props.field.shapeType === 'circle',
+  'kviewer-form-checkbox--checked': isChecked
+}"
+    role="checkbox"
+    :aria-checked="isChecked"
+    :aria-disabled="isReadOnly"
+    tabindex="0"
+    @click="toggle"
+    @keydown.space.prevent="toggle"
+    @keydown.enter.prevent="toggle"
+  >
+    <svg
+      v-if="isChecked"
+      class="kviewer-form-checkbox__icon"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2.5"
+      stroke-linecap="round"
+    >
+      <line x1="3" y1="3" x2="13" y2="13" />
+      <line x1="13" y1="3" x2="3" y2="13" />
+    </svg>
+  </div>
+
+  <!-- Real PDF form field: native checkbox -->
+  <div v-else class="kviewer-form-checkbox">
     <input
       type="checkbox"
       :checked="isChecked"
@@ -19,11 +50,16 @@ const props = defineProps({
 });
 const formFields = useFormFields();
 const state = useViewerState();
+const isDetected = computed(() => props.field.shapeType != null);
 const isReadOnly = computed(() => state.readonly.value || props.field.readOnly);
 const isChecked = computed(() => {
   const fv = formFields.getFieldValue(props.field.id);
   return fv?.value === true;
 });
+function toggle() {
+  if (isReadOnly.value) return;
+  formFields.setFieldValue(props.field.id, !isChecked.value);
+}
 function onChange(event) {
   const target = event.target;
   formFields.setFieldValue(props.field.id, target.checked);

package/dist/runtime/components/tools/ActionTools.vue

@@ -5,6 +5,7 @@
       variant="ghost"
       color="neutral"
       size="sm"
+      data-testid="action-undo"
       :disabled="!state.history.canUndo.value"
       @click="state.history.undo"
     />
@@ -13,6 +14,7 @@
       variant="ghost"
       color="neutral"
       size="sm"
+      data-testid="action-redo"
       :disabled="!state.history.canRedo.value"
       @click="state.history.redo"
     />
@@ -21,6 +23,7 @@
       :variant="state.activeTool.value === 'eraser' ? 'soft' : 'ghost'"
       color="neutral"
       size="sm"
+      data-testid="action-eraser"
       @click="state.selectTool('eraser')"
     />
   </div>

package/dist/runtime/components/tools/PageInfo.vue

@@ -1,5 +1,5 @@
 <template>
-  <span v-if="state.totalPages.value" class="text-xs text-muted">
+  <span v-if="state.totalPages.value" class="text-xs text-muted" data-testid="page-info">
     {{ state.totalPages.value }} pages
   </span>
 </template>

package/dist/runtime/components/tools/SearchTool.vue

@@ -6,6 +6,7 @@
       color="neutral"
       size="xs"
       title="Search"
+      data-testid="search-toggle"
       @click="toggleOpen"
     />
 
@@ -21,11 +22,12 @@
         color="neutral"
         size="xs"
         class="w-56"
+        data-testid="search-input"
         @update:model-value="onQueryChange"
         @keydown="onInputKeydown"
       />
 
-      <span class="min-w-16 text-center text-[11px] text-muted">
+      <span class="min-w-16 text-center text-[11px] text-muted" data-testid="search-status">
         {{ statusLabel }}
       </span>
 

package/dist/runtime/components/tools/ZoomControls.vue

@@ -7,6 +7,7 @@
       color="neutral"
       size="xs"
       class="w-24"
+      data-testid="zoom-select"
       @update:model-value="onZoomChange"
     />
     <UButton
@@ -14,6 +15,7 @@
       variant="ghost"
       color="neutral"
       size="xs"
+      data-testid="zoom-out"
       @click="state.zoomOut"
     />
     <UButton
@@ -21,6 +23,7 @@
       variant="ghost"
       color="neutral"
       size="xs"
+      data-testid="zoom-in"
       @click="state.zoomIn"
     />
   </div>

package/dist/runtime/composables/shape-detection-utils.d.ts

@@ -0,0 +1,38 @@
+import type { PageViewport } from 'pdfjs-dist';
+import type { DetectedShape, DetectedShapeType } from '../annotation/engine/types.js';
+export interface ViewportRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    w: number;
+    h: number;
+}
+/**
+ * Convert a PDF-space bounding box to viewport-space rect.
+ * PDF origin is bottom-left; viewport origin is top-left.
+ */
+export declare function pdfRectToViewport(viewport: PageViewport, x1: number, y1: number, x2: number, y2: number): ViewportRect;
+/**
+ * True if a viewport-space rect looks like a checkbox / radio button.
+ * Size: 15–120 px on each axis. Aspect ratio: 0.6–1.4 (roughly square).
+ */
+export declare function isCheckboxLikeViewport(w: number, h: number): boolean;
+/**
+ * True if PDF-space dimensions look checkbox-sized (5–40 pt, roughly square).
+ * Used for the operator-stream scan before coordinate conversion.
+ */
+export declare function isCheckboxLikePdf(w: number, h: number): boolean;
+/**
+ * Widget-specific size check (Layer 1).
+ *
+ * For actual PDF form fields (Widget annotations) we KNOW the shape is a
+ * real interactive element, so we use a more lenient minimum size (8 px
+ * instead of 15 px) to avoid rejecting small checkboxes at lower zoom levels.
+ * Wide text-input widgets are still excluded via the aspect-ratio guard.
+ */
+export declare function isCheckboxLikeWidget(w: number, h: number): boolean;
+/** Build a DetectedShape record from viewport-space left / top / w / h. */
+export declare function makeShape(id: string, left: number, top: number, w: number, h: number, shapeType?: DetectedShapeType): DetectedShape;
+/** Characters that indicate checkbox / radio icon-font glyphs. */
+export declare const SYMBOL_CHARS: Set<string>;

package/dist/runtime/composables/shape-detection-utils.js

@@ -0,0 +1,50 @@
+export function pdfRectToViewport(viewport, x1, y1, x2, y2) {
+  const [vx1, vy1] = viewport.convertToViewportPoint(x1, y1);
+  const [vx2, vy2] = viewport.convertToViewportPoint(x2, y2);
+  const left = Math.min(vx1, vx2);
+  const top = Math.min(vy1, vy2);
+  const right = Math.max(vx1, vx2);
+  const bottom = Math.max(vy1, vy2);
+  return { left, top, right, bottom, w: right - left, h: bottom - top };
+}
+export function isCheckboxLikeViewport(w, h) {
+  if (w < 15 || w > 120 || h < 15 || h > 120) return false;
+  const ratio = w / h;
+  return ratio > 0.6 && ratio < 1.4;
+}
+export function isCheckboxLikePdf(w, h) {
+  const aw = Math.abs(w);
+  const ah = Math.abs(h);
+  if (aw < 5 || aw > 40 || ah < 5 || ah > 40) return false;
+  const ratio = aw / ah;
+  return ratio >= 0.8 && ratio <= 1.25;
+}
+export function isCheckboxLikeWidget(w, h) {
+  if (w < 8 || w > 200 || h < 8 || h > 200) return false;
+  const ratio = w / h;
+  return ratio > 0.4 && ratio < 2.5;
+}
+export function makeShape(id, left, top, w, h, shapeType) {
+  return {
+    id,
+    rect: { x: left, y: top, w, h },
+    center: { x: left + w / 2, y: top + h / 2 },
+    size: Math.max(w, h),
+    shapeType
+  };
+}
+export const SYMBOL_CHARS = /* @__PURE__ */ new Set([
+  "\u25CB",
+  "\u25CF",
+  "\u25EF",
+  "\u25C9",
+  "\u2299",
+  "\u25CE",
+  "\u2B1C",
+  "\u2B1B",
+  "\u2610",
+  "\u2611",
+  "\u2612",
+  "\u25FB",
+  "\u25FC"
+]);

package/dist/runtime/composables/useFormFields.d.ts

@@ -1,5 +1,5 @@
 import { type ShallowRef } from 'vue';
-import type { FormFieldDefinition, FormFieldValue } from '../annotation/engine/types.js';
+import type { DetectedShape, FormFieldDefinition, FormFieldValue } from '../annotation/engine/types.js';
 export interface FormFieldsState {
     /** Field definitions grouped by page number */
     fieldDefinitions: ShallowRef<Map<number, FormFieldDefinition[]>>;
@@ -19,6 +19,8 @@ export interface FormFieldsState {
     setFieldValueByName: (fieldName: string, value: string | boolean | string[]) => void;
     /** Reset all field values to their defaults (keeps definitions) */
     resetValues: () => void;
+    /** Create synthetic checkbox form fields from detected shapes */
+    registerDetectedCheckboxes: (pageNumber: number, shapes: DetectedShape[], scale: number, pageHeight: number) => void;
     /** Clear all values and definitions (for document change) */
     reset: () => void;
 }

package/dist/runtime/composables/useFormFields.js

@@ -69,6 +69,52 @@ export function provideFormFields() {
     }
     return "";
   }
+  function registerDetectedCheckboxes(pageNumber, shapes, scale, pageHeight) {
+    const existingDefs = fieldDefinitions.value.get(pageNumber) ?? [];
+    const existingCenters = existingDefs.map((d) => ({
+      cx: (d.rect[0] + d.rect[2]) / 2,
+      cy: (d.rect[1] + d.rect[3]) / 2,
+      hw: (d.rect[2] - d.rect[0]) / 2,
+      hh: (d.rect[3] - d.rect[1]) / 2
+    }));
+    const newDefs = [];
+    for (let i = 0; i < shapes.length; i++) {
+      const s = shapes[i];
+      const pdfX1 = s.rect.x / scale;
+      const pdfX2 = (s.rect.x + s.rect.w) / scale;
+      const pdfY1 = pageHeight - (s.rect.y + s.rect.h) / scale;
+      const pdfY2 = pageHeight - s.rect.y / scale;
+      const overlaps = existingCenters.some(
+        (ec) => ec.cx >= pdfX1 && ec.cx <= pdfX2 && ec.cy >= pdfY1 && ec.cy <= pdfY2
+      );
+      if (overlaps) continue;
+      const fieldId = `detected-chk-p${pageNumber}-${i}`;
+      newDefs.push({
+        id: fieldId,
+        pageNumber,
+        fieldType: "checkbox",
+        fieldName: `DetectedCheckbox_p${pageNumber}_${i}`,
+        rect: [pdfX1, pdfY1, pdfX2, pdfY2],
+        readOnly: false,
+        required: false,
+        exportValue: "Yes",
+        defaultValue: "Off",
+        shapeType: s.shapeType
+      });
+    }
+    if (newDefs.length === 0) return;
+    fieldDefinitions.value.set(pageNumber, [...existingDefs, ...newDefs]);
+    triggerRef(fieldDefinitions);
+    for (const def of newDefs) {
+      fieldValues.value.set(def.id, {
+        fieldId: def.id,
+        fieldName: def.fieldName,
+        fieldType: "checkbox",
+        value: false
+      });
+    }
+    triggerRef(fieldValues);
+  }
   function resetValues() {
     for (const [, defs] of fieldDefinitions.value.entries()) {
       for (const def of defs) {
@@ -95,6 +141,7 @@ export function provideFormFields() {
     getFieldsForPage,
     getAllFieldValues,
     setFieldValueByName,
+    registerDetectedCheckboxes,
     resetValues,
     reset
   };

package/dist/runtime/composables/useShapeDetection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shape Detection Composable
+ *
+ * Detects checkbox-like shapes on each PDF page using three layers:
+ *   1. PDF annotations (Widget, Btn, Square, Circle form fields)
+ *   2. Graphical shapes from the operator stream (vector rectangles / circles)
+ *   3. Icon-font glyphs from the text layer (Unicode symbols, Private Use Area)
+ *
+ * Used by the auto-stamp feature to snap stamps onto existing form checkboxes.
+ */
+import type { PDFPageProxy, PageViewport } from 'pdfjs-dist';
+import type { DetectedShape } from '../annotation/engine/types.js';
+export interface ShapeDetection {
+    /** Run all three detection layers on a page and cache the results. */
+    preprocessShapesForPage: (pageNumber: number, pdfPage: PDFPageProxy, viewport: PageViewport) => Promise<DetectedShape[]>;
+    /** Fast O(n) lookup: first shape whose rect contains (x, y). */
+    findShapeAtPoint: (pageNumber: number, x: number, y: number) => DetectedShape | null;
+    /** Clear cached shapes for one page (e.g. after a zoom change). */
+    clearShapeCache: (pageNumber: number) => void;
+    /** Clear the entire shape cache (e.g. when a new PDF is loaded). */
+    clearAllShapeCache: () => void;
+}
+export declare function createShapeDetection(): ShapeDetection;
+export declare function useShapeDetection(): ShapeDetection;