kviewer 0.0.10 → 0.1.0

package/dist/runtime/annotation/font-style.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decode the font name parsed from a PDF widget's `/DA` (Default
+ * Appearance) string into CSS font properties.
+ *
+ * PDF /DA font names come in two flavours:
+ *  - PDF "abbreviations" used by Acrobat for the standard 14 fonts
+ *    (`Helv`, `HelvB`, `HelvO`, `HelvBO`, `TiRo`, `TiBo`, `TiIt`,
+ *    `TiBI`, `Cour`, `CoBo`, `CoOb`, `CoBO`, `ZaDb`, `Symb`).
+ *  - Full PostScript-style names (`Helvetica-Bold`, `Times-Italic`,
+ *    `Courier-BoldOblique`, etc.) — common in PDFs produced by other
+ *    tools.
+ *
+ * Anything we don't recognize falls back to sans-serif regular —
+ * exactly what pdf.js's annotation layer renders. Unrecognized names
+ * still keep weight/style detection via the `Bold`/`Italic`/`Oblique`
+ * substring check, so e.g. `MyFont-Bold` becomes `bold`.
+ */
+export interface DecodedFontStyle {
+    fontFamily: string;
+    fontWeight: 'normal' | 'bold';
+    fontStyle: 'normal' | 'italic';
+}
+export declare function decodeFontName(fontName: string | undefined): DecodedFontStyle;

package/dist/runtime/annotation/font-style.js

@@ -0,0 +1,57 @@
+const STANDARD_14 = {
+  // Helvetica family
+  Helv: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "normal" },
+  HelvB: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "normal" },
+  HelvO: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "italic" },
+  HelvBO: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "italic" },
+  Helvetica: { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "normal" },
+  "Helvetica-Bold": { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "normal" },
+  "Helvetica-Oblique": { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "normal", fontStyle: "italic" },
+  "Helvetica-BoldOblique": { fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif', fontWeight: "bold", fontStyle: "italic" },
+  // Times family
+  TiRo: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "normal" },
+  TiBo: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "normal" },
+  TiIt: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "italic" },
+  TiBI: { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "italic" },
+  "Times-Roman": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "normal" },
+  "Times-Bold": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "normal" },
+  "Times-Italic": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "normal", fontStyle: "italic" },
+  "Times-BoldItalic": { fontFamily: '"Times New Roman", Times, serif', fontWeight: "bold", fontStyle: "italic" },
+  // Courier family
+  Cour: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "normal" },
+  CoBo: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "normal" },
+  CoOb: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "italic" },
+  CoBO: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "italic" },
+  Courier: { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "normal" },
+  "Courier-Bold": { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "normal" },
+  "Courier-Oblique": { fontFamily: '"Courier New", Courier, monospace', fontWeight: "normal", fontStyle: "italic" },
+  "Courier-BoldOblique": { fontFamily: '"Courier New", Courier, monospace', fontWeight: "bold", fontStyle: "italic" }
+};
+const DEFAULT_STYLE = {
+  fontFamily: "sans-serif",
+  fontWeight: "normal",
+  fontStyle: "normal"
+};
+export function decodeFontName(fontName) {
+  if (!fontName) return DEFAULT_STYLE;
+  const name = fontName.startsWith("/") ? fontName.slice(1) : fontName;
+  const standard = STANDARD_14[name];
+  if (standard) return standard;
+  const stripped = /^[A-Z]{6}\+/.test(name) ? name.slice(7) : name;
+  const lower = stripped.toLowerCase();
+  let fontFamily = "sans-serif";
+  if (/serif|times|roman|georgia|garamond|cambria/.test(lower)) {
+    fontFamily = '"Times New Roman", Times, serif';
+  } else if (/mono|courier|consolas|menlo|inconsolata/.test(lower)) {
+    fontFamily = '"Courier New", Courier, monospace';
+  } else if (/helvet|arial|verdana|tahoma|sans/.test(lower)) {
+    fontFamily = '"Helvetica Neue", Helvetica, Arial, sans-serif';
+  }
+  const isBold = /bold|black|heavy|semibold|demibold/i.test(stripped);
+  const isItalic = /italic|oblique/i.test(stripped);
+  return {
+    fontFamily,
+    fontWeight: isBold ? "bold" : "normal",
+    fontStyle: isItalic ? "italic" : "normal"
+  };
+}

