@lark.js/mvc 0.0.2 → 0.0.4

package/README.md

@@ -1,73 +1,264 @@
-# Lark Framework
+---
+name: lark-mvc
+description: >
+  Lark MVC Framework (@lark.js/mvc) skill for building TypeScript frontend applications.
+  Use this skill whenever the user is working with the Lark framework, including:
+  creating Views, defining Stores, configuring Routes, writing templates, using Updater,
+  integrating with Vite or Webpack, or any question about Lark's API, architecture,
+  or conventions. Also trigger when the user mentions hash-based routing, Proxy-based
+  reactive state, VDOM diff rendering, event delegation, or the v-lark attribute pattern,
+  even if they do not explicitly name "Lark".
+---
 
-Lark 是基于 TypeScript 的 MVC 前端框架, 核心特点包括: 虚拟 DOM 差量更新、hash 路由、事件委托、模板编译、Proxy 响应式状态管理, 提供声明式数据绑定的 SPA 开发体验
+# Lark MVC Framework
 
-架构总览
+Lark is a TypeScript MVC framework for building single-page applications with hash-based routing, Proxy-based reactive state management, and real DOM diff rendering.
 
-```
-Framework (主入口)
-  ├── Router (hash 路由, 两阶段变更确认)
-  ├── State (跨视图 observable 数据, 键引用计数自动清理)
-  ├── Store (Proxy 深度响应式状态管理, 多平台适配)
-  ├── Frame (视图生命周期树, 对象池复用)
-  │     └── View (视图实例, 事件方法绑定)
-  │           └── Updater (数据绑定 + VDOM diff)
-  ├── EventDelegator (DOM 事件委托至 document.body)
-  ├── Service + Bag (接口请求管理, 缓存/去重/队列)
-  ├── Compiler (模板编译, 构建时将 HTML 模板编译为 JS 函数)
-  ├── Mark/Unmark (异步回调有效性追踪)
-  ├── Safeguard (Proxy 调试保护)
-  ├── Cache (LFU 风格缓存, 频率+时间双重淘汰)
-  ├── EventEmitter (多播事件发射器)
-  └── ApplyStyle (CSS 动态注入)
-```
+## Architecture Overview
+
+Lark follows a strict MVC separation:
+
+- **Model**: `defineStore` for reactive state (recommended), `cell`/`observeCell` for standalone reactive cells, `State` for global singleton data (default when no store is specified), `Service` for API request management
+- **View**: `View.extend()` creates view subclasses with template rendering, event delegation, and lifecycle hooks
+- **Controller**: `Router` for hash-based navigation, `Updater` for per-view data binding and VDOM diff, `Frame` for view lifecycle management
+
+Data flows through three pipelines (use Store when possible, State is the default when no store is specified):
+
+1. **Updater Pipeline** (view-local): `updater.set(data)` -> `updater.digest()` -> template function -> HTML string -> VDOM diff -> DOM patch -> `endUpdate()`
+2. **State Pipeline** (default cross-view): `State.set(data)` -> `State.digest()` -> `changed` event -> views read `State.get()` in `assign()` -> `updater.digest()` -> VDOM diff -> DOM patch. State uses key reference counting: when no view observes a key, the data is automatically deleted on view destroy via `State.clean()`
+3. **Store Pipeline** (cross-view, recommended): `store.key = value` -> Proxy set trap -> `trigger()` -> `GlobalDeps` lookup -> Queue microtask batch -> `store.observe` callback -> `updater.digest()` / `updater.set()` -> VDOM diff -> DOM patch
+
+### Boot Sequence (Critical Order)
+
+`Framework.boot()` executes in a specific order that must not be changed:
+
+1. Merge config -> 2. Set Router config -> 3. Set EventDelegator frame getter -> 4. Bind Router/State events -> 5. **Create rootFrame** -> 6. **Router.\_bind()** -> 7. Mount default view
+
+The rootFrame is created BEFORE `Router._bind()` so that the root element has a proper ID. If the order were reversed, rootId would default to `"root"` and views could render into `document.body` unexpectedly.
 
-Lark 框架启动时, Framework.boot() 初始化路由器、状态管理器、事件委托器, 创建根 Frame 节点, 绑定 hashchange 事件; 路由改变与状态改变通过统一的派发器 (Dispatcher) 沿 Frame 树向下通知各个 View, 触发条件匹配的视图重新渲染
+If a view was already mounted by the router (e.g. after a page reload with `#!/counter`), the default view is NOT mounted to avoid URL/display mismatch (`if (defaultView && !rootFrame.view)`).
 
-安装
+### Window Globals
+
+After boot, the framework sets these globals for debugging and extension:
+
+| Global                    | Value            | Purpose                           |
+| ------------------------- | ---------------- | --------------------------------- |
+| `window.__lark_Framework` | Framework object | Direct framework access           |
+| `window.__lark_State`     | State object     | Direct state access               |
+| `window.__lark_Router`    | Router object    | Direct router access              |
+| `window.__lark_Frame`     | Frame class      | Direct Frame class access         |
+| `window.__lark_View`      | View class       | Direct View class access          |
+| `window.__lark_Debug`     | boolean          | Enable safeguard Proxy debug mode |
+
+Setting `window.__lark_Debug = true` before boot enables:
+
+- Safeguard Proxy wrapping on State/Updater data reads (warns on cross-page reads, delays direct mutation warnings by 500ms)
+- Safeguard Proxy on Router `diff()` results and Location params
+
+## Project Structure
 
 ```
-pnpm add @lark.js/mvc
+project/
+  index.html                  # Entry HTML with <script type="module" src="/src/boot.ts">
+  vite.config.ts              # Vite config with larkMvcPlugin()
+  webpack.config.mjs          # Webpack config with larkMvcLoader (alternative bundler)
+  src/
+    boot.ts                   # Bootstrap: registerViewClass + Framework.boot(config)
+    view.ts                   # Project-level View base class (View.extend)
+    styles.css                # Global styles
+    store/
+      count.ts                # defineStore declarations
+    views/
+      home.ts                 # View.extend({ template, init, render, event methods })
+      home.html               # Template file (compiled by larkMvcPlugin or larkMvcLoader)
+      about.ts
+      about.html
+    components/
+      counter-store.ts        # Sub-component views
+      counter-store.html
 ```
 
-快速上手
+**Important**: `boot.ts` must be placed inside `src/` (not project root). The `index.html` entry references it as `/src/boot.ts`.
+
+## Step-by-Step Guide
+
+### 1. Install and Configure
 
-1. 配置构建工具
+```bash
+pnpm add @lark.js/mvc
+```
 
-Vite 项目在 vite.config.ts 中导入 larkMvcPlugin 插件, 该插件会自动将 .html 模板文件编译为 JS 函数
+### 2. Configure Vite Integration
 
 ```typescript
-import { larkMvcPlugin } from "@lark/framework/vite";
+// vite.config.ts
+import { defineConfig } from "vite";
+import { resolve } from "path";
+import { larkMvcPlugin } from "@lark.js/mvc/vite";
 
 export default defineConfig({
   plugins: [larkMvcPlugin()],
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "./src"),
+    },
+  },
 });
 ```
 
-Webpack 项目在 webpack.config.mjs 中配置 loader
+The `larkMvcPlugin` automatically compiles `.html` template imports into JS function modules. Zero configuration required -- just add the plugin and import `.html` files in your views.
+
+How it works internally:
+
+1. **resolveId hook**: Intercepts `.html` import source strings. When a module imports a `.html` file, the plugin resolves the full path and appends the `?lark-template` suffix (internal constant `LARK_TEMPLATE_SUFFIX`). This prevents Vite from treating the file as a static asset.
+2. **load hook**: When Vite requests a module whose ID ends with `?lark-template`, the plugin reads the raw HTML file from disk, auto-extracts global variables via `extractGlobalVars()` AST analysis, and compiles the template through `compileTemplate()`. The compiled output is an ES module exporting a function with signature `(data, selfId, refData) => string`.
+3. **enforce: "pre"**: The plugin is registered as a pre-phase plugin to ensure it runs before other Vite plugins that might also handle `.html` files.
+
+For debug mode with line tracking and detailed error messages:
+
+```typescript
+plugins: [larkMvcPlugin({ debug: true })];
+```
+
+### 3. Configure Webpack Integration
 
 ```javascript
-import { resolve } from "path";
-import { larkMvcLoader } from "@lark/framework/webpack";
+// webpack.config.mjs
+import path from "path";
+import { fileURLToPath } from "url";
+import HtmlWebpackPlugin from "html-webpack-plugin";
+import { larkMvcLoader } from "@lark.js/mvc/webpack";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export default {
+  entry: "./boot.ts",
+  output: {
+    path: path.resolve(__dirname, "dist"),
+    filename: "js/[name].[contenthash:8].js",
+    clean: true,
+  },
+  resolve: {
+    extensions: [".ts", ".js"],
+    alias: {
+      "@": path.resolve(__dirname, "src"),
+    },
+  },
   module: {
     rules: [
+      {
+        test: /\.ts$/,
+        use: "ts-loader",
+        exclude: /node_modules/,
+      },
+      {
+        test: /\.css$/,
+        use: ["style-loader", "css-loader", "postcss-loader"],
+      },
+      // Lark template processing - larkMvcLoader compiles .html to JS functions
       {
         test: /\.html$/,
-        loader: larkMvcLoader,
+        use: [{ loader: larkMvcLoader }],
+        exclude: /index\.html$/, // Exclude the entry HTML page
       },
     ],
   },
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: "./index.html",
+      inject: "body",
+      minify: false,
+    }),
+  ],
+  devServer: {
+    port: 3001,
+    open: true,
+    hot: true,
+  },
+  devtool: "source-map",
 };
 ```
 
