@finesoft/create-app 0.1.34 → 0.1.35

package/templates/vue/src/pages/Search.vue

@@ -1,33 +1,19 @@
 <script setup lang="ts">
-import type { Action } from "@finesoft/front";
 import ProductCard from "../components/ProductCard.vue";
 import type { SearchPage } from "../lib/models/product";
 
-const { page, onAction } = defineProps<{ page: SearchPage; onAction?: (action: Action) => void }>();
+const { page } = defineProps<{ page: SearchPage }>();
 </script>
 
 <template>
-    <div>
+    <section class="page page-search">
         <h1>{{ page.title }}</h1>
         <p>{{ page.description }}</p>
 
         <div class="results">
-            <ProductCard
-                v-for="item in page.results"
-                :key="item.id"
-                :item="item"
-                :on-action="onAction"
-            />
+            <ProductCard v-for="item in page.results" :key="item.id" :item="item" />
         </div>
 
         <p v-if="page.results.length === 0">No products found.</p>
-    </div>
+    </section>
 </template>
-
-<style scoped>
-.results {
-    display: flex;
-    gap: 1rem;
-    flex-wrap: wrap;
-}
-</style>

package/templates/vue/src/ssr.ts

@@ -1,24 +1,11 @@
-import { createSSRRender, serializeServerData } from "@finesoft/front";
 import { createSSRApp } from "vue";
 import { renderToString } from "vue/server-renderer";
+import { createSSRRender } from "@finesoft/front";
+import { app } from "./app-definition";
 import App from "./App.vue";
-import { bootstrap } from "./bootstrap";
-import { getErrorPage } from "./lib/controllers/error";
 
 export const render = createSSRRender({
-    bootstrap,
-    getErrorPage,
-    async renderApp(page, _framework) {
-        const app = createSSRApp(App, { page });
-        const html = await renderToString(app);
-        return {
-            html,
-            head: `<title>${page.title}</title><meta name="description" content="${
-                page.description ?? ""
-            }">`,
-            css: "",
-        };
-    },
+    definition: app,
+    render: (app) => renderToString(createSSRApp(App, { app })),
 });
-
-export { serializeServerData };
+export { serializeServerData } from "@finesoft/front";

package/templates/vue/src/styles.css

@@ -0,0 +1,71 @@
+:root {
+    color: #333;
+    font-family: Arial, sans-serif;
+}
+
+body {
+    margin: 0;
+}
+
+.app-shell {
+    min-height: 100vh;
+}
+
+.navigation {
+    display: flex;
+    gap: 1rem;
+    padding: 1rem;
+    border-bottom: 1px solid #eee;
+}
+
+.navigation-link {
+    color: #333;
+    text-decoration: none;
+}
+
+.navigation-link:hover,
+.navigation-link.active {
+    color: #007bff;
+}
+
+.navigation-link.active {
+    font-weight: bold;
+}
+
+.app-main {
+    padding: 1rem;
+}
+
+.loading {
+    padding: 2rem;
+    color: #999;
+    text-align: center;
+}
+
+.shelf,
+.results {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1rem;
+}
+
+.shelf.horizontal {
+    overflow-x: auto;
+    flex-wrap: nowrap;
+}
+
+.product-card {
+    min-width: 200px;
+    padding: 1rem;
+    border: 1px solid #eee;
+    border-radius: 8px;
+}
+
+.price {
+    color: #007bff;
+    font-weight: bold;
+}
+
+.price-large {
+    font-size: 1.5rem;
+}

package/templates/vue/src/views.ts

@@ -0,0 +1,12 @@
+import About from "./pages/About.vue";
+import Home from "./pages/Home.vue";
+import NotFound from "./pages/NotFound.vue";
+import ProductDetail from "./pages/ProductDetail.vue";
+import Search from "./pages/Search.vue";
+export const views = {
+    home: Home,
+    product: ProductDetail,
+    search: Search,
+    about: About,
+    error: NotFound,
+};

package/templates/vue/tsconfig.json

@@ -4,20 +4,25 @@
         "target": "ESNext",
         "module": "ESNext",
         "moduleResolution": "bundler",
-        "jsx": "preserve",
+        "allowImportingTsExtensions": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
         "esModuleInterop": true,
         "forceConsistentCasingInFileNames": true,
         "skipLibCheck": true,
         "noEmit": true,
