kviewer 0.3.3 → 0.3.5

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

@@ -4,14 +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 }]"
+    :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" />
@@ -27,8 +32,14 @@
       :selected="props.selected"
       :scale="props.scale"
       :page-height="props.pageTransform.height"
+      :mode="chromeMode ?? 'authoring'"
       @select="emit('select')"
     />
+
+    <PlacedFieldToolbar
+      v-if="showChrome && props.selected && !state.readonly.value"
+      :field="props.field"
+    />
   </div>
 </template>
 
@@ -44,6 +55,7 @@ import FormDropdown from "./FormDropdown.vue";
 import FormSignatureField from "./FormSignatureField.vue";
 import FormButton from "./FormButton.vue";
 import PlacedFieldChrome from "./PlacedFieldChrome.vue";
+import PlacedFieldToolbar from "./PlacedFieldToolbar.vue";
 const props = defineProps({
   field: { type: Object, required: true },
   pageTransform: { type: Object, required: true },
@@ -55,14 +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
 );
-const chromeColor = computed(() => {
-  const id = props.field.roleId;
-  if (!id) return "#1677ff";
-  return formFields.roleColors.value[id] ?? "#1677ff";
+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(() => 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]]);
@@ -77,5 +102,5 @@ const positionStyle = computed(() => {
 </script>
 
 <style>
-.kviewer-form-field__body{height:100%;width:100%}.kviewer-form-field__body--locked{pointer-events:none}.kviewer-form-field--editable{outline:1px dashed color-mix(in srgb,var(--kvw-field-color,#1677ff) 45%,transparent);outline-offset:0}.kviewer-form-field--editable.kviewer-form-field--placed{outline-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 75%,transparent)}.kviewer-form-field--editable.kviewer-form-field--selected{outline:none}
+.kviewer-form-field__body{height:100%;width:100%}.kviewer-form-field__body--locked{pointer-events:none}
 </style>

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,19 +1,32 @@
 <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 }"
-    :style="{ '--kvw-handle-zoom': handleZoom }"
+    :class="{
+  'kviewer-placed-chrome--selected': selected,
+  'kviewer-placed-chrome--live': mode === 'live'
+}"
     @pointerdown.stop="onChromePointerDown"
     @click.stop
   >
     <div
-      v-if="selected"
+      class="kviewer-placed-chrome__outline"
+      :class="{
+  'kviewer-placed-chrome__outline--placed': field.origin === 'placed',
+  'kviewer-placed-chrome__outline--selected': selected
+}"
+    />
+    <div
+      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>
@@ -33,20 +46,15 @@
 </template>
 
 <script setup>
-import { computed, ref } from "vue";
+import { ref } from "vue";
 import { useFormFields } from "../../composables/useFormFields";
-import { useViewerState } from "../../composables/useViewerState";
 const rootEl = ref(null);
-const viewerState = useViewerState();
-const handleZoom = computed(() => {
-  const totalZoom = (props.scale || 1) * (viewerState.visualZoom.value || 1);
-  return Math.max(0.4, 1 / totalZoom).toFixed(3);
-});
 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--selected{outline:1.5px dashed var(--kvw-field-color,#1677ff);outline-offset:0}.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:calc(3px*var(--kvw-handle-zoom, 1));bottom:calc(100% + 3px*var(--kvw-handle-zoom, 1));color:var(--kvw-field-color,#1677ff);cursor:move;display:flex;font-size:calc(9px*var(--kvw-handle-zoom, 1));gap:calc(3px*var(--kvw-handle-zoom, 1));height:calc(16px*var(--kvw-handle-zoom, 1));left:0;line-height:1;overflow:hidden;padding:0 calc(6px*var(--kvw-handle-zoom, 1)) 0 calc(2px*var(--kvw-handle-zoom, 1));pointer-events:auto;position:absolute;right:0;touch-action:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.kviewer-placed-chrome__grip-dots{color:var(--kvw-field-color,#1677ff);flex:0 0 auto;height:calc(10px*var(--kvw-handle-zoom, 1));width:calc(10px*var(--kvw-handle-zoom, 1))}.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:calc(8px*var(--kvw-handle-zoom, 1));pointer-events:auto;position:absolute;touch-action:none;width:calc(8px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle:before{content:"";inset:calc(-8px*var(--kvw-handle-zoom, 1));position:absolute}.kviewer-placed-chrome__handle--n{left:50%;top:calc(-4px*var(--kvw-handle-zoom, 1));transform:translateX(-50%)}.kviewer-placed-chrome__handle--s{bottom:calc(-4px*var(--kvw-handle-zoom, 1));left:50%;transform:translateX(-50%)}.kviewer-placed-chrome__handle--e{right:calc(-4px*var(--kvw-handle-zoom, 1));top:50%;transform:translateY(-50%)}.kviewer-placed-chrome__handle--w{left:calc(-4px*var(--kvw-handle-zoom, 1));top:50%;transform:translateY(-50%)}.kviewer-placed-chrome__handle--ne{right:calc(-4px*var(--kvw-handle-zoom, 1));top:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--nw{left:calc(-4px*var(--kvw-handle-zoom, 1));top:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--se{bottom:calc(-4px*var(--kvw-handle-zoom, 1));right:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--sw{bottom:calc(-4px*var(--kvw-handle-zoom, 1));left:calc(-4px*var(--kvw-handle-zoom, 1))}
+.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/components/form-fields/PlacedFieldToolbar.d.vue.ts

@@ -0,0 +1,7 @@
+import type { FormFieldDefinition } from '../../annotation/engine/types.js';
+type __VLS_Props = {
+    field: FormFieldDefinition;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,51 @@
+<template>
+  <!-- Same pill as AnnotationToolbar, but anchored in the page DOM below
+       the selected field so it follows pan/zoom for free (the Konva
+       selection popover is viewport-fixed because the stage has no DOM
+       anchor to attach to). Stops pointer events so a click here never
+       reaches page-level deselect handlers. -->
+  <div
+    class="kviewer-placed-toolbar"
+    @pointerdown.stop
+    @click.stop
+  >
+    <div class="flex items-center gap-0.5 bg-elevated rounded-lg shadow-lg border border-default p-1">
+      <SelectionToolbarItems :items="customItems" :ctx="selectionCtx" />
+
+      <button
+        class="flex items-center justify-center w-7 h-7 rounded-md hover:bg-default cursor-pointer"
+        :title="t('deleteField')"
+        data-testid="placed-field-delete"
+        @click="onDelete"
+      >
+        <UIcon name="i-lucide-trash-2" class="text-sm text-error" />
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed, inject } from "vue";
+import { useFormFields } from "../../composables/useFormFields";
+import { useKviewerI18n } from "../../composables/useKviewerI18n";
+import { SELECTION_ITEMS_KEY } from "../../selection-items";
+import SelectionToolbarItems from "../SelectionToolbarItems.vue";
+const props = defineProps({
+  field: { type: Object, required: true }
+});
+const formFields = useFormFields();
+const { t } = useKviewerI18n();
+const customItems = inject(SELECTION_ITEMS_KEY, void 0);
+const selectionCtx = computed(() => ({
+  kind: "field",
+  annotations: [],
+  field: props.field
+}));
+function onDelete() {
+  formFields.removePlacedField(props.field.id);
+}
+</script>
+
+<style>
+.kviewer-placed-toolbar{left:50%;pointer-events:auto;position:absolute;top:calc(100% + 8px*var(--kvw-handle-zoom, 1));transform:translateX(-50%) scale(var(--kvw-handle-zoom,1));transform-origin:50% 0;width:-moz-max-content;width:max-content;z-index:1}
+</style>

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

@@ -0,0 +1,7 @@
+import type { FormFieldDefinition } from '../../annotation/engine/types.js';
+type __VLS_Props = {
+    field: FormFieldDefinition;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/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/dist/runtime/public-types.d.ts

@@ -1,6 +1,6 @@
 export type { ExportPdfOptions } from './annotation/pdf-export/export.js';
 export type { ViewerTabItem, AddTabOptions } from './components/ViewerTabs.vue.js';
-export type { AddFormFieldPayload, CheckboxStyle, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, PlacedFieldDefaultProps, PlacedFieldDefaults, SignatureData, SignatureFieldStatus, SignatureHandlers, } from './annotation/engine/types.js';
+export type { AddFormFieldPayload, CheckboxStyle, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, IAnnotationStore, PlacedFieldDefaultProps, PlacedFieldDefaults, SignatureData, SignatureFieldStatus, SignatureHandlers, } from './annotation/engine/types.js';
 export type { ViewMode } from './composables/viewMode.js';
 export type { ViewerState, ActiveTool } from './composables/useViewerState.js';
 export type { KViewerApi, KViewerHostApi, KViewerEmbedBridgeOptions, } from './embed/bridge-host.js';
@@ -10,4 +10,5 @@ export { KViewerEmbedClient } from './embed/bridge-client.js';
 export type { EventName as KViewerEmbedEventName, EventPayloads as KViewerEmbedEventPayloads, MethodName as KViewerEmbedMethodName, } from './embed/protocol.js';
 export { KVIEWER_EMBED_PROTOCOL_VERSION, UNSUPPORTED_METHOD_ERROR_NAME as KVIEWER_EMBED_UNSUPPORTED_METHOD_ERROR_NAME, } from './embed/protocol.js';
 export type { ViewerMenuItem, ViewerMenuButtonItem, ViewerMenuCheckboxItem, ViewerMenuSeparatorItem, } from './menu-items.js';
+export type { ViewerSelectionItem, ViewerSelectionButtonItem, ViewerSelectionSelectItem, ViewerSelectionContext, } from './selection-items.js';
 export type { ViewerToolId, ViewerTopToolId, ViewerBottomToolId, ViewerLayoutToolId, ViewerToolEntry, ViewerToolSlot, } from './toolbar-tools.js';