package/dist/runtime/annotation/parsers/extractCheckboxStyles.d.ts

@@ -0,0 +1,21 @@
+import type { CheckboxStyle } from '../engine/types.js';
+/**
+ * Walk the AcroForm of a source PDF and extract the checkbox style hint
+ * (`/MK /CA`) for every checkbox widget. pdf.js does not surface this
+ * field, so without a side-channel parse we cannot know whether an
+ * existing checkbox should render as a check, cross, diamond, etc.
+ *
+ * Returns a Map keyed by field name. If multiple widgets share a name
+ * (uncommon for checkboxes, normal for radio groups), the first hit
+ * wins.
+ */
+export declare function extractCheckboxStyles(pdfBytes: Uint8Array | ArrayBuffer): Promise<Map<string, CheckboxStyle>>;
+/**
+ * Walk the AcroForm and extract push-button captions from `/MK /CA`.
+ * pdf.js exposes neither the caption nor a button label, so without this
+ * side-channel parse every push button would render with our generic
+ * "Button" fallback (e.g. a Reset button shows the wrong text).
+ *
+ * Returns a Map keyed by the button's fully qualified field name.
+ */
+export declare function extractButtonCaptions(pdfBytes: Uint8Array | ArrayBuffer): Promise<Map<string, string>>;

package/dist/runtime/annotation/parsers/extractCheckboxStyles.js

@@ -0,0 +1,75 @@
+import { PDFButton, PDFCheckBox, PDFDocument, PDFDict, PDFHexString, PDFName, PDFString } from "pdf-lib";
+import { captionToStyle } from "../checkbox-styles.js";
+export async function extractCheckboxStyles(pdfBytes) {
+  const out = /* @__PURE__ */ new Map();
+  let doc;
+  try {
+    doc = await PDFDocument.load(pdfBytes, { ignoreEncryption: true });
+  } catch {
+    return out;
+  }
+  let form;
+  try {
+    form = doc.getForm();
+  } catch {
+    return out;
+  }
+  for (const field of form.getFields()) {
+    if (!(field instanceof PDFCheckBox)) continue;
+    const acro = field.acroField;
+    const name = field.getName();
+    if (!name || out.has(name)) continue;
+    const widgets = acro.getWidgets();
+    for (const widget of widgets) {
+      const mk = widget.dict.get(PDFName.of("MK"));
+      if (!(mk instanceof PDFDict)) continue;
+      const ca = mk.get(PDFName.of("CA"));
+      let caption;
+      if (ca instanceof PDFString || ca instanceof PDFHexString) {
+        caption = ca.decodeText();
+      }
+      if (!caption) continue;
+      const style = captionToStyle(caption);
+      if (style) {
+        out.set(name, style);
+        break;
+      }
+    }
+  }
+  return out;
+}
+export async function extractButtonCaptions(pdfBytes) {
+  const out = /* @__PURE__ */ new Map();
+  let doc;
+  try {
+    doc = await PDFDocument.load(pdfBytes, { ignoreEncryption: true });
+  } catch {
+    return out;
+  }
+  let form;
+  try {
+    form = doc.getForm();
+  } catch {
+    return out;
+  }
+  for (const field of form.getFields()) {
+    if (!(field instanceof PDFButton)) continue;
+    const acro = field.acroField;
+    const name = field.getName();
+    if (!name || out.has(name)) continue;
+    const widgets = acro.getWidgets();
+    for (const widget of widgets) {
+      const mk = widget.dict.get(PDFName.of("MK"));
+      if (!(mk instanceof PDFDict)) continue;
+      const ca = mk.get(PDFName.of("CA"));
+      if (ca instanceof PDFString || ca instanceof PDFHexString) {
+        const caption = ca.decodeText();
+        if (caption) {
+          out.set(name, caption);
+          break;
+        }
+      }
+    }
+  }
+  return out;
+}

