pdf_xfa/

session.rs

//! `XfaSession` — parse-once interactive fill session over an XFA PDF.
//!
//! **Phase 1** ([`open`](XfaSession::open) / [`set_value`](XfaSession::set_value)
//! / [`save_to_bytes`](XfaSession::save_to_bytes)): enumerate the currently
//! visible/layouted fields, set values (with write-through to the bound data
//! nodes), and save a PDF whose datasets packet carries the filled values so
//! Adobe Acrobat/Reader reopens the form with them. No scripts run and the
//! layout is not recomputed.
//!
//! **Phase 2** ([`open_interactive`](XfaSession::open_interactive) /
//! [`commit_value`](XfaSession::commit_value)): the interactive commit loop —
//! a value commit fires the field's `change`/`click` scripts and a `calculate`
//! pass, then re-layouts, so conditional sections the value reveals or hides
//! are reflected in the refreshed [`fields`](XfaSession::fields) /
//! [`page_count`](XfaSession::page_count). Requires the `xfa-js-sandboxed`
//! feature; without it `commit_value` degrades to a value write plus re-layout.
//! Still out of scope: instanceManager add/remove and form-packet *structural*
//! writes.
//!
//! ```no_run
//! use pdf_xfa::session::{XfaSession, XfaWriteValue};
//!
//! let bytes = std::fs::read("form.pdf").unwrap();
//! let mut session = XfaSession::open(&bytes).unwrap();
//! println!("pages: {}", session.page_count());
//! for f in session.fields() {
//!     println!("{} = {:?}", f.name, f.value);
//! }
//! session
//!     .set_value("form1.applicant.name", XfaWriteValue::Text("Alice"))
//!     .unwrap();
//! let filled = session.save_to_bytes().unwrap();
//! std::fs::write("filled.pdf", filled).unwrap();
//! ```

// Copyright (c) 2026 Innovation Trigger B.V.
//
// PDFluent is available under two licences, at your option: the GNU AGPLv3, or
// the PDFluent Commercial Licence. See the LICENSE file in this repository --
// that file travels with the copy you received, which a URL does not.

use std::collections::HashMap;

use lopdf::Document;
use xfa_dom_resolver::data_dom::{DataDom, DataNode, DataNodeId};
use xfa_layout_engine::form::{
    Access, FieldKind, FormNodeId, FormNodeType, FormTree, GroupKind, Presence,
};
use xfa_layout_engine::layout::{LayoutContent, LayoutDom, LayoutEngine, LayoutNode};

use crate::datasets_writeback::{self, DatasetsEdit, FormPacketEdit};
#[cfg(feature = "xfa-js-sandboxed")]
use crate::dynamic::InteractiveTrigger;
use crate::dynamic::{apply_dynamic_scripts, PresenceChange};
pub use crate::dynamic::{XfaScriptError, XfaScriptErrorKind, XfaScriptReport, XfaScriptsSkipped};
use crate::error::{Result, XfaError};
use crate::extract::{extract_xfa_from_bytes, XfaPackets};
use crate::flatten::{
    apply_form_dom_presence, extract_embedded_images, inject_resolved_metrics,
    resolve_template_fonts, XfaRenderingPolicy,
};
use crate::merger::FormMerger;

/// A value to write into an XFA field.
#[derive(Debug, Clone, Copy)]
pub enum XfaWriteValue<'a> {
    /// Text-like fields: text, multiline text, numeric, date/time, password,
    /// and choice lists (pass the save value or the display value).
    Text(&'a str),
    /// Checkbox: `true` selects the on-value, `false` the off-value.
    Checkbox(bool),
    /// Radio group (exclGroup): the on-value of the member to select.
    Radio(&'a str),
}

/// Public field type, mirroring [`FieldKind`] without leaking the
/// layout-engine type into the SDK surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum XfaFieldType {
    /// Single-line or multiline text edit.
    Text,
    /// Standalone checkbox.
    Checkbox,
    /// Exclusive radio group (exclGroup with checkButton members).
    RadioGroup,
    /// Push button (not fillable).
    Button,
    /// Dropdown / choice list.
    Dropdown,
    /// Signature field (not fillable in Phase 1).
    Signature,
    /// Date/time picker (accepts text in Phase 1).
    DateTime,
    /// Numeric edit (accepts text in Phase 1).
    Numeric,
    /// Password edit.
    Password,
    /// Image edit (not fillable in Phase 1).
    Image,
    /// Barcode (not fillable).
    Barcode,
}

impl XfaFieldType {
    fn from_kind(kind: FieldKind) -> Self {
        match kind {
            FieldKind::Text => XfaFieldType::Text,
            FieldKind::Checkbox => XfaFieldType::Checkbox,
            FieldKind::Radio => XfaFieldType::RadioGroup,
            FieldKind::Button => XfaFieldType::Button,
            FieldKind::Dropdown => XfaFieldType::Dropdown,
            FieldKind::Signature => XfaFieldType::Signature,
            FieldKind::DateTimePicker => XfaFieldType::DateTime,
            FieldKind::NumericEdit => XfaFieldType::Numeric,
            FieldKind::PasswordEdit => XfaFieldType::Password,
            FieldKind::ImageEdit => XfaFieldType::Image,
            FieldKind::Barcode => XfaFieldType::Barcode,
        }
    }

    /// Whether [`XfaSession::set_value`] accepts writes for this type.
    pub fn is_fillable(self) -> bool {
        !matches!(
            self,
            XfaFieldType::Button
                | XfaFieldType::Signature
                | XfaFieldType::Image
                | XfaFieldType::Barcode
        )
    }
}

/// Axis-aligned rectangle in page space, points, top-left origin (XFA
/// coordinate convention: y grows downward from the top of the page).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct XfaRect {
    /// Left edge.
    pub x: f64,
    /// Top edge.
    pub y: f64,
    /// Width.
    pub width: f64,
    /// Height.
    pub height: f64,
}

/// One layouted widget occurrence of a field.
#[derive(Debug, Clone)]
pub struct XfaWidget {
    /// 0-based page index in the layout result.
    pub page: usize,
    /// Widget rectangle (page space, top-left origin, points).
    pub rect: XfaRect,
    /// For radio groups: the on-value asserted by this member widget.
    pub on_value: Option<String>,
}

/// A selectable option of a dropdown / list field.
#[derive(Debug, Clone)]
pub struct XfaFieldOption {
    /// User-visible text.
    pub display: String,
    /// Persisted save value (equals `display` when the template defines no
    /// separate save items).
    pub save: String,
}

