@finesoft/create-app 0.1.34 → 0.1.36

package/templates/react/vite.config.ts

@@ -1,18 +1,14 @@
 import { finesoftFrontViteConfig } from "@finesoft/front";
 import react from "@vitejs/plugin-react";
-import { defineConfig } from "vite-plus";
+import { defineConfig, lazyPlugins } from "vite-plus";
+
+const front = finesoftFrontViteConfig({
+    controllerTypes: { root: import.meta.dirname },
+    ssr: { entry: "src/ssr.ts" },
+    proxies: [{ prefix: "/api", target: "https://jsonplaceholder.typicode.com" }],
+});
 
 export default defineConfig({
-    plugins: [
-        react(),
-        finesoftFrontViteConfig({
-            ssr: { entry: "src/ssr.tsx" },
-            proxies: [
-                {
-                    prefix: "/api",
-                    target: "https://jsonplaceholder.typicode.com",
-                },
-            ],
-        }),
-    ],
+    lint: { options: { typeAware: true, typeCheck: true } },
+    plugins: lazyPlugins(() => [front, react()]),
 });

package/templates/react-minimal/README.md

@@ -0,0 +1,39 @@
+# Finesoft Front minimal application
+
+Feed, detail and Notes demonstrate tabs/stacks, retained drafts, a per-application profile and session restoration. All three native frameworks have the same example.
+
+## Run
+
+Node must satisfy `^22.18.0 || >=24.11.0`. Use Vite+ for tooling.
+
+```sh
+vp install
+vp run dev
+vp run build
+vp run preview
+```
+
+Visit `/`, open a Feed item, enter a detail note, switch to Notes and type a draft. Switch tabs and reload to see both drafts restored. Use Back to remove the detail entry; opening it again starts a fresh draft. Your name is global to this application and is saved on blur.
+
+## Server controller example
+
+`src/lib/controllers/detail.ts` extends `BaseServerController` from `@finesoft/front`. Open `/item/2` and inspect the response header `x-demo-request-method: GET`. Return to Feed and open another item: browser navigation loads the controller remotely using POST, whose response contains `x-demo-request-method: POST`. This demonstrates reading `context.request` and explicitly writing `context.responseHeaders` without adding an authentication policy.
+
+SSR executes the controller directly, and hydration reuses the result. Its implementation stays on the server; `markPublic` selects the data sent to the native view. Home and Notes remain ordinary `BaseController` examples. Route types come from `src/app-definition.ts`; the Vite plugin maintains the generated `Input` type with the appropriate server context.
+
+Keep the configured SSR entry and deploy to a request host such as Node or Worker. Serving only `dist/client` cannot execute this controller. Login state and any credential forwarding remain application-owned.
+
+## Edit
+
+- `src/config.ts`: application identity and persistence namespace.
+- `src/app-definition.ts`: pages, routes, guards and navigation.
+- `src/lib/controllers/` and `src/lib/models/`: page loading and typed public data.
+- `src/pages/`, `src/App.*`, `src/styles.css`: native UI and presentation.
+- `src/views.ts`: the view registry shared by browser and server.
+- `src/main.ts` and `src/ssr.ts`: standard browser and SSR startup.
+
+`src/instance.ts` creates one profile store/provider per mount. For an embedded application, call `mountApplication(target, uniquePersistenceKey, "memory", "/notes")`. The `data-restore-root` fields belong to their page entries.
+
+`src/locales/` contains English and Chinese JSON messages. Set `frameworkConfig.locale` in `src/app-definition.ts` to `en-US` or `zh-Hans` (default), then restart/rebuild. Navigation labels and sample items remain English.
+
+All framework APIs import from `@finesoft/front`. Select the native component with `Outlet("react")`, `Outlet("vue")`, or `Outlet("svelte")`, and pass the same renderer to `useSnapshot`. The plugin maintains `.finesoft/front.d.ts` and the exact TypeScript import mapping; install only the chosen renderer. For standalone TypeScript checks, first run `vp exec finesoft-types`. The project is standalone and requires no sibling templates or private runtime packages.

package/templates/react-minimal/index.html

@@ -6,8 +6,7 @@
         <!--ssr-head-->
     </head>
     <body>
-        <div id="app"><!--ssr-body--></div>
-        <!--ssr-data-->
-        <script type="module" src="/src/main.tsx"></script>
+        <div id="app"><!--ssr-body--><!--ssr-data--></div>
+        <script type="module" src="/src/main.ts"></script>
     </body>
 </html>

package/templates/react-minimal/package.json

