kviewer 0.2.3 → 0.3.0

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

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

@@ -1,7 +1,10 @@
 <template>
   <div
     class="kviewer-form-signature"
-    :class="{ 'kviewer-form-signature--filled': hasSigned }"
+    :class="{
+  'kviewer-form-signature--filled': hasSigned,
+  'kviewer-form-signature--static': !clickToSignEnabled
+}"
     @click="onClickSign"
   >
     <img
@@ -10,13 +13,21 @@
       class="kviewer-form-signature__preview"
       :alt="t('signature')"
     >
-    <span v-else class="kviewer-form-signature__placeholder">
+    <span v-else-if="clickToSignEnabled" class="kviewer-form-signature__placeholder">
       {{ props.field.promptText || t("clickToSign") }}
     </span>
+    <!-- click-to-sign off: passive marker — the host owns the signing flow.
+         promptText is a call to action ("Sign here"), so it only applies to
+         the click-to-sign placeholder; the marker stays a neutral label. -->
+    <span v-else class="kviewer-form-signature__placeholder kviewer-form-signature__marker">
+      <UIcon name="i-lucide-signature" class="kviewer-form-signature__marker-icon" />
+      {{ t("signature") }}
+    </span>
   </div>
 
   <ClientOnly>
     <SignatureDrawModal
+      v-if="clickToSignEnabled"
       v-model:open="drawModalOpen"
       @submit="onDrawSubmit"
       @cancel="drawModalOpen = false"
@@ -43,7 +54,9 @@ const signatureUrl = computed(() => {
   return fv.value;
 });
 const hasSigned = computed(() => !!signatureUrl.value);