-2. 定义 Store
+The `larkMvcLoader` is a standard Webpack loader that compiles `.html` template files into JS function modules at build time. It works by:
+
+1. Receiving the raw HTML source string as input from Webpack.
+2. Auto-extracting global variables via `extractGlobalVars()` AST analysis (the same function used by the Vite plugin).
+3. Compiling the template through `compileTemplate()` to produce an ES module string.
+4. Returning the compiled result to Webpack via `this.callback()`.
+
+Key configuration points:
+
+- Import `larkMvcLoader` from `@lark.js/mvc/webpack` (not from a file path).
+- Use the loader object directly as `loader: larkMvcLoader` (it is a function, not a string name).
+- Exclude `index.html` from the loader rule -- the entry HTML page should be processed by HtmlWebpackPlugin, not by larkMvcLoader.
+- Use `HtmlWebpackPlugin` to inject scripts into the entry HTML page.
+
+For debug mode, pass loader options:
+
+```javascript
+{
+  test: /\.html$/,
+  use: [
+    {
+      loader: larkMvcLoader,
+      options: { debug: true },
+    },
+  ],
+  exclude: /index\.html$/,
+},
+```
+
+The `debug` option enables line tracking and detailed compile-time/runtime error messages with source mapping.
+
+### 4. Create Entry HTML
+
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Lark App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/boot.ts"></script>
+  </body>
+</html>
+```
+
+The `<div id="app">` corresponds to `rootId: "app"` in the boot config.
+
+For Webpack, the entry HTML uses HtmlWebpackPlugin instead of a `<script>` tag. HtmlWebpackPlugin automatically injects the bundled script.
+
+### 5. Create a Project Base View
+
+```typescript
+// src/view.ts
+import { View, Router } from "@lark.js/mvc";
+
+export default View.extend({
+  make() {
+    this.updater.set({ appName: "My App" });
+    this.on("destroy", () => {
+      console.log(`View destroyed: ${this.id}`);
+    });
+  },
+  navigate(path: string, params?: Record<string, unknown>) {
+    Router.to(path, params);
+  },
+});
+```
+
+**How View.extend() works internally**: It creates an ES6 class that extends the parent View. The `make` function is collected into a `ctors` array (along with mixin `make` functions). In the constructor, extend props (like `template`) are applied as **instance properties** after `super()`, because ES6 class field declarations (e.g., `template;` in View) would shadow prototype properties. **CRITICAL**: `render` is explicitly skipped as an instance property — it is wrapped on the prototype by `View.wrapMethod()` to manage signature checking and resource cleanup. Setting `render` on the instance would bypass signature checking, the `"render"` event, and `destroyAllResources()`.
 
-通过 defineStore 创建响应式状态管理, creator 函数返回的对象中, 非函数属性成为响应式 state, 函数属性成为 handler
+### 6. Define Stores
 
 ```typescript
