M12: forms show and add pages from page templates (#1429)

## What this changes

Part of #1429. The form in that report keeps pages it shows on demand as **page templates**: the name dictionary's `/Templates` tree names pages kept out of the page tree, and `/Pages` names visible ones (ISO 32000-2 §7.7.4). Until now their fields were listed as unplaced, and the form's JavaScript could not reach them, so buttons that add a page or show a section did nothing.

- **organize**: `templates`, `spawn_template` and `set_template_hidden`.
  - A spawned page is a copy of the template page.
  - With renaming, its fields become fields of their own under `P<page>.<template>.<name>`.
  - Without renaming, its widgets join the template's fields and share their values. A template field that is its own widget is split into field + widget first.
  - Hiding a template takes its page out of the tree, keeps what it inherited (MediaBox, Resources, …) and refuses to hide the last page.
- **js**: `this.templates`, `getTemplate(name)`, `Template.name`, `Template.hidden` (setting it shows or hides the page), `Template.spawn(nPage, bRename, bOverlay)` and `spawnPageFromTemplate`, with positional or named arguments and the documented defaults (0 / true / true). Non-number pages are clamped.
- **engine**: new `Edit::SpawnTemplate` and `Edit::SetTemplateHidden`.
  - Both are checked against the assemble permission and applied in the same undo step as the script's field changes.
  - Only a button's or the console's script may change the pages. A field's own scripts (format, keystroke, validate, calculate) are told so on the console.
  - At most 100 template pages per script run, because each spawn copies the document. A loop that asks for more stops there with one console note.
- **automation**: `page_templates` (read-only), `page_template_spawn` and `page_template_set_hidden`.
- Undo labels translated in all 34 catalogues.

Not in this PR:
- `bOverlay` true (laying a template over an existing page). The script is told so on the console once and nothing changes.
- `createTemplate` / `removeTemplate`.
- An Organize-panel UI for templates.
- `numPages` is not updated inside the running script.
- Mouse Up actions on radio buttons and checkboxes (the other half of #1429) are in the open #2546.

## How you verified it

- [x] `cargo fmt --check`
- [x] clippy with `-D warnings` on the crates I changed (organize, js, engine, automation, ui-egui)
- [x] tests pass on the crates I changed

  | Crate | Result |
  |---|---|
  | organize | 188 passed |
  | js | 97 passed |
  | engine lib | 382 passed |
  | engine it | 21 passed |
  | automation | 45 + 282 passed |
  | ui-egui i18n | 65 passed |

- [x] `cargo xtask layers`, `cargo xtask assets` and `cargo xtask parity`

**Tests.**
- organize has 9 unit tests: listing, renamed and shared spawns, appending past the end, show/hide, the last page and unknown names refused, hostile template trees, repeated unrenamed copies, and inherited attributes kept when hiding.
- js has 5 tests: listing, `spawn` defaults, both argument forms, `hidden` read back, and clamping.
- engine has 5 integration tests: one undo step, renamed and shared spawns surviving save + reopen, overlay noted, field scripts refused, and the 100-page budget.
- automation has 2 tool tests.

Each behaviour was seen failing by reverting it:
- no renaming
- no field sharing
- no MediaBox fallback
- hidden page dropping inherited attributes
- no budget
- field scripts allowed to spawn
- requests not applied
- wrong default flags

Under a loaded machine `tests::xfa_model::a_slow_engine_start_does_not_count_against_the_script` (an existing timing test) failed once and passes on its own. It is not touched here.

## Never-crash

- [x] No new `unwrap`/`expect`/`panic!`/`unreachable!`/`todo!` outside tests, unless it is provably infallible with a comment saying why
- [x] No indexing or slicing with input-derived positions; checked or saturating arithmetic; allocations sized by input are capped; recursion is bounded
  - Name trees are capped at 4096 names.
  - Field walks are capped at 32 levels and 100 000 nodes, with seen-sets.
  - Spawns are capped at 100 per script run.
  - Template names are clipped and charged to the script's output budget.
- [x] No `unsafe`
- [x] Any crash this fixes has a small synthetic regression test (no crash fixed; the hostile-tree test covers cyclic and malformed `/Templates`)

## Provenance

- [x] No asset from an Adobe product, and no Adobe icon recreated, traced or imitated
- [x] No font files committed here
- [x] No GPL/AGPL code copied in
- [x] Behaviour comes from the specification or black-box observation, **not** from reading another implementation's source. The sources are ISO 32000-2 §7.7.4 and §12.7.6 and the public Acrobat JavaScript API reference for `Template`/`spawnPageFromTemplate`.
- [x] Every new asset has an `ATTRIBUTION.toml` entry and `cargo xtask assets` passes (no new assets)

## Security

- [x] `--root` confinement still holds on every path, including ones reached by nested tool dispatch (the new tools take a document id, no paths)
- [x] MCP and the UI control channel stay opt-in, loopback-only and token-authenticated
- [x] No new outbound network access

## Parity and reach

- [x] `parity/acrobat-features.toml` updated: `organize.page-templates` is now `partial`, with notes on what is still missing
- [x] Reachable headlessly through an `automation` tool (`page_templates`, `page_template_spawn`, `page_template_set_hidden`, and `js_run` for scripts)
- [x] Docs updated if this changes a documented behaviour (crate doc comments)

## Anything a reviewer should look at first

- `share_fields_with_originals` in `crates/organize/src/import/fields.rs`: how an unrenamed copy's widgets are reparented onto the template's fields. When a template field is its own widget, it is split into a field with two widget kids.
- The 100-page budget per script run in `crates/engine/src/js.rs`. Each spawn copies the document, so a `for` loop over `spawn` in a hostile form is bounded there.
This commit is contained in:
Livio Oswald authored and GitHub committed 2026-11-18 16:32:59 +07:00
1 parent 5aae9dbae2
commit 55983f1f92
26 files changed
+1362 -15

No files matched your search

+4 -4
View File
@@ -3307,11 +3307,11 @@ title = "Page templates"
area = "D"
tier = "P3"
milestone = "M12"
status = "planned"
status = "partial"
commands = []
tools = []
evidence = []
notes = ""
tools = ["page_templates", "page_template_spawn", "page_template_set_hidden", "js_run"]
evidence = ["crates/organize/src/templates/tests.rs::a_spawned_page_with_renaming_has_fields_of_its_own", "crates/organize/src/templates/tests.rs::every_unrenamed_copy_is_one_more_widget_of_the_one_field", "crates/organize/src/templates/tests.rs::showing_and_hiding_a_template_moves_its_own_page", "crates/js/src/tests.rs::spawn_asks_for_a_page_from_the_template", "crates/engine/tests/it/page_templates.rs::a_script_adds_pages_from_a_template_renamed_or_shared", "crates/engine/tests/it/page_templates.rs::a_spawning_loop_stops_at_its_page_budget", "crates/automation/tests/it/page_templates.rs::templates_are_listed_spawned_shown_and_hidden_through_tools"]
notes = "Forms' JavaScript reads this.templates and getTemplate(name), adds a page from a template with Template.spawn or spawnPageFromTemplate (nPage, bRename, bOverlay, positional or named; renamed fields go under P<page>.<template>, unrenamed copies are more widgets of the template's fields and share their values) and shows or hides one with Template.hidden (the template's own page moves into or out of the document; /Templates and /Pages name trees, ISO 32000-2 §7.7.4). Only a button's or the console's script may change the pages, as one undo step with its field changes, at most 100 pages per run. Still missing: bOverlay true (laying a template over an existing page; the script is told on the console), creating or removing templates (Doc.createTemplate, removeTemplate) and an Organize Pages ▸ Page templates panel; numPages doesn't change within the script that spawned, and the new page's fields can't be read or set (getField returns null) until that script has finished."
[[feature]]
id = "organize.bookmark-add"