/// SDK-level model of one fillable XFA form field, derived from the merged
/// form tree and the current layout.
#[derive(Debug, Clone)]
pub struct XfaFieldModel {
    /// Fully-qualified dotted name with `[n]` indices omitted when 0
    /// (Adobe display-SOM style), e.g. `form1.applicant.name` or
    /// `form1.rows.row[2].amount`.
    pub name: String,
    /// Fully-qualified SOM path with explicit `[n]` on every segment,
    /// e.g. `form1[0].rows[0].row[2].amount[0]`.
    pub som_path: String,
    /// Field type.
    pub field_type: XfaFieldType,
    /// Current value (the form-tree raw value; radio groups report the
    /// selected member's on-value, empty when none selected).
    pub value: String,
    /// Effective read-only state: the field or an ancestor container sets
    /// `access="readOnly" | "protected" | "nonInteractive"`.
    pub read_only: bool,
    /// Mandatory field (`<validate nullTest="error">`).
    pub required: bool,
    /// Multiline text edit (`<ui><textEdit multiLine="1">`).
    pub multiline: bool,
    /// Hidden/invisible/inactive via XFA presence (template, saved form
    /// state, or script-derived).
    pub hidden: bool,
    /// Dropdown/list options. For radio groups: one option per member
    /// (display = member on-value).
    pub options: Vec<XfaFieldOption>,
    /// Checkbox on-value (`<items>` / checkButton binding), when known.
    pub on_value: Option<String>,
    /// Checkbox off-value, when known.
    pub off_value: Option<String>,
    /// First page this field appears on (0-based), `None` when the field is
    /// not part of the current layout (e.g. hidden).
    pub page: Option<usize>,
    /// Rectangle of the first widget occurrence.
    pub rect: Option<XfaRect>,
    /// All layouted widget occurrences (radio groups: one per member).
    pub widgets: Vec<XfaWidget>,
    /// Whether the field has a bound data node in the datasets DOM. Values
    /// written to unbound fields are persisted by creating the data node on
    /// demand (default binding), except for `bind match="none"` fields.
    pub bound_to_data: bool,
    /// `<bind match="none">` — the field deliberately does not participate
    /// in data binding; Adobe persists such values only in the form packet.
    pub bind_none: bool,
}

/// Outcome of a successful [`XfaSession::set_value`] call.
#[derive(Debug, Clone)]
pub struct XfaSetOutcome {
    /// The normalized value written to the form tree (e.g. the resolved
    /// save value of a dropdown, or a checkbox on/off value).
    pub raw_value: String,
    /// The value was written through to a datasets node (existing or
    /// created on demand) and will be persisted by [`XfaSession::save_to_bytes`].
    pub persisted_to_datasets: bool,
}

/// Outcome of an interactive [`XfaSession::commit_value`] (Phase 2).
///
/// Extends the plain value write with the script-driven dynamic effects: the
/// commit fired the field's `change`/`click` scripts and a `calculate` pass,
/// then re-layouted. `presence_changes` and the page-count delta describe what
/// the commit revealed or hid.
#[derive(Debug, Clone)]
pub struct XfaCommitOutcome {
    /// The underlying value write (same as [`XfaSession::set_value`]).
    pub set: XfaSetOutcome,
    /// Whether interactive scripts ran (false when the `xfa-js-sandboxed`
    /// feature is not compiled in — the commit then only re-layouts).
    pub interactive: bool,
    /// Number of event scripts the runtime executed during this commit.
    pub scripts_executed: usize,
    /// Page count before the commit.
    pub page_count_before: usize,
    /// Page count after re-layout.
    pub page_count_after: usize,
    /// Fields/subforms whose presence changed (revealed or hidden) as a result
    /// of the committed value.
    pub presence_changes: Vec<PresenceChange>,
}

/// Report from a save/writeback.
#[derive(Debug, Clone, Default)]
pub struct XfaWritebackReport {
    /// Datasets packet rewritten by surgical splice (original XML preserved
    /// except for the changed values). `false` = lossless splice failed and
    /// the data section was regenerated from the data DOM instead.
    pub datasets_spliced: bool,
    /// Number of `<value>` updates applied to the saved form packet (kept in
    /// sync so Adobe's `restoreState` does not resurrect stale values).
    pub form_packet_values_updated: usize,
}

struct FieldEntry {
    /// The field node (for radio groups: the exclGroup node).
    node: FormNodeId,
    /// Member fields of a radio group, with their on-values.
    members: Vec<(FormNodeId, String)>,
    /// Effective access at enumeration time.
    read_only: bool,
    /// Path of named segments from the root, with same-name sibling indices.
    segments: Vec<(String, usize)>,
}

/// Parse-once session over a single XFA PDF.
///
/// Holds the extracted packets, the parsed datasets DOM, the merged form
/// tree, and the layout result. Field enumeration and value writes operate
/// on the cached state; no re-parse or re-layout happens per call (Phase 1:
/// value writes do not reflow the layout).
pub struct XfaSession {
    pdf_bytes: Vec<u8>,
    packets: XfaPackets,
    data_dom: DataDom,
    tree: FormTree,
    layout: LayoutDom,
    /// Root form node id — retained for re-layout in the Phase 2 commit loop.
    root_id: FormNodeId,
    fields: Vec<FieldEntry>,
    models: Vec<XfaFieldModel>,
    by_name: HashMap<String, usize>,
    /// Data nodes whose values changed (existing nodes).
    dirty_data: Vec<DataNodeId>,
    /// Data nodes created on demand: (id, parent path at creation time).
    created_data: Vec<DataNodeId>,
    /// Form-packet value syncs to apply at save.
    form_packet_sync: Vec<FormPacketEdit>,
    /// Field values as parsed, before any script ran: the baseline a commit
    /// compares against to find the values scripts wrote.
    baseline_values: HashMap<String, String>,
    /// Scripts not run, accumulated over the session (see
    /// [`XfaSession::script_report`]).
    script_report: XfaScriptReport,
    /// Phase 2: interactive mode is active — the open lifecycle ran with
    /// presence writes landing, and [`XfaSession::commit_value`] dispatches
    /// user-edit scripts + re-layouts. Set by `open_interactive`/lazy upgrade.
    ///
    /// The sandboxed runtime is **not** held on the session — it is constructed
    /// per episode (open lifecycle / each commit) and dropped — so `XfaSession`
    /// stays `Send + Sync` (the rquickjs context is `!Send`). The interactive
    /// *state* lives in `tree` (presence values), which persists across commits.
    interactive: bool,
}

