@finesoft/create-app 0.1.27 → 0.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finesoft/create-app",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Scaffold a new Finesoft Front project",
   "license": "MIT",
   "bin": {

package/templates/react/package.json

@@ -8,7 +8,7 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.2.0",
+        "@finesoft/front": "^0.4.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0"
     },

package/templates/react-minimal/package.json

@@ -8,7 +8,7 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.2.0",
+        "@finesoft/front": "^0.4.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0"
     },

package/templates/react-minimal/src/App.tsx

@@ -1,22 +1,108 @@
-import type { Action, BasePage } from "@finesoft/front";
+import {
+    isStackNode,
+    isTabsNode,
+    type AppHandle,
+    type NavigationHandle,
+    type NavigationSnapshot,
+} from "@finesoft/front";
+import { useEffect, useState } from "react";
 
-interface AppProps {
-    page?: BasePage | null;
-    loading?: boolean;
-    onAction?: (action: Action) => void;
+/** name 全局切片的极小外部 store 接口（main 创建并注入；App 只读它 + 订阅）。 */
+export interface NameStore {
+    get(): string;
+    set(value: string): void;
+    subscribe(listener: () => void): () => void;
 }
 
-export default function App({ page, loading = false }: AppProps) {
-    if (loading)
-        return (
-            <main style={{ padding: "2rem", textAlign: "center", color: "#999" }}>Loading…</main>
-        );
-    if (!page) return null;
+export interface AppProps {
+    /** 首屏快照：SSR 与客户端 hydrate 时一致（URL 推导，tree 相同）→ 无水合失配。 */
+    initialSnapshot: NavigationSnapshot | null;
+    /** 导航 handle（客户端有；SSR 无）。提供后订阅 snapshot 变更驱动重渲。 */
+    nav?: NavigationHandle;
+    /** 框架统一句柄（selectTab / pop / save）。SSR 无（渲染不依赖，仅事件处理用）。 */
+    controller?: AppHandle;
+    /** name 切片 store（客户端注入；SSR 无 → name 恒 ""）。 */
+    nameStore?: NameStore;
+}
+
+const TAB_LABELS: Record<string, string> = { home: "Feed", notes: "Notes" };
+
+export default function App({ initialSnapshot, nav, controller, nameStore }: AppProps) {
+    // 首渲用 initialSnapshot（= SSR 快照，tree 一致）→ 水合 DOM 一致；effect 仅客户端跑，订阅后续提交。
+    const [snapshot, setSnapshot] = useState(initialSnapshot);
+    useEffect(() => {
+        if (!nav) return;
+        setSnapshot(nav.getSnapshot()); // 追平 render→effect 间隙可能的提交
+        return nav.subscribe(setSnapshot);
+    }, [nav]);
+
+    // name 恒 "" 首渲（SSR + 水合一致）；会话恢复在水合后经 store 落，订阅驱动重渲。
+    const [name, setName] = useState("");
+    useEffect(() => {
+        if (!nameStore) return;
+        setName(nameStore.get());
+        return nameStore.subscribe(() => setName(nameStore.get()));
+    }, [nameStore]);
+
+    const tree = snapshot?.tree ?? null;
+    const tabBar = tree && isTabsNode(tree) ? { order: tree.order, active: tree.active } : null;
+    const branch = tree && isTabsNode(tree) ? tree.branches[tree.active] : null;
+    const canGoBack = !!branch && isStackNode(branch) && branch.entries.length > 1;
 
     return (
-        <main style={{ padding: "1rem" }}>
-            <h1>{page.title}</h1>
-            <p>{page.description}</p>
-        </main>
+        <div
+            style={{
+                maxWidth: "32rem",
+                margin: "0 auto",
+                padding: "1rem",
+                fontFamily: "system-ui",
+            }}
+        >
+            {/* 全局切片：名字 */}
+            <header
+                style={{
+                    display: "flex",
+                    gap: "0.5rem",
+                    alignItems: "center",
+                    marginBottom: "1rem",
+                }}
+            >
+                <label style={{ flex: 1 }}>
+                    Your name (global):
+                    <input
+                        value={name}
+                        placeholder="anon"
+                        onChange={(e) => {
+                            setName(e.target.value);
+                            nameStore?.set(e.target.value);
+                        }}
+                        onBlur={() => void controller?.save()}
+                    />
+                </label>
+                {name && <span>👋 {name}</span>}
+            </header>
+
+            {/* TabView */}
+            {tabBar && (
+                <nav style={{ display: "flex", gap: "0.5rem", marginBottom: "1rem" }}>
+                    {tabBar.order.map((key) => (
+                        <button
+                            key={key}
+                            style={{ fontWeight: key === tabBar.active ? 700 : 400 }}
+                            aria-current={key === tabBar.active}
+                            onClick={() => void controller?.selectTab(key)}
+                        >
+                            {TAB_LABELS[key] ?? key}
+                        </button>
+                    ))}
+                </nav>
+            )}
+
+            {canGoBack && (
+                <button style={{ marginBottom: "0.5rem" }} onClick={() => void controller?.pop()}>
+                    ← Back
+                </button>
+            )}
+        </div>
     );
 }

package/templates/react-minimal/src/bootstrap.ts

@@ -1,6 +1,39 @@
-import { type Framework, defineRoutes } from "@finesoft/front";
+import { Framework, defineNavigation, defineRoutes, leaf, stack, tabs } from "@finesoft/front";
+import { DetailController } from "./lib/controllers/detail";
 import { HomeController } from "./lib/controllers/home";
+import { NotesController } from "./lib/controllers/notes";
 
+/**
+ * 同一份 bootstrap 在浏览器与服务器都会执行：注册 controllers + 路由。
+ * 路由让 URL 能 resolve（SSR 首屏 / codec / 扁平回退都需要）。
+ */
 export function bootstrap(framework: Framework): void {
-    defineRoutes(framework, [{ path: "/", intentId: "home", controller: new HomeController() }]);
+    defineRoutes(framework, [
+        { path: "/", intentId: "home", controller: new HomeController() },
+        { path: "/item/:id", intentId: "detail", controller: new DetailController() },
+        { path: "/notes", intentId: "notes", controller: new NotesController() },
+    ]);
 }
+
+/**
+ * 结构化导航：一个 TabView（Home / Notes），每个 tab 是一个 NavigationStack。
+ * - Home 栈可 push 到 detail（栈深 +1），返回 pop（栈深 -1）。
+ * - 切 tab 保活另一分支的栈深与作用域状态（对标 SwiftUI TabView）。
+ *
+ * `initial` 用 **URL→树 工厂**（而非静态树）：这样深链 / 刷新 `/item/2` 能重建出
+ * 「Home 栈压着 detail」的结构，active-leaf codec 也把它回写成 `/item/2`，刷新不再跳回 `/`。
+ * （静态树会忽略 URL、永远从 home 起，刷新被改回 `/`。）
+ */
+export const navigation = defineNavigation({
+    initial: (url) => {
+        const path = url.split("?")[0].split("#")[0];
+        const detail = /^\/item\/(.+)$/.exec(path);
+        const home = detail
+            ? stack([leaf("home"), leaf("detail", { id: detail[1] })])
+            : stack(leaf("home"));
+        return tabs({
+            active: path === "/notes" ? "notes" : "home",
+            branches: { home, notes: stack(leaf("notes")) },
+        });
+    },
+});

package/templates/react-minimal/src/lib/controllers/detail.ts

@@ -0,0 +1,22 @@
+import { BaseController, type BasePage } from "@finesoft/front";
+
+/** Detail 页面：由 push("detail", { id }) 进入；id 进 params。 */
+export interface DetailPage extends BasePage {
+    readonly itemId: string;
+}
+
+export class DetailController extends BaseController<{ id?: string }, DetailPage> {
+    readonly intentId = "detail";
+
+    execute(params: { id?: string }): DetailPage {
+        const id = params.id ?? "?";
+        return {
+            id: `detail-${id}`,
+            pageType: "detail",
+            url: `/item/${id}`,
+            title: `Item ${id}`,
+            description: "A pushed detail screen. Its scoped note is lost once you pop it.",
+            itemId: id,
+        };
+    }
+}

package/templates/react-minimal/src/lib/controllers/home.ts

@@ -1,14 +1,33 @@
 import { BaseController, type BasePage } from "@finesoft/front";
 
-export class HomeController extends BaseController<Record<string, string>, BasePage> {
+/** 一个 feed 项。 */
+export interface FeedItem {
+    readonly id: string;
+    readonly title: string;
+}
+
+/** Home（feed）页面：携带可 push 进 detail 的列表项。 */
+export interface FeedPage extends BasePage {
+    readonly items: readonly FeedItem[];
+}
+
+const ITEMS: readonly FeedItem[] = [
+    { id: "1", title: "Structured navigation" },
+    { id: "2", title: "Session restoration" },
+    { id: "3", title: "Navigation-scoped state" },
+];
+
+export class HomeController extends BaseController<Record<string, string>, FeedPage> {
     readonly intentId = "home";
 
-    execute(): BasePage {
+    execute(): FeedPage {
         return {
             id: "home",
             pageType: "home",
-            title: "Home",
-            description: "Welcome to Finesoft Front",
+            url: "/",
+            title: "Feed",
+            description: "Tap an item to push a detail screen.",
+            items: ITEMS,
         };
     }
 }

package/templates/react-minimal/src/lib/controllers/notes.ts

@@ -0,0 +1,16 @@
+import { BaseController, type BasePage } from "@finesoft/front";
+
+/** Notes 页面：第二个 tab，演示切 tab 保活该分支的作用域状态。 */
+export class NotesController extends BaseController<Record<string, string>, BasePage> {
+    readonly intentId = "notes";
+
+    execute(): BasePage {
+        return {
+            id: "notes",
+            pageType: "notes",
+            url: "/notes",
+            title: "Notes",
+            description: "This textarea is navigation-scoped — switch tabs and it survives.",
+        };
+    }
+}

package/templates/react-minimal/src/main.tsx

@@ -1,44 +1,99 @@
-import { startBrowserApp, type Action, type BasePage, type Framework } from "@finesoft/front";
-import { createRoot } from "react-dom/client";
-import App from "./App";
-import { bootstrap } from "./bootstrap";
+import {
+    resolveIslandsShell,
+    startBrowserApp,
+    type AppHandle,
+    type BasePage,
+    type MountEntry,
+    type SessionStateProvider,
+} from "@finesoft/front";
+import type { ComponentType } from "react";
+import { flushSync } from "react-dom";
+import { createRoot, hydrateRoot } from "react-dom/client";
+import App, { type NameStore } from "./App";
+import { bootstrap, navigation } from "./bootstrap";
+import DetailView from "./views/DetailView";
+import HomeView from "./views/HomeView";
+import NotesView from "./views/NotesView";
 
-void startBrowserApp({
-    bootstrap,
-    mountId: "app",
-    mount: (target: HTMLElement, { framework }: { framework: Framework }) => {
-        let root: ReturnType<typeof createRoot> | null = null;
-        let currentPage: BasePage | null = null;
+/** name 全局切片的极小外部 store —— React 无内建响应式，跨组件共享需显式 store（mount 前建好交给 provider + App）。 */
+function createNameStore(): NameStore {
+    let value = "";
+    const listeners = new Set<() => void>();
+    return {
+        get: () => value,
+        set: (v) => {
+            value = v;
+            listeners.forEach((l) => l());
+        },
+        subscribe: (l) => {
+            listeners.add(l);
+            return () => listeners.delete(l);
+        },
+    };
+}
+const nameStore = createNameStore();
+
+/** 全局切片（app-wide）：用户名字 —— 跨 tab、跨重载都在（对标 SwiftUI @SceneStorage）。 */
+const profileProvider: SessionStateProvider = {
+    key: "profile",
+    capture: () => ({ name: nameStore.get() }),
+    restore: (data) => nameStore.set((data as { name?: string }).name ?? ""),
+};
+
+/** islands 闭包引用：mount 回调赋值，islands(mount 后挂)读时已就绪。 */
+let controller: AppHandle | undefined;
 
-        function render(page: BasePage | null, loading: boolean) {
-            const handleAction = (action: Action) => {
-                void framework.perform(action);
-            };
-            if (!root) root = createRoot(target);
-            root.render(<App page={page} loading={loading} onAction={handleAction} />);
-        }
+/** intent → 视图组件。islands 按 entry 挂为独立 React root。 */
+const VIEWS: Record<string, ComponentType<{ page: BasePage; controller?: AppHandle }>> = {
+    home: HomeView,
+    detail: DetailView,
+    notes: NotesView,
+};
 
-        return ({
-            page,
-            isFirstPage,
-        }: {
-            page: Promise<BasePage> | BasePage;
-            isFirstPage?: boolean;
-        }) => {
-            if (page instanceof Promise) {
-                if (!isFirstPage) render(currentPage, true);
-                void page.then((p) => {
-                    currentPage = p;
-                    render(currentPage, false);
-                });
-            } else {
-                currentPage = page;
-                render(currentPage, false);
-            }
-        };
+const mountEntry: MountEntry = (entry, container) => {
+    const View = VIEWS[entry.intent] ?? HomeView;
+    const element = <View page={entry.page} controller={controller} />;
+    // 首屏 island 已由 SSR 渲入容器（编排器收养并置 hydrate:true）→ 水合；否则新建。
+    if (entry.hydrate) {
+        const root = hydrateRoot(container, element);
+        return { unmount: () => root.unmount() };
+    }
+    const root = createRoot(container);
+    // flushSync 强制同步提交：domRestore 在 fs:enter 后用 rAF 回填 data-restore-root 字段，
+    // 而 React 的 root.render() 默认异步提交 DOM，rAF 会赢得竞态、字段元素尚不存在 → 回填扑空
+    // （从根路径恢复到深层 URL 时，该 island 是客户端新挂、非 SSR，必踩）。同步提交贴合 domRestore
+    // 假设的「挂载即 DOM 就绪」契约（Vue/Svelte 的 .mount() 天然同步满足）。
+    flushSync(() => root.render(element));
+    return { unmount: () => root.unmount() };
+};
+
+void startBrowserApp({
+    bootstrap,
+    mount(target, ctx) {
+        controller = ctx.app; // islands(mount 后挂)与 chrome 共用
+        // 方案 C：chrome 挂到 sibling chrome-root（不含 outlet）；outlet 由框架编排器独占。
+        const { chromeRoot, hydrate } = resolveIslandsShell(target);
+        const initialSnapshot = ctx.navigation?.getSnapshot() ?? null;
+        const element = (
+            <App
+                initialSnapshot={initialSnapshot}
+                nav={ctx.navigation}
+                controller={ctx.app}
+                nameStore={nameStore}
+            />
+        );
+        if (hydrate) hydrateRoot(chromeRoot, element);
+        else createRoot(chromeRoot).render(element);
+        return () => undefined;
     },
     callbacks: {
         onNavigate() {},
         onModal() {},
     },
+    // 结构化导航 + islands：每屏 per-entry 挂为独立 root、保活。
+    navigation: { ...navigation.toBrowserConfig(), mountEntry },
+    // 重载 DOM 自动恢复：data-restore-root 内字段/滚动自动捕获回填。
+    domRestore: true,
+    // 会话恢复：注册全局切片 provider；导航位置 + 作用域状态由框架自动捕获。
+    session: { providers: [profileProvider] },
 });

package/templates/react-minimal/src/ssr.tsx

@@ -1,25 +1,51 @@
-import { createSSRRender, serializeServerData } from "@finesoft/front";
+import {
+    createSSRNavigationRender,
+    renderIslandsHtml,
+    serializeServerData,
+    type BasePage,
+    type ResolvedEntry,
+} from "@finesoft/front";
+import type { ComponentType } from "react";
 import { renderToString } from "react-dom/server";
 import App from "./App";
-import { bootstrap } from "./bootstrap";
+import { bootstrap, navigation } from "./bootstrap";
+import DetailView from "./views/DetailView";
+import HomeView from "./views/HomeView";
+import NotesView from "./views/NotesView";
 
-export const render = createSSRRender({
+const VIEWS: Record<string, ComponentType<{ page: BasePage }>> = {
+    home: HomeView,
+    detail: DetailView,
+    notes: NotesView,
+};
+
+/**
+ * islands 架构 SSR（方案 C）：
+ * - chrome（App，header + tabbar）渲进 `<div data-fs-chrome>`。
+ * - 可见 island 内容由 `renderIslandsHtml` 渲进 sibling `<main data-fs-outlet>`，客户端按 key 收养水合。
+ *
+ * chrome 水合 props parity：客户端 mount 时 navigation.getSnapshot() 即此 URL 推导 snapshot
+ * （tree 一致）→ chrome 水合无失配，且 nav bar 首屏即被 SSR 渲出。name 仍默认 ""（会话恢复在
+ * mount 后、水合后才生效）。nav/controller/nameStore 仅事件与订阅用，不影响 SSR DOM，可省。
+ */
+export const render = createSSRNavigationRender({
     bootstrap,
     getErrorPage(status, message) {
-        return {
-            id: "error",
-            pageType: "error",
-            title: `Error ${status}`,
-            description: message,
-        };
+        return { id: "error", pageType: "error", title: `Error ${status}`, description: message };
     },
-    renderApp(page, _framework) {
+    async renderApp(page, _framework, snapshot) {
+        const chromeHtml = renderToString(<App initialSnapshot={snapshot} />);
+        const islandsHtml = await renderIslandsHtml(snapshot, (entry: ResolvedEntry) => {
+            const View = VIEWS[entry.intent] ?? HomeView;
+            return renderToString(<View page={entry.page} />);
+        });
         return {
-            html: renderToString(<App page={page} />),
+            html: `<div data-fs-chrome>${chromeHtml}</div><main data-fs-outlet>${islandsHtml}</main>`,
             head: `<title>${page.title}</title>`,
             css: "",
         };
     },
+    navigation: navigation.toSSRDefinition(),
 });
 
 export { serializeServerData };

package/templates/react-minimal/src/views/DetailView.tsx

@@ -0,0 +1,28 @@
+import type { BasePage } from "@finesoft/front";
+
+/**
+ * Detail：由 push("detail", { id }) 进入。
+ *
+ * 零样板保活：标一个 data-restore-root，里面的裸 <input>（非受控）即自动：
+ * - in-session：push 走、pop 回来值还在（islands 保活，实例没销毁）
+ * - 重载：sessionStorage 回填（domRestore），合成事件驱动可能的受控绑定
+ * 注意必须用**非受控** input（无 value/onChange）——否则 React 会盖掉 domRestore 的命令式写值。
+ */
+export default function DetailView({ page }: { page: BasePage }) {
+    return (
+        <section>
+            <h1 style={{ margin: "0 0 0.25rem" }}>{page.title}</h1>
+            <p style={{ color: "#666", margin: "0 0 1rem" }}>{page.description}</p>
+            <div data-restore-root>
+                <label style={{ display: "block", marginTop: "1rem" }}>
+                    Draft note for this screen:
+                    <input
+                        name="note"
+                        placeholder="kept while alive; restored on reload"
+                        style={{ width: "100%" }}
+                    />
+                </label>
+            </div>
+        </section>
+    );
+}

package/templates/react-minimal/src/views/HomeView.tsx

@@ -0,0 +1,27 @@
+import type { AppHandle, BasePage } from "@finesoft/front";
+import type { FeedPage } from "../lib/controllers/home";
+
+/** Home（feed）：列表项点击 push 进 detail。 */
+export default function HomeView({ page, controller }: { page: BasePage; controller?: AppHandle }) {
+    const feed = page.pageType === "home" ? (page as FeedPage) : null;
+    return (
+        <section>
+            <h1 style={{ margin: "0 0 0.25rem" }}>{page.title}</h1>
+            <p style={{ color: "#666", margin: "0 0 1rem" }}>{page.description}</p>
+            {feed && (
+                <ul style={{ listStyle: "none", padding: 0, display: "grid", gap: "0.5rem" }}>
+                    {feed.items.map((item) => (
+                        <li key={item.id}>
+                            <button
+                                style={{ width: "100%", textAlign: "left" }}
+                                onClick={() => void controller?.push("detail", { id: item.id })}
+                            >
+                                {item.title} →
+                            </button>
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </section>
+    );
+}

package/templates/react-minimal/src/views/NotesView.tsx

@@ -0,0 +1,11 @@
+import type { BasePage } from "@finesoft/front";
+
+/** Notes：第二个 tab，纯展示（切 tab 保活由 islands 负责）。 */
+export default function NotesView({ page }: { page: BasePage }) {
+    return (
+        <section>
+            <h1 style={{ margin: "0 0 0.25rem" }}>{page.title}</h1>
+            <p style={{ color: "#666", margin: "0 0 1rem" }}>{page.description}</p>
+        </section>
+    );
+}

package/templates/svelte/package.json

@@ -8,7 +8,7 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.2.0",
+        "@finesoft/front": "^0.4.0",
         "svelte": "^5.0.0"
     },
     "devDependencies": {

package/templates/svelte-minimal/package.json

@@ -8,7 +8,7 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.2.0",
+        "@finesoft/front": "^0.4.0",
         "svelte": "^5.0.0"
     },
     "devDependencies": {

package/templates/vue/package.json

@@ -8,7 +8,7 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.2.0",
+        "@finesoft/front": "^0.4.0",
         "vue": "^3.5.0"
     },
     "devDependencies": {

package/templates/vue-minimal/package.json

@@ -8,7 +8,7 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.2.0",
+        "@finesoft/front": "^0.4.0",
         "vue": "^3.5.0"
     },
     "devDependencies": {

package/templates/vue-minimal/src/App.vue

@@ -1,21 +1,62 @@
 <script setup lang="ts">
-import type { Action, BasePage } from "@finesoft/front";
+import { isStackNode, isTabsNode } from "@finesoft/front";
 import { computed } from "vue";
-import Home from "./pages/Home.vue";
+import type { AppController, AppState } from "./main";
 
-const { state, page: ssrPage } = defineProps<{
-    state?: { page: BasePage | null; loading: boolean };
-    page?: BasePage;
-    onAction?: (action: Action) => void;
-}>();
+const { state, controller } = defineProps<{ state?: AppState; controller?: AppController }>();
 
-const currentPage = computed(() => state?.page ?? ssrPage ?? null);
-const loading = computed(() => state?.loading ?? false);
+const tree = computed(() => state?.snapshot?.tree ?? null);
+
+/** Tab bar（tree 为 tabs 节点时）。 */
+const tabs = computed(() => {
+    const t = tree.value;
+    return t && isTabsNode(t) ? { order: t.order, active: t.active } : null;
+});
+const tabLabels: Record<string, string> = { home: "Feed", notes: "Notes" };
+
+/** 激活 tab 的栈深 > 1 → 可返回。 */
+const canGoBack = computed(() => {
+    const t = tree.value;
+    if (!t || !isTabsNode(t)) return false;
+    const branch = t.branches[t.active];
+    return !!branch && isStackNode(branch) && branch.entries.length > 1;
+});
+
+/** 全局切片：名字（跨 tab / 跨重载）。 */
+const name = computed({
+    get: () => state?.name ?? "",
+    set: (v) => {
+        if (state) state.name = v;
+    },
+});
 </script>
 
 <template>
-    <main style="padding: 1rem">
-        <p v-if="loading" style="text-align: center; color: #999">Loading…</p>
-        <Home v-else-if="currentPage" :page="currentPage" />
-    </main>
+    <div style="max-width: 32rem; margin: 0 auto; padding: 1rem; font-family: system-ui">
+        <!-- 全局切片：名字 -->
+        <header style="display: flex; gap: 0.5rem; align-items: center; margin-bottom: 1rem">
+            <label v-if="state" style="flex: 1">
+                Your name (global):
+                <input v-model="name" placeholder="anon" @blur="controller?.save()" />
+            </label>
+            <span v-if="name">👋 {{ name }}</span>
+        </header>
+
+        <!-- TabView -->
+        <nav v-if="tabs" style="display: flex; gap: 0.5rem; margin-bottom: 1rem">
+            <button
+                v-for="key in tabs.order"
+                :key="key"
+                :style="{ fontWeight: key === tabs.active ? '700' : '400' }"
+                :aria-current="key === tabs.active"
+                @click="controller?.selectTab(key)"
+            >
+                {{ tabLabels[key] ?? key }}
+            </button>
+        </nav>
+
+        <button v-if="canGoBack" style="margin-bottom: 0.5rem" @click="controller?.pop()">
+            ← Back
+        </button>
+    </div>
 </template>

package/templates/vue-minimal/src/bootstrap.ts

@@ -1,6 +1,39 @@
-import { Framework, defineRoutes } from "@finesoft/front";
+import { Framework, defineNavigation, defineRoutes, leaf, stack, tabs } from "@finesoft/front";
+import { DetailController } from "./lib/controllers/detail";
 import { HomeController } from "./lib/controllers/home";
+import { NotesController } from "./lib/controllers/notes";
 
+/**
+ * 同一份 bootstrap 在浏览器与服务器都会执行：注册 controllers + 路由。
+ * 路由让 URL 能 resolve（SSR 首屏 / codec / 扁平回退都需要）。
+ */
 export function bootstrap(framework: Framework): void {
-    defineRoutes(framework, [{ path: "/", intentId: "home", controller: new HomeController() }]);
+    defineRoutes(framework, [
+        { path: "/", intentId: "home", controller: new HomeController() },
+        { path: "/item/:id", intentId: "detail", controller: new DetailController() },
+        { path: "/notes", intentId: "notes", controller: new NotesController() },
+    ]);
 }
+
+/**
+ * 结构化导航：一个 TabView（Home / Notes），每个 tab 是一个 NavigationStack。
+ * - Home 栈可 push 到 detail（栈深 +1），返回 pop（栈深 -1）。
+ * - 切 tab 保活另一分支的栈深与作用域状态（对标 SwiftUI TabView）。
+ *
+ * `initial` 用 **URL→树 工厂**（而非静态树）：这样深链 / 刷新 `/item/2` 能重建出
+ * 「Home 栈压着 detail」的结构，active-leaf codec 也把它回写成 `/item/2`，刷新不再跳回 `/`。
+ * （静态树会忽略 URL、永远从 home 起，刷新被改回 `/`。）
+ */
+export const navigation = defineNavigation({
+    initial: (url) => {
+        const path = url.split("?")[0].split("#")[0];
+        const detail = /^\/item\/(.+)$/.exec(path);
+        const home = detail
+            ? stack([leaf("home"), leaf("detail", { id: detail[1] })])
+            : stack(leaf("home"));
+        return tabs({
+            active: path === "/notes" ? "notes" : "home",
+            branches: { home, notes: stack(leaf("notes")) },
+        });
+    },
+});

package/templates/vue-minimal/src/lib/controllers/detail.ts

@@ -0,0 +1,22 @@
+import { BaseController, type BasePage } from "@finesoft/front";
+
+/** Detail 页面：由 push("detail", { id }) 进入；id 进 params。 */
+export interface DetailPage extends BasePage {
+    readonly itemId: string;
+}
+
+export class DetailController extends BaseController<{ id?: string }, DetailPage> {
+    readonly intentId = "detail";
+
+    execute(params: { id?: string }): DetailPage {
+        const id = params.id ?? "?";
+        return {
+            id: `detail-${id}`,
+            pageType: "detail",
+            url: `/item/${id}`,
+            title: `Item ${id}`,
+            description: "A pushed detail screen. Its scoped note is lost once you pop it.",
+            itemId: id,
+        };
+    }
+}

package/templates/vue-minimal/src/lib/controllers/home.ts

@@ -1,15 +1,33 @@
 import { BaseController, type BasePage } from "@finesoft/front";
 
-export class HomeController extends BaseController<Record<string, string>, BasePage> {
+/** 一个 feed 项。 */
+export interface FeedItem {
+    readonly id: string;
+    readonly title: string;
+}
+
+/** Home（feed）页面：携带可 push 进 detail 的列表项。 */
+export interface FeedPage extends BasePage {
+    readonly items: readonly FeedItem[];
+}
+
+const ITEMS: readonly FeedItem[] = [
+    { id: "1", title: "Structured navigation" },
+    { id: "2", title: "Session restoration" },
+    { id: "3", title: "Navigation-scoped state" },
+];
+
+export class HomeController extends BaseController<Record<string, string>, FeedPage> {
     readonly intentId = "home";
 
-    execute(): BasePage {
+    execute(): FeedPage {
         return {
             id: "home",
             pageType: "home",
             url: "/",
-            title: "Home",
-            description: "Welcome to Finesoft Front",
+            title: "Feed",
+            description: "Tap an item to push a detail screen.",
+            items: ITEMS,
         };
     }
 }

package/templates/vue-minimal/src/lib/controllers/notes.ts

@@ -0,0 +1,16 @@
+import { BaseController, type BasePage } from "@finesoft/front";
+
+/** Notes 页面：第二个 tab，演示切 tab 保活该分支的作用域状态。 */
+export class NotesController extends BaseController<Record<string, string>, BasePage> {
+    readonly intentId = "notes";
+
+    execute(): BasePage {
+        return {
+            id: "notes",
+            pageType: "notes",
+            url: "/notes",
+            title: "Notes",
+            description: "This textarea is navigation-scoped — switch tabs and it survives.",
+        };
+    }
+}

package/templates/vue-minimal/src/main.ts

@@ -1,41 +1,75 @@
-import { startBrowserApp, type Action, type BasePage, type Framework } from "@finesoft/front";
-import { createApp, reactive } from "vue";
+import {
+    resolveIslandsShell,
+    startBrowserApp,
+    type AppHandle,
+    type MountEntry,
+    type NavigationSnapshot,
+    type SessionStateProvider,
+} from "@finesoft/front";
+import { createApp, createSSRApp, markRaw, reactive, type Component } from "vue";
 import App from "./App.vue";
-import { bootstrap } from "./bootstrap";
+import HomeView from "./views/HomeView.vue";
+import DetailView from "./views/DetailView.vue";
+import NotesView from "./views/NotesView.vue";
+import { bootstrap, navigation } from "./bootstrap";
+
+/** 只把要渲染的数据放进 reactive；handle 是带闭包的复杂对象，留在模块作用域不被代理。 */
+export interface AppState {
+    snapshot: NavigationSnapshot | null;
+    name: string;
+}
+export type AppController = AppHandle; // 组件 prop 类型 = 框架统一句柄
+
+const state = reactive<AppState>({ snapshot: null, name: "" });
+
+/** 全局切片（app-wide）：用户名字 —— 跨 tab、跨重载都在（对标 SwiftUI @SceneStorage）。 */
+const profileProvider: SessionStateProvider = {
+    key: "profile",
+    capture: () => ({ name: state.name }),
+    restore: (data) => {
+        state.name = (data as { name?: string }).name ?? "";
+    },
+};
+
+/** islands 闭包引用：mount 回调赋值，islands(mount 后挂)读时已就绪。 */
+let controller: AppHandle | undefined;
+
+/** intent → 视图组件。islands 按 entry 挂为独立 Vue app。 */
+const VIEWS: Record<string, Component> = { home: HomeView, detail: DetailView, notes: NotesView };
+
+const mountEntry: MountEntry = (entry, container) => {
+    const view = VIEWS[entry.intent] ?? HomeView;
+    // 首屏 island 已由 SSR 渲入容器（编排器收养并置 hydrate:true）→ 水合；否则新建。
+    const factory = entry.hydrate ? createSSRApp : createApp;
+    const app = factory(view, { page: entry.page, controller });
+    app.mount(container);
+    return { unmount: () => app.unmount() };
+};
 
 void startBrowserApp({
     bootstrap,
-    mount(target: HTMLElement, { framework }: { framework: Framework }) {
-        const state = reactive<{ page: BasePage | null; loading: boolean }>({
-            page: null,
-            loading: false,
-        });
-        const handleAction = (action: Action) => {
-            void framework.perform(action);
-        };
-        createApp(App, { state, onAction: handleAction }).mount(target);
-
-        return ({
-            page,
-            isFirstPage,
-        }: {
-            page: Promise<BasePage> | BasePage;
-            isFirstPage?: boolean;
-        }) => {
-            if (page instanceof Promise) {
-                if (!isFirstPage) state.loading = true;
-                void page.then((p) => {
-                    state.page = p;
-                    state.loading = false;
-                });
-            } else {
-                state.page = page;
-                state.loading = false;
-            }
-        };
+    mount(target: HTMLElement, ctx) {
+        controller = ctx.app; // islands(mount 后挂)与 chrome 共用
+        const nav = ctx.navigation;
+        if (nav) {
+            state.snapshot = nav.getSnapshot(); // mount 时 tree 已就绪
+            nav.subscribe((s) => (state.snapshot = s));
+        }
+        // 方案 C：chrome 挂到 sibling chrome-root（不含 outlet）；outlet 由框架编排器独占。
+        const { chromeRoot, hydrate } = resolveIslandsShell(target);
+        (hydrate ? createSSRApp : createApp)(App, { state, controller: markRaw(ctx.app!) }).mount(
+            chromeRoot,
+        );
+        return () => undefined;
     },
     callbacks: {
         onNavigate() {},
         onModal() {},
     },
+    // 结构化导航 + islands：每屏 per-entry 挂为独立 root、保活。
+    navigation: { ...navigation.toBrowserConfig(), mountEntry },
+    // 重载 DOM 自动恢复：data-restore-root 内字段/滚动自动捕获回填。
+    domRestore: true,
+    // 会话恢复：注册全局切片 provider；导航位置 + 作用域状态由框架自动捕获。
+    session: { providers: [profileProvider] },
 });

package/templates/vue-minimal/src/ssr.ts

@@ -1,28 +1,50 @@
-import { createSSRRender, serializeServerData } from "@finesoft/front";
-import { createSSRApp } from "vue";
+import {
+    createSSRNavigationRender,
+    renderIslandsHtml,
+    serializeServerData,
+    type ResolvedEntry,
+} from "@finesoft/front";
+import { createSSRApp, type Component } from "vue";
 import { renderToString } from "vue/server-renderer";
 import App from "./App.vue";
-import { bootstrap } from "./bootstrap";
+import HomeView from "./views/HomeView.vue";
+import DetailView from "./views/DetailView.vue";
+import NotesView from "./views/NotesView.vue";
+import { bootstrap, navigation } from "./bootstrap";
 
-export const render = createSSRRender({
+const VIEWS: Record<string, Component> = { home: HomeView, detail: DetailView, notes: NotesView };
+
+/**
+ * islands 架构 SSR（方案 C）：
+ * - chrome（App.vue，header + tabbar）渲进 `<div data-fs-chrome>`。
+ * - 可见 island 内容由 `renderIslandsHtml` 渲进 sibling `<main data-fs-outlet>`，客户端按 key 收养水合。
+ *
+ * chrome 水合 props parity：SSR 必须用与客户端 hydrate 时**相同**的初始 state 渲 App，否则
+ * App.vue 的 `v-if="state"`（name label 等）server/client 不一致 → hydration mismatch。
+ * 客户端 hydrate 时 state = { snapshot: null, name: "" }（onNavigationReady / session 恢复都在
+ * 水合**之后**才填）。controller 仅用于事件处理器（`controller?.`），不影响渲染 DOM，SSR 可省。
+ */
+export const render = createSSRNavigationRender({
     bootstrap,
     getErrorPage(status, message) {
-        return {
-            id: "error",
-            pageType: "error",
-            title: `Error ${status}`,
-            description: message,
-        };
+        return { id: "error", pageType: "error", title: `Error ${status}`, description: message };
     },
-    async renderApp(page, _framework) {
-        const app = createSSRApp(App, { page });
-        const html = await renderToString(app);
+    async renderApp(page, _framework, snapshot) {
+        // 客户端 mount 时 navigation.getSnapshot() 即此 URL 推导 snapshot（tree 一致）→ chrome 水合无失配,
+        // 且 nav bar 首屏即被 SSR 渲出。name 仍默认 ""（会话恢复在 mount 后，水合后才生效）。
+        const chromeHtml = await renderToString(
+            createSSRApp(App, { state: { snapshot, name: "" } }),
+        );
+        const islandsHtml = await renderIslandsHtml(snapshot, (entry: ResolvedEntry) =>
+            renderToString(createSSRApp(VIEWS[entry.intent] ?? HomeView, { page: entry.page })),
+        );
         return {
-            html,
+            html: `<div data-fs-chrome>${chromeHtml}</div><main data-fs-outlet>${islandsHtml}</main>`,
             head: `<title>${page.title}</title>`,
             css: "",
         };
     },
+    navigation: navigation.toSSRDefinition(),
 });
 
 export { serializeServerData };

package/templates/vue-minimal/src/views/DetailView.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import type { BasePage } from "@finesoft/front";
+
+defineProps<{ page: BasePage }>();
+</script>
+
+<template>
+    <section>
+        <h1 style="margin: 0 0 0.25rem">{{ page.title }}</h1>
+        <p style="color: #666; margin: 0 0 1rem">{{ page.description }}</p>
+
+        <!--
+          零样板保活：标一个 data-restore-root，里面的裸 <input> 即自动：
+          - in-session：push 走、pop 回来值还在（islands 保活，实例没销毁）
+          - 重载：sessionStorage 回填（domRestore），合成事件驱动可能的受控绑定
+          对比重构前：需手写 entryKey + watch + getScoped/setScoped —— 现在一行不写。
+        -->
+        <div data-restore-root>
+            <label style="display: block; margin-top: 1rem">
+                Draft note for this screen:
+                <input
+                    name="note"
+                    placeholder="kept while alive; restored on reload"
+                    style="width: 100%"
+                />
+            </label>
+        </div>
+    </section>
+</template>

package/templates/vue-minimal/src/views/HomeView.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { BasePage } from "@finesoft/front";
+import type { FeedPage } from "../lib/controllers/home";
+import type { AppController } from "../main";
+
+const { page, controller } = defineProps<{ page: BasePage; controller?: AppController }>();
+const feed = computed(() => (page.pageType === "home" ? (page as FeedPage) : null));
+</script>
+
+<template>
+    <section>
+        <h1 style="margin: 0 0 0.25rem">{{ page.title }}</h1>
+        <p style="color: #666; margin: 0 0 1rem">{{ page.description }}</p>
+        <ul v-if="feed" style="list-style: none; padding: 0; display: grid; gap: 0.5rem">
+            <li v-for="item in feed.items" :key="item.id">
+                <button
+                    style="width: 100%; text-align: left"
+                    @click="controller?.push('detail', { id: item.id })"
+                >
+                    {{ item.title }} →
+                </button>
+            </li>
+        </ul>
+    </section>
+</template>

package/templates/vue-minimal/src/views/NotesView.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import type { BasePage } from "@finesoft/front";
+
+defineProps<{ page: BasePage }>();
+</script>
+
+<template>
+    <section>
+        <h1 style="margin: 0 0 0.25rem">{{ page.title }}</h1>
+        <p style="color: #666; margin: 0 0 1rem">{{ page.description }}</p>
+    </section>
+</template>

package/templates/vue-minimal/src/pages/Home.vue

@@ -1,12 +0,0 @@
-<script setup lang="ts">
-import type { BasePage } from "@finesoft/front";
-
-defineProps<{ page: BasePage }>();
-</script>
-
-<template>
-    <div>
-        <h1>{{ page.title }}</h1>
-        <p>{{ page.description }}</p>
-    </div>
-</template>