@finesoft/create-app 0.1.34 → 0.1.36

package/templates/svelte/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/svelte/src/views.ts

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

package/templates/svelte/svelte.config.js

@@ -0,0 +1,2 @@
+/** Standard Svelte defaults; compiler configuration belongs to the Vite plugin. */
+export default {};

package/templates/svelte/tsconfig.json

@@ -4,19 +4,24 @@
         "target": "ESNext",
         "module": "ESNext",
         "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
         "esModuleInterop": true,
         "forceConsistentCasingInFileNames": true,
         "skipLibCheck": true,
         "noEmit": true,
+        "rootDir": ".",
         "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/svelte/vite.config.ts

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

package/templates/svelte-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/svelte-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/svelte-minimal/package.json

@@ -8,12 +8,16 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.5.1",
-        "svelte": "^5.55.7"
+        "@finesoft/front": "^0.5.3",
+        "svelte": "^5.56.8"
     },
     "devDependencies": {
-        "@sveltejs/vite-plugin-svelte": "^5.0.0",
-        "vite": "npm:@voidzero-dev/vite-plus-core@0.1.16",
-        "vite-plus": "0.1.24"
+        "@hono/node-server": "^2.1.0",
+        "@sveltejs/vite-plugin-svelte": "^7.3.0",
+        "@types/node": "^22.20.1",
+        "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/svelte-minimal/src/App.svelte

@@ -1,63 +1,51 @@
 <script lang="ts">
-	import { type BasePage, Framework } from "@finesoft/front";
-	import { untrack } from "svelte";
-	import { setFrameworkContext } from "./lib/framework-svelte";
-	import Home from "./pages/Home.svelte";
-
-	type Props = {
-		framework?: Framework;
-		page?: BasePage | null;
-	};
-
-	let props: Props = $props();
-
-	// context 只需在初始化时设置一次，用 untrack 明确声明仅读取初始值
-	const framework = untrack(() => props.framework);
-	if (framework) {
-		setFrameworkContext(framework);
-	}
-
-	/** 将导航 Promise 的 rejection 转为错误页，避免 {:catch} 暴露原始异常 */
-	function wrapError(p: Promise<BasePage>): Promise<BasePage> {
-		return p.catch(
-			(err): BasePage => ({
-				id: "error",
-				pageType: "error",
-				title: "Error",
-				description:
-					err instanceof Error ? err.message : "Failed to load page",
-			}),
-		);
-	}
-
-	/**
-	 * 当前页面数据:
-	 * - BasePage: SSR 直出 或 已完成的导航
-	 * - Promise<BasePage>: SPA 导航中
-	 * - null: 初始空白态
-	 */
-	let currentPage = $state<Promise<BasePage> | BasePage | null>(
-		untrack(() => props.page ?? null),
-	);
-
-	/** 由 main.ts 的 mount 回调调用，驱动 SPA 导航 */
-	export function updatePage(newPage: Promise<BasePage> | BasePage): void {
-		if (newPage instanceof Promise) {
-			currentPage = wrapError(newPage);
-		} else {
-			currentPage = newPage;
-		}
-	}
+    import { Outlet as selectOutlet, useSnapshot, type WebAppView } from "@finesoft/front";
+    import { onMount, untrack } from "svelte";
+    import { TAB_LABELS } from "./lib/navigation";
+    import { views } from "./views";
+const Outlet = selectOutlet("svelte");
+    let { app }: { app: WebAppView } = $props();
+    const snapshot = untrack(() => useSnapshot("svelte", app));
+    let name = $state("");
+    onMount(() => 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 }),
+        restore: (data) => {
+            name = data.name;
+        },
+    }));
 </script>