impl XfaSession {
    /// Open a session over the given PDF bytes.
    ///
    /// Mirrors the flatten pipeline's Extract → Bind → (static scripts) →
    /// saved-form-state → Layout stages, then caches everything.
    ///
    /// Returns [`XfaError::PacketNotFound`] when the PDF has no XFA template
    /// packet (i.e. it is not an XFA form).
    pub fn open(pdf_bytes: &[u8]) -> Result<XfaSession> {
        let packets = extract_xfa_from_bytes(pdf_bytes.to_vec())?;
        let template_xml = packets
            .template()
            .ok_or_else(|| XfaError::PacketNotFound("template".to_string()))?
            .to_string();

        // A malformed or empty datasets packet must not block the session —
        // the form is still fillable; the writeback regenerates a canonical
        // packet from scratch (Adobe tolerates both).
        let data_dom = match packets.datasets() {
            Some(ds) => DataDom::from_xml(ds).unwrap_or_else(|e| {
                log::warn!("XfaSession: datasets packet unparseable ({e}); starting empty");
                DataDom::new()
            }),
            None => DataDom::new(),
        };

        let image_files = match Document::load_mem(pdf_bytes) {
            Ok(doc) => extract_embedded_images(&doc),
            Err(_) => HashMap::new(),
        };

        let merger = FormMerger::new(&data_dom).with_image_files(image_files);
        let (mut tree, root_id) = merger
            .merge(&template_xml)
            .map_err(|e| XfaError::ParseFailed(format!("template merge: {e}")))?;

        // Static-analysis script pass only (BestEffortStatic): presence
        // toggles and FormCalc the engine can resolve without a JS runtime.
        // Phase 1 deliberately runs no change/click events.
        let _ = apply_dynamic_scripts(&mut tree, root_id)?;

        // Saved form state (Adobe-Reader-saved PDFs): presence overrides and
        // saved field values, exactly as the flatten pipeline applies them.
        if let Some(form_xml) = packets.get_packet("form") {
            let _ = apply_form_dom_presence(
                &mut tree,
                root_id,
                form_xml,
                XfaRenderingPolicy::SavedStateFaithful,
                true,
            );
            apply_form_dom_access(&mut tree, root_id, form_xml);
        }

        // Resolved font metrics make the layout geometry match the flatten
        // output (widths drive wrapping and therefore field positions).
        let resolved = resolve_template_fonts(&template_xml, pdf_bytes);
        inject_resolved_metrics(&mut tree, &resolved);

        let layout = LayoutEngine::new(&tree)
            .layout(root_id)
            .map_err(|e| XfaError::LayoutFailed(e.to_string()))?;

        let mut session = XfaSession {
            pdf_bytes: pdf_bytes.to_vec(),
            packets,
            data_dom,
            tree,
            layout,
            root_id,
            fields: Vec::new(),
            models: Vec::new(),
            by_name: HashMap::new(),
            dirty_data: Vec::new(),
            created_data: Vec::new(),
            form_packet_sync: Vec::new(),
            baseline_values: HashMap::new(),
            script_report: XfaScriptReport::default(),
            interactive: false,
        };
        session.enumerate_fields(root_id);
        session.baseline_values = session
            .models
            .iter()
            .map(|m| (m.name.clone(), m.value.clone()))
            .collect();
        Ok(session)
    }

    /// Open a session in **interactive mode** (Phase 2).
    ///
    /// Identical to [`open`](Self::open), then — when the `xfa-js-sandboxed`
    /// feature is compiled in — runs the interactive open lifecycle
    /// (`initialize` → `docReady` → `calculate`) with `field.presence` writes
    /// landing in the tree, re-layouts, and re-enumerates. The result reflects
    /// a dynamic form's real initial visible state (the script-driven
    /// show/hide of conditional sections), not the static one-shot render.
    ///
    /// Without the feature this is equivalent to [`open`](Self::open) and
    /// [`commit_value`](Self::commit_value) degrades to a value write plus
    /// re-layout (no script-driven toggles).
    pub fn open_interactive(pdf_bytes: &[u8]) -> Result<XfaSession> {
        let mut session = XfaSession::open(pdf_bytes)?;
        session.ensure_interactive();
        Ok(session)
    }

    /// Number of pages in the cached layout result.
    pub fn page_count(&self) -> usize {
        self.layout.pages.len()
    }

    /// Page dimensions `(width, height)` in points for a 0-based page index.
    pub fn page_size(&self, page: usize) -> Option<(f64, f64)> {
        self.layout.pages.get(page).map(|p| (p.width, p.height))
    }

    /// The enumerated field models, in document order.
    pub fn fields(&self) -> &[XfaFieldModel] {
        &self.models
    }

    /// Look up one field model by fully-qualified name. Accepts both the
    /// display name (`a.b[2].c`) and the explicit SOM path (`a[0].b[2].c[0]`).
    pub fn field(&self, name: &str) -> Option<&XfaFieldModel> {
        self.by_name.get(name).map(|&i| &self.models[i])
    }

    /// Set a field's value.
    ///
    /// Updates the form-tree raw value, writes through to the bound
    /// datasets node (creating it on demand for default-bound fields), and
    /// records the change for [`save_to_bytes`](Self::save_to_bytes).
    ///
    /// Rejects writes to read-only fields ([`XfaError::FieldReadOnly`]) and
    /// to non-fillable kinds (buttons, signatures, …). No change/click
    /// scripts run and the layout is not recomputed (Phase 1).
    pub fn set_value(&mut self, name: &str, value: XfaWriteValue<'_>) -> Result<XfaSetOutcome> {
        let idx = *self
            .by_name
            .get(name)
            .ok_or_else(|| XfaError::FieldNotFound(name.to_string()))?;

        if self.fields[idx].read_only {
            return Err(XfaError::FieldReadOnly(name.to_string()));
        }
        let field_type = self.models[idx].field_type;
        if !field_type.is_fillable() {
            return Err(XfaError::InvalidFieldValue {
                name: name.to_string(),
                reason: format!("{field_type:?} fields are not fillable"),
            });
        }

        let raw = self.normalize_value(idx, value, name)?;

        // 1. Form-tree raw value.
        self.write_tree_value(idx, &raw);

        // 2-3. Datasets write-through and saved-form-packet sync.
        let persisted = self.persist_value(idx, &raw)?;

        // 4. Refresh the public model.
        self.models[idx].value = raw.clone();

        Ok(XfaSetOutcome {
            raw_value: raw,
            persisted_to_datasets: persisted,
        })
    }

    /// Whether interactive mode is active (the open lifecycle ran with presence
    /// writes and commits dispatch user-edit scripts). Only ever true with the
    /// `xfa-js-sandboxed` feature compiled in.
    pub fn is_interactive(&self) -> bool {
        self.interactive
    }

