From 6e05c9513a93f5c05ec623bccea53e18eedb089c Mon Sep 17 00:00:00 2001
From: Sorin-nightz <sorin.muresan@nightz.app>
Date: Mon, 1 Dec 2025 14:46:25 +0200
Subject: [PATCH 1/3] xfa forms

---
 README.md                                 | 130 +++++++++
 src/api/PDFDocument.ts                    | 318 +++++++++++++++++++++-
 src/api/PDFDocumentOptions.ts             |   3 +-
 src/api/PDFJavaScriptAction.ts            | 133 +++++++++
 src/api/PDFPage.ts                        |  36 +++
 src/api/form/PDFField.ts                  |  59 ++++
 src/api/index.ts                          |   5 +
 tests/api/PDFDocument.spec.ts             |  83 ++++++
 tests/api/PDFDocumentXFA.spec.ts          | 138 ++++++++++
 tests/api/PDFJavaScriptAction.spec.ts     | 291 ++++++++++++++++++++
 tests/api/PDFPage.spec.ts                 | 100 +++++++
 tests/api/form/PDFFieldJavaScript.spec.ts | 294 ++++++++++++++++++++
 12 files changed, 1581 insertions(+), 9 deletions(-)
 create mode 100644 src/api/PDFJavaScriptAction.ts
 create mode 100644 tests/api/PDFDocumentXFA.spec.ts
 create mode 100644 tests/api/PDFJavaScriptAction.spec.ts
 create mode 100644 tests/api/form/PDFFieldJavaScript.spec.ts

