@celestia-island/hikari 0.55.22 → 0.55.24

package/package.json

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