From 717afaf3177a2e0925b18ae3445119efe808b129 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 16 Sep 2026 14:46:16 -0300 Subject: Add macOS backdrop blur and preserve PDF ink opacity --- docs/macos.md | 42 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) (limited to 'docs/macos.md') 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 -- cgit v1.3