diff --git a/README.md b/README.md
index fcb97e0f5..94319736d 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,9 @@ Install with: `npm install @cantoo/pdf-lib`
   - [Create Form](#create-form)
   - [Fill Form](#fill-form)
   - [Flatten Form](#flatten-form)
+  - [Work with XFA Forms](#work-with-xfa-forms)
+  - [Extract XFA JavaScript](#extract-xfa-javascript)
+  - [Modify XFA JavaScript](#modify-xfa-javascript)
   - [Copy Pages](#copy-pages)
   - [Embed PNG and JPEG Images](#embed-png-and-jpeg-images)
   - [Embed PDF Pages](#embed-pdf-pages)
@@ -104,6 +107,9 @@ Install with: `npm install @cantoo/pdf-lib`
 - Create forms
 - Fill forms
 - Flatten forms
+- Preserve XFA forms
+- Extract XFA JavaScript
+- Modify XFA JavaScript
 - Add Pages
 - Insert Pages
 - Remove Pages
@@ -732,6 +738,130 @@ const pdfBytes = await pdfDoc.save()
 //   • Rendered in an <iframe>
 ```
 
+### Work with XFA Forms
+
+XFA (XML Forms Architecture) forms are complex, dynamic PDF forms commonly used for government forms, tax documents, and enterprise applications. Unlike standard AcroForms, XFA forms embed their structure and JavaScript in XML format.
+
+**Important:** To preserve XFA forms when loading and saving PDFs, use the `preserveXFA` option:
+
+<!-- prettier-ignore -->
+```js
+import { PDFDocument } from 'pdf-lib'
+
+const xfaPdfBytes = ... // Load your XFA PDF
+
+// Load with XFA preservation
+const pdfDoc = await PDFDocument.load(xfaPdfBytes, { 
+  preserveXFA: true 
+})
+
+// Make modifications...
+
+// Save with XFA preservation
+const pdfBytes = await pdfDoc.save({ 
+  preserveXFA: true 
+})
+```
+
+**Note:** Without `preserveXFA: true`, XFA data will be removed when saving, which may cause the form to lose functionality.
+
+### Extract XFA JavaScript
+
+XFA forms often contain JavaScript for validation, calculations, and data import/export. You can extract all JavaScript from an XFA form:
+
+<!-- prettier-ignore -->
+```js
+import { PDFDocument } from 'pdf-lib'
+
+const xfaPdfBytes = ... // Load your XFA PDF
+
+// Load the PDF with XFA preservation
+const pdfDoc = await PDFDocument.load(xfaPdfBytes, { 
+  preserveXFA: true 
+})
+
+// Extract all XFA JavaScript
+const scripts = pdfDoc.getXFAJavaScripts()
+
+// Each script contains:
+// - field: The field name (e.g., 'Button1', 'TextField2')
+// - event: The event name (e.g., 'event__click', 'event__change')
+// - script: The JavaScript code
+
+console.log(`Found ${scripts.length} scripts`)
+
+scripts.forEach((script) => {
+  console.log(`Field: ${script.field}`)
+  console.log(`Event: ${script.event}`)
+  console.log(`Code: ${script.script}`)
+})
+
+// Find specific scripts
+const clickHandlers = scripts.filter(s => 
+  s.event.includes('click')
+)
+
+const validationScripts = scripts.filter(s => 
+  s.script.includes('validate') || s.script.includes('Validate')
+)
+```
+
+### Modify XFA JavaScript
+
+You can modify JavaScript in XFA forms to customize behavior, add logging, or fix issues:
+
+<!-- prettier-ignore -->
+```js
+import { PDFDocument } from 'pdf-lib'
+
+const xfaPdfBytes = ... // Load your XFA PDF
+
+// Load the PDF with XFA preservation
+const pdfDoc = await PDFDocument.load(xfaPdfBytes, { 
+  preserveXFA: true 
+})
+
+// Extract scripts to find what you want to modify
+const scripts = pdfDoc.getXFAJavaScripts()
+const importButton = scripts.find(s => s.field === 'ImportButton')
+
+if (importButton) {
+  // Modify the import button's click handler
+  const newScript = `
+    // Custom import handler
+    try {
+      console.println("Starting import...");
+      ${importButton.script}
+      console.println("Import completed!");
+    } catch(e) {
+      xfa.host.messageBox("Error: " + e.message);
+    }
+  `
+  
+  const success = pdfDoc.setXFAJavaScript(
+    'ImportButton',           // field name
+    importButton.event,       // event name (e.g., 'event__click')
+    newScript                 // new JavaScript code
+  )
+  
+  console.log(`Modification ${success ? 'succeeded' : 'failed'}`)
+}
+
+// Save with XFA preservation
+const pdfBytes = await pdfDoc.save({ 
+  preserveXFA: true 
+})
+
+// The modified PDF will have the updated JavaScript
+```
+
+**Use Cases:**
+- Add error handling to existing scripts
+- Modify validation rules
+- Add logging for debugging
+- Customize import/export behavior
+- Fix compatibility issues
+
 ### Copy Pages
 
 _This example produces [this PDF](assets/pdfs/examples/copy_pages.pdf)_ (when [this PDF](assets/pdfs/with_update_sections.pdf) is used for the `firstDonorPdfBytes` variable and [this PDF](assets/pdfs/with_large_page_count.pdf) is used for the `secondDonorPdfBytes` variable).
diff --git a/src/api/PDFDocument.ts b/src/api/PDFDocument.ts
index 447702742..0863ad5c1 100644
--- a/src/api/PDFDocument.ts
+++ b/src/api/PDFDocument.ts
@@ -172,6 +172,7 @@ export default class PDFDocument {
       capNumbers = false,
       password,
       forIncrementalUpdate = false,
+      preserveXFA = false,
     } = options;
 
     assertIs(pdf, 'pdf', ['string', Uint8Array, ArrayBuffer]);
@@ -217,6 +218,7 @@ export default class PDFDocument {
         true,
         updateMetadata,
         false,
+        preserveXFA,
       );
       if (forIncrementalUpdate) pdfDoc.takeSnapshot();
       return pdfDoc;
@@ -226,6 +228,7 @@ export default class PDFDocument {
         ignoreEncryption,
         updateMetadata,
         false,
+        preserveXFA,
       );
       if (forIncrementalUpdate) pdfDoc.takeSnapshot();
       return pdfDoc;
@@ -271,15 +274,18 @@ export default class PDFDocument {
   private readonly embeddedFiles: PDFEmbeddedFile[];
   private readonly javaScripts: PDFJavaScript[];
   private readonly isNewDocument: boolean;
+  private readonly preserveXFA: boolean;
 
   private constructor(
     context: PDFContext,
     ignoreEncryption: boolean,
     updateMetadata: boolean,
     isNewDocument = false,
+    preserveXFA = false,
   ) {
     assertIs(context, 'context', [[PDFContext, 'PDFContext']]);
     assertIs(ignoreEncryption, 'ignoreEncryption', ['boolean']);
+    assertIs(preserveXFA, 'preserveXFA', ['boolean']);
 
     this.context = context;
     this.catalog = context.lookup(context.trailerInfo.Root) as PDFCatalog;
@@ -299,6 +305,7 @@ export default class PDFDocument {
     this.embeddedPages = [];
     this.embeddedFiles = [];
     this.javaScripts = [];
+    this.preserveXFA = preserveXFA;
 
     if (!ignoreEncryption && this.isEncrypted) throw new EncryptedPDFError();
 
@@ -343,9 +350,9 @@ export default class PDFDocument {
    */
   getForm(): PDFForm {
     const form = this.formCache.access();
-    if (form.hasXFA()) {
+    if (form.hasXFA() && !this.preserveXFA) {
       console.warn(
-        'Removing XFA form data as pdf-lib does not support reading or writing XFA',
+        'Removing XFA form data as pdf-lib does not support reading or writing XFA. Set preserveXFA: true in load options to keep XFA data.',
       );
       form.deleteXFA();
     }
@@ -929,6 +936,301 @@ export default class PDFDocument {
     this.javaScripts.push(javaScript);
   }
 
+  /**
+   * Get all document-level JavaScript scripts from the document's Names dictionary.
+   * These scripts are executed when the document is opened.
+   * For example:
+   * ```js
+   * const scripts = pdfDoc.getDocumentJavaScripts()
+   * scripts.forEach(({ name, script }) => {
+   *   console.log(`Script "${name}":`, script)
+   * })
+   * ```
+   * @returns An array of objects containing script names and their JavaScript code.
+   */
+  getDocumentJavaScripts(): Array<{ name: string; script: string }> {
+    const scripts: Array<{ name: string; script: string }> = [];
+
+    const names = this.catalog.get(PDFName.of('Names'));
+    if (!names || !(names instanceof PDFDict || names instanceof PDFRef)) {
+      return scripts;
+    }
+
+    const namesDict =
+      names instanceof PDFRef ? this.context.lookup(names, PDFDict) : names;
+
+    const javascript = namesDict.get(PDFName.of('JavaScript'));
+    if (
+      !javascript ||
+      !(javascript instanceof PDFDict || javascript instanceof PDFRef)
+    ) {
+      return scripts;
+    }
+
+    const javascriptDict =
+      javascript instanceof PDFRef
+        ? this.context.lookup(javascript, PDFDict)
+        : javascript;
+
+    const jsNames = javascriptDict.get(PDFName.of('Names'));
+    if (!jsNames || !(jsNames instanceof PDFArray)) {
+      return scripts;
+    }
+
+    // Names array is a flat array of [name1, dict1, name2, dict2, ...]
+    for (let idx = 0; idx < jsNames.size(); idx += 2) {
+      const nameObj = jsNames.get(idx);
+      const actionObj = jsNames.get(idx + 1);
+
+      if (!nameObj || !actionObj) continue;
+
+      let name: string;
+      if (nameObj instanceof PDFString) {
+        name = nameObj.asString();
+      } else if (nameObj instanceof PDFHexString) {
+        name = nameObj.decodeText();
+      } else {
+        continue;
+      }
+
+      let actionDict: PDFDict;
+      if (actionObj instanceof PDFRef) {
+        actionDict = this.context.lookup(actionObj, PDFDict);
+      } else if (actionObj instanceof PDFDict) {
+        actionDict = actionObj;
+      } else {
+        continue;
+      }
+
+      const s = actionDict.lookup(PDFName.of('S'));
+      if (!(s instanceof PDFName) || s.asString() !== '/JavaScript') {
+        continue;
+      }
+
+      const js = actionDict.lookup(PDFName.of('JS'));
+      let script: string;
+      if (js instanceof PDFString) {
+        script = js.asString();
+      } else if (js instanceof PDFHexString) {
+        script = js.decodeText();
+      } else {
+        continue;
+      }
+
+      scripts.push({ name, script });
+    }
+
+    return scripts;
+  }
+
+  /**
+   * Get all JavaScript from XFA form template.
+   * XFA forms can contain JavaScript in <script> elements within the template XML.
+   * For example:
+   * ```js
+   * const xfaScripts = pdfDoc.getXFAJavaScripts()
+   * xfaScripts.forEach(({ field, event, script }) => {
+   *   console.log(`Field "${field}" on ${event}:`, script)
+   * })
+   * ```
+   * @returns An array of objects containing field names, events, and JavaScript code.
+   */
+  getXFAJavaScripts(): Array<{ field: string; event: string; script: string }> {
+    const scripts: Array<{ field: string; event: string; script: string }> = [];
+
+    const acroForm = this.catalog.get(PDFName.of('AcroForm'));
+    if (
+      !acroForm ||
+      !(acroForm instanceof PDFDict || acroForm instanceof PDFRef)
+    ) {
+      return scripts;
+    }
+
+    const formDict =
+      acroForm instanceof PDFRef
+        ? this.context.lookup(acroForm, PDFDict)
+        : acroForm;
+
+    const xfaObj = formDict.get(PDFName.of('XFA'));
+    if (!xfaObj) {
+      return scripts;
+    }
+
+    // XFA might be a reference to an array
+    const xfa = xfaObj instanceof PDFRef ? this.context.lookup(xfaObj) : xfaObj;
+
+    if (!(xfa instanceof PDFArray)) {
+      return scripts;
+    }
+
+    // XFA is an array of [name1, stream1, name2, stream2, ...]
+    for (let idx = 0; idx < xfa.size(); idx += 2) {
+      const nameObj = xfa.get(idx);
+      const streamObj = xfa.get(idx + 1);
+
+      if (!nameObj || !streamObj) continue;
+
+      let sectionName: string;
+      if (nameObj instanceof PDFString) {
+        sectionName = nameObj.asString();
+      } else if (nameObj instanceof PDFHexString) {
+        sectionName = nameObj.decodeText();
+      } else {
+        continue;
+      }
+
+      // We're interested in the 'template' section
+      if (sectionName !== 'template') continue;
+
+      const streamRef = streamObj instanceof PDFRef ? streamObj : null;
+      const stream = streamRef ? this.context.lookup(streamRef) : streamObj;
+
+      if (!stream || !(stream instanceof PDFRawStream)) continue;
+
+      const xmlBytes = decodePDFRawStream(stream).decode();
+      const xmlString = new TextDecoder().decode(xmlBytes);
+
+      // Extract JavaScript from <script> tags
+      // Note: XFA uses newlines in closing tags like </script\n>
+      const scriptMatches: Array<{
+        field: string;
+        event: string;
+        script: string;
+      }> = [];
+      const scriptPattern = /<script[^>]*>\s*([\s\S]*?)\s*<\/script\s*>/gi;
+      let scriptMatch;
+
+      while ((scriptMatch = scriptPattern.exec(xmlString)) !== null) {
+        const scriptCode = scriptMatch[1].trim();
+        if (!scriptCode) continue;
+
+        // Find the enclosing field and event by looking backwards
+        const beforeScript = xmlString.substring(
+          Math.max(0, scriptMatch.index - 2000),
+          scriptMatch.index,
+        );
+
+        // Find field name
+        const fieldNameMatch = beforeScript.match(
+          /<field[^>]*name="([^"]*)"[^>]*>/gi,
+        );
+        const fieldName = fieldNameMatch
+          ? fieldNameMatch[fieldNameMatch.length - 1].match(
+            /name="([^"]*)"/,
+          )?.[1] || 'unknown'
+          : 'unknown';
+
+        // Find event name
+        const eventNameMatch = beforeScript.match(
+          /<event[^>]*name="([^"]*)"[^>]*>/gi,
+        );
+        const eventName = eventNameMatch
+          ? eventNameMatch[eventNameMatch.length - 1].match(
+            /name="([^"]*)"/,
+          )?.[1] || 'unknown'
+          : 'unknown';
+
+        scriptMatches.push({
+          field: fieldName,
+          event: eventName,
+          script: scriptCode,
+        });
+      }
+
+      scripts.push(...scriptMatches);
+    }
+
+    return scripts;
+  }
+
+  /**
+   * Modify JavaScript in XFA form template for a specific field and event.
+   * For example:
+   * ```js
+   * pdfDoc.setXFAJavaScript('import', 'event__click', 'console.println("Modified!");')
+   * ```
+   * @param fieldName The name of the field containing the script
+   * @param eventName The name of the event (e.g., 'event__click', 'calculate')
+   * @param newScript The new JavaScript code to set
+   * @returns True if the script was found and updated, false otherwise
+   */
+  setXFAJavaScript(
+    fieldName: string,
+    eventName: string,
+    newScript: string,
+  ): boolean {
+    const acroForm = this.catalog.get(PDFName.of('AcroForm'));
+    if (
+      !acroForm ||
+      !(acroForm instanceof PDFDict || acroForm instanceof PDFRef)
+    ) {
+      return false;
+    }
+
+    const formDict =
+      acroForm instanceof PDFRef
+        ? this.context.lookup(acroForm, PDFDict)
+        : acroForm;
+
+    const xfa = formDict.get(PDFName.of('XFA'));
+    if (!xfa || !(xfa instanceof PDFArray)) {
+      return false;
+    }
+
+    // Find template section
+    for (let idx = 0; idx < xfa.size(); idx += 2) {
+      const nameObj = xfa.get(idx);
+      const streamObj = xfa.get(idx + 1);
+
+      if (!nameObj || !streamObj) continue;
+
+      let sectionName: string;
+      if (nameObj instanceof PDFString) {
+        sectionName = nameObj.asString();
+      } else if (nameObj instanceof PDFHexString) {
+        sectionName = nameObj.decodeText();
+      } else {
+        continue;
+      }
+
+      if (sectionName !== 'template') continue;
+
+      const streamRef = streamObj instanceof PDFRef ? streamObj : null;
+      const stream = streamRef ? this.context.lookup(streamRef) : streamObj;
+
+      if (!stream || !(stream instanceof PDFRawStream)) continue;
+
+      const xmlBytes = decodePDFRawStream(stream).decode();
+      let xmlString = new TextDecoder().decode(xmlBytes);
+
+      // Find and replace the script
+      // Note: XFA uses newlines in closing tags like </script\n>
+      const fieldPattern = new RegExp(
+        `(<field[^>]*name="${fieldName}"[^>]*>[\\s\\S]*?<event[^>]*name="${eventName}"[^>]*>[\\s\\S]*?<script[^>]*>)\\s*[\\s\\S]*?\\s*(<\\/script\\s*>)`,
+        'i',
+      );
+
+      const match = xmlString.match(fieldPattern);
+      if (!match) continue;
+
+      xmlString = xmlString.replace(fieldPattern, `$1\n${newScript}\n$2`);
+
+      // Create new stream with modified XML
+      const newXmlBytes = new TextEncoder().encode(xmlString);
+      const newStream = this.context.stream(newXmlBytes);
+
+      // Replace in XFA array
+      if (streamRef) {
+        this.context.delete(streamRef);
+      }
+      xfa.set(idx + 1, this.context.register(newStream));
+
+      return true;
+    }
+
+    return false;
+  }
+
   /**
    * Add an attachment to this document. Attachments are visible in the
    * "Attachments" panel of Adobe Acrobat and some other PDF readers. Any
@@ -1227,11 +1529,11 @@ export default class PDFDocument {
       const fontkit = this.assertFontkit();
       embedder = subset
         ? await CustomFontSubsetEmbedder.for(
-            fontkit,
-            bytes,
-            customName,
-            features,
-          )
+          fontkit,
+          bytes,
+          customName,
+          features,
+        )
         : await CustomFontEmbedder.for(fontkit, bytes, customName, features);
     } else {
       throw new TypeError(
@@ -1624,7 +1926,7 @@ export default class PDFDocument {
       ).serializeToBuffer();
       const result = new Uint8Array(
         this.context.pdfFileDetails.originalBytes!.byteLength +
-          increment.byteLength,
+        increment.byteLength,
       );
       result.set(this.context.pdfFileDetails.originalBytes!);
       result.set(
diff --git a/src/api/PDFDocumentOptions.ts b/src/api/PDFDocumentOptions.ts
index 058921876..685e1f619 100644
--- a/src/api/PDFDocumentOptions.ts
+++ b/src/api/PDFDocumentOptions.ts
@@ -8,7 +8,7 @@ export enum ParseSpeeds {
   Slow = 100,
 }
 
-export interface AttachmentOptions extends EmbeddedFileOptions {}
+export interface AttachmentOptions extends EmbeddedFileOptions { }
 
 export interface SaveOptions {
   useObjectStreams?: boolean;
@@ -36,6 +36,7 @@ export interface LoadOptions {
   capNumbers?: boolean;
   password?: string;
   forIncrementalUpdate?: boolean;
+  preserveXFA?: boolean;
 }
 
 export interface CreateOptions {
diff --git a/src/api/PDFJavaScriptAction.ts b/src/api/PDFJavaScriptAction.ts
new file mode 100644
index 000000000..fcca0855b
--- /dev/null
+++ b/src/api/PDFJavaScriptAction.ts
@@ -0,0 +1,133 @@
+import PDFDocument from './PDFDocument';
+import { PDFDict, PDFName, PDFString, PDFHexString, PDFRef } from '../core';
+
+/**
+ * Represents a JavaScript action extracted from a PDF.
+ * JavaScript actions can be attached to documents, pages, fields, and annotations.
+ */
+export default class PDFJavaScriptAction {
+  /** The underlying dictionary for this JavaScript action. */
+  readonly dict: PDFDict;
+
+  /** The document to which this action belongs. */
+  readonly doc: PDFDocument;
+
+  /** The reference to this action (if any). */
+  readonly ref?: PDFRef;
+
+  private constructor(dict: PDFDict, doc: PDFDocument, ref?: PDFRef) {
+    this.dict = dict;
+    this.doc = doc;
+    this.ref = ref;
+  }
+
+  /**
+   * Create a PDFJavaScriptAction from a dictionary.
+   * @param dict The action dictionary
+   * @param doc The document to which this action belongs
+   * @param ref The reference to this action (if any)
+   * @returns A PDFJavaScriptAction instance or undefined if not a JavaScript action
+   */
+  static of(
+    dict: PDFDict,
+    doc: PDFDocument,
+    ref?: PDFRef,
+  ): PDFJavaScriptAction | undefined {
+    const s = dict.lookup(PDFName.of('S'));
+    if (s instanceof PDFName && s.asString() === '/JavaScript') {
+      return new PDFJavaScriptAction(dict, doc, ref);
+    }
+    return undefined;
+  }
+
+  /**
+   * Get the JavaScript code from this action.
+   * @returns The JavaScript code as a string
+   */
+  getScript(): string | undefined {
+    const js = this.dict.lookup(PDFName.of('JS'));
+    if (js instanceof PDFString) {
+      return js.asString();
+    }
+    if (js instanceof PDFHexString) {
+      return js.decodeText();
+    }
+    return undefined;
+  }
+
+  /**
+   * Set the JavaScript code for this action.
+   * @param script The JavaScript code to set
+   */
+  setScript(script: string): void {
+    this.dict.set(PDFName.of('JS'), PDFHexString.fromText(script));
+  }
+}
+
+export interface JavaScriptActionMap {
+  /** Keystroke action (K) - executed when the user types in a field */
+  keystroke?: PDFJavaScriptAction;
+  /** Format action (F) - executed to format the field's value */
+  format?: PDFJavaScriptAction;
+  /** Validate action (V) - executed to validate the field's value */
+  validate?: PDFJavaScriptAction;
+  /** Calculate action (C) - executed to recalculate the field's value */
+  calculate?: PDFJavaScriptAction;
+  /** Mouse up action (U) - executed when mouse button is released */
+  mouseUp?: PDFJavaScriptAction;
+  /** Mouse down action (D) - executed when mouse button is pressed */
+  mouseDown?: PDFJavaScriptAction;
+  /** Mouse enter action (E) - executed when cursor enters annotation area */
+  mouseEnter?: PDFJavaScriptAction;
+  /** Mouse exit action (X) - executed when cursor exits annotation area */
+  mouseExit?: PDFJavaScriptAction;
+  /** Page open action (O) - executed when page is opened */
+  pageOpen?: PDFJavaScriptAction;
+  /** Page close action (C) - executed when page is closed */
+  pageClose?: PDFJavaScriptAction;
+  /** Focus action (Fo) - executed when annotation receives focus */
+  focus?: PDFJavaScriptAction;
+  /** Blur action (Bl) - executed when annotation loses focus */
+  blur?: PDFJavaScriptAction;
+}
+
+/**
+ * Extract JavaScript actions from an Additional Actions (AA) dictionary.
+ * @param aaDict The AA dictionary
+ * @param doc The document
+ * @returns A map of JavaScript actions
+ */
+export function extractAdditionalActions(
+  aaDict: PDFDict,
+  doc: PDFDocument,
+): JavaScriptActionMap {
+  const actions: JavaScriptActionMap = {};
+
+  const actionKeys = [
+    { key: 'K', prop: 'keystroke' as const },
+    { key: 'F', prop: 'format' as const },
+    { key: 'V', prop: 'validate' as const },
+    { key: 'C', prop: 'calculate' as const },
+    { key: 'U', prop: 'mouseUp' as const },
+    { key: 'D', prop: 'mouseDown' as const },
+    { key: 'E', prop: 'mouseEnter' as const },
+    { key: 'X', prop: 'mouseExit' as const },
+    { key: 'O', prop: 'pageOpen' as const },
+    { key: 'Fo', prop: 'focus' as const },
+    { key: 'Bl', prop: 'blur' as const },
+  ];
+
+  for (const { key, prop } of actionKeys) {
+    const actionObj = aaDict.get(PDFName.of(key));
+    if (actionObj instanceof PDFRef) {
+      const actionDict = aaDict.context.lookup(actionObj, PDFDict);
+      const action = PDFJavaScriptAction.of(actionDict, doc, actionObj);
+      if (action) actions[prop] = action;
+    } else if (actionObj instanceof PDFDict) {
+      const action = PDFJavaScriptAction.of(actionObj, doc);
+      if (action) actions[prop] = action;
+    }
+  }
+
+  return actions;
+}
diff --git a/src/api/PDFPage.ts b/src/api/PDFPage.ts
index 01893010a..2444cc389 100644
--- a/src/api/PDFPage.ts
+++ b/src/api/PDFPage.ts
@@ -21,6 +21,10 @@ import PDFEmbeddedPage from './PDFEmbeddedPage';
 import PDFFont from './PDFFont';
 import PDFImage from './PDFImage';
 import PDFSvg from './PDFSvg';
+import {
+  JavaScriptActionMap,
+  extractAdditionalActions,
+} from './PDFJavaScriptAction';
 import {
   PDFPageDrawCircleOptions,
   PDFPageDrawEllipseOptions,
@@ -706,6 +710,38 @@ export default class PDFPage {
     this.fontKey = this.node.newFontDictionary(this.font.name, this.font.ref);
   }
 
+  /**
+   * Get the JavaScript actions associated with this page.
+   * Returns a map of action types to JavaScript actions.
+   * For example:
+   * ```js
+   * const page = pdfDoc.getPage(0)
+   * const actions = page.getJavaScriptActions()
+   * if (actions && actions.pageOpen) {
+   *   console.log('Page open script:', actions.pageOpen.getScript())
+   * }
+   * if (actions && actions.pageClose) {
+   *   console.log('Page close script:', actions.pageClose.getScript())
+   * }
+   * ```
+   * @returns A map of JavaScript actions for this page, or undefined if none exist.
+   */
+  getJavaScriptActions(): JavaScriptActionMap | undefined {
+    const aaDict = this.node.get(PDFName.of('AA'));
+    if (!aaDict) return undefined;
+
+    let actualDict: PDFDict;
+    if (aaDict instanceof PDFRef) {
+      actualDict = this.doc.context.lookup(aaDict, PDFDict);
+    } else if (aaDict instanceof PDFDict) {
+      actualDict = aaDict;
+    } else {
+      return undefined;
+    }
+
+    return extractAdditionalActions(actualDict, this.doc);
+  }
+
   /**
    * Choose a default font size for this page. The default font size will be
    * used whenever text is drawn on this page and no font size is specified.
diff --git a/src/api/form/PDFField.ts b/src/api/form/PDFField.ts
index ce9977549..4649725fa 100644
--- a/src/api/form/PDFField.ts
+++ b/src/api/form/PDFField.ts
@@ -26,6 +26,10 @@ import { assertIs, assertMultiple, assertOrUndefined } from '../../utils';
 import { ImageAlignment } from '../image';
 import PDFImage from '../PDFImage';
 import { drawImage, rotateInPlace } from '../operations';
+import PDFJavaScriptAction, {
+  JavaScriptActionMap,
+  extractAdditionalActions,
+} from '../PDFJavaScriptAction';
 
 export interface FieldAppearanceOptions {
   x?: number;
@@ -248,6 +252,61 @@ export default class PDFField {
     this.acroField.setFlagTo(AcroFieldFlags.NoExport, true);
   }
 
+  /**
+   * Get the JavaScript actions associated with this field.
+   * Returns a map of action types to JavaScript actions.
+   * For example:
+   * ```js
+   * const field = form.getField('some.field')
+   * const actions = field.getJavaScriptActions()
+   * if (actions.keystroke) {
+   *   console.log('Keystroke script:', actions.keystroke.getScript())
+   * }
+   * if (actions.calculate) {
+   *   console.log('Calculate script:', actions.calculate.getScript())
+   * }
+   * ```
+   * @returns A map of JavaScript actions for this field, or undefined if none exist.
+   */
+  getJavaScriptActions(): JavaScriptActionMap | undefined {
+    const aaDict = this.acroField.dict.lookup(PDFName.of('AA'), PDFDict);
+    if (!aaDict) return undefined;
+    return extractAdditionalActions(aaDict, this.doc);
+  }
+
+  /**
+   * Get the default action (A) for this field.
+   * This is typically a submit or reset action, or can be a JavaScript action.
+   * For example:
+   * ```js
+   * const field = form.getField('some.field')
+   * const action = field.getAction()
+   * if (action) {
+   *   console.log('Action script:', action.getScript())
+   * }
+   * ```
+   * @returns The JavaScript action, or undefined if not a JavaScript action.
+   */
+  getAction(): PDFJavaScriptAction | undefined {
+    const actionObj = this.acroField.dict.get(PDFName.of('A'));
+    if (!actionObj) return undefined;
+
+    let actionDict: PDFDict;
+    if (actionObj instanceof PDFRef) {
+      actionDict = this.acroField.dict.context.lookup(actionObj, PDFDict);
+    } else if (actionObj instanceof PDFDict) {
+      actionDict = actionObj;
+    } else {
+      return undefined;
+    }
+
+    return PDFJavaScriptAction.of(
+      actionDict,
+      this.doc,
+      actionObj instanceof PDFRef ? actionObj : undefined,
+    );
+  }
+
   /** @ignore */
   needsAppearancesUpdate(): boolean {
     throw new MethodNotImplementedError(
diff --git a/src/api/index.ts b/src/api/index.ts
index b174c4e16..cf376084d 100644
--- a/src/api/index.ts
+++ b/src/api/index.ts
@@ -18,6 +18,11 @@ export { default as PDFImage } from './PDFImage';
 export { default as PDFPage } from './PDFPage';
 export { default as PDFEmbeddedPage } from './PDFEmbeddedPage';
 export { default as PDFJavaScript } from './PDFJavaScript';
+export {
+  default as PDFJavaScriptAction,
+  JavaScriptActionMap,
+  extractAdditionalActions,
+} from './PDFJavaScriptAction';
 export { default as Embeddable } from './Embeddable';
 export { default as PDFSvg } from './PDFSvg';
 export * from './snapshot';
diff --git a/tests/api/PDFDocument.spec.ts b/tests/api/PDFDocument.spec.ts
index da72f2f31..4fa4df4af 100644
--- a/tests/api/PDFDocument.spec.ts
+++ b/tests/api/PDFDocument.spec.ts
@@ -2015,4 +2015,87 @@ describe('PDFDocument', () => {
       await expect(noErrorFunc(1)).resolves.not.toThrowError();
     });
   });
+
+  describe('getDocumentJavaScripts() method', () => {
+    it('returns empty array when no JavaScript exists', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const scripts = pdfDoc.getDocumentJavaScripts();
+      expect(scripts).toEqual([]);
+    });
+
+    it('can extract document-level JavaScript', async () => {
+      const pdfDoc = await PDFDocument.create();
+      pdfDoc.addJavaScript('script1', 'console.println("Test 1");');
+      pdfDoc.addJavaScript('script2', 'console.println("Test 2");');
+
+      await pdfDoc.flush();
+
+      const scripts = pdfDoc.getDocumentJavaScripts();
+
+      expect(scripts).toHaveLength(2);
+      expect(scripts[0].name).toBe('script1');
+      expect(scripts[0].script).toBe('console.println("Test 1");');
+      expect(scripts[1].name).toBe('script2');
+      expect(scripts[1].script).toBe('console.println("Test 2");');
+    });
+
+    it('can extract JavaScript from loaded PDF', async () => {
+      const pdfDoc1 = await PDFDocument.create();
+      pdfDoc1.addJavaScript('test', 'console.show();');
+      const savedBytes = await pdfDoc1.save();
+
+      const pdfDoc2 = await PDFDocument.load(savedBytes);
+      const scripts = pdfDoc2.getDocumentJavaScripts();
+
+      expect(scripts).toHaveLength(1);
+      expect(scripts[0].name).toBe('test');
+      expect(scripts[0].script).toBe('console.show();');
+    });
+  });
+
+  describe('preserveXFA option', () => {
+    it('deletes XFA by default', async () => {
+      const pdfDoc1 = await PDFDocument.create();
+      const form = pdfDoc1.getForm();
+
+      // Manually add XFA data
+      form.acroForm.dict.set(
+        PDFName.of('XFA'),
+        PDFArray.withContext(pdfDoc1.context),
+      );
+
+      const savedBytes = await pdfDoc1.save();
+
+      // Load without preserveXFA
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+      const pdfDoc2 = await PDFDocument.load(savedBytes);
+      const form2 = pdfDoc2.getForm();
+
+      expect(form2.hasXFA()).toBe(false);
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Removing XFA form data'),
+      );
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('preserves XFA when preserveXFA is true', async () => {
+      const pdfDoc1 = await PDFDocument.create();
+      const form = pdfDoc1.getForm();
+
+      // Manually add XFA data
+      form.acroForm.dict.set(
+        PDFName.of('XFA'),
+        PDFArray.withContext(pdfDoc1.context),
+      );
+
+      const savedBytes = await pdfDoc1.save();
+
+      // Load with preserveXFA
+      const pdfDoc2 = await PDFDocument.load(savedBytes, { preserveXFA: true });
+      const form2 = pdfDoc2.getForm();
+
+      expect(form2.hasXFA()).toBe(true);
+    });
+  });
 });
diff --git a/tests/api/PDFDocumentXFA.spec.ts b/tests/api/PDFDocumentXFA.spec.ts
new file mode 100644
index 000000000..97336a5a6
--- /dev/null
+++ b/tests/api/PDFDocumentXFA.spec.ts
@@ -0,0 +1,138 @@
+import fs from 'fs';
+import { PDFDocument } from 'src/index';
+
+const toUint8Array = (buf: Buffer) => new Uint8Array(buf);
+
+describe('PDFDocument - XFA JavaScript', () => {
+  const xfaPdfPath = 'assets/pdfs/with_xfa_fields.pdf';
+
+  it('can extract XFA JavaScript from template', async () => {
+    const pdfBytes = toUint8Array(fs.readFileSync(xfaPdfPath));
+    const pdfDoc = await PDFDocument.load(pdfBytes, { preserveXFA: true });
+
+    const xfaScripts = pdfDoc.getXFAJavaScripts();
+
+    expect(xfaScripts).toBeInstanceOf(Array);
+    expect(xfaScripts.length).toBeGreaterThan(0);
+
+    // Check structure of returned scripts
+    xfaScripts.forEach((script) => {
+      expect(script).toHaveProperty('field');
+      expect(script).toHaveProperty('event');
+      expect(script).toHaveProperty('script');
+      expect(typeof script.field).toBe('string');
+      expect(typeof script.event).toBe('string');
+      expect(typeof script.script).toBe('string');
+    });
+
+    // Look for known checkbox fields
+    const checkbox = xfaScripts.find((s) => s.field === 'c1_01');
+
+    expect(checkbox).toBeDefined();
+    expect(checkbox!.event).toBe('event__mouseUp');
+    expect(checkbox!.script).toContain('getField');
+  });
+
+  it('returns empty array for non-XFA PDFs', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const xfaScripts = pdfDoc.getXFAJavaScripts();
+
+    expect(xfaScripts).toBeInstanceOf(Array);
+    expect(xfaScripts.length).toBe(0);
+  });
+
+  it('can modify XFA JavaScript', async () => {
+    const pdfBytes = toUint8Array(fs.readFileSync(xfaPdfPath));
+    const pdfDoc = await PDFDocument.load(pdfBytes, { preserveXFA: true });
+
+    const originalScripts = pdfDoc.getXFAJavaScripts();
+    const checkbox = originalScripts.find((s) => s.field === 'c1_01');
+
+    expect(checkbox).toBeDefined();
+
+    const newScript = 'console.println("Modified checkbox script");';
+    const result = pdfDoc.setXFAJavaScript('c1_01', checkbox!.event, newScript);
+
+    expect(result).toBe(true);
+
+    // Verify the modification
+    const modifiedScripts = pdfDoc.getXFAJavaScripts();
+    const modifiedCheckbox = modifiedScripts.find(
+      (s) =>
+        s.field === 'c1_01' && s.script.includes('Modified checkbox script'),
+    );
+
+    expect(modifiedCheckbox).toBeDefined();
+    expect(modifiedCheckbox!.script).toContain(newScript);
+  });
+
+  it('returns false when modifying non-existent field', async () => {
+    const pdfBytes = toUint8Array(fs.readFileSync(xfaPdfPath));
+    const pdfDoc = await PDFDocument.load(pdfBytes, { preserveXFA: true });
+
+    const result = pdfDoc.setXFAJavaScript(
+      'nonexistent',
+      'event__click',
+      'test',
+    );
+
+    expect(result).toBe(false);
+  });
+
+  it('preserves XFA structure after modification', async () => {
+    const pdfBytes = toUint8Array(fs.readFileSync(xfaPdfPath));
+    const pdfDoc = await PDFDocument.load(pdfBytes, { preserveXFA: true });
+
+    const originalCount = pdfDoc.getXFAJavaScripts().length;
+
+    pdfDoc.setXFAJavaScript('c1_01', 'event__mouseUp', 'test();');
+
+    const modifiedCount = pdfDoc.getXFAJavaScripts().length;
+
+    // Script count should remain the same
+    expect(modifiedCount).toBe(originalCount);
+  });
+
+  it('can save and reload PDF with modified XFA JavaScript', async () => {
+    const pdfBytes = toUint8Array(fs.readFileSync(xfaPdfPath));
+    const pdfDoc = await PDFDocument.load(pdfBytes, { preserveXFA: true });
+
+    const newScript = 'xfa.host.messageBox("Test modification");';
+    pdfDoc.setXFAJavaScript('c1_01', 'event__mouseUp', newScript);
+
+    const savedBytes = await pdfDoc.save();
+
+    // Reload and verify
+    const reloadedDoc = await PDFDocument.load(savedBytes, {
+      preserveXFA: true,
+    });
+    const scripts = reloadedDoc.getXFAJavaScripts();
+    const checkbox = scripts.find(
+      (s) => s.field === 'c1_01' && s.script.includes('Test modification'),
+    );
+
+    expect(checkbox).toBeDefined();
+    expect(checkbox!.script).toContain(newScript);
+  });
+
+  it('extracts scripts from multiple events on same field', async () => {
+    const pdfBytes = toUint8Array(fs.readFileSync(xfaPdfPath));
+    const pdfDoc = await PDFDocument.load(pdfBytes, { preserveXFA: true });
+
+    const xfaScripts = pdfDoc.getXFAJavaScripts();
+
+    // Group by field name
+    const fieldScripts = new Map<string, number>();
+    xfaScripts.forEach((script) => {
+      const count = fieldScripts.get(script.field) || 0;
+      fieldScripts.set(script.field, count + 1);
+    });
+
+    // Some fields may have multiple events (c1_01, c2_05, etc. have 2 event__mouseUp events)
+    const multiEventFields = Array.from(fieldScripts.entries()).filter(
+      ([_, count]) => count > 1,
+    );
+
+    expect(multiEventFields.length).toBeGreaterThan(0);
+  });
+});
diff --git a/tests/api/PDFJavaScriptAction.spec.ts b/tests/api/PDFJavaScriptAction.spec.ts
new file mode 100644
index 000000000..5e3603300
--- /dev/null
+++ b/tests/api/PDFJavaScriptAction.spec.ts
@@ -0,0 +1,291 @@
+import { PDFHexString, PDFString } from '../../src/core';
+import PDFDocument from '../../src/api/PDFDocument';
+import PDFJavaScriptAction, {
+  extractAdditionalActions,
+} from '../../src/api/PDFJavaScriptAction';
+
+describe('PDFJavaScriptAction', () => {
+  it('can be created from a JavaScript action dictionary', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const actionDict = context.obj({
+      Type: 'Action',
+      S: 'JavaScript',
+      JS: PDFHexString.fromText('console.println("Hello");'),
+    });
+
+    const ref = context.register(actionDict);
+    const action = PDFJavaScriptAction.of(actionDict, pdfDoc, ref);
+
+    expect(action).toBeInstanceOf(PDFJavaScriptAction);
+    expect(action?.dict).toBe(actionDict);
+    expect(action?.doc).toBe(pdfDoc);
+    expect(action?.ref).toBe(ref);
+  });
+
+  it('returns undefined for non-JavaScript actions', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const actionDict = context.obj({
+      Type: 'Action',
+      S: 'SubmitForm',
+      F: 'http://example.com/submit',
+    });
+
+    const action = PDFJavaScriptAction.of(actionDict, pdfDoc);
+
+    expect(action).toBeUndefined();
+  });
+
+  it('can get script from PDFString', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const script = 'console.println("Test");';
+    const actionDict = context.obj({
+      S: 'JavaScript',
+      JS: PDFString.of(script),
+    });
+
+    const action = PDFJavaScriptAction.of(actionDict, pdfDoc);
+    expect(action?.getScript()).toBe(script);
+  });
+
+  it('can get script from PDFHexString', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const script = 'console.println("Test");';
+    const actionDict = context.obj({
+      S: 'JavaScript',
+      JS: PDFHexString.fromText(script),
+    });
+
+    const action = PDFJavaScriptAction.of(actionDict, pdfDoc);
+    expect(action?.getScript()).toBe(script);
+  });
+
+  it('can set script', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const actionDict = context.obj({
+      S: 'JavaScript',
+      JS: PDFString.of('old script'),
+    });
+
+    const action = PDFJavaScriptAction.of(actionDict, pdfDoc);
+    expect(action?.getScript()).toBe('old script');
+
+    action?.setScript('new script');
+    expect(action?.getScript()).toBe('new script');
+  });
+
+  it('returns undefined when JS field is missing', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const actionDict = context.obj({
+      S: 'JavaScript',
+    });
+
+    const action = PDFJavaScriptAction.of(actionDict, pdfDoc);
+    expect(action?.getScript()).toBeUndefined();
+  });
+});
+
+describe('extractAdditionalActions', () => {
+  it('can extract keystroke action', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      K: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('keystroke script'),
+      }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.keystroke).toBeInstanceOf(PDFJavaScriptAction);
+    expect(actions.keystroke?.getScript()).toBe('keystroke script');
+  });
+
+  it('can extract format action', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      F: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('format script'),
+      }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.format).toBeInstanceOf(PDFJavaScriptAction);
+    expect(actions.format?.getScript()).toBe('format script');
+  });
+
+  it('can extract validate action', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      V: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('validate script'),
+      }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.validate).toBeInstanceOf(PDFJavaScriptAction);
+    expect(actions.validate?.getScript()).toBe('validate script');
+  });
+
+  it('can extract calculate action', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      C: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('calculate script'),
+      }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.calculate).toBeInstanceOf(PDFJavaScriptAction);
+    expect(actions.calculate?.getScript()).toBe('calculate script');
+  });
+
+  it('can extract multiple actions', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      K: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('keystroke'),
+      }),
+      F: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('format'),
+      }),
+      V: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('validate'),
+      }),
+      C: context.obj({
+        S: 'JavaScript',
+        JS: PDFString.of('calculate'),
+      }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.keystroke?.getScript()).toBe('keystroke');
+    expect(actions.format?.getScript()).toBe('format');
+    expect(actions.validate?.getScript()).toBe('validate');
+    expect(actions.calculate?.getScript()).toBe('calculate');
+  });
+
+  it('can extract actions from indirect references', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const actionDict = context.obj({
+      S: 'JavaScript',
+      JS: PDFString.of('referenced script'),
+    });
+    const actionRef = context.register(actionDict);
+
+    const aaDict = context.obj({
+      K: actionRef,
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.keystroke?.getScript()).toBe('referenced script');
+  });
+
+  it('can extract mouse actions', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      U: context.obj({ S: 'JavaScript', JS: PDFString.of('mouseUp') }),
+      D: context.obj({ S: 'JavaScript', JS: PDFString.of('mouseDown') }),
+      E: context.obj({ S: 'JavaScript', JS: PDFString.of('mouseEnter') }),
+      X: context.obj({ S: 'JavaScript', JS: PDFString.of('mouseExit') }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.mouseUp?.getScript()).toBe('mouseUp');
+    expect(actions.mouseDown?.getScript()).toBe('mouseDown');
+    expect(actions.mouseEnter?.getScript()).toBe('mouseEnter');
+    expect(actions.mouseExit?.getScript()).toBe('mouseExit');
+  });
+
+  it('can extract focus actions', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      Fo: context.obj({ S: 'JavaScript', JS: PDFString.of('focus') }),
+      Bl: context.obj({ S: 'JavaScript', JS: PDFString.of('blur') }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.focus?.getScript()).toBe('focus');
+    expect(actions.blur?.getScript()).toBe('blur');
+  });
+
+  it('can extract page actions', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      O: context.obj({ S: 'JavaScript', JS: PDFString.of('pageOpen') }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.pageOpen?.getScript()).toBe('pageOpen');
+  });
+
+  it('returns empty object when no actions exist', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({});
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(Object.keys(actions).length).toBe(0);
+  });
+
+  it('ignores non-JavaScript actions', async () => {
+    const pdfDoc = await PDFDocument.create();
+    const context = pdfDoc.context;
+
+    const aaDict = context.obj({
+      K: context.obj({
+        S: 'SubmitForm',
+        F: 'http://example.com',
+      }),
+    });
+
+    const actions = extractAdditionalActions(aaDict, pdfDoc);
+
+    expect(actions.keystroke).toBeUndefined();
+  });
+});
diff --git a/tests/api/PDFPage.spec.ts b/tests/api/PDFPage.spec.ts
index 00009ee6a..f6168cd0b 100644
--- a/tests/api/PDFPage.spec.ts
+++ b/tests/api/PDFPage.spec.ts
@@ -186,4 +186,104 @@ describe('PDFDocument', () => {
     expect(key1).not.toEqual(key2);
     expect(page2.node.normalizedEntries().Font.keys()).toEqual([key1, key2]);
   });
+
+  describe('getJavaScriptActions() method', () => {
+    it('returns undefined when page has no JavaScript actions', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const page = pdfDoc.addPage();
+
+      const actions = page.getJavaScriptActions();
+      expect(actions).toBeUndefined();
+    });
+
+    it('can extract page open action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const page = pdfDoc.addPage();
+      const context = pdfDoc.context;
+
+      // Manually add AA dictionary with page open action
+      const aaDict = context.obj({
+        O: context.obj({
+          S: 'JavaScript',
+          JS: 'console.println("Page opened");',
+        }),
+      });
+      page.node.set(PDFName.of('AA'), aaDict);
+
+      const actions = page.getJavaScriptActions();
+
+      expect(actions).toBeDefined();
+      expect(actions?.pageOpen).toBeDefined();
+      expect(actions?.pageOpen?.getScript()).toBe(
+        'console.println("Page opened");',
+      );
+    });
+
+    it('can extract page close action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const page = pdfDoc.addPage();
+      const context = pdfDoc.context;
+
+      // Manually add AA dictionary with page close action
+      const aaDict = context.obj({
+        C: context.obj({
+          S: 'JavaScript',
+          JS: 'console.println("Page closed");',
+        }),
+      });
+      page.node.set(PDFName.of('AA'), aaDict);
+
+      const actions = page.getJavaScriptActions();
+
+      expect(actions).toBeDefined();
+      expect(actions?.pageClose).toBeDefined();
+      expect(actions?.pageClose?.getScript()).toBe(
+        'console.println("Page closed");',
+      );
+    });
+
+    it('can extract multiple page actions', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const page = pdfDoc.addPage();
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        O: context.obj({
+          S: 'JavaScript',
+          JS: 'console.println("Opened");',
+        }),
+        C: context.obj({
+          S: 'JavaScript',
+          JS: 'console.println("Closed");',
+        }),
+      });
+      page.node.set(PDFName.of('AA'), aaDict);
+
+      const actions = page.getJavaScriptActions();
+
+      expect(actions?.pageOpen?.getScript()).toBe('console.println("Opened");');
+      expect(actions?.pageClose?.getScript()).toBe(
+        'console.println("Closed");',
+      );
+    });
+
+    it('handles AA as indirect reference', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const page = pdfDoc.addPage();
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        O: context.obj({
+          S: 'JavaScript',
+          JS: 'console.println("Test");',
+        }),
+      });
+      const aaRef = context.register(aaDict);
+      page.node.set(PDFName.of('AA'), aaRef);
+
+      const actions = page.getJavaScriptActions();
+
+      expect(actions?.pageOpen?.getScript()).toBe('console.println("Test");');
+    });
+  });
 });
diff --git a/tests/api/form/PDFFieldJavaScript.spec.ts b/tests/api/form/PDFFieldJavaScript.spec.ts
new file mode 100644
index 000000000..c0728b485
--- /dev/null
+++ b/tests/api/form/PDFFieldJavaScript.spec.ts
@@ -0,0 +1,294 @@
+import { PDFDocument, PDFName } from '../../../src/index';
+
+describe('PDFField JavaScript Actions', () => {
+  describe('getJavaScriptActions() method', () => {
+    it('returns undefined when field has no JavaScript actions', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+
+      const actions = field.getJavaScriptActions();
+      expect(actions).toBeUndefined();
+    });
+
+    it('can extract keystroke action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      // Manually add AA dictionary with keystroke action
+      const aaDict = context.obj({
+        K: context.obj({
+          S: 'JavaScript',
+          JS: 'event.change = event.change.toUpperCase();',
+        }),
+      });
+      field.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      const actions = field.getJavaScriptActions();
+
+      expect(actions).toBeDefined();
+      expect(actions?.keystroke).toBeDefined();
+      expect(actions?.keystroke?.getScript()).toBe(
+        'event.change = event.change.toUpperCase();',
+      );
+    });
+
+    it('can extract format action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        F: context.obj({
+          S: 'JavaScript',
+          JS: 'AFNumber_Format(2, 0, 0, 0, "$", true);',
+        }),
+      });
+      field.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      const actions = field.getJavaScriptActions();
+
+      expect(actions?.format).toBeDefined();
+      expect(actions?.format?.getScript()).toBe(
+        'AFNumber_Format(2, 0, 0, 0, "$", true);',
+      );
+    });
+
+    it('can extract validate action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        V: context.obj({
+          S: 'JavaScript',
+          JS: 'if (event.value < 0) event.rc = false;',
+        }),
+      });
+      field.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      const actions = field.getJavaScriptActions();
+
+      expect(actions?.validate).toBeDefined();
+      expect(actions?.validate?.getScript()).toBe(
+        'if (event.value < 0) event.rc = false;',
+      );
+    });
+
+    it('can extract calculate action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('total');
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        C: context.obj({
+          S: 'JavaScript',
+          JS: 'var a = this.getField("price").value; var b = this.getField("quantity").value; event.value = a * b;',
+        }),
+      });
+      field.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      const actions = field.getJavaScriptActions();
+
+      expect(actions?.calculate).toBeDefined();
+      expect(actions?.calculate?.getScript()).toContain('event.value = a * b');
+    });
+
+    it('can extract multiple actions from same field', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        K: context.obj({
+          S: 'JavaScript',
+          JS: 'keystroke script',
+        }),
+        F: context.obj({
+          S: 'JavaScript',
+          JS: 'format script',
+        }),
+        V: context.obj({
+          S: 'JavaScript',
+          JS: 'validate script',
+        }),
+        C: context.obj({
+          S: 'JavaScript',
+          JS: 'calculate script',
+        }),
+      });
+      field.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      const actions = field.getJavaScriptActions();
+
+      expect(actions?.keystroke?.getScript()).toBe('keystroke script');
+      expect(actions?.format?.getScript()).toBe('format script');
+      expect(actions?.validate?.getScript()).toBe('validate script');
+      expect(actions?.calculate?.getScript()).toBe('calculate script');
+    });
+
+    it('can extract mouse actions', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        U: context.obj({ S: 'JavaScript', JS: 'mouseUp' }),
+        D: context.obj({ S: 'JavaScript', JS: 'mouseDown' }),
+        E: context.obj({ S: 'JavaScript', JS: 'mouseEnter' }),
+        X: context.obj({ S: 'JavaScript', JS: 'mouseExit' }),
+      });
+      field.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      const actions = field.getJavaScriptActions();
+
+      expect(actions?.mouseUp?.getScript()).toBe('mouseUp');
+      expect(actions?.mouseDown?.getScript()).toBe('mouseDown');
+      expect(actions?.mouseEnter?.getScript()).toBe('mouseEnter');
+      expect(actions?.mouseExit?.getScript()).toBe('mouseExit');
+    });
+
+    it('can extract focus actions', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const aaDict = context.obj({
+        Fo: context.obj({ S: 'JavaScript', JS: 'focus script' }),
+        Bl: context.obj({ S: 'JavaScript', JS: 'blur script' }),
+      });
+      field.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      const actions = field.getJavaScriptActions();
+
+      expect(actions?.focus?.getScript()).toBe('focus script');
+      expect(actions?.blur?.getScript()).toBe('blur script');
+    });
+  });
+
+  describe('getAction() method', () => {
+    it('returns undefined when field has no default action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+
+      const action = field.getAction();
+      expect(action).toBeUndefined();
+    });
+
+    it('can extract default JavaScript action', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const actionDict = context.obj({
+        S: 'JavaScript',
+        JS: 'console.println("Default action");',
+      });
+      field.acroField.dict.set(PDFName.of('A'), actionDict);
+
+      const action = field.getAction();
+
+      expect(action).toBeDefined();
+      expect(action?.getScript()).toBe('console.println("Default action");');
+    });
+
+    it('returns undefined for non-JavaScript actions', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const actionDict = context.obj({
+        S: 'SubmitForm',
+        F: 'http://example.com/submit',
+      });
+      field.acroField.dict.set(PDFName.of('A'), actionDict);
+
+      const action = field.getAction();
+      expect(action).toBeUndefined();
+    });
+
+    it('handles action as indirect reference', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('test');
+      const context = pdfDoc.context;
+
+      const actionDict = context.obj({
+        S: 'JavaScript',
+        JS: 'referenced action',
+      });
+      const actionRef = context.register(actionDict);
+      field.acroField.dict.set(PDFName.of('A'), actionRef);
+
+      const action = field.getAction();
+
+      expect(action?.getScript()).toBe('referenced action');
+    });
+  });
+
+  describe('Integration test - field with multiple scripts', () => {
+    it('can extract all scripts from a complex form field', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const taxField = form.createTextField('tax');
+      const context = pdfDoc.context;
+
+      // Add AA dictionary with multiple actions
+      const aaDict = context.obj({
+        K: context.obj({
+          S: 'JavaScript',
+          JS: 'if (event.willCommit) { event.value = event.value.replace(/[^0-9.]/g, ""); }',
+        }),
+        F: context.obj({
+          S: 'JavaScript',
+          JS: 'AFNumber_Format(2, 0, 0, 0, "$", true);',
+        }),
+        V: context.obj({
+          S: 'JavaScript',
+          JS: 'if (event.value < 0 || event.value > 100) { app.alert("Invalid tax amount"); event.rc = false; }',
+        }),
+        C: context.obj({
+          S: 'JavaScript',
+          JS: 'var subtotal = this.getField("subtotal").value; event.value = subtotal * 0.08;',
+        }),
+      });
+      taxField.acroField.dict.set(PDFName.of('AA'), aaDict);
+
+      // Add default action
+      const defaultAction = context.obj({
+        S: 'JavaScript',
+        JS: 'console.println("Field changed");',
+      });
+      taxField.acroField.dict.set(PDFName.of('A'), defaultAction);
+
+      const actions = taxField.getJavaScriptActions();
+      const action = taxField.getAction();
+
+      // Verify all scripts are extracted
+      expect(actions).toBeDefined();
+      expect(actions?.keystroke).toBeDefined();
+      expect(actions?.format).toBeDefined();
+      expect(actions?.validate).toBeDefined();
+      expect(actions?.calculate).toBeDefined();
+      expect(action).toBeDefined();
+
+      // Verify script content
+      expect(actions?.keystroke?.getScript()).toContain('event.value.replace');
+      expect(actions?.format?.getScript()).toContain('AFNumber_Format');
+      expect(actions?.validate?.getScript()).toContain('app.alert');
+      expect(actions?.calculate?.getScript()).toContain('subtotal * 0.08');
+      expect(action?.getScript()).toBe('console.println("Field changed");');
+    });
+  });
+});

From 341b29eb30a2e7a7f0af542cf7cd215457b153b1 Mon Sep 17 00:00:00 2001
From: Sorin-nightz <sorin.muresan@nightz.app>
Date: Mon, 1 Dec 2025 17:24:02 +0200
Subject: [PATCH 2/3] xfa forms

---
 src/api/PDFJavaScriptAction.ts | 50 +++++++++++++++++++++++++++++-----
 src/api/form/PDFField.ts       | 14 ++++++++--
 2 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/src/api/PDFJavaScriptAction.ts b/src/api/PDFJavaScriptAction.ts
index fcca0855b..dde7d8c96 100644
--- a/src/api/PDFJavaScriptAction.ts
+++ b/src/api/PDFJavaScriptAction.ts
@@ -33,8 +33,15 @@ export default class PDFJavaScriptAction {
     doc: PDFDocument,
     ref?: PDFRef,
   ): PDFJavaScriptAction | undefined {
-    const s = dict.lookup(PDFName.of('S'));
-    if (s instanceof PDFName && s.asString() === '/JavaScript') {
+    const s = dict.get(PDFName.of('S'));
+    let sName: PDFName | undefined;
+    if (s instanceof PDFRef) {
+      sName = dict.context.lookup(s) as PDFName;
+    } else if (s instanceof PDFName) {
+      sName = s;
+    }
+
+    if (sName && sName.asString() === '/JavaScript') {
       return new PDFJavaScriptAction(dict, doc, ref);
     }
     return undefined;
@@ -45,12 +52,40 @@ export default class PDFJavaScriptAction {
    * @returns The JavaScript code as a string
    */
   getScript(): string | undefined {
-    const js = this.dict.lookup(PDFName.of('JS'));
-    if (js instanceof PDFString) {
-      return js.asString();
+    const js = this.dict.get(PDFName.of('JS'));
+    let jsValue: PDFString | PDFHexString | PDFName | undefined;
+
+    if (js instanceof PDFRef) {
+      jsValue = this.dict.context.lookup(js) as
+        | PDFString
+        | PDFHexString
+        | PDFName;
+    } else if (
+      js instanceof PDFString ||
+      js instanceof PDFHexString ||
+      js instanceof PDFName
+    ) {
+      jsValue = js;
+    }
+
+    if (jsValue instanceof PDFString) {
+      return jsValue.asString();
+    }
+    if (jsValue instanceof PDFHexString) {
+      return jsValue.decodeText();
     }
-    if (js instanceof PDFHexString) {
-      return js.decodeText();
+    if (jsValue instanceof PDFName) {
+      // Handle case where the value was created with context.obj() using a string literal
+      // PDFName.asString() returns the encoded name with leading slash and hex-encoded special chars
+      // We need to remove the slash and decode the hex sequences
+      const nameStr = jsValue.asString();
+      const withoutSlash = nameStr.startsWith('/')
+        ? nameStr.substring(1)
+        : nameStr;
+      // Decode hex sequences like #28 -> (
+      return withoutSlash.replace(/#([\dA-Fa-f]{2})/g, (_, hex) =>
+        String.fromCharCode(parseInt(hex, 16)),
+      );
     }
     return undefined;
   }
@@ -113,6 +148,7 @@ export function extractAdditionalActions(
     { key: 'E', prop: 'mouseEnter' as const },
     { key: 'X', prop: 'mouseExit' as const },
     { key: 'O', prop: 'pageOpen' as const },
+    { key: 'C', prop: 'pageClose' as const }, // Note: C is used for both calculate (fields) and pageClose (pages)
     { key: 'Fo', prop: 'focus' as const },
     { key: 'Bl', prop: 'blur' as const },
   ];
diff --git a/src/api/form/PDFField.ts b/src/api/form/PDFField.ts
index 4649725fa..ab2432366 100644
--- a/src/api/form/PDFField.ts
+++ b/src/api/form/PDFField.ts
@@ -269,8 +269,18 @@ export default class PDFField {
    * @returns A map of JavaScript actions for this field, or undefined if none exist.
    */
   getJavaScriptActions(): JavaScriptActionMap | undefined {
-    const aaDict = this.acroField.dict.lookup(PDFName.of('AA'), PDFDict);
-    if (!aaDict) return undefined;
+    const aaEntry = this.acroField.dict.get(PDFName.of('AA'));
+    if (!aaEntry) return undefined;
+
+    let aaDict: PDFDict;
+    if (aaEntry instanceof PDFRef) {
+      aaDict = this.doc.context.lookup(aaEntry, PDFDict);
+    } else if (aaEntry instanceof PDFDict) {
+      aaDict = aaEntry;
+    } else {
+      return undefined;
+    }
+
     return extractAdditionalActions(aaDict, this.doc);
   }
 

From 80674a298216dbc0856cdddfbcc6c0a90778a84c Mon Sep 17 00:00:00 2001
From: Sorin-nightz <sorin.muresan@nightz.app>
Date: Thu, 12 Mar 2026 21:39:15 +0200
Subject: [PATCH 3/3] addresed xfa forms review

---
 README.md                        |  67 +++++--
 src/api/PDFDocument.ts           | 307 ++++++++++++++++++-------------
 src/api/PDFJavaScriptAction.ts   |  12 +-
 tests/api/PDFDocumentXFA.spec.ts |  16 +-
 4 files changed, 234 insertions(+), 168 deletions(-)

diff --git a/README.md b/README.md
index 94319736d..058bcfd8e 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,7 @@ Install with: `npm install @cantoo/pdf-lib`
   - [Work with XFA Forms](#work-with-xfa-forms)
   - [Extract XFA JavaScript](#extract-xfa-javascript)
   - [Modify XFA JavaScript](#modify-xfa-javascript)
+  - [Extract Document JavaScript](#extract-document-javascript)
   - [Copy Pages](#copy-pages)
   - [Embed PNG and JPEG Images](#embed-png-and-jpeg-images)
   - [Embed PDF Pages](#embed-pdf-pages)
@@ -110,6 +111,7 @@ Install with: `npm install @cantoo/pdf-lib`
 - Preserve XFA forms
 - Extract XFA JavaScript
 - Modify XFA JavaScript
+- Extract document-level JavaScript
 - Add Pages
 - Insert Pages
 - Remove Pages
@@ -757,13 +759,11 @@ const pdfDoc = await PDFDocument.load(xfaPdfBytes, {
 
 // Make modifications...
 
-// Save with XFA preservation
-const pdfBytes = await pdfDoc.save({ 
-  preserveXFA: true 
-})
+// Save the document
+const pdfBytes = await pdfDoc.save()
 ```
 
-**Note:** Without `preserveXFA: true`, XFA data will be removed when saving, which may cause the form to lose functionality.
+**Note:** The `preserveXFA` option must be set to `true` when loading to preserve XFA data. XFA preservation during save happens automatically if it was preserved during load.
 
 ### Extract XFA JavaScript
 
@@ -838,19 +838,20 @@ if (importButton) {
     }
   `
   
-  const success = pdfDoc.setXFAJavaScript(
-    'ImportButton',           // field name
-    importButton.event,       // event name (e.g., 'event__click')
-    newScript                 // new JavaScript code
-  )
-  
-  console.log(`Modification ${success ? 'succeeded' : 'failed'}`)
+  try {
+    pdfDoc.setXFAJavaScript(
+      'ImportButton',         // field name
+      importButton.event,     // event name (e.g., 'event__click')
+      newScript               // new JavaScript code
+    )
+    console.log('Successfully modified XFA JavaScript')
+  } catch (error) {
+    console.error('Failed to modify script:', error.message)
+  }
 }
 
-// Save with XFA preservation
-const pdfBytes = await pdfDoc.save({ 
-  preserveXFA: true 
-})
+// Save the document
+const pdfBytes = await pdfDoc.save()
 
 // The modified PDF will have the updated JavaScript
 ```
@@ -862,6 +863,40 @@ const pdfBytes = await pdfDoc.save({
 - Customize import/export behavior
 - Fix compatibility issues
 
+### Extract Document JavaScript
+
+PDF documents can contain document-level JavaScript that executes when the document is opened. You can extract these scripts:
+
+<!-- prettier-ignore -->
+```js
+import { PDFDocument } from 'pdf-lib'
+
+const pdfBytes = ... // Load your PDF
+
+const pdfDoc = await PDFDocument.load(pdfBytes)
+
+// Extract all document-level JavaScript
+const scripts = pdfDoc.getDocumentJavaScripts()
+
+// Each script contains:
+// - name: The script name
+// - script: The JavaScript code
+
+console.log(`Found ${scripts.length} document scripts`)
+
+scripts.forEach((script) => {
+  console.log(`Script name: ${script.name}`)
+  console.log(`Code: ${script.script}`)
+})
+
+// Find specific scripts
+const initScripts = scripts.filter(s => 
+  s.name.toLowerCase().includes('init')
+)
+```
+
+**Note:** Document-level JavaScript is different from XFA JavaScript. Document-level scripts are stored in the document's Names dictionary and execute when the PDF is opened. XFA JavaScript is embedded in XFA form templates.
+
 ### Copy Pages
 
 _This example produces [this PDF](assets/pdfs/examples/copy_pages.pdf)_ (when [this PDF](assets/pdfs/with_update_sections.pdf) is used for the `firstDonorPdfBytes` variable and [this PDF](assets/pdfs/with_large_page_count.pdf) is used for the `secondDonorPdfBytes` variable).
diff --git a/src/api/PDFDocument.ts b/src/api/PDFDocument.ts
index 0863ad5c1..12193a086 100644
--- a/src/api/PDFDocument.ts
+++ b/src/api/PDFDocument.ts
@@ -1024,26 +1024,86 @@ export default class PDFDocument {
   }
 
   /**
-   * Get all JavaScript from XFA form template.
-   * XFA forms can contain JavaScript in <script> elements within the template XML.
-   * For example:
-   * ```js
-   * const xfaScripts = pdfDoc.getXFAJavaScripts()
-   * xfaScripts.forEach(({ field, event, script }) => {
-   *   console.log(`Field "${field}" on ${event}:`, script)
-   * })
-   * ```
-   * @returns An array of objects containing field names, events, and JavaScript code.
+   * Helper method to escape XML special characters in script content
    */
-  getXFAJavaScripts(): Array<{ field: string; event: string; script: string }> {
-    const scripts: Array<{ field: string; event: string; script: string }> = [];
+  private escapeXML(str: string): string {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  /**
+   * Normalizes XFA template XML so that node-html-better-parser can parse it
+   * correctly. XFA uses \n> to close opening tags, and the HTML parser treats
+   * <template> as a special inert element, so both need to be worked around.
+   */
+  private normalizeXfaXml(xml: string): string {
+    return xml
+      .replace(/\n>/g, '>')
+      .replace(/<template(\s)/g, '<xfa-template$1')
+      .replace(/<template>/g, '<xfa-template>')
+      .replace(/<\/template>/g, '</xfa-template>');
+  }
+
+  /**
+   * Recursively collects all <script> nodes from the XFA XML tree that have a
+   * valid enclosing field and event context.
+   */
+  private collectXFAScripts(
+    node: HTMLElement,
+    currentField?: string,
+    currentEvent?: string,
+  ): Array<{ scriptNode: HTMLElement; field: string; event: string }> {
+    const results: Array<{
+      scriptNode: HTMLElement;
+      field: string;
+      event: string;
+    }> = [];
+
+    const tag = node.tagName?.toLowerCase();
+    let fieldCtx = currentField;
+    let eventCtx = currentEvent;
+
+    if (tag === 'field') {
+      fieldCtx = node.getAttribute('name') ?? undefined;
+      eventCtx = undefined;
+    } else if (tag === 'event') {
+      eventCtx = node.getAttribute('name') ?? undefined;
+    } else if (tag === 'script') {
+      if (fieldCtx && eventCtx) {
+        results.push({ scriptNode: node, field: fieldCtx, event: eventCtx });
+      }
+    }
+
+    for (const child of node.childNodes) {
+      if (child.nodeType === NodeType.ELEMENT_NODE) {
+        results.push(
+          ...this.collectXFAScripts(child as HTMLElement, fieldCtx, eventCtx),
+        );
+      }
+    }
+
+    return results;
+  }
 
+  /**
+   * Helper method to extract XFA template information
+   */
+  private getXFATemplateInfo(): {
+    xfa: PDFArray;
+    templateIndex: number;
+    streamRef: PDFRef | null;
+    stream: PDFRawStream;
+  } | null {
     const acroForm = this.catalog.get(PDFName.of('AcroForm'));
     if (
       !acroForm ||
       !(acroForm instanceof PDFDict || acroForm instanceof PDFRef)
     ) {
-      return scripts;
+      return null;
     }
 
     const formDict =
@@ -1053,17 +1113,15 @@ export default class PDFDocument {
 
     const xfaObj = formDict.get(PDFName.of('XFA'));
     if (!xfaObj) {
-      return scripts;
+      return null;
     }
 
-    // XFA might be a reference to an array
     const xfa = xfaObj instanceof PDFRef ? this.context.lookup(xfaObj) : xfaObj;
 
     if (!(xfa instanceof PDFArray)) {
-      return scripts;
+      return null;
     }
 
-    // XFA is an array of [name1, stream1, name2, stream2, ...]
     for (let idx = 0; idx < xfa.size(); idx += 2) {
       const nameObj = xfa.get(idx);
       const streamObj = xfa.get(idx + 1);
@@ -1079,7 +1137,6 @@ export default class PDFDocument {
         continue;
       }
 
-      // We're interested in the 'template' section
       if (sectionName !== 'template') continue;
 
       const streamRef = streamObj instanceof PDFRef ? streamObj : null;
@@ -1087,57 +1144,65 @@ export default class PDFDocument {
 
       if (!stream || !(stream instanceof PDFRawStream)) continue;
 
-      const xmlBytes = decodePDFRawStream(stream).decode();
-      const xmlString = new TextDecoder().decode(xmlBytes);
-
-      // Extract JavaScript from <script> tags
-      // Note: XFA uses newlines in closing tags like </script\n>
-      const scriptMatches: Array<{
-        field: string;
-        event: string;
-        script: string;
-      }> = [];
-      const scriptPattern = /<script[^>]*>\s*([\s\S]*?)\s*<\/script\s*>/gi;
-      let scriptMatch;
-
-      while ((scriptMatch = scriptPattern.exec(xmlString)) !== null) {
-        const scriptCode = scriptMatch[1].trim();
-        if (!scriptCode) continue;
-
-        // Find the enclosing field and event by looking backwards
-        const beforeScript = xmlString.substring(
-          Math.max(0, scriptMatch.index - 2000),
-          scriptMatch.index,
-        );
+      return {
+        xfa,
+        templateIndex: idx + 1,
+        streamRef,
+        stream,
+      };
+    }
 
-        // Find field name
-        const fieldNameMatch = beforeScript.match(
-          /<field[^>]*name="([^"]*)"[^>]*>/gi,
-        );
-        const fieldName = fieldNameMatch
-          ? fieldNameMatch[fieldNameMatch.length - 1].match(
-            /name="([^"]*)"/,
-          )?.[1] || 'unknown'
-          : 'unknown';
-
-        // Find event name
-        const eventNameMatch = beforeScript.match(
-          /<event[^>]*name="([^"]*)"[^>]*>/gi,
-        );
-        const eventName = eventNameMatch
-          ? eventNameMatch[eventNameMatch.length - 1].match(
-            /name="([^"]*)"/,
-          )?.[1] || 'unknown'
-          : 'unknown';
-
-        scriptMatches.push({
-          field: fieldName,
-          event: eventName,
-          script: scriptCode,
-        });
-      }
+    return null;
+  }
+
+  /**
+   * Get all JavaScript from XFA form template.
+   * XFA forms can contain JavaScript in <script> elements within the template XML.
+   * For example:
+   * ```js
+   * const xfaScripts = pdfDoc.getXFAJavaScripts()
+   * xfaScripts.forEach(({ field, event, script }) => {
+   *   console.log(`Field "${field}" on ${event}:`, script)
+   * })
+   * ```
+   * @returns An array of objects containing field names, events, and JavaScript code.
+   */
+  getXFAJavaScripts(): Array<{ field: string; event: string; script: string }> {
+    const scripts: Array<{ field: string; event: string; script: string }> = [];
 
-      scripts.push(...scriptMatches);
+    const templateInfo = this.getXFATemplateInfo();
+    if (!templateInfo) {
+      return scripts;
+    }
+
+    try {
+      const xmlBytes = decodePDFRawStream(templateInfo.stream).decode();
+      const xmlString = new TextDecoder('utf-8', { fatal: true }).decode(
+        xmlBytes,
+      );
+
+      const doc = parseHtml(this.normalizeXfaXml(xmlString), { script: true });
+
+      for (const script of this.collectXFAScripts(doc)) {
+        const scriptContent = script.scriptNode.text?.trim();
+        if (scriptContent) {
+          scripts.push({
+            field: script.field,
+            event: script.event,
+            script: scriptContent,
+          });
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.message.includes('decode')) {
+          throw new Error(
+            `Failed to decode XFA template stream: Invalid UTF-8 encoding. ${error.message}`,
+          );
+        }
+        throw new Error(`Failed to parse XFA template: ${error.message}`);
+      }
+      throw error;
     }
 
     return scripts;
@@ -1152,83 +1217,65 @@ export default class PDFDocument {
    * @param fieldName The name of the field containing the script
    * @param eventName The name of the event (e.g., 'event__click', 'calculate')
    * @param newScript The new JavaScript code to set
-   * @returns True if the script was found and updated, false otherwise
+   * @throws Error if the XFA form is not found, the script location is not found, or decoding fails
    */
   setXFAJavaScript(
     fieldName: string,
     eventName: string,
     newScript: string,
-  ): boolean {
-    const acroForm = this.catalog.get(PDFName.of('AcroForm'));
-    if (
-      !acroForm ||
-      !(acroForm instanceof PDFDict || acroForm instanceof PDFRef)
-    ) {
-      return false;
+  ): void {
+    const templateInfo = this.getXFATemplateInfo();
+    if (!templateInfo) {
+      throw new Error(
+        'XFA form not found in document. Ensure the document has XFA forms and was loaded with preserveXFA: true.',
+      );
     }
 
-    const formDict =
-      acroForm instanceof PDFRef
-        ? this.context.lookup(acroForm, PDFDict)
-        : acroForm;
-
-    const xfa = formDict.get(PDFName.of('XFA'));
-    if (!xfa || !(xfa instanceof PDFArray)) {
-      return false;
+    let xmlString: string;
+    try {
+      const xmlBytes = decodePDFRawStream(templateInfo.stream).decode();
+      xmlString = new TextDecoder('utf-8', { fatal: true }).decode(xmlBytes);
+    } catch (error) {
+      throw new Error(
+        `Failed to decode XFA template stream: ${error instanceof Error ? error.message : String(error)}`,
+      );
     }
 
-    // Find template section
-    for (let idx = 0; idx < xfa.size(); idx += 2) {
-      const nameObj = xfa.get(idx);
-      const streamObj = xfa.get(idx + 1);
+    const normalizedXml = this.normalizeXfaXml(xmlString);
+    const doc = parseHtml(normalizedXml, { script: true });
 
-      if (!nameObj || !streamObj) continue;
-
-      let sectionName: string;
-      if (nameObj instanceof PDFString) {
-        sectionName = nameObj.asString();
-      } else if (nameObj instanceof PDFHexString) {
-        sectionName = nameObj.decodeText();
-      } else {
-        continue;
-      }
-
-      if (sectionName !== 'template') continue;
-
-      const streamRef = streamObj instanceof PDFRef ? streamObj : null;
-      const stream = streamRef ? this.context.lookup(streamRef) : streamObj;
-
-      if (!stream || !(stream instanceof PDFRawStream)) continue;
-
-      const xmlBytes = decodePDFRawStream(stream).decode();
-      let xmlString = new TextDecoder().decode(xmlBytes);
+    const entry = this.collectXFAScripts(doc).find(
+      (e) => e.field === fieldName && e.event === eventName,
+    );
 
-      // Find and replace the script
-      // Note: XFA uses newlines in closing tags like </script\n>
-      const fieldPattern = new RegExp(
-        `(<field[^>]*name="${fieldName}"[^>]*>[\\s\\S]*?<event[^>]*name="${eventName}"[^>]*>[\\s\\S]*?<script[^>]*>)\\s*[\\s\\S]*?\\s*(<\\/script\\s*>)`,
-        'i',
+    if (!entry) {
+      throw new Error(
+        `Script not found for field "${fieldName}" and event "${eventName}". ` +
+        'Verify the field and event names exist in the XFA template.',
       );
-
-      const match = xmlString.match(fieldPattern);
-      if (!match) continue;
-
-      xmlString = xmlString.replace(fieldPattern, `$1\n${newScript}\n$2`);
-
-      // Create new stream with modified XML
-      const newXmlBytes = new TextEncoder().encode(xmlString);
-      const newStream = this.context.stream(newXmlBytes);
-
-      // Replace in XFA array
-      if (streamRef) {
-        this.context.delete(streamRef);
-      }
-      xfa.set(idx + 1, this.context.register(newStream));
-
-      return true;
     }
 
-    return false;
+    const oldOuter = entry.scriptNode.outerHTML;
+    const tagOpen = oldOuter.match(/^(<script[^>]*>)/i)?.[1] ?? '<script>';
+    const newOuter = `${tagOpen}${this.escapeXML(newScript)}</script>`;
+    const updatedXml = normalizedXml
+      .replace(oldOuter, newOuter)
+      .replace(/xfa-template/g, 'template');
+
+    const newXmlBytes = new TextEncoder().encode(updatedXml);
+    const filter = templateInfo.stream.dict.get(PDFName.of('Filter'));
+    const newStream =
+      filter !== undefined
+        ? this.context.flateStream(newXmlBytes)
+        : this.context.stream(newXmlBytes);
+
+    if (templateInfo.streamRef) {
+      this.context.delete(templateInfo.streamRef);
+    }
+    templateInfo.xfa.set(
+      templateInfo.templateIndex,
+      this.context.register(newStream),
+    );
   }
 
   /**
diff --git a/src/api/PDFJavaScriptAction.ts b/src/api/PDFJavaScriptAction.ts
index dde7d8c96..9103ac9e7 100644
--- a/src/api/PDFJavaScriptAction.ts
+++ b/src/api/PDFJavaScriptAction.ts
@@ -75,17 +75,7 @@ export default class PDFJavaScriptAction {
       return jsValue.decodeText();
     }
     if (jsValue instanceof PDFName) {
-      // Handle case where the value was created with context.obj() using a string literal
-      // PDFName.asString() returns the encoded name with leading slash and hex-encoded special chars
-      // We need to remove the slash and decode the hex sequences
-      const nameStr = jsValue.asString();
-      const withoutSlash = nameStr.startsWith('/')
-        ? nameStr.substring(1)
-        : nameStr;
-      // Decode hex sequences like #28 -> (
-      return withoutSlash.replace(/#([\dA-Fa-f]{2})/g, (_, hex) =>
-        String.fromCharCode(parseInt(hex, 16)),
-      );
+      return jsValue.decodeText();
     }
     return undefined;
   }
diff --git a/tests/api/PDFDocumentXFA.spec.ts b/tests/api/PDFDocumentXFA.spec.ts
index 97336a5a6..9baab7fd2 100644
--- a/tests/api/PDFDocumentXFA.spec.ts
+++ b/tests/api/PDFDocumentXFA.spec.ts
@@ -51,9 +51,7 @@ describe('PDFDocument - XFA JavaScript', () => {
     expect(checkbox).toBeDefined();
 
     const newScript = 'console.println("Modified checkbox script");';
-    const result = pdfDoc.setXFAJavaScript('c1_01', checkbox!.event, newScript);
-
-    expect(result).toBe(true);
+    pdfDoc.setXFAJavaScript('c1_01', checkbox!.event, newScript);
 
     // Verify the modification
     const modifiedScripts = pdfDoc.getXFAJavaScripts();
@@ -66,17 +64,13 @@ describe('PDFDocument - XFA JavaScript', () => {
     expect(modifiedCheckbox!.script).toContain(newScript);
   });
 
-  it('returns false when modifying non-existent field', async () => {
+  it('throws when modifying non-existent field', async () => {
     const pdfBytes = toUint8Array(fs.readFileSync(xfaPdfPath));
     const pdfDoc = await PDFDocument.load(pdfBytes, { preserveXFA: true });
 
-    const result = pdfDoc.setXFAJavaScript(
-      'nonexistent',
-      'event__click',
-      'test',
-    );
-
-    expect(result).toBe(false);
+    expect(() =>
+      pdfDoc.setXFAJavaScript('nonexistent', 'event__click', 'test'),
+    ).toThrow('Script not found for field "nonexistent"');
   });
 
   it('preserves XFA structure after modification', async () => {