feat(stackflow): add FocusScope to AppScreen for focus management

packages/css/all.css

@@ -2171,6 +2171,10 @@
   display: none;
 }
 
+.seed-app-screen__layer:focus {
+  outline: none;
+}
+
 .seed-app-screen__layer {
   background-color: var(--seed-color-bg-layer-default);
 }

packages/css/all.layered.css

@@ -2388,6 +2388,10 @@
     display: none;
   }
 
+  .seed-app-screen__layer:focus {
+    outline: none;
+  }
+
   .seed-app-screen__layer {
     background-color: var(--seed-color-bg-layer-default);
   }

packages/css/recipes/app-screen.css

@@ -29,6 +29,9 @@
 .seed-app-screen__layer::-webkit-scrollbar {
     display: none;
 }
+.seed-app-screen__layer:focus {
+    outline: none;
+}
 .seed-app-screen__layer {
     background-color: var(--seed-color-bg-layer-default);
 }

packages/css/recipes/app-screen.layered.css

@@ -34,6 +34,10 @@
     display: none;
   }
 
+  .seed-app-screen__layer:focus {
+    outline: none;
+  }
+
   .seed-app-screen__layer {
     background-color: var(--seed-color-bg-layer-default);
   }

packages/qvism-preset/src/stackflow/app-screen.ts

@@ -54,6 +54,9 @@ export const appScreen = defineSlotRecipe({
       "&::-webkit-scrollbar": {
         display: "none",
       },
+      "&:focus": {
+        outline: "none",
+      },
 
       backgroundColor: vars.$color.bg.layerDefault,
     },

packages/stackflow/package.json

@@ -28,6 +28,7 @@
   },
   "dependencies": {
     "@radix-ui/react-compose-refs": "^1.1.2",
+    "@radix-ui/react-focus-scope": "^1.1.4",
     "@radix-ui/react-slot": "^1.2.3",
     "@radix-ui/react-use-callback-ref": "^1.1.1",
     "@seed-design/dom-utils": "1.0.0",

packages/stackflow/src/primitive/AppScreen/AppScreen.tsx

@@ -1,8 +1,9 @@
 import { composeRefs } from "@radix-ui/react-compose-refs";
+import { FocusScope } from "@radix-ui/react-focus-scope";
 import { mergeProps } from "@seed-design/dom-utils";
 import { Primitive, type PrimitiveProps } from "@seed-design/react-primitive";
 import { usePreventTouchDuringTransition } from "@stackflow/react-ui-core";
-import { forwardRef, useRef } from "react";
+import { forwardRef, useEffect, useRef } from "react";
 import { useAppScreen, type UseAppScreenProps } from "./useAppScreen";
 import { AppScreenProvider, useAppScreenContext } from "./useAppScreenContext";
 
@@ -32,13 +33,29 @@ export const AppScreenRoot = forwardRef<HTMLDivElement, AppScreenRootProps>((pro
     ref: innerRef as React.RefObject<HTMLDivElement>,
   });
 
+  // Focus the layer once after the enter animation completes.
+  // onMountAutoFocus fires during enter-active and interrupts the CSS animation, so we
+  // defer until transitionState reaches "enter-done". This only happens once per activity
+  // lifecycle — subsequent isTop changes (e.g. upper activity pop) don't change
+  // transitionState, so the effect won't re-fire.
+  useEffect(() => {
+    if (api.activity?.transitionState === "enter-done") {
+      api.layerRef.current?.focus();
+    }
+  }, [api.activity?.transitionState, api.layerRef]);
+
   return (
     <AppScreenProvider value={api}>
-      <Primitive.div
-        ref={composeRefs(innerRef, ref)}
-        data-stackflow-component-name="AppScreen"
-        {...mergeProps(api.activityProps, otherProps)}
-      />
+      {/* onMountAutoFocus is prevented because it fires during enter-active and
+          interrupts the CSS animation. Focus is handled by the useEffect above instead,
+          which defers until transitionState reaches "enter-done". */}
+      <FocusScope asChild trapped loop onMountAutoFocus={(e) => e.preventDefault()}>
+        <Primitive.div
+          ref={composeRefs(innerRef, ref)}
+          data-stackflow-component-name="AppScreen"
+          {...mergeProps(api.activityProps, otherProps)}
+        />
+      </FocusScope>
     </AppScreenProvider>
   );
 });
@@ -65,8 +82,14 @@ AppScreenEdge.displayName = "AppScreenEdge";
 export interface AppScreenLayerProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
 
 export const AppScreenLayer = forwardRef<HTMLDivElement, AppScreenLayerProps>((props, ref) => {
-  const { layerProps } = useAppScreenContext();
+  const { layerProps, layerRef } = useAppScreenContext();
 
-  return <Primitive.div ref={ref} {...mergeProps(layerProps, props)} />;
+  return (
+    <Primitive.div
+      ref={composeRefs(ref, layerRef)}
+      tabIndex={-1}
+      {...mergeProps(layerProps, props)}
+    />
+  );
 });
 AppScreenLayer.displayName = "AppScreenLayer";

packages/stackflow/src/primitive/AppScreen/useAppScreen.tsx

@@ -1,6 +1,6 @@
 import { dataAttr, elementProps } from "@seed-design/dom-utils";
 import { useNullableActivity } from "@stackflow/react-ui-core";
-import { useMemo } from "react";
+import { useMemo, useRef } from "react";
 import { type UseSwipeBackProps, useSwipeBack } from "../GlobalInteraction/useSwipeBack";
 import { useActivityZIndexBase } from "../../hooks";
 
@@ -10,6 +10,7 @@ export type UseAppScreenReturn = ReturnType<typeof useAppScreen>;
 
 export function useAppScreen(props: UseAppScreenProps) {
   const activity = useNullableActivity();
+  const layerRef = useRef<HTMLDivElement>(null);
 
   const transitionState = activity?.transitionState ?? "enter-done";
 
@@ -36,6 +37,7 @@ export function useAppScreen(props: UseAppScreenProps) {
   return useMemo(
     () => ({
       activity,
+      layerRef,
       stateProps,
       activityProps: elementProps({
         "data-part": "activity",