-import { defineStore } from "@lark.js/mvc";
+// src/store/count.ts
+import { defineStore, cell, observeCell, multi } from "@lark.js/mvc";
 
 export interface CountStore {
   count: number;
@@ -78,868 +269,445 @@ export interface CountStore {
   reset: () => void;
   setStep: (val: number) => void;
   clearHistory: () => void;
+  registerObservers: () => void;
 }
 
-const useCountStore = defineStore<CountStore>("count", (store) => {
-  return {
-    count: 0,
-    step: 1,
-    history: [] as string[],
+const useCountStore = defineStore<CountStore>(
+  "count",
+  (store, { lazySet, shallowSet }) => {
+    return {
+      count: 0,
+      step: 1,
+      history: [] as string[],
+      increment() {
+        store.count = store.count + store.step;
+        store.history = [...store.history, `+${store.step} -> ${store.count}`];
+      },
+      decrement() {
+        store.count = store.count - store.step;
+        store.history = [...store.history, `-${store.step} -> ${store.count}`];
+      },
+      reset() {
+        store.count = 0;
+        store.history = [...store.history, "Reset -> 0"];
+      },
+      setStep(val: number) {
+        store.step = val;
+      },
+      clearHistory() {
+        store.history = [];
+      },
+      registerObservers() {
+        // Inner observe (no view binding) for store-internal reactions
+        store.observe(undefined, ["step"], () => {
+          store.count = 0; // Reset count when step changes
+        });
+      },
+    };
+  },
+);
 
-    increment() {
-      store.count = store.count + store.step;
-      store.history = [...store.history, `+${store.step} -> ${store.count}`];
-    },
-    decrement() {
-      store.count = store.count - store.step;
-      store.history = [...store.history, `-${store.step} -> ${store.count}`];
-    },
-    reset() {
-      store.count = 0;
-      store.history = [...store.history, "Reset -> 0"];
-    },
-    setStep(val: number) {
-      store.step = val;
-    },
-    clearHistory() {
-      store.history = [];
-    },
-  };
+export default useCountStore;
+```
+
+**Creator function signature**: `(store, apis) => initialState`
+
+- `store` — InnerStore proxy for reading/writing reactive state. Reads return the raw reactive Proxy; writes through `store.key = value` trigger dependency tracking
+- `apis` — `{ lazySet, shallowSet }` utility functions:
+  - `lazySet(target, data)` — Batch-set properties without triggering observers (used during `createState` initialization)
+  - `shallowSet(target, key, data)` — Create a shallow reactive sub-state where only top-level property changes trigger observers
+
+### Standalone Reactive Cells
+
+For simple reactive data that doesn't need the full store pattern, use `cell` and `observeCell`:
+
+```typescript
+import { cell, observeCell } from "@lark.js/mvc";
+
+// Create a standalone reactive cell
+const count = cell(0);
+
+// Observe changes
+const unobserve = observeCell(count, () => {
+  console.log("count changed:", count.count);
 });
 
-export default useCountStore;
+// Mutate (triggers observer)
+count.count = 1;
+
+// Clean up
+unobserve();
 ```
 
-creator 函数接收两个参数: store 是 Proxy 代理对象, 可以读写 state, 也可以调用 observe 注册 state 改变时的 callback; apis 可以解构得到 lazySet 和 shallowSet 两个工具方法
+`cell(data)` creates a Proxy-based reactive state with `belong: "lark-global"` and a unique `linkKeys`. `observeCell(state, cb, immediate?)` tracks changes and calls `cb` when any property changes. By default `immediate = true` (fires callback immediately).
+
+### Multi-Instance Stores
 
-3. 创建 View
+When a component is used multiple times on the same page and each instance needs independent state, use `multi`:
+
+```typescript
+import { defineStore, multi } from "@lark.js/mvc";
 
-View.extend(props) 创建视图子类, 模板属性 template 引用编译后的 HTML 模板函数, init 方法中通过 useStore(this) 获取 store 实例并绑定视图生命周期, store.observe(this, keys) 声明观察的状态键
+const useCounterStore = defineStore("counter", (store) => ({
+  count: 0,
+  increment() {
+    store.count++;
+  },
+}));
 
-事件方法的方法名格式为 name<eventType>, 例如 increment<click> 对应模板中的 v-click="increment()", 编译时自动编码 View ID, 运行时由 EventDelegator 解析分发
+// multi() returns [useFn, mixinObj]
+const [useMultiCounter, counterMixin] = multi(useCounterStore);
+
+// In the view:
+export default View.extend({
+  mixins: [counterMixin], // make() generates per-instance flag
+  template,
+  init() {
+    const store = useMultiCounter(this); // Each view instance gets its own store clone
+    store.observe(this, ["count"]);
+  },
+});
+```
+
+`multi()` works by intercepting `mountFrame` calls to propagate a per-instance flag (`lark-comp-{storeName}`) down the Frame tree. When `useFn(view)` is called, it checks the flag and either returns an existing store clone or creates one via `cloneStore()`.
+
+### 7. Create a View with Template
 
 ```typescript
+// src/views/home.ts
 import { Router } from "@lark.js/mvc";
 import View from "../view";
-import template from "./counter.html";
+import template from "./home.html";
 import useCountStore from "../store/count";
 
 export default View.extend({
-  // const template: (data: unknown, selfId: string, refData: unknown) => string;
   template,
 
   init() {
+    this.assign();
+
+    // Observe count store -- changes trigger automatic view re-render
     const store = useCountStore(this);
-    store.observe(this, ["count", "step", "history"]);
+    store.observe(this, ["count", "step"]);
   },
 
-  "increment<click>"() {
-    useCountStore().increment();
-  },
+  assign() {
+    this.updater.snapshot();
+
+    const store = useCountStore();
+    this.updater.set({
+      title: "Home",
+      count: store.count,
+      step: store.step,
+    });
 
-  "decrement<click>"() {
-    useCountStore().decrement();
+    return this.updater.altered();
   },
 
-  "reset<click>"() {
-    useCountStore().reset();
+  render() {
+    this.updater.digest();
   },
 
-  "stepChange<change>"(e: Event) {
-    const target = e.target as HTMLInputElement;
-    const newStep = parseInt(target.value) || 1;
-    useCountStore().setStep(newStep);
+  "navigateTo<click>"(e: Record<string, unknown>) {
+    const params = e["params"] as Record<string, string> | undefined;
+    const path = params?.path;
+    if (path) Router.to(path);
   },
 });
 ```
 
-4. 创建模板
-
-模板使用 {{}} 语法, = 表示 HTML 转义输出, v-click 等属性绑定事件, 编译时自动将 View ID 和参数编码到事件属性值中
+### 8. Write Templates
 
 ```html
+<!-- src/views/home.html -->
 <div>
-  <div>{{=count}}</div>
-  <input type="number" value="{{=step}}" v-change="stepChange()" />
-  <button v-click="decrement()">-{{=step}}</button>
-  <button v-click="reset()">Reset</button>
-  <button v-click="increment()">+{{=step}}</button>
+  <h1>{{=title}}</h1>
+  <div>Count: {{=count}}</div>
+  <button @click="navigateTo({path: '/about'})">About</button>
 
-  {{if history.length > 0}}
-  <ul>
-    {{each history as record}}
-    <li>{{=record}}</li>
-    {{/each}}
-  </ul>
+  {{if count > 0}}
+  <p>Positive</p>
   {{else}}
-  <p>No history</p>
+  <p>Zero or negative</p>
   {{/if}}
+
+  <ul>
+    {{forOf items as item idx}}
+    <li>{{=idx}}: {{=item}}</li>
+    {{/forOf}}
+  </ul>
+
+  <!-- Sub-view embedding -->
+  <div v-lark="components/child"></div>
 </div>
 ```
 
-5. 启动应用
-
-通过 registerViewClass 注册 View 类, 配置 routes 路由映射, 调用 Framework.boot(config) 启动框架
+### 9. Bootstrap the Application
 
 ```typescript
-import { Framework, View, registerViewClass } from "@lark.js/mvc";
-import HomeView from "./src/views/home";
-import CounterView from "./src/views/counter";
-
+// src/boot.ts
+import { Framework, Router, View, registerViewClass } from "@lark.js/mvc";
+import type { FrameworkConfig } from "@lark.js/mvc";
+import HomeView from "./views/home";
+import AboutView from "./views/about";
+import CounterView from "./views/counter";
+import NotFoundView from "./views/404";
+import CounterStoreComponent from "./components/counter-store";
+import CounterUpdaterComponent from "./components/counter-updater";
+
+// Register View classes to Frame
 registerViewClass("home", HomeView as typeof View);
+registerViewClass("about", AboutView as typeof View);
 registerViewClass("counter", CounterView as typeof View);
-
-Framework.boot({
+registerViewClass("404", NotFoundView as typeof View);
+registerViewClass(
+  "components/counter-store",
+  CounterStoreComponent as typeof View,
+);
+registerViewClass(
+  "components/counter-updater",
+  CounterUpdaterComponent as typeof View,
+);
+
+const config: FrameworkConfig = {
   rootId: "app",
   defaultPath: "/home",
   defaultView: "home",
   routes: {
     "/home": "home",
+    "/about": "about",
     "/counter": "counter",
   },
   unmatchedView: "404",
   error(e: Error) {
-    console.error("Lark application error:", e);
+    console.error("Lark error:", e);
   },
-});
-```
-
-核心模块
-
-Framework — 框架主入口
-
-Framework 是 Lark 框架的主入口对象, 提供 boot() 启动方法与全局工具方法
-
-boot() 启动流程如下:
-
-1. 合并配置 (rootId, defaultView, routes, hashbang 等)
-2. `Router._setConfig()` 注入路由配置
-3. `EventDelegator.setFrameGetter()` 注入 Frame 查找器
-4. 绑定 Router 的 changed 事件到 `dispatcherNotifyChange()`
-5. 绑定 State 的 changed 事件到 `dispatcherNotifyChange()`
-6. `Frame.root(rootId)` 创建根 Frame 节点
-7. `Router._bind()` 绑定 hashchange 事件, 执行首次 diff
-8. 如果路由没有已挂载的视图, 则 `rootFrame.mountView(defaultView)` 挂载默认视图
-
-Framework 还提供以下工具方法
-
-- mark/unmark 异步回调追踪
-- dispatch 自定义 DOM 事件
-- task 分片任务调度
-- delay Promise 延时
-- use 模块加载
-- toMap/toTry/toUrl/parseUrl/has/keys/inside/node/guard/applyStyle 等工具函数
-- Cache, Base, Router, State, View, Frame 等模块的直接访问
-
-callFunction 分片执行
-
-```ts
-let callIndex = 0;
-// 扁平存储: [fn, ctx, args, fn2, ctx2, args2, ...]
-const callList = [];
-// 每片最大执行时间 48ms
-const callBreakTime = 48;
-
-function startCall() {
-  const last = Date.now(),
-    next;
-  while (true) {
-    next = callList[callIndex - 1];
-    // 依次取出函数执行
-    if (next) {
-      next.apply(callList[callIndex], callList[callIndex + 1]);
-      callIndex += 3; // 每次消费 3 个元素: fn/ctx/args
-      // 每执行一个函数都会检查一次耗时
-      if (Date.now() - last > callBreakTime && callList.length > callIndex) {
-        setTimeout(startCall); // 超时则让出主线程
-        break;
-      }
-    } else {
-      callList.length = callIndex = 0; // 全部执行, 清空
-      break;
-    }
-  }
-}
-
-function callFunction(fn, args, ctx) {
-  callList.push(fn, ctx, args); // 入队
-  if (!callIndex) {
-    // 如果没有在执行中
-    callIndex = 1;
-    setTimeout(startCall); // 异步启动
-  }
-}
+};
 
-Framework.task = callFunction;
+Framework.boot(config);
 ```
 
-- 入队: callFunction(fn, args, ctx) 不是立刻执行, 而是将 fn、ctx、args 扁平 push 到 callList
-- 异步启动: 通过 setTimeout(startCall) 推迟到下一个事件循环开始执行
-- 分片执行: startCall 在 while 循环中, 依次取出函数执行, 每执行一个函数都会检查一次耗时
-
-这是早期前端的长任务分片实践，用于
-
-- 避免一次性执行大量回调, 例如大量 View 渲染完成后的通知导致页面卡顿
-- 保持 60fps (每帧约 16ms, 48ms 约占 3 帧) 的用户交互响应
-- 与 requestIdleCallback 的思路类似, 但 callFunction 设计时浏览器可能还没有该 API
+## Key Patterns
 
-优化
+### Event Method Naming
 
-任务调度: `Framework.task(fn, args, context)` 提供分片执行能力, 调度优先级为
+Event handlers use the `name<eventType>` pattern. The framework scans the View prototype at class preparation time (in `View.prepare()`) and builds three event maps on the prototype: `$evtObjMap`, `$selMap`, `$globalEvtList`.
 
-- `scheduler.postTask('background')` Chrome 94+
-- `requestIdleCallback` Chrome 47+
-- `setTimeout(0)` 通用 fallback 方案
+| Pattern                    | Meaning                                           |
+| -------------------------- | ------------------------------------------------- |
+| `handler<click>`           | Root event on the view element                    |
+| `$selector<click>`         | Delegated event matching CSS selector `.selector` |
+| `$window<resize>`          | Global event on `window`                          |
+| `$document<keydown>`       | Global event on `document`                        |
+| `handler<click,mousedown>` | Multi-event binding                               |
 
-使用 `requestIdleCallback` 时依据 `deadline.timeRemaining()` 自适应确定每片执行数量, 回退到 setTimeout 时使用固定 48ms 时间片
+All DOM events are delegated to `document.body` using **capture-phase** listeners (`addEventListener(type, handler, true)`). The EventDelegator uses reference counting: the first binding adds the listener, the last unbinding removes it. On event dispatch, the processor walks up the DOM from the target to `document.body`, checking `@<eventType>` attributes and selector matches at each level.
 
-|                | callFunction                           | task                                                  |
-| -------------- | -------------------------------------- | ----------------------------------------------------- |
-| 调度 API       | setTimeout                             | scheduler.postTask → requestIdleCallback → setTimeout |
-| 时间切片       | 固定 48ms                              | 自适应 deadline.timeRemaining() + 48ms fallback       |
-| 接口签名       | 扁平数组 [fn, ctx, args, ...] 逐个消费 | 相同保持兼容性                                        |
-| 让出主线程时机 | 仅超时                                 |                                                       |
+The event object passed to handlers contains:
 
-Router — hash 路由器
+- `e.eventTarget` -- the actual DOM element that was clicked
+- `e.params` -- parsed parameters from `@event` attributes (URL query string format)
+- Standard DOM Event properties (`type`, `target`, etc.)
 
-Router hash 路由器基于 location.hash, 支持 #! 前缀的 hashbang 模式
+When two mixins define the same event method, they are merged into a single function that calls both in sequence via a `handlerList` array.
 
-路由变更使用两阶段确认
+### Store Observe Variations
 
-1. change 阶段: 用户可以调用 `prevent()` 取消路由跳转, 或调用 `reject()` 回退到旧 URL, 类似 beforeunload
-2. changed 阶段: 路由改变完成后触发, 通知 Dispatcher 派发器更新视图
-
-核心 API:
+```typescript
+// Simple: auto-digest on key change
+store.observe(this, ["count", "step"]);
 
-- `Router.parse(href?)`: 将 href 解析为 Location 对象, 包含 path, params, query, hash 等字段; 解析结果被 hrefCache 缓存, 相同 href 不重复解析
-- `Router.diff()`: 计算新旧 Location 的差异 LocationDiff 对象, 包括参数键值对变化和路径/视图变化, 计算结果被 changedCache 缓存; 如果检测到变更且并且不是 silent 静默模式, 则触发 changed 事件
-- `Router.to(pathOrParams, params?, replace?, silent?)`: 编程式导航, 支持字符串路径或参数对象形式; 支持历史记录替换与 silent 静默更新
-- `Router.join(...paths)`: 拼接路径, 处理 ./ , ../ , // 等路径规范
+// With custom callback
+store.observe(this, ["count"], (changedMap) => {
+  console.log("count changed", changedMap);
+});
 
-Location 对象结构
+// With ObservePayload for fine-grained control
+store.observe(this, [
+  { key: "count", alias: "currentCount", lazy: false },
+  { key: "items", transform: (val) => ({ itemCount: val.length }) },
+]);
 
-```ts
-export interface Location {
-  /** 完整 URL */
-  href: string;
-  /** 查询字符串 */
-  srcQuery: string;
-  /** hash 字符串 */
-  srcHash: string;
-  /** 查询参数 */
-  query: ParsedUri;
-  /** 哈希参数 */
-  hash: ParsedUri;
-  /** 合并参数 */
-  params: Record<string, string>;
-  /** 视图路径 */
-  view?: string;
-  /** 路由路径 */
-  path?: string;
-  /** 参数读取函数 */
-  get: (key: string, defaultValue?: string) => string;
-}
-```
+// Inner observe (no view binding, for store-internal reactions)
+store.observe(undefined, ["step"], () => {
+  store.count = 0; // Reset count when step changes
+});
 
-LocationDiff 对象结构
-
-```ts
-export interface LocationDiff {
-  /** 变更参数映射 */
-  params: Record<string, ParamDiff>;
-  /** 路径变更 */
-  path?: ParamDiff;
-  /** 视图变更 */
-  view?: ParamDiff;
-  /** 是否首次强制变更 */
-  force: boolean;
-  /** 是否有变更 */
-  changed: boolean;
-}
+// Lazy observe (default: true) -- triggers updater.digest() on change
+// Non-lazy observe (lazy: false) -- triggers updater.set() then digest()
+// This means lazy: true merges data via digest(), lazy: false sets data first
 ```
 
-beforeunload 事件支持: 监听 window 的 beforeunload 事件, 若监听器设置了 msg 字段, 浏览器弹出离开确认对话框
-
-调试模式下, Location.params 和 LocationDiff 会被 safeguard() Proxy 包装, 拦截非法写入
-
-State — 跨视图 observable 数据
+### Store Read/Write Behavior
 
-State 是全局单例的数据对象, 用于跨视图共享状态; View 通过 `observeState(keys)` 声明观察的键, State 改变时仅通知观察了相关键的视图
+The `useStore()` function returns a Proxy that separates state reads from handler access:
 
-核心流程:
+- **Reading state keys** (e.g., `store.count`) — returns a deep-cloned copy of the value (frozen for React adapter). This prevents external mutation of reactive state
+- **Writing state keys** (e.g., `store.count = 5`) — sets the value on the internal reactive state, triggering dependency tracking
+- **Accessing handlers** (e.g., `store.increment()`) — calls the function defined in the creator
+- **Inside the creator**, `store.count` reads the raw reactive Proxy (no cloning), enabling direct mutation and reactivity
 
-1. `State.get(key)` 读取数据; State.set(data) 写入数据并标记变更键
-2. `State.digest()` 触发变更通知: 将变更键传递给 Dispatcher, Dispatcher 沿 Frame 树查找观察了这些键的 View 并触发重新渲染
-3. `State.diff()` 返回上次 digest 的变更键映射
+The store uses a microtask-based `Queue` scheduler (Promise.resolve().then()) for batching observer callbacks. Multiple state changes in the same synchronous block are batched and processed in a single microtask.
 
-键引用计数: 当 View 调用 observeState(keys) 时, 通过 setupKeysRef 对这些键建立引用计数; 当 View 销毁时, 通过 teardownKeysRef 递减引用计数; 当某个键的引用计数降为 0 时, 自动从 State 中删除该键的数据, 避免内存泄漏
+### Router Two-Phase Change
 
-调试模式: 当 `window.__lark_Debug` 为 true 时, State 数据会使用 safeguard() Proxy 包装, 拦截非法写入并追踪访问来源
+Route changes go through two phases:
 
-Store — 响应式状态管理
-
-Store 模块基于 Proxy 实现深度响应式状态管理, 支持多平台适配 (Lark / React / Node), 提供 defineStore 定义 store 与自动依赖追踪
-
-createState 响应式状态底层实现
-
-`createState(data, config?)` 接收一个普通 JS 对象, 返回 Proxy 包装的代理对象 (响应式状态). Proxy 的 get 拦截器执行 track(depKey, effect) 收集依赖, set 拦截器执行 trigger(depKey) 触发更新. 依赖追踪通过全局 `GlobalDeps` Map 实现: key 为 SPLITTER + depKey (例如如 \x1ecount), value 为 effect 函数的 Set 集合
-
-当读取到对象或数组类型的属性值时, 递归调用 createState 包装, 实现深层响应式. 对于数组, 代理了 indexOf, includes, push, pop, splice, shift, unshift, sort, reverse 等方法, 使得数组操作也能触发响应式更新
-
-defineStore — 定义 store
-
-Store 模块使用 defineStore 定义 store 实例，通过 observe 建立 store 与 view 的响应式绑定, 状态改变时自动触发回调, 不需要手动调用 `updater.digest()`
+1. **`change` event** -- listeners can call `prevent()` or `reject()` to cancel navigation
+2. **`changed` event** -- URL has been updated, views are re-rendered
 
 ```typescript
-function defineStore<S>(
-  name: string,
-  creator: (store: InnerStore<S>, apis: { lazySet; shallowSet }) => S,
-  // config.platform 指定平台: Platform.Lark (默认), Platform.React, Platform.Node
-  config?: StoreConfig,
-): LarkUseStore<S> | ReactUseStore<S> | NodeUseStore<S>;
-```
-
-### store 生命周期
-
-defineStore 返回 useStore 函数, 内部维护三个状态: IDLE 未使用、ACTIVE 已激活、DESTROYED 已销毁
-
-- 首次调用 `useStore(view)` 时激活 store, store 进入 ACTIVE 状态并执行 creator
-- 所有绑定的 View 销毁后, store 自动进入 DESTROYED 状态
-- 重新调用 useStore(view) 时会重新执行 creator 创建新的 store 实例
-
-LarkStore: observe(view, keys, defCallback?) 绑定视图生命周期
-
-```ts
-store.observe(
-  // 传递 view 实例时, 状态变更时自动调用 updater.set()、updater.digest()
-  // 传递 undefined 时, 不绑定 view, 仅注册内部监听
-  view: View | undefined,
-  // 监听的键列表, 支持字符串和 ObservePayload 对象
-  keys: (string | ObservePayload)[],
-  // 可选, 回调函数, 默认为 updater.digest
-  defCallback?: (changedMap) => void,
-): () => void
-```
-
-```ts
-interface ObservePayload {
-  key: string; // 监听的键, 支持 a.b 路径
-  alias?: string; // 别名
-  cb: (changedMap) => void; // 自定义回调函数
-  lazy?: boolean; // 是否延迟执行, 默认 true
-  transform?: (val) => object; // 状态派生函数
-}
+Router.on("change", (e) => {
+  if (hasUnsavedChanges) {
+    e.prevent(); // Cancel navigation
+  }
+});
 ```
 
-ReactStore
-
-- 使用 `freezeData()` 冻结数据, 生成不可变快照, 适配 React 的不可变数据模式
-- 每次状态变更后生成新的快照, 确保引用变化以触发 React 组件重渲染
-
-NodeStore: observe 直接执行回调, 不绑定视图生命周期, 适用于 Node.js 环境下的状态管理
+### Resource Management
 
-_lazySet — 批量懒更新_
+Use `capture/release` for automatic cleanup:
 
-`lazySet(target, data)` 批量设置多个属性值, 不触发任何响应式通知. 内部通过 curLazySetKey 标记正在 lazySet 的属性 key, Proxy set 拦截器检测到匹配时跳过 trigger
-
-_shallowSet — 浅层响应式_
-
-`shallowSet(target, key, data)` 创建浅层响应式状态: 只有顶层的 key 变化才触发 trigger, 内部嵌套对象的变化不触发
-
-_cell / observeCell — 独立的响应式数据_
-
-- cell(data) 创建独立的响应式数据
-- observeCell(state, cb, immediate?) 监听 cell 变更
-
-cell 本质上是 createState 的轻量封装, 适用于不依赖 View 生命周期的独立的响应式数据
-
-_multi — 多实例 store_
-
-multi(useStore) 创建支持多实例的 store, 内部通过 flag 标识不同的 View, 首次调用时为每个 flag 克隆一个新的 store 实例 (cloneStore), 每个 store 拥有独立的 storeName 和状态. flag 通过拦截 mountFrame 沿 Frame 树向下传播, 确保同一个 Frame 树共享同一个 store 实例, 不同 Frame 树使用独立的 store 实例
-
-- `getStore(name)` / `delStore(name)` / `cloneStore(name, useStore, config?)` 按 store 名称获取、删除、克隆 store 实例
-- `isStoreActive(name)` 检查 store 是否处于 ACTIVE 状态
-- `isState(target)` 检查对象是否为 Proxy 响应式状态
-
-## Frame — 视图生命周期树
-
-Frame 是管理 View 生命周期的容器, 与 DOM 结构对应组成 Frame 树; 每个 Frame 拥有一个 View 实例, 负责挂载、卸载、子区域管理和方法调用
-
-Frame 树的设计思路
-
-- Frame 树与 DOM 树结构相同, 每个 Frame 节点对应一个 DOM 元素 (通过 ID 关联)
-- Frame 对象挂载到 DOM 元素的 frame 属性上 [frame.ts](./src/frame.ts#L130)
-
-这种设计使得 DOM 操作 (例如 VDOM diff) 可以直接通过 Frame 找到对应的 View, 也使得 View 事件处理可以沿 Frame 树向上冒泡
-
-```js
-const app = document.getElementById("app");
-// app.frame
-const frame = {
-  id: "app", // frameId, 与 DOM 元素 ID 相同
-
-  parentId: undefined, // rootFrame 没有父节点
-
-  // childrenCount: 子 frame 数量
-  childrenCount: 2, // 有 2 个子 frame
-
-  // 已触发 created 事件的子 frame 数量
-  readyCount: 2, // 2 个子 frame 已触发 created 事件
-
-  // 所有子 frame 是否已触发 created 事件
-  childrenCreated: 1,
-
-  // 子 frameId 映射
-  childrenMap: {
-    frame_0: "frame_0", // 对应 lark-view="components/counter-store"
-    frame_1: "frame_1", // 对应 lark-view="components/counter-updater"
+```typescript
+const timer = setInterval(() => {
+  /* ... */
+}, 1000);
+this.capture(
+  "myTimer",
+  {
+    destroy() {
+      clearInterval(timer);
+    },
   },
-
-  // readyMap 已 ready 的子 frame 集合
-  // hasAltered 子 frame 是否被修改
-  // signature 异步操作签名
-  // invokeList 延迟方法调用列表
-  // originalTemplate 挂载前的原始 html
-};
+  true,
+);
+// destroyOnRender=true: destroyed on next render call
+// destroyOnRender=false: destroyed only on view destroy
 ```
 
-核心方法
-
-- `mountView(viewPath, viewInitParams?)`: 查找 View 类、实例化、执行 `init()` 和 `render()`, 将 HTML 注入 DOM
-- `unmountView()`: 销毁 View 以及所有子 Frame, 清理事件绑定与资源
-- `mountFrame(frameId, viewPath, viewInitParams?)`: 挂载子 Frame, 复用对象池中的 Frame 或创建新 Frame
-- `unmountFrame(id?)`: 卸载子 Frame, 归还 Frame 对象到对象池
-- `mountZone(zoneId?)` / `unmountZone(zoneId?)`: 管理区域内的 lark-view 子视图, 区域内的子 Frame 在 mountZone 时批量创建
-- `invoke(name, args?)`: 沿 Frame 树广播方法调用; 如果 View 已渲染则直接调用, 否则加入 invokeList 延迟执行
-- `children()`: 返回所有子 Frame ID 列表
-- `parent(level?)`: 获取指定层级的父 Frame
-
-对象池: Frame 对象使用 frameCache 数组作为对象池, unmountFrame 时将 Frame 归还池中, mountFrame 时优先从池中取出复用, 避免频繁 GC
-
-事件通知: notifyCreated 与 notifyAlter 事件沿 Frame 树向上冒泡, 当所有子 Frame 就绪时触发 created 事件, 子 Frame 发生变化时触发 alter 事件. holdFireCreated 标志用于批量挂载时延迟触发 created 事件. 这些事件用于 waitZoneViewsRendered() 等待子视图就绪
-
-translateQuery: 当 viewPath 包含 SPLITTER 引用时, 通过父视图的 refData 解析引用参数, 实现父视图向子视图传递对象引用
-
-registerViewClass(viewPath, ViewClass): 注册 View 类到 viewClassRegistry, 提供给 mountView 查找
-
-View — 视图基类
-
-View 视图基类负责用户交互, 提供数据绑定、事件处理、生命周期与视图继承能力
+### Async Safety with wrapAsync
 
-_视图继承_
-
-- `View.extend(props)`: 创建视图子类, 内部使用 ES6 class extends 实现原型链继承. extend props 作为实例属性在 super() 之后调用, 避免 ES6 class 字段遮蔽 (shadow) 问题. 子类构造函数签名: `(nodeId, ownerFrame, initParams, node, mixinCtors)`
-- `View.merge(mixin)`: 混入功能到 View 原型, 事件方法以 MixinEventHandler 形式合并, 保留原始 handler 列表
-
-解析事件方法 (viewPrepare): 扫描 View 原型上的方法名, 匹配 `$?name<eventType>(<modifiers>)` 模式, 例如 `clickHandler<click>` 自动绑定 click 事件到 `clickHandler` 方法, `$menu<hover>` 绑定带选择器的事件. 解析结果构建 eventObjectMap (事件类型到位掩码的映射) 与 eventSelectorMap (事件类型到处理器名称列表的映射). 修饰符支持如 `<click,mousedown>` 绑定多个事件类型
-
-```js
-// window 上监听 resize
-"$window<resize>"(e) {}
-
-// document 上监听 keydown
-"$document<keydown>"(e) {}
-
-// 点击 .btn 元素时触发
-"$btn<click>"(e) {}
+```typescript
+async loadData() {
+  const safeCallback = this.wrapAsync((data) => {
+    this.updater.set({ items: data }).digest();
+  });
+  const data = await fetch("/api/items").then(r => r.json());
+  safeCallback(data); // Only executes if view has not been re-rendered/destroyed
+}
+```
 
-// hover .tooltip 元素时触发
-"$tooltip<mouseenter>"(e) {}
+### Sub-View Embedding
 
-// $ 后面的 CSS 选择器为空时, 默认选择 frame 根节点
-// 点击 frame 根节点时触发
-"$<click>"(e) {}
-```
+Use the `v-lark` attribute to embed child views:
 
 ```html
-<button class="btn">只需要写 CSS 类名</button>
-<div class="tooltip">不需要写 v-event, 适用于批量绑定</div>
+<div v-lark="components/child-view"></div>
 ```
 
-事件委托 (viewDelegateEvents): 将 View 的 eventObjectMap 和 eventSelectorMap 注册到 EventDelegator, 全局事件类型 (如 click, change) 绑定到 document.body, 选择器事件通过 matches() API 匹配; 同时处理 window/document 前缀的全局事件 (例如 resize, scroll), 绑定到 window/document
-
-_生命周期方法_
-
-- `make()`: 构造函数, View 实例创建时调用
-- `init(options)`: 初始化, 接收路由参数与传入数据; 返回 Promise 对象时, 框架会等待该 Promise 对象 resolve 后再执行 render
-- `render()`: 渲染方法, 内部调用 `updater.digest()` 生成 HTML 并执行 VDOM diff 更新 DOM; render 被 `viewWrapMethod` 包装, 包装函数会: 检查 signature 有效性, 递增 signature, 执行资源清理 (destroyOnRender), 调用 unmark 使旧的异步回调失效, 调用 `assign(])` 判断是否可以跳过完整渲染
-- `assign(options)`: 响应式更新模式, 仅当 assign() 返回 true 时跳过完整渲染, 执行增量更新
-
-> Lark 渲染管线对比 react 渲染管线
-
-- react 渲染管线: state 变化 → 生成 VDOM 树 (JS 对象树) → 与旧 VDOM 树 diff → 计算最小 DOM 操作 → 批量提交; react 始终操作 JS 对象, 没有生成 HTML 字符串
-- lark 渲染官宣: state 变化 → 调用模板函数生成 HTML 字符串 → 解析为真实 DOM → 与页面上真实 DOM 做 diff → 收集 DOM 操作 → 批量提交
-
-Lark 框架的 diff 算法是真实 DOM diff, 只是真实 DOM 不在页面上
-
-_数据观察_
-
-- `observeLocation(keys, observePath?):` 声明关注的路由参数键, 路由变更时如果匹配的键发生变化, 则自动触发 View 重新渲染
-- `observeState(keys)`: 声明关注的 State 键, State 变更时如果匹配的键发生变化, 则自动触发 View 重新渲染; keys 是逗号分隔的字符串
-
-_资源管理_
-
-- `capture(key, resource?, destroyOnRender?)`: 注册资源到 View, 当 View 重新渲染时自动销毁有 destroyOnRender 标记的旧资源
-- `release(key, destroy?)`: 手动释放资源
-
-_异步安全_
-
-- `wrapAsync(fn, context?)`: 包装异步回调, 通过 `mark()` 生成签名校验函数, View 销毁或重新渲染后 (unmark) 回调不会执行; wrapAsync 检查当前 signature 是否与调用时一致
-- `leaveTip(message, condition):` 页面离开提示, 条件不满足时阻止跳转; 监听 Router 的 change 事件和 window 的 beforeunload 事件
-
-Updater — 数据绑定与 VDOM diff
-
-每个 View 持有一个 Updater 实例, 管理视图数据并触发渲染
-
-核心流程
-
-1. `updater.set(data, excludes?)`: 写入数据到内部 refData ($a), 记录变更键; excludes 排除变更检测的键集合
-2. `updater.digest(data?, excludes?)`: 触发渲染管线:
-   - 如果传入了 data, 则先调用 `set(data, excludes)`
-   - 调用模板函数 `template(refData, viewId, refData)` 生成 HTML 字符串
-   - 通过虚拟文档 (vdomGetNode) 解析 HTML 为 DOM 节点
-   - 执行 VDOM diff (vdomSetChildNodes) 实际上是真实 DOM diff, 计算最小 DOM 操作集
-   - 调用 `applyIdUpdates()` 批量更新元素 ID
-   - 调用 `applyVdomOps()` 批量执行 DOM 操作
-   - 通知 Frame 处理新增的 lark-view 子视图 (mountZone)
-3. `updater.snapshot()`: 保存当前数据的 JSON 快照
-4. `updater.altered()`: 检测数据是否与上次快照不同 (通过 JSON.stringify 比较)
-5. `updater.get(key?)`: 获取数据, 不传递 key 则返回完整数据对象
-
-refData ($a): 模板函数中的引用对象 (例如循环中的列表项) 通过 refData 存储, 使用 SPLITTER 前缀的数字键索引 (例如 \x1e0, \x1e1). `updaterRef()` 负责去重查找与分配: 遍历 refData 中的 SPLITTER 前缀键, 查找值等于目标对象的已有键, 如果找到则复用, 否则分配新键
-
-digestingQueue: 支持 digest 执行过程中再次调用 digest (重新渲染), 通过 digestingQueue 队列管理, 使用 null 哨兵分隔每次 digest 的数据, 当外层 digest 结束后处理队列中的待执行 digest
-
-模板内置编码函数: $e (HTML 实体编码), $n (null 安全的 toString), $eu (URI 编码), $eq (引号编码), $i (引用查找, 用于 {{@}} 运算符)
-
-VDOM Diff Engine — 虚拟 DOM (实际上是真实 DOM) 差量比较引擎
-
-虚拟 DOM 差量比较引擎, 将新旧 DOM 树对比, 输出最小操作集
-
-核心算法:
-
-- `vdomSetNode(oldNode, newNode, parent, ref, frame, keys?)`: 对比单个节点. 先执行 vdomSpecialDiff 处理表单元素, 再通过 isEqualNode 判断节点是否相同. 如果节点类型和名称相同, 则分别对比属性 (vdomSetAttributes) 和子节点 (vdomSetChildNodes); 如果节点类型不同, 则生成 replaceChild 操作. 对于有 lark-view 属性的元素, 如果新旧 view 路径相同则跳过子节点更新, 保护已挂载的子视图
-- `vdomSetChildNodes(oldParent, newParent, ref, frame, keys?)`: 对比子节点列表, 支持 keyed diff. 算法: 先从旧子节点构建 keyedNodes 映射 (键由 vdomGetCompareKey 获取, 优先级 id > lark-key > lark-view 路径), 同时统计新子节点的 keyed 计数; 再遍历新子节点, 通过 keyed 匹配查找旧节点, 匹配成功则将旧节点移动到正确位置并递归 diff, 匹配失败则生成 appendChild 操作; 最后移除多余的旧节点
-- `vdomSetAttributes(oldNode, newNode, ref, keepId?)`: 对比元素属性. 删除新节点中不存在的旧属性, 添加/更新新节点中的属性. id 属性变更记录到 idUpdates 数组而不是直接修改, 因为 id 变更可能影响事件委托. 每次对比前清除 compareKeyCached 缓存
-- `vdomSpecialDiff(oldNode, newNode)`: 处理 input (value, checked), textarea (value), option (selected) 等特殊元素, 直接同步 DOM 属性值, 绕过 setAttribute
-
-比较键 (vdomGetCompareKey): 用于 keyed diff 的节点标识, 优先级: id 属性 > lark-key 属性 > lark-view 路径. 有 autoId 标记的元素不使用 id 作为比较键. 比较键结果缓存到元素的 compareKeyCached / cachedCompareKey 属性
-
-静态跳过: 有 lark-key 属性且值相同的元素跳过 diff; 有 lark-attr-key 属性且值相同的元素跳过属性更新
-
-DOM 操作编码为数字操作码:
-
-- 1 = `appendChild(parent, newChild)`
-- 2 = `removeChild(parent, oldChild)`
-- 4 = `replaceChild(parent, newChild, oldChild)`
-- 8 = `insertBefore(parent, newChild, refChild)`
-
-`applyVdomOps(ops)` 批量执行操作码, `applyIdUpdates(updates)` 批量更新元素 ID (用于事件委托选择器匹配)
-
-HTML 解析: `vdomGetNode(html, refNode)` 使用 `document.implementation.createHTMLDocument()` 创建虚拟文档, 通过 WrapMeta 映射处理 table, select, SVG, MathML 等需要特定父元素的标签 (例如 thead 需要包在 `<table>` 中, td 需要 `<table>, <tbody>, <tr>`). 自动检测 refNode 的 namespaceURI, SVG 命名空间使用 `<g>` 包裹, MathML 使用 `<math>` 包裹
-
-编码工具函数: encodeHTML (HTML 实体编码), encodeSafe (null 安全的字符串转换), encodeURIExtra (URI 编码), encodeQ (引号编码)
-
-EventDelegator — DOM 事件委托
-
-所有 DOM 事件委托到 document.body, 通过事件冒泡机制捕获. 每个 View 的 v-event 属性在编译时编码为 viewId\x1ehandlerName(params) 格式, 运行时由 EventDelegator 解析并分发
-
-核心机制:
-
-- `bind(eventType, selector?)`: 注册事件类型到 document.body, 选择器事件使用事件委托匹配; 同一事件类型只注册一次全局监听器
-- `domEventProcessor(event)`: 事件处理入口, 从目标元素向上遍历 DOM 树查找 v-event 属性, 解析得到 View ID 与处理器名称; 解析使用 EVENT_METHOD_REGEX 正则, 捕获 Frame ID (可选), handler 名称, 参数字符串
-- `findFrameInfo(element)`: View 边界检测, 从目标元素向上查找, 当遇到已绑定的 Frame 元素时停止, 确保事件不会跨 View 传播. 通过 rangeFrameId 属性标记 View 边界, 事件冒泡到边界时停止搜索
-- `clearRangeEvents(frameId)`: 清除指定 View 范围内的事件标记
-
-事件信息缓存: 解析后的事件信息存入 Cache 缓存, 避免重复解析属性值; Cache 使用 SPLITTER 前缀键实现命名空间隔离
-
-选择器事件: 方法名中 $ 前缀标识选择器事件 (例如 `$menu<hover>`), 编译时将选择器名称编码到 eventSelectorMap, 运行时通过 `element.matches(selector)` API 匹配, 支持 CSS 选择器语法
-
-Range 事件: 通过 lark-view-key 属性标记 View 边界, 事件处理时检查 rangeFrameId, 确保只在对应 View 的 DOM 范围内查找事件处理器
-
-Service + Bag — 接口请求管理
-
-Service 提供接口请求的统一管理, 支持缓存、去重与队列
+The framework automatically creates a child Frame, mounts the registered View class, and manages its lifecycle. The `v-lark` attribute value must match a path registered via `registerViewClass`.
 
-核心 API:
+### Updater vs State vs Store Data Flow
 
-- Service.extend(syncFn, cacheMax?, cacheBuffer?): 创建 Service 子类, 指定同步函数 (执行实际请求, 接收 bag 和 callback 参数); cacheMax 控制缓存容量上限, cacheBuffer 控制淘汰缓冲区大小
-- Service.add(attrs): 注册接口元数据, 包含 name (接口名), url (请求地址), cache (缓存时间, 毫秒, 0 表示不缓存), before (前置钩子), after (后置钩子), cleans (销毁时需要清理的缓存键)
-- service.all(attrs, done): 批量请求, 优先使用缓存, 全部完成后调用 done(errors, bag1, bag2, ...)
-- service.one(attrs, done): 批量请求, 每个完成时立即回调 done(error, bag, isLast, index)
-- service.save(attrs, done): 强制请求, 跳过缓存
-- service.enqueue(task) / service.dequeue(): 任务队列, 串行执行异步操作; enqueue 将任务加入队列, dequeue 通过 setTimeout(0) 异步消费队列
-- service.destroy(): 取消所有进行中的请求, 销毁服务实例
+Three patterns for managing view data. When no store is specified, State is the default cross-view state management:
 
-Bag: 响应数据的包装器, 提供 get(key) 与 set(keyOrData, value?) 方法. set 支持单键设置和对象合并. 缓存信息附加在 Bag 的 cacheInfo 属性上, 包含 name (接口名), after (后置钩子), cleans (清理键), key (缓存键), time (缓存时间戳)
+**Updater pattern** (view-local, manual):
 
-请求去重: 相同 cacheKey 的并发请求共享同一个 pendingCacheKeys 条目, 首次请求完成后统一通知所有等待中的回调, 避免重复请求. 缓存键由 JSON.stringify(attrs) + SPLITTER + JSON.stringify(meta) 生成
-
-缓存策略: 基于 Cache 模块实现, 每个 Service 子类拥有独立的 bagCache 实例. 缓存命中时检查是否过期 (当前时间 - cacheInfo.time > cache), 过期则删除缓存并重新请求. Service.clear(names) 按接口名批量清理缓存
-
-事件: Service 支持静态事件 (begin, done, fail, end) 和实例事件 (通过 on/off/fire), 使用 EventEmitter 实现
-
-Compiler — 模板编译器
-
-模板编译器将 {{}} 模板语法编译为 JS 函数, 在构建时通过 Vite 插件或 Webpack loader 执行
-
-三阶段编译流水线:
-
-第一阶段 — 预处理:
-
-- protectComments(): 保护 HTML 注释内的模板语法不被误处理; 将注释替换为 **lark_comment_N** 占位符, 编译完成后恢复
-- processViewEvents(): 处理 v-event 属性, 添加 \x1f (VIEW_ID_PLACEHOLDER) 前缀 + \x1e (SPLITTER) 分隔符, 将 JS 对象字面量参数转换为 URL 查询参数格式. 例如: v-click="handlerName({key: 'value'})" 转换为 v-click="\x1f\x1ehandlerName(key=value)"
-
-第二阶段 — 语法转换:
-
-- convertArtSyntax(): 将 {{}} 模板语法转换为 <% %> 内部格式. 支持的运算符:
-  - = (HTML 转义输出): {{=variable}} 转换为 <%=variable%>
-  - ! (原始输出): {{!variable}} 转换为 <%!variable%>
-  - @ (引用查找): {{@variable}} 转换为 <%@variable%>, 运行时通过 $i() 查找 refData 中的键名
-  - : (双向绑定): {{:variable}} 转换为 <%:variable%>, 渲染时与 = 相同
-  - each (数组循环): {{each list as item [index]}} 转换为 for 循环, 支持 first/last 辅助变量, 支持解构赋值 {a,b}
-  - parse (对象遍历): {{parse obj as val [key]}}
-  - for (通用 for 循环): {{for(init;test;update)}}
-  - if/else/else if (条件判断)
-  - set (变量声明): {{set a = b}}
-  - 块级验证: 使用 blockStack 追踪开放的块, 编译结束时若存在未关闭的块则抛出错误
-- addLineMarkers(): 调试模式下, 在每个 {{ 标签前插入 \x1e + lineNo 行号标记
-- extractArtInfo(): 从带行号标记的 {{ }} 块中提取行号与代码
-
-第三阶段 — 函数生成:
-
-- compileToFunction(): 将 <% %> 内部格式编译为 JS 模板函数. 输出为箭头函数: ($$,$viewId,$$ref,$e,$n,$eu,$i,$eq)=>{...}, 返回渲染后的 HTML 字符串. 函数体使用 $p 作为输出缓冲区, 通过字符串拼接构建 HTML
-- 自动变量提取: extractGlobalVars() 基于 @babel/parser AST 分析, 自动从模板中提取全局变量名. 两遍扫描: 第一遍收集变量声明和函数作用域, 第二遍识别未声明的标识符为全局变量. 排除内置全局 (JS 内置对象, 模板运行时变量, Lark 框架变量). AST 解析失败时回退到正则提取
-- View ID 注入: \x1f (VIEW_ID_PLACEHOLDER) 在函数生成阶段替换为 '+$viewId+', 实现运行时注入 View ID
-- 调试模式: 支持 $expr/$art/$line 行号追踪与 try-catch 错误包装, 错误信息包含原始模板语法和行号
-- 后处理: 清理空字符串拼接 ($p+='';), 优化 $p=''+ 为 $p+=
-
-最终输出为 ES 模块, 导出一个函数: function(data, selfId, refData) 返回渲染后的 HTML 字符串
-
-Mark/Unmark — 异步回调有效性追踪
-
-基于签名的异步回调保护机制
-
-mark(host, key) 在 host 对象上维护一个签名计数器 (SPLITTER + $b 键下的 key 属性), 每次调用 mark 递增计数器并返回一个校验函数. 校验函数闭包捕获当前签名值, 调用时检查 host 上的签名是否与闭包捕获值一致, 一致返回 true (仍有效), 不一致返回 false (已失效)
-
-unmark(host) 将签名对象设为 0, 并设置 DELETED_KEY ($a) 为 1, 使所有已有校验函数返回 false. 调用时机: View 销毁 (unmountView) 或重新渲染 (viewWrapMethod)
-
-典型场景: View 发起异步请求, 请求返回时 View 可能已被销毁或重新渲染. 通过 mark() 在请求发起时创建校验函数, 回调执行前检查有效性, 避免操作已失效的 View
-
-Safeguard — 调试保护
-
-基于 Proxy 的数据保护工具, 仅在 window.\_\_lark_debug 为 true 且 Proxy 可用时激活
-
-功能:
-
-- 拦截非法写入: 根级别直接修改数据时抛出错误 (throw new Error), 强制使用 State.set() / updater.set()
-- 追踪数据访问: getter 回调记录属性读取操作, setter 回调记录属性写入路径和值, 辅助定位数据流向问题
-- 递归代理: 嵌套对象与数组自动递归包装为 Proxy, 深层读写同样被拦截; isRoot 参数控制是否为根级对象 (根级对象不递归)
-- Proxy 池缓存: proxiesPool (Map<object, {cacheKey, entity}>) 缓存已创建的 Proxy 实例, 相同对象不重复包装; SAFEGUARD_SENTINEL 属性防止对已代理对象重复代理
-- clearSafeguardCache(): 清空 Proxy 缓存, 用于测试场景
-
-Cache — LFU 风格缓存
-
-频率与时间双重维度的缓存淘汰策略
-
-每个 CacheEntry 记录: originalKey (原始键, 不含 SPLITTER 前缀), value (缓存值), frequency (访问频率), lastTimestamp (最后访问时间)
-
-核心方法:
-
-- set(key, value): 写入缓存, 内部键为 SPLITTER + key 实现命名空间隔离; 容量超限时触发淘汰
-- get(key): 读取缓存, 命中时递增 frequency 并更新 lastTimestamp
-- del(key): 删除缓存项
-- forEach(callback): 遍历所有缓存项
-
-淘汰策略: 当缓存数量超过 maxSize + bufferSize 时, 对所有条目按 (frequency, lastTimestamp) 排序, 淘汰频率最低且时间最旧的条目, 直到数量不超过 maxSize. 支持 onRemove 回调在条目被移除时通知调用方. sortComparator 允许自定义排序比较器
-
-EventEmitter — 多播事件发射器
-
-支持 on/off/fire 的事件系统
-
-核心机制:
-
-- on(event, handler): 注册事件监听器, 内部键为 SPLITTER + event, 监听器包含 handler 和 executing 状态
-- off(event, handler?): 移除监听器. 传入 handler 时, 将其替换为 noop 而非从数组中移除 (避免在 fire 遍历过程中修改数组); 不传 handler 时, 删除整个事件的所有监听器
-- fire(event, data?, remove?, lastToFirst?): 触发事件, 执行所有监听器. executing 标志防止在 fire 过程中移除的监听器在下次 fire 时被清理. remove 参数触发后自动移除所有监听器. lastToFirst 控制执行顺序 (默认从先到后)
-- onEventName 约定: 若对象上存在 on + EventName 方法, fire 时自动调用
-
-ApplyStyle — CSS 注入
-
-动态向文档头部注入 <style> 标签
-
-支持两种调用方式: 单条注入 applyStyle(styleId, css) 和批量注入 applyStyle([id1, css1, id2, css2, ...]). 通过 injectedStyleIds Set 去重, 相同 ID 的样式不会重复注入. 每条注入返回一个清理函数, 调用后从 DOM 移除 <style> 标签并从 Set 中删除 ID
-
-变更分发机制
-
-Lark 的变更分发由 Dispatcher 模块 (内嵌在 framework.ts) 实现, 当路由或 State 发生变更时, 沿 Frame 树向下查找并通知匹配的 View 重新渲染
-
-```
-路由变更 / State 变更
-  └── dispatcherNotifyChange(data)
-        ├── 路由 view 变更 → rootFrame.mountView(newViewPath)
-        └── 参数/状态变更 → dispatcherUpdate(rootFrame, changedKeys)
-              ├── 检查 View 是否观察了变更键
-              │     ├── observeLocation → viewIsObserveChanged()
-              │     └── observeState → stateIsObserveChanged()
-              ├── 匹配则触发 View.render()
-              └── 递归子 Frame → dispatcherUpdate(childFrame, changedKeys)
-```
-
-dispatcherUpdate 通过 dispatcherUpdateTag 防止同一更新周期内重复处理同一 Frame; View 的 signature <= 1 时跳过更新 (尚未完成首次渲染); 支持 render() 返回 Promise 的异步场景, 异步渲染完成后递归处理子 Frame
-
-渲染管线
-
-```
-updater.digest()
-  ├── 调用模板函数(template) → 生成 HTML 字符串
-  ├── 虚拟文档解析 HTML → 新 DOM 节点
-  ├── VDOM diff (新旧节点对比)
-  │   ├── 属性差异 → setAttribute / 直接属性赋值
-  │   ├── 子节点差异 → appendChild / removeChild / replaceChild / insertBefore
-  │   └── 特殊元素 → 直接同步 value / checked / selected
-  ├── applyIdUpdates() — 批量更新元素 ID
-  ├── applyVdomOps() — 批量执行 DOM 操作
-  └── Frame 处理 lark-view 子视图 → mountZone
+```typescript
+this.updater.set({ count: newCount }).digest();
 ```
 
-对比 React 框架
-
-虚拟 DOM 与 diff 算法
-
-React 使用完整的虚拟 DOM 树表示 UI 结构, 通过 JSX 创建 ReactElement 对象树, diff 算法比较新旧两棵虚拟 DOM 树, 生成最小变更集. React 的 diff 算法基于三个假设: 1) 跨层级的节点移动极少, 2) 不同类型的元素产生不同的树, 3) key 属性标识节点的稳定性
-
-Lark 不使用完整的虚拟 DOM 树表示, 而是采用增量式 diff: 新模板渲染生成 HTML 字符串, 通过 document.implementation.createHTMLDocument() 解析为真实 DOM 节点, 然后直接与现有 DOM 树进行 diff. 这意味着 Lark 不需要维护一棵独立的虚拟 DOM 树, 内存占用更低. diff 过程中, Lark 的 vdomSetChildNodes 实现了基于 key 的节点匹配 (通过 id, lark-key, lark-view 属性), 类似于 React 的 key 机制, 但匹配策略更简单: 通过哈希表 (keyedNodes) 一次性构建旧节点的 key 映射, 遍历新节点时查找匹配
-
-Lark 的 diff 产生四种操作码 (appendChild=1, removeChild=2, replaceChild=4, insertBefore=8), 批量执行; React 的 diff 产生 patch 列表, 通过 React Reconciler 调度执行. Lark 的 diff 是同步的、全量的 (针对单个 View), React 的 diff 可以通过 shouldComponentUpdate / React.memo 等机制跳过子树
-
-Fiber 架构
-
-React Fiber 是 React 16 引入的协调引擎, 将渲染工作拆分为小单元 (Fiber 节点), 支持可中断的异步渲染. 每个 Fiber 节点包含 type, key, child, sibling, return 等指针, 构成链表结构, 替代了之前的递归式栈帧调用. Fiber 架构的核心优势: 1) 时间切片, 可暂停渲染以响应用户交互; 2) 优先级调度, 高优先级更新 (如用户输入) 可以中断低优先级更新 (如数据请求); 3) 可恢复的渲染, 暂停后可从断点继续
-
-Lark 的 Frame 树与 Fiber 树有相似之处: 两者都与 DOM 树同构, 都管理组件/视图的生命周期. 但 Lark 的 Frame 不实现时间切片和可中断渲染, diff 和 DOM 更新是同步执行的. Lark 的 Frame 更侧重于生命周期管理 (mountView/unmountView) 和事件边界检测 (findFrameInfo), 而非渲染调度. Lark 的任务调度能力来自 Framework.task(), 它使用 scheduler.postTask / requestIdleCallback / setTimeout 实现时间切片, 但这只用于通用任务队列, 不用于渲染过程本身
-
-渲染模型
-
-React 使用不可变数据模型: setState 生成新的状态对象, 触发组件重渲染, 组件的 render 函数返回新的 ReactElement 树. Lark 使用可变数据模型: updater.set() 直接修改内部数据, updater.digest() 触发模板函数重新执行, 生成新的 HTML 字符串. React 组件通过 props 和 state 驱动渲染, Lark View 通过 updater.refData 和 Store.observe 驱动渲染
-
-事件系统
-
-React 使用合成事件 (SyntheticEvent), 在 React 17+ 将事件委托到根容器节点, 事件对象是原生事件的跨浏览器包装. Lark 使用原生事件委托到 document.body, 通过 v-event 属性编码 View ID 和 handler 名称, EventDelegator 解析分发. Lark 的方案更轻量, 不需要额外的事件对象池和兼容层
-
-对比 Vue3 框架
-
-模板编译
+**State pattern** (default cross-view, key-ref counting):
 
