Add macOS backdrop blur and preserve PDF ink opacity

2 files changed, 41 insertions, 7 deletions

diff --git a/docs/macos.md b/docs/macos.md
index 3fdf399f..9190ca67 100644
--- a/docs/macos.md
+++ b/docs/macos.md
@@ -696,7 +696,7 @@ A theme with `bg = null` — the curated `dark`, and every vendored
 `pardes_theme_bg` answers `PARDES_COLOR_DEFAULT` and the host goes see-through:
 `window.isOpaque = false`, a clear background colour, and an
 `NSVisualEffectView` (`.underWindowBackground`, `.behindWindow`, `.active`)
-behind the grid. `PardesView` stops painting the ground at all — it *clears*,
+behind the grid when `WindowBlur` is enabled. `PardesView` stops painting the ground at all — it *clears*,
 because AppKit does not blank a non-opaque view — and any cell whose background
 is still the default resolves to `bgClear` and is skipped by the run loop.
 Reversed cells are not: a reverse puts the text colour in the background, and
@@ -710,10 +710,42 @@ blank window for every opaque theme the moment it was hidden.
 Background fills replace existing coverage, so overlapping ground, cell, tag
 and context layers cannot increase the requested opacity. The window itself
 stays clear below 100%; a second tinted window backdrop would compound it.
-Text and cursor ink stay opaque. PDF and image pixels follow the SDL image
-pipeline: remove the destination by source coverage, then add the image at the
-requested opacity. This also preserves the background under transparent image
-pixels. Theme colours and attachment rasters are interpreted as sRGB.
+Text and cursor ink stay opaque. PDFs render onto a transparent MuPDF pixmap,
+which preserves the coverage of text, paths, photos, and highlights. The host
+paints paper at `WindowOpacity`, then composites PDF content at its original
+opacity. Blank paper therefore reveals the blurred backdrop while lettering
+stays readable even at `WindowOpacity 0`. Paper is white with `PdfTint` disabled
+and uses the theme background otherwise. Explicit PDF background rectangles
+and scanned page images remain content: this does not guess paper from pixel
+brightness or remove white objects from a document. Scrolling and transitions
+retain both the content raster and its paper color.
+
+Ordinary image attachments still follow the SDL image pipeline: remove the
+destination by source coverage, then add the image at the requested opacity.
+Theme colours and attachment rasters are interpreted as sRGB. The PDF paper
+separation is currently macOS-specific; other hosts keep the opaque raster path.
+
+`WindowBlur <0..100>` controls the strength of that native backdrop independently
+of `WindowOpacity`. It is a macOS-only builtin, also accepted in the startup
+config and reported by `Config`. It defaults to 0 (off); 100 shows the full
+AppKit material and intermediate values blend the material with the unblurred
+backdrop using the effect view's alpha. An opaque themed background hides the
+effect; lowering `WindowOpacity` makes the remembered strength visible again.
+For example:
+
+```text
+WindowOpacity 71
+WindowBlur 60
+```
+
+This is material strength, not a Gaussian radius in pixels. AppKit's public
+`NSVisualEffectView` API chooses its own blur and tint for the material. It
+samples behind the window; text and cursors are drawn in a separate sibling
+above the effect and remain sharp. macOS accessibility settings such as Reduce
+Transparency can override the material's appearance. `WindowBlur 0` also turns
+off the formerly implicit blur for background-less themes; set it to 100 to
+restore that appearance. The compositor must be checked in a live window:
+offscreen grid captures cannot verify behind-window blur.
 
 `test/macos-snapshots/rendering-parity.snap` checks background colour and alpha,
 regular and bottom tags, compact context separators, and PDF fit, tint and
diff --git a/docs/rendering-parity-design.md b/docs/rendering-parity-design.md
index b6036543..14a5bc62 100644
--- a/docs/rendering-parity-design.md
+++ b/docs/rendering-parity-design.md
@@ -76,8 +76,10 @@ out.rgb = p * a * c + (1 - a) * dst.rgb
 out.a   = p * a     + (1 - a) * dst.a
 ```
 
-Thus PDF text is part of a raster page and fades with the page; native text does
-not. Transparent image pixels preserve the destination. Ordinary source-over
+This describes ordinary image attachments and the existing SDL PDF path.
+macOS PDFs now separate unpainted paper from content: paper uses p and content
+uses its own coverage, without multiplying that coverage by p. A future shared
+scene must carry this paper/content distinction explicitly. Transparent image pixels preserve the destination. Ordinary source-over
 with source alpha p*a is not equivalent. Any future operation API needs to
 express this distinction directly and specify sampling and premultiplication.