-
-<main style="padding: 1rem">
-	{#if currentPage instanceof Promise}
-		{#await currentPage}
-			<p style="text-align: center; color: #999">Loading…</p>
-		{:then page}
-			<Home {page} />
-		{/await}
-	{:else if currentPage}
-		<Home page={currentPage} />
-	{/if}
-</main>
+<div class="app-chrome">
+    <header class="profile">
+        <label>
+            Your name (global):
+            <input bind:value={name} placeholder="anon" onblur={() => app.session?.save()} />
+        </label>
+        {#if name}<span>👋 {name}</span>{/if}
+    </header>
+    {#if $snapshot.navigation.tabs}
+        <nav class="tabs" aria-label="Pages">
+            {#each $snapshot.navigation.tabs.order as key (key)}
+                <button
+                    aria-current={key === $snapshot.navigation.tabs.active}
+                    onclick={() => app.perform({ kind: "selectTab", key })}
+                >
+                    {TAB_LABELS[key] ?? key}
+                </button>
+            {/each}
+        </nav>
+    {/if}
+    {#if $snapshot.navigation.canGoBack}
+        <button onclick={() => app.perform({ kind: "pop" })}>← Back</button>
+    {/if}
+    <Outlet {app} {views} />
+</div>

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

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

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

@@ -0,0 +1,23 @@
+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";
+
+export class DetailController extends BaseServerController<Input, DetailPage> {
+    execute({ params, context }: Input): DetailPage {
+        const id = params.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/svelte-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/svelte-minimal/src/lib/controllers/home.ts

@@ -1,27 +1,28 @@
-import {
-    BaseController,
-    DEP_KEYS,
-    type BasePage,
-    type Container,
-    type Translator,
-} from "@finesoft/front";
+import { BaseController, type ControllerInput } from "@finesoft/front";
+import { markPublic } from "@finesoft/front";
+import type { FeedItem, HomePage } from "../models/page";
 
-export class HomeController extends BaseController<Record<string, string>, BasePage> {
-    readonly intentId = "home";
+const ITEMS: readonly FeedItem[] = [
+    { id: "1", title: "Structured navigation" },
+    { id: "2", title: "Session restoration" },
+    { id: "3", title: "Navigation-scoped state" },
+];
 
-    execute(_params: Record<string, string>, container: Container): BasePage {
-        const translator = container.has(DEP_KEYS.TRANSLATOR)
-            ? container.resolve<Translator>(DEP_KEYS.TRANSLATOR)
-            : undefined;
-
-        return {
-            id: "home",
-            pageType: "home",
-            url: "/",
-            title: translator?.t("home.title") ?? "Hello from Finesoft Front",
-            description:
-                translator?.t("home.description") ??
-                "This page uses locale JSON files loaded by finesoftFrontViteConfig.",
-        };
+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/svelte-minimal/src/lib/controllers/notes.ts

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

package/templates/svelte-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/svelte-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/svelte-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/svelte-minimal/src/locales/en-US.json

@@ -1,7 +1,5 @@
 {
-    "home.title": "Hello from Finesoft Front",
-    "home.description": "This page uses locale JSON files loaded by finesoftFrontViteConfig.",
     "home.localeLabel": "Current locale",
     "home.runtimeBadge": "Hydration kept the translator alive on the client.",
-    "home.switchHint": "Change frameworkConfig.locale in src/bootstrap.ts to load another JSON file."
+    "home.switchHint": "Change frameworkConfig.locale in src/app-definition.ts to en-US or zh-Hans to load the corresponding JSON file."
 }

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

@@ -1,7 +1,5 @@
 {
-    "home.title": "你好，来自 Finesoft Front",
-    "home.description": "这个页面的文案来自 finesoftFrontViteConfig 自动加载的 JSON 翻译文件。",
     "home.localeLabel": "当前语言",
     "home.runtimeBadge": "浏览器接管后，翻译器仍然可用。",
-    "home.switchHint": "把 src/bootstrap.ts 里的 frameworkConfig.locale 改成 zh-Hans，就会加载这份翻译文件。"
+    "home.switchHint": "修改 src/app-definition.ts 中的 frameworkConfig.locale：en-US 为英文，zh-Hans 为中文。"
 }

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

@@ -1,22 +1,40 @@
-import { startBrowserApp, type BasePage, type Framework } from "@finesoft/front";
-import { hydrate } from "svelte";
+import { createBrowserApp } from "@finesoft/front";
+import { hydrate, mount, unmount } from "svelte";
+import { app } from "./app-definition";
+import { appId } from "./config";
 import App from "./App.svelte";
-import { bootstrap } from "./bootstrap";
+import "./styles.css";
 
-void startBrowserApp({
-    bootstrap,
-    mount(target: HTMLElement, { framework }: { framework: Framework }) {
-        // Svelte 5 中必须用 hydrate() 激活 SSR 输出，new Component() 已被移除
-        const app = hydrate(App, { target, props: { framework } });
+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: {},
+    });
+    if (!handle.shouldHydrate) target.replaceChildren();
+    const root = (handle.shouldHydrate ? hydrate : mount)(App, { target, props: { app: handle } });
+    const originalDispose = handle.dispose.bind(handle);
+    let disposal: Promise<void> | undefined;
+    Object.assign(handle, {
+        dispose: () => (disposal ??= originalDispose().finally(() => unmount(root))),
+    });
+    await handle.ready;
+    return handle;
+}
 
-        return (props: { page: Promise<BasePage> | BasePage; isFirstPage?: boolean }) => {
-            (app as { updatePage: (p: Promise<BasePage> | BasePage) => void }).updatePage(
-                props.page,
-            );
-        };
-    },
-    callbacks: {
-        onNavigate() {},
-        onModal() {},
-    },
-});
+export const started = mountApplication(document.getElementById("app")!);
+
+if (import.meta.hot) {
+    import.meta.hot.dispose(async () => {
+        await (await started).dispose();
+    });
+}