    /// **Phase 2 interactive commit.** Set a field's value, then run the
    /// dynamic effects: fire the field's `change`/`click` scripts, a global
    /// `calculate` pass, re-layout, and re-enumerate the field/page model.
    ///
    /// This is the interactive analogue of [`set_value`](Self::set_value): the
    /// data writeback is identical (so [`save_to_bytes`](Self::save_to_bytes)
    /// still produces an Acrobat-reopenable PDF), but conditional sections that
    /// the committed value reveals or hides are reflected in the new
    /// [`fields`](Self::fields) / [`page_count`](Self::page_count).
    ///
    /// Without the `xfa-js-sandboxed` feature this degrades to a value write
    /// plus re-layout: `interactive == false`, `scripts_executed == 0`, and no
    /// script-driven presence changes (a static value edit only).
    pub fn commit_value(
        &mut self,
        name: &str,
        value: XfaWriteValue<'_>,
    ) -> Result<XfaCommitOutcome> {
        // Validate the field exists before any work.
        if !self.by_name.contains_key(name) {
            return Err(XfaError::FieldNotFound(name.to_string()));
        }

        // 0. Establish the interactive initial state BEFORE writing the value,
        //    so the open lifecycle (docReady/calculate) runs with the *pre-edit*
        //    value. Otherwise a lazily-upgraded session would reveal the section
        //    during open (seeing the new value) and the change episode below
        //    would observe no diff. Re-enumeration here can move field indices,
        //    so resolve `idx`/`changed_node` afterwards.
        let interactive = self.ensure_interactive();

        let idx = *self
            .by_name
            .get(name)
            .ok_or_else(|| XfaError::FieldNotFound(name.to_string()))?;
        let changed_node = self.fields[idx].node;
        let field_type = self.models[idx].field_type;
        let page_count_before = self.layout.pages.len();

        // 1. Phase-1 value write (tree + datasets + form-packet sync).
        let set = self.set_value(name, value)?;

        // 2. Interactive script dispatch (change/click + calculate). The
        //    runtime is constructed for this commit and dropped — the resulting
        //    presence/value state lives in `self.tree`.
        let (scripts_executed, presence_changes) = if interactive {
            self.dispatch_commit(changed_node, field_type)?
        } else {
            (0, Vec::new())
        };

        // 3. Re-layout + re-enumerate against the mutated tree.
        self.relayout_and_reenumerate()?;

        // 4. Values the scripts wrote go to the datasets too, so a save keeps
        //    them and a static open shows them.
        if interactive {
            self.persist_script_values(name)?;
        }

        Ok(XfaCommitOutcome {
            set,
            interactive: self.interactive,
            scripts_executed,
            page_count_before,
            page_count_after: self.layout.pages.len(),
            presence_changes,
        })
    }

    /// Scripts that did not run, over the whole session so far: FormCalc and
    /// other non-JavaScript scripts that were due, and JavaScript scripts that
    /// threw, timed out or were refused. Each script is counted once. Empty
    /// until the session is interactive.
    pub fn script_report(&self) -> &XfaScriptReport {
        &self.script_report
    }

    /// Write every field whose value differs from the parsed document, other
    /// than `committed` (which `set_value` already wrote), to the datasets.
    fn persist_script_values(&mut self, committed: &str) -> Result<()> {
        let changed: Vec<(usize, String)> = self
            .models
            .iter()
            .enumerate()
            .filter(|(_, m)| m.name != committed)
            .filter(|(_, m)| self.baseline_values.get(&m.name) != Some(&m.value))
            .map(|(i, m)| (i, m.value.clone()))
            .collect();
        for (idx, value) in changed {
            self.persist_value(idx, &value)?;
        }
        Ok(())
    }

    /// Lazily upgrade the session to interactive mode: construct a sandboxed
    /// runtime, run the interactive open lifecycle (presence writes land),
    /// drop the runtime, and re-layout/re-enumerate. Idempotent. Returns
    /// whether interactive mode is active afterwards (false when the feature is
    /// not compiled in). The runtime is not retained (keeps `XfaSession: Send`);
    /// the resulting initial state lives in `self.tree`.
    fn ensure_interactive(&mut self) -> bool {
        if self.interactive {
            return true;
        }
        #[cfg(feature = "xfa-js-sandboxed")]
        {
            let Ok(mut runtime) = crate::js_runtime::SandboxedRuntime::new() else {
                return false;
            };
            if let Ok((_, report)) = crate::dynamic::apply_interactive_open_reported(
                &mut self.tree,
                self.root_id,
                &mut runtime,
            ) {
                self.script_report.merge(report);
            }
            drop(runtime);
            self.interactive = true;
            // The open lifecycle may have toggled presence — realise it.
            let _ = self.relayout_and_reenumerate();
            true
        }
        #[cfg(not(feature = "xfa-js-sandboxed"))]
        {
            false
        }
    }

    /// Dispatch the interactive commit for one edited field: construct a
    /// runtime, fire its `change`/`click` scripts + a global `calculate` pass,
    /// drop the runtime. Returns `(scripts_executed, presence_changes)`.
    /// Only reached when interactive mode is active (feature compiled in).
    fn dispatch_commit(
        &mut self,
        changed_node: FormNodeId,
        field_type: XfaFieldType,
    ) -> Result<(usize, Vec<PresenceChange>)> {
        #[cfg(feature = "xfa-js-sandboxed")]
        {
            // Buttons/checkboxes/radios fire `click`; everything fires `change`.
            let triggers: &[InteractiveTrigger] = match field_type {
                XfaFieldType::Checkbox | XfaFieldType::RadioGroup | XfaFieldType::Button => {
                    &[InteractiveTrigger::Click, InteractiveTrigger::Change]
                }
                _ => &[InteractiveTrigger::Change],
            };
            let Ok(mut runtime) = crate::js_runtime::SandboxedRuntime::new() else {
                return Ok((0, Vec::new()));
            };
            let (outcome, report) = crate::dynamic::apply_interactive_commit_reported(
                &mut self.tree,
                self.root_id,
                changed_node,
                triggers,
                &mut runtime,
            )?;
            self.script_report.merge(report);
            Ok((outcome.scripts_executed, outcome.presence_changes))
        }
        #[cfg(not(feature = "xfa-js-sandboxed"))]
        {
            let _ = (changed_node, field_type);
            Ok((0, Vec::new()))
        }
    }

    /// Re-run layout against the current (script-mutated) tree and rebuild the
    /// field/page model. `LayoutEngine::layout` is a pure function of the tree
    /// and `enumerate_fields` clears-then-rebuilds, so this is safe to repeat.
    fn relayout_and_reenumerate(&mut self) -> Result<()> {
        let layout = LayoutEngine::new(&self.tree)
            .layout(self.root_id)
            .map_err(|e| XfaError::LayoutFailed(e.to_string()))?;
        self.layout = layout;
        // enumerate_fields rebuilds `fields`; clear first so it does not append.
        self.fields.clear();
        self.enumerate_fields(self.root_id);
        Ok(())
    }

    /// Serialize the updated datasets (and form-packet value syncs) into a
    /// copy of the original PDF and return the new bytes.
    pub fn save_to_bytes(&self) -> Result<Vec<u8>> {
        let mut doc = Document::load_mem(&self.pdf_bytes)
            .map_err(|e| XfaError::LoadFailed(format!("reload for writeback: {e}")))?;
        self.write_into_document(&mut doc)?;
        let mut out = Vec::new();
        doc.save_to(&mut out)
            .map_err(|e| XfaError::WritebackFailed(format!("PDF save: {e}")))?;
        Ok(out)
    }

