@celestia-island/hikari 0.55.0 → 0.55.2

package/src/composables/useSurfaceContentHold.ts

@@ -0,0 +1,58 @@
+import { computed, watch, type ComputedRef } from "vue";
+
+import type { SurfacePhase } from "../runtime/surfaceMachine";
+
+/**
+ * useSurfaceContentHold — keep a surface's last live content on screen
+ * for the whole close fold.
+ *
+ * Consumers routinely tear down the very state that feeds a window's body
+ * the moment its v-model flips false (clear-on-close watchers, store
+ * resets, socket disconnects). Without a hold, the leave transition then
+ * plays on an emptied shell: the frame collapses to its chrome BEFORE the
+ * fold starts (chest TodoLogModal, 2026-09-16 field report — the 697px
+ * conversation window became a 200px stub in the same tick as the close).
+ *
+ * While the machine is in a closing phase this serves the most recent
+ * live-rendered children instead of re-invoking the slots, so the fold
+ * always plays over the content the user was actually looking at. Vue's
+ * patch skips identical vnode references, so the held DOM is never
+ * re-patched during the close; child components with their own store
+ * subscriptions may still self-update (harmless — the failure mode under
+ * repair is content VANISHING, not content ticking).
+ *
+ * The hold releases the moment the surface leaves a closing phase: a
+ * reopen interrupt (closing → openingFrom) serves live slots again, and
+ * `closed` drops the cache so a closed surface retains nothing.
+ */
+export function useSurfaceContentHold(phase: ComputedRef<SurfacePhase>) {
+  const closing = computed(
+    () => phase.value === "closingFrom" || phase.value === "closingTo",
+  );
+
+  let held: unknown = null;
+
+  // A closed surface renders nothing — the cache would only pin a dead
+  // vnode tree. Drop it on the closed edge.
+  watch(phase, (p) => {
+    if (p === "closed") held = null;
+  });
+
+  /**
+   * Wrap one render-region producer: live while opening/open, frozen
+   * while closing. The first closing render falls through to live
+   * production when no snapshot exists (the surface opened directly into
+   * a close is not a real path, but the guard keeps the contract total).
+   */
+  function hold<T>(produce: () => T): T {
+    if (closing.value) {
+      if (held !== null) return held as T;
+      return produce();
+    }
+    const next = produce();
+    held = next;
+    return next;
+  }
+
+  return { hold, closing };
+}

package/src/composables/useSurfaceMachine.test.ts

@@ -240,6 +240,56 @@ describe("useSurfaceMachine driver", () => {
     expect(rig.edges.length).toBe(edgesAtRest);
   });
 