+const clickToSignEnabled = computed(() => state.clickToSign.value);
 async function onClickSign() {
+  if (!clickToSignEnabled.value) return;
   if (props.field.readOnly || state.readonly.value) return;
   if (formFields.isFieldLocked(props.field.id)) return;
   if (state.signatures.value.length > 0) {

package/dist/runtime/components/modals/FreeTextModal.vue

@@ -2,7 +2,7 @@
   <UModal
     v-model:open="isOpen"
     :title="props.initialText !== void 0 ? t('editText') : t('freeText')"
-    :ui="{ width: 'sm:max-w-md' }"
+    :ui="{ content: 'sm:max-w-md' }"
   >
     <template #body>
       <div class="flex flex-col gap-3">

package/dist/runtime/components/modals/SignatureDrawModal.vue

@@ -1,8 +1,25 @@
 <template>
-  <UModal v-model:open="isOpen" :title="t('drawSignature')" :ui="{ content: 'sm:max-w-2xl' }">
+  <UModal v-model:open="isOpen" :title="t('addSignature')" :ui="{ content: 'sm:max-w-2xl' }">
     <template #body>
       <div class="flex flex-col gap-3">
+        <div class="flex gap-1" role="tablist">
+          <button
+            v-for="tab in tabs"
+            :key="tab"
+            role="tab"
+            :aria-selected="mode === tab"
+            class="px-3 py-1.5 text-sm rounded cursor-pointer"
+            :class="
+  mode === tab ? 'bg-elevated text-highlighted font-medium' : 'text-muted hover:text-default'
+"
+            @click="mode = tab"
+          >
+            {{ tab === "draw" ? t("drawSignature") : t("uploadSignature") }}
+          </button>
+        </div>
+
         <div
+          v-show="mode === 'draw'"
           ref="canvasWrapEl"
           class="border border-default rounded bg-white relative w-full"
           :style="{ aspectRatio: `${canvasAspect}` }"
@@ -16,7 +33,8 @@
             @pointerleave="onPointerUp"
           />
         </div>
-        <div class="flex items-center gap-3">
+
+        <div v-if="mode === 'draw'" class="flex items-center gap-3">
           <div class="flex gap-1">
             <button
               v-for="c in signatureColors"
@@ -33,6 +51,50 @@
             {{ t("clear") }}
           </UButton>
         </div>
+
+        <template v-if="mode === 'upload'">
+          <!-- The checkerboard makes transparency visible, so users can
+               tell whether background removal actually worked before
+               placing the signature on the page. -->
+          <div
+            class="border border-dashed border-default rounded relative w-full flex items-center justify-center bg-checkerboard"
+            :style="{ aspectRatio: `${canvasAspect}` }"
+            @dragover.prevent
+            @drop.prevent="onDrop"
+          >
+            <img
+              v-if="uploadedUrl"
+              :src="uploadedUrl"
+              class="max-w-full max-h-full object-contain"
+              :alt="t('uploadSignature')"
+            >
+            <button
+              v-else
+              class="w-full h-full flex flex-col items-center justify-center gap-1 text-muted text-sm cursor-pointer"
+              @click="fileInputEl?.click()"
+            >
+              <span>{{ t("dropSignatureImage") }}</span>
+              <span class="text-xs">{{ acceptHint }}</span>
+            </button>
+          </div>
+
+          <input
+            ref="fileInputEl"
+            type="file"
+            :accept="accept"
+            class="hidden"
+            @change="onFileChange"
+          >
+
+          <p v-if="uploadError" class="text-sm text-error">{{ uploadError }}</p>
+
+          <div class="flex items-center gap-3">
+            <UButton variant="ghost" color="neutral" size="xs" @click="fileInputEl?.click()">
+              {{ t("chooseImage") }}
+            </UButton>
+            <UCheckbox v-model="removeBackground" size="sm" :label="t('removeWhiteBackground')" />
+          </div>
+        </template>
       </div>
     </template>
     <template #footer>
@@ -40,7 +102,7 @@
         <UButton variant="ghost" color="neutral" @click="cancel">
           {{ t("cancel") }}
         </UButton>
-        <UButton :disabled="!hasDrawn" @click="submit">
+        <UButton :disabled="!hasContent" @click="submit">
           {{ t("save") }}
         </UButton>
       </div>
@@ -49,8 +111,9 @@
 </template>
 
 <script setup>
-import { ref, watch, nextTick, onBeforeUnmount } from "vue";
+import { ref, computed, watch, nextTick, onBeforeUnmount } from "vue";
 import { defaultOptions } from "../../annotation/engine/config";
+import { fitWithin, knockOutWhite } from "../../annotation/utils/signature_image";
 import { useKviewerI18n } from "../../composables/useKviewerI18n";
 const { t } = useKviewerI18n();
 const props = defineProps({
@@ -64,6 +127,8 @@ watch(
     isOpen.value = v;
     if (v) {
       hasDrawn.value = false;
+      mode.value = "draw";
+      resetUpload();
       await nextTick();
       syncCanvasSize();
       clearCanvas();
@@ -71,6 +136,8 @@ watch(
   }
 );
 watch(isOpen, (v) => emit("update:open", v));
+const tabs = ["draw", "upload"];
+const mode = ref("draw");
 const canvasAspect = `${defaultOptions.signature.WIDTH} / ${defaultOptions.signature.HEIGHT}`;
 const signatureColors = defaultOptions.signature.COLORS;
 const canvasRef = ref(null);
@@ -165,7 +232,102 @@ function clearCanvas() {
   ctx.restore();
   hasDrawn.value = false;
 }
+const accept = defaultOptions.signature.ACCEPT;
+const maxSize = defaultOptions.signature.MAX_SIZE;
+const fileInputEl = ref(null);
+const uploadedUrl = ref(null);
+const uploadError = ref(null);
+const removeBackground = ref(true);
+let sourceImage = null;
+const acceptHint = accept.replace(/\./g, "").toUpperCase().replace(/,/g, ", ");
+const maxSizeMb = Math.round(maxSize / (1024 * 1024));
+const hasContent = computed(
+  () => mode.value === "draw" ? hasDrawn.value : !!uploadedUrl.value
+);
+function resetUpload() {
+  uploadedUrl.value = null;
+  uploadError.value = null;
+  sourceImage = null;
+  if (fileInputEl.value) fileInputEl.value.value = "";
+}
+function onDrop(e) {
+  const file = e.dataTransfer?.files?.[0];
+  if (file) void handleFile(file);
+}
+function onFileChange(e) {
+  const file = e.target.files?.[0];
+  if (file) void handleFile(file);
+}
+async function handleFile(file) {
+  uploadError.value = null;
+  const extension = `.${file.name.split(".").pop()?.toLowerCase() ?? ""}`;
+  if (!accept.split(",").includes(extension)) {
+    uploadError.value = t("unsupportedImageType", { accept: acceptHint });
+    return;
+  }
+  if (file.size > maxSize) {
+    uploadError.value = t("imageTooLarge", { size: maxSizeMb });
+    return;
+  }
+  try {
+    sourceImage = await loadImage(file);
+    renderUpload();
+  } catch {
+    sourceImage = null;
+    uploadError.value = t("imageReadFailed");
+  }
+}
+function loadImage(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error("read failed"));
+    reader.onload = () => {
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => reject(new Error("decode failed"));
+      img.src = reader.result;
+    };
+    reader.readAsDataURL(file);
+  });
+}
+const MAX_OUTPUT_SCALE = 3;
+function renderUpload() {
+  const img = sourceImage;
+  if (!img) return;
+  const { width, height } = fitWithin(
+    img.naturalWidth,
+    img.naturalHeight,
+    defaultOptions.signature.WIDTH * MAX_OUTPUT_SCALE,
+    defaultOptions.signature.HEIGHT * MAX_OUTPUT_SCALE
+  );
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  if (!ctx) {
+    uploadError.value = t("imageReadFailed");
+    return;
+  }
+  ctx.drawImage(img, 0, 0, width, height);
+  if (removeBackground.value) {
+    try {
+      const imageData = ctx.getImageData(0, 0, width, height);
+      knockOutWhite(imageData.data);
+      ctx.putImageData(imageData, 0, 0);
+    } catch {
+      uploadError.value = t("backgroundRemovalFailed");
+    }
+  }
+  uploadedUrl.value = canvas.toDataURL("image/png");
+}
+watch(removeBackground, () => {
+  if (sourceImage) renderUpload();
+});
 function submit() {
+  if (mode.value === "upload") {
+    if (uploadedUrl.value) emit("submit", uploadedUrl.value);
+    return;
+  }
   const canvas = canvasRef.value;
   if (!canvas) return;
   const imageUrl = canvas.toDataURL("image/png");
@@ -175,3 +337,7 @@ function cancel() {
   emit("cancel");
 }
 </script>
+
+<style scoped>
+.bg-checkerboard{background-color:#fff;background-image:linear-gradient(45deg,#e5e5e5 25%,transparent 0),linear-gradient(-45deg,#e5e5e5 25%,transparent 0),linear-gradient(45deg,transparent 75%,#e5e5e5 0),linear-gradient(-45deg,transparent 75%,#e5e5e5 0);background-position:0 0,0 8px,8px -8px,-8px 0;background-size:16px 16px}
+</style>