@seed-design/stackflow 1.1.23 → 1.1.25

package/lib/primitive/GlobalInteraction/dom.cjs

@@ -82,6 +82,34 @@ function clearAllStyles(t) {
 	for (const el of all) clearStyles(el);
 }
 /**
+* Remove all leftover inline styles from the top activity once the
+* transition has settled (globalTransitionState === "idle").
+*
+* The top + behind pair model only handles the single immediately adjacent
+* behind layer. When transitions overlap (concurrent pop, swipe-back race,
+* etc.) the landing screen can get stuck with the temporary styles of a
+* "behind" or an "exiting top" — the layer stays at -30% and shifts by 1/3,
+* or the appBar root stays at opacity 0 (setPostExitPositions) and the whole
+* app bar disappears.
+*
+* At idle the top must always be in a clean default state (setIdlePositions
+* only clears the top and styles the behind), so wipe any leftover inline
+* back to the CSS defaults (layer 0%, appBar visible). The behind is left
+* untouched, and it's a no-op if already clean.
+*/
+function clearTopActivityStyles(stackEl) {
+	const t = findTransitionTargets(stackEl);
+	const topParts = [
+		t.topLayer,
+		t.topDim,
+		t.topTitle,
+		t.topAppBarRoot,
+		t.topAppBarBackground,
+		...t.topIcons
+	];
+	for (const el of topParts) clearStyles(el);
+}
+/**
 * Set idle positions after push completes.
 * Pattern: clear everything first, then set only non-default positions.
 */