package/dist/runtime/annotation/parsers/parseFormFields.js

@@ -19,8 +19,10 @@ export function parseFormFields(annotations, pageNumber) {
       fieldType,
       fieldName: ann.fieldName ?? "",
       rect: normalizedRect,
+      originalRect: [...normalizedRect],
       readOnly: Boolean(ann.readOnly),
-      required: Boolean(ann.required)
+      required: Boolean(ann.required),
+      origin: "parsed"
     };
     if (fieldType === "text") {
       if (ann.fieldValue != null) def.defaultValue = String(ann.fieldValue);
@@ -68,8 +70,19 @@ export function parseFormFields(annotations, pageNumber) {
     if (fieldType === "button") {
       def.buttonLabel = ann.alternativeText ?? ann.fieldValue ?? ann.fieldName ?? "Button";
     }
-    if (typeof ann.fontSize === "number") def.fontSize = ann.fontSize;
-    if (Array.isArray(ann.color)) {
+    const da = ann.defaultAppearanceData ?? {};
+    if (typeof da.fontSize === "number" && da.fontSize > 0) {
+      def.fontSize = da.fontSize;
+    } else if (typeof ann.fontSize === "number" && ann.fontSize > 0) {
+      def.fontSize = ann.fontSize;
+    }
+    if (typeof da.fontName === "string" && da.fontName.length > 0) {
+      def.fontName = da.fontName;
+    }
+    if (da.fontColor && da.fontColor.length >= 3) {
+      const fc = da.fontColor;
+      def.color = [fc[0] ?? 0, fc[1] ?? 0, fc[2] ?? 0];
+    } else if (Array.isArray(ann.color)) {
       def.color = ann.color.map(
         (c) => (
           // pdf.js colors may be 0-1 floats or 0-255 integers

package/dist/runtime/annotation/pdf-export/export-form-fields.d.ts

@@ -1,9 +1,12 @@
-import type { PDFDocument } from 'pdf-lib';
-import type { FormFieldValue } from '../engine/types.js';
+import { type PDFDocument } from 'pdf-lib';
+import type { FormFieldDefinition, FormFieldValue } from '../engine/types.js';
 /**
  * Write form field values back to the PDF using pdf-lib's AcroForm API.
  *
- * This updates existing form fields in the PDF with the values the user
- * entered in the viewer. It does NOT create new fields.
+ * - Placed/detected fields that originate from the viewer are created as new
+ *   AcroForm widgets (text, checkbox, radio). Signature fields are drawn as
+ *   flat images (pdf-lib does not support creating AcroForm signature widgets).
+ * - Parsed fields (already present in the source PDF) get their values
+ *   updated in place.
  */
-export declare function writeFormFieldsToPdf(pdfDoc: PDFDocument, fieldValues: FormFieldValue[]): Promise<void>;
+export declare function writeFormFieldsToPdf(pdfDoc: PDFDocument, fieldValues: FormFieldValue[], placedDefinitions?: FormFieldDefinition[]): Promise<void>;

package/dist/runtime/annotation/pdf-export/export-form-fields.js

@@ -1,6 +1,42 @@
-export async function writeFormFieldsToPdf(pdfDoc, fieldValues) {
+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]));
+  const createdFieldNames = /* @__PURE__ */ new Set();
+  const radioGroupCache = /* @__PURE__ */ new Map();
+  for (const def of placedDefinitions) {
+    try {
+      if (def.origin === "parsed") {
+        updateParsedField(pdfDoc, def);
+      } else {
+        await createWidgetForDefinition(
+          pdfDoc,
+          def,
+          valueByFieldId.get(def.id),
+          radioGroupCache
+        );
+        createdFieldNames.add(def.fieldName);
+      }
+    } catch (err) {
+      console.warn(
+        `Failed to write form field "${def.fieldName}" (${def.fieldType}, origin=${def.origin ?? "parsed"}):`,
+        err
+      );
+    }
+  }
   const form = pdfDoc.getForm();
   for (const field of fieldValues) {
+    if (createdFieldNames.has(field.fieldName)) continue;
     try {
       switch (field.fieldType) {
         case "text": {
@@ -50,6 +86,264 @@ export async function writeFormFieldsToPdf(pdfDoc, fieldValues) {
     }
   }
 }
+function applyCheckboxStyle(pdfDoc, cb, def) {
+  const style = def.checkboxStyle;
+  if (!style) return;
+  const caption = CHECKBOX_STYLE_TABLE[style]?.caption;
+  if (!caption) return;
+  const widgets = cb.acroField.getWidgets();
+  for (const widget of widgets) {
+    let mk = widget.dict.get(PDFName.of("MK"));
+    if (!(mk instanceof PDFDict)) {
+      mk = pdfDoc.context.obj({});
+      widget.dict.set(PDFName.of("MK"), mk);
+    }
+    mk.set(PDFName.of("CA"), PDFString.of(caption));
+  }
+  const form = pdfDoc.getForm();
+  form.acroForm.dict.set(PDFName.of("NeedAppearances"), PDFBool.True);
+}
+function updateParsedField(pdfDoc, def) {
+  const form = pdfDoc.getForm();
+  let field;
+  try {
+    field = form.getField(def.fieldName);
+  } catch {
+    return;
+  }
+  const widgets = field.acroField.getWidgets();
+  if (widgets.length === 0) return;
+  const target = def.originalRect ? pickWidgetByRect(widgets, def.originalRect) : widgets[0];
+  if (!target) return;
+  if (def.originalRect && !rectsEqual(def.rect, def.originalRect)) {
+    const [x1, y1, x2, y2] = def.rect;
+    target.setRectangle({
+      x: x1,
+      y: y1,
+      width: Math.max(1, x2 - x1),
+      height: Math.max(1, y2 - y1)
+    });
+    if (def.fieldType === "text" && def.comb) {
+      form.acroForm.dict.set(PDFName.of("NeedAppearances"), PDFBool.True);
+    }
+  }
+  if (def.fieldType === "checkbox" && (def.checkboxStyle ?? "check") !== (def.originalCheckboxStyle ?? "check")) {
+    const caption = CHECKBOX_STYLE_TABLE[def.checkboxStyle ?? "check"]?.caption;
+    if (caption) {
+      for (const widget of widgets) {
+        let mk = widget.dict.get(PDFName.of("MK"));
+        if (!(mk instanceof PDFDict)) {
+          mk = pdfDoc.context.obj({});
+          widget.dict.set(PDFName.of("MK"), mk);
+        }
+        mk.set(PDFName.of("CA"), PDFString.of(caption));
+      }
+      form.acroForm.dict.set(PDFName.of("NeedAppearances"), PDFBool.True);
+    }
+  }
+}
+function rectsEqual(a, b) {
+  for (let i = 0; i < 4; i++) {
+    if (Math.abs((a[i] ?? 0) - (b[i] ?? 0)) > 0.01) return false;
+  }
+  return true;
+}
+function pickWidgetByRect(widgets, expected) {
+  const [ex1, ey1, ex2, ey2] = expected;
+  const ew = ex2 - ex1;
+  const eh = ey2 - ey1;
+  const tolerance = 0.5;
+  for (const w of widgets) {
+    const r = w.getRectangle();
+    if (Math.abs(r.x - ex1) <= tolerance && Math.abs(r.y - ey1) <= tolerance && Math.abs(r.width - ew) <= tolerance && Math.abs(r.height - eh) <= tolerance) return w;
+  }
+  return void 0;
+}
+async function createWidgetForDefinition(pdfDoc, def, fv, radioGroupCache) {
+  const form = pdfDoc.getForm();
+  const pageIndex = def.pageNumber - 1;
+  const pages = pdfDoc.getPages();
+  const page = pages[pageIndex];
+  if (!page) return;
+  const [x1, y1, x2, y2] = def.rect;
+  const box = {
+    x: x1,
+    y: y1,
+    width: Math.max(1, x2 - x1),
+    height: Math.max(1, y2 - y1)
+  };
+  switch (def.fieldType) {
+    case "text": {
+      const tf = form.createTextField(def.fieldName);
+      if (def.maxLen && def.maxLen > 0) tf.setMaxLength(def.maxLen);
+      if (def.multiLine) tf.enableMultiline();
+      const v = fv?.value;
+      if (typeof v === "string" && v !== "") tf.setText(v);
+      tf.addToPage(page, box);
+      applyFlags(tf, def);
+      break;
+    }
+    case "checkbox": {
+      const cb = form.createCheckBox(def.fieldName);
+      cb.addToPage(page, box);
+      if (fv?.value === true) cb.check();
+      applyFlags(cb, def);
+      applyCheckboxStyle(pdfDoc, cb, def);
+      break;
+    }
+    case "radio": {
+      let group = radioGroupCache.get(def.fieldName);
+      if (!group) {
+        try {
+          group = form.getRadioGroup(def.fieldName);
+        } catch {
+          group = form.createRadioGroup(def.fieldName);
+        }
+        radioGroupCache.set(def.fieldName, group);
+      }
+      const existingOptions = new Set(group.getOptions());
+      let optionValue = def.buttonValue || `Option_${existingOptions.size + 1}`;
+      if (existingOptions.has(optionValue)) {
+        let n = existingOptions.size + 1;
+        while (existingOptions.has(`Option_${n}`)) n += 1;
+        optionValue = `Option_${n}`;
+      }
+      group.addOptionToPage(optionValue, page, box);
+      if (typeof fv?.value === "string" && fv.value === optionValue) {
+        group.select(optionValue);
+      }
+      applyFlags(group, def);
+      break;
+    }
+    case "signature": {
+      await createSignatureField(pdfDoc, page, def, fv);
+      break;
+    }
+    case "dropdown": {
+      const labels = (def.options ?? []).map((o) => o.displayValue);
+      if (def.combo === false) {
+        const list = form.createOptionList(def.fieldName);
+        if (labels.length > 0) list.setOptions(labels);
+        list.addToPage(page, box);
+        if (def.multiSelect) list.enableMultiselect();
+        const v = fv?.value;
+        if (Array.isArray(v) && v.length > 0) list.select(v);
+        else if (typeof v === "string" && v) list.select(v);
+        applyFlags(list, def);
+      } else {
+        const dd = form.createDropdown(def.fieldName);
+        if (labels.length > 0) dd.setOptions(labels);
+        dd.addToPage(page, box);
+        if (def.editable) dd.enableEditing();
+        const v = fv?.value;
+        if (typeof v === "string" && v) dd.select(v);
+        else if (Array.isArray(v) && v[0]) dd.select(v[0]);
+        applyFlags(dd, def);
+      }
+      break;
+    }
+  }
+}
+function applyFlags(field, def) {
+  if (def.readOnly) field.enableReadOnly();
+  if (def.required) field.enableRequired();
+}
+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 buildSignaturePlaceholderAppearance(pdfDoc, width, height);
+  const mimeType = match[1] ?? "";
+  const base64 = match[2] ?? "";
+  const image = mimeType.includes("jpeg") || mimeType.includes("jpg") ? await pdfDoc.embedJpg(base64) : await pdfDoc.embedPng(base64);
+  const imgAspect = image.width / image.height;
+  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 } }
+  });
+  const stream = PDFRawStream.of(dict, new TextEncoder().encode(ops));
+  return pdfDoc.context.register(stream);
+}
 async function embedSignatureImage(pdfDoc, field) {
   const dataUrl = field.value;
   const match = dataUrl.match(/^data:(image\/[a-zA-Z0-9.+-]+);base64,(.+)$/);

package/dist/runtime/annotation/pdf-export/export.d.ts

@@ -1,4 +1,4 @@
-import { type IAnnotationStore, type FormFieldValue } from '../engine/types.js';
+import { type IAnnotationStore, type FormFieldDefinition, type FormFieldValue } from '../engine/types.js';
 export interface ExportPdfOptions {
     flatten?: boolean;
     download?: boolean;
@@ -10,9 +10,10 @@ interface ExportPdfParams {
     annotations: IAnnotationStore[];
     options?: ExportPdfOptions;
     formFieldValues?: FormFieldValue[];
+    placedFormFieldDefinitions?: FormFieldDefinition[];
     originalAnnotationIds?: Set<string>;
     modifiedAnnotationIds?: Set<string>;
     deletedAnnotationIds?: Set<string>;
 }
-export declare function exportAnnotationsToPdf({ pdfData, annotations, options, formFieldValues, originalAnnotationIds, modifiedAnnotationIds, deletedAnnotationIds, }: ExportPdfParams): Promise<Uint8Array>;
+export declare function exportAnnotationsToPdf({ pdfData, annotations, options, formFieldValues, placedFormFieldDefinitions, originalAnnotationIds, modifiedAnnotationIds, deletedAnnotationIds, }: ExportPdfParams): Promise<Uint8Array>;
 export {};

package/dist/runtime/annotation/pdf-export/export.js

@@ -198,6 +198,7 @@ export async function exportAnnotationsToPdf({
   annotations,
   options,
   formFieldValues,
+  placedFormFieldDefinitions,
   originalAnnotationIds,
   modifiedAnnotationIds,
   deletedAnnotationIds
@@ -205,8 +206,14 @@ export async function exportAnnotationsToPdf({
   const flatten = options?.flatten ?? false;
   const preserveOriginalAnnotations = options?.preserveOriginalAnnotations ?? false;
   const pdfDoc = await PDFDocument.load(toUint8Array(pdfData));
-  if (formFieldValues && formFieldValues.length > 0) {
-    await writeFormFieldsToPdf(pdfDoc, formFieldValues);
+  const hasValues = formFieldValues && formFieldValues.length > 0;
+  const hasPlaced = placedFormFieldDefinitions && placedFormFieldDefinitions.length > 0;
+  if (hasValues || hasPlaced) {
+    await writeFormFieldsToPdf(
+      pdfDoc,
+      formFieldValues ?? [],
+      placedFormFieldDefinitions ?? []
+    );
   }
   let annotationsToWrite = annotations;
   if (!preserveOriginalAnnotations) {

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;font-family:inherit;height:100%;line-height:normal;margin:0;outline:none;padding:1px 2px;resize:none;width:100%}.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{background:linear-gradient(180deg,#f0f0f0,#d0d0d0);border:1px solid rgba(0,0,0,.3);box-sizing:border-box;cursor:pointer;font-family:inherit;font-weight:600;height:100%;padding:2px 6px;text-align:center;width:100%}.kviewer-form-button:hover{background:linear-gradient(180deg,#e8e8e8,#c8c8c8)}.kviewer-form-button:active{background:linear-gradient(180deg,#c8c8c8,#d0d0d0)}.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/FormFieldLayer.d.vue.ts

@@ -5,6 +5,11 @@ type __VLS_Props = {
     pageHeight: number;
     pointerEvents: string;
     zIndex: number;
+    /** PDF user-space origin offsets (`view[0]`, `view[1]`). Forwarded to
+     *  FormFieldWrapper so /Rect coordinates can be mapped to canvas space
+     *  when the page's MediaBox is not at (0, 0). */
+    viewOffsetX?: number;
+    viewOffsetY?: number;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;