+        "rootDir": ".",
+        "jsx": "preserve",
         "paths": {
-            "@/*": ["./src/*"],
-            "@finesoft/front": ["../../packages/front/src/index.ts"],
-            "@finesoft/front/browser": ["../../packages/front/src/browser.ts"],
-            "@finesoft/core": ["../../packages/core/src/index.ts"],
-            "@finesoft/browser": ["../../packages/browser/src/index.ts"],
-            "@finesoft/ssr": ["../../packages/ssr/src/index.ts"],
-            "@finesoft/server": ["../../packages/server/src/index.ts"]
+            "@finesoft/front": [
+                "./.finesoft/front.d.ts"
+            ]
         }
     },
-    "include": ["src/**/*", "env.d.ts", "vite.config.ts"]
+    "include": [
+        "src/**/*",
+        "env.d.ts",
+        "vite.config.ts"
+    ]
 }

package/templates/vue/vite.config.ts

@@ -1,18 +1,14 @@
 import { finesoftFrontViteConfig } from "@finesoft/front";
 import vue from "@vitejs/plugin-vue";
-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: [
-        vue(),
-        finesoftFrontViteConfig({
-            ssr: { entry: "src/ssr.ts" },
-            proxies: [
-                {
-                    prefix: "/api",
-                    target: "https://jsonplaceholder.typicode.com",
-                },
-            ],
-        }),
-    ],
+    lint: { options: { typeAware: true, typeCheck: true } },
+    plugins: lazyPlugins(() => [front, vue()]),
 });

package/templates/vue-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/vue-minimal/index.html

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

package/templates/vue-minimal/package.json

@@ -8,12 +8,16 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.5.1",
-        "vue": "^3.5.0"
+        "@finesoft/front": "^0.5.2",
+        "vue": "^3.5.41"
     },
     "devDependencies": {
-        "@vitejs/plugin-vue": "^5.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",
+        "@vitejs/plugin-vue": "^6.0.8",
+        "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/vue-minimal/src/App.vue

@@ -1,62 +1,65 @@
 <script setup lang="ts">
-import { isStackNode, isTabsNode } from "@finesoft/front";
-import { computed } from "vue";
-import type { AppController, AppState } from "./main";
+import { Outlet as selectOutlet, useSnapshot, type WebAppView } from "@finesoft/front";
+import { onMounted, onUnmounted, ref } from "vue";
+import { TAB_LABELS } from "./lib/navigation";
+import { views } from "./views";
+const Outlet = selectOutlet("vue");
 
-const { state, controller } = defineProps<{ state?: AppState; controller?: AppController }>();
-
-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;
-    },
+defineOptions({ inheritAttrs: false });
+const { app } = defineProps<{ app: WebAppView }>();
+const snapshot = useSnapshot("vue", app);
+// Start empty on both server and client; restore the profile after hydration.
+const name = ref("");
+let unregister: (() => void) | undefined;
+onUnmounted(() => unregister?.());
+onMounted(() => {
+    unregister = 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: name.value }),
+        restore: (data) => {
+            name.value = data.name;
+        },
+    });
 });
 </script>
 
 <template>
-    <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">
+    <div class="app-chrome">
+        <header class="profile">
+            <label>
                 Your name (global):
-                <input v-model="name" placeholder="anon" @blur="controller?.save()" />
+                <input
+                    :value="name"
+                    placeholder="anon"
+                    @input="name = ($event.target as HTMLInputElement).value"
+                    @blur="app.session?.save()"
+                />
             </label>
             <span v-if="name">👋 {{ name }}</span>
         </header>
-
-        <!-- TabView -->
-        <nav v-if="tabs" style="display: flex; gap: 0.5rem; margin-bottom: 1rem">
+        <nav v-if="snapshot.navigation.tabs" class="tabs" aria-label="Pages">
             <button
-                v-for="key in tabs.order"
+                v-for="key in snapshot.navigation.tabs.order"
                 :key="key"
-                :style="{ fontWeight: key === tabs.active ? '700' : '400' }"
-                :aria-current="key === tabs.active"
-                @click="controller?.selectTab(key)"
+                :aria-current="key === snapshot.navigation.tabs.active"
+                @click="app.perform({ kind: 'selectTab', key })"
             >
-                {{ tabLabels[key] ?? key }}
+                {{ TAB_LABELS[key] ?? key }}
             </button>
         </nav>
-
-        <button v-if="canGoBack" style="margin-bottom: 0.5rem" @click="controller?.pop()">
+        <button v-if="snapshot.navigation.canGoBack" @click="app.perform({ kind: 'pop' })">
             ← Back
         </button>
+        <Outlet :app="app" :views="views" />
     </div>
 </template>

package/templates/vue-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/vue-minimal/src/config.ts

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

package/templates/vue-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/vue-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/vue-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/vue-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/vue-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/vue-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/vue-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/vue-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."
+}