@celestia-island/hikari 0.55.18 → 0.55.19

package/package.json

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

package/src/DemoApp.tsx

@@ -366,7 +366,8 @@ export default defineComponent({
             <HInput modelValue={form.value.text} onUpdate:modelValue={(v: string) => (form.value.text = v)} placeholder="Disabled" disabled />
             <HSearchInput modelValue={form.value.search} onUpdate:modelValue={(v: string | number) => (form.value.search = String(v))} placeholder="Search..." />
             <HNumberInput modelValue={form.value.number} onUpdate:modelValue={(v: number) => (form.value.number = v)} placeholder="Number" />
-            <HInput variant="password" modelValue={form.value.password} onUpdate:modelValue={(v: string) => (form.value.password = v)} placeholder="Password (sweep reveal — default)" />
+            <HInput variant="password" modelValue={form.value.password} onUpdate:modelValue={(v: string) => (form.value.password = v)} placeholder="Password (filter reveal — default)" />
+            <HInput variant="password" revealStrategy="sweep" modelValue={form.value.password} onUpdate:modelValue={(v: string) => (form.value.password = v)} placeholder="Password (sweep reveal — readable band)" />
             <HInput variant="password" revealStrategy="noise" modelValue={form.value.password} onUpdate:modelValue={(v: string) => (form.value.password = v)} placeholder="Password (noise reveal — screenshot-safe)" />
             <HInput variant="password" revealStrategy="plain" modelValue={form.value.password} onUpdate:modelValue={(v: string) => (form.value.password = v)} placeholder="Password (plain reveal)" />
             <HInput variant="password" revealTrigger="toggle" modelValue={form.value.password} onUpdate:modelValue={(v: string) => (form.value.password = v)} placeholder="Password (click eye toggles)" />

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

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { Comment, createApp, createVNode, h, nextTick, ref, type Slot } from "vue";
 
 import HkInput from "./HkInput";
+import HkPasswordSurface from "./HkPasswordSurface";
 import { NOISE_TILE_H, NOISE_TILE_W } from "./revealKinematogram";
 import { passwordLevel } from "../utils/password";
 import { setReducedMotion } from "../runtime/animationBus";
@@ -14,9 +15,9 @@ import { setReducedMotion } from "../runtime/animationBus";
  *   hint, caps-lock / full-width hints, pending-clear refocus semantics
  * - right-edge affordance (passwordTrailing): eye reveal (default) /
  *   strength traffic light / none
- * - reveal strategy (revealStrategy): "sweep" readable window (default)
- *   vs "noise" boiling kinematogram (screenshot-safe) vs "plain"
- *   readable text
+ * - reveal strategy (revealStrategy): "filter" dual counter-drifting
+ *   spatter layers (default) vs "sweep" readable window vs "noise"
+ *   boiling kinematogram (screenshot-safe) vs "plain" readable text
  * - reveal trigger (revealTrigger): press-and-hold (default) vs
  *   click-to-toggle with auto-hide (revealAutoHideMs)
  * - the strength dot classifies through the shared passwordLevel util
@@ -1313,13 +1314,27 @@ describe("HkInput password reveal eye", () => {
 /** Installs a per-canvas recording getContext stub (happy-dom has no
  * real 2d): every canvas element gets its own recorder so a test can
  * tell the visible dot canvas apart from offscreen painter canvases. */
-function stubRecordingContexts() {
+function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
+  // linearGradients: false simulates a pattern-ful but gradient-less
+  // engine (the filter painter must hand the frame back BEFORE any
+  // visible drawing so the component can latch the plain fallback).
+  const { linearGradients = true } = opts;
   interface CanvasRec {
     canvas: HTMLCanvasElement;
     texts: string[];
     patternFills: number;
     drawImages: number;
     putImageDatas: number;
+    gradients: number;
+    /** fillRect calls that actually ran with a gradient as fillStyle —
+     * the halo DRAWN pin (creation alone proves nothing, R2 M3). */
+    gradientFills: number;
+    /** globalCompositeOperation assignments, in order — the mask MUST
+     * see "source-in" before its pattern fill or the glyphs never get
+     * carved out of the ink spatter (R3 F2: without this the password
+     * would render INVISIBLE on a real canvas, silently). */
+    compositeOps: string[];
+    fillStyles: string[];
     clips: Array<{ x: number; y: number; w: number; h: number }>;
     translates: number[];
   }
@@ -1336,13 +1351,20 @@ function stubRecordingContexts() {
         patternFills: 0,
         drawImages: 0,
         putImageDatas: 0,
+        gradients: 0,
+        gradientFills: 0,
+        compositeOps: [],
+        fillStyles: [],
         clips: [],
         translates: [],
       };
       byCanvas.set(this, rec);
     }
     const r = rec;
-    return {
+    let fillStyleBox: string | CanvasGradient | CanvasPattern = "";
+    let gradientArmed = false;
+    let compositeOpBox: GlobalCompositeOperation = "source-over";
+    const stub: Record<string, unknown> = {
       canvas: this,
       clearRect: () => {},
       save: () => {},
@@ -1352,7 +1374,12 @@ function stubRecordingContexts() {
       beginPath: () => {},
       arc: () => {},
       fill: () => {},
-      fillRect: () => {},
+      fillRect: () => {
+        if (gradientArmed) {
+          r.gradientFills++;
+          gradientArmed = false;
+        }
+      },
       measureText: () => ({ width: 10 }),
       fillText: (text: string) => r.texts.push(String(text)),
       drawImage: () => r.drawImages++,
@@ -1360,6 +1387,10 @@ function stubRecordingContexts() {
         r.patternFills++;
         return {} as CanvasPattern;
       },
+      createLinearGradient: () => {
+        r.gradients++;
+        return { __recGradient: true, addColorStop: () => {} } as unknown as CanvasGradient;
+      },
       createImageData: (w: number, h: number) => ({
         data: new Uint8ClampedArray(w * h * 4),
       }),
@@ -1368,12 +1399,30 @@ function stubRecordingContexts() {
         r.clips.push({ x, y, w, h }),
       clip: () => {},
       imageSmoothingEnabled: false,
-      globalCompositeOperation: "source-over",
+      get globalCompositeOperation() {
+        return compositeOpBox;
+      },
+      set globalCompositeOperation(v: GlobalCompositeOperation) {
+        compositeOpBox = v;
+        r.compositeOps.push(String(v));
+      },
       font: "",
-      fillStyle: "",
+      get fillStyle() {
+        return fillStyleBox;
+      },
+      set fillStyle(v: string | CanvasGradient | CanvasPattern) {
+        fillStyleBox = v;
+        gradientArmed =
+          typeof v === "object" &&
+          v !== null &&
+          (v as { __recGradient?: boolean }).__recGradient === true;
+        if (typeof v === "string") r.fillStyles.push(v);
+      },
       textAlign: "",
       textBaseline: "",
-    } as unknown as CanvasRenderingContext2D;
+    };
+    if (!linearGradients) delete stub.createLinearGradient;
+    return stub as unknown as CanvasRenderingContext2D;
   }) as unknown as typeof HTMLCanvasElement.prototype.getContext;
   return {
     byCanvas,
@@ -1384,13 +1433,15 @@ function stubRecordingContexts() {
 }
 
 describe("HkInput password reveal strategies", () => {
-  it("sweep (default) draws readable text inside a moving window over the noise field", async () => {
-    // The default reveal: real high-contrast text clipped to a band
+  it("sweep draws readable text inside a moving window over the noise field", async () => {
+    // The opt-in readable band: real high-contrast text clipped to a band
     // that sweeps across the row (sweepWindow), on top of the boiling
     // noise field. A single frame leaks only the band's characters.
     const rec = stubRecordingContexts();
     try {
-      const { container, input } = mountPasswordInput("abc");
+      const { container, input } = mountPasswordInput("abc", {
+        revealStrategy: "sweep",
+      });
       const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
       eye.dispatchEvent(
         new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
@@ -1437,7 +1488,9 @@ describe("HkInput password reveal strategies", () => {
     // left it (R2 mutation M23 — the sweepT reset had no pin).
     const rec = stubRecordingContexts();
     try {
-      const { container } = mountPasswordInput("abc");
+      const { container } = mountPasswordInput("abc", {
+        revealStrategy: "sweep",
+      });
       const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
       eye.dispatchEvent(
         new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
@@ -1483,7 +1536,9 @@ describe("HkInput password reveal strategies", () => {
     setReducedMotion(true);
     const rec = stubRecordingContexts();
     try {
-      const { container } = mountPasswordInput("abc");
+      const { container } = mountPasswordInput("abc", {
+        revealStrategy: "sweep",
+      });
       const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
       eye.dispatchEvent(
         new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
@@ -1508,6 +1563,240 @@ 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).
+    const rand = vi.spyOn(Math, "random").mockReturnValue(0.5);
+    const rec = stubRecordingContexts();
+    try {
+      const { container, input } = 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)!;
+      // No glyph on the visible canvas — the screenshot sees spatter,
+      // halo and a noise-composited stamp, never letterforms…
+      expect(vis.texts).toEqual([]);
+      // …while the offscreen mask rasterized the row exactly once.
+      const allRecs = Array.from(rec.byCanvas.values());
+      const mask = allRecs.find((r) => r.texts.length > 0);
+      expect(mask, "offscreen glyph mask").toBeTruthy();
+      expect(mask!.texts).toEqual(["a", "b", "c"]);
+      // The mask MUST carve the glyphs out of the ink spatter via
+      // source-in compositing — losing it renders the password
+      // INVISIBLE on a real canvas (R3 F2, a silent total-loss
+      // regression the suite previously could not see).
+      expect(mask!.compositeOps, "mask carves glyphs via source-in").toContain("source-in");
+      // The first frame already carries background spatter (pattern),
+      // the halo ramp (gradient CREATED and then actually FILLED) and
+      // the mask stamp (drawImage).
+      expect(vis.patternFills).toBeGreaterThan(0);
+      expect(vis.gradients, "halo gradient created").toBeGreaterThan(0);
+      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).
+      const tiles = allRecs.filter(
+        (r) => r.fillStyles.filter((s) => s.startsWith("rgb(")).length > 100,
+      );
+      expect(tiles.length, "exactly two spatter tiles").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,
+        `glyph layer carries the lightness pedestal (bg ${bgMean.toFixed(1)} vs ink ${inkMean.toFixed(1)})`,
+      ).toBeGreaterThan(8);
+      // The DOM input still never flips.
+      expect(input.type).toBe("password");
+      // Bus frames advance BOTH layer drifts (fresh pattern phases on
+      // the visible ctx for the background, on the mask ctx for the
+      // glyph layer).
+      const visTranslates = vis.translates.length;
+      const maskTranslates = mask!.translates.length;
+      const visPatterns = vis.patternFills;
+      const visGradientFills = vis.gradientFills;
+      // Distinct drift PHASES, not just repeat calls — a frozen
+      // accumulator re-pushes the same wrapped offset every frame and
+      // count-only pins cannot tell (R3 F1).
+      const visDistinct = new Set(vis.translates).size;
+      const maskDistinct = new Set(mask!.translates).size;
+      for (let i = 0; i < 3; i++) {
+        await new Promise((r) => setTimeout(r, 45));
+        await new Promise((r) => requestAnimationFrame(() => r(null)));
+      }
+      expect(vis.patternFills, "background layer keeps drifting").toBeGreaterThan(visPatterns);
+      expect(vis.translates.length, "background pattern phase advances").toBeGreaterThan(visTranslates);
+      expect(mask!.translates.length, "glyph layer counter-drifts").toBeGreaterThan(maskTranslates);
+      expect(new Set(vis.translates).size, "background drift phases CHANGE").toBeGreaterThan(visDistinct);
+      expect(new Set(mask!.translates).size, "glyph drift phases CHANGE").toBeGreaterThan(maskDistinct);
+      expect(vis.gradientFills, "halo redrawn every frame").toBeGreaterThan(visGradientFills);
+      // Still no glyph on the visible canvas after all those frames.
+      expect(vis.texts).toEqual([]);
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      rec.restore();
+      rand.mockRestore();
+    }
+  });
+
+  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
+    // tile canvases receive a full redraw (ground + every dot) per hold.
+    const rec = stubRecordingContexts();
+    try {
+      const { container } = mountPasswordInput("abc");
+      const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
+      const hold = async () => {
+        eye.dispatchEvent(
+          new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
+        );
+        await nextTick();
+        document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+        await nextTick();
+      };
+      await hold();
+      const tiles = Array.from(rec.byCanvas.values()).filter(
+        (r) => r.fillStyles.filter((s) => s.startsWith("rgb(")).length > 100,
+      );
+      expect(tiles.length).toBe(2);
+      const counts1 = tiles.map((r) => r.fillStyles.length);
+      expect(counts1[0]!, "ground + dots on hold 1").toBeGreaterThan(1000);
+      await hold();
+      const counts2 = tiles.map((r) => r.fillStyles.length);
+      expect(counts2[0]).toBe(counts1[0]! * 2);
+      expect(counts2[1]).toBe(counts1[1]! * 2);
+    } finally {
+      rec.restore();
+    }
+  });
+
+  it("filter degrades to static plain text when the animation bus is parked (reduced motion)", async () => {
+    // Filter's static frame is camouflaged noise BY DESIGN — exactly
+    // what a reduced-motion user cannot trade on. The degrade target is
+    // therefore the fully readable plain text, like the sweep's.
+    setReducedMotion(true);
+    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)!;
+      expect(vis.texts).toEqual(["a", "b", "c"]);
+      // No filter machinery on the visible canvas in the degraded state…
+      expect(vis.patternFills).toBe(0);
+      expect(vis.gradients).toBe(0);
+      // …and the degrade target is PLAIN text, not the legacy jitter
+      // (the jitter translates per glyph, plain never does).
+      expect(vis.translates.length, "static plain, not jitter").toBe(0);
+      await new Promise((r) => setTimeout(r, 260));
+      expect(vis.texts).toEqual(["a", "b", "c"]);
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      rec.restore();
+      setReducedMotion(false);
+    }
+  });
+
+  it("filter hands the frame back untouched on a gradient-less engine, then latches the plain fallback", async () => {
+    // A pattern-ful but gradient-less engine: the painter's pre-check
+    // must bail BEFORE any visible drawing (no partial spatter frame),
+    // and the component then shows the readable plain fallback — the
+    // pin for the capability guard (R1 weak pin C2).
+    const rec = stubRecordingContexts({ linearGradients: false });
+    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)!;
+      // The painter handed the frame back WITHOUT drawing anything…
+      expect(vis.patternFills, "no partial spatter frame").toBe(0);
+      expect(vis.drawImages).toBe(0);
+      // …and the fallback that engaged is the readable plain text.
+      expect(vis.texts).toEqual(["a", "b", "c"]);
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      rec.restore();
+    }
+  });
+
+  it("filter is the surface-level default too (direct HkPasswordSurface mount)", async () => {
+    // HkInput declares and forwards its own default, which is where the
+    // user-facing pin lives — but the surface ALSO declares a default,
+    // and the two must not silently drift apart (R1 weak pin M7). The
+    // surface is internal (never exported), so mount it directly.
+    const rec = stubRecordingContexts();
+    const model = ref("abc");
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render() {
+        return h(HkPasswordSurface, {
+          modelValue: model.value,
+          "onUpdate:modelValue": (v: string) => {
+            model.value = v;
+          },
+        });
+      },
+    });
+    app.mount(container);
+    try {
+      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)!;
+      // Filter signature: glyphs only on the offscreen mask, two
+      // spatter tiles, halo gradient — with NO revealStrategy prop.
+      expect(vis.texts).toEqual([]);
+      const tiles = Array.from(rec.byCanvas.values()).filter(
+        (r) => r.fillStyles.filter((s) => s.startsWith("rgb(")).length > 100,
+      );
+      expect(tiles.length, "two spatter tiles = filter, not sweep/noise").toBe(2);
+      expect(vis.gradientFills, "halo band drawn").toBeGreaterThan(0);
+      document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+      await nextTick();
+    } finally {
+      app.unmount();
+      container.remove();
+      rec.restore();
+    }
+  });
+
   it("plain strategy draws readable text on the VISIBLE canvas — and nothing else", async () => {
     // The opt-in readable reveal (revealStrategy="plain"): glyphs ARE
     // the visible frame — no noise fills, no mask stamp — while the DOM
@@ -1888,10 +2177,13 @@ describe("HkInput password reveal trigger", () => {
     // intervening release must not re-seed the painter mid-hold (fresh
     // noise + phase reset would visibly flash the field). Observable
     // pin: beginHold retiles the noise canvas — exactly ONE
-    // putImageData per reveal.
+    // putImageData per reveal (the NOISE painter's signature; the
+    // filter painter retiles with vector fills instead).
     const rec = stubRecordingContexts();
     try {
-      const { container } = mountPasswordInput("abc");
+      const { container } = mountPasswordInput("abc", {
+        revealStrategy: "noise",
+      });
       const eye = container.querySelector<HTMLElement>("button.hk-pwd-eye")!;
       eye.dispatchEvent(
         new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),

package/src/components/HkInput.tsx

@@ -58,12 +58,12 @@ export default defineComponent({
     /**
      * Right-edge affordance for `variant="password"`:
      * - "eye" (default): the reveal button. While revealed, the canvas
-     *   renders the reveal chosen by `revealStrategy` (the sweep
-     *   readable-window by default; boiling-noise and plain text on
-     *   opt-in); the trigger is `revealTrigger` (press-and-hold by
-     *   default, click-toggle on opt-in). The DOM value stays inside
-     *   the type="password" input at all times — every strategy draws
-     *   on the canvas.
+     *   renders the reveal chosen by `revealStrategy` (the dual-layer
+     *   counter-drifting spatter "filter" by default; sweep readable-
+     *   window, boiling-noise and plain text on opt-in); the trigger
+     *   is `revealTrigger` (press-and-hold by default, click-toggle on
+     *   opt-in). The DOM value stays inside the type="password" input
+     *   at all times — every strategy draws on the canvas.
      * - "strength": the traffic-light dot (weak / fair / strong via the
      *   shared `passwordLevel` classifier, overridable through
      *   `strengthEvaluator`) with a localized tooltip on hover and on
@@ -77,11 +77,17 @@ export default defineComponent({
     /**
      * Reveal content for the password eye (`variant="password"`,
      * `passwordTrailing="eye"`):
-     * - "sweep" (default): 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
-     *   only the characters under the band (partial capture
-     *   resistance).
+     * - "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.
+     * - "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
+     *   under the band in the clear (partial capture resistance).
      * - "noise": the boiling-noise kinematogram — statistically pure
      *   noise in any single-frame screenshot (nothing for OCR to lock
      *   onto), but the hardest to read. Opt-in for high-exposure
@@ -92,8 +98,8 @@ export default defineComponent({
      *   shoulder surfers. Pick per threat model.
      */
     revealStrategy: {
-      type: String as () => "sweep" | "noise" | "plain",
-      default: "sweep",
+      type: String as () => "filter" | "sweep" | "noise" | "plain",
+      default: "filter",
     },
     /**
      * Reveal interaction for the password eye: "hold" (default) reveals

package/src/components/HkPasswordSurface.tsx

@@ -24,6 +24,7 @@ import HkTooltip from "./HkTooltip";
 import { HkPlaceholderMarquee, type PlaceholderVariant } from "./HkPlaceholderMarquee";
 import {
   layoutRevealGlyphs,
+  RevealFilterPainter,
   RevealNoisePainter,
   sweepWindow,
   type RevealLayout,
@@ -51,24 +52,29 @@ interface Ripple {
  * Right-edge affordance (`passwordTrailing`):
  * - "eye" (default): the reveal button. What the reveal SHOWS is chosen
  *   by `revealStrategy`, how it is TRIGGERED by `revealTrigger`:
- *   - strategy "sweep" (default): 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 (see
- *     revealKinematogram.ts). Reading is effortless; a single frame —
- *     a screenshot — shows only the characters under the band, the rest
- *     stays noise (partial capture resistance). Reduced motion or a
- *     pattern-less engine degrades to the fully readable static plain
- *     text.
+ *   - 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.
+ *   - 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
+ *     effortless; a single frame shows the characters under the band
+ *     in the clear (partial capture resistance only).
  *   - strategy "noise": the screenshot-safe boiling-noise kinematogram:
  *     one shared noise tile, the background drifting sideways while the
  *     noise sampled through the password glyphs is re-sampled at a
- *     random phase every frame. A human reads the glyph silhouettes off
- *     the flicker-vs-drift contrast, while any single frame — a
- *     screenshot — is pure noise with no glyph structure for OCR to
- *     lock onto. The hardest to read; opt-in for high-exposure
- *     surfaces. When the animation bus is parked (reduced motion) or
- *     the engine cannot run the pattern path, the reveal degrades to
- *     the legacy static per-glyph jitter drawing.
+ *     random phase every frame. Statistically pure noise in ANY single
+ *     frame (nothing for OCR), but the hardest to read; opt-in for
+ *     high-exposure surfaces. When the animation bus is parked
+ *     (reduced motion) or the engine cannot run the pattern path, the
+ *     reveal degrades to the legacy static per-glyph jitter drawing.
  *   - strategy "plain": the industry-standard readable reveal — the
  *     password is drawn as ordinary text on the canvas while revealed
  *     (the DOM input stays type="password"). Readable by everyone,
@@ -112,11 +118,14 @@ export default defineComponent({
     },
     /**
      * What the eye reveal SHOWS:
-     * - "sweep" (default): 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. Genuinely easy to
-     *   read; a single screenshot leaks only the characters under the
-     *   band (partial capture resistance).
+     * - "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.
+     * - "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.
      * - "noise": the screenshot-safe boiling-noise kinematogram —
      *   statistically pure noise in any single frame, nothing for OCR,
      *   but the hardest to read (opt-in for high-exposure surfaces).
@@ -124,8 +133,8 @@ export default defineComponent({
      *   screenshot-visible — pick per threat model).
      */
     revealStrategy: {
-      type: String as () => "sweep" | "noise" | "plain",
-      default: "sweep",
+      type: String as () => "filter" | "sweep" | "noise" | "plain",
+      default: "filter",
     },
     /**
      * How the eye reveal is TRIGGERED: "hold" (default) = press-and-
@@ -177,6 +186,7 @@ export default defineComponent({
     // drives the sweep strategy's window position (seconds since the
     // reveal started).
     const revealNoise = new RevealNoisePainter();
+    const revealFilter = new RevealFilterPainter();
     let revealFrames = 0;
     let revealLayoutValue = "";
     let revealLayoutW = -1;
@@ -494,7 +504,7 @@ export default defineComponent({
     }
 
     /**
-     * Sweep reveal pass (`revealStrategy="sweep"`, the default): the
+     * Sweep reveal pass (`revealStrategy="sweep"`): the
      * boiling-noise field stays as the base layer, and the password is
      * drawn as ordinary high-contrast text ONLY inside a narrow window
      * that sweeps across the row (sweepWindow kinematics: constant
@@ -547,6 +557,28 @@ export default defineComponent({
       ctx.restore();
     }
 
+    /**
+     * Filter reveal pass (`revealStrategy="filter"`, the default): the
+     * whole row stays on screen at all times — static glyph apertures
+     * filled with one spatter texture, over a statistically identical
+     * spatter field drifting the OPPOSITE way, plus a small lightness
+     * pedestal and a halo band. A human reads the row continuously off
+     * the counter-motion + pedestal; a single frame carries no glyph
+     * structure (matched texture statistics), only the weak pedestal
+     * signal dissolved into the halo ramp. Like the sweep, a pattern-
+     * less engine latches the static fallback to PLAIN text — filter
+     * exists for readability, never degrade to frozen noise.
+     */
+    function drawRevealFilterFrame(ctx: CanvasRenderingContext2D, W: number, H: number, dt: number) {
+      const layout = revealLayoutFor(ctx, W, H);
+      if (!layout || layout.glyphs.length === 0) return;
+      revealFilter.advance(dt, dpr);
+      if (!revealFilter.paint(ctx, W, H, layout, cachedMonoFont || syncMonoFont(), revealLayoutKey)) {
+        revealStaticFallback = true;
+        drawRevealPlainText(ctx, W, H);
+      }
+    }
+
     /**
      * Legacy anti-OCR fallback, used only when frames cannot drive the
      * kinematogram (parked animation bus — reduced motion — or an
@@ -628,6 +660,16 @@ export default defineComponent({
           drawRevealSweepFrame(ctx, W, H, dt);
           return;
         }
+        if (props.revealStrategy === "filter") {
+          // Same degrade contract as the sweep: readable in motion,
+          // plain text when motion cannot run.
+          if (revealStaticFallback) {
+            drawRevealPlainText(ctx, W, H);
+            return;
+          }
+          drawRevealFilterFrame(ctx, W, H, dt);
+          return;
+        }
         if (!revealStaticFallback && drawRevealNoise(ctx, W, H, dt)) return;
         drawRevealJitterText(ctx, W, H);
         return;
@@ -724,27 +766,37 @@ export default defineComponent({
       if (!props.modelValue || props.disabled || revealing.value) return;
       syncTextHsl();
       syncMonoFont();
-      // The plain strategy is static — no painter, no watchdog. Both
-      // motion strategies (sweep default, noise opt-in) drive the noise
+      // The plain strategy is static — no painter, no watchdog. The
+      // motion strategies (filter default, sweep, noise) drive their
       // painter per frame and degrade to a STATIC fallback when frames
-      // cannot drive them: sweep falls back to plain text (its whole
-      // point is readability), noise to the legacy jitter.
+      // cannot drive them: filter and sweep fall back to plain text
+      // (their whole point is readability), noise to the legacy jitter.
+      // A parked bus (reduced motion) will never deliver a frame, so
+      // the motion reveals would freeze — filter and sweep into an
+      // unreadable mid-state, noise into pure noise — degrade
+      // immediately to the strategy's static fallback (plain text for
+      // filter and sweep, legacy jitter for noise). Motion-sensitive
+      // users keep their preference and the reveal stays usable. The
+      // plain strategy needs no degrade: its static text is already
+      // motion-free. The parked check runs BEFORE beginHold so a
+      // reduced-motion hold never builds noise/spatter tiles it will
+      // never paint.
       const isPlain = props.revealStrategy === "plain";
+      const parked = !isPlain && isAnimationParked();
       if (!isPlain) {
         revealStaticFallback = false;
         revealFrames = 0;
         sweepT = 0;
-        revealNoise.beginHold(textHsl);
+        if (!parked) {
+          if (props.revealStrategy === "filter") {
+            revealFilter.beginHold(textHsl, dpr);
+          } else {
+            revealNoise.beginHold(textHsl);
+          }
+        }
       }
       revealing.value = true;
-      // A parked bus (reduced motion) will never deliver a frame, so
-      // the motion reveals would freeze — the sweep into unreadable
-      // mid-state noise, the noise into pure noise — degrade immediately
-      // to the strategy's static fallback (plain text for sweep, legacy
-      // jitter for noise). Motion-sensitive users keep their preference
-      // and the reveal stays usable. The plain strategy needs no
-      // degrade: its static text is already motion-free.
-      if (!isPlain && isAnimationParked()) {
+      if (parked) {
         revealStaticFallback = true;
       }
       // Paint one synchronous frame so the reveal appears instantly;

package/src/components/revealKinematogram.test.ts

@@ -2,8 +2,10 @@ import { describe, expect, it, vi } from "vitest";
 
 import {
   BACKGROUND_DRIFT_PX_S,
+  FILTER_DRIFT_PX_S,
   layoutRevealGlyphs,
   NOISE_TILE_W,
+  RevealFilterPainter,
   RevealNoisePainter,
   sweepWindow,
   SWEEP_END_PAUSE_S,
@@ -132,6 +134,65 @@ describe("RevealNoisePainter", () => {
   });
 });
 
+describe("RevealFilterPainter", () => {
+  it("seeds both layer phases from randomness at each hold", () => {
+    const p = new RevealFilterPainter();
+    const rand = vi.spyOn(Math, "random").mockReturnValue(0.25);
+    try {
+      p.beginHold([220, 10, 15]);
+      // 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.
+      const d = p.peekDrift();
+      expect(d.background).toBeCloseTo(0.25 * NOISE_TILE_W, 10);
+      expect(d.ink).toBeCloseTo(0.25 * NOISE_TILE_W, 10);
+    } finally {
+      rand.mockRestore();
+    }
+  });
+
+  it("drifts the two layers in OPPOSITE directions at equal speed", () => {
+    // The segregation cue IS the 180° direction difference: a mutation
+    // sending both layers the same way (or at unequal speeds) must go
+    // red here.
+    const p = new RevealFilterPainter();
+    const rand = vi.spyOn(Math, "random").mockReturnValue(0.25); // driftSign = +1
+    try {
+      p.beginHold([220, 10, 15]);
+      const before = p.peekDrift();
+      p.advance(0.25, 2);
+      const after = p.peekDrift();
+      const step = FILTER_DRIFT_PX_S * 2 * 0.25;
+      expect(after.background - before.background).toBeCloseTo(step, 10);
+      expect(after.ink - before.ink).toBeCloseTo(-step, 10);
+    } finally {
+      rand.mockRestore();
+    }
+  });
+
+  it("flips both drift directions when the per-hold draw says so", () => {
+    const p = new RevealFilterPainter();
+    const rand = vi.spyOn(Math, "random").mockReturnValue(0.75); // driftSign = -1
+    try {
+      p.beginHold([220, 10, 15]);
+      const before = p.peekDrift();
+      p.advance(0.25, 2);
+      const after = p.peekDrift();
+      const step = FILTER_DRIFT_PX_S * 2 * 0.25;
+      expect(after.background - before.background).toBeCloseTo(-step, 10);
+      expect(after.ink - before.ink).toBeCloseTo(step, 10);
+    } finally {
+      rand.mockRestore();
+    }
+  });
+
+  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.available).toBe(false);
+  });
+});
+
 describe("sweepWindow", () => {
   const dpr = 1;
   // A 100px travel at 220 CSS px/s ≈ 0.4545s of movement per cycle.

package/src/components/revealKinematogram.ts

@@ -1,10 +1,12 @@
 /**
  * revealKinematogram — the canvas rendering behind the HkPasswordSurface
  * reveal strategies: the boiling-noise kinematogram (the "noise"
- * strategy — screenshot-safe in any single frame) and the sweep-window
+ * strategy — screenshot-safe in any single frame), the sweep-window
  * kinematics for the "sweep" strategy (a readable band over the noise;
- * deliberately NOT single-frame safe). Both serve hold and toggle
- * triggers; the "plain" strategy bypasses this module entirely.
+ * deliberately NOT single-frame safe), and the dual counter-drifting
+ * spatter layers of the "filter" strategy (readable in motion, only a
+ * weak luminance signal in any single frame). All serve hold and
+ * toggle triggers; the "plain" strategy bypasses this module entirely.
  *
  * Principle: the whole reveal area is filled with ONE shared noise tile.
  * The glyph mask stays perfectly still while the BACKGROUND noise drifts
@@ -385,3 +387,273 @@ export class RevealNoisePainter {
     }
   }
 }
+
+/** ── Filter strategy: dual counter-drifting spatter layers ──────────
+ *
+ * Design (literature-grounded, chosen over the sweep when screenshot
+ * resistance matters more than instant legibility): the whole reveal
+ * 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.
+ *
+ * Why these parameters (the failure modes of video CAPTCHAs say what
+ * to avoid — NuCAPTCHA & animated-GIF schemes died to per-frame OCR +
+ * cross-frame registration; the kinematogram above replaced an earlier
+ * counter-DRIFT variant of this module that was illegible at field
+ * font sizes):
+ * - Spatter dots ~0.6–1.4× the stroke width, not 1px grain: masking
+ *   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).
+ * - 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).
+ * - The glyph APERTURES never move — only the texture inside them
+ *   flows. Cross-frame registration of the glyph shapes (the attack
+ *   that killed video CAPTCHAs) finds nothing to align.
+ * - The pedestal is deliberately SMALL: it is a static first-order cue
+ *   and therefore the one signal a single frame leaks. Kept at
+ *   FILTER_PEDESTAL_L lightness points and spread by the halo ramp, it
+ *   aids human pop-out without giving thresholding a plateau. An
+ *   attacker averaging MANY frames can in principle recover the
+ *   pedestal's DC component (same cost class as the video attack on
+ *   the noise strategy) — accepted risk, documented; consumers that
+ *   cannot accept it pick "noise" (zero static signal) or "plain"
+ *   (full readability).
+ * - The drift sign is re-randomized per hold (and both tiles are
+ *   freshly generated per hold) so two holds never replay the same
+ *   frame sequence.
+ *
+ * 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). */
+
+/** 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. */
+export const FILTER_PEDESTAL_L = 10;
+
+/** Peak alpha of the halo band (white, at the glyph-row midline). */
+export const FILTER_HALO_ALPHA = 0.1;
+
+/** Halo half-height as a multiple of the glyph font size (device px):
+ * the ramp spans ±this × fontPx around the row midline, so the
+ * pedestal step dissolves into a gradient ~1–2 letter heights wide. */
+export const FILTER_HALO_FONT_SCALE = 1.2;
+
+/** Spatter dot radius band in CSS px (scaled by dpr into the device-px
+ * tile): ≈0.6–1.4× the stroke width of the 13–22px reveal band, the
+ * spatial scale where masking is most efficient per unit contrast. */
+const FILTER_SPATTER_R_MIN_CSS = 1.2;
+const FILTER_SPATTER_R_MAX_CSS = 2.8;
+
+/** Spatter coverage: one dot per this many tile px². BOTH layers share
+ * the density, size and lightness distributions — matched texture
+ * statistics are the single-frame defense; only the mean luminance
+ * (pedestal) and the drift direction differ. */
+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;
+
+export class RevealFilterPainter {
+  private bgTile: HTMLCanvasElement | null = null;
+  private inkTile: HTMLCanvasElement | null = null;
+  private mask: HTMLCanvasElement | null = null;
+  private maskKey = "";
+  private offsetBackground = 0;
+  private offsetInk = 0;
+  private driftSign = 1;
+  private dpr = 1;
+  private ok = true;
+
+  /** False once canvas 2D is unusable: the caller degrades to the
+   * static plain text (filter exists for readability). */
+  get available(): boolean {
+    return this.ok;
+  }
+
+  /** Accumulated pre-wrap drift of both layers in device px (test
+   * window: the two must move in OPPOSITE directions at equal speed). */
+  peekDrift(): { background: number; ink: number } {
+    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
+   * pixel-identical and automation cannot precompute the motion. */
+  beginHold(base: Hsl, dpr = 1): void {
+    this.dpr = dpr;
+    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");
+  }
+
+  advance(dt: number, dpr: number): void {
+    const step = FILTER_DRIFT_PX_S * dpr * dt;
+    this.offsetBackground += this.driftSign * step;
+    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.
+   * 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 {
+    try {
+      if (typeof document === "undefined") return false;
+      if (which === "bg") {
+        this.bgTile ??= document.createElement("canvas");
+      } else {
+        this.inkTile ??= document.createElement("canvas");
+      }
+      const tile = (which === "bg" ? this.bgTile : this.inkTile)!;
+      tile.width = NOISE_TILE_W;
+      tile.height = NOISE_TILE_H;
+      const tctx = tile.getContext("2d");
+      if (!tctx) return false;
+      const [h, s, l] = base;
+      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));
+      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);
+        tctx.fillStyle = `rgb(${r},${g},${b})`;
+        const rad = rMin + Math.random() * (rMax - rMin);
+        tctx.beginPath();
+        tctx.arc(Math.random() * NOISE_TILE_W, Math.random() * NOISE_TILE_H, rad, 0, Math.PI * 2);
+        tctx.fill();
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Composite one frame: background spatter translated by its
+   * accumulated drift, the halo ramp centered on the glyph row, then
+   * the glyph mask — rebuilt only when `maskKey` changes — re-filled
+   * with the ink spatter at ITS accumulated counter-drift and stamped
+   * on top. Returns false (latching ONLY on a thrown error, like the
+   * noise painter) when the pattern/gradient path is unavailable.
+   */
+  paint(
+    ctx: CanvasRenderingContext2D,
+    W: number,
+    H: number,
+    layout: RevealLayout,
+    monoFont: string,
+    maskKey: string,
+  ): boolean {
+    if (!this.bgTile || !this.inkTile || !this.ok) return false;
+    try {
+      if (typeof document === "undefined") return false;
+      // Capability pre-check BEFORE anything is drawn: a partial frame
+      // (spatter without halo or text) must never flash on screen.
+      if (
+        typeof ctx.createPattern !== "function" ||
+        typeof ctx.createLinearGradient !== "function"
+      ) {
+        return false;
+      }
+      // 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).
+      const bandH = Math.min(H / 2, FILTER_HALO_FONT_SCALE * layout.fontPx);
+      const midY = H / 2;
+      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)");
+      this.mask ??= document.createElement("canvas");
+      if (this.mask.width !== W || this.mask.height !== H) {
+        this.mask.width = W;
+        this.mask.height = H;
+        this.maskKey = "";
+      }
+      const mctx = this.mask.getContext("2d");
+      if (!mctx) return false;
+
+      if (this.maskKey !== maskKey) {
+        mctx.globalCompositeOperation = "source-over";
+        mctx.clearRect(0, 0, W, H);
+        mctx.fillStyle = "#fff";
+        mctx.textAlign = "left";
+        mctx.textBaseline = "middle";
+        mctx.font = `${layout.fontPx.toFixed(2)}px ${monoFont}`;
+        for (const g of layout.glyphs) {
+          mctx.fillText(g.ch, g.x, H / 2);
+        }
+        this.maskKey = maskKey;
+      }
+
+      const patInk = mctx.createPattern(this.inkTile, "repeat");
+      if (!patInk) return false;
+      mctx.save();
+      mctx.globalCompositeOperation = "source-in";
+      mctx.imageSmoothingEnabled = false;
+      const oi = Math.round(wrapDrift(this.offsetInk, NOISE_TILE_W));
+      mctx.translate(-oi, 0);
+      mctx.fillStyle = patInk;
+      mctx.fillRect(oi, 0, W + 2, H);
+      mctx.restore();
+
+      const patBg = ctx.createPattern(this.bgTile, "repeat");
+      if (!patBg) return false;
+      ctx.save();
+      ctx.imageSmoothingEnabled = false;
+      const ob = Math.round(wrapDrift(this.offsetBackground, NOISE_TILE_W));
+      ctx.translate(-ob, 0);
+      ctx.fillStyle = patBg;
+      ctx.fillRect(ob, 0, W + 2, H);
+      ctx.restore();
+
+      // Halo: a smooth vertical ramp centered on the glyph row — the
+      // surround of the text sits slightly brighter, aiding pop-out
+      // while dissolving the pedestal step into a gradient with no
+      // plateau for thresholding to lock onto (gradient created up
+      // front, before any visible drawing).
+      ctx.save();
+      ctx.fillStyle = grad;
+      ctx.fillRect(0, midY - bandH, W, bandH * 2);
+      ctx.restore();
+
+      ctx.drawImage(this.mask, 0, 0);
+      return true;
+    } catch {
+      this.ok = false;
+      return false;
+    }
+  }
+}