@celestia-island/hikari 0.55.19 → 0.55.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.19",
+  "version": "0.55.21",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkInput.password.test.tsx

@@ -1334,6 +1334,11 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
      * carved out of the ink spatter (R3 F2: without this the password
      * would render INVISIBLE on a real canvas, silently). */
     compositeOps: string[];
+    /** Gradient stop colors, in order — pins the halo's THEME color
+     * (white over a dark ground, black over a light one). */
+    gradientStops: string[];
+    /** Font string assignments — pins the BOLD glyph aperture. */
+    fonts: string[];
     fillStyles: string[];
     clips: Array<{ x: number; y: number; w: number; h: number }>;
     translates: number[];
@@ -1354,6 +1359,8 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
         gradients: 0,
         gradientFills: 0,
         compositeOps: [],
+        gradientStops: [],
+        fonts: [],
         fillStyles: [],
         clips: [],
         translates: [],
@@ -1364,6 +1371,7 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
     let fillStyleBox: string | CanvasGradient | CanvasPattern = "";
     let gradientArmed = false;
     let compositeOpBox: GlobalCompositeOperation = "source-over";
+    let fontBox = "";
     const stub: Record<string, unknown> = {
       canvas: this,
       clearRect: () => {},
@@ -1389,7 +1397,10 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
       },
       createLinearGradient: () => {
         r.gradients++;
-        return { __recGradient: true, addColorStop: () => {} } as unknown as CanvasGradient;
+        return {
+          __recGradient: true,
+          addColorStop: (_o: number, c: string) => r.gradientStops.push(String(c)),
+        } as unknown as CanvasGradient;
       },
       createImageData: (w: number, h: number) => ({
         data: new Uint8ClampedArray(w * h * 4),
@@ -1406,7 +1417,13 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
         compositeOpBox = v;
         r.compositeOps.push(String(v));
       },
-      font: "",
+      get font() {
+        return fontBox;
+      },
+      set font(v: string) {
+        fontBox = v;
+        r.fonts.push(String(v));
+      },
       get fillStyle() {
         return fillStyleBox;
       },
@@ -1564,14 +1581,15 @@ describe("HkInput password reveal strategies", () => {
   });
 
   it("filter (default) keeps glyphs off the visible canvas: counter-drifting spatter, pedestal, halo", async () => {
-    // The default reveal: STATIC glyph apertures filled with one
-    // spatter texture, over a statistically matched spatter field
-    // drifting the opposite way; the glyphs lifted by a small lightness
-    // pedestal with a halo band around the row. Glyph geometry must
-    // NEVER reach the visible canvas (mask → source-in stamp only) —
-    // that is the screenshot contract. Math.random is pinned at 0.5 so
-    // the dot lightness equals the exact layer base (deterministic
-    // pedestal comparison).
+    // The default reveal: STATIC BOLD glyph apertures filled with one
+    // GRAYSCALE spatter texture, over a statistically matched spatter
+    // field drifting the opposite way on the theme-anchored ground;
+    // the glyphs shifted by a small pedestal toward the theme's
+    // visibility direction with a halo band around the row. Glyph
+    // geometry must NEVER reach the visible canvas (mask → source-in
+    // stamp only) — that is the screenshot contract. Math.random is
+    // pinned at 0.5 so the dot lightness equals the exact layer base
+    // (deterministic pedestal comparison).
     const rand = vi.spyOn(Math, "random").mockReturnValue(0.5);
     const rec = stubRecordingContexts();
     try {
@@ -1604,14 +1622,25 @@ describe("HkInput password reveal strategies", () => {
       expect(vis.gradientFills, "halo band drawn").toBeGreaterThan(0);
       expect(vis.drawImages).toBeGreaterThan(0);
       // The two spatter tiles: bg first, ink second (deterministic
-      // draw order), each with hundreds of solid-color dot fills. The
-      // ink tile's mean color must sit ABOVE the bg tile's — the
-      // lightness pedestal the human pop-out cue (and the only signal
-      // a single frame leaks).
+      // draw order), each with hundreds of solid-color dot fills.
+      // happy-dom resolves no computed color, so the ink stays at the
+      // pre-sync fallback (a DARK ink) — the effective theme here is
+      // LIGHT: near-white ground, dark-gray speckle, and the pedestal
+      // shifts the glyph layer DARKER (visibility direction).
       const tiles = allRecs.filter(
         (r) => r.fillStyles.filter((s) => s.startsWith("rgb(")).length > 100,
       );
       expect(tiles.length, "exactly two spatter tiles").toBe(2);
+
+      // Backing-store tripwire (R3 F1): a shrunken tile silently
+      // drops ~75% of its dots and desyncs the pattern period from
+      // wrapDrift's modulus (the noise painter's documented P1 class).
+      expect(
+        tiles.every(
+          (t) => t.canvas.width === NOISE_TILE_W && t.canvas.height === NOISE_TILE_H,
+        ),
+        "spatter tiles sized to the noise tile backing store",
+      ).toBe(true);
       const meanOf = (r: (typeof tiles)[number]) => {
         const samples = r.fillStyles.filter((s) => s.startsWith("rgb("));
         let sum = 0;
@@ -1624,9 +1653,38 @@ describe("HkInput password reveal strategies", () => {
       const bgMean = meanOf(tiles[0]!);
       const inkMean = meanOf(tiles[1]!);
       expect(
-        inkMean - bgMean,
-        `glyph layer carries the lightness pedestal (bg ${bgMean.toFixed(1)} vs ink ${inkMean.toFixed(1)})`,
+        bgMean - inkMean,
+        `light theme: glyph pedestal shifts DARKER (bg ${bgMean.toFixed(1)} vs ink ${inkMean.toFixed(1)})`,
       ).toBeGreaterThan(8);
+      // Strict grayscale: no theme hue may survive into the spatter —
+      // every solid fill is a NEUTRAL gray (r === g === b).
+      for (const tile of tiles) {
+        for (const fill of tile.fillStyles.filter((s) => s.startsWith("rgb("))) {
+          const [r8, g8, b8] = fill.slice(4, -1).split(",").map(Number);
+          expect(
+            r8 === g8 && g8 === b8,
+            `spatter must be grayscale, got ${fill}`,
+          ).toBe(true);
+        }
+      }
+      // Theme anchor: the LIGHT theme's ground is near-white (first
+      // fill on the bg tile is the ground wash; L 93 → rgb ≈ 237).
+      const [gr, gg, gb] = tiles[0]!.fillStyles[0]!.slice(4, -1).split(",").map(Number);
+      expect(gr!, "light-theme ground is near-white").toBeGreaterThan(230);
+      expect(gr!).toBeLessThan(245);
+      expect(gg!).toBe(gr);
+      expect(gb!).toBe(gr);
+      // Halo color follows the theme: BLACK over a light ground —
+      // peak AND endpoints share the theme channel (R2 F1).
+      expect(vis.gradientStops, "light theme paints a BLACK halo").toContain("rgba(0,0,0,0.1)");
+      expect(vis.gradientStops).not.toContain("rgba(255,255,255,0.1)");
+      expect(vis.gradientStops, "light halo endpoints fade on BLACK").toContain("rgba(0,0,0,0)");
+      expect(vis.gradientStops).not.toContain("rgba(255,255,255,0)");
+      // The glyph apertures rasterize BOLD.
+      expect(
+        mask!.fonts.some((f) => f.startsWith("bold ")),
+        "glyph apertures rasterize bold",
+      ).toBe(true);
       // The DOM input still never flips.
       expect(input.type).toBe("password");
       // Bus frames advance BOTH layer drifts (fresh pattern phases on
@@ -1661,6 +1719,226 @@ describe("HkInput password reveal strategies", () => {
     }
   });
 
+  /**
+   * Force the computed `.color` (the reveal's ink + theme proxy) while
+   * forwarding every other computed-style query to the real engine.
+   * Returns a restore function.
+   */
+  function forceInkColor(color: string): () => void {
+    const original = window.getComputedStyle;
+    window.getComputedStyle = ((el: Element, ...rest: unknown[]) => {
+      const real = original.call(window, el, ...(rest as []));
+      return new Proxy(real, {
+        get(target, prop) {
+          if (prop === "color") return color;
+          const v = Reflect.get(target, prop, target);
+          return typeof v === "function"
+            ? (v as (...a: unknown[]) => unknown).bind(target)
+            : v;
+        },
+      });
+    }) as typeof window.getComputedStyle;
+    return () => {
+      window.getComputedStyle = original;
+    };
+  }
+
+  it("filter inverts its grayscale anchors for a dark theme (light field ink)", async () => {
+    // Light field ink = a dark theme: near-black ground, light-gray
+    // speckle, a BRIGHTER glyph pedestal and a WHITE halo — every
+    // anchor flips with the theme while the mechanism stays identical.
+    // The theme proxy is the computed field-ink lightness (>= 50 =
+    // dark theme), so feed a light ink through getComputedStyle.
+    const restoreInk = forceInkColor("rgb(148, 233, 211)");
+    const rec = stubRecordingContexts();
+    try {
+      const { container } = mountPasswordInput("abc");
+      const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
+      eye.dispatchEvent(
+        new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
+      );
+      await nextTick();
+      const visible = container.querySelector<HTMLCanvasElement>(".hk-pwd-dots")!;
+      const vis = rec.byCanvas.get(visible)!;
+      const allRecs = Array.from(rec.byCanvas.values());
+      const tiles = allRecs.filter(
+        (r) => r.fillStyles.filter((s) => s.startsWith("rgb(")).length > 100,
+      );
+      expect(tiles.length).toBe(2);
+      const meanOf = (r: (typeof tiles)[number]) => {
+        const samples = r.fillStyles.filter((s) => s.startsWith("rgb("));
+        let sum = 0;
+        for (const s of samples) {
+          const [r8, g8, b8] = s.slice(4, -1).split(",").map(Number);
+          sum += (r8! + g8! + b8!) / 3;
+        }
+        return sum / samples.length;
+      };
+      const bgMean = meanOf(tiles[0]!);
+      const inkMean = meanOf(tiles[1]!);
+      expect(
+        inkMean - bgMean,
+        `dark theme: glyph pedestal shifts BRIGHTER (bg ${bgMean.toFixed(1)} vs ink ${inkMean.toFixed(1)})`,
+      ).toBeGreaterThan(8);
+      // Strict grayscale on the dark side too (R2 F4).
+      for (const tile of tiles) {
+        for (const fill of tile.fillStyles.filter((f) => f.startsWith("rgb("))) {
+          const [r8, g8, b8] = fill.slice(4, -1).split(",").map(Number);
+          expect(r8 === g8 && g8 === b8, `dark spatter must be grayscale, got ${fill}`).toBe(true);
+        }
+      }
+      // Matched texture statistics (R2 F2): the two layers must carry
+      // the SAME dot count and (pedestal aside) the same lightness
+      // RANGE — a diverging spread/density is the single-frame
+      // segmentation leak the docblock promises cannot happen.
+      const dotStats = (r: (typeof tiles)[number]) => {
+        const dots = r.fillStyles.slice(1).filter((f) => f.startsWith("rgb("));
+        let min = 255, max = 0;
+        for (const f of dots) {
+          const v = Number(f.slice(4, -1).split(",")[0]);
+          if (v < min) min = v;
+          if (v > max) max = v;
+        }
+        return { count: dots.length, range: max - min };
+      };
+      const bgStats = dotStats(tiles[0]!);
+      const inkStats = dotStats(tiles[1]!);
+      expect(inkStats.count, "both layers carry the same dot density").toBe(bgStats.count);
+      expect(
+        Math.abs(inkStats.range - bgStats.range),
+        `matched lightness spread (bg ${bgStats.range} vs ink ${inkStats.range})`,
+      ).toBeLessThan(6);
+      // The pedestal lifts ground AND dots together: the two grounds
+      // sit exactly one pedestal apart (~10 L ≈ 25 rgb), so an ink
+      // ground that loses or doubles its shift goes red (R2 C1b).
+      const groundOf = (r: (typeof tiles)[number]) =>
+        Number(r.fillStyles[0]!.slice(4, -1).split(",")[0]);
+      const groundDelta = Math.abs(groundOf(tiles[1]!) - groundOf(tiles[0]!));
+      expect(
+        groundDelta >= 20 && groundDelta <= 30,
+        `grounds one pedestal apart (delta ${groundDelta})`,
+      ).toBe(true);
+      // Near-black ground: L 10 → rgb ≈ 26.
+      const [gr, gg, gb] = tiles[0]!.fillStyles[0]!.slice(4, -1).split(",").map(Number);
+      expect(gr!, "dark-theme ground is near-black").toBeGreaterThan(18);
+      expect(gr!).toBeLessThan(34);
+      expect(gg!).toBe(gr);
+      expect(gb!).toBe(gr);
+      // White halo over the dark ground — peak AND endpoints share
+      // the theme channel (an endpoint desync must go red, R2 F1).
+      expect(vis.gradientStops, "dark theme paints a WHITE halo").toContain("rgba(255,255,255,0.1)");
+      expect(vis.gradientStops).not.toContain("rgba(0,0,0,0.1)");
+      expect(vis.gradientStops, "dark halo endpoints fade on WHITE").toContain("rgba(255,255,255,0)");
+      expect(vis.gradientStops).not.toContain("rgba(0,0,0,0)");
+      // Same screenshot contract and bold apertures as the light theme.
+      const mask = allRecs.find((r) => r.texts.length > 0)!;
+      expect(mask.texts).toEqual(["a", "b", "c"]);
+      expect(vis.texts).toEqual([]);
+      expect(mask.fonts.some((f) => f.startsWith("bold "))).toBe(true);
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      rec.restore();
+      restoreInk();
+    }
+  });
+
+  it("filter keeps the documented light-anchor degrade for modern color-function inks", async () => {
+    // oklch()/lab()/color() inks cannot be parsed into a triple — the
+    // documented degrade keeps the fallback ink (a DARK ink → light
+    // anchors), never throwing and never guessing a theme. Locked as
+    // intentional (R1 finding F1).
+    const restoreInk = forceInkColor("oklch(70% 0.1 200)");
+    const rec = stubRecordingContexts();
+    try {
+      const { container } = mountPasswordInput("abc");
+      const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
+      eye.dispatchEvent(
+        new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
+      );
+      await nextTick();
+      const visible = container.querySelector<HTMLCanvasElement>(".hk-pwd-dots")!;
+      const vis = rec.byCanvas.get(visible)!;
+      const allRecs = Array.from(rec.byCanvas.values());
+      const tiles = allRecs.filter(
+        (r) => r.fillStyles.filter((s) => s.startsWith("rgb(")).length > 100,
+      );
+      expect(tiles.length).toBe(2);
+      const [gr] = tiles[0]!.fillStyles[0]!.slice(4, -1).split(",").map(Number);
+      expect(gr!, "fallback ink → LIGHT anchors (near-white ground)").toBeGreaterThan(230);
+      expect(vis.gradientStops, "black halo in the degrade").toContain("rgba(0,0,0,0.1)");
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      rec.restore();
+      restoreInk();
+    }
+  });
+
+  it("filter degrades the same way for color()-function inks", async () => {
+    // Locks the DEGRADE SEMANTICS for color() inks: the modern-
+    // function rejection yields null → the fallback dark ink → LIGHT
+    // anchors. Honest limit (verified during R2 remedies): spec-valid
+    // color() values are 0–1 floats, so even a DELETED guard parses
+    // them into sub-1 triples (L < 1 → light) — guard deletion is not
+    // observable through the filter theme. The guard's real consumer
+    // is the NOISE painter's colored tiles (it prevents deriving a
+    // garbage hue from e.g. [0.5,0.2,0.8]); this pin keeps any future
+    // "auto-interpret color()" change (×255 scaling → L 50 → dark)
+    // from silently re-theming the filter.
+    const restoreInk = forceInkColor("color(display-p3 1 0 0)");
+    const rec = stubRecordingContexts();
+    try {
+      const { container } = mountPasswordInput("abc");
+      const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
+      eye.dispatchEvent(
+        new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
+      );
+      await nextTick();
+      const allRecs = Array.from(rec.byCanvas.values());
+      const tiles = allRecs.filter(
+        (r) => r.fillStyles.filter((f) => f.startsWith("rgb(")).length > 100,
+      );
+      expect(tiles.length).toBe(2);
+      const [gr] = tiles[0]!.fillStyles[0]!.slice(4, -1).split(",").map(Number);
+      expect(gr!, "color() ink degrades to the LIGHT anchors").toBeGreaterThan(230);
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      rec.restore();
+      restoreInk();
+    }
+  });
+
+  it("filter treats exactly-50 ink lightness as a dark theme (boundary)", async () => {
+    // rgb(255,0,0): max+min halves to EXACTLY 0.5 (128/255 does not)
+    // — L === 50 on the nose, so the >= side of the theme proxy wins
+    // and the reveal anchors dark (R1 finding F2).
+    const restoreInk = forceInkColor("rgb(255, 0, 0)");
+    const rec = stubRecordingContexts();
+    try {
+      const { container } = mountPasswordInput("abc");
+      const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
+      eye.dispatchEvent(
+        new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
+      );
+      await nextTick();
+      const allRecs = Array.from(rec.byCanvas.values());
+      const tiles = allRecs.filter(
+        (r) => r.fillStyles.filter((s) => s.startsWith("rgb(")).length > 100,
+      );
+      expect(tiles.length).toBe(2);
+      const [gr] = tiles[0]!.fillStyles[0]!.slice(4, -1).split(",").map(Number);
+      expect(gr!, "L === 50 anchors DARK (near-black ground)").toBeGreaterThan(18);
+      expect(gr!).toBeLessThan(34);
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      rec.restore();
+      restoreInk();
+    }
+  });
+
   it("filter regenerates both spatter tiles on every hold", async () => {
     // Fresh noise per hold is an anti-replay contract: two holds of the
     // same password must never replay the same frame sequence. Pin: the

package/src/components/HkInput.tsx

@@ -77,13 +77,15 @@ export default defineComponent({
     /**
      * Reveal content for the password eye (`variant="password"`,
      * `passwordTrailing="eye"`):
-     * - "filter" (default): dual counter-drifting spatter layers —
-     *   static glyph apertures filled with one spatter texture over a
-     *   statistically matched field drifting the opposite way, plus a
-     *   small lightness pedestal and a halo band around the row. The
-     *   whole row stays readable in motion; a single-frame screenshot
-     *   carries no glyph structure, only a weak luminance signal
-     *   dissolved into the halo.
+     * - "filter" (default): dual counter-drifting spatter layers in
+     *   strict black/white/gray — static BOLD glyph apertures filled
+     *   with one gray spatter texture over a statistically matched
+     *   field drifting the opposite way on the theme's ground
+     *   (near-black in a dark theme, near-white in a light one),
+     *   plus a small visibility-direction lightness pedestal and a
+     *   halo band around the row. The whole row stays readable in
+     *   motion; a single-frame screenshot carries no glyph structure,
+     *   only a weak luminance signal dissolved into the halo.
      * - "sweep": a readable window — ordinary high-contrast text inside
      *   a narrow band sweeping across the row over the boiling-noise
      *   field. Easy to read; a single screenshot leaks the characters

package/src/components/HkPasswordSurface.tsx

@@ -53,15 +53,17 @@ interface Ripple {
  * - "eye" (default): the reveal button. What the reveal SHOWS is chosen
  *   by `revealStrategy`, how it is TRIGGERED by `revealTrigger`:
  *   - strategy "filter" (default): dual counter-drifting spatter
- *     layers — the glyph row is a set of STATIC apertures filled with a
- *     spatter texture drifting one way, over a statistically identical
- *     spatter field drifting the other way, the glyphs lifted by a
- *     small lightness pedestal with a soft halo band around the row
- *     (see revealKinematogram.ts). The whole row stays readable in
- *     motion while any single frame — a screenshot — carries no glyph
- *     structure, only a weak mean-luminance signal dissolved into the
- *     halo ramp. Reduced motion or a pattern-less engine degrades to
- *     the fully readable static plain text.
+ *     layers in strict BLACK/WHITE/GRAY — the glyph row is a set of
+ *     STATIC bold apertures filled with a gray spatter texture
+ *     drifting one way, over a statistically identical spatter field
+ *     drifting the other way on the theme's ground (near-black in a
+ *     dark theme, near-white in a light one), the glyphs shifted by a
+ *     small lightness pedestal toward visibility with a soft halo
+ *     band around the row (see revealKinematogram.ts). The whole row
+ *     stays readable in motion while any single frame — a screenshot
+ *     — carries no glyph structure, only a weak mean-luminance signal
+ *     dissolved into the halo ramp. Reduced motion or a pattern-less
+ *     engine degrades to the fully readable static plain text.
  *   - strategy "sweep": a readable window — the password is drawn as
  *     ordinary high-contrast text inside a narrow band that sweeps
  *     across the row over the boiling-noise field. Reading is
@@ -118,11 +120,13 @@ export default defineComponent({
     },
     /**
      * What the eye reveal SHOWS:
-     * - "filter" (default): dual counter-drifting spatter layers —
-     *   static glyph apertures over an oppositely drifting, statisti-
-     *   cally matched spatter field, plus a small lightness pedestal
-     *   and halo. Readable in motion; a single screenshot carries no
-     *   glyph structure, only a weak luminance signal.
+     * - "filter" (default): dual counter-drifting spatter layers in
+     *   strict black/white/gray — static BOLD glyph apertures over an
+     *   oppositely drifting, statistically matched gray spatter field
+     *   on the theme's ground (near-black dark theme / near-white
+     *   light theme), plus a small visibility-direction lightness
+     *   pedestal and halo. Readable in motion; a single screenshot
+     *   carries no glyph structure, only a weak luminance signal.
      * - "sweep": a readable window — ordinary high-contrast text inside
      *   a narrow band sweeping across the row. Easy to read; a single
      *   screenshot leaks the band's characters in the clear.
@@ -313,7 +317,16 @@ export default defineComponent({
       // previous base instead (latent for consumer themes authored in
       // those functions; hikari's own themes use rgb triplets/hex).
       if (/^(oklch|oklab|lab|lch|color)\(/i.test(raw.trim())) return null;
-      const ns = raw.split(/[\s,()rgba]+/).map(Number).filter((n) => !isNaN(n));
+      // Leading separators are REAL here: a computed `rgb(r, g, b)`
+      // string starts with "rgb(" and the split would yield a leading
+      // EMPTY token — Number("") === 0, which silently shifts the
+      // triple to [0, r, g] and skews every derived HSL channel (the
+      // filter theme proxy read a light ink as 45.7% lightness).
+      const ns = raw
+        .split(/[\s,()rgba]+/)
+        .filter((t) => t !== "")
+        .map(Number)
+        .filter((n) => !isNaN(n));
       return ns.length >= 3 ? [ns[0], ns[1], ns[2]] : null;
     }
 
@@ -789,7 +802,12 @@ export default defineComponent({
         sweepT = 0;
         if (!parked) {
           if (props.revealStrategy === "filter") {
-            revealFilter.beginHold(textHsl, dpr);
+            // Grayscale spatter anchored to the effective theme: dark
+            // themes carry light field ink, so the ink lightness is
+            // the theme proxy — light ink (>= 50) means a dark theme
+            // (near-black ground), dark ink a light theme (near-white
+            // ground). No theme hue survives into the spatter.
+            revealFilter.beginHold(textHsl[2] >= 50 ? "dark" : "light", dpr);
           } else {
             revealNoise.beginHold(textHsl);
           }

package/src/components/HkScrollContainer.test.ts

@@ -248,3 +248,156 @@ describe("HkScrollContainer approachEnd", () => {
     expect(emissions.length).toBe(2);
   });
 });
+
+// ── Back-to-top signal (scroll parameter every template can hand to a
+// floating quick-action pad) — sensed on the container's own throttled
+// pass; HkWaterfall forwards these thresholds and mirrors the emit. ──
+describe("HkScrollContainer back-to-top signal", () => {
+  async function flushFrames(): Promise<void> {
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+  }
+
+  it("emits update:backTopVisible with the SHOW/HIDE hysteresis band", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const emitted: boolean[] = [];
+    const instance = ref<{ backTopVisible?: boolean } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            ref: instance as never,
+            backTopShow: 360,
+            backTopHide: 240,
+            "onUpdate:backTopVisible": (v: boolean) => emitted.push(v),
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+
+    const scrollTo = async (top: number) => {
+      stubGeometry(viewport, { scrollTop: top, scrollHeight: 5000, clientHeight: 400 });
+      viewport.dispatchEvent(new Event("scroll"));
+      await flushFrames();
+    };
+
+    await scrollTo(0);
+    expect(emitted).toEqual([]); // below: never emits
+    await scrollTo(300);
+    expect(emitted).toEqual([]); // inside the band, was hidden: stays hidden
+    await scrollTo(400);
+    expect(emitted).toEqual([true]); // past SHOW: emits true
+    emitted.length = 0;
+    await scrollTo(300);
+    expect(emitted).toEqual([]); // inside the band, was visible: stays visible
+    await scrollTo(200);
+    expect(emitted).toEqual([false]); // below HIDE: emits false
+    app.unmount();
+  });
+
+  it("exposes the sensed state as backTopVisible", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const instance = ref<{ backTopVisible?: boolean } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            ref: instance as never,
+            backTopShow: 100,
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+
+    stubGeometry(viewport, { scrollTop: 500, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(instance.value?.backTopVisible).toBe(true);
+
+    // Show-only mode hides at the SAME threshold it shows at: 50 < 100
+    // must read false (the hysteresis fallback `top > show` is what
+    // pins this — a mutant `top > 0` would keep it true here).
+    stubGeometry(viewport, { scrollTop: 50, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(instance.value?.backTopVisible).toBe(false);
+
+    stubGeometry(viewport, { scrollTop: 0, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(instance.value?.backTopVisible).toBe(false);
+    app.unmount();
+  });
+
+  it("re-senses immediately when the thresholds change at runtime", async () => {
+    // Live-read contract (same as approachDistance): toggling backTopShow
+    // after mount must emit without waiting for the next scroll event —
+    // a consumer that swaps thresholds while idle gets a truthful signal.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const emitted: boolean[] = [];
+    const props = reactive({ backTopShow: undefined as number | undefined });
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            backTopShow: props.backTopShow,
+            "onUpdate:backTopVisible": (v: boolean) => emitted.push(v),
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+    stubGeometry(viewport, { scrollTop: 500, scrollHeight: 5000, clientHeight: 400 });
+    await flushFrames();
+    expect(emitted).toEqual([]); // inert while unset, geometry already past
+
+    props.backTopShow = 100;
+    await nextTick();
+    await flushFrames();
+    expect(emitted).toEqual([true]); // re-sensed without any scroll event
+    app.unmount();
+  });
+
+  it("never emits while backTopShow is unset", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const emitted: boolean[] = [];
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            "onUpdate:backTopVisible": (v: boolean) => emitted.push(v),
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+    stubGeometry(viewport, { scrollTop: 5000, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(emitted).toEqual([]);
+    app.unmount();
+  });
+});

package/src/components/HkScrollContainer.tsx

@@ -85,8 +85,23 @@ export default defineComponent({
      *  scroll content dissolving at the dock's edge reads as
      *  intentional instead of a hard clip. */
     dockFade: { type: Boolean, default: true },
+    /** Back-to-top signal (scroll parameter every scrollable template
+     *  can hand to a floating quick-action pad): while set, the
+     *  container derives a visibility signal from its own throttled
+     *  scroll pass — visible once scrollTop passes SHOW px, hidden
+     *  again below HIDE px. The HIDE < SHOW hysteresis band stops the
+     *  signal from flickering when the user idles at one threshold.
+     *  Emits `update:backTopVisible` on change; inert (never emitted)
+     *  while unset. */
+    backTopShow: { type: Number, default: undefined },
+    /** Hide threshold of the hysteresis; only read when `backTopShow`
+     *  is also set. Without it the signal falls back to the single
+     *  `top > backTopShow` test. A misconfigured `backTopHide >=
+     *  backTopShow` degrades the same way (the show test wins first),
+     *  so the band only widens, never inverts. */
+    backTopHide: { type: Number, default: undefined },
   },
-  emits: { approachEnd: () => true },
+  emits: { approachEnd: () => true, "update:backTopVisible": (_v: boolean) => true },
   setup(props, { slots, expose, emit }) {
     const { t } = useI18n();
     const viewportRef = ref<HTMLElement>();
@@ -112,6 +127,12 @@ export default defineComponent({
 
     const pinned = ref(true);
     const FOLLOW_THRESHOLD = 24;
+
+    // Back-to-top visibility (see the backTopShow prop doc). Starts
+    // false and only ever changes through the sensed hysteresis below —
+    // the same semantics HkWaterfall shipped before the signal moved
+    // down to the shared scroll host.
+    const backTopVisible = ref(false);
     const autoFollowContent = shallowRef<HTMLElement | null>(null);
     let followRO: ResizeObserver | null = null;
     const showAutoTag = computed(() => props.autoFollow && props.scrollbar && pinned.value);
@@ -186,6 +207,13 @@ export default defineComponent({
       scheduleUpdate();
     }, { flush: "post" });
 
+    // Runtime threshold changes re-sense immediately (same live-read
+    // contract as approachDistance): without this, a backTopShow toggle
+    // after mount would emit nothing until the next scroll/resize.
+    watch(() => [props.backTopShow, props.backTopHide] as const, () => {
+      scheduleUpdate();
+    });
+
     /** Build the overlay tracks for the enabled axes (scrollbar on). */
     function mountScrollbars() {
       const vp = viewportRef.value;
@@ -261,6 +289,30 @@ export default defineComponent({
       const vp = viewportRef.value;
       if (!vp) return;
       senseOverflow(vp);
+      senseBackTop(vp);
+    }
+
+    /** Back-to-top hysteresis, derived on the same throttled pass as the
+     *  overflow sensing (scroll / resize / content resize / refresh) so
+     *  every scrollable template gets the signal for free — no consumer
+     *  installs a second scroll listener. */
+    function senseBackTop(vp: HTMLElement) {
+      if (props.backTopShow === undefined) return;
+      const top = vp.scrollTop;
+      const show = props.backTopShow;
+      const hide = props.backTopHide;
+      const next =
+        hide !== undefined
+          ? top > show
+            ? true
+            : top < hide
+              ? false
+              : backTopVisible.value
+          : top > show;
+      if (next !== backTopVisible.value) {
+        backTopVisible.value = next;
+        emit("update:backTopVisible", next);
+      }
     }
 
     /** Mirror the live scroll geometry onto the root element as
@@ -455,7 +507,7 @@ export default defineComponent({
       approachHandle.value?.recheck();
     }
 
-    expose({ scrollTo, scrollToElement, getScrollElement, getScrollTop, refresh, getOverflow, isNearEnd, recheck });
+    expose({ scrollTo, scrollToElement, getScrollElement, getScrollTop, refresh, getOverflow, isNearEnd, recheck, backTopVisible });
 
     return () => {
       const Tag = props.as as "div" | "section" | "nav" | "main" | "aside";

package/src/components/HkWaterfall.tsx

@@ -252,25 +252,11 @@ export default defineComponent({
     function recomputeActive() {
       scrollRaf = null;
       if (!scrollEl) return;
-      const top = scrollEl.scrollTop;
-
-      if (props.backTopShow !== undefined) {
-        const show = props.backTopShow;
-        const hide = props.backTopHide;
-        const next =
-          hide !== undefined
-            ? top > show
-              ? true
-              : top < hide
-                ? false
-                : backTopVisible.value
-            : top > show;
-        if (next !== backTopVisible.value) {
-          backTopVisible.value = next;
-          emit("update:backTopVisible", next);
-        }
-      }
-
+      // Back-to-top visibility is no longer derived here: the shared
+      // scroll host (HkScrollContainer) senses it on its own throttled
+      // pass and this view mirrors the host's signal (see the render
+      // wiring below) — one scroll pass, one source of truth, and every
+      // other scrollable template gets the same signal for free.
       const viewportTop = scrollEl.getBoundingClientRect().top;
       const attr = sectionAttribute.value;
       const sections = scrollEl.querySelectorAll<HTMLElement>(`[${attr}]`);
@@ -409,6 +395,18 @@ export default defineComponent({
           class="hk-waterfall-scroll"
           mode="windowed"
           overscanScreens={props.overscanScreens}
+          // Back-to-top sensing lives on the scroll host now; this view
+          // forwards the thresholds and mirrors the emitted signal so its
+          // own public contract (update:backTopVisible + exposed
+          // backTopVisible) is unchanged for consumers.
+          backTopShow={props.backTopShow}
+          backTopHide={props.backTopHide}
+          onUpdate:backTopVisible={(v: boolean) => {
+            if (v !== backTopVisible.value) {
+              backTopVisible.value = v;
+              emit("update:backTopVisible", v);
+            }
+          }}
         >
           {{
             default: () =>

package/src/components/revealKinematogram.test.ts

@@ -139,7 +139,7 @@ describe("RevealFilterPainter", () => {
     const p = new RevealFilterPainter();
     const rand = vi.spyOn(Math, "random").mockReturnValue(0.25);
     try {
-      p.beginHold([220, 10, 15]);
+      p.beginHold("dark");
       // Drift-sign draw, then one phase draw per layer before retile;
       // happy-dom has no 2d context, so the tile builds bail before
       // consuming any more randomness.
@@ -158,7 +158,7 @@ describe("RevealFilterPainter", () => {
     const p = new RevealFilterPainter();
     const rand = vi.spyOn(Math, "random").mockReturnValue(0.25); // driftSign = +1
     try {
-      p.beginHold([220, 10, 15]);
+      p.beginHold("dark");
       const before = p.peekDrift();
       p.advance(0.25, 2);
       const after = p.peekDrift();
@@ -174,7 +174,7 @@ describe("RevealFilterPainter", () => {
     const p = new RevealFilterPainter();
     const rand = vi.spyOn(Math, "random").mockReturnValue(0.75); // driftSign = -1
     try {
-      p.beginHold([220, 10, 15]);
+      p.beginHold("dark");
       const before = p.peekDrift();
       p.advance(0.25, 2);
       const after = p.peekDrift();
@@ -188,7 +188,7 @@ describe("RevealFilterPainter", () => {
 
   it("never throws without a 2d context and stays unusable (fallback path)", () => {
     const p = new RevealFilterPainter();
-    expect(() => p.beginHold([220, 10, 15])).not.toThrow();
+    expect(() => p.beginHold("dark")).not.toThrow();
     expect(p.available).toBe(false);
   });
 });

package/src/components/revealKinematogram.ts

@@ -395,16 +395,25 @@ export class RevealNoisePainter {
  * area carries ONE spatter texture drifting in one direction; the
  * password glyphs are STATIC apertures carrying a SECOND spatter
  * texture — statistically identical (same generator, dot size and
- * lightness distribution) but drifting the OPPOSITE way and lifted by
- * a small lightness pedestal, with a soft halo band brightening the
- * surround of the glyph row. A human segments the two layers
- * effortlessly (motion transparency at a 180° direction difference is
- * the strongest segregation cue the visual system has) and reads the
- * row aided by the pedestal + halo, while any SINGLE frame carries no
- * motion at all: the glyph boundary survives only as a small mean-
- * luminance step inside a smooth halo ramp — nothing for a global or
- * adaptive threshold to plateau on, and (matched statistics) nothing
- * for a texture classifier either.
+ * lightness distribution) but drifting the OPPOSITE way and shifted by
+ * a small lightness pedestal toward the theme's visibility direction,
+ * with a soft halo band around the glyph row. A human segments the two
+ * layers effortlessly (motion transparency at a 180° direction
+ * difference is the strongest segregation cue the visual system has)
+ * and reads the row aided by the pedestal + halo, while any SINGLE
+ * frame carries no motion at all: the glyph boundary survives only as
+ * a small mean-luminance step inside a smooth halo ramp — nothing for
+ * a global or adaptive threshold to plateau on, and (matched
+ * statistics) nothing for a texture classifier either.
+ *
+ * The palette is strictly GRAYSCALE — black, white and grays only, no
+ * theme hue survives into the spatter (the ink-colored variant read as
+ * an uncomfortable cyan). The two anchors follow the EFFECTIVE theme:
+ * a dark theme (light field ink) gets a near-black ground with light
+ * gray speckle, a white halo and a BRIGHTER glyph pedestal; a light
+ * theme (dark ink) inverts every one of those — near-white ground,
+ * dark gray speckle, black halo, DARKER glyph pedestal. Visibility,
+ * not absolute brightness, is the invariant.
  *
  * Why these parameters (the failure modes of video CAPTCHAs say what
  * to avoid — NuCAPTCHA & animated-GIF schemes died to per-frame OCR +
@@ -415,6 +424,10 @@ export class RevealNoisePainter {
  *   and motion signal both peak near the letters' diagnostic spatial
  *   band, so MODERATE noise contrast suffices (the old design's fine
  *   grain + fast ±40px/s drift is exactly what made it unreadable).
+ * - The glyph apertures rasterize in BOLD: a heavier stroke exposes
+ *   more of the counter-drifting texture inside each glyph (stronger
+ *   signal under interference); the shared layout's 1.2× letter
+ *   spacing absorbs the wider advances.
  * - Drift ±FILTER_DRIFT_PX_S: slow enough to track coherently at field
  *   sizes, fast enough that a single frame carries no usable motion
  *   energy (form-from-motion needs ~100–200ms of integration).
@@ -436,20 +449,29 @@ export class RevealNoisePainter {
  *
  * Invariants the tests pin: glyph geometry NEVER touches the visible
  * canvas (mask → `source-in` noise stamp, exactly like the noise
- * painter); the two tiles differ in mean luminance (the pedestal);
- * the halo gradient is drawn every frame; a pattern-less or
- * gradient-less engine degrades to the static plain text (filter
- * exists FOR readability — never to frozen noise). */
+ * painter); every spatter fill is a NEUTRAL gray (r === g === b); the
+ * ground anchor follows the theme (near-black vs near-white); the two
+ * tiles differ in mean luminance along the theme's pedestal direction;
+ * the mask rasterizes in bold; the halo gradient is drawn every frame
+ * in the theme's halo color; a pattern-less or gradient-less engine
+ * degrades to the static plain text (filter exists FOR readability —
+ * never to frozen noise). */
+
+/** Effective theme the filter anchors its grayscale palette to. */
+export type RevealFilterTheme = "dark" | "light";
 
 /** Counter-drift speed of each layer in CSS px/s (opposite signs). */
 export const FILTER_DRIFT_PX_S = 84;
 
-/** Lightness pedestal of the glyph layer over the background layer,
- * in HSL lightness points (clamped into [L_MIN, L_MAX] like every
- * sample). Small on purpose — see the strategy docblock. */
+/** Lightness pedestal of the glyph layer, in HSL lightness points
+ * (clamped into [L_MIN, L_MAX] like every sample). The DIRECTION
+ * follows the theme: brighter glyphs over a dark theme's ground,
+ * darker glyphs over a light theme's. Small on purpose — see the
+ * strategy docblock. */
 export const FILTER_PEDESTAL_L = 10;
 
-/** Peak alpha of the halo band (white, at the glyph-row midline). */
+/** Peak alpha of the halo band (theme-colored, at the glyph midline):
+ * white over a dark ground, black over a light ground. */
 export const FILTER_HALO_ALPHA = 0.1;
 
 /** Halo half-height as a multiple of the glyph font size (device px):
@@ -472,10 +494,17 @@ const FILTER_SPATTER_PX_PER_DOT = 45;
 /** Dot lightness spread around the layer base (both layers share it). */
 const FILTER_SPATTER_L_SPREAD = 22;
 
-/** Tile ground sits this far below the layer base so the dots read as
- * speckles on a darker field; the pedestal lifts ground AND dots
- * together so the whole glyph aperture carries the +pedestal mean. */
-const FILTER_SPATTER_GROUND_L = 30;
+/** Dark theme anchors: near-black ground, mid-light gray speckle. */
+const FILTER_DARK_BASE_L = 64;
+const FILTER_DARK_GROUND_L = 10;
+
+/** Light theme anchors: near-white ground, mid-dark gray speckle. */
+const FILTER_LIGHT_BASE_L = 38;
+const FILTER_LIGHT_GROUND_L = 93;
+
+/** Glyph aperture weight: bold strokes expose more of the counter-
+ * drifting texture inside each glyph. */
+const FILTER_APERTURE_WEIGHT = "bold";
 
 export class RevealFilterPainter {
   private bgTile: HTMLCanvasElement | null = null;
@@ -485,6 +514,7 @@ export class RevealFilterPainter {
   private offsetBackground = 0;
   private offsetInk = 0;
   private driftSign = 1;
+  private theme: RevealFilterTheme = "dark";
   private dpr = 1;
   private ok = true;
 
@@ -500,17 +530,20 @@ export class RevealFilterPainter {
     return { background: this.offsetBackground, ink: this.offsetInk };
   }
 
-  /** Start a hold: two FRESH spatter tiles (background at the base
-   * lightness, glyph layer lifted by the pedestal), randomized phases
-   * and a randomized drift direction, so replays are never
+  /** Start a hold: two FRESH grayscale spatter tiles anchored to the
+   * theme (near-black/near-white ground), the glyph layer shifted by
+   * the pedestal along the theme's visibility direction, randomized
+   * phases and a randomized drift direction, so replays are never
    * pixel-identical and automation cannot precompute the motion. */
-  beginHold(base: Hsl, dpr = 1): void {
+  beginHold(theme: RevealFilterTheme = "dark", dpr = 1): void {
     this.dpr = dpr;
+    this.theme = theme;
     this.driftSign = Math.random() < 0.5 ? 1 : -1;
     this.offsetBackground = Math.random() * NOISE_TILE_W;
     this.offsetInk = Math.random() * NOISE_TILE_W;
     this.maskKey = ""; // force a mask rebuild on the first paint
-    this.ok = this.retile(base, 0, "bg") && this.retile(base, FILTER_PEDESTAL_L, "ink");
+    const pedestal = (theme === "dark" ? 1 : -1) * FILTER_PEDESTAL_L;
+    this.ok = this.retile(0, "bg") && this.retile(pedestal, "ink");
   }
 
   advance(dt: number, dpr: number): void {
@@ -519,11 +552,12 @@ export class RevealFilterPainter {
     this.offsetInk -= this.driftSign * step;
   }
 
-  /** (Re)build one spatter tile: a darkened ground of the ink color,
-   * then a fixed-density scatter of soft dots at the layer lightness.
+  /** (Re)build one spatter tile: the theme's ground (near-black over a
+   * dark theme, near-white over a light one), then a fixed-density
+   * scatter of NEUTRAL-GRAY dots around the theme's base lightness.
    * Draw order is deterministic (bg tile first, then ink) so tests can
    * attribute the per-canvas recordings. */
-  private retile(base: Hsl, pedestalL: number, which: "bg" | "ink"): boolean {
+  private retile(pedestalL: number, which: "bg" | "ink"): boolean {
     try {
       if (typeof document === "undefined") return false;
       if (which === "bg") {
@@ -536,17 +570,20 @@ export class RevealFilterPainter {
       tile.height = NOISE_TILE_H;
       const tctx = tile.getContext("2d");
       if (!tctx) return false;
-      const [h, s, l] = base;
+      const dark = this.theme === "dark";
+      const baseL = dark ? FILTER_DARK_BASE_L : FILTER_LIGHT_BASE_L;
+      const groundL = dark ? FILTER_DARK_GROUND_L : FILTER_LIGHT_GROUND_L;
       const lift = (v: number) => Math.min(L_MAX, Math.max(L_MIN, v));
-      const [gr, gg, gb] = hslToRgb(h, s, lift(l + pedestalL - FILTER_SPATTER_GROUND_L));
+      // Saturation is ZERO by construction — black/white/gray only.
+      const [gr, gg, gb] = hslToRgb(0, 0, lift(groundL + pedestalL));
       tctx.fillStyle = `rgb(${gr},${gg},${gb})`;
       tctx.fillRect(0, 0, NOISE_TILE_W, NOISE_TILE_H);
       const count = Math.round((NOISE_TILE_W * NOISE_TILE_H) / FILTER_SPATTER_PX_PER_DOT);
       const rMin = FILTER_SPATTER_R_MIN_CSS * this.dpr;
       const rMax = FILTER_SPATTER_R_MAX_CSS * this.dpr;
       for (let i = 0; i < count; i++) {
-        const dl = lift(l + pedestalL + (Math.random() * 2 - 1) * FILTER_SPATTER_L_SPREAD);
-        const [r, g, b] = hslToRgb(h, s, dl);
+        const dl = lift(baseL + pedestalL + (Math.random() * 2 - 1) * FILTER_SPATTER_L_SPREAD);
+        const [r, g, b] = hslToRgb(0, 0, dl);
         tctx.fillStyle = `rgb(${r},${g},${b})`;
         const rad = rMin + Math.random() * (rMax - rMin);
         tctx.beginPath();
@@ -588,14 +625,19 @@ export class RevealFilterPainter {
       }
       // Create the halo gradient up front as well: creation draws
       // nothing, so a bail here still leaves the visible canvas
-      // untouched (no partial frame — see the pre-check above).
+      // untouched (no partial frame — see the pre-check above). The
+      // halo color follows the theme: white over a dark ground, black
+      // over a light one.
       const bandH = Math.min(H / 2, FILTER_HALO_FONT_SCALE * layout.fontPx);
       const midY = H / 2;
+      // Endpoints derive from the SAME theme channel string as the
+      // peak — no literal compare that could silently desync them.
+      const haloRGB = this.theme === "dark" ? "255,255,255" : "0,0,0";
       const grad = ctx.createLinearGradient(0, midY - bandH, 0, midY + bandH);
       if (!grad) return false;
-      grad.addColorStop(0, "rgba(255,255,255,0)");
-      grad.addColorStop(0.5, `rgba(255,255,255,${FILTER_HALO_ALPHA})`);
-      grad.addColorStop(1, "rgba(255,255,255,0)");
+      grad.addColorStop(0, `rgba(${haloRGB},0)`);
+      grad.addColorStop(0.5, `rgba(${haloRGB},${FILTER_HALO_ALPHA})`);
+      grad.addColorStop(1, `rgba(${haloRGB},0)`);
       this.mask ??= document.createElement("canvas");
       if (this.mask.width !== W || this.mask.height !== H) {
         this.mask.width = W;
@@ -611,7 +653,7 @@ export class RevealFilterPainter {
         mctx.fillStyle = "#fff";
         mctx.textAlign = "left";
         mctx.textBaseline = "middle";
-        mctx.font = `${layout.fontPx.toFixed(2)}px ${monoFont}`;
+        mctx.font = `${FILTER_APERTURE_WEIGHT} ${layout.fontPx.toFixed(2)}px ${monoFont}`;
         for (const g of layout.glyphs) {
           mctx.fillText(g.ch, g.x, H / 2);
         }