    /// Apply the datasets/form-packet writeback to an already-loaded
    /// `lopdf::Document` (the SDK facade path: the caller owns the document
    /// and serializes it itself).
    pub fn write_into_document(&self, doc: &mut Document) -> Result<XfaWritebackReport> {
        let mut report = XfaWritebackReport::default();

        // Build the new datasets packet: surgical splice of the original
        // packet text, falling back to data-section regeneration.
        let edits = self.collect_datasets_edits();
        let original_datasets = self.packets.datasets();
        let new_datasets = match original_datasets {
            Some(orig) => match datasets_writeback::splice_datasets(orig, &edits) {
                Some(spliced) => {
                    report.datasets_spliced = true;
                    spliced
                }
                None => datasets_writeback::regenerate_datasets(orig, &self.data_dom),
            },
            None => datasets_writeback::regenerate_datasets("", &self.data_dom),
        };

        // Saved form packet: keep recorded field values in sync.
        let new_form = self.packets.get_packet("form").and_then(|orig| {
            if self.form_packet_sync.is_empty() {
                return None;
            }
            let (xml, updated) =
                datasets_writeback::splice_form_packet(orig, &self.form_packet_sync);
            report.form_packet_values_updated = updated;
            if updated > 0 {
                Some(xml)
            } else {
                None
            }
        });

        datasets_writeback::write_packets_into_pdf(doc, &new_datasets, new_form.as_deref())?;
        Ok(report)
    }

    /// True when any value was changed since the session opened.
    pub fn is_dirty(&self) -> bool {
        !self.dirty_data.is_empty()
            || !self.created_data.is_empty()
            || !self.form_packet_sync.is_empty()
    }

    // ── internals ──────────────────────────────────────────────────────

    fn normalize_value(&self, idx: usize, value: XfaWriteValue<'_>, name: &str) -> Result<String> {
        let model = &self.models[idx];
        match (model.field_type, value) {
            (XfaFieldType::Checkbox, XfaWriteValue::Checkbox(on)) => Ok(if on {
                model.on_value.clone().unwrap_or_else(|| "1".to_string())
            } else {
                model.off_value.clone().unwrap_or_else(|| "0".to_string())
            }),
            (XfaFieldType::Checkbox, XfaWriteValue::Text(s)) => {
                let on_v = model.on_value.clone().unwrap_or_else(|| "1".to_string());
                let off_v = model.off_value.clone().unwrap_or_else(|| "0".to_string());
                if s == on_v || s.eq_ignore_ascii_case("true") || s == "1" {
                    Ok(on_v)
                } else if s == off_v || s.eq_ignore_ascii_case("false") || s == "0" || s.is_empty()
                {
                    Ok(off_v)
                } else {
                    Err(XfaError::InvalidFieldValue {
                        name: name.to_string(),
                        reason: format!("checkbox accepts {on_v:?} or {off_v:?}, got {s:?}"),
                    })
                }
            }
            (XfaFieldType::RadioGroup, XfaWriteValue::Radio(s))
            | (XfaFieldType::RadioGroup, XfaWriteValue::Text(s)) => {
                let known = self.fields[idx].members.iter().any(|(_, on)| on == s);
                if known {
                    Ok(s.to_string())
                } else {
                    let opts: Vec<&str> = self.fields[idx]
                        .members
                        .iter()
                        .map(|(_, on)| on.as_str())
                        .collect();
                    Err(XfaError::InvalidFieldValue {
                        name: name.to_string(),
                        reason: format!("radio accepts one of {opts:?}, got {s:?}"),
                    })
                }
            }
            (XfaFieldType::Dropdown, XfaWriteValue::Text(s)) => {
                if model.options.is_empty() {
                    return Ok(s.to_string());
                }
                if let Some(opt) = model.options.iter().find(|o| o.save == s) {
                    return Ok(opt.save.clone());
                }
                if let Some(opt) = model.options.iter().find(|o| o.display == s) {
                    return Ok(opt.save.clone());
                }
                // XFA choice lists may allow free entry; the template parser
                // does not currently surface `open="..."`, so accept unknown
                // values rather than over-rejecting.
                Ok(s.to_string())
            }
            (_, XfaWriteValue::Text(s)) => Ok(s.to_string()),
            (ft, v) => Err(XfaError::InvalidFieldValue {
                name: name.to_string(),
                reason: format!("{v:?} is not assignable to a {ft:?} field"),
            }),
        }
    }

    fn write_tree_value(&mut self, idx: usize, raw: &str) {
        let entry = &self.fields[idx];
        if entry.members.is_empty() {
            let id = entry.node;
            if let FormNodeType::Field { .. } = self.tree.get(id).node_type {
                self.tree.get_mut(id).node_type = FormNodeType::Field {
                    value: raw.to_string(),
                };
            }
        } else {
            // exclGroup: the group node itself carries the selected on-value
            // (so `this.rawValue` in a change script reads the new selection),
            // the matching member gets the value, and every other member is
            // cleared (mirrors the merger's apply_exclusive_choice_value).
            let group = entry.node;
            if let FormNodeType::Field { .. } = self.tree.get(group).node_type {
                self.tree.get_mut(group).node_type = FormNodeType::Field {
                    value: raw.to_string(),
                };
            }
            let members = entry.members.clone();
            for (member, on_value) in members {
                let new_value = if on_value == raw {
                    raw.to_string()
                } else {
                    String::new()
                };
                if let FormNodeType::Field { .. } = self.tree.get(member).node_type {
                    self.tree.get_mut(member).node_type = FormNodeType::Field { value: new_value };
                }
            }
        }
    }

    /// Write through to the datasets DOM. Returns `true` when the value is
    /// now held by a data node (existing or created).
    /// Write a field's value through to the datasets DOM and record the
    /// saved-form-packet sync. Shared by [`set_value`](Self::set_value) and the
    /// script-written values a commit persists. Returns whether the value
    /// reached a datasets node.
    fn persist_value(&mut self, idx: usize, raw: &str) -> Result<bool> {
        let persisted = self.write_data_value(idx, raw)?;

        // Saved-form-packet value sync (recorded; spliced at save time).
        if self.packets.get_packet("form").is_some() {
            let segments = self.fields[idx].segments.clone();
            // Drop earlier edits for this field (group prefix covers the
            // radio-member edits too).
            self.form_packet_sync
                .retain(|e| !e.segments.starts_with(&segments));
            if self.fields[idx].members.is_empty() {
                self.form_packet_sync.push(FormPacketEdit {
                    segments,
                    value: raw.to_string(),
                    insert_if_missing: true,
                });
            } else {
                // Radio group: the saved form DOM stores the selection on
                // the member fields — the selected member carries the
                // on-value, deselected members are cleared. Also refresh a
                // group-level <value> when the producer wrote one.
                for (member, on) in self.fields[idx].members.clone() {
                    let mut member_segments = segments.clone();
                    member_segments.push((self.tree.get(member).name.clone(), 0));
                    let selected = on == raw;
                    self.form_packet_sync.push(FormPacketEdit {
                        segments: member_segments,
                        value: if selected {
                            raw.to_string()
                        } else {
                            String::new()
                        },
                        insert_if_missing: selected,
                    });
                }
                self.form_packet_sync.push(FormPacketEdit {
                    segments,
                    value: raw.to_string(),
                    insert_if_missing: false,
                });
            }
        }
        Ok(persisted)
    }