+  it("transitionstart re-arms the deadline once so a late-latched transition completes", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", () => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    const realGCS = window.getComputedStyle.bind(window);
+    vi.stubGlobal("getComputedStyle", (el: Element, ...rest: unknown[]) => {
+      const style = realGCS(el as Element, ...(rest as []));
+      return { ...style, transitionDuration: "0.3s" } as CSSStyleDeclaration;
+    });
+    const rig = mountRig(true);
+    rig.send("OPEN");
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(130); // flip timer forced the FLIP
+    expect(rig.phase()).toBe("openingTo");
+    // Flip-relative deadline: 300 + 80 → settles at t≈500 unless the
+    // browser reports the transition ACTUALLY started late (frame
+    // starvation latches the transition on the first post-flip frame).
+    const panel = document.querySelector<HTMLElement>(".panel")!;
+
+    // t=330: the transition latches 200ms after the flip.
+    await vi.advanceTimersByTimeAsync(200);
+    panel.dispatchEvent(new Event("transitionstart", { bubbles: true }));
+    // → deadline re-armed to 330 + 300 + 80 = 710.
+
+    // t=390: a bubbled report from a NON-layer descendant (target filter)
+    // and a duplicate report on the panel (one re-arm per phase) are
+    // both ignored — either would push the deadline to 770.
+    await vi.advanceTimersByTimeAsync(60);
+    const child = document.createElement("span");
+    panel.appendChild(child);
+    child.dispatchEvent(new Event("transitionstart", { bubbles: true }));
+    panel.dispatchEvent(new Event("transitionstart", { bubbles: true }));
+
+    // The flip-relative deadline (t=500) passes without settling — the
+    // re-arm is real…
+    await vi.advanceTimersByTimeAsync(300); // t=690
+    expect(rig.phase()).toBe("openingTo");
+    // …and the latch-relative deadline completes the open (t=710), ahead
+    // of where a second re-arm would have put it (t=770).
+    await vi.advanceTimersByTimeAsync(30); // t=720
+    expect(rig.phase()).toBe("open");
+    await nextTick();
+    expect(scrimClasses(rig)).toEqual([]);
+    // No late timers fire afterwards.
+    const edgesAtRest = rig.edges.length;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(rig.phase()).toBe("open");
+    expect(rig.edges.length).toBe(edgesAtRest);
+  });
+
   it("UNMOUNT from any phase clears every clock and walks to closed", async () => {
     vi.useFakeTimers();
     const rig = mountRig();

package/src/composables/useSurfaceMachine.ts

@@ -58,7 +58,10 @@ export interface SurfaceMachine {
  * - The ONLY correctness clock is setTimeout: every animation phase arms
  *   exactly one deadline timer; the frame flip is double-rAF (smooth)
  *   with a flip timer as the starved fallback. Duplicate FLIPs are
- *   absorbed by the table (idempotent self-loops).
+ *   absorbed by the table (idempotent self-loops). transitionend (TEND)
+ *   settles a phase early; transitionstart re-arms the deadline once so
+ *   a frame-starved, late-latched transition still completes — both are
+ *   advisory optimizations, never the correctness clock.
  * - Phase changes clear every pending timer/rAF before arming the next
  *   phase's — at most one flip + one deadline exist at any moment, so
  *   timers cannot leak or fire stale (the machine has no "late
@@ -257,6 +260,7 @@ export function useSurfaceMachine(options: SurfaceMachineOptions): SurfaceMachin
         if (measured > 0) {
           rearmDeadline(measured + slack);
           armTend(measured);
+          armStart(measured);
         } else {
           completeNow();
         }
@@ -264,6 +268,36 @@ export function useSurfaceMachine(options: SurfaceMachineOptions): SurfaceMachin
     }
   }
 
+  /** transitionstart re-arm: under frame starvation the CSS transition
+   *  only LATCHES when the first frame after the flip is produced, while
+   *  this phase's deadline was armed at the flip — a transition starting
+   *  300ms late would be cut mid-flight by its own deadline, snapping the
+   *  surface to rest (2026-09-16 chest field report: the desktop modal
+   *  enter freezes at its low/transparent from-pair, then jumps). When
+   *  the browser reports the transition actually started, re-arm the
+   *  deadline from that moment so a late-started transition still runs
+   *  to completion. A never-started transition (frames never come) fires
+   *  nothing — the flip-relative deadline stays the bound (A2), so this
+   *  changes settle latency only when the animation genuinely runs.
+   *  One re-arm per layer per phase: every animated property fires its
+   *  own transitionstart on the same frame. */
+  function armStart(expectedMs: number): void {
+    const seen = new Set<HTMLElement>();
+    for (const layer of options.layers) {
+      const el = layer.el?.();
+      if (!el || !el.isConnected || seen.has(el)) continue;
+      seen.add(el);
+      let rearmed = false;
+      const onStart = (e: TransitionEvent) => {
+        if (e.target !== el || rearmed) return;
+        rearmed = true;
+        rearmDeadline(expectedMs + slack);
+      };
+      el.addEventListener("transitionstart", onStart);
+      tendCleanups.push(() => el.removeEventListener("transitionstart", onStart));
+    }
+  }
+
   function send(event: SurfaceEventType): void {
     const from = phase.value;
     const to = surfaceTransition(from, event);