[lfals]

Resolves: #85

Stacked on: #164 (feat/84-form-field-widget-model)

📝 Summary

Builds the editor-level foundation for form fields on top of the #84 field/widget model. Adds a plain TypeScript editing session that creates/places/selects/updates logical fields and visual widgets, optionally syncing to the existing overlay API without depending on Vue internals.

API	Responsibility
createFormEditor	Session owning PDFFormModel, selection, placement lifecycle, field/widget updates
createFormEditorOverlayAdapter	Bridge to PDFElementsPublicApi with id recovery and silent spill restore
PDFElements.moveObjectToPage	Relocate an overlay without emitting pdf-elements:delete-object

Supports one logical field ↔ N widgets, shared vs widget-specific properties, interactive placement via adding-ended, and model/overlay rollback when geometry updates are rejected.

Concrete per-type UX (text/checkbox/radio/dropdown), AcroForm parse/write, signing and LibreSign/Nextcloud workflow concepts remain outside scope.

Also adds:

• public docs in docs/FORM_EDITING.md plus API/README cross-links
• unit and overlay-integration coverage for identity, sync, spill restore and host delete wiring
• five council review rounds addressing identity, sync and spill/delete findings

🧪 How to test

1. Check public types and lint:

   npm run typecheck
   npm run lint

2. Run focused form-editing coverage:

   npm run test -- tests/utils/formEditing.spec.ts tests/components/formEditing.overlay.spec.ts

   Expected: 24 tests pass, including multi-widget fields, overlay id recovery, spill restore without delete-object, and duplicate elementId rejection.
3. Run the full unit suite and build:

   npm run test
   npm run build
   npm run validate:dist

   Expected: 128 unit tests pass; build and PDF.js distribution validation succeed.
4. Optional demo smoke check:

   npm run dev

   Existing overlay editing remains available. Form editing is a public session API; per-type UI belongs to follow-up work.

Validation evidence

• Focused regression/acceptance tests
• Relevant lint and type checks
• Full unit suite: 128 tests passed
• Production build and PDF.js distribution validation
• Local act for Node CI and Tests workflows
• CI reviewed

⚙️ Public API changes

• createFormEditor / createFormEditorOverlayAdapter exported publicly
• Field-level and widget-level editing kept clearly separated
• Multiple widgets per logical field supported
• Overlay sync optional; generic non-form overlays remain compatible
• moveObjectToPage added for silent page relocation
• Unit and overlay-integration tests added for shared editing behavior
• Public editing docs and migration/host wiring guidance added
• Authorization/capabilities: not applicable to this editor-foundation change.

🚧 Tasks

• Follow the public field/widget model from Define a stable form field and widget data model #84
• Provide reusable create/place/select/update editing behavior
• Keep field-level and widget-level properties separated
• Support multiple widgets for the same logical field
• Expose behavior without depending on internal Vue state
• Complete council review rounds and address blocking findings
• CI review on the draft PR

✅ Checklist

• I have read and followed the contribution guide.
• The diff does not contain unrelated refactors or generated changes.
• Commits follow Conventional Commits.
• New source files include SPDX headers.
• All commits include DCO sign-off.

🤖 AI (if applicable)

• The content of this PR was partially or fully generated using AI.