@@ -139,6 +167,7 @@ function applySwipeStyles(t, displacement, ratio) {
 //#endregion
 exports.applySwipeStyles = applySwipeStyles;
 exports.clearAllStyles = clearAllStyles;
+exports.clearTopActivityStyles = clearTopActivityStyles;
 exports.findTransitionTargets = findTransitionTargets;
 exports.readTransitionStyle = readTransitionStyle;
 exports.setIdlePositions = setIdlePositions;

package/lib/primitive/GlobalInteraction/dom.d.ts

@@ -30,6 +30,23 @@ export declare function setOpacity(el: HTMLElement | null, value: string): void;
  * This is the foundation — call before setting any specific positions.
  */
 export declare function clearAllStyles(t: TransitionTargets): void;
+/**
+ * Remove all leftover inline styles from the top activity once the
+ * transition has settled (globalTransitionState === "idle").
+ *
+ * The top + behind pair model only handles the single immediately adjacent
+ * behind layer. When transitions overlap (concurrent pop, swipe-back race,
+ * etc.) the landing screen can get stuck with the temporary styles of a
+ * "behind" or an "exiting top" — the layer stays at -30% and shifts by 1/3,
+ * or the appBar root stays at opacity 0 (setPostExitPositions) and the whole
+ * app bar disappears.
+ *
+ * At idle the top must always be in a clean default state (setIdlePositions
+ * only clears the top and styles the behind), so wipe any leftover inline
+ * back to the CSS defaults (layer 0%, appBar visible). The behind is left
+ * untouched, and it's a no-op if already clean.
+ */
+export declare function clearTopActivityStyles(stackEl: HTMLElement): void;
 /**
  * Set idle positions after push completes.
  * Pattern: clear everything first, then set only non-default positions.

package/lib/primitive/GlobalInteraction/dom.js

@@ -82,6 +82,34 @@ function clearAllStyles(t) {
 	for (const el of all) clearStyles(el);
 }
 /**
+* Remove all leftover inline styles from the top activity once the
+* transition has settled (globalTransitionState === "idle").
+*
+* The top + behind pair model only handles the single immediately adjacent
+* behind layer. When transitions overlap (concurrent pop, swipe-back race,
+* etc.) the landing screen can get stuck with the temporary styles of a
+* "behind" or an "exiting top" — the layer stays at -30% and shifts by 1/3,
+* or the appBar root stays at opacity 0 (setPostExitPositions) and the whole
+* app bar disappears.
+*
+* At idle the top must always be in a clean default state (setIdlePositions
+* only clears the top and styles the behind), so wipe any leftover inline
+* back to the CSS defaults (layer 0%, appBar visible). The behind is left
+* untouched, and it's a no-op if already clean.
+*/
+function clearTopActivityStyles(stackEl) {
+	const t = findTransitionTargets(stackEl);
+	const topParts = [
+		t.topLayer,
+		t.topDim,
+		t.topTitle,
+		t.topAppBarRoot,
+		t.topAppBarBackground,
+		...t.topIcons
+	];
+	for (const el of topParts) clearStyles(el);
+}
+/**
 * Set idle positions after push completes.
 * Pattern: clear everything first, then set only non-default positions.
 */
@@ -137,4 +165,4 @@ function applySwipeStyles(t, displacement, ratio) {
 	for (const icon of t.behindIcons) setOpacity(icon, `${ratio}`);
 }
 //#endregion
-export { applySwipeStyles, clearAllStyles, findTransitionTargets, readTransitionStyle, setIdlePositions, setOpacity, setPostExitPositions, setTransform };
+export { applySwipeStyles, clearAllStyles, clearTopActivityStyles, findTransitionTargets, readTransitionStyle, setIdlePositions, setOpacity, setPostExitPositions, setTransform };

package/lib/primitive/GlobalInteraction/useGlobalInteraction.cjs

@@ -4,6 +4,7 @@ const require_useTopActivity = require("../private/useTopActivity.cjs");
 const require_dom = require("./dom.cjs");
 const require_animation = require("./animation.cjs");
 let react = require("react");
+let _stackflow_react = require("@stackflow/react");
 //#region src/primitive/GlobalInteraction/useGlobalInteraction.ts
 var IDLE_CONTEXT = Object.freeze({
 	x0: 0,
@@ -135,6 +136,7 @@ function useGlobalInteraction() {
 		setSwipeBackState
 	]);
 	const topActivity = require_useTopActivity.useTopActivity();
+	const stack = (0, _stackflow_react.useStack)();
 	const prevTransitionStateRef = (0, react.useRef)(topActivity.transitionState);
 	(0, react.useLayoutEffect)(() => {
 		const prev = prevTransitionStateRef.current;
@@ -183,6 +185,12 @@ function useGlobalInteraction() {
 		stopRunningAnims,
 		cancelPendingPushRAF
 	]);
+	const topActivityId = stack?.activities.find((activity) => activity.isTop)?.id;
+	(0, react.useLayoutEffect)(() => {
+		if (stack?.globalTransitionState !== "idle") return;
+		const stackEl = stackRef.current;
+		if (stackEl) require_dom.clearTopActivityStyles(stackEl);
+	}, [stack?.globalTransitionState, topActivityId]);
 	(0, react.useEffect)(() => {
 		return () => {
 			cancelPendingPushRAF();

package/lib/primitive/GlobalInteraction/useGlobalInteraction.js

@@ -1,8 +1,9 @@
 "use client";
 import { useTopActivity } from "../private/useTopActivity.js";
-import { applySwipeStyles, clearAllStyles, findTransitionTargets, readTransitionStyle, setIdlePositions, setPostExitPositions } from "./dom.js";
+import { applySwipeStyles, clearAllStyles, clearTopActivityStyles, findTransitionTargets, readTransitionStyle, setIdlePositions, setPostExitPositions } from "./dom.js";
 import { animateSwipeCancel, animateSwipeComplete, animateTransition, cancelAll, scrubAppBarBackground } from "./animation.js";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { useStack } from "@stackflow/react";
 //#region src/primitive/GlobalInteraction/useGlobalInteraction.ts
 var IDLE_CONTEXT = Object.freeze({
 	x0: 0,
@@ -134,6 +135,7 @@ function useGlobalInteraction() {
 		setSwipeBackState
 	]);
 	const topActivity = useTopActivity();
+	const stack = useStack();
 	const prevTransitionStateRef = useRef(topActivity.transitionState);
 	useLayoutEffect(() => {
 		const prev = prevTransitionStateRef.current;
@@ -182,6 +184,12 @@ function useGlobalInteraction() {
 		stopRunningAnims,
 		cancelPendingPushRAF
 	]);
+	const topActivityId = stack?.activities.find((activity) => activity.isTop)?.id;
+	useLayoutEffect(() => {
+		if (stack?.globalTransitionState !== "idle") return;
+		const stackEl = stackRef.current;
+		if (stackEl) clearTopActivityStyles(stackEl);
+	}, [stack?.globalTransitionState, topActivityId]);
 	useEffect(() => {
 		return () => {
 			cancelPendingPushRAF();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-design/stackflow",
-  "version": "1.1.23",
+  "version": "1.1.25",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/daangn/seed-design.git",
@@ -36,7 +36,7 @@
     "clsx": "^2.1.1"
   },
   "devDependencies": {
-    "@seed-design/css": "1.2.13",
+    "@seed-design/css": "1.2.15",
     "@stackflow/core": "^1.2.0",
     "@stackflow/react": "^1.5.1",
     "@types/react": "^19.2.2",

package/src/primitive/GlobalInteraction/animation.ts

@@ -138,10 +138,13 @@ function collectAnimations(anims: (Animation | null)[], durationMs: number): Ani
 
 // ─── iOS Slide ──────────────────────────────────────────────────────────────
 
-interface TitleKeyframe {
+// Intersect with the DOM `Keyframe` so values of this type satisfy the
+// `[property: string]` index signature `el.animate()` expects, while still
+// guaranteeing `opacity` and `transform` are present.
+type TitleKeyframe = Keyframe & {
   opacity: string;
   transform: string;
-}
+};
 
 interface IosPositions {
   topLayer: string;

package/src/primitive/GlobalInteraction/dom.ts

@@ -127,6 +127,35 @@ export function clearAllStyles(t: TransitionTargets) {
   for (const el of all) clearStyles(el);
 }
 
+/**
+ * Remove all leftover inline styles from the top activity once the
+ * transition has settled (globalTransitionState === "idle").
+ *
+ * The top + behind pair model only handles the single immediately adjacent
+ * behind layer. When transitions overlap (concurrent pop, swipe-back race,
+ * etc.) the landing screen can get stuck with the temporary styles of a
+ * "behind" or an "exiting top" — the layer stays at -30% and shifts by 1/3,
+ * or the appBar root stays at opacity 0 (setPostExitPositions) and the whole
+ * app bar disappears.
+ *
+ * At idle the top must always be in a clean default state (setIdlePositions
+ * only clears the top and styles the behind), so wipe any leftover inline
+ * back to the CSS defaults (layer 0%, appBar visible). The behind is left
+ * untouched, and it's a no-op if already clean.
+ */
+export function clearTopActivityStyles(stackEl: HTMLElement) {
+  const t = findTransitionTargets(stackEl);
+  const topParts = [
+    t.topLayer,
+    t.topDim,
+    t.topTitle,
+    t.topAppBarRoot,
+    t.topAppBarBackground,
+    ...t.topIcons,
+  ];
+  for (const el of topParts) clearStyles(el);
+}
+
 /**
  * Set idle positions after push completes.
  * Pattern: clear everything first, then set only non-default positions.

package/src/primitive/GlobalInteraction/useGlobalInteraction.test.tsx

@@ -0,0 +1,159 @@
+import { aggregate, makeEvent, type DomainEvent, type Stack } from "@stackflow/core";
+import { render } from "@testing-library/react";
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { appBarAnatomy } from "../AppBar/anatomy";
+import { appScreenAnatomy } from "../AppScreen/anatomy";
+
+// `useGlobalInteraction` (and the `useTopActivity` it calls) only consume
+// `useStack` from @stackflow/react. Mocking just that lets the test feed real
+// Stack snapshots — built by @stackflow/core's own reducer — without pulling in
+// a renderer plugin. Registered before the dynamic import below so the hook
+// picks it up.
+let currentStack: Stack;
+mock.module("@stackflow/react", () => ({ useStack: () => currentStack }));
+
+const { useGlobalInteraction } = await import("./useGlobalInteraction");
+const { findTransitionTargets, setIdlePositions } = await import("./dom");
+
+// happy-dom ships no WAAPI. A `finished` that never settles models an
+// animation that is still in flight, which is all these tests need.
+Element.prototype.animate = (() => ({
+  finished: new Promise<void>(() => {}),
+  cancel() {},
+})) as Element["animate"];
+
+// ─── Real stack snapshots ───────────────────────────────────────────────────
+
+const T0 = 1_000_000;
+const TRANSITION_DURATION = 350;
+
+/** Zero-padded so the reducer's lexicographic sort by id matches insertion order. */
+function evt<T extends DomainEvent["name"]>(
+  seq: number,
+  name: T,
+  params: Omit<Extract<DomainEvent, { name: T }>, "id" | "name" | "eventDate">,
+) {
+  return makeEvent(name, {
+    ...params,
+    id: String(seq).padStart(4, "0"),
+    eventDate: T0 + seq,
+  });
+}
+
+const BASE_EVENTS: DomainEvent[] = [
+  evt(1, "Initialized", { transitionDuration: TRANSITION_DURATION }),
+  evt(2, "ActivityRegistered", { activityName: "Screen" }),
+  evt(3, "Pushed", { activityId: "a1", activityName: "Screen", activityParams: {} }),
+  evt(4, "Pushed", { activityId: "a2", activityName: "Screen", activityParams: {} }),
+];
+
+/** Far enough past every eventDate that both pushes have settled. */
+const SETTLED_AT = T0 + TRANSITION_DURATION * 10;
+
+const POP_SEQ = 5;
+
+function stackAfter(...extraEvents: DomainEvent[]): Stack {
+  return aggregate([...BASE_EVENTS, ...extraEvents], SETTLED_AT);
+}
+
+/** `pop({ animate: false })` — stackflow maps it to `skipExitActiveState`. */
+const POP_WITHOUT_ANIMATION = evt(POP_SEQ, "Popped", { skipExitActiveState: true });
+
+/** A plain animated `pop()`, still mid-flight at `SETTLED_AT`. */
+const POP_WITH_ANIMATION = makeEvent("Popped", {
+  id: String(POP_SEQ).padStart(4, "0"),
+  eventDate: SETTLED_AT,
+});
+
+// ─── Harness ────────────────────────────────────────────────────────────────
+
+function ActivityMarkup({ id, isTop }: { id: string; isTop: boolean }) {
+  return (
+    <section
+      data-part={appScreenAnatomy.activity}
+      data-activity-id={id}
+      data-transition-style="slideFromRightIOS"
+      {...(isTop ? { "data-activity-is-top": "" } : {})}
+    >
+      <div data-part={appScreenAnatomy.layer} data-testid={`${id}-layer`} />
+      <div data-part={appScreenAnatomy.dim} />
+      <div data-part={appBarAnatomy.root}>
+        <div data-part={appBarAnatomy.background} />
+        <div data-part={appBarAnatomy.main} data-testid={`${id}-title`} />
+        <div data-part={appBarAnatomy.icon} data-testid={`${id}-icon`} />
+      </div>
+    </section>
+  );
+}
+
+function Harness() {
+  const { stackRef } = useGlobalInteraction();
+
+  // Mirrors the core's `visibleActivities` filter — exit-done is unmounted.
+  const visible = currentStack.activities.filter((a) => a.transitionState !== "exit-done");
+
+  return (
+    <div ref={stackRef} data-testid="stack">
+      {visible.map((activity) => (
+        <ActivityMarkup key={activity.id} id={activity.id} isTop={activity.isTop} />
+      ))}
+    </div>
+  );
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe("useGlobalInteraction — settle safety-net", () => {
+  beforeEach(() => {
+    currentStack = stackAfter();
+  });
+
+  it("leaves the behind layer pinned at its idle offset while a2 is on top", () => {
+    // Premise check: a settled push is idle, with a2 on top.
+    expect(currentStack.globalTransitionState).toBe("idle");
+    expect(currentStack.activities.find((a) => a.isTop)?.id).toBe("a2");
+
+    const { getByTestId, rerender } = render(<Harness />);
+
+    // Exactly what the push's finished handler leaves behind.
+    setIdlePositions(findTransitionTargets(getByTestId("stack")), "slideFromRightIOS");
+    rerender(<Harness />);
+
+    expect(getByTestId("a1-layer").style.transform).toBe("translate3d(-30%, 0, 0)");
+  });
+
+  it("clears the landing activity when pop({ animate: false }) skips exit-active", () => {
+    const { getByTestId, rerender } = render(<Harness />);
+    setIdlePositions(findTransitionTargets(getByTestId("stack")), "slideFromRightIOS");
+
+    currentStack = stackAfter(POP_WITHOUT_ANIMATION);
+
+    // Premise: the transition state machine never moves — a1 just becomes top.
+    expect(currentStack.globalTransitionState).toBe("idle");
+    expect(currentStack.activities.find((a) => a.isTop)?.id).toBe("a1");
+
+    rerender(<Harness />);
+
+    expect(getByTestId("a1-layer").style.transform).toBe("");
+    expect(getByTestId("a1-title").style.transform).toBe("");
+    expect(getByTestId("a1-title").style.opacity).toBe("");
+    expect(getByTestId("a1-icon").style.opacity).toBe("");
+  });
+
+  it("does not touch inline styles while a transition is still in flight", () => {
+    const { getByTestId, rerender } = render(<Harness />);
+    setIdlePositions(findTransitionTargets(getByTestId("stack")), "slideFromRightIOS");
+
+    currentStack = stackAfter(POP_WITH_ANIMATION);
+
+    // Premise: an animated pop parks a2 in exit-active, so the stack is loading.
+    expect(currentStack.globalTransitionState).toBe("loading");
+    expect(currentStack.activities.find((a) => a.id === "a2")?.transitionState).toBe("exit-active");
+
+    rerender(<Harness />);
+
+    // The WAAPI pop animation owns the unwind from here — the safety-net must
+    // stay out of the way until everything settles.
+    expect(getByTestId("a1-layer").style.transform).toBe("translate3d(-30%, 0, 0)");
+  });
+});

package/src/primitive/GlobalInteraction/useGlobalInteraction.ts

@@ -1,3 +1,4 @@
+import { useStack } from "@stackflow/react";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
 import { useTopActivity } from "../private/useTopActivity";
 import {
@@ -7,6 +8,7 @@ import {
   readTransitionStyle,
   applySwipeStyles,
   clearAllStyles,
+  clearTopActivityStyles,
   setIdlePositions,
   setPostExitPositions,
 } from "./dom";
@@ -257,6 +259,7 @@ export function useGlobalInteraction() {
   }, [stopRunningAnims, stopAppBarBgScrub, setSwipeBackState]);
 
   const topActivity = useTopActivity();
+  const stack = useStack();
 
   // ── WAAPI push/pop transitions triggered by stackflow state changes ──
   const prevTransitionStateRef = useRef<string>(topActivity.transitionState);
@@ -326,6 +329,35 @@ export function useGlobalInteraction() {
     }
   }, [topActivity.transitionState, stopRunningAnims, cancelPendingPushRAF]);
 
+  // ── Settle safety-net ──
+  // The top + behind pair model only handles the single immediately adjacent
+  // behind layer. When transitions overlap (concurrent pop, swipe-back race,
+  // etc.) and end on a path the pair model didn't unwind, the landing screen
+  // can get stuck with temporary styles — the layer stays at -30% and shifts
+  // by 1/3, or the appBar root stays at opacity 0 (setPostExitPositions) and
+  // the whole app bar disappears.
+  //
+  // Guarantee: once everything settles (globalTransitionState === "idle") the
+  // top must always be in a clean default state. Wipe all leftover inline
+  // styles from the top activity — the behind is left untouched (stays at
+  // -30%), this only runs at idle, and it's a no-op if already clean.
+  //
+  // Keyed on the top activity too, not just globalTransitionState: an
+  // `animate: false` navigation makes the core skip the enter-active /
+  // exit-active phase entirely, so globalTransitionState never leaves "idle"
+  // and a state-only dependency would never re-run. That is how a behind
+  // layer became the top while still pinned at -30%.
+  const topActivityId = stack?.activities.find((activity) => activity.isTop)?.id;
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: topActivityId is a trigger, not a value read here — clearTopActivityStyles re-queries the DOM
+  useLayoutEffect(() => {
+    if (stack?.globalTransitionState !== "idle") return;
+    const stackEl = stackRef.current;
+    if (stackEl) {
+      clearTopActivityStyles(stackEl);
+    }
+  }, [stack?.globalTransitionState, topActivityId]);
+
   // Cancel any pending push rAF and running animations on unmount so
   // late-firing finished handlers can't run against a torn-down stack.
   useEffect(() => {