Watermark plugin with alignment, repeat tiling, and XObject-optimised placement

[antonsamper]

Overview

This PR introduces a new @embedpdf/plugin-watermark package and wires it into the React MUI example. It supports text and image watermarks, alignment-aware positioning, repeat tiling, and an optimised XObject path to reduce duplicated appearance data in saved PDFs.

What changed

1) New watermark plugin package

• Added packages/plugin-watermark with plugin manifest, reducer, actions, types, and implementation.
• Exposed public capability methods:
  • addWatermark(input)
  • removeWatermark(id)
  • getWatermarks()
  • applyToDocument(documentId)
  • clearFromDocument(documentId)
  • onWatermarkChange

2) Per-document watermark scoping

• Watermark definitions are tracked per open document (not globally).
• Configured watermarks are seeded on document load.
• Document close clears watermark state for that document.

3) Alignment and repeat behaviour

• Added semantic alignment options (top|center|bottom + left|center|right) for base placement.
• Alignment is resolved against page rotation so positioning remains intuitive on rotated pages.
• Added repeat modes: none, horizontal, vertical, both.
• Added repeat spacing controls (repeatSpacing.x, repeatSpacing.y).

4) Optimised tiling via shared XObject

• Added engine-level operation to place one appearance PDF across many placements using shared form XObject references:
  • tileAppearanceXObjectBehind(...)
• Watermark plugin attempts XObject tiling first for repeated placements.
• If the XObject route cannot be applied safely, it falls back to sequential stamp+flatten behaviour.
• Added helpers to export annotation appearance as PDF for reuse:
  • exportAnnotationAppearanceAsPdf(...)
  • exportAnnotationsAppearanceAsPdf(...)

5) Engine/model plumbing

• Added method definitions and transport wiring across orchestrator, remote executor, worker engine/runner, PDFium engine, and model interfaces for the new appearance/XObject operations.

6) React MUI example integration

• Registered WatermarkPluginPackage in examples/react-mui/src/application.tsx.
• Added a dedicated WatermarkPanel drawer UI with:
  • text/image watermark modes
  • alignment, size, opacity, rotation
  • repeat mode + spacing
  • estimated placement count preflight
  • long-running apply state and full-page takeover overlay
• Added toolbar button for the watermark drawer.

7) Documentation

• Added plugin documentation in packages/plugin-watermark/README.md:
  • API and configuration
  • alignment and repeat options
  • XObject tiling strategy
  • caveats around flattened content permanence

Behavioural notes

• removeWatermark removes watermark definitions from plugin state only.
• Flattened watermark visuals already written into page content are not reversible in-place.
• clearFromDocument clears placement tracking, not flattened visuals.

[vercel]

@antonsamper is attempting to deploy a commit to the OpenBook Team on Vercel.

A member of the Team first needs to authorize it.