kviewer 0.2.4 → 0.3.1

package/dist/runtime/annotation/utils/signature_image.js

@@ -0,0 +1,20 @@
+export const WHITE_CUTOFF = 240;
+export const WHITE_SOFT_EDGE = 180;
+export function knockOutWhite(data, cutoff = WHITE_CUTOFF, softEdge = WHITE_SOFT_EDGE) {
+  for (let i = 0; i < data.length; i += 4) {
+    const luminance = 0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2];
+    if (luminance >= cutoff) {
+      data[i + 3] = 0;
+    } else if (luminance > softEdge) {
+      const ratio = (cutoff - luminance) / (cutoff - softEdge);
+      data[i + 3] = Math.round(data[i + 3] * ratio);
+    }
+  }
+}
+export function fitWithin(width, height, maxWidth, maxHeight) {
+  const scale = Math.min(maxWidth / width, maxHeight / height, 1);
+  return {
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale))
+  };
+}

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-text-layer{left:0;line-height:1;overflow:hidden;position:absolute;top:0;-webkit-user-select:none;-moz-user-select:none;user-select:none;z-index:1}.kviewer-text-layer--interactive{cursor:text;-webkit-user-select:text;-moz-user-select:text;user-select:text}.KViewer_is_painting.KViewer_painting_type_12 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_12 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_13 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_13 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_5 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_5 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_6 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_6 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_7 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_7 .kviewer-annotation-layer *,.KViewer_is_painting.KViewer_painting_type_8 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_8 .kviewer-annotation-layer *{cursor:crosshair!important}.KViewer_is_painting.KViewer_painting_type_4 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_4 .kviewer-annotation-layer *{cursor:text!important}.KViewer_is_painting.KViewer_painting_type_11 .kviewer-annotation-layer,.KViewer_is_painting.KViewer_painting_type_11 .kviewer-annotation-layer *{cursor:crosshair!important}.KViewer_selector_hover{cursor:pointer!important}.kviewer-form-layer{left:0;overflow:hidden;position:absolute;top:0}.kviewer-form-field{box-sizing:border-box;position:absolute}.kviewer-form-input{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 14%,transparent);border:1px solid transparent;box-sizing:border-box;color:#000;display:block;font-family:-apple-system,BlinkMacSystemFont,Helvetica Neue,Helvetica,Arial,sans-serif;font-weight:500;height:100%;line-height:normal;margin:0;outline:none;padding:1px 2px;resize:none;width:100%;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;text-rendering:optimizeLegibility;vertical-align:top}.kviewer-form-input:hover{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 22%,transparent);border-color:rgba(0,0,0,.2)}.kviewer-form-input:focus{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 28%,transparent);border-color:var(--kvw-field-color,var(--color-primary,#3b82f6));outline:2px solid var(--kvw-field-color,var(--color-primary,#3b82f6))}.kviewer-form-uselect{align-items:center;background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 14%,transparent);border:1px solid transparent;border-radius:0;box-sizing:border-box;color:#000;cursor:pointer;display:flex;height:100%;line-height:1;padding:0 11px 0 2px;width:100%}.kviewer-form-uselect:hover{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 22%,transparent);border-color:rgba(0,0,0,.2)}.kviewer-form-uselect:focus-visible{background-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 28%,transparent);outline:2px solid var(--kvw-field-color,var(--color-primary,#3b82f6));outline-offset:-2px}.kviewer-form-uselect:disabled{cursor:default}.kviewer-form-listbox{overflow-y:auto;padding:0}.kviewer-form-listbox option{padding:1px 3px}.kviewer-form-editable-combo{height:100%;position:relative;width:100%}.kviewer-form-editable-combo input{height:100%;width:100%}.kviewer-form-checkbox,.kviewer-form-radio{align-items:center;background:#fff;box-sizing:border-box;cursor:pointer;display:flex;height:100%;justify-content:center;width:100%}.kviewer-form-checkbox input,.kviewer-form-radio input{accent-color:var(--kvw-field-color,var(--color-primary,#3b82f6));cursor:pointer;height:80%;margin:0;max-height:18px;max-width:18px;width:80%}.kviewer-form-checkbox--detected{background:transparent}.kviewer-form-checkbox--circle{border-radius:50%}.kviewer-form-checkbox__icon{color:#1a1a1a;height:65%;width:65%}.kviewer-form-checkbox--circle .kviewer-form-checkbox__icon{height:50%;width:50%}.kviewer-form-radio input{accent-color:var(--kvw-field-color,var(--color-primary,#3b82f6));cursor:pointer;height:80%;margin:0;max-height:18px;max-width:18px;width:80%}.kviewer-form-button{align-items:center;background:#c8c8c8;border:1px solid rgba(0,0,0,.35);box-sizing:border-box;color:#000;cursor:pointer;display:flex;font-family:inherit;font-weight:700;height:100%;justify-content:center;line-height:1;padding:0 6px;text-align:center;width:100%;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.kviewer-form-button:hover{background:#bdbdbd}.kviewer-form-button:active{background:#b0b0b0}.kviewer-form-signature{align-items:center;background:rgba(255,255,200,.15);border:1px dashed rgba(0,0,0,.2);cursor:pointer;display:flex;height:100%;justify-content:center;width:100%}.kviewer-form-signature:hover{background:color-mix(in srgb,var(--kvw-field-color,#3b82f6) 8%,transparent);border-color:var(--kvw-field-color,var(--color-primary,#3b82f6))}.kviewer-form-signature--filled{background:transparent;border-color:transparent;border-style:solid}.kviewer-form-signature__preview{max-height:100%;max-width:100%;-o-object-fit:contain;object-fit:contain}.kviewer-form-signature__placeholder{color:rgba(0,0,0,.4);font-size:10px;pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.kviewer-form-signature--static{cursor:default}.kviewer-form-signature--static:hover{background:rgba(255,255,200,.15);border-color:rgba(0,0,0,.2)}.kviewer-form-signature__marker{align-items:center;display:inline-flex;gap:4px}.kviewer-form-signature__marker-icon{flex:0 0 auto;height:12px;width:12px}