-Vue3 的模板编译器将单文件组件的 <template> 编译为渲染函数, 编译过程分为三步: parse (模板 → AST), transform (AST → JavaScript AST), generate (JavaScript AST → 渲染函数代码). Vue3 的编译器实现了静态提升 (Static Hoisting): 将静态节点提升到渲染函数外部, 避免每次渲染重新创建; PatchFlag 标记动态节点, diff 时只比较标记为动态的部分; Block Tree 优化, 将模板按结构化指令 (v-if, v-for) 拆分为 Block, diff 时扁平化遍历
-
-Lark 的模板编译器将 {{}} 语法编译为 JS 函数, 编译过程分为三步: 预处理 (protectComments + processViewEvents), 语法转换 (convertArtSyntax: {{}} → <% %>), 函数生成 (compileToFunction: <% %> → 箭头函数). Lark 的编译器没有 AST 中间表示, 直接通过正则匹配和字符串替换完成转换. Lark 不实现静态提升, 每次渲染完整执行模板函数; 也没有 PatchFlag, 每次渲染产生的 HTML 需要完整 diff. Lark 通过 lark-key 和 lark-attr-key 属性提供手动静态跳过能力, 类似于 Vue3 PatchFlag 的手动版本
-
-Vue3 的编译器输出 render() 函数, 返回虚拟 DOM 节点树 (VNode), 再由运行时进行 diff; Lark 的编译器输出模板函数, 返回 HTML 字符串, 由 Updater 解析为真实 DOM 后再 diff. Vue3 的编译时优化更丰富, Lark 的编译器更简洁, 依赖运行时 diff 的 keyed 匹配来保证性能
-
-Vue3 的编译器支持 v-model (双向绑定), v-slot (插槽), v-once (只渲染一次), v-memo (记忆化) 等指令; Lark 支持 = (转义输出), ! (原始输出), @ (引用查找), : (绑定) 运算符, 以及 each, parse, for, if/else, set 控制流
-
-Proxy 响应式
-
-Vue3 使用 Proxy 实现响应式系统, 核心是 reactive() 和 ref() 两个 API. reactive() 接收对象并返回 Proxy 包装, get 拦截器通过 track(target, key) 收集依赖, set 拦截器通过 trigger(target, key) 触发更新. ref() 包装原始值, 通过对象访问器 (get/set) 实现响应式. Vue3 的依赖追踪使用全局 WeakMap(target -> Map(key -> Set(effect))) 结构, effect 函数执行时自动收集依赖. Vue3 还提供 computed (计算属性, 惰性求值+缓存), watch/watchEffect (副作用), shallowReactive/shallowRef (浅层响应式) 等衍生 API
-
-Lark 的 Store 模块同样基于 Proxy 实现响应式, 核心是 createState() 和 defineStore(). createState() 接收普通对象, 返回 Proxy 包装的响应式状态, get 拦截器执行 track(depKey, effect), set 拦截器执行 trigger(depKey). 依赖追踪使用全局 GlobalDeps Map (key 为 SPLITTER + depKey, value 为 effect Set). 两者的依赖追踪机制本质相同, 区别在于:
-
-1. 依赖粒度: Vue3 以 target + key 为粒度 (每个对象的每个属性独立追踪), Lark 以 depKey 为粒度 (扁平化的全局 Map). Vue3 的 WeakMap 结构允许对象被 GC 时自动清理依赖映射, Lark 的全局 Map 需要手动清理 (通过 Store 生命周期管理)
-2. 效果调度: Vue3 的 effect 通过 scheduler 调度执行, 支持异步批量更新 (nextTick); Lark 的 Store 的 observe 直接绑定 View 的 updater.digest, 状态变更后同步触发渲染, 或通过 ObservePayload.lazy 延迟到下一帧
-3. 计算属性: Vue3 提供 computed() 实现惰性求值和缓存; Lark 通过 ObservePayload.transform 实现状态派生, 但不内置缓存
-4. 浅层响应式: Vue3 提供 shallowReactive/shallowRef; Lark 提供 shallowSet(), 只有顶层 key 变化触发通知
-5. 批量更新: Vue3 通过 nextTick 批量处理同一事件循环内的多次状态变更; Lark 通过 lazySet() 批量设置多个属性但只触发一次通知
-6. 原始值响应式: Vue3 使用 ref() 包装原始值; Lark 使用 cell() 创建独立响应式数据单元, 本质是 createState 的轻量封装
-7. 多平台: Lark 的 Store 设计了 LarkStore / ReactStore / NodeStore 三种适配器, ReactStore 使用 freezeData 生成不可变快照适配 React, NodeStore 适用于 Node.js 环境; Vue3 没有类似的多平台设计, 其响应式系统与 Vue 组件生命周期绑定
-
-组件模型
+```typescript
+// Write: set data and digest to notify
+State.set({ count: newCount }).digest();
+
+// Read: in view's assign(), pull from State
+assign() {
+  this.updater.snapshot();
+  this.updater.set({ count: State.get("count") });
+  return this.updater.altered();
+}
 
-Vue3 使用单文件组件 (SFC) 组织视图, <template>, <script>, <style> 放在同一个 .vue 文件中; Lark 将模板 (.html) 和逻辑 (.ts) 分离, 通过 import 关联. Vue3 组件通过 props 接收父组件数据, 通过 emit 向父组件发送事件; Lark View 通过 lark-view 属性传递路径参数, 通过 {{@}} 引用查找传递对象引用, 通过 Frame.invoke 跨层级通信
+// Observe: listen to State "changed" event to trigger re-render
+State.on("changed", (e) => {
+  if (e.keys.count) this.assign(); // Re-assign if count changed
+});
 
-Vue3 的组合式 API (Composition API) 通过 setup() 函数组织逻辑, 使用 ref, reactive, computed, watch 等 API; Lark 的 defineStore creator 函数类似于 setup(), 在其中定义 state 和 handler. Vue3 使用 provide/inject 跨层级传递数据; Lark 使用 State (全局单例) 和 Store (按需创建) 实现跨视图数据共享
+// Cleanup: use State.clean() in mixins to auto-delete keys on view destroy
+export default View.extend({
+  mixins: [State.clean("count")],
+});
+```
 
