kviewer 0.3.4 → 0.3.5

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "kviewer",
   "configKey": "kviewer",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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

@@ -26,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
@@ -122,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[];
@@ -138,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
@@ -145,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
@@ -171,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;
@@ -181,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;
@@ -204,8 +206,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,11 @@ 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 viewerRoot = ref(null);
 const scrollContainer = ref(null);
 const { state: viewerState, setScrollToPageFn, setDownloadPdfFn, setPrintPdfFn, setApplyScaleFn } = provideViewerState();
@@ -291,6 +291,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 +308,6 @@ provideKviewerI18n(
   }),
   computed(() => props.messages ?? {})
 );
-watch(
-  () => props.roleColors,
-  (v) => {
-    formFieldsState.setRoleColors(v ?? {});
-  },
-  { immediate: true }
-);
 watch(
   () => props.fieldDefaults,
   (v) => {
@@ -347,22 +349,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) => {
@@ -992,11 +978,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 +1128,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 +1151,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 +1172,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

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

@@ -26,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
@@ -122,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[];
@@ -138,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
@@ -145,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
@@ -171,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;
@@ -181,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;
@@ -204,8 +206,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[];

package/dist/runtime/components/ViewerTabs.vue

@@ -63,13 +63,12 @@
           :menu-items="menuItems"
           :selection-items="selectionItems"
           :tools="tools"
-          :role-colors="roleColors"
-          :active-role-id="activeRoleId"
           :click-to-sign="clickToSign"
           :editable-placed-fields="editablePlacedFields"
           :field-defaults="fieldDefaults"
-          @update:active-role-id="(v) => emit('update:activeRoleId', v)"
           @field-placed="(f) => emit('field-placed', f)"
+          @field-updated="(f, p) => emit('field-updated', f, p)"
+          @field-removed="(f) => emit('field-removed', f)"
           @signed-status-changed="(p) => emit('signed-status-changed', p)"
         >
           <template v-if="$slots.header" #header>
@@ -109,8 +108,6 @@ const props = defineProps({
   viewMode: { type: String, required: false, default: "fit-width" },
   zoom: { type: Number, required: false, default: 1 },
   minTabs: { type: Number, required: false, default: 0 },
-  roleColors: { type: Object, required: false, default: void 0 },
-  activeRoleId: { type: [String, null], required: false, default: void 0 },
   scripting: { type: Boolean, required: false, default: false },
   menuItems: { type: Array, required: false, default: void 0 },
   selectionItems: { type: Array, required: false, default: void 0 },
@@ -123,7 +120,7 @@ const slots = useSlots();
 const toolSlotNames = computed(
   () => Object.keys(slots).filter((name) => name.startsWith("tool-"))
 );
-const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed", "update:activeRoleId", "field-placed", "signed-status-changed"]);
+const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed", "field-placed", "field-updated", "field-removed", "signed-status-changed"]);
 let idCounter = 0;
 function generateId() {
   return `tab-${Date.now()}-${++idCounter}`;

package/dist/runtime/components/ViewerTabs.vue.d.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[];

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

@@ -4,17 +4,19 @@
     :class="{
   'kviewer-form-field--editable': showChrome,
   'kviewer-form-field--placed': isPlaced,
-  'kviewer-form-field--selected': props.selected
+  'kviewer-form-field--selected': props.selected,
+  'kviewer-form-field--readonly': isReadonlyOutsideAuthoring
 }"
     :style="[positionStyle, {
   '--kvw-field-color': chromeColor,
   '--kvw-handle-zoom': handleZoom
 }]"
     :data-element-id="props.field.id"
+    @contextmenu="onContextMenu"
   >
     <div
       class="kviewer-form-field__body"
-      :class="{ 'kviewer-form-field__body--locked': showChrome }"
+      :class="{ 'kviewer-form-field__body--locked': chromeMode === 'authoring' }"
     >
       <FormTextField v-if="props.field.fieldType === 'text'" :field="props.field" />
       <FormCheckbox v-else-if="props.field.fieldType === 'checkbox'" :field="props.field" />
@@ -30,6 +32,7 @@
       :selected="props.selected"
       :scale="props.scale"
       :page-height="props.pageTransform.height"
+      :mode="chromeMode ?? 'authoring'"
       @select="emit('select')"
     />
 
@@ -64,18 +67,27 @@ const state = useViewerState();
 const formFields = useFormFields();
 const isPlaced = computed(() => props.field.origin === "placed");
 const isFormEditMode = computed(() => state.formEditMode.value);
-const showChrome = computed(
-  () => isFormEditMode.value || formFields.editablePlacedFields.value && isPlaced.value
+const chromeMode = computed(() => {
+  if (isFormEditMode.value) return "authoring";
+  if (formFields.editablePlacedFields.value && isPlaced.value && !props.field.readOnly) {
+    return "live";
+  }
+  return null;
+});
+const showChrome = computed(() => chromeMode.value !== null);
+const isReadonlyOutsideAuthoring = computed(
+  () => props.field.readOnly && !isFormEditMode.value
 );
+function onContextMenu(e) {
+  if (chromeMode.value !== "live") return;
+  e.preventDefault();
+  emit("select");
+}
 const handleZoom = computed(() => {
   const totalZoom = (props.scale || 1) * (state.visualZoom.value || 1);
   return (1 / totalZoom).toFixed(3);
 });
-const chromeColor = computed(() => {
-  const id = props.field.roleId;
-  if (!id) return "#1677ff";
-  return formFields.roleColors.value[id] ?? "#1677ff";
-});
+const chromeColor = computed(() => props.field.fieldColor ?? "#1677ff");
 const positionStyle = computed(() => {
   const rect = props.field.rect;
   const r = convertPdfRectToCanvas(props.pageTransform, [rect[0], rect[1], rect[2], rect[3]]);

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

@@ -55,10 +55,18 @@ const signatureUrl = computed(() => {
 });
 const hasSigned = computed(() => !!signatureUrl.value);
 const clickToSignEnabled = computed(() => state.clickToSign.value);
-async function onClickSign() {
-  if (!clickToSignEnabled.value) return;
+const liveEditing = computed(
+  () => formFields.editablePlacedFields.value && props.field.origin === "placed" && !state.formEditMode.value
+);
+async function onClickSign(e) {
   if (props.field.readOnly || state.readonly.value) return;
   if (formFields.isFieldLocked(props.field.id)) return;
+  if (liveEditing.value && (hasSigned.value || !clickToSignEnabled.value)) {
+    e.stopPropagation();
+    formFields.selectPlacedField(props.field.id);
+    return;
+  }
+  if (!clickToSignEnabled.value) return;
   if (state.signatures.value.length > 0) {
     const sig = state.signatures.value[0];
     if (sig) {

package/dist/runtime/components/form-fields/PlacedFieldChrome.d.vue.ts

@@ -6,6 +6,10 @@ type __VLS_Props = {
     scale: number;
     /** PDF-space page height (kept for parity; unused here). */
     pageHeight: number;
+    /** 'authoring' = form-edit mode (chrome is the whole interactive
+     *  surface). 'live' = editablePlacedFields outside form-edit mode
+     *  (chrome is transparent except grip and handles). */
+    mode: 'authoring' | 'live';
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     select: () => any;

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

@@ -1,11 +1,16 @@
 <template>
-  <!-- The whole chrome is the interactive surface in form-edit mode:
-       click to select, drag anywhere to move, plus a label bar above and
-       eight resize handles when selected. -->
+  <!-- Two interaction modes. Authoring (form-edit mode): the whole chrome
+       is the interactive surface — click to select, drag anywhere to move.
+       Live (editablePlacedFields): the surface is transparent so the field
+       body stays usable (click-to-sign, text input); management happens on
+       the always-visible grip ("handle = manage, body = use"). -->
   <div
     ref="rootEl"
     class="kviewer-placed-chrome"
-    :class="{ 'kviewer-placed-chrome--selected': selected }"
+    :class="{
+  'kviewer-placed-chrome--selected': selected,
+  'kviewer-placed-chrome--live': mode === 'live'
+}"
     @pointerdown.stop="onChromePointerDown"
     @click.stop
   >
@@ -17,9 +22,11 @@
 }"
     />
     <div
-      v-if="selected"
+      v-if="selected || mode === 'live'"
       class="kviewer-placed-chrome__grip"
       :title="field.fieldName"
+      @pointerdown.stop="onChromePointerDown"
+      @click.stop
     >
       <UIcon name="i-lucide-grip-vertical" class="kviewer-placed-chrome__grip-dots" />
       <span class="kviewer-placed-chrome__grip-label">{{ field.fieldName }}</span>
@@ -46,7 +53,8 @@ const props = defineProps({
   field: { type: Object, required: true },
   selected: { type: Boolean, required: true },
   scale: { type: Number, required: true },
-  pageHeight: { type: Number, required: true }
+  pageHeight: { type: Number, required: true },
+  mode: { type: String, required: true }
 });
 const emit = defineEmits(["select"]);
 const formFields = useFormFields();
@@ -91,12 +99,16 @@ function onChromePointerDown(e) {
       startRect[2] + dx,
       startRect[3] + pdfDy
     ];
-    formFields.updatePlacedField(props.field.id, { rect: next });
+    formFields.updatePlacedField(props.field.id, { rect: next }, { silent: true });
   };
   const onUp = () => {
     window.removeEventListener("pointermove", onMove);
     window.removeEventListener("pointerup", onUp);
-    if (!dragging) emit("select");
+    if (!dragging) {
+      emit("select");
+      return;
+    }
+    formFields.updatePlacedField(props.field.id, { rect: [...props.field.rect] });
   };
   window.addEventListener("pointermove", onMove);
   window.addEventListener("pointerup", onUp);
@@ -106,6 +118,7 @@ function onHandlePointerDown(e, name) {
   const startY = e.clientY;
   const [sx1, sy1, sx2, sy2] = props.field.rect;
   const s = effectiveScale();
+  let resized = false;
   const onMove = (ev) => {
     const dx = (ev.clientX - startX) / s;
     const dy = (ev.clientY - startY) / s;
@@ -115,11 +128,15 @@ function onHandlePointerDown(e, name) {
     if (name.includes("s")) y1 = Math.min(y2 - 4, sy1 + pdfDy);
     if (name.includes("e")) x2 = Math.max(x1 + 4, sx2 + dx);
     if (name.includes("w")) x1 = Math.min(x2 - 4, sx1 + dx);
-    formFields.updatePlacedField(props.field.id, { rect: [x1, y1, x2, y2] });
+    resized = true;
+    formFields.updatePlacedField(props.field.id, { rect: [x1, y1, x2, y2] }, { silent: true });
   };
   const onUp = () => {
     window.removeEventListener("pointermove", onMove);
     window.removeEventListener("pointerup", onUp);
+    if (resized) {
+      formFields.updatePlacedField(props.field.id, { rect: [...props.field.rect] });
+    }
   };
   window.addEventListener("pointermove", onMove);
   window.addEventListener("pointerup", onUp);
@@ -127,5 +144,5 @@ function onHandlePointerDown(e, name) {
 </script>
 
 <style>
-.kviewer-placed-chrome{cursor:move;inset:0;pointer-events:auto;position:absolute;touch-action:none}.kviewer-placed-chrome__outline{border:1px dashed color-mix(in srgb,var(--kvw-field-color,#1677ff) 45%,transparent);box-sizing:border-box;height:calc(100%/var(--kvw-handle-zoom, 1));left:0;pointer-events:none;position:absolute;top:0;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 0;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__outline--placed{border-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 75%,transparent)}.kviewer-placed-chrome__outline--selected{border:1.5px dashed var(--kvw-field-color,#1677ff)}.kviewer-placed-chrome__grip{align-items:center;background:color-mix(in srgb,var(--kvw-field-color,#1677ff) 15%,transparent);border:1px solid color-mix(in srgb,var(--kvw-field-color,#1677ff) 40%,transparent);border-radius:4px;bottom:calc(100% + 4px*var(--kvw-handle-zoom, 1));box-sizing:border-box;color:var(--kvw-field-color,#1677ff);cursor:move;display:flex;font-size:12px;gap:4px;height:22px;left:0;line-height:1;overflow:hidden;padding:0 8px 0 3px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__grip-dots{color:var(--kvw-field-color,#1677ff);flex:0 0 auto;height:13px;width:13px}.kviewer-placed-chrome__grip-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kviewer-placed-chrome__handle{background:#fff;border:1px solid var(--kvw-field-color,#1677ff);border-radius:2px;height:8px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));width:8px}.kviewer-placed-chrome__handle:before{content:"";inset:-8px;position:absolute}.kviewer-placed-chrome__handle--n{left:50%;top:-4px;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--s{bottom:-4px;left:50%;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--e{right:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--w{left:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--ne{right:-4px;top:-4px}.kviewer-placed-chrome__handle--nw{left:-4px;top:-4px}.kviewer-placed-chrome__handle--se{bottom:-4px;right:-4px}.kviewer-placed-chrome__handle--sw{bottom:-4px;left:-4px}
+.kviewer-placed-chrome{cursor:move;inset:0;pointer-events:auto;position:absolute;touch-action:none}.kviewer-placed-chrome--live{cursor:default;pointer-events:none}.kviewer-placed-chrome__outline{border:1px dashed color-mix(in srgb,var(--kvw-field-color,#1677ff) 45%,transparent);box-sizing:border-box;height:calc(100%/var(--kvw-handle-zoom, 1));left:0;pointer-events:none;position:absolute;top:0;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 0;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__outline--placed{border-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 75%,transparent)}.kviewer-placed-chrome__outline--selected{border:1.5px dashed var(--kvw-field-color,#1677ff)}.kviewer-placed-chrome__grip{align-items:center;background:color-mix(in srgb,var(--kvw-field-color,#1677ff) 15%,transparent);border:1px solid color-mix(in srgb,var(--kvw-field-color,#1677ff) 40%,transparent);border-radius:4px;bottom:calc(100% + 4px*var(--kvw-handle-zoom, 1));box-sizing:border-box;color:var(--kvw-field-color,#1677ff);cursor:move;display:flex;font-size:12px;gap:4px;height:22px;left:0;line-height:1;overflow:hidden;padding:0 8px 0 3px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));transform-origin:0 100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:calc(100%/var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__grip-dots{color:var(--kvw-field-color,#1677ff);flex:0 0 auto;height:13px;width:13px}.kviewer-placed-chrome__grip-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kviewer-placed-chrome__handle{background:#fff;border:1px solid var(--kvw-field-color,#1677ff);border-radius:2px;height:8px;pointer-events:auto;position:absolute;touch-action:none;transform:scale(var(--kvw-handle-zoom,1));width:8px}.kviewer-placed-chrome__handle:before{content:"";inset:-8px;position:absolute}.kviewer-placed-chrome__handle--n{left:50%;top:-4px;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--s{bottom:-4px;left:50%;transform:translateX(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--e{right:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--w{left:-4px;top:50%;transform:translateY(-50%) scale(var(--kvw-handle-zoom,1))}.kviewer-placed-chrome__handle--ne{right:-4px;top:-4px}.kviewer-placed-chrome__handle--nw{left:-4px;top:-4px}.kviewer-placed-chrome__handle--se{bottom:-4px;right:-4px}.kviewer-placed-chrome__handle--sw{bottom:-4px;left:-4px}
 </style>

package/dist/runtime/components/form-fields/PlacedFieldChrome.vue.d.ts

@@ -6,6 +6,10 @@ type __VLS_Props = {
     scale: number;
     /** PDF-space page height (kept for parity; unused here). */
     pageHeight: number;
+    /** 'authoring' = form-edit mode (chrome is the whole interactive
+     *  surface). 'live' = editablePlacedFields outside form-edit mode
+     *  (chrome is transparent except grip and handles). */
+    mode: 'authoring' | 'live';
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     select: () => any;

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

@@ -27,10 +27,22 @@ export interface FormFieldsState {
      *  `addPlacedField` with full control over the field's properties.
      *  Returns the created definition. */
     addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
-    /** Update a form field's rect, name, or flags. */
-    updatePlacedField: (id: string, patch: Partial<FormFieldDefinition>) => void;
-    /** Remove a form field and its value. */
-    removePlacedField: (id: string) => void;
+    /** Update a form field's rect, name, or flags. Notifies the field-event
+     *  sink unless `opts.silent` — pass silent from the public API (the host
+     *  knows about its own calls) and from high-frequency gesture updates
+     *  (commit one non-silent update on gesture end instead). */
+    updatePlacedField: (id: string, patch: Partial<FormFieldDefinition>, opts?: {
+        silent?: boolean;
+    }) => void;
+    /** Remove a form field and its value. Same `silent` contract as
+     *  `updatePlacedField`. */
+    removePlacedField: (id: string, opts?: {
+        silent?: boolean;
+    }) => void;
+    /** Install the sink that receives user-driven field mutations. Viewer.vue
+     *  owns it and fans out to the `field-updated` / `field-removed` emits and
+     *  the embed bridge. Survives document changes (unlike the value sink). */
+    setFieldEventSink: (sink: FieldEventSink | null) => void;
     /** All form-field definitions, flattened across pages. */
     getAllFields: () => FormFieldDefinition[];
     /** All user-placed field definitions (used by export). */
@@ -45,19 +57,6 @@ export interface FormFieldsState {
     selectedPlacedFieldId: Ref<string | null>;
     /** Select or deselect a placed field. Pass null to deselect. */
     selectPlacedField: (id: string | null) => void;
-    /** Opaque role id new placements are auto-tagged with. The host owns
-     *  what roles exist; the editor only carries the active id forward to
-     *  newly placed fields and looks up its color via roleColors. */
-    activeRoleId: Ref<string | null>;
-    /** Set or clear the active role for upcoming placements. */
-    setActiveRole: (id: string | null) => void;
-    /** Map from roleId → CSS color, supplied by the host via the KViewer
-     *  `roleColors` prop. Reading this drives the chrome and placement
-     *  preview color. The editor never mutates role definitions itself. */
-    roleColors: ShallowRef<Record<string, string>>;
-    /** Replace the host-provided color map. Called by KViewer when the
-     *  prop changes. */
-    setRoleColors: (colors: Record<string, string>) => void;
     /** Per-field-type presets merged into every tool placement. Host-owned
      *  via the KViewer `fieldDefaults` prop or the bridge; programmatic
      *  `addFormField` calls are NOT affected (the payload is explicit). */
@@ -110,5 +109,17 @@ export interface FormFieldsState {
 /** Sink signature used by [[setValueWriteSink]]. Receives every user-driven
  *  field value write (the primary id AND each mirrored sibling). */
 export type ValueWriteSink = (fieldId: string, value: string | boolean | string[]) => void;
+/** User-driven field mutation, delivered to the sink installed via
+ *  [[setFieldEventSink]]. `field` is the post-mutation definition for
+ *  updates and the last-known definition for removals. */
+export type FieldEvent = {
+    type: 'updated';
+    field: FormFieldDefinition;
+    patch: Partial<FormFieldDefinition>;
+} | {
+    type: 'removed';
+    field: FormFieldDefinition;
+};
+export type FieldEventSink = (event: FieldEvent) => void;
 export declare function provideFormFields(): FormFieldsState;
 export declare function useFormFields(): FormFieldsState;

package/dist/runtime/composables/useFormFields.js

@@ -12,16 +12,8 @@ export function provideFormFields() {
   const fieldDefinitions = shallowRef(/* @__PURE__ */ new Map());
   const fieldValues = shallowRef(/* @__PURE__ */ new Map());
   const selectedPlacedFieldId = ref(null);
-  const activeRoleId = ref(null);
-  const roleColors = shallowRef({});
   const placedFieldDefaults = shallowRef({});
   const editablePlacedFields = ref(false);
-  function setActiveRole(id) {
-    activeRoleId.value = id;
-  }
-  function setRoleColors(colors) {
-    roleColors.value = colors;
-  }
   function setPlacedFieldDefaults(defaults) {
     placedFieldDefaults.value = defaults;
   }
@@ -43,6 +35,10 @@ export function provideFormFields() {
   function setValueWriteSink(sink) {
     valueWriteSink = sink;
   }
+  let fieldEventSink = null;
+  function setFieldEventSink(sink) {
+    fieldEventSink = sink;
+  }
   let checkboxStyleMap = null;
   let buttonCaptionMap = null;
   let signedSignatureNames = null;
@@ -297,9 +293,7 @@ export function provideFormFields() {
         )
       );
     }
-    if (activeRoleId.value) {
-      def.roleId = activeRoleId.value;
-    }
+    if (def.meta) def.meta = { ...def.meta };
     if (payload.fieldType === "radio") {
       def.buttonValue = nextRadioOptionValue(fieldName);
     }
@@ -340,7 +334,8 @@ export function provideFormFields() {
       required: payload.required ?? false,
       origin: "placed"
     };
-    if (payload.roleId !== void 0) def.roleId = payload.roleId;
+    if (payload.fieldColor !== void 0) def.fieldColor = payload.fieldColor;
+    if (payload.meta !== void 0) def.meta = { ...payload.meta };
     if (payload.defaultValue !== void 0) def.defaultValue = payload.defaultValue;
     if (payload.fontSize !== void 0) def.fontSize = payload.fontSize;
     if (payload.fontName !== void 0) def.fontName = payload.fontName;
@@ -401,7 +396,7 @@ export function provideFormFields() {
     while (used.has(`Option_${n}`)) n += 1;
     return `Option_${n}`;
   }
-  function updatePlacedField(id, patch) {
+  function updatePlacedField(id, patch, opts) {
     let found;
     for (const [page, defs] of fieldDefinitions.value.entries()) {
       const idx = defs.findIndex((d) => d.id === id);
@@ -422,12 +417,16 @@ export function provideFormFields() {
       fv.fieldType = found.fieldType;
       triggerRef(fieldValues);
     }
+    if (!opts?.silent && fieldEventSink) {
+      fieldEventSink({ type: "updated", field: found, patch });
+    }
   }
-  function removePlacedField(id) {
-    let removed = false;
+  function removePlacedField(id, opts) {
+    let removed;
     for (const [page, defs] of fieldDefinitions.value.entries()) {
       const idx = defs.findIndex((d) => d.id === id);
       if (idx === -1) continue;
+      removed = defs[idx];
       const nextDefs = defs.slice();
       nextDefs.splice(idx, 1);
       if (nextDefs.length === 0) {
@@ -435,7 +434,6 @@ export function provideFormFields() {
       } else {
         fieldDefinitions.value.set(page, nextDefs);
       }
-      removed = true;
       break;
     }
     if (!removed) return;
@@ -446,6 +444,9 @@ export function provideFormFields() {
     if (selectedPlacedFieldId.value === id) {
       selectedPlacedFieldId.value = null;
     }
+    if (!opts?.silent && fieldEventSink) {
+      fieldEventSink({ type: "removed", field: removed });
+    }
   }
   function getPlacedFields() {
     const out = [];
@@ -477,14 +478,12 @@ export function provideFormFields() {
         if (d.fieldType !== "signature") continue;
         const fv = fieldValues.value.get(d.id);
         const signed = typeof fv?.value === "string" && fv.value !== "" || d.signedInSource === true;
-        const status = {
+        out.push({
           id: d.id,
           fieldName: d.fieldName,
           pageNumber: d.pageNumber,
           signed
-        };
-        if (d.roleId) status.roleId = d.roleId;
-        out.push(status);
+        });
       }
     }
     return out;
@@ -556,11 +555,8 @@ export function provideFormFields() {
     resetValues,
     reset,
     setValueWriteSink,
+    setFieldEventSink,
     applyFieldValueFromExternal,
-    activeRoleId,
-    setActiveRole,
-    roleColors,
-    setRoleColors,
     placedFieldDefaults,
     setPlacedFieldDefaults,
     editablePlacedFields,

package/dist/runtime/embed/bridge-client.d.ts

@@ -21,7 +21,8 @@ type EventHandler<E extends EventName> = (payload: EventPayloads[E]) => void;
  * an iframe. Wraps `postMessage` into a Promise-based RPC mirroring the
  * viewer's exposed methods, and surfaces iframe-emitted events
  * (`ready`, `formEditMode-changed`, `viewedPages-changed`, `all-pages-read`,
- * `field-placed`, `signedStatus-changed`) via `on()`.
+ * `field-placed`, `field-updated`, `field-removed`, `signedStatus-changed`)
+ * via `on()`.
  */
 export declare class KViewerEmbedClient {
     private readonly iframe;
@@ -68,7 +69,8 @@ export declare class KViewerEmbedClient {
      *  a push-style signal subscribe via `on('signedStatus-changed', …)`. */
     getSignedStatus(): Promise<boolean>;
     /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
-     *  signed, roleId). */
+     *  signed). Correlate to host data by `id` (see the `meta` bag on
+     *  `getFormFields()` for grouping, e.g. by signer). */
     getSignatureFieldStatus(): Promise<SignatureFieldStatus[]>;
     getFormEditMode(): Promise<boolean>;
     setFormEditMode(enabled: boolean): Promise<void>;

package/dist/runtime/embed/bridge-client.js

@@ -104,7 +104,8 @@ export class KViewerEmbedClient {
     return this.call("getSignedStatus");
   }
   /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
-   *  signed, roleId). */
+   *  signed). Correlate to host data by `id` (see the `meta` bag on
+   *  `getFormFields()` for grouping, e.g. by signer). */
   getSignatureFieldStatus() {
     return this.call("getSignatureFieldStatus");
   }

package/dist/runtime/embed/bridge-host.d.ts

@@ -27,6 +27,8 @@ export interface KViewerApi {
     setFieldDefaults: (defaults: PlacedFieldDefaults) => void;
     setClickToSign: (enabled: boolean) => void;
     onFieldPlaced: (cb: (field: FormFieldDefinition) => void) => () => void;
+    onFieldUpdated: (cb: (field: FormFieldDefinition, patch: Partial<FormFieldDefinition>) => void) => () => void;
+    onFieldRemoved: (cb: (field: FormFieldDefinition) => void) => () => void;
     getSignedStatus: () => boolean;
     getSignatureFieldStatus: () => SignatureFieldStatus[];
     onSignedStatusChanged: (cb: (payload: {

package/dist/runtime/embed/bridge-host.js

@@ -202,6 +202,22 @@ export function useKViewerEmbedBridge(viewerRef, options) {
           )
         );
       }
+      if (typeof viewer.onFieldUpdated === "function") {
+        events.push("field-updated");
+        stopViewerStateWatches.push(
+          viewer.onFieldUpdated(
+            (field, patch) => postEvent("field-updated", { field, patch })
+          )
+        );
+      }
+      if (typeof viewer.onFieldRemoved === "function") {
+        events.push("field-removed");
+        stopViewerStateWatches.push(
+          viewer.onFieldRemoved(
+            (field) => postEvent("field-removed", { field })
+          )
+        );
+      }
       if (typeof viewer.onSignedStatusChanged === "function") {
         events.push("signedStatus-changed");
         stopViewerStateWatches.push(

package/dist/runtime/embed/protocol.d.ts

@@ -150,6 +150,18 @@ export interface EventPayloads {
     'field-placed': {
         field: FormFieldDefinition;
     };
+    /** The user changed a field through the viewer UI (moved/resized it or
+     *  edited its properties). Not fired for `updateFormField()` calls.
+     *  Continuous edits may fire repeatedly — treat as an upsert. */
+    'field-updated': {
+        field: FormFieldDefinition;
+        patch: Partial<FormFieldDefinition>;
+    };
+    /** The user removed a field through the viewer UI. Not fired for
+     *  `removeFormField()` calls. `field` is the last-known definition. */
+    'field-removed': {
+        field: FormFieldDefinition;
+    };
     /** A signature field's signed state changed (signed, cleared, added,
      *  removed, or renamed). Push-style counterpart to `getSignedStatus()`. */
     'signedStatus-changed': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kviewer",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Kabema PDF Editor",
   "repository": "kabema/kviewer",
   "license": "MIT",