@@ -8,15 +8,19 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.5.1",
-        "react": "^19.0.0",
-        "react-dom": "^19.0.0"
+        "@finesoft/front": "^0.5.3",
+        "react": "^19.2.8",
+        "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@types/react": "^19.0.0",
-        "@types/react-dom": "^19.0.0",
-        "@vitejs/plugin-react": "^4.0.0",
-        "vite": "npm:@voidzero-dev/vite-plus-core@0.1.16",
-        "vite-plus": "0.1.24"
+        "@hono/node-server": "^2.1.0",
+        "@types/node": "^22.20.1",
+        "@types/react": "^19.2.18",
+        "@types/react-dom": "^19.2.4",
+        "@vitejs/plugin-react": "^6.0.5",
+        "hono": "^4.13.1",
+        "typescript": "^6.0.3",
+        "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+        "vite-plus": "0.2.8"
     }
 }

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

@@ -1,108 +1,63 @@
-import {
-    isStackNode,
-    isTabsNode,
-    type AppHandle,
-    type NavigationHandle,
-    type NavigationSnapshot,
-} from "@finesoft/front";
-import { useEffect, useState } from "react";
-
-/** name 全局切片的极小外部 store 接口（main 创建并注入；App 只读它 + 订阅）。 */
-export interface NameStore {
-    get(): string;
-    set(value: string): void;
-    subscribe(listener: () => void): () => void;
-}
-
-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 落，订阅驱动重渲。
+import { Outlet as selectOutlet, useSnapshot, type WebAppView } from "@finesoft/front";
+import { useLayoutEffect, useRef, useState } from "react";
+import { TAB_LABELS } from "./lib/navigation";
+import { views } from "./views";
+const Outlet = selectOutlet("react");
+export default function App({ app }: { readonly app: WebAppView }) {
+    const snapshot = useSnapshot("react", app);
+    // Start empty on both server and client; restore the profile after hydration.
     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;
+    const current = useRef(name);
+    current.current = name;
+    useLayoutEffect(() => {
+        return app.session?.register({
+            key: "profile",
+            version: 1,
+            decode: (data) => {
+                if (
+                    !data ||
+                    typeof data !== "object" ||
+                    typeof (data as { name?: unknown }).name !== "string"
+                )
+                    throw Error("invalid-profile-state");
+                return data as { name: string };
+            },
+            capture: () => ({ name: current.current }),
+            restore: (data) => setName(data.name),
+        });
+    }, [app]);
 
     return (
-        <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 }}>
+        <div className="app-chrome">
+            <header className="profile">
+                <label>
                     Your name (global):
                     <input
                         value={name}
                         placeholder="anon"
-                        onChange={(e) => {
-                            setName(e.target.value);
-                            nameStore?.set(e.target.value);
-                        }}
-                        onBlur={() => void controller?.save()}
+                        onChange={(event) => setName(event.target.value)}
+                        onBlur={() => void app.session?.save()}
                     />
                 </label>
                 {name && <span>👋 {name}</span>}
             </header>
