@celestia-island/hikari 0.40.18 → 0.40.21

package/src/runtime/surfaceMachine.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  SURFACE_EVENTS,
+  SURFACE_PHASES,
+  classPairOf,
+  classesForPair,
+  isMounted,
+  isQuiescent,
+  surfaceTransition,
+  type SurfaceEventType,
+  type SurfacePhase,
+} from "./surfaceMachine";
+
+/** The spec table as data — the single reviewable proof artifact. The
+ *  reducer must agree with it on every cell; this test is the diff. */
+const SPEC: Record<SurfacePhase, Record<SurfaceEventType, SurfacePhase>> = {
+  closed: {
+    OPEN: "openingFrom",
+    CLOSE: "closed",
+    FLIP: "closed",
+    DEADLINE: "closed",
+    TEND: "closed",
+    UNMOUNT: "closed",
+  },
+  openingFrom: {
+    OPEN: "openingFrom",
+    CLOSE: "closingFrom",
+    FLIP: "openingTo",
+    DEADLINE: "open",
+    TEND: "open",
+    UNMOUNT: "closed",
+  },
+  openingTo: {
+    OPEN: "openingTo",
+    CLOSE: "closingFrom",
+    FLIP: "openingTo",
+    DEADLINE: "open",
+    TEND: "open",
+    UNMOUNT: "closed",
+  },
+  open: {
+    OPEN: "open",
+    CLOSE: "closingFrom",
+    FLIP: "open",
+    DEADLINE: "open",
+    TEND: "open",
+    UNMOUNT: "closed",
+  },
+  closingFrom: {
+    OPEN: "openingFrom",
+    CLOSE: "closingFrom",
+    FLIP: "closingTo",
+    DEADLINE: "closed",
+    TEND: "closed",
+    UNMOUNT: "closed",
+  },
+  closingTo: {
+    OPEN: "openingFrom",
+    CLOSE: "closingTo",
+    FLIP: "closingTo",
+    DEADLINE: "closed",
+    TEND: "closed",
+    UNMOUNT: "closed",
+  },
+};
+
+describe("surfaceMachine table", () => {
+  // T1 (totality + conformance): all 36 cells defined and matching the
+  // spec table — the reducer IS the table.
+  it("defines every (phase, event) cell exactly as the spec table", () => {
+    expect(SURFACE_PHASES).toHaveLength(6);
+    expect(SURFACE_EVENTS).toHaveLength(6);
+    for (const phase of SURFACE_PHASES) {
+      for (const event of SURFACE_EVENTS) {
+        const expected = SPEC[phase][event];
+        if (surfaceTransition(phase, event) !== expected) {
+          throw new Error(`table cell (${phase}, ${event}) diverges from the spec table`);
+        }
+      }
+    }
+  });
+
+  // T2/T3 (outputs are pure functions of state): quiescent states carry
+  // no transition classes; only non-closed states mount.
+  it("quiescent phases paint no transition classes", () => {
+    for (const phase of SURFACE_PHASES) {
+      const classes = classesForPair("hk-x", classPairOf(phase));
+      if (isQuiescent(phase)) {
+        expect(classes).toEqual([]);
+      } else {
+        expect(classes.length).toBe(2);
+      }
+      expect(isMounted(phase) === (phase !== "closed")).toBe(true);
+    }
+  });
+
+  // T4 (liveness): one DEADLINE walks any animation phase to a
+  // quiescent phase — the A2 (rAF/transitionend starved) column.
+  it("a single DEADLINE settles every animation phase (starvation column)", () => {
+    for (const phase of SURFACE_PHASES) {
+      const next = surfaceTransition(phase, "DEADLINE");
+      expect(isQuiescent(next), `${phase} + DEADLINE`).toBe(true);
+    }
+  });
+
+  // Idempotence: duplicating any event never moves the machine.
+  it("every event is idempotent in its target state", () => {
+    for (const phase of SURFACE_PHASES) {
+      for (const event of SURFACE_EVENTS) {
+        const once = surfaceTransition(phase, event);
+        expect(surfaceTransition(once, event)).toBe(once);
+      }
+    }
+  });
+});
+
+// ── Property-based exploration ─────────────────────────────────────
+// Deterministic seeded RNG (xorshift32) — no PBT dependency, full
+// reproducibility from the printed seed on failure.
+
+function rng(seed: number): () => number {
+  let s = seed | 0 || 1;
+  return () => {
+    s ^= s << 13; s ^= s >>> 17; s ^= s << 5;
+    return (s >>> 0) / 0x100000000;
+  };
+}
+
+describe("surfaceMachine property-based exploration", () => {
+  const RUNS = 4000;
+  const MAX_EVENTS = 40;
+
+  // Invariants checked after EVERY event of every run:
+  //  I-mounted: mounted(phase) ⟺ phase !== closed
+  //  I-classes: transition classes only on animation phases (implied by
+  //             classPairOf being total/pure — asserted via quiescence)
+  //  I-quiesce: after draining (each request followed by its DEADLINE),
+  //             the machine rests in {closed, open} — bounded settling
+  //             without any FLIP/TEND ever arriving (axiom A2).
+  it("every random event stream settles quiescently under total frame starvation", () => {
+    for (let run = 0; run < RUNS; run++) {
+      const rand = rng(run + 1);
+      let phase: SurfacePhase = "closed";
+      for (let i = 0; i < MAX_EVENTS; i++) {
+        const pool: SurfaceEventType[] =
+          rand() < 0.5
+            ? ["OPEN", "CLOSE", "UNMOUNT"] // starvation diet: no FLIP/TEND
+            : [...SURFACE_EVENTS];
+        const event = pool[Math.floor(rand() * pool.length)]!;
+        phase = surfaceTransition(phase, event);
+        // I-mounted
+        expect(phase === "closed" || isMounted(phase)).toBe(true);
+        // UNMOUNT absorbs: once sent, only OPEN can leave closed.
+        if (event === "UNMOUNT") {
+          expect(phase).toBe("closed");
+        }
+      }
+      // Drain: one DEADLINE settles any animation phase (T4).
+      phase = surfaceTransition(phase, "DEADLINE");
+      expect(isQuiescent(phase), `run ${run} drained to ${phase}`).toBe(true);
+    }
+  });
+
+  // Reversal safety: OPEN/CLOSE may interleave arbitrarily inside the
+  // animation windows; the machine must never enter a phase that paints
+  // resting classes while mounted=false (the "invisible with content"
+  // inversion) or transition classes while quiescent.
+  it("request interleavings never invert the mounted/classes relationship", () => {
+    for (let run = 0; run < 2000; run++) {
+      const rand = rng(10_000 + run);
+      let phase: SurfacePhase = "closed";
+      for (let i = 0; i < 30; i++) {
+        const event: SurfaceEventType =
+          rand() < 0.7 ? (rand() < 0.5 ? "OPEN" : "CLOSE") : "FLIP";
+        phase = surfaceTransition(phase, event);
+        const mounted = isMounted(phase);
+        const paintingTransitionClasses = !isQuiescent(phase);
+        // A mounted surface either rests (no classes) or animates
+        // (classes) — and classes imply mounted.
+        if (paintingTransitionClasses) expect(mounted).toBe(true);
+        if (!mounted) expect(phase).toBe("closed");
+      }
+    }
+  });
+});