-API 速查
+Key differences from Store:
 
-Store API
+- State uses `State.set()` + `State.digest()` (manual notification), Store uses direct property assignment (automatic reactivity via Proxy)
+- State keys are auto-deleted when reference count reaches 0 (via `State.clean()` mixin), Store persists until `store.$destroyFn()` is called
+- State requires manual event listening (`State.on("changed", ...)`), Store provides `store.observe()` with auto-cleanup
 
-| API                                     | 说明                                      |
-| --------------------------------------- | ----------------------------------------- |
-| defineStore(name, creator, config?)     | 声明式定义 store                          |
-| useStore(view?)                         | 获取 store 代理, 传入 view 时绑定生命周期 |
-| store.observe(view, keys, defCallback?) | 监听状态变更                              |
-| lazySet(target, data)                   | 批量更新, 只触发一次通知                  |
-| shallowSet(target, key, data)           | 创建浅层响应式状态                        |
-| cell(data)                              | 创建独立响应式数据单元                    |
-| observeCell(state, cb, immediate?)      | 监听 cell 变更                            |
-| multi(useStore)                         | 创建多实例 store                          |
-| getStore(name)                          | 按名称获取 store 实例                     |
-| delStore(name)                          | 删除 store                                |
-| cloneStore(name, useStore, config?)     | 克隆 store                                |
-| isStoreActive(name)                     | 检查 store 是否处于 ACTIVE 状态           |
-| isState(target)                         | 检查对象是否为响应式状态                  |
-| createState(data, config?)              | 创建响应式状态                            |
+**Store pattern** (cross-view, reactive, recommended):
 
