From e3fa68a53c3f9a37a186c884bba2010d294a10bb Mon Sep 17 00:00:00 2001
From: lrnselfreliance <33263708+lrnselfreliance@users.noreply.github.com>
Date: Tue, 11 Aug 2026 18:57:01 -0600
Subject: [PATCH] ui: a PDF asks before it lights up a night-adapted eye (#654)
* ui: a PDF asks before it lights up a night-adapted eye
Night and amber pass media through an SVG color matrix so nothing a user opens costs
them their dark adaptation. It reaches everything drawn in our own document -- images,
video, canvases, and same-origin iframes like the EPUB viewer.
It does not reach a PDF, and the miss is not subtle. Chrome draws PDFs in its own
out-of-process viewer, which the compositor paints outside the parent's filter: the
computed style on the iframe really does say `filter: url(#wrolpi-night-red)` and the
page still arrives in full color. Measured in night mode on a device, a PDF covered
55% of the doc page in non-red pixels -- a full-brightness photograph of a blue sky --
while the chrome around it was correctly red. The preview modal measured 39.8%.
Tinting from outside was tried and does not work. A red `mix-blend-mode: multiply`
overlay above the iframe cannot see the plugin's pixels, so it stops blending and paints
flat opaque red: zero non-red pixels by measurement, document entirely obliterated.
So the PDF is withheld and the reader chooses. Nothing renders until they do; hiding it
with CSS would still load and paint the viewer, which is the flash being avoided.
Gated on whether the theme is CURRENTLY filtering, not on its name. A reader who turns
night's filter off has said they do not want this, and amber with its filter on has the
same unreachable PDF and does. Only PDFs: text and the EPUB viewer are documents of our
own and tint correctly, so gating them would hide something for no reason.
The gallery paragraph claiming the matrix remaps PDFs is corrected -- it was the one
place we told users something this measurement disproves.
Co-Authored-By: Claude Opus 5 (1M context)
* review: the reveal that outlived its document, and a test that proved nothing
Five review comments, all correct.
The bug: MediaGate was not keyed in FilePreview. The effect that rebuilds a preview sets
the modal to null and then to the new content in one pass, so React 18 batches both and
reconciles instead of unmounting -- the fiber survives, and a reader who revealed PDF A
would get PDF B in full color with no prompt. Keyed by url, which is what Docs already
did with activePath.
The test named "re-gates when filtering is turned back on" never revealed anything first,
so it went from gated=false to gated=true with `revealed` already false. That path never
reaches the reset effect: the test passed with the effect deleted. It now clicks Show
first, and fails without the effect.
The hide control moved above the media. A preview fills `calc(100dvh - 18.75rem)`, a
height calibrated with no room for a trailing button row, so a control after it lands
below the fold of a full-screen modal -- leaving the reader who just lit up their eyes
scrolling to find the way back.
Docs' embed -- the surface measured at 55% non-red -- had no contract test where
FilePreview had one. It has one now, asserting the gate wraps the iframe, keys per
document, and reads mediaFilterEnabled rather than the theme's name.
Gallery copy said "night and amber withhold it"; amber's filter is off unless asked for.
Co-Authored-By: Claude Opus 5 (1M context)
---------
Co-authored-by: Claude Opus 5 (1M context)
---
app/src/components/Docs.js | 37 +++++++++---
app/src/components/Docs.test.js | 49 ++++++++++++++++
app/src/components/FilePreview.js | 36 ++++++++++--
app/src/components/FilePreview.test.js | 78 ++++++++++++++++++++++++++
app/src/components/ThemeSamplePage.js | 23 +++++++-
app/src/components/ui/MediaGate.tsx | 76 +++++++++++++++++++++++++
app/src/components/ui/index.ts | 1 +
app/src/components/ui/ui.test.js | 76 +++++++++++++++++++++++++
8 files changed, 361 insertions(+), 15 deletions(-)
create mode 100644 app/src/components/Docs.test.js
create mode 100644 app/src/components/ui/MediaGate.tsx
diff --git a/app/src/components/Docs.js b/app/src/components/Docs.js
index 815b1654..f63de41f 100644
--- a/app/src/components/Docs.js
+++ b/app/src/components/Docs.js
@@ -1,7 +1,7 @@
-import React, {useEffect, useState} from 'react';
+import React, {useContext, useEffect, useState} from 'react';
import {Link, Route, Routes, useLocation, useNavigate, useParams, useSearchParams} from "react-router";
import {deleteFileGroups, getDocStatistics, tagFileGroup, untagFileGroup} from "../api";
-import {Media} from "../contexts/contexts";
+import {Media, ThemeContext} from "../contexts/contexts";
import {
APIButton,
BackButton,
@@ -17,7 +17,18 @@ import {
toLocaleString,
useTitle
} from "./Common";
-import {Button, ButtonGroup, Group, Header, Loading, Panel, Statistic, StatisticGroup, Tabs} from "./ui";
+import {
+ Button,
+ ButtonGroup,
+ Group,
+ Header,
+ Loading,
+ MediaGate,
+ Panel,
+ Statistic,
+ StatisticGroup,
+ Tabs
+} from "./ui";
import {BulkTagModal} from "./BulkTagModal";
import {TaggedDeleteConfirmModal} from "./TaggedDeleteConfirmModal";
import {DeepSearchHint, docMimetypeFilterOptions, FilesView, SearchControlBar} from "./Files";
@@ -157,6 +168,8 @@ function DocsPage() {
function DocPage() {
const {fileGroupId} = useParams();
const navigate = useNavigate();
+ // Whether the theme is currently filtering media; a PDF is the one embed it cannot reach.
+ const {mediaFilterEnabled} = useContext(ThemeContext);
const {docFile, doc, fetchDoc} = useDoc(parseInt(fileGroupId));
const [searchParams] = useSearchParams();
const [taggedFileGroups, setTaggedFileGroups] = useState(null);
@@ -344,11 +357,19 @@ function DocPage() {
{isCbz && activePath && }
{canEmbed && embedUrl && !isCbz &&
-
+ {/*
+ * Only the PDF is gated. The EPUB viewer is our own same-origin document, so the
+ * theme's media filter reaches it; Chrome's PDF viewer is composited out of
+ * process and cannot be tinted. Keyed on the path so selecting a different file
+ * re-gates rather than inheriting the last one's reveal.
+ */}
+
+
+
}
diff --git a/app/src/components/Docs.test.js b/app/src/components/Docs.test.js
new file mode 100644
index 00000000..147ea885
--- /dev/null
+++ b/app/src/components/Docs.test.js
@@ -0,0 +1,49 @@
+import fs from 'fs';
+import path from 'path';
+
+/*
+ * The document page's embedded viewer, and which of them is withheld in a filtering theme.
+ *
+ * This is the surface that measured 55% non-red pixels in night mode: a PDF is drawn by the
+ * browser in its own out-of-process viewer, which the theme's SVG filter never reaches, so it
+ * arrives in full color however the iframe is styled. The EPUB viewer is a document of our own
+ * and tints correctly, so gating it would hide something for no reason.
+ *
+ * Read off the source. DocPage renders only after `useDoc` resolves a file group and reaches
+ * the embed through several branches of file selection; a render test here would assert more
+ * about the mocks than about the wiring. ui.test.js covers what MediaGate itself does, and
+ * FilePreview.test.js covers the same contract on the other embed surface.
+ */
+
+const source = fs.readFileSync(path.join(__dirname, 'Docs.js'), 'utf8');
+
+describe('DocPage embed gating (source contract)', () => {
+ it('wraps the embedded viewer in a MediaGate', () => {
+ // The iframe must not be reachable without passing through the gate.
+ const embed = source.match(/]*>\s*
- Images, video, PDFs, embedded pages, and the map canvas cannot read theme
+ Images, video, embedded pages, and the map canvas cannot read theme
tokens, so a monochrome theme remaps them with an SVG color matrix instead.
Night filters to red unless you turn it off; amber tints to match only if
you ask. Light and dark offer no filter, so both images look the same here.
@@ -258,6 +259,24 @@ export function ThemeSamplePage() {
show only this caption.
+ {/*
+ The one thing the matrix cannot reach. Gated on the live filter state, so in
+ night it withholds and in light it simply shows — the same behavior /docs has.
+ */}
+
+
+
+
+
+ MediaGate. A PDF is the one thing the filter cannot reach:
+ the browser draws it in its own viewer, outside the page, so it arrives
+ in full color however the frame is styled — and painting over it just
+ hides the document. So when a filter is on — night by default, amber if
+ you ask — it withholds the PDF and lets you choose. Light and dark offer
+ no filter and show it straight through, which is what you see here
+ unless a filter is on.
+
+
diff --git a/app/src/components/ui/MediaGate.tsx b/app/src/components/ui/MediaGate.tsx
new file mode 100644
index 00000000..87f5b857
--- /dev/null
+++ b/app/src/components/ui/MediaGate.tsx
@@ -0,0 +1,76 @@
+import React from 'react';
+import {Button} from './Button';
+import {Message} from './Feedback';
+
+/*
+ * A gate for media the theme's filter cannot reach.
+ *
+ * Night and amber pass media through an SVG color matrix so nothing a user opens costs them
+ * their dark adaptation. That filter reaches everything drawn in our own document -- images,
+ * video, canvases, and same-origin iframes such as the EPUB viewer.
+ *
+ * It does not reach a PDF. Chrome renders PDFs in its own out-of-process viewer, which the
+ * compositor paints outside the parent's filter: the computed style on the iframe really does
+ * say `filter: url(#wrolpi-night-red)`, and the page still arrives in full color. Measured on
+ * a device in night mode, a PDF covered 55% of the viewport in non-red pixels while the chrome
+ * around it was correctly red.
+ *
+ * Tinting it from outside does not work either. A red `mix-blend-mode: multiply` overlay above
+ * the iframe cannot see the plugin's pixels, so it stops blending and paints flat opaque red:
+ * the measurement reports zero non-red pixels while the document is entirely obliterated.
+ *
+ * So the options are to render PDFs ourselves or to not show one unasked. This is the second:
+ * the reader is told why, and chooses. Nothing renders until they do -- hiding it with CSS
+ * would still load and paint the viewer, which is the whole thing being avoided.
+ *
+ * `gated` is a prop rather than something read from ThemeContext, so this stays a component of
+ * the library like any other: it is told whether to gate, it does not decide. Call sites pass
+ * `isPdf && mediaFilterEnabled`.
+ */
+
+export interface MediaGateProps {
+ /** Whether to withhold `children` until the reader asks for them. */
+ gated: boolean;
+ /** What is being withheld, named in the reader's terms: "PDF", "document". */
+ kind?: string;
+ children: React.ReactNode;
+}
+
+export function MediaGate({gated, kind = 'PDF', children}: MediaGateProps) {
+ const [revealed, setRevealed] = React.useState(false);
+
+ // Re-gate when filtering comes back on, so revealing one document does not leave every
+ // later one unguarded.
+ React.useEffect(() => {
+ if (!gated) setRevealed(false);
+ }, [gated]);
+
+ if (!gated) return <>{children}>
+
+ if (revealed) {
+ /*
+ * The control goes ABOVE the media, not after it. A preview fills
+ * `calc(100dvh - 18.75rem)`, a height calibrated with no room for a trailing button
+ * row, so a control placed after it lands below the fold of a full-screen modal --
+ * leaving the reader who just lit up their eyes scrolling to find the way to undo it.
+ */
+ return <>
+
+
+
+ {children}
+ >
+ }
+
+ return
+
+ This {kind} cannot be tinted to match the theme, so it would be shown in full color
+ and at full brightness.
+
+
+
+}
diff --git a/app/src/components/ui/index.ts b/app/src/components/ui/index.ts
index 102d7d15..bac5c82e 100644
--- a/app/src/components/ui/index.ts
+++ b/app/src/components/ui/index.ts
@@ -20,6 +20,7 @@ export * from './DataTable';
export * from './Navigation';
export * from './SearchBox';
export * from './Inputs';
+export * from './MediaGate';
export * from './Overlays';
export * from './ThemePicker';
export * from './toast';
diff --git a/app/src/components/ui/ui.test.js b/app/src/components/ui/ui.test.js
index fb221ff9..26caf2a7 100644
--- a/app/src/components/ui/ui.test.js
+++ b/app/src/components/ui/ui.test.js
@@ -20,6 +20,7 @@ import {
IconStack,
Loader,
Loading,
+ MediaGate,
Placeholder,
Pagination,
SearchBox,
@@ -1694,3 +1695,78 @@ describe('modal sizes', () => {
expect(offenders).toEqual([]);
});
});
+
+describe('MediaGate', () => {
+ /*
+ * Withholding media the theme's filter cannot reach.
+ *
+ * The case that matters is a PDF in night mode: Chrome renders it in an out-of-process
+ * viewer that the parent's filter never touches, so it arrives in full color -- measured at
+ * 55% non-red pixels on a device while the chrome around it was correctly red.
+ */
+ it('renders its children untouched when nothing is being filtered', () => {
+ renderUI(
the document
);
+
+ expect(screen.getByText('the document')).toBeInTheDocument();
+ expect(screen.queryByRole('button', {name: /Show the full-color/})).not.toBeInTheDocument();
+ });
+
+ it('withholds the media, and says why, when the theme is filtering', () => {
+ renderUI(
the document
);
+
+ // Not merely hidden: absent. A CSS-hidden iframe still loads and paints the viewer,
+ // which is the bright flash this exists to prevent.
+ expect(screen.queryByText('the document')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent(/cannot be tinted/);
+ });
+
+ it('shows the media when the reader asks for it', async () => {
+ renderUI(
the document
);
+
+ await userEvent.click(screen.getByRole('button', {name: 'Show the full-color PDF'}));
+
+ expect(screen.getByText('the document')).toBeInTheDocument();
+ });
+
+ it('lets the reader put it away again', async () => {
+ renderUI(
the document
);
+ await userEvent.click(screen.getByRole('button', {name: 'Show the full-color PDF'}));
+
+ await userEvent.click(screen.getByRole('button', {name: 'Hide the PDF again'}));
+
+ expect(screen.queryByText('the document')).not.toBeInTheDocument();
+ });
+
+ it('re-gates a revealed document when filtering is turned back on', async () => {
+ /*
+ * Revealing one document must not leave every later one unguarded: the reader who turns
+ * the filter off, looks at a PDF, then turns it back on has re-stated the preference
+ * this respects.
+ *
+ * The reveal in the middle is the whole test. An earlier version went straight from
+ * `gated={false}` to `gated={true}` with `revealed` still false, which never reaches the
+ * reset effect at all -- it passed just as well with that effect deleted, so it was
+ * testing the `if (!gated)` early return and claiming to test the reset.
+ */
+ const gate = (gated) =>
+
+
the document
+ ;
+
+ const {rerender} = render(gate(true));
+ await userEvent.click(screen.getByRole('button', {name: 'Show the full-color PDF'}));
+ expect(screen.getByText('the document')).toBeInTheDocument();
+
+ rerender(gate(false)); // filter off: shown because nothing is being filtered
+ rerender(gate(true)); // filter back on: must be withheld again, not still revealed
+
+ expect(screen.queryByText('the document')).not.toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Show the full-color PDF'})).toBeInTheDocument();
+ });
+
+ it('names what it is withholding', () => {
+ renderUI(