package/src/runtime/surfaceMachine.ts

@@ -0,0 +1,229 @@
+// Surface lifecycle state machine — the provable core of every overlay
+// surface (modal scrim+panel, sheet scrim+panel, popover) in hikari.
+//
+// WHY A MACHINE. The pre-machine design drove two independent Vue
+// <Transition> engines off one boolean, with rAF/transitionend as the
+// class-flip clock. Those events can starve (occluded webviews — the
+// 2026-09 field reports), and two engines can diverge through the same
+// event stream (the mobile "panel visible, scrim gone" state, later the
+// full-opacity close flash — the "black rectangle"). The fixes of that
+// era (#407 leave watchdog, #414 enter watchdog) REPAIRED observed bad
+// states; a repair list is never complete.
+//
+// This module inverts the approach: the lifecycle is ONE explicit
+// finite-state machine whose transition table is total by construction,
+// whose outputs are pure functions of the state, and whose only
+// correctness clock is setTimeout (the one primitive field-verified to
+// fire under the starvation conditions that starve rAF). Bad states —
+// divergent layers, stuck transition classes at rest — are UNREPRESENT-
+// ABLE in the state space rather than detected and repaired.
+//
+// AXIOMS (the proof's ground rules):
+//   A1 setTimeout callbacks fire exactly once, within a bounded delay.
+//   A2 rAF and transitionend may NEVER fire. (The machine stays correct
+//      under A2 alone; both are advisory optimizations in the driver.)
+//   A3 Synchronous class/style writes take effect at the next style
+//      recalc. (What the compositor PAINTS is outside the axioms.)
+//
+// STATES — six, including the two-phase animation windows (a `.from`
+// phase holds the from-class pair until a frame flip; a `.to` phase
+// runs the CSS transition to the resting pair):
+//
+//   closed        no DOM, no timers, nothing registered
+//   openingFrom   mounted, enter-from classes, flip pending
+//   openingTo     mounted, enter-to classes, animating
+//   open          mounted, resting classes, morph armed — the only
+//                 state where size measurements are taken
+//   closingFrom   mounted, leave-from classes, flip pending
+//   closingTo     mounted, leave-to classes, animating
+//
+// EVENTS:
+//   OPEN/CLOSE  surface request (user logic, back gesture, closeAll)
+//   FLIP        frame flip (double-rAF or the flip timer — same event)
+//   DEADLINE    phase deadline timer (the correctness clock)
+//   TEND        transitionend (advisory early completion; the driver
+//               does not emit it — the cell exists so the table stays
+//               total for future adopters)
+//   UNMOUNT     component teardown
+//
+// THE TABLE. Completeness is the table itself — every (state, event)
+// cell is defined; table conformance is enforced by a test that holds
+// the spec table as data and diffs the reducer against it cell by cell.
+// Duplicate/inappropriate events are idempotent self-loops (absorbing),
+// so no interleaving — however adversarial — leaves the machine
+// undefined or divergent.
+
+export type SurfacePhase =
+  | "closed"
+  | "openingFrom"
+  | "openingTo"
+  | "open"
+  | "closingFrom"
+  | "closingTo";
+
+export type SurfaceEventType =
+  | "OPEN"
+  | "CLOSE"
+  | "FLIP"
+  | "DEADLINE"
+  | "TEND"
+  | "UNMOUNT";
+
+export type SurfaceEvent = { type: SurfaceEventType };
+
+export const SURFACE_PHASES: readonly SurfacePhase[] = [
+  "closed",
+  "openingFrom",
+  "openingTo",
+  "open",
+  "closingFrom",
+  "closingTo",
+] as const;
+
+export const SURFACE_EVENTS: readonly SurfaceEventType[] = [
+  "OPEN",
+  "CLOSE",
+  "FLIP",
+  "DEADLINE",
+  "TEND",
+  "UNMOUNT",
+] as const;
+
+/**
+ * The total transition function δ: S × E → S.
+ *
+ * | state       | OPEN         | CLOSE        | FLIP        | DEADLINE    | TEND        | UNMOUNT |
+ * |-------------|--------------|--------------|-------------|-------------|-------------|---------|
+ * | closed      | openingFrom  | closed       | closed      | closed      | closed      | closed  |
+ * | openingFrom | openingFrom  | closingFrom  | openingTo   | open        | open        | closed  |
+ * | openingTo   | openingTo    | closingFrom  | openingTo   | open        | open        | closed  |
+ * | open        | open         | closingFrom  | open        | open        | open        | closed  |
+ * | closingFrom | openingFrom  | closingFrom  | closingTo   | closed      | closed      | closed  |
+ * | closingTo   | openingFrom  | closingTo    | closingTo   | closed      | closed      | closed  |
+ *
+ * Reading guide:
+ * - Requests are idempotent (OPEN in any opening/open state is a no-op)
+ *   — user flapping converges instead of thrashing.
+ * - A CLOSE during the opening window reverses from the CURRENT computed
+ *   style (CSS re-targets the running transition); a OPEN during the
+ *   closing window likewise reverses. Interruption is a first-class cell,
+ *   not a corner case — the f108–f112 churn of the 2026-09 recording.
+ * - DEADLINE alone walks any state to a quiescent state: openingFrom →
+ *   open, closingFrom → closed — starving frames skip the animation, not
+ *   the state). This is the liveness column: under A1+A2 every request
+ *   settles within flipBudget + maxDuration + slack.
+ */
+export function surfaceTransition(
+  phase: SurfacePhase,
+  event: SurfaceEventType,
+): SurfacePhase {
+  switch (phase) {
+    case "closed":
+      switch (event) {
+        case "OPEN": return "openingFrom";
+        case "CLOSE":
+        case "FLIP":
+        case "DEADLINE":
+        case "TEND":
+        case "UNMOUNT": return "closed";
+      }
+      break;
+    case "openingFrom":
+      switch (event) {
+        case "OPEN": return "openingFrom";
+        case "CLOSE": return "closingFrom";
+        case "FLIP": return "openingTo";
+        case "DEADLINE":
+        case "TEND": return "open";
+        case "UNMOUNT": return "closed";
+      }
+      break;
+    case "openingTo":
+      switch (event) {
+        case "OPEN": return "openingTo";
+        case "CLOSE": return "closingFrom";
+        case "FLIP": return "openingTo";
+        case "DEADLINE":
+        case "TEND": return "open";
+        case "UNMOUNT": return "closed";
+      }
+      break;
+    case "open":
+      switch (event) {
+        case "OPEN":
+        case "FLIP":
+        case "DEADLINE":
+        case "TEND": return "open";
+        case "CLOSE": return "closingFrom";
+        case "UNMOUNT": return "closed";
+      }
+      break;
+    case "closingFrom":
+      switch (event) {
+        case "OPEN": return "openingFrom";
+        case "CLOSE": return "closingFrom";
+        case "FLIP": return "closingTo";
+        case "DEADLINE":
+        case "TEND": return "closed";
+        case "UNMOUNT": return "closed";
+      }
+      break;
+    case "closingTo":
+      switch (event) {
+        case "OPEN": return "openingFrom";
+        case "CLOSE":
+        case "FLIP": return "closingTo";
+        case "DEADLINE":
+        case "TEND": return "closed";
+        case "UNMOUNT": return "closed";
+      }
+      break;
+  }
+  // Exhaustiveness guard: TypeScript proves every phase/event pair
+  // returned above; reaching this line is a compile-time impossibility
+  // that we still assert at runtime (a built table can never be wrong
+  // silently).
+  throw new Error(
+    `[surfaceMachine] unhandled transition ${phase} x ${event} — the table has a hole (bug: table not total)`,
+  );
+}
+
+/** Whether the phase is one of the two quiescent (resting) states. */
+export function isQuiescent(phase: SurfacePhase): boolean {
+  return phase === "closed" || phase === "open";
+}
+
+/** Whether the surface's DOM is mounted (everything except `closed`). */
+export function isMounted(phase: SurfacePhase): boolean {
+  return phase !== "closed";
+}
+
+/** The class-pair family a phase paints (pure Moore output). */
+export type SurfaceClassPair = "none" | "enter-from" | "enter-to" | "leave-from" | "leave-to";
+
+export function classPairOf(phase: SurfacePhase): SurfaceClassPair {
+  switch (phase) {
+    case "closed": return "none";
+    case "openingFrom": return "enter-from";
+    case "openingTo": return "enter-to";
+    case "open": return "none";
+    case "closingFrom": return "leave-from";
+    case "closingTo": return "leave-to";
+  }
+}
+
+/** Vue-style transition classes for one layer prefix (Moore output).
+ *
+ *  The names match what the family's SCSS already animates
+ *  (`${prefix}-enter-from` etc.), so adopting the machine changes WHO
+ *  flips the classes and WHEN — never WHAT the classes are.
+ */
+export function classesForPair(prefix: string, pair: SurfaceClassPair): string[] {
+  switch (pair) {
+    case "none": return [];
+    case "enter-from": return [`${prefix}-enter-from`, `${prefix}-enter-active`];
+    case "enter-to": return [`${prefix}-enter-to`, `${prefix}-enter-active`];
+    case "leave-from": return [`${prefix}-leave-from`, `${prefix}-leave-active`];
+    case "leave-to": return [`${prefix}-leave-to`, `${prefix}-leave-active`];
+  }
+}