-View 事件绑定
+```typescript
+const store = useCountStore(this);
+store.observe(this, ["count"]);
+// Later, from any view:
+useCountStore().increment(); // Automatically triggers re-render in all observing views
+```
 
-模板中通过 v-事件类型 属性绑定事件, 格式为 v-click="handlerName()". 支持传参: v-click="handlerName({key: value})", JS 对象字面量参数会自动转换为 URL 查询参数格式. 编译时自动编码 View ID 与参数, 运行时由 EventDelegator 解析分发
+### Frame Tree Events
 
-模板语法
+Frame fires lifecycle events:
 
-| 语法                                        | 说明                          |
-| ------------------------------------------- | ----------------------------- |
-| {{=variable}}                               | HTML 转义输出                 |
-| {{!variable}}                               | 原始输出 (不转义)             |
-| {{@variable}}                               | 引用查找 (用于对象/数组)      |
-| {{:variable}}                               | 双向绑定                      |
-| {{each list as item}}                       | 数组循环                      |
-| {{each list as item idx}}                   | 数组循环 (带索引)             |
-| {{each list as item idx last}}              | 数组循环 (带索引和 last 变量) |
-| {{parse obj as val key}}                    | 对象遍历                      |
-| {{for(init;test;update)}}                   | 通用 for 循环                 |
-| {{if condition}}                            | 条件判断                      |
-| {{else if condition}}                       | else-if 条件                  |
-| {{else}}                                    | else 分支                     |
-| {{/if}} / {{/each}} / {{/parse}} / {{/for}} | 关闭块                        |
-| {{set var = expr}}                          | 变量声明                      |
+- `add` -- new Frame created
+- `remove` -- Frame removed
+- `created` -- all child Frames rendered
+- `alter` -- child Frame content changed
 
