kviewer 0.2.4 → 0.3.1

package/README.md

@@ -88,7 +88,7 @@ By default the toolbar is fully built-in. Pass `tools` to choose which buttons r
 </template>
 ```
 
-`separator`/`spacer` are layout primitives (`spacer` right-aligns what follows). `tools` controls buttons only — it never gates programmatic `state.selectTool(...)` access. Form-edit mode is API-only (`v-model:form-edit-mode` / `setFormEditMode()` / `toggleFormEditMode()`); there is no built-in toggle button. See the [toolbar configuration docs](https://github.com/uppt/nuxt-kviewer) for the full tool-ID list and the array that reproduces the default toolbar.
+`separator`/`spacer` are layout primitives (`spacer` right-aligns what follows). `tools` controls buttons only — it never gates programmatic `state.selectTool(...)` access. Form-edit mode is API-only (`v-model:form-edit-mode` / `setFormEditMode()` / `toggleFormEditMode()`); there is no built-in toggle button. See the [toolbar configuration docs](https://kviewer.wrench.kabema-digital.de/api/kviewer#configuring-the-toolbar) for the full tool-ID list and the array that reproduces the default toolbar.
 
 ## Viewer Ref API
 
@@ -185,6 +185,18 @@ A page counts as read once its top edge scrolls into view (computed from geometr
 
 The same surface is available over the [embed bridge](src/runtime/embed): `client.allPagesRead()`, `client.getViewedPages()`, `client.resetViewedPages()`, and the `all-pages-read` / `viewedPages-changed` events via `client.on(...)`.
 
+## Migrating to v0.3.0
+
+The built-in **click-to-sign** flow on signature fields is now **opt-in** (previously always on). Without it, signature fields render as passive markers (signature icon + a localized "Signature" label) and clicking them does nothing — so an embedding e-sign product's own signing process stays the only entry point.
+
+To restore the previous behavior:
+
+```vue
+<KViewer :source="pdfUrl" click-to-sign />
+```
+
+or at runtime via `viewer.setClickToSign(true)` / the embed bridge's `client.setClickToSign(true)`. A field's `promptText` now only applies to the click-to-sign placeholder; signature values set programmatically always render.
+
 ## Development
 
 <details>

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "kviewer",
   "configKey": "kviewer",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -72,6 +72,15 @@ const module$1 = defineNuxtModule({
     const require_ = createRequire(import.meta.url);
     const pdfjsDir = dirname(require_.resolve("pdfjs-dist/package.json"));
     nuxt.hook("nitro:config", (nitroConfig) => {
+      nitroConfig.externals ||= {};
+      nitroConfig.externals.inline ||= [];
+      if (Array.isArray(nitroConfig.externals.inline)) {
+        for (const dependency of ["unhead", "consola"]) {
+          if (!nitroConfig.externals.inline.includes(dependency)) {
+            nitroConfig.externals.inline.push(dependency);
+          }
+        }
+      }
       nitroConfig.publicAssets ||= [];
       nitroConfig.publicAssets.push(
         {

package/dist/runtime/annotation/engine/config.d.ts

@@ -44,6 +44,7 @@ export declare const defaultOptions: {
         STROKE_WIDTH: number;
         OPACITY: number;
         MAX_CURSOR_SIZE: number;
+        MAX_PLACEMENT_SIZE: number;
         MAX_UPLOAD_IMAGE_SIZE: number;
         LOAD_PDF_ANNOTATION: boolean;
         DB_CLICK_DELETE: boolean;

package/dist/runtime/annotation/engine/config.js

@@ -74,6 +74,10 @@ export const defaultOptions = {
     STROKE_WIDTH: 2,
     OPACITY: 1,
     MAX_CURSOR_SIZE: 96,
+    // Bound for stamps/signatures placed without explicit dimensions. Shared
+    // by the placement path and the cursor preview so the ghost cannot drift
+    // from what actually lands on the page.
+    MAX_PLACEMENT_SIZE: 120,
     MAX_UPLOAD_IMAGE_SIZE: 800,
     LOAD_PDF_ANNOTATION: true,
     DB_CLICK_DELETE: false

package/dist/runtime/annotation/engine/cursor-preview.d.ts

@@ -1,2 +1,15 @@
-export declare function showCursorPreview(imageUrl: string, size?: number): void;
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/**
+ * Bumped whenever the preview is torn down or replaced. Callers that size the
+ * preview asynchronously capture it first and bail if it moved, so a slow
+ * measurement cannot resurrect a ghost for a tool the user already left.
+ */
+export declare function cursorPreviewToken(): number;
+/** Synchronous hit for an already-measured image, so repeat picks don't flash. */
+export declare function peekImageSize(imageUrl: string): ImageSize | null;
+export declare function measureImage(imageUrl: string): Promise<ImageSize | null>;
+export declare function showCursorPreview(imageUrl: string, width?: number, height?: number): void;
 export declare function hideCursorPreview(): void;

package/dist/runtime/annotation/engine/cursor-preview.js

@@ -4,6 +4,32 @@ const PADDING = 6;
 const CROSSHAIR_SIZE = 12;
 let previewEl = null;
 let mouseMoveHandler = null;
+let previewToken = 0;
+const naturalSizeCache = /* @__PURE__ */ new Map();
+export function cursorPreviewToken() {
+  return previewToken;
+}
+export function peekImageSize(imageUrl) {
+  return naturalSizeCache.get(imageUrl) ?? null;
+}
+export function measureImage(imageUrl) {
+  const cached = naturalSizeCache.get(imageUrl);
+  if (cached) return Promise.resolve(cached);
+  return new Promise((resolve) => {
+    const img = new Image();
+    img.addEventListener("load", () => {
+      const size = { width: img.naturalWidth, height: img.naturalHeight };
+      if (!size.width || !size.height) {
+        resolve(null);
+        return;
+      }
+      naturalSizeCache.set(imageUrl, size);
+      resolve(size);
+    });
+    img.addEventListener("error", () => resolve(null));
+    img.src = imageUrl;
+  });
+}
 function isOverPage(e) {
   const target = e.target;
   if (!target) return false;
@@ -21,16 +47,15 @@ function onMouseMove(e) {
     document.body.style.cursor = "";
   }
 }
-export function showCursorPreview(imageUrl, size = 80) {
+export function showCursorPreview(imageUrl, width = 80, height = width) {
   hideCursorPreview();
-  const outerSize = size + PADDING * 2;
   previewEl = document.createElement("div");
   Object.assign(previewEl.style, {
     position: "fixed",
     zIndex: "9999",
     pointerEvents: "none",
-    width: `${outerSize}px`,
-    height: `${outerSize}px`,
+    width: `${width + PADDING * 2}px`,
+    height: `${height + PADDING * 2}px`,
     transform: "translate(-50%, -50%)",
     border: `2px solid ${PRIMARY_COLOR}`,
     borderRadius: "3px",
@@ -41,8 +66,8 @@ export function showCursorPreview(imageUrl, size = 80) {
   const img = document.createElement("img");
   img.src = imageUrl;
   Object.assign(img.style, {
-    width: `${size}px`,
-    height: `${size}px`,
+    width: `${width}px`,
+    height: `${height}px`,
     objectFit: "contain",
     display: "block",
     pointerEvents: "none"
@@ -76,6 +101,7 @@ export function showCursorPreview(imageUrl, size = 80) {
   document.addEventListener("mousemove", mouseMoveHandler);
 }
 export function hideCursorPreview() {
+  previewToken++;
   if (previewEl) {
     previewEl.remove();
     previewEl = null;

package/dist/runtime/annotation/engine/editor/editor.d.ts

@@ -33,6 +33,8 @@ export declare abstract class Editor {
     currentShapeGroup: IShapeGroup | null;
     protected getStylusModeEnabled?: () => boolean;
     protected freehandGroupingDelay: number;
+    private lastPointerDownAt;
+    private lastPointerDownPos;
     static MinSize: number;
     constructor({ userName, konvaStage, pageNumber, annotation, onAdd, editorType, onChange, getStylusModeEnabled, freehandGroupingDelay, }: IEditorOptions & {
         editorType: AnnotationType;
@@ -40,6 +42,13 @@ export declare abstract class Editor {
     private dispatchAddEvent;
     private dispatchChangedEvent;
     protected enableEditMode(): void;
+    /**
+     * Returns true when this pointer-down is a duplicate of the immediately
+     * preceding one (same spot, within {@link DUPLICATE_DOWN_MS}). See the
+     * constant docs: this catches the iOS ghost click and stylus contact
+     * bounce that would otherwise commit two overlapping annotations per tap.
+     */
+    private isDuplicatePointerDown;
     protected disableEditMode(): void;
     protected getBgLayer(konvaStage?: Konva.Stage): Konva.Layer;
     protected delShapeGroup(id: string): void;
@@ -62,6 +71,14 @@ export declare abstract class Editor {
     activate(konvaStage: Konva.Stage, annotation: IAnnotationType): void;
     rebindEvents(): void;
     addSerializedGroupToLayer(konvaStage: Konva.Stage, konvaString: string): void;
+    /**
+     * Attach a rehydrated group to the page layer AND register it in
+     * shapeGroupStore. Registration is what lets the painter resolve this
+     * editor as the group's owner (findEditorForGroupId) — without it,
+     * drag/transform changes to the group are silently never persisted.
+     * Subclasses that override addSerializedGroupToLayer must call this.
+     */
+    protected adoptHydratedGroup(konvaStage: Konva.Stage, ghostGroup: Konva.Group): void;
     deleteGroup(id: string, konvaStage: Konva.Stage): void;
     updateStyle(annotationStore: IAnnotationStore, style: IAnnotationStyle): void;
     static Timer: Map<number, {

package/dist/runtime/annotation/engine/editor/editor.js

@@ -2,6 +2,8 @@ import Konva from "konva";
 import { formatTimestamp, generateUUID } from "../utils.js";
 import { SHAPE_GROUP_NAME } from "../const.js";
 import { isStylusTouch } from "../input-device.js";
+const DUPLICATE_DOWN_MS = 400;
+const DUPLICATE_DOWN_DISTANCE = 12;
 export class Editor {
   userName;
   id;
@@ -15,6 +17,8 @@ export class Editor {
   currentShapeGroup;
   getStylusModeEnabled;
   freehandGroupingDelay;
+  lastPointerDownAt = 0;
+  lastPointerDownPos = null;
   static MinSize = 8;
   constructor({
     userName,
@@ -87,7 +91,9 @@ export class Editor {
   enableEditMode() {
     const stylusEnabled = this.getStylusModeEnabled?.() ?? false;
     this.konvaStage.on("mousedown", (e) => {
-      if (e.evt.button === 0) this.mouseDownHandler(e);
+      if (e.evt.button !== 0) return;
+      if (this.isDuplicatePointerDown()) return;
+      this.mouseDownHandler(e);
     });
     this.konvaStage.on("mousemove", (e) => {
       this.mouseMoveHandler(e);
@@ -97,29 +103,42 @@ export class Editor {
     });
     this.konvaStage.on("touchstart", (e) => {
       if (e.evt.touches.length !== 1) return;
-      if (stylusEnabled) {
-        if (!isStylusTouch(e.evt)) return;
-        e.evt.preventDefault();
-      }
+      if (stylusEnabled && !isStylusTouch(e.evt)) return;
+      e.evt.preventDefault();
+      if (this.isDuplicatePointerDown()) return;
       this.mouseDownHandler(e);
     });
     this.konvaStage.on("touchmove", (e) => {
       if (e.evt.touches.length !== 1) return;
-      if (stylusEnabled) {
-        if (!isStylusTouch(e.evt)) return;
-        if (this.isPainting) e.evt.preventDefault();
-      }
+      if (stylusEnabled && !isStylusTouch(e.evt)) return;
+      if (this.isPainting) e.evt.preventDefault();
       this.mouseMoveHandler(e);
     });
     this.konvaStage.on("touchend", (e) => {
-      if (stylusEnabled) {
-        const touch = e.evt.changedTouches?.[0];
-        const isStylus = touch && "touchType" in touch && touch.touchType === "stylus";
-        if (!isStylus) return;
-      }
+      if (stylusEnabled && !isStylusTouch(e.evt)) return;
+      e.evt.preventDefault();
       this.mouseUpHandler(e);
     });
   }
+  /**
+   * Returns true when this pointer-down is a duplicate of the immediately
+   * preceding one (same spot, within {@link DUPLICATE_DOWN_MS}). See the
+   * constant docs: this catches the iOS ghost click and stylus contact
+   * bounce that would otherwise commit two overlapping annotations per tap.
+   */
+  isDuplicatePointerDown() {
+    const pos = this.konvaStage.getRelativePointerPosition();
+    const now = Date.now();
+    const prevAt = this.lastPointerDownAt;
+    const prevPos = this.lastPointerDownPos;
+    this.lastPointerDownAt = now;
+    this.lastPointerDownPos = pos ? { x: pos.x, y: pos.y } : null;
+    if (!pos || !prevPos) return false;
+    if (now - prevAt > DUPLICATE_DOWN_MS) return false;
+    const dx = pos.x - prevPos.x;
+    const dy = pos.y - prevPos.y;
+    return dx * dx + dy * dy <= DUPLICATE_DOWN_DISTANCE * DUPLICATE_DOWN_DISTANCE;
+  }
   disableEditMode() {
     this.isPainting = false;
     this.konvaStage.off("click mousedown mousemove mouseup touchstart touchmove touchend");
@@ -211,11 +230,21 @@ export class Editor {
     this.enableEditMode();
   }
   addSerializedGroupToLayer(konvaStage, konvaString) {
-    this.konvaStage = konvaStage;
     const ghostGroup = Konva.Node.create(konvaString);
     if (ghostGroup instanceof Konva.Container) {
       ghostGroup.find((node) => node instanceof Konva.Shape).forEach((shape) => shape.strokeScaleEnabled(true));
     }
+    this.adoptHydratedGroup(konvaStage, ghostGroup);
+  }
+  /**
+   * Attach a rehydrated group to the page layer AND register it in
+   * shapeGroupStore. Registration is what lets the painter resolve this
+   * editor as the group's owner (findEditorForGroupId) — without it,
+   * drag/transform changes to the group are silently never persisted.
+   * Subclasses that override addSerializedGroupToLayer must call this.
+   */
+  adoptHydratedGroup(konvaStage, ghostGroup) {
+    this.konvaStage = konvaStage;
     const id = ghostGroup.id();
     this.getBgLayer(konvaStage).add(ghostGroup);
     if (this.shapeGroupStore.has(id)) return;

package/dist/runtime/annotation/engine/tools/signature.js

@@ -1,9 +1,14 @@
 import Konva from "konva";
 import { AnnotationType } from "../types.js";
-import { resizeImage } from "../utils.js";
 import { Editor } from "../editor/editor.js";
 import { defaultOptions } from "../config.js";
-import { showCursorPreview } from "../cursor-preview.js";
+import {
+  cursorPreviewToken,
+  measureImage,
+  peekImageSize,
+  showCursorPreview
+} from "../cursor-preview.js";
+import { cursorPreviewSize, placementSize } from "../../utils/placement_size.js";
 export class EditorSignature extends Editor {
   signatureUrl;
   signatureImage;
@@ -15,7 +20,23 @@ export class EditorSignature extends Editor {
     }
   }
   createCursorImg() {
-    showCursorPreview(this.signatureUrl, defaultOptions.setting.MAX_CURSOR_SIZE);
+    const scale = this.konvaStage?.scale()?.x ?? 1;
+    const max = defaultOptions.setting.MAX_PLACEMENT_SIZE;
+    const cached = cursorPreviewSize(null, peekImageSize(this.signatureUrl), max, scale);
+    if (cached) {
+      showCursorPreview(this.signatureUrl, cached.width, cached.height);
+      return;
+    }
+    const token = cursorPreviewToken();
+    void measureImage(this.signatureUrl).then((natural) => {
+      if (cursorPreviewToken() !== token) return;
+      const size = cursorPreviewSize(null, natural, max, scale);
+      if (size) {
+        showCursorPreview(this.signatureUrl, size.width, size.height);
+      } else {
+        showCursorPreview(this.signatureUrl, defaultOptions.setting.MAX_CURSOR_SIZE);
+      }
+    });
   }
   mouseDownHandler(e) {
     if (e.currentTarget !== this.konvaStage) return;
@@ -25,7 +46,11 @@ export class EditorSignature extends Editor {
     const pos = this.konvaStage.getRelativePointerPosition();
     Konva.Image.fromURL(this.signatureUrl, async (image) => {
       const { width: width_rec, height: height_rec } = image.getClientRect();
-      const { newWidth, newHeight } = resizeImage(width_rec, height_rec, 120);
+      const { width: newWidth, height: newHeight } = placementSize(
+        null,
+        { width: width_rec, height: height_rec },
+        defaultOptions.setting.MAX_PLACEMENT_SIZE
+      ) ?? { width: width_rec, height: height_rec };
       const crosshair = { x: newWidth / 2, y: newHeight / 2 };
       this.signatureImage = image;
       this.signatureImage.setAttrs({
@@ -63,7 +88,7 @@ export class EditorSignature extends Editor {
       oldImage.destroy();
       ghostGroup.add(image);
     });
-    this.getBgLayer(konvaStage).add(ghostGroup);
+    this.adoptHydratedGroup(konvaStage, ghostGroup);
   }
   mouseMoveHandler() {
   }

package/dist/runtime/annotation/engine/tools/stamp.d.ts

@@ -8,7 +8,16 @@ export declare class EditorStamp extends Editor {
     private stampWidth;
     private stampHeight;
     constructor(editorOptions: IEditorOptions, defaultStampUrl: string | null);
+    private get explicitSize();
     private createCursorImg;
+    /**
+     * True when an identical stamp (same source image) already sits under the
+     * tap point. Guards against dropping a second, overlapping copy on a spot
+     * that's already stamped — e.g. a flaky stylus misses a tap, the user
+     * re-sweeps the column, and re-hits cells that already carry a cross.
+     * Distance is compared in stage-content units so it is zoom-independent.
+     */
+    private hasIdenticalStampNear;
     protected mouseDownHandler(e: KonvaEventObject<MouseEvent | TouchEvent>): void;
     activateWithStamp(konvaStage: Konva.Stage, annotation: IAnnotationType, stampUrl: string | null, stampWidth?: number, stampHeight?: number): void;
     addSerializedGroupToLayer(konvaStage: Konva.Stage, konvaString: string): void;

package/dist/runtime/annotation/engine/tools/stamp.js

@@ -1,9 +1,17 @@
 import Konva from "konva";
 import { AnnotationType } from "../types.js";
-import { resizeImage } from "../utils.js";
 import { Editor } from "../editor/editor.js";
 import { defaultOptions } from "../config.js";
-import { showCursorPreview } from "../cursor-preview.js";
+import {
+  cursorPreviewToken,
+  measureImage,
+  peekImageSize,
+  showCursorPreview
+} from "../cursor-preview.js";
+import {
+  cursorPreviewSize,
+  placementSize
+} from "../../utils/placement_size.js";
 export class EditorStamp extends Editor {
   stampUrl;
   stampImage;
@@ -16,27 +24,71 @@ export class EditorStamp extends Editor {
       this.createCursorImg();
     }
   }
+  get explicitSize() {
+    return { width: this.stampWidth ?? 0, height: this.stampHeight ?? 0 };
+  }
   createCursorImg() {
-    const baseSize = this.stampWidth ?? this.stampHeight ?? defaultOptions.setting.MAX_CURSOR_SIZE;
     const scale = this.konvaStage?.scale()?.x ?? 1;
-    showCursorPreview(this.stampUrl, Math.round(baseSize * scale));
+    const max = defaultOptions.setting.MAX_PLACEMENT_SIZE;
+    const immediate = cursorPreviewSize(
+      this.explicitSize,
+      peekImageSize(this.stampUrl),
+      max,
+      scale
+    );
+    if (immediate) {
+      showCursorPreview(this.stampUrl, immediate.width, immediate.height);
+      return;
+    }
+    const token = cursorPreviewToken();
+    void measureImage(this.stampUrl).then((natural) => {
+      if (cursorPreviewToken() !== token) return;
+      const size = cursorPreviewSize(this.explicitSize, natural, max, scale);
+      if (size) {
+        showCursorPreview(this.stampUrl, size.width, size.height);
+      } else {
+        showCursorPreview(this.stampUrl, defaultOptions.setting.MAX_CURSOR_SIZE);
+      }
+    });
+  }
+  /**
+   * True when an identical stamp (same source image) already sits under the
+   * tap point. Guards against dropping a second, overlapping copy on a spot
+   * that's already stamped — e.g. a flaky stylus misses a tap, the user
+   * re-sweeps the column, and re-hits cells that already carry a cross.
+   * Distance is compared in stage-content units so it is zoom-independent.
+   */
+  hasIdenticalStampNear(pos, size) {
+    const threshold = Math.max(8, size * 0.5);
+    const t2 = threshold * threshold;
+    const images = this.konvaStage.find("Image");
+    for (const img of images) {
+      if (img.getAttr("base64") !== this.stampUrl) continue;
+      const rect = img.getClientRect({ relativeTo: this.konvaStage });
+      const cx = rect.x + rect.width / 2;
+      const cy = rect.y + rect.height / 2;
+      const dx = cx - pos.x;
+      const dy = cy - pos.y;
+      if (dx * dx + dy * dy <= t2) return true;
+    }
+    return false;
   }
   mouseDownHandler(e) {
     if (e.currentTarget !== this.konvaStage) return;
+    const pos = this.konvaStage.getRelativePointerPosition();
+    if (!pos) return;
+    const estimatedSize = this.stampWidth ?? this.stampHeight ?? defaultOptions.setting.MAX_PLACEMENT_SIZE;
+    if (this.hasIdenticalStampNear(pos, estimatedSize)) return;
     this.stampImage = null;
     this.currentShapeGroup = this.createShapeGroup();
     this.getBgLayer().add(this.currentShapeGroup.konvaGroup);
-    const pos = this.konvaStage.getRelativePointerPosition();
     Konva.Image.fromURL(this.stampUrl, async (image) => {
-      let newWidth;
-      let newHeight;
-      if (this.stampWidth && this.stampHeight) {
-        newWidth = this.stampWidth;
-        newHeight = this.stampHeight;
-      } else {
-        const { width: width_rec, height: height_rec } = image.getClientRect();
-        ({ newWidth, newHeight } = resizeImage(width_rec, height_rec, 120));
-      }
+      const { width: width_rec, height: height_rec } = image.getClientRect();
+      const { width: newWidth, height: newHeight } = placementSize(
+        this.explicitSize,
+        { width: width_rec, height: height_rec },
+        defaultOptions.setting.MAX_PLACEMENT_SIZE
+      ) ?? { width: width_rec, height: height_rec };
       const crosshair = { x: newWidth / 2, y: newHeight / 2 };
       this.stampImage = image;
       this.stampImage.setAttrs({
@@ -83,7 +135,7 @@ export class EditorStamp extends Editor {
         oldText.moveToTop();
       }
     });
-    this.getBgLayer(konvaStage).add(ghostGroup);
+    this.adoptHydratedGroup(konvaStage, ghostGroup);
   }
   mouseMoveHandler() {
   }

package/dist/runtime/annotation/engine/types.d.ts

@@ -294,6 +294,31 @@ export interface AddFormFieldPayload {
     /** 0 = left, 1 = center, 2 = right. */
     textAlignment?: number;
 }
+/**
+ * Preset properties applied to fields the user places via the placement
+ * tools. `pageNumber`/`rect`/`fieldType` come from the gesture;
+ * `fieldName`/`buttonValue` stay auto-generated so name uniqueness and
+ * radio grouping keep working — rename via the `field-placed` event and
+ * `updateFormField()` instead.
+ */
+export type PlacedFieldDefaultProps = Partial<Omit<AddFormFieldPayload, 'pageNumber' | 'rect' | 'fieldType' | 'fieldName' | 'buttonValue'>>;
+/** Per-field-type presets for tool placements, keyed by {@link FormFieldType}. */
+export type PlacedFieldDefaults = Partial<Record<FormFieldType, PlacedFieldDefaultProps>>;
+/**
+ * Signed-state snapshot of one signature widget. `signed` is true when the
+ * widget holds a signature image applied in this session OR the source PDF
+ * already carries a digital signature for the field (`signedInSource`).
+ * Lets a host (e.g. an e-sign app) gate finalization on all fields being
+ * signed — see `getSignedStatus()` / the `signedStatus-changed` event.
+ */
+export interface SignatureFieldStatus {
+    id: string;
+    fieldName: string;
+    pageNumber: number;
+    signed: boolean;
+    /** Present when the field is tagged with a host role. */
+    roleId?: string;
+}
 export interface DetectedShapeRect {
     x: number;
     y: number;

package/dist/runtime/annotation/engine/utils.d.ts

@@ -7,10 +7,7 @@ export declare function generateUUID(): string;
 export declare function setCssCustomProperty(propertyName: string, value: string): void;
 export declare function removeCssCustomProperty(propertyName: string): void;
 export declare function base64ToImageBitmap(base64: string): Promise<ImageBitmap>;
-export declare function resizeImage(width: number, height: number, max: number): {
-    newWidth: number;
-    newHeight: number;
-};
+export { resizeImage } from '../utils/placement_size.js';
 export declare function convertToRGB(array: number[], index?: number): string;
 export declare function formatTimestamp(timestamp: number): string;
 export declare function formatPDFDate(dateString: string | null, full?: boolean): string;

package/dist/runtime/annotation/engine/utils.js

@@ -67,16 +67,7 @@ export async function base64ToImageBitmap(base64) {
   const blob = new Blob([bytes], { type: "image/png" });
   return await createImageBitmap(blob);
 }
-export function resizeImage(width, height, max) {
-  if (width <= max && height <= max) {
-    return { newWidth: width, newHeight: height };
-  }
-  const scaleFactor = Math.min(max / width, max / height);
-  return {
-    newWidth: width * scaleFactor,
-    newHeight: height * scaleFactor
-  };
-}
+export { resizeImage } from "../utils/placement_size.js";
 export function convertToRGB(array, index = 0) {
   if (index < 0 || index * 3 + 2 >= array.length) {
     throw new Error("Index out of bounds");

package/dist/runtime/annotation/pdf-export/export.js

@@ -224,9 +224,6 @@ async function flattenPageAnnotations(pdfDoc, page, annotations) {
       drawX = 0;
       drawY = H_u;
       break;
-    default:
-      drawX = 0;
-      drawY = 0;
   }
   page.drawImage(image, {
     x: drawX,

package/dist/runtime/annotation/utils/placement_size.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sizing rules shared by stamp/signature placement and the drag cursor
+ * preview. They live apart from the engine so both paths derive their size
+ * from one implementation — the ghost drifting from what actually lands on
+ * the page was a real bug, not a hypothetical one.
+ */
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/** Aspect-preserving downscale. Never upscales. */
+export declare function resizeImage(width: number, height: number, max: number): {
+    newWidth: number;
+    newHeight: number;
+};
+/**
+ * The size an annotation will occupy in stage-content units once placed.
+ * Explicit dimensions (a stamp carrying width/height metadata) win outright;
+ * otherwise the image's own aspect ratio is bounded by `max`.
+ */
+export declare function placementSize(explicit: Partial<ImageSize> | null, natural: ImageSize | null, max: number): ImageSize | null;
+/**
+ * The same size expressed in CSS pixels, for the cursor ghost. The Konva stage
+ * scale is what converts content units to what the user actually sees, so a
+ * ghost that ignores it is wrong at every zoom level but 100%.
+ */
+export declare function cursorPreviewSize(explicit: Partial<ImageSize> | null, natural: ImageSize | null, max: number, scale: number): ImageSize | null;

package/dist/runtime/annotation/utils/placement_size.js

@@ -0,0 +1,26 @@
+export function resizeImage(width, height, max) {
+  if (width <= max && height <= max) {
+    return { newWidth: width, newHeight: height };
+  }
+  const scaleFactor = Math.min(max / width, max / height);
+  return {
+    newWidth: width * scaleFactor,
+    newHeight: height * scaleFactor
+  };
+}
+export function placementSize(explicit, natural, max) {
+  if (explicit?.width && explicit?.height) {
+    return { width: explicit.width, height: explicit.height };
+  }
+  if (!natural?.width || !natural?.height) return null;
+  const { newWidth, newHeight } = resizeImage(natural.width, natural.height, max);
+  return { width: newWidth, height: newHeight };
+}
+export function cursorPreviewSize(explicit, natural, max, scale) {
+  const size = placementSize(explicit, natural, max);
+  if (!size) return null;
+  return {
+    width: Math.round(size.width * scale),
+    height: Math.round(size.height * scale)
+  };
+}

package/dist/runtime/annotation/utils/signature_image.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pixel helpers for signature images uploaded from disk.
+ *
+ * Kept free of DOM APIs (they take plain pixel buffers, not canvases) so
+ * the behaviour is unit-testable without a headless browser — the rest
+ * of the upload flow lives in SignatureDrawModal.vue.
+ */
+/**
+ * Scanned or photographed signatures arrive on opaque white paper,
+ * which would cover page content once stamped onto a PDF. Map luminance
+ * to alpha so near-white goes fully transparent and the anti-aliased
+ * edges of the strokes fade out instead of leaving a hard halo.
+ */
+export declare const WHITE_CUTOFF = 240;
+export declare const WHITE_SOFT_EDGE = 180;
+/** Mutates `data` (RGBA, as returned by ImageData) in place. */
+export declare function knockOutWhite(data: Uint8ClampedArray, cutoff?: number, softEdge?: number): void;
+/**
+ * Scale `width`×`height` down to fit inside `maxWidth`×`maxHeight`,
+ * preserving aspect ratio. Never scales up: a signature smaller than the
+ * box is left at its natural size rather than being blown up and blurred.
+ */
+export declare function fitWithin(width: number, height: number, maxWidth: number, maxHeight: number): {
+    width: number;
+    height: number;
+};