kviewer 0.0.11 → 0.1.1

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, KVIEWER_EMBED_PROTOCOL_VERSION, KViewerApi, KViewerEmbedBridgeOptions, KViewerEmbedClient, KViewerEmbedClientOptions, KViewerEmbedEventName, KViewerEmbedEventPayloads, KViewerEmbedMethodName, SignatureData, SignatureHandlers, ViewMode, ViewerMenuButtonItem, ViewerMenuCheckboxItem, ViewerMenuItem, ViewerMenuSeparatorItem, useKViewerEmbedBridge } 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.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,6 +1,7 @@
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import { defineNuxtModule, createResolver, addPlugin, addComponentsDir } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addPlugin, addComponentsDir, addImports } from '@nuxt/kit';
+export { KVIEWER_EMBED_PROTOCOL_VERSION, KViewerEmbedClient, useKViewerEmbedBridge } from '../dist/runtime/public-types.js';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -9,10 +10,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"));
@@ -22,6 +28,11 @@ const module$1 = defineNuxtModule({
       prefix: options.prefix,
       ignore: ["color-mode/**", "content/**", "prose/**"]
     });
+    addImports([
+      { name: "useKViewerEmbedBridge", from: resolve("./runtime/embed/bridge-host") },
+      { name: "KViewerEmbedClient", from: resolve("./runtime/embed/bridge-client") },
+      { name: "KVIEWER_EMBED_PROTOCOL_VERSION", from: resolve("./runtime/embed/protocol") }
+    ]);
     const require_ = createRequire(import.meta.url);
     const pdfjsDir = dirname(require_.resolve("pdfjs-dist/package.json"));
     nuxt.hook("nitro:config", (nitroConfig) => {
@@ -36,6 +47,15 @@ const module$1 = defineNuxtModule({
           dir: join(pdfjsDir, "cmaps"),
           baseURL: "/_kviewer/cmaps",
           maxAge: 60 * 60 * 24 * 365
+        },
+        // PDF.js scripting sandbox bundle. Required when the viewer's
+        // `scripting` prop is enabled — the sandbox is a QuickJS WASM
+        // module that executes embedded PDF JavaScript (field AA scripts,
+        // calculate/format/validate, document/page-open actions).
+        {
+          dir: join(pdfjsDir, "legacy/build"),
+          baseURL: "/_kviewer/pdfjs",
+          maxAge: 60 * 60 * 24 * 365
         }
       );
     });

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,6 +1,7 @@
 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';
+import type { ViewerMenuItem } from '../menu-items.js';
 type __VLS_Props = {
     source: string | Uint8Array | object;
     textLayer?: boolean;
@@ -21,6 +22,29 @@ 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;
+    /** 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
+     *  WASM sandbox (no DOM/network/host-JS escape), but arbitrary JS from
+     *  untrusted PDFs is still real attack surface — default is `false`.
+     *  Treated as read-once per document; toggling at runtime requires
+     *  changing the `source` prop or remounting the component. */
+    scripting?: boolean;
+    /** Extra items appended to the default burger menu (after Download
+     *  and the form-field-detection toggle). Use this to expose app-level
+     *  toggles or actions without replacing the entire header. Ignored
+     *  when the host supplies a custom `#header` slot. */
+    menuItems?: ViewerMenuItem[];
 };
 declare function exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
 type ImportMode = 'replace' | 'merge';
@@ -44,6 +68,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,19 +86,25 @@ 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;
     zoom: number;
     readonly: boolean;
     active: boolean;
+    menuItems: ViewerMenuItem[];
+    scripting: boolean;
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     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;