@celestia-island/hikari 0.55.22 → 0.55.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.22",
+  "version": "0.55.23",
   "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

@@ -3,7 +3,7 @@ import { Comment, createApp, createVNode, h, nextTick, ref, type Slot } from "vu
 
 import HkInput from "./HkInput";
 import HkPasswordSurface from "./HkPasswordSurface";
-import { NOISE_TILE_H, NOISE_TILE_W } from "./revealKinematogram";
+import { FILTER_PEDESTAL_L, NOISE_TILE_H, NOISE_TILE_W } from "./revealKinematogram";
 import { passwordLevel } from "../utils/password";
 import { setReducedMotion } from "../runtime/animationBus";
 
@@ -1339,6 +1339,8 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
     gradientStops: string[];
     /** Font string assignments — pins the BOLD glyph aperture. */
     fonts: string[];
+    /** arc() radii, in call order — pins the spatter dot SIZE band. */
+    arcRadii: number[];
     fillStyles: string[];
     clips: Array<{ x: number; y: number; w: number; h: number }>;
     translates: number[];
@@ -1361,6 +1363,7 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
         compositeOps: [],
         gradientStops: [],
         fonts: [],
+        arcRadii: [],
         fillStyles: [],
         clips: [],
         translates: [],
@@ -1380,7 +1383,7 @@ function stubRecordingContexts(opts: { linearGradients?: boolean } = {}) {
       translate: (x: number) => r.translates.push(x),
       rotate: () => {},
       beginPath: () => {},
-      arc: () => {},
+      arc: (_x: number, _y: number, radius: number) => r.arcRadii.push(radius),
       fill: () => {},
       fillRect: () => {
         if (gradientArmed) {
@@ -1582,10 +1585,10 @@ describe("HkInput password reveal strategies", () => {
 
   it("filter (default) keeps glyphs off the visible canvas: counter-drifting spatter, pedestal, halo", async () => {
     // The default reveal: STATIC BOLD glyph apertures filled with one
-    // GRAYSCALE spatter texture, over a statistically matched spatter
-    // field streaming the opposite way on the uniform near-black
-    // ground; the glyphs lifted by a small brightening pedestal with a
-    // white halo band around the row. Glyph
+    // BRIGHT GRAYSCALE spatter texture, over a statistically matched
+    // DIM spatter field drifting the opposite way on the uniform
+    // near-black ground; the glyphs lifted by a LARGE brightening
+    // pedestal with a white 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
@@ -1624,7 +1627,7 @@ describe("HkInput password reveal strategies", () => {
       // The two spatter tiles: bg first, ink second (deterministic
       // draw order), each with hundreds of solid-color dot fills. The
       // anchors are UNIFORM (white-on-black reading in every theme):
-      // near-black ground, light-gray speckle, and the pedestal lifts
+      // near-black ground, dim-gray speckle, and the pedestal lifts
       // the glyph layer BRIGHTER. happy-dom resolves no computed
       // color, so the ink stays at the pre-sync fallback (a DARK ink)
       // — irrelevant now, the anchors follow nothing.
@@ -1661,6 +1664,13 @@ describe("HkInput password reveal strategies", () => {
         inkMean - bgMean,
         `glyph pedestal lifts BRIGHTER (bg ${bgMean.toFixed(1)} vs ink ${inkMean.toFixed(1)})`,
       ).toBeGreaterThan(8);
+      // Magnitude pin (R1 F4): the pedestal is LARGE by design (26 L ≈
+      // 66 rgb here) — a revert to the old small 10 L pedestal (~26
+      // rgb) must go red, not just stay above the sign threshold.
+      expect(
+        inkMean - bgMean,
+        "the bright-text pedestal is LARGE, not merely positive",
+      ).toBeGreaterThan(36);
       // 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) {
@@ -1689,6 +1699,21 @@ describe("HkInput password reveal strategies", () => {
         mask!.fonts.some((f) => f.startsWith("bold ")),
         "glyph apertures rasterize bold",
       ).toBe(true);
+      // Dot size band (R1 F6): ~0.6–1.4× the stroke width — dpr is 1
+      // in this environment (guarded below), so every spatter radius
+      // sits in the CSS band [1.2, 2.8]. NOTE: with random pinned at
+      // 0.5 every radius is the band MIDPOINT — the min-side teeth
+      // live in the light-ink test's unmocked band check (R2 F1).
+      expect(window.devicePixelRatio || 1).toBe(1);
+      for (const tile of tiles) {
+        expect(tile.arcRadii.length, "spatter dots drawn as arcs").toBeGreaterThan(1000);
+        for (const rad of tile.arcRadii) {
+          expect(
+            rad >= 1.2 && rad <= 2.8,
+            `dot radius inside the stroke band, got ${rad}`,
+          ).toBe(true);
+        }
+      }
       // The DOM input still never flips.
       expect(input.type).toBe("password");
       // Bus frames advance BOTH layer drifts (fresh pattern phases on
@@ -1750,7 +1775,7 @@ describe("HkInput password reveal strategies", () => {
   it("filter anchors white-on-black regardless of the field ink (light ink)", async () => {
     // UNIFORMITY pin: the anchors follow NOTHING — feed a LIGHT field
     // ink through getComputedStyle and the reveal must still paint the
-    // same near-black ground, light-gray speckle, brighter pedestal
+    // same near-black ground, dim-gray speckle, brighter pedestal
     // and white halo as the default (dark-ink) mount.
     const restoreInk = forceInkColor("rgb(148, 233, 211)");
     const rec = stubRecordingContexts();
@@ -1790,6 +1815,33 @@ describe("HkInput password reveal strategies", () => {
           expect(r8 === g8 && g8 === b8, `dark spatter must be grayscale, got ${fill}`).toBe(true);
         }
       }
+      // Dot size band with REAL randomness (R2 F1): the default test's
+      // pinned 0.5 random freezes every radius at the band MIDPOINT,
+      // which is blind on the min side — here thousands of uniform
+      // samples must ALL sit in [1.2, 2.8] AND the empirical extremes
+      // must touch both edges, so a shrunken rMin (sub-pixel speckle)
+      // or a blown rMax both go red. dpr is 1 in this environment —
+      // the guard makes that assumption explicit (R2 F2).
+      expect(window.devicePixelRatio || 1).toBe(1);
+      {
+        let min = Infinity;
+        let max = -Infinity;
+        let count = 0;
+        for (const tile of tiles) {
+          for (const rad of tile.arcRadii) {
+            if (rad < min) min = rad;
+            if (rad > max) max = rad;
+            count++;
+            expect(
+              rad >= 1.2 && rad <= 2.8,
+              `dot radius inside the stroke band, got ${rad}`,
+            ).toBe(true);
+          }
+        }
+        expect(count, "thousands of spatter dots sampled").toBeGreaterThan(3000);
+        expect(min, "the small edge of the band is actually used").toBeLessThan(1.5);
+        expect(max, "the large edge of the band is actually used").toBeGreaterThan(2.5);
+      }
       // 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
@@ -1812,14 +1864,16 @@ describe("HkInput password reveal strategies", () => {
         `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
+      // sit exactly one pedestal apart (26 L ≈ 66 rgb at the current
+      // tuning; the threshold derives from the constant), 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]!));
+      const pedRgb = FILTER_PEDESTAL_L * 2.55;
       expect(
-        groundDelta >= 20 && groundDelta <= 30,
-        `grounds one pedestal apart (delta ${groundDelta})`,
+        groundDelta >= pedRgb - 6 && groundDelta <= pedRgb + 6,
+        `grounds one pedestal apart (delta ${groundDelta}, want ~${pedRgb.toFixed(0)})`,
       ).toBe(true);
       // Near-black ground regardless of the ink: L 10 → rgb ≈ 26.
       const [gr, gg, gb] = tiles[0]!.fillStyles[0]!.slice(4, -1).split(",").map(Number);
@@ -1931,7 +1985,9 @@ describe("HkInput password reveal strategies", () => {
       );
       expect(tiles.length).toBe(2);
       const counts1 = tiles.map((r) => r.fillStyles.length);
-      expect(counts1[0]!, "ground + dots on hold 1").toBeGreaterThan(1000);
+      // Dense field (R1 F5): ~2341 dots per tile at 28 px²/dot — the
+      // old sparse 45 px²/dot (1457 fills) must fail this floor.
+      expect(counts1[0]!, "dense spatter field on hold 1").toBeGreaterThan(2000);
       await hold();
       const counts2 = tiles.map((r) => r.fillStyles.length);
       expect(counts2[0]).toBe(counts1[0]! * 2);

package/src/components/HkInput.tsx

@@ -77,14 +77,13 @@ export default defineComponent({
     /**
      * Reveal content for the password eye (`variant="password"`,
      * `passwordTrailing="eye"`):
-     * - "filter" (default): dual FAST counter-drifting spatter layers
-     *   in strict black/white/gray — static BOLD glyph apertures
-     *   filled with one gray spatter texture over a statistically
-     *   matched field streaming the opposite way on a UNIFORM
-     *   near-black ground (white-on-black in every theme), plus a
-     *   small brightening pedestal and a white halo; the speed lets
-     *   persistence of vision average the glyphs readable. A
-     *   single-frame screenshot carries no glyph structure.
+     * - "filter" (default): dual counter-drifting spatter layers in
+     *   strict black/white/gray — static BOLD glyph apertures filled
+     *   with a BRIGHT dense gray spatter over a statistically matched
+     *   DIM field drifting the opposite way on a UNIFORM near-black
+     *   ground (white-on-black in every theme), plus a large
+     *   brightening pedestal and a white halo. A single-frame
+     *   screenshot carries no glyph structure.
      * - "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/HkNodeCanvas.gestures.test.tsx

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkNodeCanvas from "./HkNodeCanvas";
+
+/** Mount a component into a detached div and return the root element. */
+function mountToDom(component: ReturnType<typeof defineComponent>): HTMLElement {
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  const app = createApp(component);
+  app.mount(el);
+  return el;
+}
+
+function pointerEvent(type: string, opts: Record<string, number | boolean> = {}): PointerEvent {
+  return new PointerEvent(type, {
+    pointerId: (opts.pointerId as number) ?? 1,
+    clientX: (opts.clientX as number) ?? 0,
+    clientY: (opts.clientY as number) ?? 0,
+    button: (opts.button as number) ?? 0,
+    bubbles: true,
+    cancelable: true,
+    ...opts,
+  });
+}
+
+describe("HkNodeCanvas gesture & animation upgrades", () => {
+  describe("tweenCamera", () => {
+    it("exposes tweenCamera as a function", () => {
+      const exposed: Record<string, unknown> = {};
+      const Host = defineComponent({
+        setup() {
+          const canvasRef = ref<unknown>(null);
+          const check = () => {
+            const vm = canvasRef.value as Record<string, unknown> | null;
+            if (vm) Object.assign(exposed, { tweenCamera: vm.tweenCamera });
+          };
+          return () =>
+            h(HkNodeCanvas, { ref: canvasRef, minimap: false, onVnodeMounted: check }, { default: () => h("div") });
+        },
+      });
+      const el = mountToDom(Host);
+      expect(typeof exposed.tweenCamera).toBe("function");
+      el.remove();
+    });
+
+    it("tweenMs=0 (default) does not start an animation frame", () => {
+      let tweenFn: ((...a: unknown[]) => void) | null = null;
+      const Host = defineComponent({
+        setup() {
+          const canvasRef = ref<unknown>(null);
+          const check = () => {
+            const vm = canvasRef.value as Record<string, unknown> | null;
+            if (vm) tweenFn = vm.tweenCamera as (...a: unknown[]) => void;
+          };
+          return () =>
+            h(HkNodeCanvas, {
+              ref: canvasRef,
+              minimap: false,
+              fitOnLoad: false,
+              onVnodeMounted: check,
+            }, { default: () => h("div") });
+        },
+      });
+      const el = mountToDom(Host);
+      expect(tweenFn).toBeTruthy();
+      // Calling with default tweenMs=0 should snap (no rAF started).
+      tweenFn!({ k: 2, x: 100, y: 50 });
+      el.remove();
+    });
+  });
+
+  describe("pinchable prop", () => {
+    it("defaults to true", () => {
+      const el = mountToDom(defineComponent({
+        setup() {
+          return () => h(HkNodeCanvas, { minimap: false }, { default: () => h("div") });
+        },
+      }));
+      expect(el.querySelector(".hk-node-canvas")).toBeTruthy();
+      el.remove();
+    });
+
+    it("can be disabled", () => {
+      const el = mountToDom(defineComponent({
+        setup() {
+          return () => h(HkNodeCanvas, { minimap: false, pinchable: false }, { default: () => h("div") });
+        },
+      }));
+      expect(el.querySelector(".hk-node-canvas")).toBeTruthy();
+      el.remove();
+    });
+  });
+
+  describe("reduced motion", () => {
+    it("respectReducedMotion defaults to true", () => {
+      const el = mountToDom(defineComponent({
+        setup() {
+          return () => h(HkNodeCanvas, { minimap: false }, { default: () => h("div") });
+        },
+      }));
+      expect(el.querySelector(".hk-node-canvas")).toBeTruthy();
+      el.remove();
+    });
+  });
+
+  describe("pointerScale prop", () => {
+    it("accepts a pointerScale function", () => {
+      const el = mountToDom(defineComponent({
+        setup() {
+          return () =>
+            h(HkNodeCanvas, {
+              minimap: false,
+              pointerScale: () => ({ x: 2, y: 2 }),
+            }, { default: () => h("div") });
+        },
+      }));
+      expect(el.querySelector(".hk-node-canvas")).toBeTruthy();
+      el.remove();
+    });
+  });
+
+  describe("pinch gesture (integration)", () => {
+    it("two simultaneous pointers do not crash", async () => {
+      const Host = defineComponent({
+        setup() {
+          return () =>
+            h(HkNodeCanvas, {
+              minimap: false,
+              pannable: true,
+              pinchable: true,
+            }, { default: () => h("div") });
+        },
+      });
+      const el = mountToDom(Host);
+      const root = el.querySelector(".hk-node-canvas")!;
+      expect(root).toBeTruthy();
+
+      // Simulate two fingers down.
+      root.dispatchEvent(pointerEvent("pointerdown", { pointerId: 10, clientX: 100, clientY: 100 }));
+      root.dispatchEvent(pointerEvent("pointerdown", { pointerId: 20, clientX: 200, clientY: 100 }));
+      await nextTick();
+
+      // Simulate one finger moving (pinch in progress).
+      root.dispatchEvent(pointerEvent("pointermove", { pointerId: 20, clientX: 150, clientY: 100 }));
+      await nextTick();
+
+      // Release both fingers.
+      root.dispatchEvent(pointerEvent("pointerup", { pointerId: 10 }));
+      root.dispatchEvent(pointerEvent("pointerup", { pointerId: 20 }));
+      await nextTick();
+
+      // No crash — the component is still mounted.
+      expect(el.querySelector(".hk-node-canvas")).toBeTruthy();
+      el.remove();
+    });
+  });
+});

package/src/components/HkNodeCanvas.tsx

@@ -219,6 +219,26 @@ export default defineComponent({
       type: String as PropType<PrintPaper>,
       default: "auto" as PrintPaper,
     },
+
+    // ── Gesture & animation upgrades ─────────────────────────────
+
+    /** Camera tween duration in ms (0 disables tweening). Only
+     *  `tweenCamera()` animates over this duration with ease-out cubic.
+     *  Snaps instantly when prefers-reduced-motion is active and
+     *  `respectReducedMotion` is on (default). */
+    tweenMs: { type: Number, default: 0 },
+    /** Two-finger pinch-to-zoom on touch devices. */
+    pinchable: { type: Boolean, default: true },
+    /** Snap tweens when prefers-reduced-motion is active (default). */
+    respectReducedMotion: { type: Boolean, default: true },
+    /** DPI scale provider: maps pointer coordinates to drawn coordinates.
+     *  Needed when the canvas is inside a CSS `zoom` or `transform: scale()`
+     *  container — pointer events report unscaled page coordinates but the
+     *  camera measures the canvas's own pixels. */
+    pointerScale: {
+      type: Function as PropType<(() => { x: number; y: number }) | undefined>,
+      default: undefined,
+    },
   },
   emits: ["update:camera"],
   setup(props, { slots, emit, expose }) {
@@ -237,6 +257,27 @@ export default defineComponent({
     /** Set by setCamera (gestures and imperative calls) — never by `fit`. */
     let movedByHand = false;
 
+    // ── Pinch-to-zoom state ──────────────────────────────────────
+    /** Active pointers for pinch tracking (pointerId → screen position). */
+    const activePointers = new Map<number, { x: number; y: number }>();
+    /** Pinch gesture snapshot: start distance/zoom/midpoint for the ratio. */
+    let pinchSnapshot: {
+      startDist: number;
+      startZoom: number;
+      midX: number;
+      midY: number;
+    } | null = null;
+
+    // ── Camera tween state ───────────────────────────────────────
+    let tweenRaf: number | null = null;
+
+    // ── Motion constraints ───────────────────────────────────────
+    const reducedMotion = computed(() => {
+      if (!props.respectReducedMotion) return false;
+      return typeof window !== "undefined"
+        && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    });
+
     // ── Canvas2D painter layer ───────────────────────────────────
     const canvasEl = shallowRef<HTMLCanvasElement | null>(null);
     /** Registered painters, sorted by z on each frame. */
@@ -495,6 +536,11 @@ export default defineComponent({
     }
 
     function onPointerDown(event: PointerEvent) {
+      // When a pinch is live, cancel any single-pointer pan.
+      if (pinchSnapshot !== null) {
+        panning = null;
+        return;
+      }
       if (!props.pannable || event.button !== 0) return;
       // A host that drags its own nodes suppresses the pan by preventing the
       // default on its card's pointerdown: the root listens in the bubble
@@ -517,6 +563,7 @@ export default defineComponent({
       ) {
         return;
       }
+      trackPointer(event);
       panning = {
         pointerId: event.pointerId,
         x: event.clientX,
@@ -535,6 +582,14 @@ export default defineComponent({
     }
 
     function onPointerMove(event: PointerEvent) {
+      // Update pinch tracking when a tracked pointer moves.
+      if (activePointers.has(event.pointerId)) {
+        activePointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+        if (pinchSnapshot !== null) {
+          updatePinch();
+          return;
+        }
+      }
       if (!panning || event.pointerId !== panning.pointerId) return;
       // The gesture is only captured once it passes the slop, so a release that
       // happens outside the canvas never reaches this element. Without this the
@@ -567,6 +622,8 @@ export default defineComponent({
     }
 
     function endPan(event: PointerEvent) {
+      endPointerTracking(event);
+      if (pinchSnapshot !== null) return;
       if (!panning || event.pointerId !== panning.pointerId) return;
       const pointerId = panning.pointerId;
       panning = null;
@@ -580,6 +637,11 @@ export default defineComponent({
       // canvas clears focus), and ending the gesture there would kill the first
       // pan after any click. Only the window's own blur ends it.
       if (event.target && event.target !== window) return;
+      // Clear pinch state too: a blur during a two-finger gesture would
+      // otherwise leave a stale snapshot that permanently suppresses pan
+      // (every pointerdown would hit the pinch-active early return).
+      activePointers.clear();
+      pinchSnapshot = null;
       if (!panning) return;
       const pointerId = panning.pointerId;
       panning = null;
@@ -668,6 +730,7 @@ export default defineComponent({
     );
 
     onBeforeUnmount(() => {
+      cancelTween();
       stopFrameLoop();
       ro?.disconnect();
       ro = null;
@@ -820,6 +883,97 @@ export default defineComponent({
       return copy;
     }
 
+    // ── Pinch-to-zoom ────────────────────────────────────────────
+
+    /** Track active pointers for pinch detection. */
+    function trackPointer(event: PointerEvent): void {
+      activePointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+      if (
+        props.pinchable
+        && !props.printMode
+        && activePointers.size === 2
+        && pinchSnapshot === null
+      ) {
+        const [a, b] = [...activePointers.values()];
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        pinchSnapshot = {
+          startDist: Math.hypot(dx, dy),
+          startZoom: camera.value.k,
+          midX: (a.x + b.x) / 2,
+          midY: (a.y + b.y) / 2,
+        };
+      }
+    }
+
+    /** Update pinch zoom from current pointer positions. */
+    function updatePinch(): void {
+      if (!pinchSnapshot || activePointers.size < 2) return;
+      const [a, b] = [...activePointers.values()];
+      const dist = Math.hypot(b.x - a.x, b.y - a.y);
+      if (pinchSnapshot.startDist < 1) return;
+      const ratio = dist / pinchSnapshot.startDist;
+      const targetK = normalizeZoom(pinchSnapshot.startZoom * ratio);
+      // Zoom anchored at the pinch midpoint.
+      const rect = rootEl.value?.getBoundingClientRect();
+      if (!rect) return;
+      const scale = props.pointerScale?.() ?? { x: 1, y: 1 };
+      const midX = ((pinchSnapshot.midX - rect.left) / scale.x);
+      const midY = ((pinchSnapshot.midY - rect.top) / scale.y);
+      const cam = camera.value;
+      const k = targetK;
+      const x = midX - ((midX - cam.x) * k) / cam.k;
+      const y = midY - ((midY - cam.y) * k) / cam.k;
+      setCamera({ k, x, y });
+    }
+
+    /** End pinch tracking when a pointer lifts. */
+    function endPointerTracking(event: PointerEvent): void {
+      activePointers.delete(event.pointerId);
+      if (activePointers.size < 2) {
+        pinchSnapshot = null;
+      }
+    }
+
+    // ── Camera tween ─────────────────────────────────────────────
+
+    /** Cancel any running tween. */
+    function cancelTween(): void {
+      if (tweenRaf !== null) {
+        cancelAnimationFrame(tweenRaf);
+        tweenRaf = null;
+      }
+    }
+
+    /** Animate the camera to a target over `tweenMs`, or snap if
+     *  reduced-motion is active or tweenMs is 0. */
+    function tweenCamera(target: NodeCanvasCamera, durationMs?: number): void {
+      cancelTween();
+      const ms = durationMs ?? props.tweenMs;
+      if (ms <= 0 || reducedMotion.value) {
+        setCamera(target);
+        return;
+      }
+      const start = { ...camera.value };
+      const startTime = performance.now();
+
+      const step = (now: number) => {
+        const t = Math.min((now - startTime) / ms, 1);
+        const eased = 1 - Math.pow(1 - t, 3); // ease-out cubic
+        setCamera({
+          k: start.k + (target.k - start.k) * eased,
+          x: start.x + (target.x - start.x) * eased,
+          y: start.y + (target.y - start.y) * eased,
+        });
+        if (t < 1) {
+          tweenRaf = requestAnimationFrame(step);
+        } else {
+          tweenRaf = null;
+        }
+      };
+      tweenRaf = requestAnimationFrame(step);
+    }
+
     expose({
       camera,
       viewport,
@@ -829,6 +983,7 @@ export default defineComponent({
       screenToWorld,
       worldToScreen,
       setCamera,
+      tweenCamera,
       // ── New: rendering base capabilities ──
       levelOfDetail,
       registerPainter,

package/src/components/HkPasswordSurface.tsx

@@ -53,17 +53,17 @@ 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 "filter" (default): dual FAST counter-drifting spatter
+ *   - strategy "filter" (default): dual counter-drifting spatter
  *     layers in strict BLACK/WHITE/GRAY — the glyph row is a set of
- *     STATIC bold apertures filled with a gray spatter texture
- *     streaming one way, over a statistically identical spatter field
- *     streaming the other way, both on a UNIFORM near-black ground
- *     (white-on-black reading in every theme). The drift is very fast
- *     so persistence of vision averages the aperture interiors into
- *     readable near-solid glyphs. A 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.
+ *     STATIC bold apertures filled with a bright gray spatter texture
+ *     drifting one way, over a statistically matched DIM spatter
+ *     field drifting the other way, both on a UNIFORM near-black
+ *     ground (white-on-black reading in every theme; legibility lives
+ *     in the brightness channel — dense dots, dim surround, bright
+ *     text layer). A single frame — a screenshot — carries no glyph
+ *     structure, only the 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
@@ -120,13 +120,13 @@ export default defineComponent({
     },
     /**
      * What the eye reveal SHOWS:
-     * - "filter" (default): dual FAST counter-drifting spatter layers
-     *   in strict black/white/gray — static BOLD glyph apertures over
-     *   an oppositely streaming, statistically matched gray spatter
-     *   field on a UNIFORM near-black ground (white-on-black in every
-     *   theme), plus a small brightening pedestal and white halo; the
-     *   speed lets persistence of vision average the glyphs readable.
-     *   A single screenshot carries no glyph structure.
+     * - "filter" (default): dual counter-drifting spatter layers in
+     *   strict black/white/gray — static BOLD glyph apertures filled
+     *   with a BRIGHT dense gray spatter over an oppositely drifting,
+     *   statistically matched DIM spatter field on a UNIFORM
+     *   near-black ground (white-on-black in every theme), plus a
+     *   large brightening pedestal and white halo. A single
+     *   screenshot carries no glyph structure.
      * - "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.

package/src/components/revealKinematogram.test.ts

@@ -135,15 +135,14 @@ describe("RevealNoisePainter", () => {
   });
 });
 
-describe("FILTER_DRIFT_PX_S persistence floor", () => {
-  it("keeps the counter-drift fast enough for persistence reading", () => {
-    // The readability mechanism RELIES on speed: within one
-    // persistence-of-vision window (~100ms) the texture must keep
-    // crossing dot spacings (the mean spacing is ~7px — ~2 crossings
-    // at the 150 floor, several at the shipped 300) so the static
-    // aperture interiors time-average into near-solid glyphs (R1 F7,
-    // R3 wording note).
-    expect(FILTER_DRIFT_PX_S).toBeGreaterThanOrEqual(150);
+describe("FILTER_DRIFT_PX_S settled band", () => {
+  it("keeps the drift in the live-tuned moderate band", () => {
+    // 84 px/s is the live-tuned settled value: the 300px/s
+    // persistence experiment read WORSE live (no stable surface for
+    // the eye to bind) and was reverted — a silent re-raise must go
+    // red. The band allows small tuning without test edits (R1 F2).
+    expect(FILTER_DRIFT_PX_S).toBeGreaterThanOrEqual(60);
+    expect(FILTER_DRIFT_PX_S).toBeLessThanOrEqual(120);
   });
 });
 
@@ -192,17 +191,24 @@ describe("RevealFilterPainter", () => {
   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.
+    // red here. TWO probe combos whose real steps differ (42 and 21)
+    // so no single hardcoded step constant passes both (R1 F3: the
+    // old 0.25/2-only probe was blind to `const step = 42`).
     const p = new RevealFilterPainter();
     const rand = vi.spyOn(Math, "random").mockReturnValue(0.25); // driftSign = +1
     try {
       p.beginHold();
-      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);
+      for (const [dt, dpr] of [
+        [0.25, 2],
+        [0.125, 2],
+      ] as const) {
+        const before = p.peekDrift();
+        p.advance(dt, dpr);
+        const after = p.peekDrift();
+        const step = FILTER_DRIFT_PX_S * dpr * dt;
+        expect(after.background - before.background).toBeCloseTo(step, 10);
+        expect(after.ink - before.ink).toBeCloseTo(-step, 10);
+      }
     } finally {
       rand.mockRestore();
     }

package/src/components/revealKinematogram.ts

@@ -396,21 +396,22 @@ export class RevealNoisePainter {
  * 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 shifted by
- * a small brightening lightness pedestal (white-on-black reading),
+ * a large brightening lightness pedestal (live-tuned, white-on-black
+ * reading),
  * 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 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 and strictly UNIFORM — black,
  * white and grays only, no theme hue survives into the spatter (the
  * ink-colored variant read as an uncomfortable cyan), and the anchors
- * do NOT follow the theme: ALWAYS a near-black ground with light gray
- * speckle, a white halo and a brighter glyph pedestal (the theme-
+ * do NOT follow the theme: ALWAYS a near-black ground with dim gray
+ * speckle, a white halo and a much-brighter glyph pedestal (the theme-
  * following light variant read far worse and was dropped — a dark
  * reveal strip inside a light page is the accepted look).
  *
@@ -423,30 +424,37 @@ 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).
+ * - Legibility lives in the BRIGHTNESS channel (live-tuned): the
+ *   surround dots sit LOW (FILTER_BASE_L) on the near-black ground so
+ *   the background reads dim, the glyph layer is lifted by a LARGE
+ *   pedestal (FILTER_PEDESTAL_L) so the text reads bright, and the
+ *   dots are DENSE (FILTER_SPATTER_PX_PER_DOT) so both fields read as
+ *   textured surfaces rather than sparse speckle. The large pedestal
+ *   is a bigger single-frame leak than the original small one — an
+ *   accepted trade per the readability-first direction.
  * - 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, deliberately VERY fast: within one
- *   persistence-of-vision window (~100ms) the texture travels ~30px —
- *   several dot spacings (the mean spacing is ~7px) — so the aperture
- *   interior time-averages into a clean pedestal + spatter mean and
- *   the glyphs read near-solid, while the counter-motion segregation
- *   only sharpens. A single frame still carries no motion energy at
- *   all (form-from-motion needs the temporal integration that only
- *   the live eye provides).
+ * - Drift ±FILTER_DRIFT_PX_S: moderate — slow enough to track
+ *   coherently at field font sizes, fast enough that a single frame
+ *   carries no usable motion energy. (A 300px/s persistence-of-vision
+ *   experiment read worse live: the eye never got a stable surface to
+ *   bind, so the speed came back down and legibility moved into the
+ *   brightness channel instead.)
  * - 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 pedestal is deliberately LARGE (live-tuned readability
+ *   first): it is a static first-order cue and therefore the one
+ *   signal a single frame leaks, and the current magnitude leaks MORE
+ *   of it than the original small one — the accepted trade for a dim
+ *   surround and a bright text layer. The halo ramp still spreads the
+ *   step so thresholding finds no plateau, and 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) —
+ *   consumers that cannot accept this trade 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.
@@ -462,14 +470,18 @@ export class RevealNoisePainter {
  * never to frozen noise). */
 
 /** Counter-drift speed of each layer in CSS px/s (opposite signs).
- * Deliberately very fast — see the persistence rationale above. */
-export const FILTER_DRIFT_PX_S = 300;
+ * The 300px/s persistence experiment read WORSE live (the eye never
+ * got a stable surface to bind); 84 tracks coherently at field sizes
+ * and is the settled value. */
+export const FILTER_DRIFT_PX_S = 84;
 
 /** Lightness pedestal of the glyph layer (brighter — the text reads
  * white-on-black), in HSL lightness points (clamped into
- * [L_MIN, L_MAX] like every sample). Small on purpose — see the
+ * [L_MIN, L_MAX] like every sample). Deliberately LARGE (live-tuned
+ * readability-first): a dim surround and a bright text layer. The
+ * static single-frame leak grows with it — accepted trade, see the
  * strategy docblock. */
-export const FILTER_PEDESTAL_L = 10;
+export const FILTER_PEDESTAL_L = 26;
 
 /** Peak alpha of the halo band (white, at the glyph-row midline). */
 export const FILTER_HALO_ALPHA = 0.1;
@@ -485,19 +497,20 @@ export const FILTER_HALO_FONT_SCALE = 1.2;
 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;
+/** Spatter coverage: one dot per this many tile px² — DENSE
+ * (live-tuned) so both fields read as textured surfaces. 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 = 28;
 
 /** Dot lightness spread around the layer base (both layers share it). */
 const FILTER_SPATTER_L_SPREAD = 22;
 
-/** The one anchor pair: near-black ground, mid-light gray speckle —
- * white-on-black reading in EVERY theme (the light variant read far
- * worse and was dropped). */
-const FILTER_BASE_L = 64;
+/** The one anchor set: near-black ground + DIM gray speckle for the
+ * surround — white-on-black reading in EVERY theme with the brightness
+ * doing the work (the light variant read far worse and was dropped). */
+const FILTER_BASE_L = 48;
 const FILTER_GROUND_L = 10;
 
 /** Glyph aperture weight: bold strokes expose more of the counter-