kviewer 0.2.3 → 0.3.0

package/dist/runtime/components/tools/ToolProperties.vue

@@ -1,110 +1,107 @@
 <template>
-  <div class="flex items-center gap-2 px-2 py-1 rounded-md border border-default bg-default/60 lg:min-w-64">
-    <template v-if="supportsProperties">
-      <!-- ── Desktop: inline color buttons + slider (md and above) ── -->
-      <div class="hidden lg:flex items-center gap-1">
-        <button
-          v-for="color in colors"
-          :key="color"
-          class="w-4 h-4 rounded-full border-2 cursor-pointer transition-transform hover:scale-110"
-          :class="color === currentColor ? 'border-white ring-1 ring-primary' : 'border-transparent'"
-          :style="{ backgroundColor: color }"
-          :title="`Color: ${color}`"
-          @click="setColor(color)"
-        />
-      </div>
-
-      <div
-        v-if="activeType === AnnotationType.FREEHAND"
-        class="hidden lg:flex items-center gap-2 min-w-40"
-      >
-        <UIcon name="i-lucide-minus" class="text-[10px] text-muted" />
-        <USlider
-          :model-value="freehandStrokeWidth"
-          :min="1"
-          :max="24"
-          :step="1"
-          size="sm"
-          class="w-28"
-          @update:model-value="setFreehandSize"
-        />
-        <UIcon name="i-lucide-plus" class="text-[10px] text-muted" />
-        <span class="w-9 text-[11px] text-muted text-right tabular-nums">
-          {{ freehandStrokeWidth }}px
-        </span>
-      </div>
+  <!-- Rendered only while a tool with editable style is active — an empty
+       "no properties" pill would just be toolbar noise the rest of the
+       time. The second row is a grid, so the center column stays put. -->
+  <div
+    v-if="supportsProperties"
+    class="flex items-center gap-2 px-2 py-1 rounded-md border border-default bg-default/60 lg:min-w-64"
+  >
+    <!-- ── Desktop: inline color buttons + slider (md and above) ── -->
+    <div class="hidden lg:flex items-center gap-1">
+      <button
+        v-for="color in colors"
+        :key="color"
+        class="w-4 h-4 rounded-full border-2 cursor-pointer transition-transform hover:scale-110"
+        :class="color === currentColor ? 'border-white ring-1 ring-primary' : 'border-transparent'"
+        :style="{ backgroundColor: color }"
+        :title="`Color: ${color}`"
+        @click="setColor(color)"
+      />
+    </div>
 
-      <!-- ── Mobile: two popover buttons (below md) ── -->
-      <div class="flex lg:hidden items-center gap-1">
-        <!-- Color popover -->
-        <UPopover v-model:open="colorPopoverOpen">
-          <button
-            class="flex items-center justify-center w-7 h-7 rounded-md hover:bg-default cursor-pointer"
-            :title="t('color')"
-          >
-            <span
-              class="w-4 h-4 rounded-full border border-white/30"
-              :style="{ backgroundColor: currentColor ?? colors[0] }"
-            />
-          </button>
-          <template #content>
-            <div class="p-3">
-              <div class="grid grid-cols-4 gap-1.5">
-                <button
-                  v-for="color in colors"
-                  :key="color"
-                  class="w-7 h-7 rounded-full border-2 cursor-pointer transition-transform hover:scale-110"
-                  :class="color === currentColor ? 'border-white ring-2 ring-primary' : 'border-transparent'"
-                  :style="{ backgroundColor: color }"
-                  @click="setColorAndClose(color)"
-                />
-              </div>
-            </div>
-          </template>
-        </UPopover>
+    <div
+      v-if="activeType === AnnotationType.FREEHAND"
+      class="hidden lg:flex items-center gap-2 min-w-40"
+    >
+      <UIcon name="i-lucide-minus" class="text-[10px] text-muted" />
+      <USlider
+        :model-value="freehandStrokeWidth"
+        :min="1"
+        :max="24"
+        :step="1"
+        size="sm"
+        class="w-28"
+        @update:model-value="setFreehandSize"
+      />
+      <UIcon name="i-lucide-plus" class="text-[10px] text-muted" />
+      <span class="w-9 text-[11px] text-muted text-right tabular-nums">
+        {{ freehandStrokeWidth }}px
+      </span>
+    </div>
 
