kviewer 0.2.4 → 0.3.0

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.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

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

@@ -63,7 +63,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

@@ -9,6 +9,14 @@ export declare class EditorStamp extends Editor {
     private stampHeight;
     constructor(editorOptions: IEditorOptions, defaultStampUrl: string | null);
     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

@@ -21,12 +21,37 @@ export class EditorStamp extends Editor {
     const scale = this.konvaStage?.scale()?.x ?? 1;
     showCursorPreview(this.stampUrl, Math.round(baseSize * scale));
   }
+  /**
+   * 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 ?? 120;
+    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;
@@ -83,7 +108,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/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/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;
+};

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

@@ -0,0 +1,20 @@
+export const WHITE_CUTOFF = 240;
+export const WHITE_SOFT_EDGE = 180;
+export function knockOutWhite(data, cutoff = WHITE_CUTOFF, softEdge = WHITE_SOFT_EDGE) {
+  for (let i = 0; i < data.length; i += 4) {
+    const luminance = 0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2];
+    if (luminance >= cutoff) {
+      data[i + 3] = 0;
+    } else if (luminance > softEdge) {
+      const ratio = (cutoff - luminance) / (cutoff - softEdge);
+      data[i + 3] = Math.round(data[i + 3] * ratio);
+    }
+  }
+}
+export function fitWithin(width, height, maxWidth, maxHeight) {
+  const scale = Math.min(maxWidth / width, maxHeight / height, 1);
+  return {
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale))
+  };
+}

package/dist/runtime/assets/kviewer.css

@@ -1 +1 @@
-.kviewer-text-layer{left:0;line-height:1;overflow:hidden;position:absolute;top:0;-webkit-user-select:none;-moz-user-select:none;user-select:none;z-index:1}.kviewer-text-layer--interactive{cursor:text;-webkit-user-select:text;-moz-user-select:text;user-select:text}.KViewer_is_painting.KViewer_painting_type_12 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_12 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_13 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_13 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_5 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_5 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_6 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_6 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_7 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_7 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_8 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_8 .kviewer-annotation-layer *{cursor:crosshair!important}.KViewer_is_painting.KViewer_painting_type_4 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_4 .kviewer-annotation-layer *{cursor:text!important}.KViewer_is_painting.KViewer_painting_type_11 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_11 .kviewer-annotation-layer *{cursor:crosshair!important}.KViewer_selector_hover{cursor:pointer!important}.kviewer-form-layer{left:0;overflow:hidden;position:absolute;top:0}.kviewer-form-field{box-sizing:border-box;position:absolute}.kviewer-form-input{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 14%,transparent);border:1px solid transparent;box-sizing:border-box;color:#000;display:block;font-family:-apple-system,BlinkMacSystemFont,Helvetica Neue,Helvetica,Arial,sans-serif;font-weight:500;height:100%;line-height:normal;margin:0;outline:none;padding:1px 2px;resize:none;width:100%;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;text-rendering:optimizeLegibility;vertical-align:top}.kviewer-form-input:hover{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 22%,transparent);border-color:rgba(0,0,0,.2)}.kviewer-form-input:focus{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 28%,transparent);border-color:var(--kvw-field-color,var(--color-primary,#3b82f6));outline:2px solid var(--kvw-field-color,var(--color-primary,#3b82f6))}.kviewer-form-uselect{align-items:center;background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 14%,transparent);border:1px solid transparent;border-radius:0;box-sizing:border-box;color:#000;cursor:pointer;display:flex;height:100%;line-height:1;padding:0 11px 0 2px;width:100%}.kviewer-form-uselect:hover{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 22%,transparent);border-color:rgba(0,0,0,.2)}.kviewer-form-uselect:focus-visible{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 28%,transparent);outline:2px solid var(--kvw-field-color,var(--color-primary,#3b82f6));outline-offset:-2px}.kviewer-form-uselect:disabled{cursor:default}.kviewer-form-listbox{overflow-y:auto;padding:0}.kviewer-form-listbox option{padding:1px 3px}.kviewer-form-editable-combo{height:100%;position:relative;width:100%}.kviewer-form-editable-combo input{height:100%;width:100%}.kviewer-form-checkbox,.kviewer-form-radio{align-items:center;background:#fff;box-sizing:border-box;cursor:pointer;display:flex;height:100%;justify-content:center;width:100%}.kviewer-form-checkbox input,.kviewer-form-radio input{accent-color:var(--kvw-field-color,var(--color-primary,#3b82f6));cursor:pointer;height:80%;margin:0;max-height:18px;max-width:18px;width:80%}.kviewer-form-checkbox--detected{background:transparent}.kviewer-form-checkbox--circle{border-radius:50%}.kviewer-form-checkbox__icon{color:#1a1a1a;height:65%;width:65%}.kviewer-form-checkbox--circle .kviewer-form-checkbox__icon{height:50%;width:50%}.kviewer-form-radio input{accent-color:var(--kvw-field-color,var(--color-primary,#3b82f6));cursor:pointer;height:80%;margin:0;max-height:18px;max-width:18px;width:80%}.kviewer-form-button{align-items:center;background:#c8c8c8;border:1px solid rgba(0,0,0,.35);box-sizing:border-box;color:#000;cursor:pointer;display:flex;font-family:inherit;font-weight:700;height:100%;justify-content:center;line-height:1;padding:0 6px;text-align:center;width:100%;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.kviewer-form-button:hover{background:#bdbdbd}.kviewer-form-button:active{background:#b0b0b0}.kviewer-form-signature{align-items:center;background:rgba(255,255,200,.15);border:1px dashed rgba(0,0,0,.2);cursor:pointer;display:flex;height:100%;justify-content:center;width:100%}.kviewer-form-signature:hover{background:color-mix(in srgb,var(--kvw-field-color,#3b82f6) 8%,transparent);border-color:var(--kvw-field-color,var(--color-primary,#3b82f6))}.kviewer-form-signature--filled{background:transparent;border-color:transparent;border-style:solid}.kviewer-form-signature__preview{max-height:100%;max-width:100%;-o-object-fit:contain;object-fit:contain}.kviewer-form-signature__placeholder{color:rgba(0,0,0,.4);font-size:10px;pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}
+.kviewer-text-layer{left:0;line-height:1;overflow:hidden;position:absolute;top:0;-webkit-user-select:none;-moz-user-select:none;user-select:none;z-index:1}.kviewer-text-layer--interactive{cursor:text;-webkit-user-select:text;-moz-user-select:text;user-select:text}.KViewer_is_painting.KViewer_painting_type_12 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_12 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_13 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_13 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_5 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_5 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_6 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_6 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_7 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_7 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_8 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_8 .kviewer-annotation-layer *{cursor:crosshair!important}.KViewer_is_painting.KViewer_painting_type_4 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_4 .kviewer-annotation-layer *{cursor:text!important}.KViewer_is_painting.KViewer_painting_type_11 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_11 .kviewer-annotation-layer *{cursor:crosshair!important}.KViewer_selector_hover{cursor:pointer!important}.kviewer-form-layer{left:0;overflow:hidden;position:absolute;top:0}.kviewer-form-field{box-sizing:border-box;position:absolute}.kviewer-form-input{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 14%,transparent);border:1px solid transparent;box-sizing:border-box;color:#000;display:block;font-family:-apple-system,BlinkMacSystemFont,Helvetica Neue,Helvetica,Arial,sans-serif;font-weight:500;height:100%;line-height:normal;margin:0;outline:none;padding:1px 2px;resize:none;width:100%;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;text-rendering:optimizeLegibility;vertical-align:top}.kviewer-form-input:hover{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 22%,transparent);border-color:rgba(0,0,0,.2)}.kviewer-form-input:focus{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 28%,transparent);border-color:var(--kvw-field-color,var(--color-primary,#3b82f6));outline:2px solid var(--kvw-field-color,var(--color-primary,#3b82f6))}.kviewer-form-uselect{align-items:center;background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 14%,transparent);border:1px solid transparent;border-radius:0;box-sizing:border-box;color:#000;cursor:pointer;display:flex;height:100%;line-height:1;padding:0 11px 0 2px;width:100%}.kviewer-form-uselect:hover{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 22%,transparent);border-color:rgba(0,0,0,.2)}.kviewer-form-uselect:focus-visible{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 28%,transparent);outline:2px solid var(--kvw-field-color,var(--color-primary,#3b82f6));outline-offset:-2px}.kviewer-form-uselect:disabled{cursor:default}.kviewer-form-listbox{overflow-y:auto;padding:0}.kviewer-form-listbox option{padding:1px 3px}.kviewer-form-editable-combo{height:100%;position:relative;width:100%}.kviewer-form-editable-combo input{height:100%;width:100%}.kviewer-form-checkbox,.kviewer-form-radio{align-items:center;background:#fff;box-sizing:border-box;cursor:pointer;display:flex;height:100%;justify-content:center;width:100%}.kviewer-form-checkbox input,.kviewer-form-radio input{accent-color:var(--kvw-field-color,var(--color-primary,#3b82f6));cursor:pointer;height:80%;margin:0;max-height:18px;max-width:18px;width:80%}.kviewer-form-checkbox--detected{background:transparent}.kviewer-form-checkbox--circle{border-radius:50%}.kviewer-form-checkbox__icon{color:#1a1a1a;height:65%;width:65%}.kviewer-form-checkbox--circle .kviewer-form-checkbox__icon{height:50%;width:50%}.kviewer-form-radio input{accent-color:var(--kvw-field-color,var(--color-primary,#3b82f6));cursor:pointer;height:80%;margin:0;max-height:18px;max-width:18px;width:80%}.kviewer-form-button{align-items:center;background:#c8c8c8;border:1px solid rgba(0,0,0,.35);box-sizing:border-box;color:#000;cursor:pointer;display:flex;font-family:inherit;font-weight:700;height:100%;justify-content:center;line-height:1;padding:0 6px;text-align:center;width:100%;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.kviewer-form-button:hover{background:#bdbdbd}.kviewer-form-button:active{background:#b0b0b0}.kviewer-form-signature{align-items:center;background:rgba(255,255,200,.15);border:1px dashed rgba(0,0,0,.2);cursor:pointer;display:flex;height:100%;justify-content:center;width:100%}.kviewer-form-signature:hover{background:color-mix(in srgb,var(--kvw-field-color,#3b82f6) 8%,transparent);border-color:var(--kvw-field-color,var(--color-primary,#3b82f6))}.kviewer-form-signature--filled{background:transparent;border-color:transparent;border-style:solid}.kviewer-form-signature__preview{max-height:100%;max-width:100%;-o-object-fit:contain;object-fit:contain}.kviewer-form-signature__placeholder{color:rgba(0,0,0,.4);font-size:10px;pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.kviewer-form-signature--static{cursor:default}.kviewer-form-signature--static:hover{background:rgba(255,255,200,.15);border-color:rgba(0,0,0,.2)}.kviewer-form-signature__marker{align-items:center;display:inline-flex;gap:4px}.kviewer-form-signature__marker-icon{flex:0 0 auto;height:12px;width:12px}

package/dist/runtime/components/FormFieldLayer.vue

@@ -48,7 +48,12 @@ const state = useViewerState();
 const fields = computed(() => formFields.getFieldsForPage(props.pageNumber));
 const selectedFieldId = formFields.selectedPlacedFieldId;
 watch(() => state.formEditMode.value, (enabled) => {
-  if (!enabled) formFields.selectPlacedField(null);
+  if (enabled) return;
+  const id = formFields.selectedPlacedFieldId.value;
+  if (!id) return;
+  const def = formFields.getFieldById(id);
+  const keepsChrome = formFields.editablePlacedFields.value && def?.origin === "placed";
+  if (!keepsChrome) formFields.selectPlacedField(null);
 });
 watch(() => state.activeTool.value, (tool) => {
   const isFormFieldTool = typeof tool === "number" && (tool === AnnotationType.FORM_TEXT || tool === AnnotationType.FORM_CHECKBOX || tool === AnnotationType.FORM_RADIO || tool === AnnotationType.FORM_SIGNATURE);

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

@@ -1,5 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
-import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
 import type { ViewerToolEntry } from '../toolbar-tools.js';
@@ -35,6 +35,21 @@ type __VLS_Props = {
      *  drives this — typically by binding it to a role picker in its own
      *  UI. Supports v-model via `v-model:active-role-id`. */
     activeRoleId?: string | null;
+    /** When true, clicking an unsigned signature field opens kviewer's own
+     *  signing flow (saved signature or draw modal). Off by default so hosts
+     *  that own the signing process (e.g. an embedding e-sign app) don't get
+     *  a competing canvas — fields then render as passive markers. */
+    clickToSign?: boolean;
+    /** When true, user-placed form fields show selection chrome and can be
+     *  moved/resized/deleted in hand mode even outside form-edit mode.
+     *  Fields parsed from the source PDF are unaffected. */
+    editablePlacedFields?: boolean;
+    /** Per-field-type presets merged into every field the user places via
+     *  the placement tools (e.g. a signature `promptText` or `lockAction`).
+     *  `fieldName` stays auto-generated — rename via the `field-placed`
+     *  event and `updateFormField()`. Programmatic `addFormField()` calls
+     *  are not affected. */
+    fieldDefaults?: PlacedFieldDefaults;
     /** Execute embedded JavaScript inside the PDF — field-level AA scripts
      *  (Mouse Up, Calculate, Format, Validate, Keystroke), document-level
      *  open actions, and page-level scripts. Powered by pdf.js's QuickJS
@@ -98,6 +113,32 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     removeFormField: (id: string) => void;
     /** All form-field definitions (parsed, detected, and placed), flat. */
     getFormFields: () => FormFieldDefinition[];
+    /** Replace the per-field-type presets applied to tool placements.
+     *  Programmatic counterpart to the `fieldDefaults` prop. */
+    setFieldDefaults: (defaults: PlacedFieldDefaults) => void;
+    /** Enable/disable kviewer's built-in click-to-sign flow at runtime.
+     *  Programmatic counterpart to the `clickToSign` prop. */
+    setClickToSign: (enabled: boolean) => void;
+    /** Subscribe to tool placements (imperative mirror of the
+     *  `field-placed` event, used by the embed bridge). Returns an
+     *  unsubscribe function. */
+    onFieldPlaced: (cb: (field: FormFieldDefinition) => void) => (() => void);
+    /** True once every signature field in the document is signed — via a
+     *  value applied in this session or a digital signature already in the
+     *  source PDF. Vacuously true when the document has no signature
+     *  fields, so combine with `getSignatureFieldStatus().length` if you
+     *  need "at least one". Use to gate e.g. envelope finalization. */
+    getSignedStatus: () => boolean;
+    /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
+     *  signed, roleId). */
+    getSignatureFieldStatus: () => SignatureFieldStatus[];
+    /** Subscribe to signed-status changes (imperative mirror of the
+     *  `signed-status-changed` event, used by the embed bridge). Returns
+     *  an unsubscribe function. */
+    onSignedStatusChanged: (cb: (payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => void) => (() => void);
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */
@@ -114,20 +155,32 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     resetViewedPages: () => void;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "all-pages-read": () => any;
+    "field-placed": (field: FormFieldDefinition) => any;
     "update:formEditMode": (value: boolean) => any;
     "update:activeRoleId": (value: string | null) => any;
     "update:viewedPages": (pages: number[]) => any;
+    "signed-status-changed": (payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onAll-pages-read"?: (() => any) | undefined;
+    "onField-placed"?: ((field: FormFieldDefinition) => any) | undefined;
     "onUpdate:formEditMode"?: ((value: boolean) => any) | undefined;
     "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
     "onUpdate:viewedPages"?: ((pages: number[]) => any) | undefined;
+    "onSigned-status-changed"?: ((payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;
     zoom: number;
+    clickToSign: boolean;
     readonly: boolean;
     active: boolean;
+    locale: KviewerLocale;
     menuItems: ViewerMenuItem[];
     tools: ViewerToolEntry[];
     scripting: boolean;
@@ -138,7 +191,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     formEditMode: boolean;
     roleColors: Record<string, string>;
     activeRoleId: string | null;
-    locale: KviewerLocale;
+    editablePlacedFields: boolean;
+    fieldDefaults: PlacedFieldDefaults;
     messages: KviewerMessageOverrides;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/runtime/components/Viewer.vue

@@ -242,6 +242,9 @@ const props = defineProps({
   formEditMode: { type: Boolean, required: false, default: void 0 },
   roleColors: { type: Object, required: false, default: void 0 },
   activeRoleId: { type: [String, null], required: false, default: void 0 },
+  clickToSign: { type: Boolean, required: false, default: false },
+  editablePlacedFields: { type: Boolean, required: false, default: false },
+  fieldDefaults: { type: Object, required: false, default: void 0 },
   scripting: { type: Boolean, required: false, default: false },
   menuItems: { type: Array, required: false, default: void 0 },
   tools: { type: Array, required: false, default: void 0 },
@@ -252,7 +255,9 @@ const slots = useSlots();
 const toolSlotNames = computed(
   () => Object.keys(slots).filter((name) => name.startsWith("tool-"))
 );
-const emit = defineEmits(["update:formEditMode", "update:activeRoleId", "update:viewedPages", "all-pages-read"]);
+const emit = defineEmits(["update:formEditMode", "update:activeRoleId", "update:viewedPages", "all-pages-read", "field-placed", "signed-status-changed"]);
+const fieldPlacedCallbacks = /* @__PURE__ */ new Set();
+const signedStatusCallbacks = /* @__PURE__ */ new Set();
 const viewerRoot = ref(null);
 const scrollContainer = ref(null);
 const { state: viewerState, setScrollToPageFn, setDownloadPdfFn, setApplyScaleFn } = provideViewerState();
@@ -262,6 +267,9 @@ watchEffect(() => {
 watchEffect(() => {
   viewerState.shapeDetection.value = props.shapeDetection ?? false;
 });
+watchEffect(() => {
+  viewerState.clickToSign.value = props.clickToSign ?? false;
+});
 watch(
   () => props.formEditMode,
   (v) => {
@@ -293,6 +301,28 @@ watch(
   },
   { immediate: true }
 );
+watch(
+  () => props.fieldDefaults,
+  (v) => {
+    formFieldsState.setPlacedFieldDefaults(v ?? {});
+  },
+  { immediate: true }
+);
+watch(
+  () => props.editablePlacedFields,
+  (v) => {
+    formFieldsState.setEditablePlacedFields(v ?? false);
+  },
+  { immediate: true }
+);
+const signatureStatus = computed(() => formFieldsState.getSignatureFieldStatus());
+const signatureStatusKey = (fields) => fields.map((s) => `${s.id}|${s.fieldName}|${s.signed ? 1 : 0}`).join(";");
+watch(signatureStatus, (next, prev) => {
+  if (prev && signatureStatusKey(next) === signatureStatusKey(prev)) return;
+  const payload = { allSigned: next.every((s) => s.signed), fields: next };
+  emit("signed-status-changed", payload);
+  for (const cb of signedStatusCallbacks) cb(payload);
+});
 watch(
   () => props.activeRoleId,
   (v) => {
@@ -918,7 +948,12 @@ onMounted(() => {
     userName: props.userName,
     onRequestTextInput,
     onPlaceField: (payload) => {
-      formFieldsState.addPlacedField(payload);
+      const def = formFieldsState.addPlacedField(payload);
+      if (!viewerState.formEditMode.value && formFieldsState.editablePlacedFields.value) {
+        formFieldsState.selectPlacedField(def.id);
+      }
+      emit("field-placed", def);
+      for (const cb of fieldPlacedCallbacks) cb(def);
       viewerState.selectTool("hand");
     },
     getFormFieldPreviewColor: () => {
@@ -1070,6 +1105,37 @@ defineExpose({
   removeFormField: (id) => formFieldsState.removePlacedField(id),
   /** All form-field definitions (parsed, detected, and placed), flat. */
   getFormFields: () => formFieldsState.getAllFields(),
+  /** Replace the per-field-type presets applied to tool placements.
+   *  Programmatic counterpart to the `fieldDefaults` prop. */
+  setFieldDefaults: (defaults) => formFieldsState.setPlacedFieldDefaults(defaults),
+  /** Enable/disable kviewer's built-in click-to-sign flow at runtime.
+   *  Programmatic counterpart to the `clickToSign` prop. */
+  setClickToSign: (enabled) => {
+    viewerState.clickToSign.value = enabled;
+  },
+  /** Subscribe to tool placements (imperative mirror of the
+   *  `field-placed` event, used by the embed bridge). Returns an
+   *  unsubscribe function. */
+  onFieldPlaced: (cb) => {
+    fieldPlacedCallbacks.add(cb);
+    return () => fieldPlacedCallbacks.delete(cb);
+  },
+  /** True once every signature field in the document is signed — via a
+   *  value applied in this session or a digital signature already in the
+   *  source PDF. Vacuously true when the document has no signature
+   *  fields, so combine with `getSignatureFieldStatus().length` if you
+   *  need "at least one". Use to gate e.g. envelope finalization. */
+  getSignedStatus: () => formFieldsState.getSignatureFieldStatus().every((s) => s.signed),
+  /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
+   *  signed, roleId). */
+  getSignatureFieldStatus: () => formFieldsState.getSignatureFieldStatus(),
+  /** Subscribe to signed-status changes (imperative mirror of the
+   *  `signed-status-changed` event, used by the embed bridge). Returns
+   *  an unsubscribe function. */
+  onSignedStatusChanged: (cb) => {
+    signedStatusCallbacks.add(cb);
+    return () => signedStatusCallbacks.delete(cb);
+  },
   /** Reactive form-edit-mode flag — read with `.value`. */
   formEditMode: viewerState.formEditMode,
   /** Programmatically enter or leave form-edit mode. */