@geektech/tsone 0.1.0 → 0.3.0

package/README-zh.md

@@ -53,7 +53,7 @@ class App extends Component<Record<string, never>, AppState> {
   protected initState(): AppState {
     return {
       count: 0,
-      version: '0.0.2',
+      version: '0.3.0',
     };
   }
 
@@ -95,9 +95,10 @@ console.log(status.value);
 
 ## 开发工具
 
-独立的 `@geektech/tsone-cli` 包提供 `tsone dev` 与 `tsone build`。默认入口为
-`src/main.ts`；入口模块必须通过 `export const app` 导出应用，并且该值必须提供
-`renderHtmlDocument()`。
+独立的 `@geektech/tsone-cli` 包提供 `tsone create`、`tsone dev` 与
+`tsone build`。`tsone create` 会在当前目录脚手架一个基础项目（包含一个展示
+TSone 名称与 GitHub 链接的首页）。CLI 的默认入口为 `src/main.ts`；入口模块必须
+通过 `export const app` 导出应用，并且该值必须提供 `renderHtmlDocument()`。
 
 可以在项目根目录创建可选的 `tsone.config.ts`：
 
@@ -121,16 +122,36 @@ export default defineConfig({
 ```
 
 代理也支持字符串简写，例如 `{ '/backend': 'http://localhost:4000' }`。默认值为
-入口 `src/main.ts`、主机 `127.0.0.1`、端口 `52211`、空的 `server.proxy` 和
-输出目录 `dist`。
+入口 `src/main.ts`、主机 `127.0.0.1`、端口 `52211`、空的 `server.proxy`、输出
+目录 `dist`，且没有额外页面。
+
+多页应用可在同一配置文件里把路由映射到页面入口；每个页面入口与根入口一样，
+都要通过 `export const app` 暴露带有 `renderHtmlDocument()` 的应用：
+
+```typescript
+export default defineConfig({
+  entry: 'src/main.ts',
+  pages: {
+    '/about': 'src/about.ts',
+    '/docs/guide': 'src/guide.ts',
+  },
+});
+```
+
+`pages` 的键必须以 `/` 开头并支持嵌套；根路径 `/` 由 `entry` 提供。开发时每个
+页面在其路由下提供服务，`tsone build` 会为每个页面输出一个 HTML 文档
+（`index.html`、`about.html`、`docs/guide.html`），资源 URL 相对各文档。
 
 ```text
-tsone dev [--host <host>] [--port <port>]
+tsone create
+tsone dev [--host <host>] [--port <port>] [--no-watch]
 tsone build [--out-dir <path>]
 ```
 
-`dev` 只接受主机和端口覆盖，`build` 只接受输出目录覆盖；`--port 3000` 和
-`--port=3000` 两种形式均可。构建输出必须是项目根目录内部的安全子目录。
+`create` 不接受任何选项。`dev` 接受主机、端口覆盖和 `--no-watch`；`build` 只
+接受输出目录覆盖；`--port 3000` 和 `--port=3000` 两种形式均可。`tsone dev`
+默认监听项目文件，文件变化时通过 `/__tsone/reload` 通知浏览器刷新。构建输出
+必须是项目根目录内部的安全子目录。
 
 编程式工具 API 来自 `@geektech/tsone-cli`，而不是框架主入口。该包导出
 `defineConfig`、`resolveConfig`、`startDevServer` 与 `build`。调用方负责开发
@@ -210,7 +231,7 @@ bun run dev:admin
 文档站点使用 typed content registry：中文内容维护在
 `packages/tsone/docs/app/content/zh/`，英文内容维护在
 `packages/tsone/docs/app/content/en/`，中英文逻辑路由必须一致。
-中英文 catalog 当前各包含 14 条逻辑路由；新增或删除路由时必须同步修改两边。
+中英文 catalog 当前各包含 15 条逻辑路由；新增或删除路由时必须同步修改两边。
 
 内容链接保持 locale-neutral，不要手写 `/en/`。中文公开路由不带前缀，英文公开
 路由使用 `/en/`。浏览器语言检测仅在 `/` 生效；手动选择优先并持久化，后续访问
@@ -224,6 +245,17 @@ bun run docs:build
 
 构建遇到缺失、多余、重复、空内容或混用语言的页面时会严格失败。
 
+需要把站点托管到某个子路径下（例如 GitHub Pages 项目页
+`https://<owner>.github.io/tsone/`）时，可以用 base path 构建：
+
+```bash
+bun run docs:build -- --base=/tsone/
+```
+
+也可以通过环境变量 `DOCS_BASE_PATH` 指定。配置 base path 后，产物中的所有
+链接与资源 URL 都会带上该前缀，语言引导脚本会从渲染后的文档读取 base path，
+站点即可在任意子路径下正常工作。
+
 基础 HTML 文档壳也可以放进 `createApp` 配置里生成。默认会输出 `#app`
 挂载节点；需要自定义挂载点时再传 `rootElement`。`body` 需要自定义时传入组件
 或 VNode，不传 HTML 字符串。
@@ -283,7 +315,8 @@ const html = app.renderHtmlDocument({
 - `effect()` / `stop()`
 - `computed()`
 - `ref()` / `isRef()` / `unref()`
-- `version`，当前为 `0.0.2`
+- `nextTick()` / `flushSync()`
+- `version`，当前为 `0.3.0`
 
 ## 渲染、通信与表单
 

package/README.md

@@ -58,7 +58,7 @@ class App extends Component<Record<string, never>, AppState> {
   protected initState(): AppState {
     return {
       count: 0,
-      version: '0.0.2',
+      version: '0.3.0',
     };
   }
 
@@ -101,8 +101,10 @@ need to override the default target.
 
 ## Development Tooling
 
-The separate `@geektech/tsone-cli` package provides `tsone dev` and
-`tsone build`. Its default entry is `src/main.ts`; that module must expose the
+The separate `@geektech/tsone-cli` package provides `tsone create`, `tsone dev`,
+and `tsone build`. `tsone create` scaffolds a basic project (including a
+homepage showing the TSone name and a GitHub link) into the current directory.
+The CLI's default entry is `src/main.ts`; that module must expose the
 application as `export const app`, and the value must provide
 `renderHtmlDocument()`.
 
@@ -130,16 +132,39 @@ export default defineConfig({
 
 The string proxy shorthand is also supported, for example
 `{ '/backend': 'http://localhost:4000' }`. Defaults are `src/main.ts`,
-`127.0.0.1`, port `52211`, an empty `server.proxy`, and `dist`.
+`127.0.0.1`, port `52211`, an empty `server.proxy`, `dist`, and no additional
+pages.
+
+Multi-page applications map routes to page entries in the same config file;
+each page entry exposes `app` with `renderHtmlDocument()` exactly like the root
+entry:
+
+```typescript
+export default defineConfig({
+  entry: 'src/main.ts',
+  pages: {
+    '/about': 'src/about.ts',
+    '/docs/guide': 'src/guide.ts',
+  },
+});
+```
+
+`pages` keys must start with `/` and may nest; the root `/` is served by
+`entry`. During development each page is served at its route, and `tsone build`
+emits one HTML document per page (`index.html`, `about.html`,
+`docs/guide.html`) with page-relative asset URLs.
 
 ```text
-tsone dev [--host <host>] [--port <port>]
+tsone create
+tsone dev [--host <host>] [--port <port>] [--no-watch]
 tsone build [--out-dir <path>]
 ```
 
-`dev` accepts host/port overrides and `build` accepts the output-directory
-override; both `--port 3000` and `--port=3000` forms are valid. Build output
-must remain a safe child directory inside the project root.
+`create` takes no options. `dev` accepts host/port overrides and `--no-watch`;
+`build` accepts the output-directory override; both `--port 3000` and
+`--port=3000` forms are valid. `tsone dev` watches the project by default and
+notifies browsers to reload over `/__tsone/reload` when a watched file changes.
+Build output must remain a safe child directory inside the project root.
 
 Programmatic tooling is imported from `@geektech/tsone-cli`, not from the
 framework root. It exports `defineConfig`, `resolveConfig`, `startDevServer`,
@@ -227,7 +252,7 @@ content lives in `packages/tsone/docs/app/content/zh/`, while English content
 lives in `packages/tsone/docs/app/content/en/`. Every logical route must exist
 in both directories.
 
-Chinese and English catalogs each contain exactly 14 logical routes. Add or
+Chinese and English catalogs each contain exactly 15 logical routes. Add or
 remove a route in both catalogs in the same change.
 
 Content links stay locale-neutral: never write `/en/` manually. Chinese public
@@ -244,6 +269,18 @@ bun run docs:build
 The build fails strictly for missing, extra, duplicate, empty, or
 mixed-language pages.
 
+To host the site under a sub-path (for example a GitHub Pages project page such
+as `https://<owner>.github.io/tsone/`), build it with a base path:
+
+```bash
+bun run docs:build -- --base=/tsone/
+```
+
+You can also set the `DOCS_BASE_PATH` environment variable. When a base path is
+configured, every link and asset URL is prefixed with it, and the locale
+bootstrap reads the base path from the rendered document, so the site works
+under any sub-path.
+
 The base HTML document shell can also be generated from `createApp`. It emits a
 `#app` mount node by default; pass `rootElement` only to use a different target.
 When a custom `body` is needed, pass a component or VNode rather than an HTML
@@ -303,7 +340,8 @@ The main `@geektech/tsone` entry point exports:
 - `effect()` / `stop()`
 - `computed()`
 - `ref()` / `isRef()` / `unref()`
-- `version`, currently `0.0.2`
+- `nextTick()` / `flushSync()`
+- `version`, currently `0.3.0`
 
 ## Rendering, Communication, and Forms
 

package/dist/core/reactive/scheduler.d.ts

@@ -0,0 +1,32 @@
+import type { ReactiveEffect } from './types';
+/**
+ * 响应式 effect 批处理调度器。
+ *
+ * 同一批同步状态变更（同一个任务内的多次 mutation）只会触发一次 effect
+ * 运行：effect 被 enqueue 后去重入队，并在微任务中统一冲刷（flush）。
+ * 冲刷期间的重复入队会在同一轮循环中继续处理，直到队列清空。
+ *
+ * 组件渲染通过该调度器合并更新：连续修改 state 不会逐次重渲染，
+ * 与 Vue 微任务调度 / React 自动批处理的语义一致。
+ */
+export declare class ReactiveScheduler {
+    private readonly pending;
+    private flushing;
+    private flushPromise;
+    private flushResolve;
+    /**
+     * 将 effect 加入待冲刷队列（去重）。
+     */
+    enqueue(effect: ReactiveEffect): void;
+    /**
+     * 同步冲刷队列：立即执行所有待运行的 effect。
+     * 若当前正处于一次冲刷中（例如在 effect 内部调用），则直接返回，
+     * 由正在进行的冲刷循环负责处理新增任务。
+     */
+    flush(): void;
+    /**
+     * 返回一个在待冲刷的 effect 全部执行完成后 resolve 的 Promise。
+     * 若当前没有待冲刷任务，立即 resolve。
+     */
+    nextTick(): Promise<void>;
+}

package/dist/core/reactive.d.ts

@@ -1,5 +1,17 @@
 import { ComputedRef, Ref, ReactiveEffect, ReactiveEffectOptions } from './reactive/types';
+import { ReactiveScheduler } from './reactive/scheduler';
 export type { ComputedRef, Ref, ReactiveEffect, ReactiveEffectOptions, } from './reactive/types';
+export declare const reactiveScheduler: ReactiveScheduler;
+/**
+ * 等待当前批次的响应式 effect 全部执行完成（通常是组件重渲染）。
+ * 修改 state 后需要立即读取 DOM 时使用：await nextTick()。
+ */
+export declare function nextTick(): Promise<void>;
+/**
+ * 同步冲刷待执行的响应式 effect，立即完成组件重渲染。
+ * 一般仅测试或需要同步读 DOM 的场景使用。
+ */
+export declare function flushSync(): void;
 export declare class ReactiveSystem {
     private static instance;
     private activeEffect;