fix(dashboard): firing animation gates to single-step jumps and uses pre-fire enabled set

fahchen · fahchen · commit 6e51744ac296 · 2026-05-31T18:56:50.000+09:00
Live firing animation now skips when activeVersion jumps by more than one —
multi-step batches snap to post-fire instead of animating only the last
occurrence over the already-combined state. Replay-mode path already had
this check.

Intermediate enabled-transition set during the dwell phase previously came
from a naive "every input place has ≥1 token" client check, which ignored
arc multiplicity, transition guards, and binding expressions, and treated
zero-input transitions as disabled. Drop that helper and keep the pre-fire
enabled set across all firing phases (pre, intermediate, output) so the
highlighted transitions match a real, server-authoritative enablement state
the whole time. The post-fire set takes over at fullMs as before.
diff --git a/dashboard/ui/src/routes/EnactmentDetailPage.test.tsx b/dashboard/ui/src/routes/EnactmentDetailPage.test.tsx
@@ -1049,7 +1049,7 @@ describe("EnactmentDetailPage", () => {
       }
     })
 
-    it("replay step-forward progresses enabled set pre → intermediate (client-computed) → post across the three-interval firing window", async () => {
+    it("replay step-forward holds the PRE-fire enabled set across the entire firing window, then snaps to post-fire at fullMs", async () => {
       const restore = mutateReplay(
         { version: 0, derived_at: "2026-05-29T01:00:00Z" },
         { min: 0, max: 3 }
@@ -1121,23 +1121,24 @@ describe("EnactmentDetailPage", () => {
         expect(stub().dataset.firingTransition).toBe("approve")
         expect(stub().dataset.enabledTransitions).toBe("[]")
 
-        // First RAF tick at elapsed = 0. Still pre-inputEndMs → pre-fire.
+        // First RAF tick at elapsed = 0. Pre-fire.
         await flushRaf()
         expect(stub().dataset.enabledTransitions).toBe("[]")
 
-        // Cross inputEndMs (=800). In intermediate window now. The client
-        // re-derives the enabled set from the intermediate diagram tokens
-        // (the test snapshot keeps pending=1, decided=0 so `approve` remains
-        // enabled at the intermediate marking).
+        // Cross inputEndMs (=800) into the intermediate (dwell) window. The
+        // engine-correct intermediate enabled set can't be computed
+        // client-side (arc multiplicity / guards / binding expressions are
+        // not on the wire), so we keep the pre-fire enabled set instead of
+        // lying with a tokens-only approximation.
         nowRef.current = 5_900
         await flushRaf()
-        expect(stub().dataset.enabledTransitions).toBe(JSON.stringify(["approve"]))
+        expect(stub().dataset.enabledTransitions).toBe("[]")
 
         // Still in Phase B (elapsed = 1600 → between outputStartMs=1200 and
-        // fullMs=2000). Intermediate enabled persists until fullMs apply.
+        // fullMs=2000). Override still pre-fire.
         nowRef.current = 6_600
         await flushRaf()
-        expect(stub().dataset.enabledTransitions).toBe(JSON.stringify(["approve"]))
+        expect(stub().dataset.enabledTransitions).toBe("[]")
 
         // Past fullMs → applyFinalPendings flips replayEnabledTransitions to
         // the post-fire set carried by the reply.
@@ -1154,6 +1155,176 @@ describe("EnactmentDetailPage", () => {
       }
     })
 
+    it("skips the live firing animation when activeVersion jumps by more than 1 (multi-occurrence batch)", async () => {
+      const mut = sampleSnapshot as unknown as {
+        summary: { version: number }
+        occurrences: Array<{
+          id: string
+          step_number: number
+          transition: string
+          binding_summary: string
+          occurred_at: string
+          outputs_summary: string
+        }>
+      }
+      const origVersion = mut.summary.version
+      const origOccurrences = mut.occurrences
+      // Park at v=3 with no occurrence so mount seeds lastVersionRef without
+      // animating.
+      mut.summary.version = 3
+      mut.occurrences = []
+
+      try {
+        const { rerender } = renderRoute(<EnactmentDetailPage />)
+        const stub = () => screen.getByTestId("net-diagram-stub")
+        expect(stub().dataset.firingTransition).toBe("")
+
+        // Jump from v=3 to v=5 (TWO occurrences). The runner batched both;
+        // animating only the LAST would misrepresent the timeline, so the
+        // page must snap to post-fire without running the firing animation.
+        mut.summary.version = 5
+        mut.occurrences = [
+          {
+            id: "occ-4",
+            step_number: 4,
+            transition: "approve",
+            binding_summary: "",
+            occurred_at: "2026-05-29T01:00:00Z",
+            outputs_summary: ""
+          },
+          {
+            id: "occ-5",
+            step_number: 5,
+            transition: "approve",
+            binding_summary: "",
+            occurred_at: "2026-05-29T01:00:01Z",
+            outputs_summary: ""
+          }
+        ]
+        await act(async () => {
+          rerender(
+            <Toasty>
+              <MemoryRouter initialEntries={["/enactments/en-aaaa"]}>
+                <Routes>
+                  <Route path="/enactments/:id" element={<EnactmentDetailPage />} />
+                </Routes>
+              </MemoryRouter>
+            </Toasty>
+          )
+        })
+
+        expect(stub().dataset.firingTransition).toBe("")
+        expect(stub().dataset.firingInput).toBe("0")
+        expect(stub().dataset.firingOutput).toBe("0")
+      } finally {
+        mut.summary.version = origVersion
+        mut.occurrences = origOccurrences
+      }
+    })
+
+    it("live firing animation holds the PRE-fire enabled set across all phases via the override", async () => {
+      const mut = sampleSnapshot as unknown as {
+        summary: { version: number }
+        occurrences: Array<{
+          id: string
+          step_number: number
+          transition: string
+          binding_summary: string
+          occurred_at: string
+          outputs_summary: string
+        }>
+      }
+      const origVersion = mut.summary.version
+      const origOccurrences = mut.occurrences
+      // Sample diagram has `approve` with enabled_count=1, so the pre-fire
+      // enabled set derived in live mode is ["approve"]. NetDiagram normally
+      // derives that itself from displayedDiagram.transitions[].enabled_count,
+      // so the stub reports "live". With the firing override active during
+      // the animation it should switch to a concrete set instead.
+      mut.summary.version = 3
+      mut.occurrences = []
+
+      const rafCallbacks: FrameRequestCallback[] = []
+      const nowRef = { current: 1_000 }
+      const performanceSpy = vi.spyOn(performance, "now").mockImplementation(() => nowRef.current)
+      const rafSpy = vi
+        .spyOn(window, "requestAnimationFrame")
+        .mockImplementation((cb: FrameRequestCallback): number => {
+          rafCallbacks.push(cb)
+          return rafCallbacks.length
+        })
+      const cafSpy = vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => {})
+      const flushRaf = async () => {
+        const due = rafCallbacks.splice(0)
+        await act(async () => {
+          due.forEach((cb) => cb(nowRef.current))
+        })
+      }
+
+      try {
+        const { rerender } = renderRoute(<EnactmentDetailPage />)
+        const stub = () => screen.getByTestId("net-diagram-stub")
+        // No firing yet → NetDiagram derives enabled set itself.
+        expect(stub().dataset.enabledTransitions).toBe("live")
+
+        mut.summary.version = 4
+        mut.occurrences = [
+          {
+            id: "occ-4",
+            step_number: 4,
+            transition: "approve",
+            binding_summary: "",
+            occurred_at: "2026-05-29T01:00:00Z",
+            outputs_summary: ""
+          }
+        ]
+        await act(async () => {
+          rerender(
+            <Toasty>
+              <MemoryRouter initialEntries={["/enactments/en-aaaa"]}>
+                <Routes>
+                  <Route path="/enactments/:id" element={<EnactmentDetailPage />} />
+                </Routes>
+              </MemoryRouter>
+            </Toasty>
+          )
+        })
+
+        expect(stub().dataset.firingTransition).toBe("approve")
+        // Override active across pre + intermediate + Phase B (until fullMs).
+        const preFireSet = JSON.stringify(["approve"])
+        expect(stub().dataset.enabledTransitions).toBe(preFireSet)
+
+        // Phase A midpoint.
+        nowRef.current = 1_400
+        await flushRaf()
+        expect(stub().dataset.enabledTransitions).toBe(preFireSet)
+
+        // Intermediate (dwell).
+        nowRef.current = 2_000
+        await flushRaf()
+        expect(stub().dataset.enabledTransitions).toBe(preFireSet)
+
+        // Phase B midpoint.
+        nowRef.current = 2_600
+        await flushRaf()
+        expect(stub().dataset.enabledTransitions).toBe(preFireSet)
+
+        // Past fullMs → firing clears, override goes away, NetDiagram derives
+        // from the (post-fire) displayed diagram again.
+        nowRef.current = 3_100
+        await flushRaf()
+        expect(stub().dataset.firingTransition).toBe("")
+        expect(stub().dataset.enabledTransitions).toBe("live")
+      } finally {
+        mut.summary.version = origVersion
+        mut.occurrences = origOccurrences
+        performanceSpy.mockRestore()
+        rafSpy.mockRestore()
+        cafSpy.mockRestore()
+      }
+    })
+
     it("Jump-to-live button dispatches :exit_replay while in replay", async () => {
       const restore = mutateReplay(
         { version: 1, derived_at: "2026-05-29T01:00:00Z" },
diff --git a/dashboard/ui/src/routes/EnactmentDetailPage.tsx b/dashboard/ui/src/routes/EnactmentDetailPage.tsx
@@ -63,9 +63,12 @@ type TabId = "markings" | "workitems" | "occurrences" | "telemetry" | "debug"
 //
 // Marking + enabled-transition state commits at TWO boundaries:
 //   * inputEndMs (drain visible): displayed diagram flips to intermediate
-//     (input places drained, output places still pre-fire). Intermediate
-//     enabled set computed client-side (T enabled iff every input place of T
-//     still has ≥1 token).
+//     (input places drained, output places still pre-fire). The displayed
+//     ENABLED SET stays pinned to pre-fire — computing engine-correct
+//     enablement client-side would require arc-multiplicity, guards, and
+//     binding-expression evaluation, which the wire does not carry. Pre-fire
+//     is a known-good approximation that never lies about specific
+//     transitions during the brief dwell.
 //   * fullMs (arrival visible): displayed diagram flips to post-fire
 //     (server-pushed). Post-fire enabled set from `:replay_to_version` reply
 //     in replay mode, or from the post-fire diagram's `enabled_count` in
@@ -112,24 +115,16 @@ function buildIntermediateDiagram(
   return { ...post, places }
 }
 
-// Client-side intermediate enabled set: T is enabled iff every p_to_t arc's
-// place has ≥1 token in the supplied diagram. Matches plan option (b) — no
-// wire change; the brief intermediate-phase glow approximates engine truth.
-function computeEnabledFromDiagramTokens(diagram: DiagramPayload): ReadonlySet<string> {
-  const tokens = new Map<string, number>()
-  for (const p of diagram.places) tokens.set(p.name, p.tokens_count)
-  const inputs = new Map<string, string[]>()
-  for (const arc of diagram.arcs) {
-    if (arc.orientation !== "p_to_t") continue
-    const list = inputs.get(arc.transition) ?? []
-    list.push(arc.place)
-    inputs.set(arc.transition, list)
-  }
+// Pre-fire enabled set in LIVE mode is derived directly from the pre-fire
+// diagram's per-transition `enabled_count`. Used as the override during the
+// firing animation so the highlight doesn't flip to the post-fire set the
+// instant the server pushes the new diagram. Replay mode does NOT need this
+// helper — `replayEnabledTransitions` already holds the pre-fire value
+// through Phases A+B and snaps to post-fire at applyFinalPendings().
+function preFireEnabledFromDiagram(diagram: DiagramPayload): ReadonlySet<string> {
   const enabled = new Set<string>()
   for (const t of diagram.transitions) {
-    const inputList = inputs.get(t.name)
-    if (!inputList || inputList.length === 0) continue
-    if (inputList.every((p) => (tokens.get(p) ?? 0) >= 1)) enabled.add(t.name)
+    if (t.enabled_count > 0) enabled.add(t.name)
   }
   return enabled
 }
@@ -492,7 +487,8 @@ function DetailContent({
 
   // Three-phase intermediate state. Computed once per (firingPhase,
   // firingPreDiagram, diagram) tuple. `firingPhase === null` short-circuits so
-  // off-firing renders pay nothing.
+  // off-firing renders pay nothing. Enabled-transition set during firing is
+  // NOT computed from this diagram — see `enabledTransitionsOverride` below.
   const intermediateState = useMemo(() => {
     if (firingPhase === null || firingPreDiagram === null || diagram === null) {
       return null
@@ -504,11 +500,20 @@ function DetailContent({
     )
     return {
       diagram: interDiag,
-      markings: diagramToMarkingRows(interDiag),
-      enabled: computeEnabledFromDiagramTokens(interDiag)
+      markings: diagramToMarkingRows(interDiag)
     }
   }, [firingPhase, firingPreDiagram, diagram])
 
+  // Live-mode pre-fire enabled set. Captured from the pre-fire diagram so the
+  // override stays stable through the entire firing animation (Phase A +
+  // intermediate dwell + Phase B), instead of letting NetDiagram derive from
+  // `displayedDiagram.transitions[].enabled_count` — which flips to post-fire
+  // values the instant the server pushes the post-fire diagram.
+  const liveFiringEnabledOverride = useMemo(() => {
+    if (firingPhase === null || firingPreDiagram === null) return null
+    return preFireEnabledFromDiagram(firingPreDiagram)
+  }, [firingPhase, firingPreDiagram])
+
   // Three-phase selectors. RAF ticks update firingProgress so these recompute
   // on every frame the phase advances; identity changes only at the boundaries
   // (pre→intermediate at inputEndMs, intermediate→post at fullMs). The dwell
@@ -559,6 +564,11 @@ function DetailContent({
     if (prev === null) return
     if (activeVersion <= prev) return
     if (replayState !== null) return
+    // Multi-step bumps (runner batched N>1 occurrences into one bridge event)
+    // skip the firing animation. Animating only the LAST occurrence over the
+    // already-combined post-fire diagram would drop the intermediate firings
+    // from the visible timeline. Snap straight to post-fire instead.
+    if (activeVersion !== prev + 1) return
 
     const occurrence = occurrences.find((o) => o.step_number === activeVersion)
     if (!occurrence) return
@@ -615,22 +625,22 @@ function DetailContent({
   }, [firingPhase, applyFinalPendings])
 
   // Enabled-transition override resolution:
-  //   * Phase B (intermediate): client-computed set against drained inputs.
-  //     Drives BOTH live and replay glow during the brief intermediate window.
-  //   * Replay (non-firing OR Phase A/post): replay reply's enabled set.
-  //     `replayEnabledTransitions` holds the PRE-fire value through Phases A+B
-  //     and snaps to post-fire when applyFinalPendings runs at fullMs.
-  //   * Live (non-firing OR Phase A/post): undefined → NetDiagram derives from
-  //     the displayedDiagram's transitions[].enabled_count. Pre-fire diagram
-  //     carries pre-fire counts (Phase A), post-fire diagram carries post-fire
-  //     counts (post).
+  //   * Firing (any phase before fullMs): pre-fire enabled set. In replay,
+  //     `replayEnabledTransitions` already holds the pre-fire value through
+  //     Phases A+B and snaps to post-fire when applyFinalPendings runs at
+  //     fullMs. In live, `liveFiringEnabledOverride` mirrors the pre-fire
+  //     diagram's `enabled_count`, so the highlight doesn't follow the
+  //     server-pushed post-fire diagram mid-animation. We deliberately do NOT
+  //     re-derive enablement client-side from the intermediate (drained)
+  //     marking — engine-correct enablement needs arc multiplicity, guards,
+  //     and binding-expression evaluation; the wire carries none of that.
+  //   * Replay, non-firing: replay reply's enabled set.
+  //   * Live, non-firing: undefined → NetDiagram derives from the displayed
+  //     diagram's transitions[].enabled_count.
   const enabledTransitionsOverride: ReadonlySet<string> | undefined = (() => {
-    if (
-      firingPhase !== null &&
-      firingDisplayPhase === "intermediate" &&
-      intermediateState
-    ) {
-      return intermediateState.enabled
+    if (firingPhase !== null && firingDisplayPhase !== "post") {
+      if (replayState !== null) return replayEnabledTransitions
+      if (liveFiringEnabledOverride !== null) return liveFiringEnabledOverride
     }
     return replayState === null ? undefined : replayEnabledTransitions
   })()