    fn write_data_value(&mut self, idx: usize, raw: &str) -> Result<bool> {
        let entry_node = self.fields[idx].node;
        if self.tree.meta(entry_node).data_bind_none {
            // `bind match="none"` — by design not persisted in datasets.
            return Ok(false);
        }

        if let Some(raw_id) = self.tree.meta(entry_node).bound_data_node {
            let id = DataNodeId::from_raw(raw_id);
            match self.data_dom.get(id) {
                Some(DataNode::DataValue { .. }) => {
                    self.data_dom
                        .set_value(id, raw.to_string())
                        .map_err(|e| XfaError::WritebackFailed(e.to_string()))?;
                    if !self.dirty_data.contains(&id) {
                        self.dirty_data.push(id);
                    }
                    return Ok(true);
                }
                Some(DataNode::DataGroup { .. }) => {
                    // Container-bound (e.g. an exclGroup bound to a group):
                    // fall through to create/find a value child below.
                }
                None => return Ok(false),
            }
        }

        // No directly bound value node: create one on demand under the
        // nearest bound ancestor (XFA default binding by name).
        let created = self.create_data_node_for(idx, raw)?;
        Ok(created)
    }

    fn create_data_node_for(&mut self, idx: usize, raw: &str) -> Result<bool> {
        let field_node = self.fields[idx].node;
        let data_name = self.tree.get(field_node).name.clone();
        if data_name.is_empty() {
            return Ok(false);
        }

        // Find the nearest ancestor (or the node itself when group-bound)
        // with a bound data *group*.
        let mut parent_group: Option<DataNodeId> = None;
        // The node itself may be bound to a group (exclGroup case).
        if let Some(raw_id) = self.tree.meta(field_node).bound_data_node {
            let id = DataNodeId::from_raw(raw_id);
            if matches!(self.data_dom.get(id), Some(DataNode::DataGroup { .. })) {
                // The group IS the field's data home: a value child named
                // like the field is the XFA §4.4.5 group-value convention —
                // but Designer datasets normally store the exclGroup value
                // directly on the group-named *value* node. Prefer an
                // existing value child named like the field, else write a
                // value child with the field's name.
                parent_group = Some(id);
            }
        }
        if parent_group.is_none() {
            let mut cursor = self.parent_of(field_node);
            while let Some(p) = cursor {
                if let Some(raw_id) = self.tree.meta(p).bound_data_node {
                    let id = DataNodeId::from_raw(raw_id);
                    if matches!(self.data_dom.get(id), Some(DataNode::DataGroup { .. })) {
                        parent_group = Some(id);
                        break;
                    }
                }
                cursor = self.parent_of(p);
            }
        }
        if parent_group.is_none() {
            // No bound ancestor at all (empty or absent datasets): synthesize
            // the group chain from the data root along the field's named
            // path — the same tree Adobe Reader creates on first save.
            // Explicit `<bind ref>` fields are skipped: their data home is
            // not the name chain.
            if self.tree.meta(field_node).data_bind_ref.is_none() {
                parent_group = self.synthesize_group_chain(idx)?;
            }
        }
        let Some(group) = parent_group else {
            return Ok(false);
        };

        // Reuse an existing same-name child value node when present.
        let existing = self
            .data_dom
            .children_by_name(group, &data_name)
            .into_iter()
            .find(|&c| matches!(self.data_dom.get(c), Some(DataNode::DataValue { .. })));
        let id = match existing {
            Some(c) => {
                self.data_dom
                    .set_value(c, raw.to_string())
                    .map_err(|e| XfaError::WritebackFailed(e.to_string()))?;
                if !self.dirty_data.contains(&c) {
                    self.dirty_data.push(c);
                }
                self.tree.meta_mut(self.fields[idx].node).bound_data_node = Some(c.as_raw());
                return Ok(true);
            }
            None => self
                .data_dom
                .create_value(group, &data_name, raw)
                .map_err(|e| XfaError::WritebackFailed(e.to_string()))?,
        };
        self.created_data.push(id);
        self.tree.meta_mut(self.fields[idx].node).bound_data_node = Some(id.as_raw());
        Ok(true)
    }

    /// Create (or find) the data-group chain `root → seg[0] → … → seg[n-2]`
    /// for the field at `idx`, creating a `<data>` root when the DataDom is
    /// empty. Returns the deepest group, or `None` when an indexed segment
    /// (`name[i>0]`) is missing — repeated-instance synthesis is out of
    /// Phase-1 scope.
    fn synthesize_group_chain(&mut self, idx: usize) -> Result<Option<DataNodeId>> {
        let segments = self.fields[idx].segments.clone();
        if segments.len() < 2 {
            // A root-level field still needs a root group to live under.
            if segments.is_empty() {
                return Ok(None);
            }
        }

        let root = match self.data_dom.root() {
            Some(r)
                if self
                    .data_dom
                    .get(r)
                    .map(DataNode::is_group)
                    .unwrap_or(false) =>
            {
                r
            }
            _ => {
                let r = self.data_dom.alloc(DataNode::DataGroup {
                    name: "data".to_string(),
                    namespace: None,
                    children: Vec::new(),
                    is_record: false,
                    parent: None,
                });
                self.data_dom.set_root(r);
                r
            }
        };

        let mut cursor = root;
        for (name, index) in &segments[..segments.len() - 1] {
            let groups: Vec<DataNodeId> = self
                .data_dom
                .children_by_name(cursor, name)
                .into_iter()
                .filter(|&c| {
                    self.data_dom
                        .get(c)
                        .map(DataNode::is_group)
                        .unwrap_or(false)
                })
                .collect();
            cursor = match groups.get(*index) {
                Some(&g) => g,
                None if *index == 0 => self
                    .data_dom
                    .create_group(cursor, name)
                    .map_err(|e| XfaError::WritebackFailed(e.to_string()))?,
                None => return Ok(None),
            };
        }
        Ok(Some(cursor))
    }

    fn parent_of(&self, node: FormNodeId) -> Option<FormNodeId> {
        // FormTree stores no parent links; derive lazily from the arena.
        for (i, n) in self.tree.nodes.iter().enumerate() {
            if n.children.contains(&node) {
                return Some(FormNodeId(i));
            }
        }
        None
    }

    fn collect_datasets_edits(&self) -> Vec<DatasetsEdit> {
        let mut edits = Vec::new();
        for &id in &self.dirty_data {
            if let Some(path) = self.data_path_of(id) {
                if let Ok(value) = self.data_dom.value(id) {
                    edits.push(DatasetsEdit::SetValue {
                        path,
                        value: value.to_string(),
                    });
                }
            }
        }
        for &id in &self.created_data {
            let Some(node) = self.data_dom.get(id) else {
                continue;
            };
            let name = node.name().to_string();
            let Some(parent) = node.parent() else {
                continue;
            };
            let Some(parent_path) = self.data_path_of(parent) else {
                continue;
            };
            if let Ok(value) = self.data_dom.value(id) {
                edits.push(DatasetsEdit::CreateValue {
                    parent_path,
                    name,
                    value: value.to_string(),
                });
            }
        }
        edits
    }