-        <!-- Stroke width popover (freehand only) -->
-        <UPopover v-if="activeType === AnnotationType.FREEHAND">
-          <button
-            class="flex items-center justify-center h-7 px-1.5 gap-0.5 rounded-md hover:bg-default cursor-pointer"
-            :title="t('strokeWidth')"
-          >
-            <UIcon name="i-lucide-pencil" class="text-sm text-muted" />
-            <span class="text-[10px] text-muted tabular-nums">{{ freehandStrokeWidth }}</span>
-          </button>
-          <template #content>
-            <div class="p-3 flex items-center gap-3">
-              <button
-                class="flex items-center justify-center w-8 h-8 rounded-md hover:bg-default cursor-pointer disabled:opacity-40 disabled:cursor-not-allowed"
-                :disabled="freehandStrokeWidth <= 1"
-                :title="t('decreaseStrokeWidth')"
-                @click="decrementStrokeWidth"
-              >
-                <UIcon name="i-lucide-minus" class="text-sm" />
-              </button>
-              <span class="w-9 text-center text-sm tabular-nums">
-                {{ freehandStrokeWidth }}px
-              </span>
+    <!-- ── Mobile: two popover buttons (below md) ── -->
+    <div class="flex lg:hidden items-center gap-1">
+      <!-- Color popover -->
+      <UPopover v-model:open="colorPopoverOpen">
+        <button
+          class="flex items-center justify-center w-7 h-7 rounded-md hover:bg-default cursor-pointer"
+          :title="t('color')"
+        >
+          <span
+            class="w-4 h-4 rounded-full border border-white/30"
+            :style="{ backgroundColor: currentColor ?? colors[0] }"
+          />
+        </button>
+        <template #content>
+          <div class="p-3">
+            <div class="grid grid-cols-4 gap-1.5">
               <button
-                class="flex items-center justify-center w-8 h-8 rounded-md hover:bg-default cursor-pointer disabled:opacity-40 disabled:cursor-not-allowed"
-                :disabled="freehandStrokeWidth >= 24"
-                :title="t('increaseStrokeWidth')"
-                @click="incrementStrokeWidth"
-              >
-                <UIcon name="i-lucide-plus" class="text-sm" />
-              </button>
+                v-for="color in colors"
+                :key="color"
+                class="w-7 h-7 rounded-full border-2 cursor-pointer transition-transform hover:scale-110"
+                :class="color === currentColor ? 'border-white ring-2 ring-primary' : 'border-transparent'"
+                :style="{ backgroundColor: color }"
+                @click="setColorAndClose(color)"
+              />
             </div>
-          </template>
-        </UPopover>
-      </div>
-    </template>
+          </div>
+        </template>
+      </UPopover>
 
-    <template v-else>
-      <div class="flex items-center gap-1.5 text-xs text-muted">
-        <UIcon name="i-lucide-sliders-horizontal" class="text-sm" />
-        <span>{{ t("noProperties") }}</span>
-      </div>
-    </template>
+      <!-- Stroke width popover (freehand only) -->
+      <UPopover v-if="activeType === AnnotationType.FREEHAND">
+        <button
+          class="flex items-center justify-center h-7 px-1.5 gap-0.5 rounded-md hover:bg-default cursor-pointer"
+          :title="t('strokeWidth')"
+        >
+          <UIcon name="i-lucide-pencil" class="text-sm text-muted" />
+          <span class="text-[10px] text-muted tabular-nums">{{ freehandStrokeWidth }}</span>
+        </button>
+        <template #content>
+          <div class="p-3 flex items-center gap-3">
+            <button
+              class="flex items-center justify-center w-8 h-8 rounded-md hover:bg-default cursor-pointer disabled:opacity-40 disabled:cursor-not-allowed"
+              :disabled="freehandStrokeWidth <= 1"
+              :title="t('decreaseStrokeWidth')"
+              @click="decrementStrokeWidth"
+            >
+              <UIcon name="i-lucide-minus" class="text-sm" />
+            </button>
+            <span class="w-9 text-center text-sm tabular-nums">
+              {{ freehandStrokeWidth }}px
+            </span>
+            <button
+              class="flex items-center justify-center w-8 h-8 rounded-md hover:bg-default cursor-pointer disabled:opacity-40 disabled:cursor-not-allowed"
+              :disabled="freehandStrokeWidth >= 24"
+              :title="t('increaseStrokeWidth')"
+              @click="incrementStrokeWidth"
+            >
+              <UIcon name="i-lucide-plus" class="text-sm" />
+            </button>
+          </div>
+        </template>
+      </UPopover>
+    </div>
   </div>
 </template>
 

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