-
-            {/* TabView */}
-            {tabBar && (
-                <nav style={{ display: "flex", gap: "0.5rem", marginBottom: "1rem" }}>
-                    {tabBar.order.map((key) => (
+            {snapshot.navigation.tabs && (
+                <nav className="tabs" aria-label="Pages">
+                    {snapshot.navigation.tabs.order.map((key) => (
                         <button
                             key={key}
-                            style={{ fontWeight: key === tabBar.active ? 700 : 400 }}
-                            aria-current={key === tabBar.active}
-                            onClick={() => void controller?.selectTab(key)}
+                            aria-current={key === snapshot.navigation.tabs?.active}
+                            onClick={() => void app.perform({ kind: "selectTab", key: key })}
                         >
                             {TAB_LABELS[key] ?? key}
                         </button>
                     ))}
                 </nav>
             )}
-
-            {canGoBack && (
-                <button style={{ marginBottom: "0.5rem" }} onClick={() => void controller?.pop()}>
-                    ← Back
-                </button>
+            {snapshot.navigation.canGoBack && (
+                <button onClick={() => void app.perform({ kind: "pop" })}>← Back</button>
             )}
+            <Outlet app={app} views={views} />
         </div>
     );
 }

package/templates/react-minimal/src/app-definition.ts

@@ -0,0 +1,48 @@
+import { loadMessages } from "virtual:finesoft-front/i18n-loader";
+import { appId } from "./config";
+import { getErrorPage } from "./lib/controllers/error";
+import {
+    definePage,
+    defineWebApp,
+    stack,
+    tabs,
+    type LeafNode,
+    type RouteMatch,
+} from "@finesoft/front";
+import { DetailController } from "./lib/controllers/detail";
+import { HomeController } from "./lib/controllers/home";
+import { NotesController } from "./lib/controllers/notes";
+export const homePage = definePage({
+    id: "home",
+    create: () => new HomeController(),
+    routes: ["/"],
+});
+export const detailPage = definePage({
+    id: "detail",
+    create: () => new DetailController(),
+    routes: ["/item/:id"],
+});
+export const notesPage = definePage({
+    id: "notes",
+    create: () => new NotesController(),
+    routes: ["/notes"],
+});
+export function createNavigation({ match, target }: { match?: RouteMatch; target?: LeafNode }) {
+    if (!match || !target) return undefined;
+    const home =
+        match.intent.id === "detail" ? stack([homePage.leaf(), target]) : stack(homePage.leaf());
+    return tabs({
+        active: match.intent.id === "notes" ? "notes" : "home",
+        branches: { home, notes: stack(match.intent.id === "notes" ? target : notesPage.leaf()) },
+    });
+}
+
+export const app = defineWebApp({
+    id: appId,
+    loadMessages,
+    configuration: { locale: "zh-Hans" },
+    pages: [homePage, detailPage, notesPage],
+    getErrorPage,
+
+    navigation: createNavigation,
+});

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

@@ -0,0 +1,2 @@
+/** App identity also namespaces persisted browser sessions. */
+export const appId = "react-minimal";

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

@@ -1,22 +1,23 @@
-import { BaseController, type BasePage } from "@finesoft/front";
+import { BaseServerController } from "@finesoft/front";
+import { markPublic } from "@finesoft/front";
+import type { DetailPage } from "../models/page";
+import type { DetailControllerInput as Input } from "../../../.finesoft/controller-types";
 
-/** 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 {
+export class DetailController extends BaseServerController<Input, DetailPage> {
+    execute({ params, context }: Input): 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,
-        };
+        // GET during SSR, POST when browser navigation loads this controller remotely.
+        context.responseHeaders.set("x-demo-request-method", context.request.method);
+        return markPublic(
+            {
+                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,
+            },
+            ["itemId"],
+        );
     }
 }

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

@@ -0,0 +1,15 @@
+import { markPublic } from "@finesoft/front";
+import type { ErrorPage } from "../models/page";
+
+export function getErrorPage(status: number, message: string): ErrorPage {
+    return markPublic(
+        {
+            id: "error",
+            pageType: "error",
+            title: `Error ${status}`,
+            description: message,
+            status,
+        },
+        ["status"],
+    );
+}

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

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

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

@@ -1,10 +1,12 @@
-import { BaseController, type BasePage } from "@finesoft/front";
+import { BaseController, type ControllerInput } from "@finesoft/front";
+import type { NotesPage } from "../models/page";
 
 /** Notes 页面：第二个 tab，演示切 tab 保活该分支的作用域状态。 */
-export class NotesController extends BaseController<Record<string, string>, BasePage> {
-    readonly intentId = "notes";
-
-    execute(): BasePage {
+export class NotesController extends BaseController<
+    ControllerInput<Record<string, string>>,
+    NotesPage
+> {
+    execute(): NotesPage {
         return {
             id: "notes",
             pageType: "notes",

package/templates/react-minimal/src/lib/locale.ts

@@ -0,0 +1,16 @@
+import type { WebAppView } from "@finesoft/front";
+
+/** Both SSR and hydrated views read the translator from their own application. */
+export function getHomeLocale(app?: WebAppView) {
+    const translator = app?.translator;
+    return {
+        lang: app?.locale?.lang ?? "unknown",
+        label: translator?.t("home.localeLabel") ?? "Current locale",
+        badge:
+            translator?.t("home.runtimeBadge") ??
+            "Hydration kept the translator alive on the client.",
+        hint:
+            translator?.t("home.switchHint") ??
+            "Change frameworkConfig.locale in src/app-definition.ts to load another JSON file.",
+    };
+}

package/templates/react-minimal/src/lib/models/page.ts

@@ -0,0 +1,27 @@
+import type { BasePage } from "@finesoft/front";
+
+export interface FeedItem {
+    readonly id: string;
+    readonly title: string;
+}
+
+export interface HomePage extends BasePage {
+    readonly pageType: "home";
+    readonly items: readonly FeedItem[];
+}
+
+export interface DetailPage extends BasePage {
+    readonly pageType: "detail";
+    readonly itemId: string;
+}
+
+export interface NotesPage extends BasePage {
+    readonly pageType: "notes";
+}
+
+export interface ErrorPage extends BasePage {
+    readonly pageType: "error";
+    readonly status: number;
+}
+
+export type AppPage = HomePage | DetailPage | NotesPage | ErrorPage;

package/templates/react-minimal/src/lib/navigation.ts

@@ -0,0 +1,11 @@
+import { isStackNode, isTabsNode, type NavigationSnapshot } from "@finesoft/front";
+
+export const TAB_LABELS: Readonly<Record<string, string>> = { home: "Feed", notes: "Notes" };
+
+/** The renderer supplies each committed snapshot; chrome needs no second subscription. */
+export function getNavigationChrome(snapshot?: NavigationSnapshot) {
+    const tree = snapshot?.tree;
+    const tabs = tree && isTabsNode(tree) ? { order: tree.order, active: tree.active } : null;
+    const branch = tree && isTabsNode(tree) ? tree.branches[tree.active] : null;
+    return { tabs, canGoBack: !!branch && isStackNode(branch) && branch.entries.length > 1 };
+}

package/templates/react-minimal/src/locales/en-US.json

@@ -0,0 +1,5 @@
+{
+    "home.localeLabel": "Current locale",
+    "home.runtimeBadge": "Hydration kept the translator alive on the client.",
+    "home.switchHint": "Change frameworkConfig.locale in src/app-definition.ts to en-US or zh-Hans to load the corresponding JSON file."
+}

package/templates/react-minimal/src/locales/zh-Hans.json

@@ -0,0 +1,5 @@
+{
+    "home.localeLabel": "当前语言",
+    "home.runtimeBadge": "浏览器接管后，翻译器仍然可用。",
+    "home.switchHint": "修改 src/app-definition.ts 中的 frameworkConfig.locale：en-US 为英文，zh-Hans 为中文。"
+}

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

@@ -0,0 +1,43 @@
+import { createBrowserApp } from "@finesoft/front";
+import { createRoot, hydrateRoot } from "react-dom/client";
+import { createElement } from "react";
+import { app } from "./app-definition";
+import { appId } from "./config";
+import App from "./App";
+import "./styles.css";
+
+export async function mountApplication(
+    target: HTMLElement,
+    persistenceKey = appId,
+    history: "browser" | "memory" = "browser",
+    url?: string,
+) {
+    const handle = await createBrowserApp({
+        definition: app,
+        target,
+        history,
+        url,
+        persistenceKey,
+        domRestore: true,
+        session: {},
+    });
+    const root = handle.shouldHydrate
+        ? hydrateRoot(target, createElement(App, { app: handle }))
+        : createRoot(target);
+    if (!handle.shouldHydrate) root.render(createElement(App, { app: handle }));
+    const originalDispose = handle.dispose.bind(handle);
+    let disposal: Promise<void> | undefined;
+    Object.assign(handle, {
+        dispose: () => (disposal ??= originalDispose().finally(() => root.unmount())),
+    });
+    await handle.ready;
+    return handle;
+}
+
+export const started = mountApplication(document.getElementById("app")!);
+
+if (import.meta.hot) {
+    import.meta.hot.dispose(async () => {
+        await (await started).dispose();
+    });
+}

package/templates/react-minimal/src/pages/Detail.tsx

@@ -0,0 +1,20 @@
+import type { DetailPage } from "../lib/models/page";
+
+export default function Detail({ page }: { page: DetailPage }) {
+    return (
+        <section className="page">
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+            {/* The entry owns this draft; data-restore-root also restores it after reload. */}
+            <div className="draft" data-restore-root>
+                <label>
+                    Detail note
+                    <input
+                        name="note"
+                        placeholder="Kept while this screen is alive; lost when popped"
+                    />
+                </label>
+            </div>
+        </section>
+    );
+}

package/templates/react-minimal/src/pages/Home.tsx

@@ -0,0 +1,38 @@
+import type { ViewProps } from "@finesoft/front";
+import type { HomePage } from "../lib/models/page";
+import { getHomeLocale } from "../lib/locale";
+
+export default function Home({
+    page,
+    app,
+}: {
+    page: HomePage;
+} & Pick<ViewProps, "app">) {
+    const locale = getHomeLocale(app);
+    return (
+        <section className="page">
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+            <ul className="feed">
+                {page.items.map((item) => (
+                    <li key={item.id}>
+                        <button
+                            onClick={() =>
+                                void app.perform({ kind: "flow", url: `/item/${item.id}` })
+                            }
+                        >
+                            {item.title}
+                        </button>
+                    </li>
+                ))}
+            </ul>
+            <section className="locale-info" aria-label="Locale">
+                <p>
+                    <strong>{locale.label}:</strong> {locale.lang}
+                </p>
+                <p>{locale.badge}</p>
+                <p>{locale.hint}</p>
+            </section>
+        </section>
+    );
+}

package/templates/react-minimal/src/pages/NotFound.tsx

@@ -0,0 +1,11 @@
+import type { ErrorPage } from "../lib/models/page";
+
+export default function NotFound({ page }: { page: ErrorPage }) {
+    return (
+        <section className="page">
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+            <a href="/">← Go Home</a>
+        </section>
+    );
+}