kviewer 0.3.4 → 0.3.6

package/dist/module.json

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

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?;

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/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-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}
+.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/Viewer.d.vue.ts

@@ -1,4 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
+import type { ScrollBoundaryPayload } from '../embed/protocol.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';
@@ -26,16 +27,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
@@ -122,9 +113,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[];
@@ -138,6 +131,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
@@ -145,7 +146,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
@@ -154,6 +155,9 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
     }) => void) => (() => void);
+    /** Subscribe to vertical wheel movement left over when the viewer reaches
+     *  a document boundary. Used by the embed bridge for parent scrolling. */
+    onScrollBoundary: (cb: (payload: ScrollBoundaryPayload) => void) => (() => void);
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */
@@ -171,8 +175,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;
@@ -181,8 +186,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;
@@ -204,8 +210,6 @@ 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[];

package/dist/runtime/components/Viewer.vue

@@ -243,8 +243,6 @@ const props = defineProps({
   active: { type: Boolean, required: false, default: true },
   freehandGroupingDelay: { type: Number, required: false, default: 1e3 },
   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 },
@@ -260,9 +258,12 @@ 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", "field-placed", "signed-status-changed"]);
+const emit = defineEmits(["update:formEditMode", "update:viewedPages", "all-pages-read", "field-placed", "field-updated", "field-removed", "signed-status-changed"]);
 const fieldPlacedCallbacks = /* @__PURE__ */ new Set();
 const signedStatusCallbacks = /* @__PURE__ */ new Set();
+const fieldUpdatedCallbacks = /* @__PURE__ */ new Set();
+const fieldRemovedCallbacks = /* @__PURE__ */ new Set();
+const scrollBoundaryCallbacks = /* @__PURE__ */ new Set();
 const viewerRoot = ref(null);
 const scrollContainer = ref(null);
 const { state: viewerState, setScrollToPageFn, setDownloadPdfFn, setPrintPdfFn, setApplyScaleFn } = provideViewerState();
@@ -291,6 +292,15 @@ watch(
 );
 const viewerSearch = provideViewerSearch();
 const formFieldsState = provideFormFields();
+formFieldsState.setFieldEventSink((event) => {
+  if (event.type === "updated") {
+    emit("field-updated", event.field, event.patch);
+    for (const cb of fieldUpdatedCallbacks) cb(event.field, event.patch);
+  } else {
+    emit("field-removed", event.field);
+    for (const cb of fieldRemovedCallbacks) cb(event.field);
+  }
+});
 const kviewerPublicConfig = useRuntimeConfig().public.kviewer;
 provideKviewerI18n(
   computed(() => {
@@ -299,13 +309,6 @@ provideKviewerI18n(
   }),
   computed(() => props.messages ?? {})
 );
-watch(
-  () => props.roleColors,
-  (v) => {
-    formFieldsState.setRoleColors(v ?? {});
-  },
-  { immediate: true }
-);
 watch(
   () => props.fieldDefaults,
   (v) => {
@@ -347,22 +350,6 @@ watch(signatureStatus, (next, prev) => {
   emit("signed-status-changed", payload);
   for (const cb of signedStatusCallbacks) cb(payload);
 });
-watch(
-  () => props.activeRoleId,
-  (v) => {
-    if (v === void 0) return;
-    if (formFieldsState.activeRoleId.value !== v) {
-      formFieldsState.setActiveRole(v);
-    }
-  },
-  { immediate: true }
-);
-watch(
-  () => formFieldsState.activeRoleId.value,
-  (v) => {
-    if (props.activeRoleId !== v) emit("update:activeRoleId", v);
-  }
-);
 const pageSettings = providePageSettings(viewerRoot);
 const virtualization = createPageVirtualization();
 setScrollToPageFn((pageNumber) => {
@@ -878,28 +865,43 @@ function initPanzoom() {
   inertiaPanzoom.attach(zoomWrapper.value);
 }
 let wheelCooldown = false;
+function notifyScrollBoundary(deltaY) {
+  if (deltaY === 0) return;
+  const payload = {
+    edge: deltaY > 0 ? "end" : "start",
+    deltaY
+  };
+  for (const callback of scrollBoundaryCallbacks) callback(payload);
+}
 function onWheel(event) {
   if (event.ctrlKey || event.metaKey) return;
   if (isSinglePageMode.value) {
     event.preventDefault();
-    if (wheelCooldown) return;
+    const total = viewerState.totalPages.value;
+    const cur = viewerState.currentPage.value;
+    const isAtBoundary = event.deltaY > 0 && cur >= total || event.deltaY < 0 && cur <= 1;
+    if (wheelCooldown) {
+      if (isAtBoundary) notifyScrollBoundary(event.deltaY);
+      return;
+    }
     wheelCooldown = true;
     setTimeout(() => {
       wheelCooldown = false;
     }, 300);
-    const total = viewerState.totalPages.value;
-    const cur = viewerState.currentPage.value;
     if (event.deltaY > 0 && cur < total) {
       viewerState.currentPage.value = cur + 1;
     } else if (event.deltaY < 0 && cur > 1) {
       viewerState.currentPage.value = cur - 1;
+    } else {
+      notifyScrollBoundary(event.deltaY);
     }
     return;
   }
   event.preventDefault();
   const dx = event.shiftKey ? event.deltaY : event.deltaX;
   const dy = event.shiftKey ? 0 : event.deltaY;
-  inertiaPanzoom.scrollBy(dx, dy);
+  const remaining = inertiaPanzoom.scrollBy(dx, dy);
+  notifyScrollBoundary(remaining.y);
 }
 function isTextInputTarget(target) {
   if (!(target instanceof HTMLElement)) return false;
@@ -992,11 +994,9 @@ onMounted(() => {
       for (const cb of fieldPlacedCallbacks) cb(def);
       viewerState.selectTool("hand");
     },
-    getFormFieldPreviewColor: () => {
-      const id = formFieldsState.activeRoleId.value;
-      if (!id) return void 0;
-      return formFieldsState.roleColors.value[id];
-    },
+    // The placement drag preview adopts the fieldColor preset of the tool's
+    // field type, so the rubber-band already shows the signer's color.
+    getFormFieldPreviewColor: (fieldType) => formFieldsState.placedFieldDefaults.value[fieldType]?.fieldColor,
     freehandGroupingDelay: props.freehandGroupingDelay,
     // Suspend panzoom gestures while an annotation is being dragged or
     // transformed. Otherwise single-finger pan runs in parallel with the
@@ -1144,10 +1144,12 @@ defineExpose({
    *  The new field is exported into the PDF on `exportPdf()` like any
    *  field placed via the placement tool. */
   addFormField: (payload) => formFieldsState.addFormField(payload),
-  /** Patch a form field by id (rect, name, flags, type-specific props). */
-  updateFormField: (id, patch) => formFieldsState.updatePlacedField(id, patch),
-  /** Remove a form field by id (drops its value too). */
-  removeFormField: (id) => formFieldsState.removePlacedField(id),
+  /** 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, patch) => formFieldsState.updatePlacedField(id, patch, { silent: true }),
+  /** Remove a form field by id (drops its value too). Does not fire
+   *  `field-removed` — that event is for user-driven removals. */
+  removeFormField: (id) => formFieldsState.removePlacedField(id, { silent: true }),
   /** All form-field definitions (parsed, detected, and placed), flat. */
   getFormFields: () => formFieldsState.getAllFields(),
   /** Replace the per-field-type presets applied to tool placements.
@@ -1165,6 +1167,20 @@ defineExpose({
     fieldPlacedCallbacks.add(cb);
     return () => fieldPlacedCallbacks.delete(cb);
   },
+  /** Subscribe to user-driven field edits (imperative mirror of the
+   *  `field-updated` event, used by the embed bridge). Returns an
+   *  unsubscribe function. */
+  onFieldUpdated: (cb) => {
+    fieldUpdatedCallbacks.add(cb);
+    return () => fieldUpdatedCallbacks.delete(cb);
+  },
+  /** Subscribe to user-driven field removals (imperative mirror of the
+   *  `field-removed` event, used by the embed bridge). Returns an
+   *  unsubscribe function. */
+  onFieldRemoved: (cb) => {
+    fieldRemovedCallbacks.add(cb);
+    return () => fieldRemovedCallbacks.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
@@ -1172,7 +1188,7 @@ defineExpose({
    *  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). */
+   *  signed). Correlate to host data by `id`. */
   getSignatureFieldStatus: () => formFieldsState.getSignatureFieldStatus(),
   /** Subscribe to signed-status changes (imperative mirror of the
    *  `signed-status-changed` event, used by the embed bridge). Returns
@@ -1181,6 +1197,12 @@ defineExpose({
     signedStatusCallbacks.add(cb);
     return () => signedStatusCallbacks.delete(cb);
   },
+  /** Subscribe to vertical wheel movement left over when the viewer reaches
+   *  a document boundary. Used by the embed bridge for parent scrolling. */
+  onScrollBoundary: (cb) => {
+    scrollBoundaryCallbacks.add(cb);
+    return () => scrollBoundaryCallbacks.delete(cb);
+  },
   /** Reactive form-edit-mode flag — read with `.value`. */
   formEditMode: viewerState.formEditMode,
   /** Programmatically enter or leave form-edit mode. */

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

@@ -1,4 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
+import type { ScrollBoundaryPayload } from '../embed/protocol.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';
@@ -26,16 +27,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
@@ -122,9 +113,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[];
@@ -138,6 +131,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
@@ -145,7 +146,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
@@ -154,6 +155,9 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
     }) => void) => (() => void);
+    /** Subscribe to vertical wheel movement left over when the viewer reaches
+     *  a document boundary. Used by the embed bridge for parent scrolling. */
+    onScrollBoundary: (cb: (payload: ScrollBoundaryPayload) => void) => (() => void);
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */
@@ -171,8 +175,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;
@@ -181,8 +186,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;
@@ -204,8 +210,6 @@ 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[];

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

@@ -54,11 +54,6 @@ type __VLS_Props = {
     zoom?: number;
     /** Minimum number of tabs -- prevents closing below this count. */
     minTabs?: number;
-    /** Forwarded to every Viewer instance — see KViewer's `roleColors`. */
-    roleColors?: Record<string, string>;
-    /** Forwarded to every Viewer instance — see KViewer's `activeRoleId`.
-     *  Supports v-model via `v-model:active-role-id`. */
-    activeRoleId?: string | null;
     /** Forwarded to every Viewer instance — see KViewer's `scripting`.
      *  Per-tab override via `ViewerTabItem.scripting` wins when set. */
     scripting?: boolean;
@@ -82,7 +77,7 @@ declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
 declare function removeTab(id: string): boolean;
 declare function activateTab(id: string): void;
 declare function getViewer(id: string): ComponentPublicInstance | null;
-declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
+declare var __VLS_7: {}, __VLS_21: {}, __VLS_35: {
     tab: {
         id: string;
         label: string;
@@ -182,7 +177,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_37: {
+}, __VLS_38: {
     tab: {
         id: string;
         label: string;
@@ -282,21 +277,21 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_41: string, __VLS_42: {
+}, __VLS_42: string, __VLS_43: {
     state: import("../composables/useViewerState.js").ViewerState;
-}, __VLS_44: {};
+}, __VLS_45: {};
 type __VLS_Slots = {} & {
-    [K in NonNullable<typeof __VLS_41>]?: (props: typeof __VLS_42) => any;
+    [K in NonNullable<typeof __VLS_42>]?: (props: typeof __VLS_43) => any;
 } & {
     'tabs-leading'?: (props: typeof __VLS_7) => any;
 } & {
     'tabs-trailing'?: (props: typeof __VLS_21) => any;
 } & {
-    header?: (props: typeof __VLS_34) => any;
+    header?: (props: typeof __VLS_35) => any;
 } & {
-    footer?: (props: typeof __VLS_37) => any;
+    footer?: (props: typeof __VLS_38) => any;
 } & {
-    empty?: (props: typeof __VLS_44) => any;
+    empty?: (props: typeof __VLS_45) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     addTab: typeof addTab;
@@ -405,7 +400,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "field-placed": (field: FormFieldDefinition) => any;
-    "update:activeRoleId": (value: string | null) => any;
+    "field-updated": (field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => any;
+    "field-removed": (field: FormFieldDefinition) => any;
     "signed-status-changed": (payload: {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
@@ -416,7 +412,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     "tab-removed": (id: string) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onField-placed"?: ((field: FormFieldDefinition) => any) | undefined;
-    "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
+    "onField-updated"?: ((field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => any) | undefined;
+    "onField-removed"?: ((field: FormFieldDefinition) => any) | undefined;
     "onSigned-status-changed"?: ((payload: {
         allSigned: boolean;
         fields: SignatureFieldStatus[];
@@ -435,8 +432,6 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;
-    roleColors: Record<string, string>;
-    activeRoleId: string | null;
     editablePlacedFields: boolean;
     fieldDefaults: PlacedFieldDefaults;
     selectionItems: ViewerSelectionItem[];