    /// Path of `(name, index-among-same-name-element-siblings)` segments
    /// from the data root down to `id`. The root itself is segment 0; the
    /// upward walk stops there (the parse may keep wrapper parents like
    /// `<xfa:datasets>` linked above the effective root).
    fn data_path_of(&self, id: DataNodeId) -> Option<Vec<(String, usize)>> {
        let root = self.data_dom.root()?;
        let mut rev = Vec::new();
        let mut cursor = Some(id);
        while let Some(c) = cursor {
            let node = self.data_dom.get(c)?;
            let name = node.name().to_string();
            let at_root = c == root;
            let parent = if at_root { None } else { node.parent() };
            let index = match parent {
                Some(p) => {
                    // Index among same-name siblings, skipping nodes the
                    // splicer cannot see as XML elements (attribute-derived
                    // metadata values).
                    let mut k = 0usize;
                    let mut found = None;
                    for &sib in self.data_dom.children(p) {
                        let Some(sn) = self.data_dom.get(sib) else {
                            continue;
                        };
                        if sn.name() != name {
                            continue;
                        }
                        if is_metadata_value(sn) {
                            continue;
                        }
                        if sib == c {
                            found = Some(k);
                            break;
                        }
                        k += 1;
                    }
                    found?
                }
                None => 0,
            };
            rev.push((name, index));
            if at_root {
                cursor = None;
            } else {
                // A node that never reaches the effective root (e.g. it
                // lives under a wrapper sibling) cannot be spliced by a
                // root-relative path.
                cursor = Some(node.parent()?);
            }
        }
        rev.reverse();
        Some(rev)
    }

    // ── enumeration ─────────────────────────────────────────────────────

    fn enumerate_fields(&mut self, root: FormNodeId) {
        // Geometry first: form node → widget occurrences.
        let mut geometry: HashMap<usize, Vec<(usize, XfaRect)>> = HashMap::new();
        for (page_idx, page) in self.layout.pages.iter().enumerate() {
            for node in &page.nodes {
                collect_geometry(node, 0.0, 0.0, page_idx, &mut geometry);
            }
        }

        let mut entries = Vec::new();
        let mut segments: Vec<(String, usize)> = Vec::new();
        let mut sibling_counters: Vec<HashMap<String, usize>> = vec![HashMap::new()];
        // The merged tree's root is a synthetic container (named "root");
        // Adobe SOM names start at the template's root subform, so walk the
        // root's children instead of the root itself.
        let root_access = self.tree.meta(root).access.unwrap_or(Access::Open);
        for &child in &self.tree.get(root).children.clone() {
            self.walk_enumerate(
                child,
                root_access,
                &mut segments,
                &mut sibling_counters,
                &mut entries,
            );
        }

        let mut models = Vec::new();
        let mut by_name: HashMap<String, usize> = HashMap::new();
        for entry in entries {
            let model = self.build_model(&entry, &geometry);
            let idx = models.len();
            // First registration wins; later duplicates stay addressable via
            // their explicit SOM path.
            by_name.entry(model.name.clone()).or_insert(idx);
            by_name.entry(model.som_path.clone()).or_insert(idx);
            models.push(model);
            self.fields.push(entry);
        }
        self.models = models;
        self.by_name = by_name;
    }

    #[allow(clippy::too_many_arguments)]
    fn walk_enumerate(
        &self,
        node_id: FormNodeId,
        inherited_access: Access,
        segments: &mut Vec<(String, usize)>,
        sibling_counters: &mut Vec<HashMap<String, usize>>,
        out: &mut Vec<FieldEntry>,
    ) {
        let node = self.tree.get(node_id);
        let meta = self.tree.meta(node_id);
        let access = meta.access.unwrap_or(inherited_access);

        let named = !node.name.is_empty();
        if named {
            let counter = sibling_counters
                .last_mut()
                .expect("sibling counter scope present");
            let idx = *counter
                .entry(node.name.clone())
                .and_modify(|c| *c += 1)
                .or_insert(0);
            segments.push((node.name.clone(), idx));
        }

        let is_radio_group = matches!(node.node_type, FormNodeType::ExclGroup)
            || meta.group_kind == GroupKind::ExclusiveChoice;
        let is_field = matches!(node.node_type, FormNodeType::Field { .. });

        if is_radio_group {
            let mut members = Vec::new();
            for &child in &node.children {
                if let FormNodeType::Field { .. } = self.tree.get(child).node_type {
                    let cmeta = self.tree.meta(child);
                    let on = cmeta
                        .item_value
                        .clone()
                        .or_else(|| cmeta.style.check_button_on_value.clone())
                        .unwrap_or_else(|| self.tree.get(child).name.clone());
                    members.push((child, on));
                }
            }
            if !members.is_empty() {
                out.push(FieldEntry {
                    node: node_id,
                    members,
                    read_only: access.denies_writes(),
                    segments: segments.clone(),
                });
            }
        } else if is_field {
            out.push(FieldEntry {
                node: node_id,
                members: Vec::new(),
                read_only: access.denies_writes(),
                segments: segments.clone(),
            });
        }

        // Recurse into containers (not into exclGroup members or field
        // internals — members are folded into the group entry above).
        if !is_field && !is_radio_group {
            sibling_counters.push(HashMap::new());
            for &child in &node.children {
                self.walk_enumerate(child, access, segments, sibling_counters, out);
            }
            sibling_counters.pop();
        }

        if named {
            segments.pop();
        }
    }

