Merge remote-tracking branch 'origin/main' into tony/future-to-stable-plan

Author: tonyfromundefined

.changeset/add-lifecycle-plugin.md

@@ -1,3 +1,24 @@
+## 2026.04.15
+
+Add lifecyclePlugin and useFocusEffect hook for activity focus/blur lifecycle [`39dbf81`](https://github.com/daangn/stackflow/commit/39dbf81472af06daa5c40da098e232c2fe3b4a92)
+
+- `useFocusEffect(callback)` hook to register per-activity focus/blur callbacks
+- Detection and invocation in plugin `onChanged` (outside React render cycle)
+- `callbackRef` pattern for always-latest callback without `useCallback`
+- Error isolation via `runSafely()` for all user callbacks
+
+Released packages:
+- 📦 [@stackflow/plugin-lifecycle@0.1.0](https://npmjs.com/package/@stackflow/plugin-lifecycle/v/0.1.0)
+
+---
+
+Add README documentation for plugin-lifecycle [`fce2047`](https://github.com/daangn/stackflow/commit/fce204702b876869764076f74246319623fb3e89)
+
+Released packages:
+- 📦 [@stackflow/plugin-lifecycle@0.1.0](https://npmjs.com/package/@stackflow/plugin-lifecycle/v/0.1.0)
+
+---
+
 ## 2026.04.03
 
 Fix intermittent incorrect transition state when `transitionDuration` is set to 0 by ensuring `now >= eventDate` in the initial aggregate call within `dispatchEvent`. [`0160f82`](https://github.com/daangn/stackflow/commit/0160f82738e45932d13715564c4d1da2c4698c18)

docs/components/ChangelogContent.mdx

@@ -0,0 +1,16 @@
+# @stackflow/plugin-lifecycle
+
+## 0.1.0
+
+### Minor Changes
+
+- 39dbf81: Add lifecyclePlugin and useFocusEffect hook for activity focus/blur lifecycle
+
+  - `useFocusEffect(callback)` hook to register per-activity focus/blur callbacks
+  - Detection and invocation in plugin `onChanged` (outside React render cycle)
+  - `callbackRef` pattern for always-latest callback without `useCallback`
+  - Error isolation via `runSafely()` for all user callbacks
+
+### Patch Changes
+
+- fce2047: Add README documentation for plugin-lifecycle

extensions/plugin-lifecycle/CHANGELOG.md

@@ -0,0 +1,63 @@
+# plugin-lifecycle
+
+Stackflow plugin that provides `useFocusEffect`, a hook for running side-effects when an activity gains or loses focus.
+
+## Setup
+
+Add `lifecyclePlugin()` to your stackflow configuration:
+
+```typescript
+import { stackflow } from "@stackflow/react";
+import { lifecyclePlugin } from "@stackflow/plugin-lifecycle";
+
+const { Stack, useFlow } = stackflow({
+  activities: {
+    // ...
+  },
+  plugins: [
+    lifecyclePlugin(),
+    // ... other plugins
+  ],
+});
+```
+
+## Usage
+
+`useFocusEffect` runs a callback when the activity becomes active, and an optional cleanup when it loses focus (blur), unmounts, or the callback reference changes.
+
+```tsx
+import { useFocusEffect } from "@stackflow/plugin-lifecycle";
+
+function ArticleActivity({ articleId }) {
+  useFocusEffect(() => {
+    queryClient.invalidateQueries(["article", articleId]);
+
+    return () => {
+      // optional cleanup on blur
+    };
+  });
+}
+```
+
+To re-run the effect when dependencies change, wrap the callback in `useCallback`:
+
+```tsx
+import { useCallback } from "react";
+import { useFocusEffect } from "@stackflow/plugin-lifecycle";
+
+function ArticleActivity({ articleId }) {
+  useFocusEffect(
+    useCallback(() => {
+      const sub = subscribe(articleId);
+      return () => sub.unsubscribe();
+    }, [articleId]),
+  );
+}
+```
+
+## When to use
+
+- **`useFocusEffect`** — External side-effects that should fire immediately on activity transition: query invalidation, analytics events, cache warming.
+- **`useActiveEffect`** (`@stackflow/react`) — Effects that depend on a settled React tree: DOM manipulation, scroll restoration.
+
+The key difference is timing: `useFocusEffect` runs from the plugin's `onChanged` handler (outside the React render cycle), so it executes immediately without waiting for React's deferred rendering.

extensions/plugin-lifecycle/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@stackflow/plugin-lifecycle",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/daangn/stackflow.git",