kviewer 0.0.11 → 0.1.0

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.11",
+  "version": "0.1.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -9,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"));

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

@@ -23,6 +23,10 @@ export interface PainterCallbacks {
     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;
@@ -54,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

@@ -182,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() {
@@ -332,7 +336,8 @@ export class Painter {
         editor = new EditorFormField(editorOpts, {
           fieldType,
           pageHeight,
-          onPlaceField
+          onPlaceField,
+          getPreviewColor: this.callbacks.getFormFieldPreviewColor
         });
         break;
       }

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

@@ -6,11 +6,17 @@ export interface IEditorFormFieldOptions {
     /** 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);

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

@@ -11,6 +11,7 @@ export class EditorFormField extends Editor {
   fieldType;
   pageHeight;
   onPlaceField;
+  getPreviewColor;
   preview = null;
   vertex = { x: 0, y: 0 };
   constructor(editorOptions, opts) {
@@ -21,6 +22,7 @@ export class EditorFormField extends Editor {
     this.fieldType = opts.fieldType;
     this.pageHeight = opts.pageHeight;
     this.onPlaceField = opts.onPlaceField;
+    this.getPreviewColor = opts.getPreviewColor;
   }
   setPageHeight(pageHeight) {
     this.pageHeight = pageHeight;
@@ -36,7 +38,7 @@ export class EditorFormField extends Editor {
       y: pos.y,
       width: 0,
       height: 0,
-      stroke: "#1677ff",
+      stroke: this.getPreviewColor?.() ?? "#1677ff",
       strokeWidth: 1,
       dash: [4, 4],
       strokeScaleEnabled: false,

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

@@ -209,6 +209,11 @@ export interface FormFieldDefinition {
     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;
@@ -223,6 +228,65 @@ export interface PlaceFieldPayload {
     /** 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/pdf-export/export-form-fields.js

@@ -1,4 +1,14 @@
-import { PDFBool, PDFDict, PDFName, PDFString, StandardFonts, rgb } from "pdf-lib";
+import {
+  AcroFieldFlags,
+  AnnotationFlags,
+  PDFAcroSignature,
+  PDFBool,
+  PDFDict,
+  PDFName,
+  PDFRawStream,
+  PDFString,
+  StandardFonts
+} from "pdf-lib";
 import { CHECKBOX_STYLE_TABLE } from "../checkbox-styles.js";
 export async function writeFormFieldsToPdf(pdfDoc, fieldValues, placedDefinitions = []) {
   const valueByFieldId = new Map(fieldValues.map((v) => [v.fieldId, v]));
@@ -206,13 +216,7 @@ async function createWidgetForDefinition(pdfDoc, def, fv, radioGroupCache) {
       break;
     }
     case "signature": {
-      const v = fv?.value;
-      const signed = typeof v === "string" && v.startsWith("data:image");
-      if (signed) {
-        await drawSignatureImage(pdfDoc, page, v, box);
-      } else {
-        await drawSignaturePlaceholder(pdfDoc, page, box);
-      }
+      await createSignatureField(pdfDoc, page, def, fv);
       break;
     }
     case "dropdown": {
@@ -244,55 +248,101 @@ function applyFlags(field, def) {
   if (def.readOnly) field.enableReadOnly();
   if (def.required) field.enableRequired();
 }
-async function drawSignatureImage(pdfDoc, page, dataUrl, box) {
+async function createSignatureField(pdfDoc, page, def, fv) {
+  const { context } = pdfDoc;
+  const form = pdfDoc.getForm();
+  const [x1, y1, x2, y2] = def.rect;
+  const width = Math.max(1, x2 - x1);
+  const height = Math.max(1, y2 - y1);
+  const fieldDict = context.obj({
+    FT: "Sig",
+    Kids: []
+  });
+  const fieldRef = context.register(fieldDict);
+  const sig = PDFAcroSignature.fromDict(fieldDict, fieldRef);
+  sig.setPartialName(def.fieldName);
+  if (def.readOnly) sig.setFlagTo(AcroFieldFlags.ReadOnly, true);
+  if (def.required) sig.setFlagTo(AcroFieldFlags.Required, true);
+  const v = fv?.value;
+  const signed = typeof v === "string" && v.startsWith("data:image");
+  const appearanceRef = signed ? await buildSignedSignatureAppearance(pdfDoc, v, width, height) : await buildSignaturePlaceholderAppearance(pdfDoc, width, height);
+  const widgetDict = context.obj({
+    Type: "Annot",
+    Subtype: "Widget",
+    Rect: [x1, y1, x2, y2],
+    P: page.ref,
+    Parent: fieldRef,
+    F: 1 << AnnotationFlags.Print,
+    AP: { N: appearanceRef }
+  });
+  const widgetRef = context.register(widgetDict);
+  sig.addWidget(widgetRef);
+  form.acroForm.addField(fieldRef);
+  page.node.addAnnot(widgetRef);
+}
+async function buildSignaturePlaceholderAppearance(pdfDoc, width, height) {
+  const { context } = pdfDoc;
+  const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
+  const label = "Sign here";
+  const fontSize = Math.max(6, Math.min(12, height * 0.4));
+  const textWidth = font.widthOfTextAtSize(label, fontSize);
+  const textHeight = font.heightAtSize(fontSize);
+  const textX = (width - textWidth) / 2;
+  const textY = (height - textHeight) / 2;
+  const ops = [
+    "q",
+    "0.55 0.55 0.55 RG",
+    "0.75 w",
+    "[3 2] 0 d",
+    `0.5 0.5 ${(width - 1).toFixed(3)} ${(height - 1).toFixed(3)} re`,
+    "S",
+    "0.55 0.55 0.55 rg",
+    "BT",
+    `/F1 ${fontSize.toFixed(3)} Tf`,
+    `${textX.toFixed(3)} ${textY.toFixed(3)} Td`,
+    `(${label}) Tj`,
+    "ET",
+    "Q"
+  ].join("\n");
+  const dict = context.obj({
+    Type: "XObject",
+    Subtype: "Form",
+    BBox: [0, 0, width, height],
+    Matrix: [1, 0, 0, 1, 0, 0],
+    Resources: { Font: { F1: font.ref } }
+  });
+  const stream = PDFRawStream.of(dict, new TextEncoder().encode(ops));
+  return context.register(stream);
+}
+async function buildSignedSignatureAppearance(pdfDoc, dataUrl, width, height) {
   const match = dataUrl.match(/^data:(image\/[a-zA-Z0-9.+-]+);base64,(.+)$/);
-  if (!match) return;
+  if (!match) return buildSignaturePlaceholderAppearance(pdfDoc, width, height);
   const mimeType = match[1] ?? "";
   const base64 = match[2] ?? "";
-  let image;
-  if (mimeType.includes("jpeg") || mimeType.includes("jpg")) {
-    image = await pdfDoc.embedJpg(base64);
-  } else {
-    image = await pdfDoc.embedPng(base64);
-  }
+  const image = mimeType.includes("jpeg") || mimeType.includes("jpg") ? await pdfDoc.embedJpg(base64) : await pdfDoc.embedPng(base64);
   const imgAspect = image.width / image.height;
-  const boxAspect = box.width / box.height;
-  let drawW = box.width;
-  let drawH = box.height;
-  if (imgAspect > boxAspect) {
-    drawH = box.width / imgAspect;
-  } else {
-    drawW = box.height * imgAspect;
-  }
-  const drawX = box.x + (box.width - drawW) / 2;
-  const drawY = box.y + (box.height - drawH) / 2;
-  page.drawImage(image, { x: drawX, y: drawY, width: drawW, height: drawH });
-}
-async function drawSignaturePlaceholder(pdfDoc, page, box) {
-  page.drawRectangle({
-    x: box.x,
-    y: box.y,
-    width: box.width,
-    height: box.height,
-    borderColor: rgb(0.55, 0.55, 0.55),
-    borderWidth: 0.75,
-    borderDashArray: [3, 2]
+  const boxAspect = width / height;
+  let drawW = width;
+  let drawH = height;
+  if (imgAspect > boxAspect) drawH = width / imgAspect;
+  else drawW = height * imgAspect;
+  const drawX = (width - drawW) / 2;
+  const drawY = (height - drawH) / 2;
+  const ops = [
+    "q",
+    `${drawW.toFixed(3)} 0 0 ${drawH.toFixed(3)} ${drawX.toFixed(3)} ${drawY.toFixed(3)} cm`,
+    "/Img Do",
+    "Q"
+  ].join("\n");
+  const dict = pdfDoc.context.obj({
+    Type: "XObject",
+    Subtype: "Form",
+    BBox: [0, 0, width, height],
+    Matrix: [1, 0, 0, 1, 0, 0],
+    Resources: { XObject: { Img: image.ref } }
   });
-  try {
-    const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
-    const label = "Sign here";
-    const fontSize = Math.max(6, Math.min(12, box.height * 0.4));
-    const textWidth = font.widthOfTextAtSize(label, fontSize);
-    const textHeight = font.heightAtSize(fontSize);
-    page.drawText(label, {
-      x: box.x + (box.width - textWidth) / 2,
-      y: box.y + (box.height - textHeight) / 2,
-      size: fontSize,
-      font,
-      color: rgb(0.55, 0.55, 0.55)
-    });
-  } catch {
-  }
+  const stream = PDFRawStream.of(dict, new TextEncoder().encode(ops));
+  return pdfDoc.context.register(stream);
 }
 async function embedSignatureImage(pdfDoc, field) {
   const dataUrl = field.value;

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:rgba(224,232,255,.6);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:rgba(224,232,255,.8);border-color:rgba(0,0,0,.2)}.kviewer-form-input:focus{background-color:rgba(224,232,255,.9);border-color:var(--color-primary,#3b82f6);outline:2px solid var(--color-primary,#3b82f6)}.kviewer-form-select{-webkit-appearance:auto;-moz-appearance:auto;appearance:auto;cursor:pointer}.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(--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(--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:rgba(59,130,246,.08);border-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-select{-webkit-appearance:auto;-moz-appearance:auto;appearance:auto;cursor:pointer}.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}

package/dist/runtime/components/PdfPage.vue

@@ -54,6 +54,7 @@
 
 <script setup>
 import { ref, shallowRef, computed, onMounted, onBeforeUnmount, watch } from "vue";
+import { useRuntimeConfig } from "#imports";
 import { useViewerState } from "../composables/useViewerState";
 import { useViewerSearch } from "../composables/useViewerSearch";
 import { usePageProxyCache } from "../composables/usePageProxyCache";
@@ -71,6 +72,10 @@ const props = defineProps({
 const canvasRef = ref(null);
 const textLayerRef = ref(null);
 const annotationRef = ref(null);
+const runtimeConfig = useRuntimeConfig();
+const minRenderPixelRatio = Number(
+  runtimeConfig.public.kviewer?.minRenderPixelRatio ?? 2
+);
 const state = useViewerState();
 const search = useViewerSearch();
 const proxyCache = usePageProxyCache();
@@ -181,7 +186,7 @@ async function renderCanvas(opts) {
     currentRenderTask.cancel();
     currentRenderTask = null;
   }
-  const dpr = window.devicePixelRatio || 1;
+  const dpr = Math.max(window.devicePixelRatio || 1, minRenderPixelRatio);
   const quality = props.renderQuality ?? 1;
   const viewport = proxy.getViewport({
     scale: props.scale * quality * dpr

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

@@ -1,5 +1,5 @@
 import { type ViewMode } from '../composables/useViewerState.js';
-import type { IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 type __VLS_Props = {
     source: string | Uint8Array | object;
@@ -21,6 +21,16 @@ type __VLS_Props = {
      *  with selection chrome, can be moved/resized, and the property panel
      *  is shown. Supports v-model via `v-model:form-edit-mode`. */
     formEditMode?: boolean;
+    /** Map of roleId → CSS color used to color-code form fields in
+     *  form-edit mode. The editor stays unopinionated about role
+     *  definitions: the host owns the role list, names, and color picker,
+     *  and just hands a flat lookup table to the viewer. Unknown or
+     *  missing ids fall back to the default blue. */
+    roleColors?: Record<string, string>;
+    /** Active role id new field placements are auto-tagged with. The host
+     *  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;
 };
 declare function exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
 type ImportMode = 'replace' | 'merge';
@@ -44,6 +54,16 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     getKonvaCanvasState: typeof getKonvaCanvasState;
     getFormFieldValues: () => import("../annotation/engine/types.js").FormFieldValue[];
     setFormFieldValue: (fieldName: string, value: string | boolean | string[]) => void;
+    /** Add a form field programmatically. Returns the created definition.
+     *  The new field is exported into the PDF on `exportPdf()` like any
+     *  field placed via the placement tool. */
+    addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
+    /** Patch a form field by id (rect, name, flags, type-specific props). */
+    updateFormField: (id: string, patch: Partial<FormFieldDefinition>) => void;
+    /** Remove a form field by id (drops its value too). */
+    removeFormField: (id: string) => void;
+    /** All form-field definitions (parsed, detected, and placed), flat. */
+    getFormFields: () => FormFieldDefinition[];
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */
@@ -52,8 +72,10 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     toggleFormEditMode: () => boolean;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:formEditMode": (value: boolean) => any;
+    "update:activeRoleId": (value: string | null) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onUpdate:formEditMode"?: ((value: boolean) => any) | undefined;
+    "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;
@@ -65,6 +87,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     viewMode: ViewMode;
     shapeDetection: boolean;
     formEditMode: boolean;
+    roleColors: Record<string, string>;
+    activeRoleId: string | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/runtime/components/Viewer.vue

@@ -221,9 +221,11 @@ const props = defineProps({
   shapeDetection: { type: Boolean, required: false, default: false },
   active: { type: Boolean, required: false, default: true },
   freehandGroupingDelay: { type: Number, required: false, default: 1e3 },
-  formEditMode: { type: Boolean, required: false, default: void 0 }
+  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 }
 });
-const emit = defineEmits(["update:formEditMode"]);
+const emit = defineEmits(["update:formEditMode", "update:activeRoleId"]);
 const viewerRoot = ref(null);
 const scrollContainer = ref(null);
 const { state: viewerState, setScrollToPageFn, setDownloadPdfFn } = provideViewerState();
@@ -249,6 +251,29 @@ watch(
 );
 const viewerSearch = provideViewerSearch();
 const formFieldsState = provideFormFields();
+watch(
+  () => props.roleColors,
+  (v) => {
+    formFieldsState.setRoleColors(v ?? {});
+  },
+  { immediate: true }
+);
+watch(
+  () => props.activeRoleId,
+  (v) => {
+    if (v === void 0) return;
+    if (formFieldsState.activeRoleId.value !== v) {
+      formFieldsState.setActiveRole(v);
+    }
+  },
+  { immediate: true }
+);
+watch(
+  () => formFieldsState.activeRoleId.value,
+  (v) => {
+    if (props.activeRoleId !== v) emit("update:activeRoleId", v);
+  }
+);
 const pageSettings = providePageSettings(viewerRoot);
 const virtualization = createPageVirtualization();
 setScrollToPageFn((pageNumber) => {
@@ -686,6 +711,11 @@ onMounted(() => {
       formFieldsState.addPlacedField(payload);
       viewerState.selectTool("hand");
     },
+    getFormFieldPreviewColor: () => {
+      const id = formFieldsState.activeRoleId.value;
+      if (!id) return void 0;
+      return formFieldsState.roleColors.value[id];
+    },
     freehandGroupingDelay: props.freehandGroupingDelay,
     // Suspend panzoom gestures while an annotation is being dragged or
     // transformed. Otherwise single-finger pan runs in parallel with the
@@ -802,6 +832,16 @@ defineExpose({
   getKonvaCanvasState,
   getFormFieldValues: () => formFieldsState.getAllFieldValues(),
   setFormFieldValue: (fieldName, value) => formFieldsState.setFieldValueByName(fieldName, value),
+  /** Add a form field programmatically. Returns the created definition.
+   *  The new field is exported into the PDF on `exportPdf()` like any
+   *  field placed via the placement tool. */
+  addFormField: (payload) => formFieldsState.addFormField(payload),
+  /** Patch a form field by id (rect, name, flags, type-specific props). */
+  updateFormField: (id, patch) => formFieldsState.updatePlacedField(id, patch),
+  /** Remove a form field by id (drops its value too). */
+  removeFormField: (id) => formFieldsState.removePlacedField(id),
+  /** All form-field definitions (parsed, detected, and placed), flat. */
+  getFormFields: () => formFieldsState.getAllFields(),
   /** 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 { IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 type __VLS_Props = {
     source: string | Uint8Array | object;
@@ -21,6 +21,16 @@ type __VLS_Props = {
      *  with selection chrome, can be moved/resized, and the property panel
      *  is shown. Supports v-model via `v-model:form-edit-mode`. */
     formEditMode?: boolean;
+    /** Map of roleId → CSS color used to color-code form fields in
+     *  form-edit mode. The editor stays unopinionated about role
+     *  definitions: the host owns the role list, names, and color picker,
+     *  and just hands a flat lookup table to the viewer. Unknown or
+     *  missing ids fall back to the default blue. */
+    roleColors?: Record<string, string>;
+    /** Active role id new field placements are auto-tagged with. The host
+     *  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;
 };
 declare function exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
 type ImportMode = 'replace' | 'merge';
@@ -44,6 +54,16 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     getKonvaCanvasState: typeof getKonvaCanvasState;
     getFormFieldValues: () => import("../annotation/engine/types.js").FormFieldValue[];
     setFormFieldValue: (fieldName: string, value: string | boolean | string[]) => void;
+    /** Add a form field programmatically. Returns the created definition.
+     *  The new field is exported into the PDF on `exportPdf()` like any
+     *  field placed via the placement tool. */
+    addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
+    /** Patch a form field by id (rect, name, flags, type-specific props). */
+    updateFormField: (id: string, patch: Partial<FormFieldDefinition>) => void;
+    /** Remove a form field by id (drops its value too). */
+    removeFormField: (id: string) => void;
+    /** All form-field definitions (parsed, detected, and placed), flat. */
+    getFormFields: () => FormFieldDefinition[];
     /** Reactive form-edit-mode flag — read with `.value`. */
     formEditMode: import("vue").Ref<boolean, boolean>;
     /** Programmatically enter or leave form-edit mode. */
@@ -52,8 +72,10 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     toggleFormEditMode: () => boolean;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:formEditMode": (value: boolean) => any;
+    "update:activeRoleId": (value: string | null) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onUpdate:formEditMode"?: ((value: boolean) => any) | undefined;
+    "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;
@@ -65,6 +87,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     viewMode: ViewMode;
     shapeDetection: boolean;
     formEditMode: boolean;
+    roleColors: Record<string, string>;
+    activeRoleId: string | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

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

@@ -48,6 +48,11 @@ type __VLS_Props = {
     zoom?: number;
     /** Minimum number of tabs -- prevents closing below this count. */
     minTabs?: number;
+    /** Forwarded to every Viewer instance — see KViewer's `roleColors`. */
+    roleColors?: Record<string, string>;
+    /** Forwarded to every Viewer instance — see KViewer's `activeRoleId`.
+     *  Supports v-model via `v-model:active-role-id`. */
+    activeRoleId?: string | null;
 };
 declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
     id?: string;
@@ -55,7 +60,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_30: {
+declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
     tab: {
         id: string;
         label: string;
@@ -154,7 +159,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
     };
-}, __VLS_33: {
+}, __VLS_35: {
     tab: {
         id: string;
         label: string;
@@ -253,17 +258,17 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
     };
-}, __VLS_35: {};
+}, __VLS_37: {};
 type __VLS_Slots = {} & {
     'tabs-leading'?: (props: typeof __VLS_7) => any;
 } & {
     'tabs-trailing'?: (props: typeof __VLS_21) => any;
 } & {
-    header?: (props: typeof __VLS_30) => any;
+    header?: (props: typeof __VLS_32) => any;
 } & {
-    footer?: (props: typeof __VLS_33) => any;
+    footer?: (props: typeof __VLS_35) => any;
 } & {
-    empty?: (props: typeof __VLS_35) => any;
+    empty?: (props: typeof __VLS_37) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     addTab: typeof addTab;
@@ -370,11 +375,13 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         shapeDetection?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:activeRoleId": (value: string | null) => 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<{
+    "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
     "onUpdate:activeTab"?: ((id: string) => any) | undefined;
     "onTab-added"?: ((tab: ViewerTabItem) => any) | undefined;
     "onTab-close"?: ((id: string) => any) | undefined;
@@ -385,6 +392,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;
+    roleColors: Record<string, string>;
+    activeRoleId: string | null;
     defaultActiveTab: string;
     minTabs: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/runtime/components/ViewerTabs.vue

@@ -59,6 +59,9 @@
           :zoom="activeTab.zoom ?? zoom"
           :readonly="readonly"
           :shape-detection="activeTab.shapeDetection ?? shapeDetection"
+          :role-colors="roleColors"
+          :active-role-id="activeRoleId"
+          @update:active-role-id="(v) => emit('update:activeRoleId', v)"
         >
           <template v-if="$slots.header" #header>
             <slot name="header" :tab="activeTab" />
@@ -91,9 +94,11 @@ const props = defineProps({
   shapeDetection: { type: Boolean, required: false },
   viewMode: { type: String, required: false, default: "fit-width" },
   zoom: { type: Number, required: false, default: 1 },
-  minTabs: { type: Number, required: false, default: 0 }
+  minTabs: { type: Number, required: false, default: 0 },
+  roleColors: { type: Object, required: false, default: void 0 },
+  activeRoleId: { type: [String, null], required: false, default: void 0 }
 });
-const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed"]);
+const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed", "update:activeRoleId"]);
 let idCounter = 0;
 function generateId() {
   return `tab-${Date.now()}-${++idCounter}`;

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

@@ -48,6 +48,11 @@ type __VLS_Props = {
     zoom?: number;
     /** Minimum number of tabs -- prevents closing below this count. */
     minTabs?: number;
+    /** Forwarded to every Viewer instance — see KViewer's `roleColors`. */
+    roleColors?: Record<string, string>;
+    /** Forwarded to every Viewer instance — see KViewer's `activeRoleId`.
+     *  Supports v-model via `v-model:active-role-id`. */
+    activeRoleId?: string | null;
 };
 declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
     id?: string;
@@ -55,7 +60,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_30: {
+declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
     tab: {
         id: string;
         label: string;
@@ -154,7 +159,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
     };
-}, __VLS_33: {
+}, __VLS_35: {
     tab: {
         id: string;
         label: string;
@@ -253,17 +258,17 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_30: {
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
     };
-}, __VLS_35: {};
+}, __VLS_37: {};
 type __VLS_Slots = {} & {
     'tabs-leading'?: (props: typeof __VLS_7) => any;
 } & {
     'tabs-trailing'?: (props: typeof __VLS_21) => any;
 } & {
-    header?: (props: typeof __VLS_30) => any;
+    header?: (props: typeof __VLS_32) => any;
 } & {
-    footer?: (props: typeof __VLS_33) => any;
+    footer?: (props: typeof __VLS_35) => any;
 } & {
-    empty?: (props: typeof __VLS_35) => any;
+    empty?: (props: typeof __VLS_37) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     addTab: typeof addTab;
@@ -370,11 +375,13 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         shapeDetection?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:activeRoleId": (value: string | null) => 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<{
+    "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
     "onUpdate:activeTab"?: ((id: string) => any) | undefined;
     "onTab-added"?: ((tab: ViewerTabItem) => any) | undefined;
     "onTab-close"?: ((id: string) => any) | undefined;
@@ -385,6 +392,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;
+    roleColors: Record<string, string>;
+    activeRoleId: string | null;
     defaultActiveTab: string;
     minTabs: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

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

@@ -6,7 +6,7 @@
   'kviewer-form-field--placed': isPlaced,
   'kviewer-form-field--selected': props.selected
 }"
-    :style="positionStyle"
+    :style="[positionStyle, { '--kvw-field-color': chromeColor }]"
   >
     <div
       class="kviewer-form-field__body"
@@ -34,6 +34,7 @@
 <script setup>
 import { computed } from "vue";
 import { useViewerState } from "../../composables/useViewerState";
+import { useFormFields } from "../../composables/useFormFields";
 import FormTextField from "./FormTextField.vue";
 import FormCheckbox from "./FormCheckbox.vue";
 import FormRadioButton from "./FormRadioButton.vue";
@@ -51,9 +52,15 @@ const props = defineProps({
 });
 const emit = defineEmits(["select"]);
 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 chromeColor = computed(() => {
+  const id = props.field.roleId;
+  if (!id) return "#1677ff";
+  return formFields.roleColors.value[id] ?? "#1677ff";
+});
 const positionStyle = computed(() => {
   const rect = props.field.rect;
   const vx = props.viewOffsetX ?? 0;
@@ -73,5 +80,5 @@ const positionStyle = computed(() => {
 </script>
 
 <style>
-.kviewer-form-field__body{height:100%;width:100%}.kviewer-form-field__body--locked{pointer-events:none}.kviewer-form-field--editable{outline:1px dashed rgba(22,119,255,.45);outline-offset:0}.kviewer-form-field--editable.kviewer-form-field--placed{outline-color:rgba(22,119,255,.75)}.kviewer-form-field--editable.kviewer-form-field--selected{outline:none}
+.kviewer-form-field__body{height:100%;width:100%}.kviewer-form-field__body--locked{pointer-events:none}.kviewer-form-field--editable{outline:1px dashed color-mix(in srgb,var(--kvw-field-color,#1677ff) 45%,transparent);outline-offset:0}.kviewer-form-field--editable.kviewer-form-field--placed{outline-color:color-mix(in srgb,var(--kvw-field-color,#1677ff) 75%,transparent)}.kviewer-form-field--editable.kviewer-form-field--selected{outline:none}
 </style>

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

@@ -127,5 +127,5 @@ function onHandlePointerDown(e, name) {
 </script>
 
 <style>
-.kviewer-placed-chrome{cursor:move;inset:0;pointer-events:auto;position:absolute;touch-action:none}.kviewer-placed-chrome--selected{outline:1.5px dashed #1677ff;outline-offset:0}.kviewer-placed-chrome__grip{align-items:center;background:rgba(22,119,255,.15);border:1px solid rgba(22,119,255,.4);border-radius:calc(3px*var(--kvw-handle-zoom, 1));bottom:calc(100% + 3px*var(--kvw-handle-zoom, 1));color:#1677ff;cursor:move;display:flex;font-size:calc(9px*var(--kvw-handle-zoom, 1));gap:calc(3px*var(--kvw-handle-zoom, 1));height:calc(16px*var(--kvw-handle-zoom, 1));left:0;line-height:1;overflow:hidden;padding:0 calc(6px*var(--kvw-handle-zoom, 1)) 0 calc(2px*var(--kvw-handle-zoom, 1));pointer-events:auto;position:absolute;right:0;touch-action:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.kviewer-placed-chrome__grip-dots{color:#1677ff;flex:0 0 auto;height:calc(10px*var(--kvw-handle-zoom, 1));width:calc(10px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__grip-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kviewer-placed-chrome__handle{background:#fff;border:1px solid #1677ff;border-radius:2px;height:calc(8px*var(--kvw-handle-zoom, 1));pointer-events:auto;position:absolute;touch-action:none;width:calc(8px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle:before{content:"";inset:calc(-8px*var(--kvw-handle-zoom, 1));position:absolute}.kviewer-placed-chrome__handle--n{left:50%;top:calc(-4px*var(--kvw-handle-zoom, 1));transform:translateX(-50%)}.kviewer-placed-chrome__handle--s{bottom:calc(-4px*var(--kvw-handle-zoom, 1));left:50%;transform:translateX(-50%)}.kviewer-placed-chrome__handle--e{right:calc(-4px*var(--kvw-handle-zoom, 1));top:50%;transform:translateY(-50%)}.kviewer-placed-chrome__handle--w{left:calc(-4px*var(--kvw-handle-zoom, 1));top:50%;transform:translateY(-50%)}.kviewer-placed-chrome__handle--ne{right:calc(-4px*var(--kvw-handle-zoom, 1));top:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--nw{left:calc(-4px*var(--kvw-handle-zoom, 1));top:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--se{bottom:calc(-4px*var(--kvw-handle-zoom, 1));right:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--sw{bottom:calc(-4px*var(--kvw-handle-zoom, 1));left:calc(-4px*var(--kvw-handle-zoom, 1))}
+.kviewer-placed-chrome{cursor:move;inset:0;pointer-events:auto;position:absolute;touch-action:none}.kviewer-placed-chrome--selected{outline:1.5px dashed var(--kvw-field-color,#1677ff);outline-offset:0}.kviewer-placed-chrome__grip{align-items:center;background:color-mix(in srgb,var(--kvw-field-color,#1677ff) 15%,transparent);border:1px solid color-mix(in srgb,var(--kvw-field-color,#1677ff) 40%,transparent);border-radius:calc(3px*var(--kvw-handle-zoom, 1));bottom:calc(100% + 3px*var(--kvw-handle-zoom, 1));color:var(--kvw-field-color,#1677ff);cursor:move;display:flex;font-size:calc(9px*var(--kvw-handle-zoom, 1));gap:calc(3px*var(--kvw-handle-zoom, 1));height:calc(16px*var(--kvw-handle-zoom, 1));left:0;line-height:1;overflow:hidden;padding:0 calc(6px*var(--kvw-handle-zoom, 1)) 0 calc(2px*var(--kvw-handle-zoom, 1));pointer-events:auto;position:absolute;right:0;touch-action:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.kviewer-placed-chrome__grip-dots{color:var(--kvw-field-color,#1677ff);flex:0 0 auto;height:calc(10px*var(--kvw-handle-zoom, 1));width:calc(10px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__grip-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kviewer-placed-chrome__handle{background:#fff;border:1px solid var(--kvw-field-color,#1677ff);border-radius:2px;height:calc(8px*var(--kvw-handle-zoom, 1));pointer-events:auto;position:absolute;touch-action:none;width:calc(8px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle:before{content:"";inset:calc(-8px*var(--kvw-handle-zoom, 1));position:absolute}.kviewer-placed-chrome__handle--n{left:50%;top:calc(-4px*var(--kvw-handle-zoom, 1));transform:translateX(-50%)}.kviewer-placed-chrome__handle--s{bottom:calc(-4px*var(--kvw-handle-zoom, 1));left:50%;transform:translateX(-50%)}.kviewer-placed-chrome__handle--e{right:calc(-4px*var(--kvw-handle-zoom, 1));top:50%;transform:translateY(-50%)}.kviewer-placed-chrome__handle--w{left:calc(-4px*var(--kvw-handle-zoom, 1));top:50%;transform:translateY(-50%)}.kviewer-placed-chrome__handle--ne{right:calc(-4px*var(--kvw-handle-zoom, 1));top:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--nw{left:calc(-4px*var(--kvw-handle-zoom, 1));top:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--se{bottom:calc(-4px*var(--kvw-handle-zoom, 1));right:calc(-4px*var(--kvw-handle-zoom, 1))}.kviewer-placed-chrome__handle--sw{bottom:calc(-4px*var(--kvw-handle-zoom, 1));left:calc(-4px*var(--kvw-handle-zoom, 1))}
 </style>

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

@@ -5,6 +5,7 @@ export declare function createAnnotationEngine(viewerState: ViewerState, options
     onRequestTextInput: PainterCallbacks['onRequestTextInput'];
     onRequestDeleteConfirm?: PainterCallbacks['onRequestDeleteConfirm'];
     onPlaceField?: PainterCallbacks['onPlaceField'];
+    getFormFieldPreviewColor?: PainterCallbacks['getFormFieldPreviewColor'];
     freehandGroupingDelay?: number;
     setExternalGesturesEnabled?: (enabled: boolean) => void;
 }): Painter;

package/dist/runtime/composables/useAnnotationEngine.js

@@ -61,7 +61,8 @@ export function createAnnotationEngine(viewerState, options) {
     },
     onRequestTextInput: options.onRequestTextInput,
     onRequestDeleteConfirm: options.onRequestDeleteConfirm,
-    onPlaceField: options.onPlaceField
+    onPlaceField: options.onPlaceField,
+    getFormFieldPreviewColor: options.getFormFieldPreviewColor
   };
   const painter = new Painter({
     userName: options.userName ?? "User",

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

@@ -1,5 +1,5 @@
 import { type Ref, type ShallowRef } from 'vue';
-import type { CheckboxStyle, DetectedShape, FormFieldDefinition, FormFieldValue, PlaceFieldPayload } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, CheckboxStyle, DetectedShape, FormFieldDefinition, FormFieldValue, PlaceFieldPayload } from '../annotation/engine/types.js';
 export interface FormFieldsState {
     /** Field definitions grouped by page number */
     fieldDefinitions: ShallowRef<Map<number, FormFieldDefinition[]>>;
@@ -23,10 +23,16 @@ export interface FormFieldsState {
     registerDetectedCheckboxes: (pageNumber: number, shapes: DetectedShape[], scale: number, pageHeight: number) => void;
     /** Add a user-placed form field (from the placement tool). Returns the created def. */
     addPlacedField: (payload: PlaceFieldPayload) => FormFieldDefinition;
-    /** Update a placed field's rect, name, or flags. */
+    /** Add a form field programmatically. Public API counterpart to
+     *  `addPlacedField` with full control over the field's properties.
+     *  Returns the created definition. */
+    addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
+    /** Update a form field's rect, name, or flags. */
     updatePlacedField: (id: string, patch: Partial<FormFieldDefinition>) => void;
-    /** Remove a placed field and its value. */
+    /** Remove a form field and its value. */
     removePlacedField: (id: string) => void;
+    /** All form-field definitions, flattened across pages. */
+    getAllFields: () => FormFieldDefinition[];
     /** All user-placed field definitions (used by export). */
     getPlacedFields: () => FormFieldDefinition[];
     /** Look up a field definition by id (any origin). */
@@ -35,6 +41,19 @@ export interface FormFieldsState {
     selectedPlacedFieldId: Ref<string | null>;
     /** Select or deselect a placed field. Pass null to deselect. */
     selectPlacedField: (id: string | null) => void;
+    /** Opaque role id new placements are auto-tagged with. The host owns
+     *  what roles exist; the editor only carries the active id forward to
+     *  newly placed fields and looks up its color via roleColors. */
+    activeRoleId: Ref<string | null>;
+    /** Set or clear the active role for upcoming placements. */
+    setActiveRole: (id: string | null) => void;
+    /** Map from roleId → CSS color, supplied by the host via the KViewer
+     *  `roleColors` prop. Reading this drives the chrome and placement
+     *  preview color. The editor never mutates role definitions itself. */
+    roleColors: ShallowRef<Record<string, string>>;
+    /** Replace the host-provided color map. Called by KViewer when the
+     *  prop changes. */
+    setRoleColors: (colors: Record<string, string>) => void;
     /** Apply checkbox-style hints (extracted from `/MK /CA` in the source PDF)
      *  to existing parsed checkbox defs and store the map for any defs
      *  parsed afterwards. Keyed by checkbox fieldName. */

package/dist/runtime/composables/useFormFields.js

@@ -12,6 +12,14 @@ export function provideFormFields() {
   const fieldDefinitions = shallowRef(/* @__PURE__ */ new Map());
   const fieldValues = shallowRef(/* @__PURE__ */ new Map());
   const selectedPlacedFieldId = ref(null);
+  const activeRoleId = ref(null);
+  const roleColors = shallowRef({});
+  function setActiveRole(id) {
+    activeRoleId.value = id;
+  }
+  function setRoleColors(colors) {
+    roleColors.value = colors;
+  }
   function selectPlacedField(id) {
     selectedPlacedFieldId.value = id;
   }
@@ -231,6 +239,9 @@ export function provideFormFields() {
       required: false,
       origin: "placed"
     };
+    if (activeRoleId.value) {
+      def.roleId = activeRoleId.value;
+    }
     if (payload.fieldType === "radio") {
       def.buttonValue = nextRadioOptionValue(fieldName);
     }
@@ -256,6 +267,67 @@ export function provideFormFields() {
     }
     return def;
   }
+  function addFormField(payload) {
+    const id = `placed-${generateUUID()}`;
+    const fieldName = payload.fieldName ?? nextPlacedFieldName(payload.fieldType);
+    const def = {
+      id,
+      pageNumber: payload.pageNumber,
+      fieldType: payload.fieldType,
+      fieldName,
+      rect: [...payload.rect],
+      readOnly: payload.readOnly ?? false,
+      required: payload.required ?? false,
+      origin: "placed"
+    };
+    if (payload.roleId !== void 0) def.roleId = payload.roleId;
+    if (payload.defaultValue !== void 0) def.defaultValue = payload.defaultValue;
+    if (payload.fontSize !== void 0) def.fontSize = payload.fontSize;
+    if (payload.fontName !== void 0) def.fontName = payload.fontName;
+    if (payload.color !== void 0) def.color = payload.color;
+    if (payload.backgroundColor !== void 0) def.backgroundColor = payload.backgroundColor;
+    if (payload.textAlignment !== void 0) def.textAlignment = payload.textAlignment;
+    if (payload.fieldType === "radio") {
+      def.buttonValue = payload.buttonValue ?? nextRadioOptionValue(fieldName);
+    }
+    if (payload.fieldType === "checkbox") {
+      def.checkboxStyle = payload.checkboxStyle ?? "check";
+    }
+    if (payload.fieldType === "dropdown") {
+      def.combo = payload.combo ?? true;
+      def.options = payload.options ?? [{ exportValue: "Option 1", displayValue: "Option 1" }];
+      if (payload.multiSelect !== void 0) def.multiSelect = payload.multiSelect;
+    }
+    if (payload.fieldType === "text") {
+      if (payload.multiLine !== void 0) def.multiLine = payload.multiLine;
+      if (payload.password !== void 0) def.password = payload.password;
+      if (payload.comb !== void 0) def.comb = payload.comb;
+      if (payload.maxLen !== void 0) def.maxLen = payload.maxLen;
+    }
+    if (payload.fieldType === "signature") {
+      if (payload.promptText !== void 0) def.promptText = payload.promptText;
+      if (payload.lockAction !== void 0) def.lockAction = payload.lockAction;
+      if (payload.lockFieldNames !== void 0) def.lockFieldNames = payload.lockFieldNames;
+    }
+    const existingDefs = fieldDefinitions.value.get(payload.pageNumber) ?? [];
+    fieldDefinitions.value.set(payload.pageNumber, [...existingDefs, def]);
+    triggerRef(fieldDefinitions);
+    fieldValues.value.set(id, {
+      fieldId: id,
+      fieldName: def.fieldName,
+      fieldType: def.fieldType,
+      value: getDefaultValue(def)
+    });
+    triggerRef(fieldValues);
+    return def;
+  }
+  function getAllFields() {
+    const out = [];
+    for (const defs of fieldDefinitions.value.values()) {
+      for (const d of defs) out.push(d);
+    }
+    return out;
+  }
   function nextRadioOptionValue(groupName) {
     const used = /* @__PURE__ */ new Set();
     for (const defs of fieldDefinitions.value.values()) {
@@ -387,8 +459,10 @@ export function provideFormFields() {
     setFieldValueByName,
     registerDetectedCheckboxes,
     addPlacedField,
+    addFormField,
     updatePlacedField,
     removePlacedField,
+    getAllFields,
     getPlacedFields,
     getFieldById,
     selectedPlacedFieldId,
@@ -397,7 +471,11 @@ export function provideFormFields() {
     applyButtonCaptions,
     isFieldLocked,
     resetValues,
-    reset
+    reset,
+    activeRoleId,
+    setActiveRole,
+    roleColors,
+    setRoleColors
   };
   provide(FORM_FIELDS_KEY, state);
   return state;

package/dist/runtime/composables/useInertiaPanzoom.js

@@ -281,6 +281,7 @@ export function useInertiaPanzoom(options = {}) {
     }
     function onDown(e) {
       if (e.pointerType === "pen") return;
+      if (e.pointerType === "mouse") return;
       if (!gesturesEnabled) return;
       stopMomentum();
       setWillChangeActive(true);

package/dist/runtime/public-types.d.ts

@@ -1,4 +1,4 @@
 export type { ExportPdfOptions } from './annotation/pdf-export/export.js';
 export type { ViewerTabItem, AddTabOptions } from './components/ViewerTabs.vue.js';
-export type { SignatureData, SignatureHandlers } from './annotation/engine/types.js';
+export type { AddFormFieldPayload, CheckboxStyle, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, SignatureData, SignatureHandlers, } from './annotation/engine/types.js';
 export type { ViewMode } from './composables/viewMode.js';

package/dist/types.d.mts

@@ -1,4 +1,4 @@
-export { type ExportPdfOptions, type SignatureData, type SignatureHandlers, type ViewMode } from '../dist/runtime/public-types.js'
+export { type AddFormFieldPayload, type CheckboxStyle, type ExportPdfOptions, type FormFieldDefinition, type FormFieldOrigin, type FormFieldType, type FormFieldValue, type SignatureData, type SignatureHandlers, type ViewMode } from '../dist/runtime/public-types.js'
 
 export { default } from './module.mjs'
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kviewer",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "description": "Kabema PDF Editor",
   "repository": "kabema/kviewer",
   "license": "MIT",