    fn build_model(
        &self,
        entry: &FieldEntry,
        geometry: &HashMap<usize, Vec<(usize, XfaRect)>>,
    ) -> XfaFieldModel {
        let node = self.tree.get(entry.node);
        let meta = self.tree.meta(entry.node);

        let name = segments_to_display_name(&entry.segments);
        let som_path = segments_to_som_path(&entry.segments);

        let field_type = if entry.members.is_empty() {
            XfaFieldType::from_kind(meta.field_kind)
        } else {
            XfaFieldType::RadioGroup
        };

        // Value: field raw value, or selected member's on-value for groups.
        let value = if entry.members.is_empty() {
            match &node.node_type {
                FormNodeType::Field { value } => value.clone(),
                _ => String::new(),
            }
        } else {
            entry
                .members
                .iter()
                .find_map(|(m, on)| match &self.tree.get(*m).node_type {
                    FormNodeType::Field { value } if !value.is_empty() && value == on => {
                        Some(on.clone())
                    }
                    _ => None,
                })
                .unwrap_or_default()
        };

        // Options.
        let options = if !entry.members.is_empty() {
            entry
                .members
                .iter()
                .map(|(_, on)| XfaFieldOption {
                    display: on.clone(),
                    save: on.clone(),
                })
                .collect()
        } else {
            let displays = &meta.display_items;
            let saves = &meta.save_items;
            displays
                .iter()
                .enumerate()
                .map(|(i, d)| XfaFieldOption {
                    display: d.clone(),
                    save: saves.get(i).cloned().unwrap_or_else(|| d.clone()),
                })
                .collect()
        };

        let on_value = meta
            .style
            .check_button_on_value
            .clone()
            .or_else(|| meta.item_value.clone());
        let off_value = meta.style.check_button_off_value.clone();

        // Geometry: the group node's own rect plus member rects.
        let mut widgets: Vec<XfaWidget> = Vec::new();
        if let Some(occ) = geometry.get(&entry.node.0) {
            for (page, rect) in occ {
                widgets.push(XfaWidget {
                    page: *page,
                    rect: *rect,
                    on_value: None,
                });
            }
        }
        for (member, on) in &entry.members {
            if let Some(occ) = geometry.get(&member.0) {
                for (page, rect) in occ {
                    widgets.push(XfaWidget {
                        page: *page,
                        rect: *rect,
                        on_value: Some(on.clone()),
                    });
                }
            }
        }
        widgets.sort_by(|a, b| {
            a.page.cmp(&b.page).then(
                a.rect
                    .y
                    .partial_cmp(&b.rect.y)
                    .unwrap_or(std::cmp::Ordering::Equal),
            )
        });
        let page = widgets.first().map(|w| w.page);
        let rect = widgets.first().map(|w| w.rect);

        let bound = meta
            .bound_data_node
            .map(|raw| self.data_dom.get(DataNodeId::from_raw(raw)).is_some())
            .unwrap_or(false);

        XfaFieldModel {
            name,
            som_path,
            field_type,
            value,
            read_only: entry.read_only,
            required: meta.required,
            multiline: meta.multiline,
            hidden: meta.presence != Presence::Visible,
            options,
            on_value,
            off_value,
            page,
            rect,
            widgets,
            bound_to_data: bound,
            bind_none: meta.data_bind_none,
        }
    }
}

fn is_metadata_value(node: &DataNode) -> bool {
    match node {
        DataNode::DataValue { contains, .. } => {
            *contains == xfa_dom_resolver::data_dom::DataContains::MetaData
        }
        DataNode::DataGroup { .. } => false,
    }
}

fn segments_to_display_name(segments: &[(String, usize)]) -> String {
    segments
        .iter()
        .map(|(n, i)| {
            if *i == 0 {
                n.clone()
            } else {
                format!("{n}[{i}]")
            }
        })
        .collect::<Vec<_>>()
        .join(".")
}

fn segments_to_som_path(segments: &[(String, usize)]) -> String {
    segments
        .iter()
        .map(|(n, i)| format!("{n}[{i}]"))
        .collect::<Vec<_>>()
        .join(".")
}

/// Accumulate absolute widget rectangles per form node.
///
/// Layout coordinates are parent-relative (the render bridge accumulates
/// them the same way); rectangles are reported in XFA page space (top-left
/// origin, points).
fn collect_geometry(
    node: &LayoutNode,
    parent_x: f64,
    parent_y: f64,
    page_idx: usize,
    out: &mut HashMap<usize, Vec<(usize, XfaRect)>>,
) {
    let abs_x = node.rect.x + parent_x;
    let abs_y = node.rect.y + parent_y;

    let record = matches!(node.content, LayoutContent::Field { .. })
        || matches!(
            node.content,
            LayoutContent::WrappedText {
                from_field: true,
                ..
            }
        );
    if record {
        out.entry(node.form_node.0).or_default().push((
            page_idx,
            XfaRect {
                x: abs_x,
                y: abs_y,
                width: node.rect.width,
                height: node.rect.height,
            },
        ));
    }

    for child in &node.children {
        collect_geometry(child, abs_x, abs_y, page_idx, out);
    }
}

/// Apply `access="…"` attributes from the saved form packet onto matching
/// form-tree nodes (session-only pass; the flatten pipeline ignores access).
///
/// Adobe Reader records interactive locks (e.g. fields disabled after
/// submission) as `access="readOnly"` in the form packet. Without this pass
/// the session would let callers write fields Acrobat refuses to edit.
fn apply_form_dom_access(tree: &mut FormTree, root_id: FormNodeId, form_xml: &str) {
    let Ok(doc) = roxmltree::Document::parse(form_xml) else {
        return;
    };

    fn matches_node(tree: &FormTree, fid: FormNodeId, tag: &str, name: &str) -> bool {
        let node = tree.get(fid);
        match (tag, &node.node_type) {
            ("subform", FormNodeType::Subform | FormNodeType::Area) => node.name == name,
            ("exclGroup", FormNodeType::ExclGroup) => node.name == name,
            // Some producers serialize exclGroups as <field> in the form DOM.
            ("field", FormNodeType::Field { .. } | FormNodeType::ExclGroup) => node.name == name,
            _ => false,
        }
    }

    fn walk(tree: &mut FormTree, fid: FormNodeId, xml: roxmltree::Node<'_, '_>) {
        if let Some(access) = xml.attribute("access") {
            tree.meta_mut(fid).access = Some(Access::parse(access));
        }

        let xml_children: Vec<roxmltree::Node<'_, '_>> = xml
            .children()
            .filter(|c| {
                c.is_element() && matches!(c.tag_name().name(), "subform" | "field" | "exclGroup")
            })
            .collect();
        if xml_children.is_empty() {
            return;
        }

        let tree_children = tree.get(fid).children.clone();
        let mut used = vec![false; tree_children.len()];
        for xc in xml_children {
            let tag = xc.tag_name().name();
            let name = xc.attribute("name").unwrap_or("");
            if name.is_empty() {
                continue;
            }
            for (i, &cid) in tree_children.iter().enumerate() {
                if used[i] || !matches_node(tree, cid, tag, name) {
                    continue;
                }
                used[i] = true;
                walk(tree, cid, xc);
                break;
            }
        }
    }

    // The form packet root is <form> (sometimes namespaced); its element
    // children mirror the template root subform's children. The template
    // FormTree root is the <template> wrapper whose first child is the root
    // subform — align by descending one level when the names don't match.
    let Some(form_root) = doc.root().children().find(|c| c.is_element()) else {
        return;
    };
    // Try matching the root subform: the form packet's first subform child
    // corresponds to the tree root's subform child of the same name.
    let root_children = tree.get(root_id).children.clone();
    let packet_subforms: Vec<roxmltree::Node<'_, '_>> = form_root
        .children()
        .filter(|c| c.is_element() && c.tag_name().name() == "subform")
        .collect();
    for xc in packet_subforms {
        let name = xc.attribute("name").unwrap_or("");
        for &cid in &root_children {
            if matches_node(tree, cid, "subform", name) {
                walk(tree, cid, xc);
                break;
            }
        }
    }
}