-Framework 全局方法
+```typescript
+Frame.on("add", ({ frame }) => {
+  /* ... */
+});
+```
 
-| 方法                                       | 说明                |
-| ------------------------------------------ | ------------------- |
-| Framework.boot(config)                     | 启动框架            |
-| Framework.config(cfg?)                     | 获取/设置配置       |
-| Framework.mark / unmark                    | 异步回调追踪        |
-| Framework.dispatch(target, type, init?)    | 触发自定义 DOM 事件 |
-| Framework.task(fn, args?, ctx?)            | 分片任务调度        |
-| Framework.delay(time)                      | Promise 延时        |
-| Framework.use(names, callback?)            | 模块加载            |
-| Framework.toMap / toTry / toUrl / parseUrl | 工具函数            |
-| Framework.has / keys / inside / node       | 工具函数            |
-| Framework.guid                             | 生成唯一 ID         |
-| Framework.guard                            | Proxy 调试保护      |
-| Framework.applyStyle                       | CSS 动态注入        |
-| Framework.Cache                            | LFU 缓存类          |
-| Framework.Base                             | EventEmitter 基类   |
-
-Router API
-
-| API                                         | 说明                       |
-| ------------------------------------------- | -------------------------- |
-| Router.parse(href?)                         | 解析 href 为 Location 对象 |
-| Router.diff()                               | 计算新旧路由差异           |
-| Router.to(path, params?, replace?, silent?) | 编程式导航                 |
-| Router.join(...paths)                       | 路径拼接                   |
-| Router.on(event, handler)                   | 监听路由事件               |
-| Router.off(event, handler?)                 | 移除路由事件监听           |
-
-State API
-
-| API                        | 说明                 |
-| -------------------------- | -------------------- |
-| State.get(key)             | 读取数据             |
-| State.set(data)            | 写入数据并标记变更键 |
-| State.digest()             | 触发变更通知         |
-| State.diff()               | 获取上次变更键映射   |
-| State.on(event, handler)   | 监听状态事件         |
-| State.off(event, handler?) | 移除状态事件监听     |
+### Vite vs Webpack Comparison
+
+| Feature              | Vite (larkMvcPlugin)                               | Webpack (larkMvcLoader)                            |
+| -------------------- | -------------------------------------------------- | -------------------------------------------------- |
+| Import path          | `@lark.js/mvc/vite`                                | `@lark.js/mvc/webpack`                             |
+| Type                 | Vite Plugin (resolveId + load hooks)               | Webpack Loader (standard loader interface)         |
+| Configuration        | `plugins: [larkMvcPlugin()]`                       | `module.rules` with loader rule                    |
+| Debug mode           | `larkMvcPlugin({ debug: true })`                   | `options: { debug: true }`                         |
+| HTML entry exclusion | Not needed (Vite handles index.html separately)    | `exclude: /index\.html$/`                          |
+| Dev server           | Vite dev server (fast HMR)                         | webpack-dev-server (standard HMR)                  |
+| Template compilation | Same pipeline: extractGlobalVars + compileTemplate | Same pipeline: extractGlobalVars + compileTemplate |
+
+## Common Pitfalls
+
+1. **boot.ts must be in `src/`** -- The index.html entry point references `/src/boot.ts`, not `/boot.ts`
+2. **registerViewClass before boot** -- All view classes must be registered before calling `Framework.boot()`
+3. **Template imports require larkMvcPlugin or larkMvcLoader** -- `.html` imports only work because the Vite plugin or Webpack loader compiles them at build time
+4. **Use State.set/digest, not direct mutation** -- Directly modifying State data bypasses change detection. In debug mode (`window.__lark_Debug = true`), safeguard Proxy warns about this with a 500ms delay
+5. **observe requires view binding for auto-cleanup** -- Always pass `this` to `store.observe(this, ...)` so the observation is cleaned up when the view is destroyed. Without view binding, you must manually call the returned unobserve function
+6. **Event method names use `<>` not `()`** -- The pattern is `name<click>`, not `name(click)`
+7. **assign must return altered()** -- The `assign` method should call `this.updater.snapshot()` at the start and return `this.updater.altered()` at the end to enable incremental updates
+8. **Do not modify view.signature** -- It is managed internally; setting it to 0 destroys the view. The wrapped render() increments signature automatically
+9. **v-lark containers are replaced** -- The content inside a `v-lark` element is replaced by the child view's rendered output
+10. **Webpack must exclude index.html** -- The larkMvcLoader rule must exclude `index.html` so HtmlWebpackPlugin can process it instead
+11. **Webpack uses loader object, not string name** -- Import `larkMvcLoader` from `@lark.js/mvc/webpack` and use it directly as `loader: larkMvcLoader`, not as a string like `"larkMvcLoader"`
+12. **Store reads return cloned data** — `useStore(view).count` returns a deep-cloned copy, not the reactive Proxy. Mutating the returned value does NOT trigger reactivity. Only writes through `store.key = value` are reactive
+13. **forOf requires "as" keyword** -- `{{forOf list item}}` is invalid. Must use `{{forOf list as item}}`
+14. **Inner observe deduplication** -- `store.observe(undefined, keys, callback)` uses a deduplication flag based on `key + observeKeys.join("-") + cb.toString()`. The same inner observe with identical key/callback won't register twice
+15. **View.wrapAsync is signature-based** -- The callback only executes if `view.signature` hasn't changed since `wrapAsync` was called. Re-rendering or destroying the view increments signature, invalidating the callback
+16. **Frame object pooling** -- Destroyed Frame objects are cached and reused. Don't hold references to Frame instances after unmountView() as they may be reinitialized for a different view
+17. **Updater re-digest support** -- Calling `updater.digest()` during an ongoing digest is supported via an internal queue. The sentinel pattern (`null` entry) marks the digest boundary, and callbacks are executed after all digest cycles complete
+18. **Store creator runs once** -- The creator function passed to `defineStore` runs once at definition time. Store state persists across view mounts/unmounts unless `store.$destroyFn()` is explicitly called
+19. **State is the default when no store is specified** -- Without `defineStore`, cross-view data flows through `State.set()` / `State.get()` / `State.digest()`. Always use `State.set()` + `State.digest()` to update data (never mutate `State.get()` directly). Use `State.clean()` in mixins to auto-delete keys on view destroy; otherwise, State data persists globally and is never garbage collected
+
+## References
+
+For detailed API signatures and template syntax, consult the reference files:
+
+- `references/api-reference.md` -- Complete API reference for all Lark modules
+- `references/template-syntax.md` -- Template syntax, operators, control flow, and event binding