package/src/runtime/transitionWatchdog.test.ts

@@ -1,79 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-import { armTransitionClassWatchdog, stripTransitionClasses } from "./transitionWatchdog";
-
-afterEach(() => {
-  vi.useRealTimers();
-});
-
-function makeEl(...classes: string[]): HTMLElement {
-  const el = document.createElement("div");
-  el.className = classes.join(" ");
-  return el;
-}
-
-describe("stripTransitionClasses", () => {
-  it("removes every name-prefixed transition class and keeps the rest", () => {
-    const el = makeEl(
-      "hk-modal-overlay",
-      "hk-modal-overlay-enter-from",
-      "hk-modal-overlay-enter-active",
-      "other-class",
-    );
-    stripTransitionClasses(el, "hk-modal-overlay");
-    expect(el.className).toBe("hk-modal-overlay other-class");
-  });
-
-  it("never strips a class merely containing the name mid-word", () => {
-    const el = makeEl("hk-modal-overlay-v2");
-    stripTransitionClasses(el, "hk-modal-overlay");
-    expect(el.className).toBe("hk-modal-overlay-v2");
-  });
-
-  it("is a no-op on a class-less element", () => {
-    const el = makeEl("hk-modal-overlay");
-    stripTransitionClasses(el, "hk-modal-overlay");
-    expect(el.className).toBe("hk-modal-overlay");
-  });
-});
-
-describe("armTransitionClassWatchdog", () => {
-  it("strips stuck transition classes once the budget lapses while open", () => {
-    vi.useFakeTimers();
-    const el = makeEl(
-      "hk-modal-overlay",
-      "hk-modal-overlay-enter-from",
-      "hk-modal-overlay-enter-active",
-    );
-    armTransitionClassWatchdog(el, "hk-modal-overlay", () => true);
-    vi.advanceTimersByTime(599);
-    expect(el.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
-    vi.advanceTimersByTime(2);
-    expect(el.className).toBe("hk-modal-overlay");
-  });
-
-  it("leaves the element alone once the surface closed (leave owns it)", () => {
-    vi.useFakeTimers();
-    const el = makeEl("hk-modal-overlay", "hk-modal-overlay-enter-from");
-    armTransitionClassWatchdog(el, "hk-modal-overlay", () => false);
-    vi.advanceTimersByTime(1000);
-    expect(el.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
-  });
-
-  it("disarming cancels the strip (a normal enter finalized)", () => {
-    vi.useFakeTimers();
-    const el = makeEl("hk-modal-overlay", "hk-modal-overlay-enter-active");
-    const disarm = armTransitionClassWatchdog(el, "hk-modal-overlay", () => true);
-    disarm();
-    vi.advanceTimersByTime(1000);
-    expect(el.classList.contains("hk-modal-overlay-enter-active")).toBe(true);
-  });
-
-  it("does nothing when no transition class is stuck", () => {
-    vi.useFakeTimers();
-    const el = makeEl("hk-modal-overlay");
-    armTransitionClassWatchdog(el, "hk-modal-overlay", () => true);
-    vi.advanceTimersByTime(1000);
-    expect(el.className).toBe("hk-modal-overlay");
-  });
-});

package/src/runtime/transitionWatchdog.ts

@@ -1,73 +0,0 @@
-// Transition-class repair kit — the enter-side counterpart of HkModal's
-// leave watchdog.
-//
-// A Vue <Transition> flips enter-from → enter-to through rAF and waits on
-// transitionend. When rAF starves (occluded/backgrounded webview — the
-// same pathology the leave watchdog in HkModal bounds), the enter classes
-// FREEZE on the element: the layer keeps `*-enter-from` (opacity: 0,
-// translateY(100%), …) while the surface is logically open. The modal's
-// scrim then stays invisible with the panel floating above it, and the
-// eventual close flashes the resurrected curtain at full opacity — the
-// 2026-09 mobile "black rectangle" report (the leave pair
-// leave-from → leave-to snaps the scrim to opacity: 1 before fading).
-//
-// Two primitives:
-//   stripTransitionClasses — remove every `name-*` transition class so the
-//     element snaps to its resting state (no fade — this is a repair
-//     path, the animation already failed).
-//   armTransitionClassWatchdog — bounded safety net: if the element still
-//     carries `name-enter-*` classes once the budget lapses (larger than
-//     any themed duration), strip them. Normal enters disarm it; a
-//     completed enter is a no-op (the classes are already gone).
-
-/** The exact set of classes Vue's <Transition name=…> stamps on an
- *  element — matched precisely so a hand-written class that merely
- *  starts with the name (e.g. `name-v2`) is never touched. */
-const TRANSITION_CLASS_SUFFIXES = [
-  "-enter-from",
-  "-enter-active",
-  "-enter-to",
-  "-leave-from",
-  "-leave-active",
-  "-leave-to",
-] as const;
-
-function transitionClassesOf(el: HTMLElement, name: string): string[] {
-  const names = TRANSITION_CLASS_SUFFIXES.map((suffix) => `${name}${suffix}`);
-  return Array.from(el.classList).filter((cls) => names.includes(cls));
-}
-
-/** Strip all `name-*` transition classes off `el`, snapping it to its
- *  resting (non-transition) state. Safe on class-less elements. */
-export function stripTransitionClasses(el: HTMLElement, name: string): void {
-  for (const cls of transitionClassesOf(el, name)) el.classList.remove(cls);
-}
-
-/**
- * Bound a stuck transition: if the element still carries ANY `name-*`
- * transition class after `budgetMs` while the surface is open (the enter
- * never finalized — or an interrupted leave left its pair behind — rAF
- * starvation), strip them so the layer renders in its open state instead
- * of staying frozen at a from/to pair. The budget is larger than any
- * themed CSS duration, so a legitimate animation never sees the strip.
- *
- * `isStillOpen` gates the repair: once the surface closed, the leave owns
- * the element and a late strip must not fight it.
- *
- * @returns the disarm function (call on after-enter / enter-cancelled /
- *   close / unmount).
- */
-export function armTransitionClassWatchdog(
-  el: HTMLElement,
-  name: string,
-  isStillOpen: () => boolean,
-  budgetMs = 600,
-): () => void {
-  const timer = setTimeout(() => {
-    if (!isStillOpen()) return;
-    if (transitionClassesOf(el, name).length > 0) {
-      stripTransitionClasses(el, name);
-    }
-  }, budgetMs);
-  return () => clearTimeout(timer);
-}