@@ -1,5 +1,5 @@
 import { type Ref, type ShallowRef } from 'vue';
-import type { AddFormFieldPayload, CheckboxStyle, DetectedShape, FormFieldDefinition, FormFieldValue, PlaceFieldPayload } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, CheckboxStyle, DetectedShape, FormFieldDefinition, FormFieldValue, PlaceFieldPayload, PlacedFieldDefaults, SignatureFieldStatus } from '../annotation/engine/types.js';
 export interface FormFieldsState {
     /** Field definitions grouped by page number */
     fieldDefinitions: ShallowRef<Map<number, FormFieldDefinition[]>>;
@@ -35,6 +35,10 @@ export interface FormFieldsState {
     getAllFields: () => FormFieldDefinition[];
     /** All user-placed field definitions (used by export). */
     getPlacedFields: () => FormFieldDefinition[];
+    /** Signed-state snapshot of every signature widget (any origin).
+     *  Reads the reactive defs/values, so computeds over it re-run on
+     *  every signing or field change. */
+    getSignatureFieldStatus: () => SignatureFieldStatus[];
     /** Look up a field definition by id (any origin). */
     getFieldById: (id: string) => FormFieldDefinition | undefined;
     /** Id of the currently selected placed field (null if none). */
@@ -54,6 +58,18 @@ export interface FormFieldsState {
     /** 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). */
+    placedFieldDefaults: ShallowRef<PlacedFieldDefaults>;
+    /** Replace the placement presets. */
+    setPlacedFieldDefaults: (defaults: PlacedFieldDefaults) => void;
+    /** When true, user-placed fields show selection chrome and can be
+     *  moved/resized/deleted in hand mode even outside form-edit mode.
+     *  Parsed/detected fields are unaffected. */
+    editablePlacedFields: Ref<boolean>;
+    /** Enable or disable placed-field editing outside form-edit mode. */
+    setEditablePlacedFields: (enabled: boolean) => void;
     /** Apply checkbox-style hints (extracted from `/MK /CA` in the source PDF)
      *  to existing parsed checkbox defs and store the map for any defs
      *  parsed afterwards. Keyed by checkbox fieldName. */

package/dist/runtime/composables/useFormFields.js

@@ -14,12 +14,20 @@ export function provideFormFields() {
   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;
+  }
+  function setEditablePlacedFields(enabled) {
+    editablePlacedFields.value = enabled;
+  }
   function selectPlacedField(id) {
     selectedPlacedFieldId.value = id;
   }
@@ -261,10 +269,6 @@ export function provideFormFields() {
     while (existing.has(`${base}_${n}`)) n += 1;
     return `${base}_${n}`;
   }
-  function placedDefaultValue(fieldType) {
-    if (fieldType === "checkbox") return false;
-    return "";
-  }
   function addPlacedField(payload) {
     const id = `placed-${generateUUID()}`;
     let fieldName;
@@ -284,6 +288,15 @@ export function provideFormFields() {
       required: false,
       origin: "placed"
     };
+    const defaults = placedFieldDefaults.value[payload.fieldType];
+    if (defaults) {
+      Object.assign(
+        def,
+        Object.fromEntries(
+          Object.entries(defaults).filter(([, value]) => value !== void 0)
+        )
+      );
+    }
     if (activeRoleId.value) {
       def.roleId = activeRoleId.value;
     }
@@ -291,11 +304,11 @@ export function provideFormFields() {
       def.buttonValue = nextRadioOptionValue(fieldName);
     }
     if (payload.fieldType === "checkbox") {
-      def.checkboxStyle = "check";
+      def.checkboxStyle ??= "check";
     }
     if (payload.fieldType === "dropdown") {
-      def.combo = true;
-      def.options = [{ exportValue: "Option 1", displayValue: "Option 1" }];
+      def.combo ??= true;
+      def.options ??= [{ exportValue: "Option 1", displayValue: "Option 1" }];
     }
     const existingDefs = fieldDefinitions.value.get(payload.pageNumber) ?? [];
     fieldDefinitions.value.set(payload.pageNumber, [...existingDefs, def]);
@@ -304,7 +317,9 @@ export function provideFormFields() {
       fieldId: id,
       fieldName: def.fieldName,
       fieldType: def.fieldType,
-      value: placedDefaultValue(def.fieldType)
+      // Honors a `defaultValue` preset from placedFieldDefaults, matching
+      // how addFormField initializes values.
+      value: getDefaultValue(def)
     });
     triggerRef(fieldValues);
     if (payload.fieldType === "radio") {
@@ -455,6 +470,25 @@ export function provideFormFields() {
     }
     return false;
   }
+  function getSignatureFieldStatus() {
+    const out = [];
+    for (const defs of fieldDefinitions.value.values()) {
+      for (const d of defs) {
+        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 = {
+          id: d.id,
+          fieldName: d.fieldName,
+          pageNumber: d.pageNumber,
+          signed
+        };
+        if (d.roleId) status.roleId = d.roleId;
+        out.push(status);
+      }
+    }
+    return out;
+  }
   function isFieldLocked(fieldId) {
     const target = getFieldById(fieldId);
     if (!target) return false;
@@ -511,6 +545,7 @@ export function provideFormFields() {
     removePlacedField,
     getAllFields,
     getPlacedFields,
+    getSignatureFieldStatus,
     getFieldById,
     selectedPlacedFieldId,
     selectPlacedField,
@@ -525,7 +560,11 @@ export function provideFormFields() {
     activeRoleId,
     setActiveRole,
     roleColors,
-    setRoleColors
+    setRoleColors,
+    placedFieldDefaults,
+    setPlacedFieldDefaults,
+    editablePlacedFields,
+    setEditablePlacedFields
   };
   provide(FORM_FIELDS_KEY, state);
   return state;

package/dist/runtime/composables/useViewerSearch.js

@@ -156,7 +156,7 @@ export function provideViewerSearch() {
       const end = match.end;
       const isSelected = isSelectedPage && i === selectedMatchIndex;
       const highlightSuffix = isSelected ? " selected" : "";
-      let selectedSpan = null;
+      let selectedSpan;
       if (!prevEnd || begin.divIdx !== prevEnd.divIdx) {
         if (prevEnd) {
           appendTextToDiv(binding, prevEnd.divIdx, prevEnd.offset, void 0);

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

@@ -60,6 +60,7 @@ export interface ViewerState {
     visualZoom: Ref<number>;
     formEditMode: Ref<boolean>;
     setFormEditMode: (enabled: boolean) => void;
+    clickToSign: Ref<boolean>;
 }
 export interface ViewerStateProvider {
     state: ViewerState;

package/dist/runtime/composables/useViewerState.js

@@ -73,6 +73,7 @@ export function provideViewerState() {
   const visualZoom = ref(1);
   const stylusMode = ref(false);
   const formEditMode = ref(false);
+  const clickToSign = ref(false);
   function isFormFieldTool(t) {
     return typeof t === "number" && (t === AnnotationType.FORM_TEXT || t === AnnotationType.FORM_CHECKBOX || t === AnnotationType.FORM_RADIO || t === AnnotationType.FORM_SIGNATURE);
   }
@@ -96,28 +97,25 @@ export function provideViewerState() {
   const activeStamp = ref(null);
   const signatures = ref([]);
   const activeSignature = ref(null);
-  let _signatureHandlers = null;
+  const _signatureHandlers = shallowRef(null);
   async function loadSignatures() {
-    if (!_signatureHandlers) return;
-    signatures.value = await _signatureHandlers.onLoad();
+    if (!_signatureHandlers.value) return;
+    signatures.value = await _signatureHandlers.value.onLoad();
   }
   async function saveSignature(imageUrl) {
-    if (!_signatureHandlers) return null;
-    const sig = await _signatureHandlers.onSave(imageUrl);
+    if (!_signatureHandlers.value) return null;
+    const sig = await _signatureHandlers.value.onSave(imageUrl);
     signatures.value = [...signatures.value, sig];
     return sig;
   }
   async function deleteSignature(id) {
-    if (!_signatureHandlers) return;
-    await _signatureHandlers.onDelete(id);
+    if (!_signatureHandlers.value) return;
+    await _signatureHandlers.value.onDelete(id);
     signatures.value = signatures.value.filter((s) => s.id !== id);
     if (activeSignature.value?.id === id) activeSignature.value = null;
   }
   function selectTool(tool, dataTransfer) {
     if (readonly.value && tool !== "hand") return;
-    if (isFormFieldTool(tool) && !formEditMode.value) {
-      formEditMode.value = true;
-    }
     activeTool.value = tool;
     selectedAnnotation.value = null;
     selectedAnnotations.value = [];
@@ -187,10 +185,10 @@ export function provideViewerState() {
     signatures,
     activeSignature,
     get signatureHandlers() {
-      return _signatureHandlers;
+      return _signatureHandlers.value;
     },
     set signatureHandlers(v) {
-      _signatureHandlers = v;
+      _signatureHandlers.value = v;
     },
     loadSignatures,
     saveSignature,
@@ -207,7 +205,8 @@ export function provideViewerState() {
     shapeDetection: shapeDetectionEnabled,
     visualZoom,
     formEditMode,
-    setFormEditMode
+    setFormEditMode,
+    clickToSign
   };
   provide(VIEWER_STATE_KEY, state);
   return {

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

@@ -1,5 +1,5 @@
 import type { ExportPdfOptions } from '../annotation/pdf-export/export.js';
-import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus } from '../annotation/engine/types.js';
 import { type EventName, type EventPayloads, type ImportAnnotationsMode } from './protocol.js';
 export interface KViewerEmbedClientOptions {
     /**
@@ -20,8 +20,8 @@ type EventHandler<E extends EventName> = (payload: EventPayloads[E]) => void;
  * Parent-page client that drives a `<KViewer>` instance running inside
  * 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`)
- * via `on()`.
+ * (`ready`, `formEditMode-changed`, `viewedPages-changed`, `all-pages-read`,
+ * `field-placed`, `signedStatus-changed`) via `on()`.
  */
 export declare class KViewerEmbedClient {
     private readonly iframe;
@@ -50,6 +50,22 @@ export declare class KViewerEmbedClient {
     updateFormField(id: string, patch: Partial<FormFieldDefinition>): Promise<void>;
     removeFormField(id: string): Promise<void>;
     getFormFields(): Promise<FormFieldDefinition[]>;
+    /** Replace the per-field-type presets applied when the user places a
+     *  field via the placement tools. Subscribe to `on('field-placed', …)`
+     *  for per-field follow-ups (e.g. renaming). */
+    setFieldDefaults(defaults: PlacedFieldDefaults): Promise<void>;
+    /** Enable/disable kviewer's built-in click-to-sign flow on signature
+     *  fields. Off by default — fields render as passive markers so the
+     *  host's own signing process stays the only entry point. */
+    setClickToSign(enabled: boolean): Promise<void>;
+    /** True once every signature field is signed (in-session value or a
+     *  digital signature already in the source PDF). Vacuously true with
+     *  zero signature fields. Use to gate e.g. envelope finalization; for
+     *  a push-style signal subscribe via `on('signedStatus-changed', …)`. */
+    getSignedStatus(): Promise<boolean>;
+    /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
+     *  signed, roleId). */
+    getSignatureFieldStatus(): Promise<SignatureFieldStatus[]>;
     getFormEditMode(): Promise<boolean>;
     setFormEditMode(enabled: boolean): Promise<void>;
     toggleFormEditMode(): Promise<boolean>;

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

@@ -78,6 +78,30 @@ export class KViewerEmbedClient {
   getFormFields() {
     return this.call("getFormFields");
   }
+  /** Replace the per-field-type presets applied when the user places a
+   *  field via the placement tools. Subscribe to `on('field-placed', …)`
+   *  for per-field follow-ups (e.g. renaming). */
+  setFieldDefaults(defaults) {
+    return this.call("setFieldDefaults", defaults);
+  }
+  /** Enable/disable kviewer's built-in click-to-sign flow on signature
+   *  fields. Off by default — fields render as passive markers so the
+   *  host's own signing process stays the only entry point. */
+  setClickToSign(enabled) {
+    return this.call("setClickToSign", enabled);
+  }
+  /** True once every signature field is signed (in-session value or a
+   *  digital signature already in the source PDF). Vacuously true with
+   *  zero signature fields. Use to gate e.g. envelope finalization; for
+   *  a push-style signal subscribe via `on('signedStatus-changed', …)`. */
+  getSignedStatus() {
+    return this.call("getSignedStatus");
+  }
+  /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
+   *  signed, roleId). */
+  getSignatureFieldStatus() {
+    return this.call("getSignatureFieldStatus");
+  }
   getFormEditMode() {
     return this.call("getFormEditMode");
   }

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

@@ -1,6 +1,6 @@
 import { type Ref } from 'vue';
 import type { ExportPdfOptions } from '../annotation/pdf-export/export.js';
-import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus } from '../annotation/engine/types.js';
 import { type MethodName } from './protocol.js';
 /**
  * Surface the bridge calls on the KViewer template ref. Mirrors the
@@ -23,6 +23,15 @@ export interface KViewerApi {
     updateFormField: (id: string, patch: Partial<FormFieldDefinition>) => void;
     removeFormField: (id: string) => void;
     getFormFields: () => FormFieldDefinition[];
+    setFieldDefaults: (defaults: PlacedFieldDefaults) => void;
+    setClickToSign: (enabled: boolean) => void;
+    onFieldPlaced: (cb: (field: FormFieldDefinition) => void) => () => void;
+    getSignedStatus: () => boolean;
+    getSignatureFieldStatus: () => SignatureFieldStatus[];
+    onSignedStatusChanged: (cb: (payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => void) => () => void;
     formEditMode: Ref<boolean>;
     setFormEditMode: (enabled: boolean) => void;
     toggleFormEditMode: () => boolean;

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

@@ -66,6 +66,20 @@ export function useKViewerEmbedBridge(viewerRef, options) {
       }
       case "getFormFields":
         return viewer.getFormFields();
+      case "setFieldDefaults": {
+        const [defaults] = req.args;
+        viewer.setFieldDefaults(defaults);
+        return void 0;
+      }
+      case "setClickToSign": {
+        const [enabled] = req.args;
+        viewer.setClickToSign(enabled);
+        return void 0;
+      }
+      case "getSignedStatus":
+        return viewer.getSignedStatus();
+      case "getSignatureFieldStatus":
+        return viewer.getSignatureFieldStatus();
       case "getFormEditMode":
         return viewer.formEditMode.value;
       case "setFormEditMode": {
@@ -130,6 +144,12 @@ export function useKViewerEmbedBridge(viewerRef, options) {
           viewer.formEditMode,
           (enabled) => postEvent("formEditMode-changed", { enabled })
         ),
+        viewer.onFieldPlaced(
+          (field) => postEvent("field-placed", { field })
+        ),
+        viewer.onSignedStatusChanged(
+          (payload) => postEvent("signedStatus-changed", payload)
+        ),
         // Read-tracking. The getters touch the viewer's reactive viewed-pages
         // state, so watch re-runs them whenever a page is viewed or tracking
         // is reset.

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

@@ -1,5 +1,5 @@
 import type { ExportPdfOptions } from '../annotation/pdf-export/export.js';
-import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus } from '../annotation/engine/types.js';
 export declare const KVIEWER_EMBED_PROTOCOL_VERSION = 1;
 export declare const REQUEST_KIND: "kviewer:request";
 export declare const RESPONSE_KIND: "kviewer:response";
@@ -47,6 +47,22 @@ export interface MethodSignatures {
         args: [];
         result: FormFieldDefinition[];
     };
+    setFieldDefaults: {
+        args: [defaults: PlacedFieldDefaults];
+        result: undefined;
+    };
+    setClickToSign: {
+        args: [enabled: boolean];
+        result: undefined;
+    };
+    getSignedStatus: {
+        args: [];
+        result: boolean;
+    };
+    getSignatureFieldStatus: {
+        args: [];
+        result: SignatureFieldStatus[];
+    };
     getFormEditMode: {
         args: [];
         result: boolean;
@@ -112,6 +128,17 @@ export interface EventPayloads {
     /** Fires once when the final unseen page is viewed. Re-arms after
      *  `resetViewedPages()` or a new document. */
     'all-pages-read': Record<string, never>;
+    /** The user placed a form field via a placement tool. Patch it with
+     *  `updateFormField()` to set host-driven properties. */
+    'field-placed': {
+        field: FormFieldDefinition;
+    };
+    /** A signature field's signed state changed (signed, cleared, added,
+     *  removed, or renamed). Push-style counterpart to `getSignedStatus()`. */
+    'signedStatus-changed': {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    };
 }
 export type EventName = keyof EventPayloads;
 export interface EventMessage<E extends EventName = EventName> {