kviewer 0.0.10 → 0.1.0

package/README.md

@@ -81,6 +81,11 @@ await viewerRef.value?.importAnnotations(draft, { mode: 'replace' })
 // Read / write form field values
 const fields = viewerRef.value?.getFormFieldValues()
 viewerRef.value?.setFormFieldValue('email', 'user@example.com')
+
+// Toggle form-edit mode programmatically
+viewerRef.value?.setFormEditMode(true)
+viewerRef.value?.toggleFormEditMode()
+const isEditing = viewerRef.value?.formEditMode.value
 </script>
 ```
 
@@ -92,9 +97,33 @@ viewerRef.value?.setFormFieldValue('email', 'user@example.com')
 | `getFormFieldValues()` | `FormFieldValue[]` |
 | `setFormFieldValue(fieldName, value)` | `void` |
 | `getKonvaCanvasState()` | `Record<number, string>` |
+| `formEditMode` | `Ref<boolean>` |
+| `setFormEditMode(enabled)` | `void` |
+| `toggleFormEditMode()` | `boolean` (the new state) |
 
 `exportPdf` options default to `{ flatten: false, download: false, preserveOriginalAnnotations: false }`.
 
+### Form-edit mode
+
+`KViewer` exposes a **form-edit mode** that turns every form field into a movable/resizable widget with a property sidebar. It's also reachable from the burger menu in the toolbar, but consumers can drive it externally via prop binding or the imperative API.
+
+Two-way binding via `v-model:form-edit-mode`:
+
+```vue
+<template>
+  <button @click="formEditMode = !formEditMode">
+    {{ formEditMode ? 'Exit edit mode' : 'Edit form' }}
+  </button>
+  <KViewer v-model:form-edit-mode="formEditMode" :source="pdfUrl" />
+</template>
+
+<script setup lang="ts">
+const formEditMode = ref(false)
+</script>
+```
+
+Or imperatively from the ref API (`setFormEditMode`, `toggleFormEditMode`, reactive `formEditMode` ref).
+
 When native PDF annotations are auto-imported into Konva, exporting with `preserveOriginalAnnotations: true` may duplicate annotations. Prefer `preserveOriginalAnnotations: false` in that workflow.
 
 ## Development

package/dist/module.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-export { ExportPdfOptions, SignatureData, SignatureHandlers, ViewMode } from '../dist/runtime/public-types.js';
+export { AddFormFieldPayload, CheckboxStyle, ExportPdfOptions, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, SignatureData, SignatureHandlers, ViewMode } from '../dist/runtime/public-types.js';
 
 interface ModuleOptions {
     /**
@@ -7,6 +7,14 @@ interface ModuleOptions {
      * @defaultValue `K`
      */
     prefix?: string;
+    /**
+     * Minimum pixel ratio used to rasterize PDF pages. The canvas is rendered
+     * at `cssSize * max(devicePixelRatio, minRenderPixelRatio)` and downscaled
+     * by CSS, producing a supersampled, sharper image on non-HiDPI displays.
+     * Higher values cost ~quadratically more memory and CPU.
+     * @defaultValue `2`
+     */
+    minRenderPixelRatio?: number;
 }
 
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "kviewer",
   "configKey": "kviewer",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,3 +1,5 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
 import { defineNuxtModule, createResolver, addPlugin, addComponentsDir } from '@nuxt/kit';
 
 const module$1 = defineNuxtModule({
@@ -7,10 +9,15 @@ const module$1 = defineNuxtModule({
   },
   // Default configuration options of the Nuxt module
   defaults: {
-    prefix: "K"
+    prefix: "K",
+    minRenderPixelRatio: 2
   },
   setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.kviewer = {
+      ...nuxt.options.runtimeConfig.public.kviewer,
+      minRenderPixelRatio: options.minRenderPixelRatio ?? 2
+    };
     nuxt.options.css.push("pdfjs-dist/web/pdf_viewer.css");
     nuxt.options.css.push(resolve("./runtime/assets/kviewer.css"));
     addPlugin(resolve("./runtime/plugin"));
@@ -20,6 +27,23 @@ const module$1 = defineNuxtModule({
       prefix: options.prefix,
       ignore: ["color-mode/**", "content/**", "prose/**"]
     });
+    const require_ = createRequire(import.meta.url);
+    const pdfjsDir = dirname(require_.resolve("pdfjs-dist/package.json"));
+    nuxt.hook("nitro:config", (nitroConfig) => {
+      nitroConfig.publicAssets ||= [];
+      nitroConfig.publicAssets.push(
+        {
+          dir: join(pdfjsDir, "standard_fonts"),
+          baseURL: "/_kviewer/standard_fonts",
+          maxAge: 60 * 60 * 24 * 365
+        },
+        {
+          dir: join(pdfjsDir, "cmaps"),
+          baseURL: "/_kviewer/cmaps",
+          maxAge: 60 * 60 * 24 * 365
+        }
+      );
+    });
   }
 });
 

package/dist/runtime/annotation/checkbox-styles.d.ts

@@ -0,0 +1,19 @@
+import type { CheckboxStyle } from './engine/types.js';
+/**
+ * Maps each standard checkbox style to:
+ * - `caption`: the single ZapfDingbats character written to `/MK /CA` on
+ *   the widget when the PDF is exported (per ISO 32000-1 §12.5.6.19).
+ * - `glyph`: a Unicode character with the same visual meaning, used by
+ *   the HTML viewer to render the checkbox in the user's browser without
+ *   needing to embed the ZapfDingbats font.
+ */
+export declare const CHECKBOX_STYLE_TABLE: Record<CheckboxStyle, {
+    caption: string;
+    glyph: string;
+}>;
+/** Reverse lookup: ZapfDingbats `/MK /CA` character → CheckboxStyle. */
+export declare function captionToStyle(caption: string): CheckboxStyle | undefined;
+export declare const CHECKBOX_STYLE_OPTIONS: {
+    label: string;
+    value: CheckboxStyle;
+}[];

package/dist/runtime/annotation/checkbox-styles.js

@@ -0,0 +1,27 @@
+export const CHECKBOX_STYLE_TABLE = {
+  // Heavy check / cross (U+2714 / U+2718) match Apple Preview's chunkier
+  // ZapfDingbats-style rendering — the thin U+2713/U+2717 glyphs feel
+  // anemic next to the field border. The trailing U+FE0E (variation
+  // selector-15) forces the text presentation, otherwise macOS swaps
+  // them for colored emoji.
+  check: { caption: "4", glyph: "\u2714\uFE0E" },
+  cross: { caption: "8", glyph: "\u2718\uFE0E" },
+  diamond: { caption: "u", glyph: "\u25C6" },
+  circle: { caption: "l", glyph: "\u25CF" },
+  star: { caption: "H", glyph: "\u2605" },
+  square: { caption: "n", glyph: "\u25A0" }
+};
+export function captionToStyle(caption) {
+  for (const [style, info] of Object.entries(CHECKBOX_STYLE_TABLE)) {
+    if (info.caption === caption) return style;
+  }
+  return void 0;
+}
+export const CHECKBOX_STYLE_OPTIONS = [
+  { label: "Check", value: "check" },
+  { label: "Cross", value: "cross" },
+  { label: "Diamond", value: "diamond" },
+  { label: "Circle", value: "circle" },
+  { label: "Star", value: "star" },
+  { label: "Square", value: "square" }
+];

package/dist/runtime/annotation/engine/config.js

@@ -279,5 +279,49 @@ export const annotationDefinitions = [
     resizable: true,
     draggable: true,
     icon: "i-lucide-stamp"
+  },
+  {
+    name: "formText",
+    type: AnnotationType.FORM_TEXT,
+    pdfjsEditorType: PdfjsAnnotationEditorType.NONE,
+    pdfjsAnnotationType: PdfjsAnnotationType.WIDGET,
+    subtype: "Widget",
+    isOnce: true,
+    resizable: false,
+    draggable: false,
+    icon: "i-lucide-text-cursor-input"
+  },
+  {
+    name: "formCheckbox",
+    type: AnnotationType.FORM_CHECKBOX,
+    pdfjsEditorType: PdfjsAnnotationEditorType.NONE,
+    pdfjsAnnotationType: PdfjsAnnotationType.WIDGET,
+    subtype: "Widget",
+    isOnce: true,
+    resizable: false,
+    draggable: false,
+    icon: "i-lucide-square-check"
+  },
+  {
+    name: "formSignature",
+    type: AnnotationType.FORM_SIGNATURE,
+    pdfjsEditorType: PdfjsAnnotationEditorType.NONE,
+    pdfjsAnnotationType: PdfjsAnnotationType.WIDGET,
+    subtype: "Widget",
+    isOnce: true,
+    resizable: false,
+    draggable: false,
+    icon: "i-lucide-signature"
+  },
+  {
+    name: "formRadio",
+    type: AnnotationType.FORM_RADIO,
+    pdfjsEditorType: PdfjsAnnotationEditorType.NONE,
+    pdfjsAnnotationType: PdfjsAnnotationType.WIDGET,
+    subtype: "Widget",
+    isOnce: true,
+    resizable: false,
+    draggable: false,
+    icon: "i-lucide-circle-dot"
   }
 ];

package/dist/runtime/annotation/engine/painter.d.ts

@@ -1,12 +1,14 @@
 import Konva from 'konva';
 import type { IRect } from 'konva/lib/types';
-import { type IAnnotationStore, type IAnnotationStyle, type IAnnotationType } from './types.js';
+import { type IAnnotationStore, type IAnnotationStyle, type IAnnotationType, type PlaceFieldPayload } from './types.js';
 import { type IEditorFreeTextOptions } from './tools/free-text.js';
 export interface KonvaCanvas {
     pageNumber: number;
     konvaStage: Konva.Stage;
     wrapper: HTMLDivElement;
     isActive: boolean;
+    /** Base PDF-space page height — needed for coord flipping in placement tools. */
+    pageHeight: number;
 }
 export interface PainterCallbacks {
     setDefaultMode: () => void;
@@ -20,6 +22,11 @@ export interface PainterCallbacks {
     onAnnotationChanged: (annotationStore: IAnnotationStore, selectorRect: IRect) => void;
     onRequestTextInput: IEditorFreeTextOptions['onRequestTextInput'];
     onRequestDeleteConfirm?: (id: string) => Promise<boolean>;
+    onPlaceField?: (payload: PlaceFieldPayload) => void;
+    /** Optional accessor returning the color to use for the form-field
+     *  placement preview. Lets the active role color override the default
+     *  blue without rebuilding the editor between placements. */
+    getFormFieldPreviewColor?: () => string | undefined;
 }
 export declare class Painter {
     private userName;
@@ -51,7 +58,10 @@ export declare class Painter {
     private updateStore;
     /**
      * Convert a Konva stage-relative rect to viewport-relative coordinates
-     * by combining with the stage container's DOM position.
+     * by combining with the stage container's DOM position. `getBoundingClientRect`
+     * already includes ancestor CSS transforms (panzoom), but `stageRect` is in
+     * pre-transform canvas pixels — scale it by the same factor so the offset
+     * matches the on-screen size.
      */
     private toViewportRect;
     private parseStampData;

package/dist/runtime/annotation/engine/painter.js

@@ -22,6 +22,7 @@ import { EditorStamp } from "./tools/stamp.js";
 import { EditorNote } from "./tools/note.js";
 import { EditorArrow } from "./tools/arrow.js";
 import { EditorCloud } from "./tools/cloud.js";
+import { EditorFormField } from "./tools/form-field.js";
 import { Selector } from "./editor/selector.js";
 import { Store } from "./store.js";
 import { isIPad } from "./input-device.js";
@@ -181,17 +182,21 @@ export class Painter {
   }
   /**
    * Convert a Konva stage-relative rect to viewport-relative coordinates
-   * by combining with the stage container's DOM position.
+   * by combining with the stage container's DOM position. `getBoundingClientRect`
+   * already includes ancestor CSS transforms (panzoom), but `stageRect` is in
+   * pre-transform canvas pixels — scale it by the same factor so the offset
+   * matches the on-screen size.
    */
   toViewportRect(pageNumber, stageRect) {
     const canvas = this.konvaCanvasStore.get(pageNumber);
     if (!canvas) return stageRect;
     const containerBounds = canvas.wrapper.getBoundingClientRect();
+    const visualScale = canvas.wrapper.offsetWidth > 0 ? containerBounds.width / canvas.wrapper.offsetWidth : 1;
     return {
-      x: containerBounds.left + stageRect.x,
-      y: containerBounds.top + stageRect.y,
-      width: stageRect.width,
-      height: stageRect.height
+      x: containerBounds.left + stageRect.x * visualScale,
+      y: containerBounds.top + stageRect.y * visualScale,
+      width: stageRect.width * visualScale,
+      height: stageRect.height * visualScale
     };
   }
   parseStampData() {
@@ -244,6 +249,11 @@ export class Painter {
         );
         return;
       }
+      if (storeEditor instanceof EditorFormField) {
+        storeEditor.setPageHeight(
+          this.konvaCanvasStore.get(pageNumber)?.pageHeight ?? 0
+        );
+      }
       storeEditor.activate(konvaStage, annotation);
       return;
     }
@@ -312,6 +322,25 @@ export class Painter {
       case AnnotationType.STRIKEOUT:
         editor = new EditorHighLight(editorOpts, annotation.type);
         break;
+      case AnnotationType.FORM_TEXT:
+      case AnnotationType.FORM_CHECKBOX:
+      case AnnotationType.FORM_RADIO:
+      case AnnotationType.FORM_SIGNATURE: {
+        const onPlaceField = this.callbacks.onPlaceField;
+        if (!onPlaceField) {
+          console.warn("Form-field placement requires an onPlaceField callback.");
+          return;
+        }
+        const pageHeight = this.konvaCanvasStore.get(pageNumber)?.pageHeight ?? 0;
+        const fieldType = annotation.type === AnnotationType.FORM_TEXT ? "text" : annotation.type === AnnotationType.FORM_CHECKBOX ? "checkbox" : annotation.type === AnnotationType.FORM_RADIO ? "radio" : "signature";
+        editor = new EditorFormField(editorOpts, {
+          fieldType,
+          pageHeight,
+          onPlaceField,
+          getPreviewColor: this.callbacks.getFormFieldPreviewColor
+        });
+        break;
+      }
       case AnnotationType.SELECT:
         this.selector.activate(pageNumber);
         break;
@@ -451,7 +480,8 @@ export class Painter {
       pageNumber,
       konvaStage,
       wrapper: container,
-      isActive: false
+      isActive: false,
+      pageHeight: height
     });
     this.reDrawAnnotation(pageNumber);
     this.enablePainting();

package/dist/runtime/annotation/engine/tools/form-field.d.ts

@@ -0,0 +1,30 @@
+import type { KonvaEventObject } from 'konva/lib/Node';
+import { type FormFieldType, type IAnnotationStore, type IAnnotationStyle, type PlaceFieldPayload } from '../types.js';
+import { Editor, type IEditorOptions } from '../editor/editor.js';
+export interface IEditorFormFieldOptions {
+    fieldType: FormFieldType;
+    /** PDF-space page height, needed to flip Konva page-local Y → PDF Y. */
+    pageHeight: number;
+    onPlaceField: (payload: PlaceFieldPayload) => void;
+    /** Resolves to the active role color so the placement preview matches
+     *  the color the field will be tagged with. Re-read on every drag start
+     *  so the user can switch roles between placements without rebuilding
+     *  the editor. */
+    getPreviewColor?: () => string | undefined;
+}
+export declare class EditorFormField extends Editor {
+    private fieldType;
+    private pageHeight;
+    private onPlaceField;
+    private getPreviewColor?;
+    private preview;
+    private vertex;
+    constructor(editorOptions: IEditorOptions, opts: IEditorFormFieldOptions);
+    setPageHeight(pageHeight: number): void;
+    protected mouseDownHandler(e: KonvaEventObject<MouseEvent | TouchEvent>): void;
+    protected mouseMoveHandler(e: KonvaEventObject<MouseEvent | TouchEvent>): void;
+    protected mouseUpHandler(): void;
+    private globalPointerUpHandler;
+    protected changeStyle(_a: IAnnotationStore, _s: IAnnotationStyle): void;
+    addSerializedGroupToLayer(): void;
+}

package/dist/runtime/annotation/engine/tools/form-field.js

@@ -0,0 +1,119 @@
+import Konva from "konva";
+import {
+  AnnotationType
+} from "../types.js";
+import { Editor } from "../editor/editor.js";
+const TOO_SMALL = 6;
+const DEFAULT_CHECKBOX = 18;
+const DEFAULT_RADIO = 18;
+const DEFAULT_SIGNATURE = { width: 200, height: 60 };
+export class EditorFormField extends Editor {
+  fieldType;
+  pageHeight;
+  onPlaceField;
+  getPreviewColor;
+  preview = null;
+  vertex = { x: 0, y: 0 };
+  constructor(editorOptions, opts) {
+    super({
+      ...editorOptions,
+      editorType: opts.fieldType === "text" ? AnnotationType.FORM_TEXT : opts.fieldType === "checkbox" ? AnnotationType.FORM_CHECKBOX : opts.fieldType === "radio" ? AnnotationType.FORM_RADIO : AnnotationType.FORM_SIGNATURE
+    });
+    this.fieldType = opts.fieldType;
+    this.pageHeight = opts.pageHeight;
+    this.onPlaceField = opts.onPlaceField;
+    this.getPreviewColor = opts.getPreviewColor;
+  }
+  setPageHeight(pageHeight) {
+    this.pageHeight = pageHeight;
+  }
+  mouseDownHandler(e) {
+    if (e.currentTarget !== this.konvaStage) return;
+    const pos = this.konvaStage.getRelativePointerPosition();
+    if (!pos) return;
+    this.isPainting = true;
+    this.vertex = { x: pos.x, y: pos.y };
+    this.preview = new Konva.Rect({
+      x: pos.x,
+      y: pos.y,
+      width: 0,
+      height: 0,
+      stroke: this.getPreviewColor?.() ?? "#1677ff",
+      strokeWidth: 1,
+      dash: [4, 4],
+      strokeScaleEnabled: false,
+      visible: false,
+      listening: false
+    });
+    this.getBgLayer().add(this.preview);
+    window.addEventListener("mouseup", this.globalPointerUpHandler);
+  }
+  mouseMoveHandler(e) {
+    if (!this.isPainting || !this.preview) return;
+    e.evt.preventDefault();
+    const pos = this.konvaStage.getRelativePointerPosition();
+    if (!pos) return;
+    this.preview.show();
+    this.preview.setAttrs({
+      x: Math.min(this.vertex.x, pos.x),
+      y: Math.min(this.vertex.y, pos.y),
+      width: Math.abs(pos.x - this.vertex.x),
+      height: Math.abs(pos.y - this.vertex.y)
+    });
+  }
+  mouseUpHandler() {
+    if (!this.isPainting) return;
+    this.isPainting = false;
+    window.removeEventListener("mouseup", this.globalPointerUpHandler);
+    const preview = this.preview;
+    if (!preview) return;
+    let x = preview.x();
+    let y = preview.y();
+    let w = preview.width();
+    let h = preview.height();
+    const dragged = preview.isVisible() && Math.max(w, h) >= TOO_SMALL;
+    if (!dragged) {
+      if (this.fieldType === "checkbox") {
+        w = DEFAULT_CHECKBOX;
+        h = DEFAULT_CHECKBOX;
+        x = this.vertex.x - w / 2;
+        y = this.vertex.y - h / 2;
+      } else if (this.fieldType === "radio") {
+        w = DEFAULT_RADIO;
+        h = DEFAULT_RADIO;
+        x = this.vertex.x - w / 2;
+        y = this.vertex.y - h / 2;
+      } else if (this.fieldType === "signature") {
+        w = DEFAULT_SIGNATURE.width;
+        h = DEFAULT_SIGNATURE.height;
+        x = this.vertex.x - w / 2;
+        y = this.vertex.y - h / 2;
+      } else {
+        preview.destroy();
+        this.preview = null;
+        return;
+      }
+    }
+    preview.destroy();
+    this.preview = null;
+    const x1 = x;
+    const x2 = x + w;
+    const y2 = this.pageHeight - y;
+    const y1 = this.pageHeight - (y + h);
+    this.onPlaceField({
+      pageNumber: this.pageNumber,
+      fieldType: this.fieldType,
+      rectPdf: [x1, y1, x2, y2]
+    });
+  }
+  globalPointerUpHandler = (e) => {
+    if (e.button !== 0) return;
+    this.mouseUpHandler();
+  };
+  changeStyle(_a, _s) {
+  }
+  // Placed fields are never re-drawn from a konva string; the form-field
+  // HTML layer owns their visual representation.
+  addSerializedGroupToLayer() {
+  }
+}

package/dist/runtime/annotation/engine/types.d.ts

@@ -53,7 +53,11 @@ export declare enum AnnotationType {
     STAMP = 10,
     NOTE = 11,
     ARROW = 12,
-    CLOUD = 13
+    CLOUD = 13,
+    FORM_TEXT = 14,
+    FORM_CHECKBOX = 15,
+    FORM_SIGNATURE = 16,
+    FORM_RADIO = 17
 }
 export interface IAnnotationType {
     name: string;
@@ -134,16 +138,42 @@ export interface IAnnotationStore {
     draggable: boolean;
 }
 export type FormFieldType = 'text' | 'checkbox' | 'radio' | 'dropdown' | 'signature' | 'button';
+/**
+ * Standard PDF checkbox glyph styles, per Acrobat's "Check Box Style"
+ * options. Each maps to a single ZapfDingbats character written to the
+ * widget's `/MK /CA` entry — see ISO 32000-1 §12.5.6.19.
+ */
+export type CheckboxStyle = 'check' | 'cross' | 'diamond' | 'circle' | 'star' | 'square';
+/**
+ * Where a form field came from. Export uses this to decide whether to
+ * update an existing PDF widget ('parsed') or create a new one ('placed',
+ * 'detected'). Missing = 'parsed' for backward compat.
+ */
+export type FormFieldOrigin = 'parsed' | 'detected' | 'placed';
 export interface FormFieldDefinition {
     id: string;
     pageNumber: number;
     fieldType: FormFieldType;
     fieldName: string;
     rect: [number, number, number, number];
+    /** The rect this field had when first parsed from the source PDF. Used
+     *  on export to detect that a parsed field has been moved/resized so
+     *  its existing widget can be updated in place. Unset for placed and
+     *  detected fields (their `rect` IS their original rect). */
+    originalRect?: [number, number, number, number];
     readOnly: boolean;
     required: boolean;
+    origin?: FormFieldOrigin;
     /** Visual shape hint for detected checkboxes (circle renders round, rectangle renders square). */
     shapeType?: DetectedShapeType;
+    /** Checkbox glyph style. Only used when fieldType === 'checkbox'.
+     *  Defaults to 'check' for placed checkboxes; populated from `/MK /CA`
+     *  for parsed checkboxes when the source PDF specifies a non-default. */
+    checkboxStyle?: CheckboxStyle;
+    /** The checkbox style this field had when first parsed from the source
+     *  PDF. Used on export to detect that a parsed checkbox's style was
+     *  changed in form-edit mode, so we know to overwrite its `/MK /CA`. */
+    originalCheckboxStyle?: CheckboxStyle;
     defaultValue?: string;
     maxLen?: number;
     multiLine?: boolean;
@@ -159,10 +189,31 @@ export interface FormFieldDefinition {
     multiSelect?: boolean;
     editable?: boolean;
     buttonLabel?: string;
+    /** Signature-only: placeholder text shown on the unsigned widget.
+     *  Defaults to 'Click to sign' when unset. */
+    promptText?: string;
+    /** Signature-only: when this signature is filled, lock other fields in
+     *  the form so they can no longer be edited. Mirrors PDF spec
+     *  /Lock /Action: 'all' locks every other field; 'include' locks only
+     *  fields listed in lockFieldNames; 'exclude' locks every field NOT
+     *  listed. Enforced inside the viewer (the viewer flattens signatures
+     *  to images on export, so this doesn't round-trip as a real /Sig
+     *  /Lock dict). */
+    lockAction?: 'all' | 'include' | 'exclude';
+    /** Field names referenced by lockAction = 'include' or 'exclude'. */
+    lockFieldNames?: string[];
     fontSize?: number;
+    /** PDF font name as parsed from `/DA` (e.g. "Helv", "HelvB", "Times-Bold").
+     *  Used to derive CSS font-family / font-weight / font-style. */
+    fontName?: string;
     color?: number[];
     backgroundColor?: number[];
     textAlignment?: number;
+    /** Opaque role tag for color-coding in form-edit mode. The editor
+     *  doesn't own role definitions — the host (integrating app) maps
+     *  roleId → color via the `roleColors` prop on KViewer. Not exported
+     *  to the PDF. */
+    roleId?: string;
 }
 export interface FormFieldValue {
     fieldId: string;
@@ -170,6 +221,72 @@ export interface FormFieldValue {
     fieldType: FormFieldType;
     value: string | boolean | string[];
 }
+/** Payload for placing a new form field via the drawing tool. */
+export interface PlaceFieldPayload {
+    pageNumber: number;
+    fieldType: FormFieldType;
+    /** PDF-space rect [x1, y1, x2, y2], bottom-left origin. */
+    rectPdf: [number, number, number, number];
+}
+/**
+ * Public payload for adding a form field programmatically. All optional
+ * fields fall back to sensible defaults — only `pageNumber`, `fieldType`,
+ * and `rect` are required. The created field has `origin: 'placed'` so it
+ * is exported into the PDF as a new widget.
+ */
+export interface AddFormFieldPayload {
+    pageNumber: number;
+    fieldType: FormFieldType;
+    /** PDF-space rect [x1, y1, x2, y2], bottom-left origin. */
+    rect: [number, number, number, number];
+    /** Field name. Auto-generated when omitted. Multiple widgets that share
+     *  a `fieldName` (and `fieldType`) act as one PDF field — values are
+     *  mirrored across them on edit. Radios with the same `fieldName` form
+     *  one option group. */
+    fieldName?: string;
+    /** Opaque role tag for color-coding in form-edit mode. */
+    roleId?: string;
+    /** Default value for the field. Becomes the initial value too. */
+    defaultValue?: string;
+    readOnly?: boolean;
+    required?: boolean;
+    /** checkbox: glyph style. Defaults to 'check'. */
+    checkboxStyle?: CheckboxStyle;
+    /** signature: placeholder text on the unsigned widget. */
+    promptText?: string;
+    /** signature: lock other fields once signed. */
+    lockAction?: 'all' | 'include' | 'exclude';
+    /** signature: field names referenced by lockAction = 'include' / 'exclude'. */
+    lockFieldNames?: string[];
+    /** dropdown: editable combo box (true) vs list box (false). Defaults to true. */
+    combo?: boolean;
+    /** dropdown / listbox: allow multiple selections. */
+    multiSelect?: boolean;
+    /** dropdown / listbox: choices. */
+    options?: {
+        displayValue: string;
+        exportValue: string;
+    }[];
+    /** text: render as multiple lines. */
+    multiLine?: boolean;
+    /** text: render as a password field. */
+    password?: boolean;
+    /** text: render as evenly-spaced character cells (requires `maxLen`). */
+    comb?: boolean;
+    /** text: maximum input length. */
+    maxLen?: number;
+    /** radio: this widget's option value within its group. Auto-generated
+     *  when omitted (e.g. "Option_1", "Option_2", …). */
+    buttonValue?: string;
+    fontSize?: number;
+    fontName?: string;
+    /** RGB color tuple in 0–1 (PDF native). */
+    color?: number[];
+    /** RGB background color tuple in 0–1 (PDF native). */
+    backgroundColor?: number[];
+    /** 0 = left, 1 = center, 2 = right. */
+    textAlignment?: number;
+}
 export interface DetectedShapeRect {
     x: number;
     y: number;

package/dist/runtime/annotation/engine/types.js

@@ -54,6 +54,10 @@ export var AnnotationType = /* @__PURE__ */ ((AnnotationType2) => {
   AnnotationType2[AnnotationType2["NOTE"] = 11] = "NOTE";
   AnnotationType2[AnnotationType2["ARROW"] = 12] = "ARROW";
   AnnotationType2[AnnotationType2["CLOUD"] = 13] = "CLOUD";
+  AnnotationType2[AnnotationType2["FORM_TEXT"] = 14] = "FORM_TEXT";
+  AnnotationType2[AnnotationType2["FORM_CHECKBOX"] = 15] = "FORM_CHECKBOX";
+  AnnotationType2[AnnotationType2["FORM_SIGNATURE"] = 16] = "FORM_SIGNATURE";
+  AnnotationType2[AnnotationType2["FORM_RADIO"] = 17] = "FORM_RADIO";
   return AnnotationType2;
 })(AnnotationType || {});
 export var CommentStatus = /* @__PURE__ */ ((CommentStatus2) => {