package/dist/runtime/components/FormFieldLayer.vue

@@ -48,7 +48,12 @@ const state = useViewerState();
 const fields = computed(() => formFields.getFieldsForPage(props.pageNumber));
 const selectedFieldId = formFields.selectedPlacedFieldId;
 watch(() => state.formEditMode.value, (enabled) => {
-  if (!enabled) formFields.selectPlacedField(null);
+  if (enabled) return;
+  const id = formFields.selectedPlacedFieldId.value;
+  if (!id) return;
+  const def = formFields.getFieldById(id);
+  const keepsChrome = formFields.editablePlacedFields.value && def?.origin === "placed";
+  if (!keepsChrome) formFields.selectPlacedField(null);
 });
 watch(() => state.activeTool.value, (tool) => {
   const isFormFieldTool = typeof tool === "number" && (tool === AnnotationType.FORM_TEXT || tool === AnnotationType.FORM_CHECKBOX || tool === AnnotationType.FORM_RADIO || tool === AnnotationType.FORM_SIGNATURE);

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

@@ -1,5 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
-import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
 import type { ViewerToolEntry } from '../toolbar-tools.js';
@@ -35,6 +35,21 @@ type __VLS_Props = {
      *  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
+     *  a competing canvas — fields then render as passive markers. */
+    clickToSign?: boolean;
+    /** When true, user-placed form fields show selection chrome and can be
+     *  moved/resized/deleted in hand mode even outside form-edit mode.
+     *  Fields parsed from the source PDF are unaffected. */
+    editablePlacedFields?: boolean;
+    /** Per-field-type presets merged into every field the user places via
+     *  the placement tools (e.g. a signature `promptText` or `lockAction`).
+     *  `fieldName` stays auto-generated — rename via the `field-placed`
+     *  event and `updateFormField()`. Programmatic `addFormField()` calls
+     *  are not affected. */
+    fieldDefaults?: PlacedFieldDefaults;
     /** Execute embedded JavaScript inside the PDF — field-level AA scripts
      *  (Mouse Up, Calculate, Format, Validate, Keystroke), document-level
      *  open actions, and page-level scripts. Powered by pdf.js's QuickJS
@@ -98,6 +113,32 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     removeFormField: (id: string) => void;
     /** All form-field definitions (parsed, detected, and placed), flat. */
     getFormFields: () => FormFieldDefinition[];
+    /** Replace the per-field-type presets applied to tool placements.
+     *  Programmatic counterpart to the `fieldDefaults` prop. */
+    setFieldDefaults: (defaults: PlacedFieldDefaults) => void;
+    /** Enable/disable kviewer's built-in click-to-sign flow at runtime.
+     *  Programmatic counterpart to the `clickToSign` prop. */
+    setClickToSign: (enabled: boolean) => void;
+    /** Subscribe to tool placements (imperative mirror of the
+     *  `field-placed` event, used by the embed bridge). Returns an
+     *  unsubscribe function. */
+    onFieldPlaced: (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
+     *  fields, so combine with `getSignatureFieldStatus().length` if you
+     *  need "at least one". Use to gate e.g. envelope finalization. */
+    getSignedStatus: () => boolean;
+    /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
+     *  signed, roleId). */
+    getSignatureFieldStatus: () => SignatureFieldStatus[];
+    /** Subscribe to signed-status changes (imperative mirror of the
+     *  `signed-status-changed` event, used by the embed bridge). Returns
+     *  an unsubscribe function. */
+    onSignedStatusChanged: (cb: (payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => void) => (() => void);
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */
@@ -114,20 +155,32 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     resetViewedPages: () => void;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "all-pages-read": () => any;
+    "field-placed": (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;
+        fields: SignatureFieldStatus[];
+    }) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onAll-pages-read"?: (() => any) | undefined;
+    "onField-placed"?: ((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;
+        fields: SignatureFieldStatus[];
+    }) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;
     zoom: number;
+    clickToSign: boolean;
     readonly: boolean;
     active: boolean;
+    locale: KviewerLocale;
     menuItems: ViewerMenuItem[];
     tools: ViewerToolEntry[];
     scripting: boolean;
@@ -138,7 +191,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     formEditMode: boolean;
     roleColors: Record<string, string>;
     activeRoleId: string | null;
-    locale: KviewerLocale;
+    editablePlacedFields: boolean;
+    fieldDefaults: PlacedFieldDefaults;
     messages: KviewerMessageOverrides;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/runtime/components/Viewer.vue

@@ -242,6 +242,9 @@ const props = defineProps({
   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 },
   scripting: { type: Boolean, required: false, default: false },
   menuItems: { type: Array, required: false, default: void 0 },
   tools: { type: Array, required: false, default: void 0 },
@@ -252,7 +255,9 @@ 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"]);
+const emit = defineEmits(["update:formEditMode", "update:activeRoleId", "update:viewedPages", "all-pages-read", "field-placed", "signed-status-changed"]);
+const fieldPlacedCallbacks = /* @__PURE__ */ new Set();
+const signedStatusCallbacks = /* @__PURE__ */ new Set();
 const viewerRoot = ref(null);
 const scrollContainer = ref(null);
 const { state: viewerState, setScrollToPageFn, setDownloadPdfFn, setApplyScaleFn } = provideViewerState();
@@ -262,6 +267,9 @@ watchEffect(() => {
 watchEffect(() => {
   viewerState.shapeDetection.value = props.shapeDetection ?? false;
 });
+watchEffect(() => {
+  viewerState.clickToSign.value = props.clickToSign ?? false;
+});
 watch(
   () => props.formEditMode,
   (v) => {
@@ -293,6 +301,28 @@ watch(
   },
   { immediate: true }
 );
+watch(
+  () => props.fieldDefaults,
+  (v) => {
+    formFieldsState.setPlacedFieldDefaults(v ?? {});
+  },
+  { immediate: true }
+);
+watch(
+  () => props.editablePlacedFields,
+  (v) => {
+    formFieldsState.setEditablePlacedFields(v ?? false);
+  },
+  { immediate: true }
+);
+const signatureStatus = computed(() => formFieldsState.getSignatureFieldStatus());
+const signatureStatusKey = (fields) => fields.map((s) => `${s.id}|${s.fieldName}|${s.signed ? 1 : 0}`).join(";");
+watch(signatureStatus, (next, prev) => {
+  if (prev && signatureStatusKey(next) === signatureStatusKey(prev)) return;
+  const payload = { allSigned: next.every((s) => s.signed), fields: next };
+  emit("signed-status-changed", payload);
+  for (const cb of signedStatusCallbacks) cb(payload);
+});
 watch(
   () => props.activeRoleId,
   (v) => {
@@ -918,7 +948,12 @@ onMounted(() => {
     userName: props.userName,
     onRequestTextInput,
     onPlaceField: (payload) => {
-      formFieldsState.addPlacedField(payload);
+      const def = formFieldsState.addPlacedField(payload);
+      if (!viewerState.formEditMode.value && formFieldsState.editablePlacedFields.value) {
+        formFieldsState.selectPlacedField(def.id);
+      }
+      emit("field-placed", def);
+      for (const cb of fieldPlacedCallbacks) cb(def);
       viewerState.selectTool("hand");
     },
     getFormFieldPreviewColor: () => {
@@ -1070,6 +1105,37 @@ defineExpose({
   removeFormField: (id) => formFieldsState.removePlacedField(id),
   /** All form-field definitions (parsed, detected, and placed), flat. */
   getFormFields: () => formFieldsState.getAllFields(),
+  /** Replace the per-field-type presets applied to tool placements.
+   *  Programmatic counterpart to the `fieldDefaults` prop. */
+  setFieldDefaults: (defaults) => formFieldsState.setPlacedFieldDefaults(defaults),
+  /** Enable/disable kviewer's built-in click-to-sign flow at runtime.
+   *  Programmatic counterpart to the `clickToSign` prop. */
+  setClickToSign: (enabled) => {
+    viewerState.clickToSign.value = enabled;
+  },
+  /** Subscribe to tool placements (imperative mirror of the
+   *  `field-placed` event, used by the embed bridge). Returns an
+   *  unsubscribe function. */
+  onFieldPlaced: (cb) => {
+    fieldPlacedCallbacks.add(cb);
+    return () => fieldPlacedCallbacks.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
+   *  fields, so combine with `getSignatureFieldStatus().length` if you
+   *  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). */
+  getSignatureFieldStatus: () => formFieldsState.getSignatureFieldStatus(),
+  /** Subscribe to signed-status changes (imperative mirror of the
+   *  `signed-status-changed` event, used by the embed bridge). Returns
+   *  an unsubscribe function. */
+  onSignedStatusChanged: (cb) => {
+    signedStatusCallbacks.add(cb);
+    return () => signedStatusCallbacks.delete(cb);
+  },
   /** Reactive form-edit-mode flag — read with `.value`. */
   formEditMode: viewerState.formEditMode,
   /** Programmatically enter or leave form-edit mode. */

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

@@ -1,5 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
-import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, PlacedFieldDefaults, SignatureFieldStatus, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
 import type { ViewerToolEntry } from '../toolbar-tools.js';
@@ -35,6 +35,21 @@ type __VLS_Props = {
      *  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
+     *  a competing canvas — fields then render as passive markers. */
+    clickToSign?: boolean;
+    /** When true, user-placed form fields show selection chrome and can be
+     *  moved/resized/deleted in hand mode even outside form-edit mode.
+     *  Fields parsed from the source PDF are unaffected. */
+    editablePlacedFields?: boolean;
+    /** Per-field-type presets merged into every field the user places via
+     *  the placement tools (e.g. a signature `promptText` or `lockAction`).
+     *  `fieldName` stays auto-generated — rename via the `field-placed`
+     *  event and `updateFormField()`. Programmatic `addFormField()` calls
+     *  are not affected. */
+    fieldDefaults?: PlacedFieldDefaults;
     /** Execute embedded JavaScript inside the PDF — field-level AA scripts
      *  (Mouse Up, Calculate, Format, Validate, Keystroke), document-level
      *  open actions, and page-level scripts. Powered by pdf.js's QuickJS
@@ -98,6 +113,32 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     removeFormField: (id: string) => void;
     /** All form-field definitions (parsed, detected, and placed), flat. */
     getFormFields: () => FormFieldDefinition[];
+    /** Replace the per-field-type presets applied to tool placements.
+     *  Programmatic counterpart to the `fieldDefaults` prop. */
+    setFieldDefaults: (defaults: PlacedFieldDefaults) => void;
+    /** Enable/disable kviewer's built-in click-to-sign flow at runtime.
+     *  Programmatic counterpart to the `clickToSign` prop. */
+    setClickToSign: (enabled: boolean) => void;
+    /** Subscribe to tool placements (imperative mirror of the
+     *  `field-placed` event, used by the embed bridge). Returns an
+     *  unsubscribe function. */
+    onFieldPlaced: (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
+     *  fields, so combine with `getSignatureFieldStatus().length` if you
+     *  need "at least one". Use to gate e.g. envelope finalization. */
+    getSignedStatus: () => boolean;
+    /** Per-widget signed-state snapshot (id, fieldName, pageNumber,
+     *  signed, roleId). */
+    getSignatureFieldStatus: () => SignatureFieldStatus[];
+    /** Subscribe to signed-status changes (imperative mirror of the
+     *  `signed-status-changed` event, used by the embed bridge). Returns
+     *  an unsubscribe function. */
+    onSignedStatusChanged: (cb: (payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => void) => (() => void);
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */
@@ -114,20 +155,32 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     resetViewedPages: () => void;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "all-pages-read": () => any;
+    "field-placed": (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;
+        fields: SignatureFieldStatus[];
+    }) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onAll-pages-read"?: (() => any) | undefined;
+    "onField-placed"?: ((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;
+        fields: SignatureFieldStatus[];
+    }) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;
     zoom: number;
+    clickToSign: boolean;
     readonly: boolean;
     active: boolean;
+    locale: KviewerLocale;
     menuItems: ViewerMenuItem[];
     tools: ViewerToolEntry[];
     scripting: boolean;
@@ -138,7 +191,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     formEditMode: boolean;
     roleColors: Record<string, string>;
     activeRoleId: string | null;
-    locale: KviewerLocale;
+    editablePlacedFields: boolean;
+    fieldDefaults: PlacedFieldDefaults;
     messages: KviewerMessageOverrides;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

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

@@ -1,6 +1,6 @@
 import { type ComponentPublicInstance } from 'vue';
 import type { ViewMode } from '../composables/useViewerState.js';
-import type { StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { FormFieldDefinition, PlacedFieldDefaults, SignatureFieldStatus, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import type { ViewerMenuItem } from '../menu-items.js';
 import type { ViewerToolEntry } from '../toolbar-tools.js';
 export interface ViewerTabItem {
@@ -65,6 +65,13 @@ type __VLS_Props = {
     menuItems?: ViewerMenuItem[];
     /** Forwarded to every Viewer instance — see KViewer's `tools`. */
     tools?: ViewerToolEntry[];
+    /** Forwarded to every Viewer instance — see KViewer's `clickToSign`. */
+    clickToSign?: boolean;
+    /** Forwarded to every Viewer instance — see KViewer's
+     *  `editablePlacedFields`. */
+    editablePlacedFields?: boolean;
+    /** Forwarded to every Viewer instance — see KViewer's `fieldDefaults`. */
+    fieldDefaults?: PlacedFieldDefaults;
 };
 declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
     id?: string;
@@ -72,7 +79,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_32: {
+declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
     tab: {
         id: string;
         label: string;
@@ -172,7 +179,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_35: {
+}, __VLS_37: {
     tab: {
         id: string;
         label: string;
@@ -272,21 +279,21 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_39: string, __VLS_40: {
+}, __VLS_41: string, __VLS_42: {
     state: import("../composables/useViewerState.js").ViewerState;
-}, __VLS_42: {};
+}, __VLS_44: {};
 type __VLS_Slots = {} & {
-    [K in NonNullable<typeof __VLS_39>]?: (props: typeof __VLS_40) => any;
+    [K in NonNullable<typeof __VLS_41>]?: (props: typeof __VLS_42) => any;
 } & {
     'tabs-leading'?: (props: typeof __VLS_7) => any;
 } & {
     'tabs-trailing'?: (props: typeof __VLS_21) => any;
 } & {
-    header?: (props: typeof __VLS_32) => any;
+    header?: (props: typeof __VLS_34) => any;
 } & {
-    footer?: (props: typeof __VLS_35) => any;
+    footer?: (props: typeof __VLS_37) => any;
 } & {
-    empty?: (props: typeof __VLS_42) => any;
+    empty?: (props: typeof __VLS_44) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     addTab: typeof addTab;
@@ -394,13 +401,23 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         scripting?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "field-placed": (field: FormFieldDefinition) => any;
     "update:activeRoleId": (value: string | null) => any;
+    "signed-status-changed": (payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => any;
     "update:activeTab": (id: string) => any;
     "tab-added": (tab: ViewerTabItem) => any;
     "tab-close": (id: string) => any;
     "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;
+    "onSigned-status-changed"?: ((payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => any) | undefined;
     "onUpdate:activeTab"?: ((id: string) => any) | undefined;
     "onTab-added"?: ((tab: ViewerTabItem) => any) | undefined;
     "onTab-close"?: ((id: string) => any) | undefined;
@@ -408,6 +425,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
 }>, {
     userName: string;
     zoom: number;
+    clickToSign: boolean;
     menuItems: ViewerMenuItem[];
     tools: ViewerToolEntry[];
     scripting: boolean;
@@ -416,6 +434,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     viewMode: ViewMode;
     roleColors: Record<string, string>;
     activeRoleId: string | null;
+    editablePlacedFields: boolean;
+    fieldDefaults: PlacedFieldDefaults;
     defaultActiveTab: string;
     minTabs: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/runtime/components/ViewerTabs.vue

@@ -64,7 +64,12 @@
           :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)"
+          @signed-status-changed="(p) => emit('signed-status-changed', p)"
         >
           <template v-if="$slots.header" #header>
             <slot name="header" :tab="activeTab" />
@@ -107,13 +112,16 @@ const props = defineProps({
   activeRoleId: { type: [String, null], required: false, default: void 0 },
   scripting: { type: Boolean, required: false, default: false },
   menuItems: { type: Array, required: false, default: void 0 },
-  tools: { type: Array, required: false, default: void 0 }
+  tools: { type: Array, 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 }
 });
 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"]);
+const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed", "update:activeRoleId", "field-placed", "signed-status-changed"]);
 let idCounter = 0;
 function generateId() {
   return `tab-${Date.now()}-${++idCounter}`;

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

@@ -1,6 +1,6 @@
 import { type ComponentPublicInstance } from 'vue';
 import type { ViewMode } from '../composables/useViewerState.js';
-import type { StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { FormFieldDefinition, PlacedFieldDefaults, SignatureFieldStatus, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import type { ViewerMenuItem } from '../menu-items.js';
 import type { ViewerToolEntry } from '../toolbar-tools.js';
 export interface ViewerTabItem {
@@ -65,6 +65,13 @@ type __VLS_Props = {
     menuItems?: ViewerMenuItem[];
     /** Forwarded to every Viewer instance — see KViewer's `tools`. */
     tools?: ViewerToolEntry[];
+    /** Forwarded to every Viewer instance — see KViewer's `clickToSign`. */
+    clickToSign?: boolean;
+    /** Forwarded to every Viewer instance — see KViewer's
+     *  `editablePlacedFields`. */
+    editablePlacedFields?: boolean;
+    /** Forwarded to every Viewer instance — see KViewer's `fieldDefaults`. */
+    fieldDefaults?: PlacedFieldDefaults;
 };
 declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
     id?: string;
@@ -72,7 +79,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_32: {
+declare var __VLS_7: {}, __VLS_21: {}, __VLS_34: {
     tab: {
         id: string;
         label: string;
@@ -172,7 +179,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_35: {
+}, __VLS_37: {
     tab: {
         id: string;
         label: string;
@@ -272,21 +279,21 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         shapeDetection?: boolean | undefined;
         scripting?: boolean | undefined;
     };
-}, __VLS_39: string, __VLS_40: {
+}, __VLS_41: string, __VLS_42: {
     state: import("../composables/useViewerState.js").ViewerState;
-}, __VLS_42: {};
+}, __VLS_44: {};
 type __VLS_Slots = {} & {
-    [K in NonNullable<typeof __VLS_39>]?: (props: typeof __VLS_40) => any;
+    [K in NonNullable<typeof __VLS_41>]?: (props: typeof __VLS_42) => any;
 } & {
     'tabs-leading'?: (props: typeof __VLS_7) => any;
 } & {
     'tabs-trailing'?: (props: typeof __VLS_21) => any;
 } & {
-    header?: (props: typeof __VLS_32) => any;
+    header?: (props: typeof __VLS_34) => any;
 } & {
-    footer?: (props: typeof __VLS_35) => any;
+    footer?: (props: typeof __VLS_37) => any;
 } & {
-    empty?: (props: typeof __VLS_42) => any;
+    empty?: (props: typeof __VLS_44) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     addTab: typeof addTab;
@@ -394,13 +401,23 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         scripting?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "field-placed": (field: FormFieldDefinition) => any;
     "update:activeRoleId": (value: string | null) => any;
+    "signed-status-changed": (payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => any;
     "update:activeTab": (id: string) => any;
     "tab-added": (tab: ViewerTabItem) => any;
     "tab-close": (id: string) => any;
     "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;
+    "onSigned-status-changed"?: ((payload: {
+        allSigned: boolean;
+        fields: SignatureFieldStatus[];
+    }) => any) | undefined;
     "onUpdate:activeTab"?: ((id: string) => any) | undefined;
     "onTab-added"?: ((tab: ViewerTabItem) => any) | undefined;
     "onTab-close"?: ((id: string) => any) | undefined;
@@ -408,6 +425,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
 }>, {
     userName: string;
     zoom: number;
+    clickToSign: boolean;
     menuItems: ViewerMenuItem[];
     tools: ViewerToolEntry[];
     scripting: boolean;
@@ -416,6 +434,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     viewMode: ViewMode;
     roleColors: Record<string, string>;
     activeRoleId: string | null;
+    editablePlacedFields: boolean;
+    fieldDefaults: PlacedFieldDefaults;
     defaultActiveTab: string;
     minTabs: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

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

@@ -11,7 +11,7 @@
   >
     <div
       class="kviewer-form-field__body"
-      :class="{ 'kviewer-form-field__body--locked': isFormEditMode }"
+      :class="{ 'kviewer-form-field__body--locked': showChrome }"
     >
       <FormTextField v-if="props.field.fieldType === 'text'" :field="props.field" />
       <FormCheckbox v-else-if="props.field.fieldType === 'checkbox'" :field="props.field" />
@@ -55,7 +55,9 @@ const state = useViewerState();
 const formFields = useFormFields();
 const isPlaced = computed(() => props.field.origin === "placed");
 const isFormEditMode = computed(() => state.formEditMode.value);
-const showChrome = computed(() => isFormEditMode.value);
+const showChrome = computed(
+  () => isFormEditMode.value || formFields.editablePlacedFields.value && isPlaced.value
+);
 const chromeColor = computed(() => {
   const id = props.field.roleId;
   if (!id) return "#1677ff";