kviewer 0.3.3 → 0.3.5

package/dist/module.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-export { ActiveTool, AddFormFieldPayload, CheckboxStyle, ExportPdfOptions, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, KVIEWER_EMBED_PROTOCOL_VERSION, KVIEWER_EMBED_UNSUPPORTED_METHOD_ERROR_NAME, KViewerApi, KViewerEmbedBridgeOptions, KViewerEmbedClient, KViewerEmbedClientOptions, KViewerEmbedEventName, KViewerEmbedEventPayloads, KViewerEmbedMethodName, KViewerHostApi, PlacedFieldDefaults, SignatureData, SignatureFieldStatus, SignatureHandlers, ViewMode, ViewerBottomToolId, ViewerLayoutToolId, ViewerMenuButtonItem, ViewerMenuCheckboxItem, ViewerMenuItem, ViewerMenuSeparatorItem, ViewerState, ViewerToolEntry, ViewerToolId, ViewerToolSlot, ViewerTopToolId, useKViewerEmbedBridge } from '../dist/runtime/public-types.js';
+export { ActiveTool, AddFormFieldPayload, CheckboxStyle, ExportPdfOptions, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, IAnnotationStore, KVIEWER_EMBED_PROTOCOL_VERSION, KVIEWER_EMBED_UNSUPPORTED_METHOD_ERROR_NAME, KViewerApi, KViewerEmbedBridgeOptions, KViewerEmbedClient, KViewerEmbedClientOptions, KViewerEmbedEventName, KViewerEmbedEventPayloads, KViewerEmbedMethodName, KViewerHostApi, PlacedFieldDefaults, SignatureData, SignatureFieldStatus, SignatureHandlers, ViewMode, ViewerBottomToolId, ViewerLayoutToolId, ViewerMenuButtonItem, ViewerMenuCheckboxItem, ViewerMenuItem, ViewerMenuSeparatorItem, ViewerSelectionButtonItem, ViewerSelectionContext, ViewerSelectionItem, ViewerSelectionSelectItem, ViewerState, ViewerToolEntry, ViewerToolId, ViewerToolSlot, ViewerTopToolId, useKViewerEmbedBridge } from '../dist/runtime/public-types.js';
 
 interface ModuleOptions {
     /**

package/dist/module.json

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

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

@@ -52,6 +52,7 @@ export declare class Selector {
     private marqueeRect;
     private marqueeStartPos;
     private marqueeStage;
+    private suppressStageClick;
     constructor({ konvaCanvasStore, getAnnotationStore, onDelete, onSelected, onMultiSelected, onMultiChanged, onCancel, onChanged, onRequestDeleteConfirm, onFreeTextDoubleClick, getStylusModeEnabled, setExternalGesturesEnabled, }: ISelectorOptions);
     /** Returns true if this event should be rejected (finger touch in stylus mode). */
     private isStylusRejected;

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

@@ -24,6 +24,7 @@ export class Selector {
   marqueeRect = null;
   marqueeStartPos = null;
   marqueeStage = null;
+  suppressStageClick = false;
   constructor({
     konvaCanvasStore,
     getAnnotationStore,
@@ -88,13 +89,17 @@ export class Selector {
   }
   disableStageEvents(konvaStage) {
     konvaStage.off(
-      "click mousedown mousemove mouseup touchstart touchmove touchend pointerdown pointermove pointerup"
+      "click tap mousedown mousemove mouseup touchstart touchmove touchend pointerdown pointermove pointerup"
     );
   }
   bindStageEvents(konvaStage) {
     konvaStage.on("click tap", (e) => {
       if (e.target !== konvaStage) return;
       if (this.isStylusRejected(e.evt)) return;
+      if (this.suppressStageClick) {
+        this.suppressStageClick = false;
+        return;
+      }
       this.clearTransformers();
     });
   }
@@ -474,6 +479,7 @@ export class Selector {
     this.handleShapeClick(shape, konvaStage, false);
   }
   clear() {
+    this.suppressStageClick = false;
     this.clearTransformers();
     this.konvaCanvasStore.forEach((konvaCanvas) => {
       const { konvaStage } = konvaCanvas;
@@ -489,6 +495,7 @@ export class Selector {
     const pageGroups = this.getPageShapeGroups(konvaStage);
     this.disableStageEvents(konvaStage);
     this.bindStageEvents(konvaStage);
+    this.bindMarqueeEvents(konvaStage, { mouseOnly: true });
     this.enableShapeGroups(pageGroups, konvaStage);
     if (this.selectedId) {
       this.selectedShape(this.selectedId, konvaStage);
@@ -519,13 +526,17 @@ export class Selector {
     this.enableShapeGroups(pageGroups, konvaStage);
     this.bindMarqueeEvents(konvaStage);
   }
-  bindMarqueeEvents(konvaStage) {
-    konvaStage.on("mousedown touchstart", (e) => {
+  bindMarqueeEvents(konvaStage, opts = {}) {
+    const { mouseOnly = false } = opts;
+    konvaStage.on(mouseOnly ? "mousedown" : "mousedown touchstart", (e) => {
       if (e.target !== konvaStage) return;
       if (this.isStylusRejected(e.evt)) return;
+      const button = e.evt?.button;
+      if (mouseOnly && button !== void 0 && button !== 0) return;
       if (this.getStylusModeEnabled?.() && e.evt) e.evt.preventDefault();
       this.clearTransformers();
       this.selectedIds = [];
+      this.marqueeRect?.destroy();
       const pos = konvaStage.getRelativePointerPosition();
       if (!pos) return;
       this.marqueeStartPos = pos;
@@ -543,7 +554,7 @@ export class Selector {
       });
       this.getBackgroundLayer(konvaStage).add(this.marqueeRect);
     });
-    konvaStage.on("mousemove touchmove", (e) => {
+    konvaStage.on(mouseOnly ? "mousemove" : "mousemove touchmove", (e) => {
       if (!this.marqueeRect || !this.marqueeStartPos || !this.marqueeStage) return;
       if (this.isStylusRejected(e.evt)) return;
       if (this.getStylusModeEnabled?.() && e.evt) e.evt.preventDefault();
@@ -556,7 +567,7 @@ export class Selector {
       this.marqueeRect.setAttrs({ x, y, width, height });
       this.marqueeStage.batchDraw();
     });
-    konvaStage.on("mouseup touchend", (e) => {
+    konvaStage.on(mouseOnly ? "mouseup" : "mouseup touchend", (e) => {
       if (!this.marqueeRect || !this.marqueeStage) return;
       if (this.isStylusRejected(e.evt)) return;
       const selectionBox = this.marqueeRect.getClientRect();
@@ -567,6 +578,7 @@ export class Selector {
         this.marqueeStage = null;
         return;
       }
+      if (mouseOnly) this.suppressStageClick = true;
       const groups = this.getPageShapeGroups(this.marqueeStage);
       const matchedIds = [];
       groups.forEach((group) => {

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

@@ -1,6 +1,6 @@
 import Konva from 'konva';
 import type { IRect } from 'konva/lib/types';
-import { type IAnnotationStore, type IAnnotationStyle, type IAnnotationType, type PlaceFieldPayload } from './types.js';
+import { type FormFieldType, type IAnnotationStore, type IAnnotationStyle, type IAnnotationType, type PlaceFieldPayload } from './types.js';
 import { type IEditorFreeTextOptions } from './tools/free-text.js';
 export interface KonvaCanvas {
     pageNumber: number;
@@ -26,7 +26,7 @@ export interface PainterCallbacks {
     /** Optional accessor returning the color to use for the form-field
      *  placement preview. Lets the active role color override the default
      *  blue without rebuilding the editor between placements. */
-    getFormFieldPreviewColor?: () => string | undefined;
+    getFormFieldPreviewColor?: (fieldType: FormFieldType) => string | undefined;
 }
 export declare class Painter {
     private userName?;
@@ -128,6 +128,8 @@ export declare class Painter {
     activateEraser(): void;
     highlightRange(range: Range, annotation: IAnnotationType): void;
     selectAnnotation(id: string): void;
+    /** Clears the current annotation selection without touching the store. */
+    clearSelection(): void;
     initAnnotations(annotations: IAnnotationStore[]): Promise<void>;
     update(id: string, updates: Partial<IAnnotationStore>): void;
     delete(id: string, emit?: boolean): void;

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

@@ -624,6 +624,10 @@ export class Painter {
     this.selector.select(id);
     this.callbacks.setDefaultMode();
   }
+  /** Clears the current annotation selection without touching the store. */
+  clearSelection() {
+    this.selector.delete();
+  }
   async initAnnotations(annotations) {
     annotations.forEach((annotation) => {
       this.saveToStore(annotation, true);

package/dist/runtime/annotation/engine/tools/form-field.d.ts

@@ -6,11 +6,11 @@ export interface IEditorFormFieldOptions {
     /** PDF-space page height, needed to flip Konva page-local Y → PDF Y. */
     pageHeight: number;
     onPlaceField: (payload: PlaceFieldPayload) => void;
-    /** Resolves to the active role color so the placement preview matches
-     *  the color the field will be tagged with. Re-read on every drag start
-     *  so the user can switch roles between placements without rebuilding
-     *  the editor. */
-    getPreviewColor?: () => string | undefined;
+    /** Resolves to the fieldColor preset for this field type so the
+     *  placement preview matches the color the field will land with.
+     *  Re-read on every drag start so the host can change defaults between
+     *  placements without rebuilding the editor. */
+    getPreviewColor?: (fieldType: FormFieldType) => string | undefined;
 }
 export declare class EditorFormField extends Editor {
     private fieldType;

package/dist/runtime/annotation/engine/tools/form-field.js

@@ -38,7 +38,7 @@ export class EditorFormField extends Editor {
       y: pos.y,
       width: 0,
       height: 0,
-      stroke: this.getPreviewColor?.() ?? "#1677ff",
+      stroke: this.getPreviewColor?.(this.fieldType) ?? "#1677ff",
       strokeWidth: 1,
       dash: [4, 4],
       strokeScaleEnabled: false,

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

@@ -216,11 +216,17 @@ export interface FormFieldDefinition {
     color?: number[];
     backgroundColor?: number[];
     textAlignment?: number;
-    /** Opaque role tag for color-coding in form-edit mode. The editor
-     *  doesn't own role definitions — the host (integrating app) maps
-     *  roleId → color via the `roleColors` prop on KViewer. Not exported
-     *  to the PDF. */
-    roleId?: string;
+    /** CSS color driving the field's editor chrome (outline, grip, hover
+     *  accents). Host-owned; falls back to the default blue when unset.
+     *  Not exported to the PDF — use `color`/`backgroundColor` for the
+     *  widget's native appearance. Typically set per placement via
+     *  `fieldDefaults` (e.g. one color per signer). */
+    fieldColor?: string;
+    /** Host-owned metadata bag. The editor carries it around untouched —
+     *  it is never read, validated, or exported to the PDF. Must stay
+     *  JSON-serializable so it survives the embed bridge. Replaced
+     *  wholesale by an `updateFormField()` patch (no deep merge). */
+    meta?: Record<string, unknown>;
 }
 export interface FormFieldValue {
     fieldId: string;
@@ -251,8 +257,13 @@ export interface AddFormFieldPayload {
      *  mirrored across them on edit. Radios with the same `fieldName` form
      *  one option group. */
     fieldName?: string;
-    /** Opaque role tag for color-coding in form-edit mode. */
-    roleId?: string;
+    /** CSS color for the field's editor chrome (see
+     *  {@link FormFieldDefinition.fieldColor}). */
+    fieldColor?: string;
+    /** Host-owned metadata bag, carried untouched (see
+     *  {@link FormFieldDefinition.meta}). Also usable as a preset in
+     *  `fieldDefaults` so tool placements get their metadata atomically. */
+    meta?: Record<string, unknown>;
     /** Default value for the field. Becomes the initial value too. */
     defaultValue?: string;
     readOnly?: boolean;
@@ -316,8 +327,6 @@ export interface SignatureFieldStatus {
     fieldName: string;
     pageNumber: number;
     signed: boolean;
-    /** Present when the field is tagged with a host role. */
-    roleId?: string;
 }
 export interface DetectedShapeRect {
     x: number;

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

@@ -6,8 +6,7 @@ import {
   PDFDict,
   PDFName,
   PDFRawStream,
-  PDFString,
-  StandardFonts
+  PDFString
 } from "pdf-lib";
 import { CHECKBOX_STYLE_TABLE } from "../checkbox-styles.js";
 export async function writeFormFieldsToPdf(pdfDoc, fieldValues, placedDefinitions = []) {
@@ -265,7 +264,7 @@ async function createSignatureField(pdfDoc, page, def, fv) {
   if (def.required) sig.setFlagTo(AcroFieldFlags.Required, true);
   const v = fv?.value;
   const signed = typeof v === "string" && v.startsWith("data:image");
-  const appearanceRef = signed ? await buildSignedSignatureAppearance(pdfDoc, v, width, height) : await buildSignaturePlaceholderAppearance(pdfDoc, width, height);
+  const appearanceRef = signed ? await buildSignedSignatureAppearance(pdfDoc, v, width, height) : buildEmptySignatureAppearance(pdfDoc, width, height);
   const widgetDict = context.obj({
     Type: "Annot",
     Subtype: "Widget",
@@ -282,43 +281,21 @@ async function createSignatureField(pdfDoc, page, def, fv) {
   form.acroForm.addField(fieldRef);
   page.node.addAnnot(widgetRef);
 }
-async function buildSignaturePlaceholderAppearance(pdfDoc, width, height) {
+function buildEmptySignatureAppearance(pdfDoc, width, height) {
   const { context } = pdfDoc;
-  const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
-  const label = "Sign here";
-  const fontSize = Math.max(6, Math.min(12, height * 0.4));
-  const textWidth = font.widthOfTextAtSize(label, fontSize);
-  const textHeight = font.heightAtSize(fontSize);
-  const textX = (width - textWidth) / 2;
-  const textY = (height - textHeight) / 2;
-  const ops = [
-    "q",
-    "0.55 0.55 0.55 RG",
-    "0.75 w",
-    "[3 2] 0 d",
-    `0.5 0.5 ${(width - 1).toFixed(3)} ${(height - 1).toFixed(3)} re`,
-    "S",
-    "0.55 0.55 0.55 rg",
-    "BT",
-    `/F1 ${fontSize.toFixed(3)} Tf`,
-    `${textX.toFixed(3)} ${textY.toFixed(3)} Td`,
-    `(${label}) Tj`,
-    "ET",
-    "Q"
-  ].join("\n");
   const dict = context.obj({
     Type: "XObject",
     Subtype: "Form",
     BBox: [0, 0, width, height],
     Matrix: [1, 0, 0, 1, 0, 0],
-    Resources: { Font: { F1: font.ref } }
+    Resources: {}
   });
-  const stream = PDFRawStream.of(dict, new TextEncoder().encode(ops));
+  const stream = PDFRawStream.of(dict, new Uint8Array(0));
   return context.register(stream);
 }
 async function buildSignedSignatureAppearance(pdfDoc, dataUrl, width, height) {
   const match = dataUrl.match(/^data:(image\/[a-zA-Z0-9.+-]+);base64,(.+)$/);
-  if (!match) return buildSignaturePlaceholderAppearance(pdfDoc, width, height);
+  if (!match) return buildEmptySignatureAppearance(pdfDoc, width, height);
   const mimeType = match[1] ?? "";
   const base64 = match[2] ?? "";
   const image = mimeType.includes("jpeg") || mimeType.includes("jpg") ? await pdfDoc.embedJpg(base64) : await pdfDoc.embedPng(base64);

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-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}
+.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-field--readonly.kviewer-form-field--placed{filter:grayscale(.6);opacity:.5}.kviewer-form-field--readonly .kviewer-form-signature,.kviewer-form-field--readonly .kviewer-form-signature:hover{background:rgba(255,255,200,.15);border-color:rgba(0,0,0,.2);cursor:not-allowed}.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-field--editable .kviewer-form-signature,.kviewer-form-field__body--locked .kviewer-form-signature,.kviewer-form-field__body--locked .kviewer-form-signature:hover{border-color:transparent}.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/AnnotationToolbar.vue

@@ -55,6 +55,9 @@
         <UIcon name="i-lucide-pencil" class="text-sm text-muted" />
       </button>
 
+      <!-- Host-supplied custom items (selectionItems prop) -->
+      <SelectionToolbarItems :items="customItems" :ctx="selectionCtx" />
+
       <!-- Delete -->
       <button
         class="flex items-center justify-center w-7 h-7 rounded-md hover:bg-default cursor-pointer"
@@ -69,12 +72,20 @@
 </template>
 
 <script setup>
-import { computed } from "vue";
+import { computed, inject } from "vue";
 import { useViewerState } from "../composables/useViewerState";
 import { useKviewerI18n } from "../composables/useKviewerI18n";
 import { defaultOptions, annotationDefinitions } from "../annotation/engine/config";
 import { AnnotationType } from "../annotation/engine/types";
+import { SELECTION_ITEMS_KEY } from "../selection-items";
+import SelectionToolbarItems from "./SelectionToolbarItems.vue";
 const state = useViewerState();
+const customItems = inject(SELECTION_ITEMS_KEY, void 0);
+const selectionCtx = computed(() => ({
+  kind: "annotation",
+  annotations: state.selectedAnnotations.value.length > 0 ? state.selectedAnnotations.value : state.selectedAnnotation.value ? [state.selectedAnnotation.value] : [],
+  field: null
+}));
 const { t } = useKviewerI18n();
 const colors = defaultOptions.colors;
 const isMultiSelect = computed(() => state.selectedAnnotations.value.length > 1);

package/dist/runtime/components/FormFieldLayer.vue

@@ -2,6 +2,7 @@
   <div
     v-if="fields.length > 0"
     class="kviewer-form-layer"
+    :class="{ 'kviewer-form-layer--interactive': props.pointerEvents === 'auto' }"
     :style="{
   position: 'absolute',
   top: 0,
@@ -11,7 +12,6 @@
   transform: `scale(${props.scale})`,
   transformOrigin: '0 0',
   zIndex: props.zIndex,
-  pointerEvents: props.pointerEvents,
   // Force native form controls (inputs, checkboxes, radios, scrollbars)
   // to render in light mode regardless of the user\'s OS theme — PDF
   // pages have a white background, so dark-mode controls clash.
@@ -57,7 +57,8 @@ watch(() => state.formEditMode.value, (enabled) => {
 });
 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);
-  if (tool !== "hand" && !isFormFieldTool) formFields.selectPlacedField(null);
+  const keepsSelection = tool === "hand" || tool === AnnotationType.SELECT || isFormFieldTool;
+  if (!keepsSelection) formFields.selectPlacedField(null);
 });
 function onKeyDown(e) {
   if (!selectedFieldId.value) return;
@@ -75,3 +76,7 @@ onBeforeUnmount(() => {
   window.removeEventListener("keydown", onKeyDown);
 });
 </script>
+
+<style>
+.kviewer-form-layer{pointer-events:none}.kviewer-form-layer--interactive .kviewer-form-field{pointer-events:auto}.kviewer-form-layer:not(.kviewer-form-layer--interactive) .kviewer-form-field,.kviewer-form-layer:not(.kviewer-form-layer--interactive) .kviewer-placed-chrome,.kviewer-form-layer:not(.kviewer-form-layer--interactive) .kviewer-placed-toolbar{pointer-events:none}
+</style>

package/dist/runtime/components/PdfPage.vue

@@ -63,6 +63,7 @@
   height: cssHeight + 'px',
   zIndex: 3,
   pointerEvents: annotationPointerEvents,
+  cursor: annotationCursor,
   transform: 'translateZ(0)',
   overflow: 'hidden'
 }"
@@ -134,9 +135,31 @@ const annotationPointerEvents = computed(() => {
   if (state.readonly.value) return "none";
   return isSearchTextInteractive.value ? "none" : isAnnotating.value ? "auto" : "none";
 });
+const annotationCursor = computed(() => {
+  const tool = state.activeTool.value;
+  if (tool === "marquee" || tool === "eraser") return "crosshair";
+  if (typeof tool !== "number") return "";
+  switch (tool) {
+    case AnnotationType.NONE:
+    case AnnotationType.SELECT:
+      return "";
+    // Stamp/signature hide the native cursor behind a floating image
+    // preview (body cursor 'none'); an element cursor here would
+    // override that and bring the arrow back on top of the preview.
+    case AnnotationType.STAMP:
+    case AnnotationType.SIGNATURE:
+      return "";
+    case AnnotationType.HIGHLIGHT:
+    case AnnotationType.STRIKEOUT:
+    case AnnotationType.UNDERLINE:
+      return "text";
+    default:
+      return "crosshair";
+  }
+});
 const isUsingAnnotationTool = computed(() => {
   const tool = state.activeTool.value;
-  return tool === "marquee" || tool === "eraser" || typeof tool === "number" && tool !== AnnotationType.NONE;
+  return tool === "marquee" || tool === "eraser" || typeof tool === "number" && tool !== AnnotationType.NONE && tool !== AnnotationType.SELECT;
 });
 const formFieldPointerEvents = computed(() => {
   if (state.readonly.value) return "none";

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

@@ -0,0 +1,8 @@
+import type { ViewerSelectionContext, ViewerSelectionItem } from '../selection-items.js';
+type __VLS_Props = {
+    items: ViewerSelectionItem[] | undefined;
+    ctx: ViewerSelectionContext;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/SelectionToolbarItems.vue

@@ -0,0 +1,43 @@
+<template>
+  <template v-for="item in visibleItems" :key="item.key">
+    <button
+      v-if="item.type === 'button'"
+      class="flex items-center justify-center h-7 rounded-md hover:bg-default cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
+      :class="item.icon ? 'w-7' : 'px-2'"
+      :title="item.label"
+      :disabled="item.disabled"
+      :data-testid="`selection-item-${item.key}`"
+      @click="item.onSelect(props.ctx)"
+    >
+      <UIcon v-if="item.icon" :name="item.icon" class="text-sm text-muted" />
+      <span v-else class="text-xs text-muted whitespace-nowrap">{{ item.label }}</span>
+    </button>
+    <USelect
+      v-else-if="item.type === 'select'"
+      :model-value="selectValue(item)"
+      :items="item.items"
+      :placeholder="item.placeholder"
+      :disabled="item.disabled"
+      :aria-label="item.label"
+      :title="item.label"
+      class="w-24"
+      size="sm"
+      :data-testid="`selection-item-${item.key}`"
+      @update:model-value="(v) => item.onUpdate(String(v), props.ctx)"
+    />
+  </template>
+</template>
+
+<script setup>
+import { computed } from "vue";
+const props = defineProps({
+  items: { type: null, required: true },
+  ctx: { type: Object, required: true }
+});
+const visibleItems = computed(
+  () => (props.items ?? []).filter((item) => item.visible?.(props.ctx) ?? true)
+);
+function selectValue(item) {
+  return typeof item.value === "function" ? item.value(props.ctx) : item.value;
+}
+</script>

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

@@ -0,0 +1,8 @@
+import type { ViewerSelectionContext, ViewerSelectionItem } from '../selection-items.js';
+type __VLS_Props = {
+    items: ViewerSelectionItem[] | undefined;
+    ctx: ViewerSelectionContext;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -3,6 +3,7 @@ import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, Placed
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
 import type { ViewerToolEntry } from '../toolbar-tools.js';
+import { type ViewerSelectionItem } from '../selection-items.js';
 import { type KviewerMessageOverrides } from '../composables/useKviewerI18n.js';
 import { type KviewerLocale } from '../i18n/messages.js';
 type __VLS_Props = {
@@ -25,16 +26,6 @@ type __VLS_Props = {
      *  with selection chrome, can be moved/resized, and the property panel
      *  is shown. Supports v-model via `v-model:form-edit-mode`. */
     formEditMode?: boolean;
-    /** Map of roleId → CSS color used to color-code form fields in
-     *  form-edit mode. The editor stays unopinionated about role
-     *  definitions: the host owns the role list, names, and color picker,
-     *  and just hands a flat lookup table to the viewer. Unknown or
-     *  missing ids fall back to the default blue. */
-    roleColors?: Record<string, string>;
-    /** Active role id new field placements are auto-tagged with. The host
-     *  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
@@ -63,6 +54,11 @@ type __VLS_Props = {
      *  toggles or actions without replacing the entire header. Ignored
      *  when the host supplies a custom `#header` slot. */
     menuItems?: ViewerMenuItem[];
+    /** Custom controls appended to the floating selection popover — shown
+     *  when an annotation or a placed form field (e.g. a signature field)
+     *  is selected. Buttons and selects; every callback receives the
+     *  current selection. See {@link ViewerSelectionItem}. */
+    selectionItems?: ViewerSelectionItem[];
     /** Configures which toolbar tools render and in what order. Entries are
      *  built-in tool IDs (strings) or `{ type: 'slot', ... }` objects that
      *  inject a custom button via a `#tool-<name>` slot. When omitted, the
@@ -116,9 +112,11 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
      *  The new field is exported into the PDF on `exportPdf()` like any
      *  field placed via the placement tool. */
     addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
-    /** Patch a form field by id (rect, name, flags, type-specific props). */
+    /** Patch a form field by id (rect, name, flags, type-specific props).
+     *  Does not fire `field-updated` — that event is for user-driven edits. */
     updateFormField: (id: string, patch: Partial<FormFieldDefinition>) => void;
-    /** Remove a form field by id (drops its value too). */
+    /** Remove a form field by id (drops its value too). Does not fire
+     *  `field-removed` — that event is for user-driven removals. */
     removeFormField: (id: string) => void;
     /** All form-field definitions (parsed, detected, and placed), flat. */
     getFormFields: () => FormFieldDefinition[];
@@ -132,6 +130,14 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
      *  `field-placed` event, used by the embed bridge). Returns an
      *  unsubscribe function. */
     onFieldPlaced: (cb: (field: FormFieldDefinition) => void) => (() => void);
+    /** Subscribe to user-driven field edits (imperative mirror of the
+     *  `field-updated` event, used by the embed bridge). Returns an
+     *  unsubscribe function. */
+    onFieldUpdated: (cb: (field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => void) => (() => void);
+    /** Subscribe to user-driven field removals (imperative mirror of the
+     *  `field-removed` event, used by the embed bridge). Returns an
+     *  unsubscribe function. */
+    onFieldRemoved: (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
@@ -139,7 +145,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
      *  need "at least one". Use to gate e.g. envelope finalization. */
     getSignedStatus: () => boolean;
     /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
-     *  signed, roleId). */
+     *  signed). Correlate to host data by `id`. */
     getSignatureFieldStatus: () => SignatureFieldStatus[];
     /** Subscribe to signed-status changes (imperative mirror of the
      *  `signed-status-changed` event, used by the embed bridge). Returns
@@ -165,8 +171,9 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "all-pages-read": () => any;
     "field-placed": (field: FormFieldDefinition) => any;
+    "field-updated": (field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => any;
+    "field-removed": (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;
@@ -175,8 +182,9 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onAll-pages-read"?: (() => any) | undefined;
     "onField-placed"?: ((field: FormFieldDefinition) => any) | undefined;
+    "onField-updated"?: ((field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => any) | undefined;
+    "onField-removed"?: ((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;
@@ -198,10 +206,9 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;
     shapeDetection: boolean;
-    roleColors: Record<string, string>;
-    activeRoleId: string | null;
     editablePlacedFields: boolean;
     fieldDefaults: PlacedFieldDefaults;
+    selectionItems: ViewerSelectionItem[];
     messages: KviewerMessageOverrides;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;