Watermark plugin

@nextgensoftwares/folio-plugin-watermark draws text and image watermarks on pages: on screen, in the PDF (real glyphs, true transparency) and in Word as Word's own watermark, which users can edit or remove from Design ▸ Watermark.

import { composePlugins } from '@nextgensoftwares/folio-editor';
import { watermarkPlugin } from '@nextgensoftwares/folio-plugin-watermark';

const watermark = watermarkPlugin({
  text: 'CONFIDENTIAL · {{user}} · {{date}}',
  opacity: 0.12,
  tile: { gap: 120 },
  pages: 'all',
});
const composed = composePlugins(standardSchema, [watermark /* , pdfExportPlugin(...), docxExportPlugin(...) */]);

<FolioView editor={editor} painters={composed.painters} pageLayers={composed.pageLayers} layerVariables={{ user: me.name }} />

How it works

The plugin contributes one PageLayer: a pure function from a page box to positioned custom fragments of type watermark. Layers are presentation only: layout and page reuse never change when the watermark does. Fragments are cached per page and settings version, and @nextgensoftwares/folio-react only paints layers for the pages it already renders (virtualized), so a 5,000-page book costs the same as a 5-page one.

Changing the watermark (watermark.setOptions({ opacity: 0.3 })) notifies the layer's subscribe; the view re-renders the visible pages' layer boxes, never their content.

Options

Option	Default	Meaning
text	none	a string or { content, fontFamily?, fontSize?, fontWeight?, italic? }; , , (YYYY-MM-DD) and host variables such as
image	none	{ src, width?, height? } px, drawn contained in its box
color	#6b7280	text colour (CSS)
opacity	0.15	0..1
angle	-45	degrees, clockwise like CSS rotate()
position	'center'	'top', 'bottom' or { x, y } in page fractions
tile	false	true or { gap }: a brick pattern over the whole page (wins over count)
count	1	copies per page (1..50), spread evenly and shrunk so each fits its share of the page; 1 = one copy at position
countLayout	'grid'	'grid' (rows × columns shaped like the page, a short last row centred) or 'diagonal' (along the line the text runs on)
pages	'all'	'first', 'odd', 'even', [1, [3, 5]] or (page, total) => boolean
targets	all on	{ screen?, pdf?, docx?, print? }
z	'under'	'over' for stamps on top of the text
variables	{}	merged over the host's layer variables
enabled	true	master switch
settings	true	adds a "Watermark" section to the host's settings slot (false, or { slot, order, label })

Every option is treated as untrusted input: numbers are clamped and must be finite, colours and font families can't inject CSS, image sources follow the safe-src rules (no javascript:, no SVG/HTML data:), text is capped at 200 characters and a page never gets more than 400 tiles per kind.

Screen

The watermark painter is a React component: rotated text through a CSS transform, or an <img> with object-fit: contain. Layer boxes are aria-hidden, not selectable and pointer-events: none, so clicks, drags and selection go to the page underneath.

PDF

Pass the layers to the exporter; the plugin's exporters.pdf painter draws each fragment with glyphs from the embedded fonts (the same HarfBuzz shaping as body text), rotated about its centre, with opacity through an ExtGState. Images are embedded once and reused on every page.

pdfExportPlugin({ faces, exporters: () => composed.exporters.pdf, pageLayers: () => composed.pageLayers, variables: () => ({ user: me.name }) });

Word

docxExportPlugin({ exporters: () => composed.exporters.docx, pageLayers: () => composed.pageLayers }) writes the shape Word's Design ▸ Watermark writes, in the section header: a PowerPlusWaterMarkObject WordArt shape for text, a WordPictureWatermark picture (with Word's washout when opacity < 0.9) for images. Word repeats it on every page by itself.

• 'first' turns on Word's different first page; 'odd'/'even' turn on odd/even headers. The existing header and footer are copied into the extra headers so nothing else changes. Other rules are approximated from a first, an even and an odd page.
• A Word watermark is a static shape: / are left out, tiles and count copies collapse into one centred watermark (at the per-copy size), and the position is Word's (centred on the margins). Word draws one watermark shape per header, so several copies per page are a screen/PDF feature.