[BREAKING CHANGE] future -> stable (#695)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: ENvironmentSet <sbshw1@gmail.com>

Author: 3 people

.changeset/compat-await-push-v2-compat.md

@@ -0,0 +1,5 @@
+---
+"@stackflow/compat-await-push": patch
+---
+
+Remove unused peer dependencies (`@stackflow/core`, `@stackflow/react`, `react`, `@types/react`) — pure Promise-based utility with no React or Stackflow imports.

.changeset/core-config-v2-alignment.md

@@ -0,0 +1,6 @@
+---
+"@stackflow/config": major
+"@stackflow/core": major
+---
+
+Major version bump for ecosystem alignment. No API changes.

.changeset/link-v2-stable-api.md

@@ -0,0 +1,9 @@
+---
+"@stackflow/link": major
+---
+
+Promote Future API to the default entry point and remove the legacy Stable API.
+
+- `@stackflow/link/future` and `@stackflow/link/stable` sub-paths removed. Import from `@stackflow/link` directly.
+- `createLinkComponent()` removed. Use `import { Link } from "@stackflow/link"` directly.
+- `LinkProps.urlPatternOptions` removed. Link URL generation now uses `config.historySync.urlPatternOptions`.

.changeset/react-v2-stable-api.md

@@ -0,0 +1,16 @@
+---
+"@stackflow/react": major
+---
+
+Promote Future API to the default entry point and remove the legacy Stable API.
+
+- `@stackflow/react/future` and `@stackflow/react/stable` sub-paths removed. Import from `@stackflow/react` directly.
+- `stackflow()` signature changed from `{ activities, transitionDuration }` to `{ config, components }`. Use `defineConfig()` from `@stackflow/config` for activity and route definitions.
+- `useActions()` removed in favor of direct `useFlow()` imports, and `useStepActions()` removed in favor of direct `useStepFlow()` imports.
+- `useActiveEffect()`, `useEnterDoneEffect()`, and `useStep()` are no longer exported from the default API.
+- Step actions moved from `stackflow().actions` to the separate `stackflow().stepActions` object, with renamed methods: `stepPush` -> `pushStep`, `stepReplace` -> `replaceStep`, and `stepPop` -> `popStep`.
+- `stackflow()` no longer returns the `activities` field, `useFlow`, `useStepFlow`, `addActivity`, or `addPlugin`. Hooks are now direct imports and activities are defined in `@stackflow/config`.
+- `stackflow().actions` no longer exposes `getStack()` or `dispatchEvent()`; it now exposes only `push`, `replace`, and `pop`.
+- `__internal__` directory removed; shared utilities are inlined into the main source.
+- New default exports: `useLoaderData()`, `useConfig()`, `usePrepare()`, `lazy()`, and `structuredActivityComponent()`.
+- Activity params now use `declare module "@stackflow/config" { interface Register { ... } }` instead of component props inference.

.pnp.cjs

@@ -130,33 +130,51 @@ Plugins can hook into various lifecycle events:
 
 ## Common Tasks
 
-### Adding a New Activity
+### Setting Up Navigation
 ```typescript
-export const { Stack, useFlow } = stackflow({
-  transitionDuration: 350,
+import { stackflow } from "@stackflow/react";
+
+export const { Stack, actions } = stackflow({
+  config,
+  components: {
+    Main,
+    Article,
+  },
   plugins: [
     basicRendererPlugin(),
     basicUIPlugin({
       theme: "cupertino",
     }),
+    historySyncPlugin({
+      config,
+      fallbackActivity: () => "Main",
+    }),
   ],
-  activities: {
-    MyActivity,
-  },
 });
 ```
 
-### Navigation
+### Defining an Activity
 ```tsx
-const MyActivity: ActivityComponentType = () => {
+import type { ActivityComponentType } from "@stackflow/react";
+import { useFlow } from "@stackflow/react";
+
+declare module "@stackflow/config" {
+  interface Register {
+    MyActivity: {
+      title: string;
+    };
+  }
+}
+
+const MyActivity: ActivityComponentType<"MyActivity"> = () => {
   const { push } = useFlow();
- 
+
   const onClick = () => {
     push("Article", {
       title: "Hello",
     });
   };
- 
+
   return (
     <AppScreen appBar={{ title: "My Activity" }}>
       <div>
@@ -188,17 +206,15 @@ stackflow({
 });
 ```
 
-## Future API (Stackflow 2.0 Preview)
-
-The Future API (`@stackflow/react/future`) is a preview of Stackflow 2.0 that optimizes initial loading performance through better separation of concerns. Key improvements:
+## API Design
 
-- **Config-first approach**: Activities and routes defined in `@stackflow/config` using `defineConfig()`, with React components injected separately
-- **Direct imports**: Hooks (`useFlow`, `useStepFlow`) and `<Link>` component imported directly without factory functions
-- **Loader API**: Built-in data loading without React dependencies for better performance
-- **API Pipelining**: Parallel loading of API data and React app initialization
-- **Enhanced type safety**: Types inferred from config rather than component props
+`@stackflow/react` uses a config-first approach for optimal loading performance:
 
-The Future API maintains compatibility with existing code while preparing for Stackflow 2.0. Routes are now declared in the config file alongside activities, and the plugin system has been streamlined to work with the centralized configuration.
+- **Config-first approach**: Activities and routes defined in `@stackflow/config` using `defineConfig()`, with React components injected separately via `stackflow()`
+- **Direct imports**: Hooks (`useFlow`, `useStepFlow`) and `<Link>` component imported directly from `@stackflow/react`
+- **Loader API**: Built-in data loading via `useLoaderData` without React dependencies for better performance
+- **Lazy loading**: Code splitting via `lazy()` for activity components
+- **Enhanced type safety**: Types inferred from config via `declare module "@stackflow/config"` register pattern
 
 ## Build System
 

AGENTS.md

@@ -35,19 +35,34 @@ So, what advantages does **Stackflow** have compared to the existing navigation
 ## Getting Started
 
 ```bash
-$ yarn add @stackflow/core @stackflow/react
+$ yarn add @stackflow/config @stackflow/core @stackflow/react
 ```
 
 ```tsx
-import ReactDOM from 'react-dom'
-
-import { stackflow } from '@stackflow/react';
+import ReactDOM from "react-dom";
+import { defineConfig } from "@stackflow/config";
+import { stackflow } from "@stackflow/react";
+import MyActivity from "./MyActivity";
+
+const config = defineConfig({
+  activities: [
+    {
+      name: "MyActivity",
+    },
+  ],
+  initialActivity: () => "MyActivity",
+  transitionDuration: 350,
+});
 
-const { Stack, useFlow } = stackflow({
-  // ...
+const { Stack } = stackflow({
+  config,
+  components: {
+    MyActivity,
+  },
+  plugins: [],
 });
 
-const App: React.FC = () => {
+const App = () => {
   return (
     <Stack />
   );

README.md

@@ -32,15 +32,12 @@
   "dependencies": {
     "@seed-design/design-token": "^1.0.3",
     "@seed-design/stylesheet": "^1.0.4",
-    "@stackflow/compat-await-push": "^1.1.13",
     "@stackflow/config": "^1.2.0",
     "@stackflow/core": "^1.1.0",
     "@stackflow/link": "^1.5.0",
     "@stackflow/plugin-basic-ui": "^1.9.2",
     "@stackflow/plugin-devtools": "^0.1.11",
     "@stackflow/plugin-history-sync": "^1.7.0",
-    "@stackflow/plugin-map-initial-activity": "^1.0.11",
-    "@stackflow/plugin-preload": "^1.4.3",
     "@stackflow/plugin-renderer-basic": "^1.1.13",
     "@stackflow/plugin-stack-depth-change": "^1.1.5",
     "@stackflow/react": "^1.4.0",

demo/package.json

@@ -2,7 +2,7 @@ import {
   content,
   useActivityParams,
   useLoaderData,
-} from "@stackflow/react/future";
+} from "@stackflow/react";
 import { LazyLoadImage } from "react-lazy-load-image-component";
 import ArticleCard from "../../components/ArticleCard";
 import ArticleProfile from "../../components/ArticleProfile";

demo/src/activities/Article/Article.content.tsx

@@ -1,4 +1,4 @@
-import { layout } from "@stackflow/react/future";
+import { layout } from "@stackflow/react";
 import Layout from "../../components/Layout";
 
 const ArticleLayout = layout<"Article">(({ params: { title }, children }) => {