@lark.js/mvc 0.0.1 → 0.0.3

package/README.md

@@ -1 +1,945 @@
-# Lark - TypeScript MVC framework
+# Lark Framework
+
+Lark 是基于 TypeScript 的 MVC 前端框架, 核心特点包括: 虚拟 DOM 差量更新、hash 路由、事件委托、模板编译、Proxy 响应式状态管理, 提供声明式数据绑定的 SPA 开发体验
+
+架构总览
+
+```
+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 动态注入)
+```
+
+Lark 框架启动时, Framework.boot() 初始化路由器、状态管理器、事件委托器, 创建根 Frame 节点, 绑定 hashchange 事件; 路由改变与状态改变通过统一的派发器 (Dispatcher) 沿 Frame 树向下通知各个 View, 触发条件匹配的视图重新渲染
+
+安装
+
+```
+pnpm add @lark.js/mvc
+```
+
+快速上手
+
+1. 配置构建工具
+
+Vite 项目在 vite.config.ts 中导入 larkMvcPlugin 插件, 该插件会自动将 .html 模板文件编译为 JS 函数
+
+```typescript
+import { larkMvcPlugin } from "@lark/framework/vite";
+
+export default defineConfig({
+  plugins: [larkMvcPlugin()],
+});
+```
+
+Webpack 项目在 webpack.config.mjs 中配置 loader
+
+```javascript
+import { resolve } from "path";
+import { larkMvcLoader } from "@lark/framework/webpack";
+
+export default {
+  module: {
+    rules: [
+      {
+        test: /\.html$/,
+        loader: larkMvcLoader,
+      },
+    ],
+  },
+};
+```
+
+2. 定义 Store
+
+通过 defineStore 创建响应式状态管理, creator 函数返回的对象中, 非函数属性成为响应式 state, 函数属性成为 handler
+
+```typescript
+import { defineStore } from "@lark.js/mvc";
+
+export interface CountStore {
+  count: number;
+  step: number;
+  history: string[];
+  increment: () => void;
+  decrement: () => void;
+  reset: () => void;
+  setStep: (val: number) => void;
+  clearHistory: () => void;
+}
+
+const useCountStore = defineStore<CountStore>("count", (store) => {
+  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 = [];
+    },
+  };
+});
+
+export default useCountStore;
+```
+
+creator 函数接收两个参数: store 是 Proxy 代理对象, 可以读写 state, 也可以调用 observe 注册 state 改变时的 callback; apis 可以解构得到 lazySet 和 shallowSet 两个工具方法
+
+3. 创建 View
+
+View.extend(props) 创建视图子类, 模板属性 template 引用编译后的 HTML 模板函数, init 方法中通过 useStore(this) 获取 store 实例并绑定视图生命周期, store.observe(this, keys) 声明观察的状态键
+
+事件方法的方法名格式为 name<eventType>, 例如 increment<click> 对应模板中的 @click="increment()", 编译时自动编码 View ID, 运行时由 EventDelegator 解析分发
+
+```typescript
+import { Router } from "@lark.js/mvc";
+import View from "../view";
+import template from "./counter.html";
+import useCountStore from "../store/count";
+
+export default View.extend({
+  // const template: (data: unknown, selfId: string, refData: unknown) => string;
+  template,
+
+  init() {
+    const store = useCountStore(this);
+    store.observe(this, ["count", "step", "history"]);
+  },
+
+  "increment<click>"() {
+    useCountStore().increment();
+  },
+
+  "decrement<click>"() {
+    useCountStore().decrement();
+  },
+
+  "reset<click>"() {
+    useCountStore().reset();
+  },
+
+  "stepChange<change>"(e: Event) {
+    const target = e.target as HTMLInputElement;
+    const newStep = parseInt(target.value) || 1;
+    useCountStore().setStep(newStep);
+  },
+});
+```
+
+4. 创建模板
+
+模板使用 {{}} 语法, = 表示 HTML 转义输出, @click 等属性绑定事件, 编译时自动将 View ID 和参数编码到事件属性值中
+
+```html
+<div>
+  <div>{{=count}}</div>
+  <input type="number" value="{{=step}}" @change="stepChange()" />
+  <button @click="decrement()">-{{=step}}</button>
+  <button @click="reset()">Reset</button>
+  <button @click="increment()">+{{=step}}</button>
+
+  {{if history.length > 0}}
+  <ul>
+    {{each history as record}}
+    <li>{{=record}}</li>
+    {{/each}}
+  </ul>
+  {{else}}
+  <p>No history</p>
+  {{/if}}
+</div>
+```
+
+5. 启动应用
+
+通过 registerViewClass 注册 View 类, 配置 routes 路由映射, 调用 Framework.boot(config) 启动框架
+
+```typescript
+import { Framework, View, registerViewClass } from "@lark.js/mvc";
+import HomeView from "./src/views/home";
+import CounterView from "./src/views/counter";
+
+registerViewClass("home", HomeView as typeof View);
+registerViewClass("counter", CounterView as typeof View);
+
+Framework.boot({
+  rootId: "app",
+  defaultPath: "/home",
+  defaultView: "home",
+  routes: {
+    "/home": "home",
+    "/counter": "counter",
+  },
+  unmatchedView: "404",
+  error(e: Error) {
+    console.error("Lark application 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;
+```
+
+- 入队: callFunction(fn, args, ctx) 不是立刻执行, 而是将 fn、ctx、args 扁平 push 到 callList
+- 异步启动: 通过 setTimeout(startCall) 推迟到下一个事件循环开始执行
+- 分片执行: startCall 在 while 循环中, 依次取出函数执行, 每执行一个函数都会检查一次耗时
+
+这是早期前端的长任务分片实践，用于
+
+- 避免一次性执行大量回调, 例如大量 View 渲染完成后的通知导致页面卡顿
+- 保持 60fps (每帧约 16ms, 48ms 约占 3 帧) 的用户交互响应
+- 与 requestIdleCallback 的思路类似, 但 callFunction 设计时浏览器可能还没有该 API
+
+优化
+
+任务调度: `Framework.task(fn, args, context)` 提供分片执行能力, 调度优先级为
+
+- `scheduler.postTask('background')` Chrome 94+
+- `requestIdleCallback` Chrome 47+
+- `setTimeout(0)` 通用 fallback 方案
+
+使用 `requestIdleCallback` 时依据 `deadline.timeRemaining()` 自适应确定每片执行数量, 回退到 setTimeout 时使用固定 48ms 时间片
+
+|                | callFunction                           | task                                                  |
+| -------------- | -------------------------------------- | ----------------------------------------------------- |
+| 调度 API       | setTimeout                             | scheduler.postTask → requestIdleCallback → setTimeout |
+| 时间切片       | 固定 48ms                              | 自适应 deadline.timeRemaining() + 48ms fallback       |
+| 接口签名       | 扁平数组 [fn, ctx, args, ...] 逐个消费 | 相同保持兼容性                                        |
+| 让出主线程时机 | 仅超时                                 |                                                       |
+
+Router — hash 路由器
+
+Router hash 路由器基于 location.hash, 支持 #! 前缀的 hashbang 模式
+
+路由变更使用两阶段确认
+
+1. change 阶段: 用户可以调用 `prevent()` 取消路由跳转, 或调用 `reject()` 回退到旧 URL, 类似 beforeunload
+2. changed 阶段: 路由改变完成后触发, 通知 Dispatcher 派发器更新视图
+
+核心 API:
+
+- `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)`: 拼接路径, 处理 ./ , ../ , // 等路径规范
+
+Location 对象结构
+
+```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;
+}
+```
+
+LocationDiff 对象结构
+
+```ts
+export interface LocationDiff {
+  /** 变更参数映射 */
+  params: Record<string, ParamDiff>;
+  /** 路径变更 */
+  path?: ParamDiff;
+  /** 视图变更 */
+  view?: ParamDiff;
+  /** 是否首次强制变更 */
+  force: boolean;
+  /** 是否有变更 */
+  changed: boolean;
+}
+```
+
+beforeunload 事件支持: 监听 window 的 beforeunload 事件, 若监听器设置了 msg 字段, 浏览器弹出离开确认对话框
+
+调试模式下, Location.params 和 LocationDiff 会被 safeguard() Proxy 包装, 拦截非法写入
+
+State — 跨视图 observable 数据
+
+State 是全局单例的数据对象, 用于跨视图共享状态; View 通过 `observeState(keys)` 声明观察的键, State 改变时仅通知观察了相关键的视图
+
+核心流程:
+
+1. `State.get(key)` 读取数据; State.set(data) 写入数据并标记变更键
+2. `State.digest()` 触发变更通知: 将变更键传递给 Dispatcher, Dispatcher 沿 Frame 树查找观察了这些键的 View 并触发重新渲染
+3. `State.diff()` 返回上次 digest 的变更键映射
+
+键引用计数: 当 View 调用 observeState(keys) 时, 通过 setupKeysRef 对这些键建立引用计数; 当 View 销毁时, 通过 teardownKeysRef 递减引用计数; 当某个键的引用计数降为 0 时, 自动从 State 中删除该键的数据, 避免内存泄漏
+
+调试模式: 当 `window.__lark_Debug` 为 true 时, State 数据会使用 safeguard() Proxy 包装, 拦截非法写入并追踪访问来源
+
+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()`
+
+```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; // 状态派生函数
+}
+```
+
+ReactStore
+
+- 使用 `freezeData()` 冻结数据, 生成不可变快照, 适配 React 的不可变数据模式
+- 每次状态变更后生成新的快照, 确保引用变化以触发 React 组件重渲染
+
+NodeStore: observe 直接执行回调, 不绑定视图生命周期, 适用于 Node.js 环境下的状态管理
+
+_lazySet — 批量懒更新_
+
+`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", // 对应 v-lark="components/counter-store"
+    frame_1: "frame_1", // 对应 v-lark="components/counter-updater"
+  },
+
+  // readyMap 已 ready 的子 frame 集合
+  // hasAltered 子 frame 是否被修改
+  // signature 异步操作签名
+  // invokeList 延迟方法调用列表
+  // originalTemplate 挂载前的原始 html
+};
+```
+
+核心方法
+
+- `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?)`: 管理区域内的 v-lark 子视图, 区域内的子 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 视图基类负责用户交互, 提供数据绑定、事件处理、生命周期与视图继承能力
+
+_视图继承_
+
+- `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) {}
+
+// hover .tooltip 元素时触发
+"$tooltip<mouseenter>"(e) {}
+
+// $ 后面的 CSS 选择器为空时, 默认选择 frame 根节点
+// 点击 frame 根节点时触发
+"$<click>"(e) {}
+```
+
+```html
+<button class="btn">只需要写 CSS 类名</button>
+<div class="tooltip">不需要写 @event, 适用于批量绑定</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 处理新增的 v-lark 子视图 (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 操作. 对于有 v-lark 属性的元素, 如果新旧 view 路径相同则跳过子节点更新, 保护已挂载的子视图
+- `vdomSetChildNodes(oldParent, newParent, ref, frame, keys?)`: 对比子节点列表, 支持 keyed diff. 算法: 先从旧子节点构建 keyedNodes 映射 (键由 vdomGetCompareKey 获取, 优先级 id > ldk > v-lark 路径), 同时统计新子节点的 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 属性 > ldk 属性 > v-lark 路径. 有 autoId 标记的元素不使用 id 作为比较键. 比较键结果缓存到元素的 compareKeyCached / cachedCompareKey 属性
+
+静态跳过: 有 ldk 属性且值相同的元素跳过 diff; 有 lak 属性且值相同的元素跳过属性更新
+
+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 的 @event 属性在编译时编码为 viewId\x1ehandlerName(params) 格式, 运行时由 EventDelegator 解析并分发
+
+核心机制:
+
+- `bind(eventType, selector?)`: 注册事件类型到 document.body, 选择器事件使用事件委托匹配; 同一事件类型只注册一次全局监听器
+- `domEventProcessor(event)`: 事件处理入口, 从目标元素向上遍历 DOM 树查找 @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 事件: 通过 lvk 属性标记 View 边界, 事件处理时检查 rangeFrameId, 确保只在对应 View 的 DOM 范围内查找事件处理器
+
+Service + Bag — 接口请求管理
+
+Service 提供接口请求的统一管理, 支持缓存、去重与队列
+
+核心 API:
+
+- 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(): 取消所有进行中的请求, 销毁服务实例
+
+Bag: 响应数据的包装器, 提供 get(key) 与 set(keyOrData, value?) 方法. set 支持单键设置和对象合并. 缓存信息附加在 Bag 的 cacheInfo 属性上, 包含 name (接口名), after (后置钩子), cleans (清理键), key (缓存键), time (缓存时间戳)
+
+请求去重: 相同 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(): 处理 @event 属性, 添加 \x1f (VIEW_ID_PLACEHOLDER) 前缀 + \x1e (SPLITTER) 分隔符, 将 JS 对象字面量参数转换为 URL 查询参数格式. 例如: @click="handlerName({key: 'value'})" 转换为 @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 处理 v-lark 子视图 → mountZone
+```
+
+对比 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, ldk, v-lark 属性), 类似于 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, 通过 @event 属性编码 View ID 和 handler 名称, EventDelegator 解析分发. Lark 的方案更轻量, 不需要额外的事件对象池和兼容层
+
+对比 Vue3 框架
+
+模板编译
+
+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 通过 ldk 和 lak 属性提供手动静态跳过能力, 类似于 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 组件生命周期绑定
+
+组件模型
+
+Vue3 使用单文件组件 (SFC) 组织视图, <template>, <script>, <style> 放在同一个 .vue 文件中; Lark 将模板 (.html) 和逻辑 (.ts) 分离, 通过 import 关联. Vue3 组件通过 props 接收父组件数据, 通过 emit 向父组件发送事件; Lark View 通过 v-lark 属性传递路径参数, 通过 {{@}} 引用查找传递对象引用, 通过 Frame.invoke 跨层级通信
+
+Vue3 的组合式 API (Composition API) 通过 setup() 函数组织逻辑, 使用 ref, reactive, computed, watch 等 API; Lark 的 defineStore creator 函数类似于 setup(), 在其中定义 state 和 handler. Vue3 使用 provide/inject 跨层级传递数据; Lark 使用 State (全局单例) 和 Store (按需创建) 实现跨视图数据共享
+
+API 速查
+
+Store API
+
+| 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?)              | 创建响应式状态                            |
+
+View 事件绑定
+
+模板中通过 @事件类型 属性绑定事件, 格式为 @click="handlerName()". 支持传参: @click="handlerName({key: value})", JS 对象字面量参数会自动转换为 URL 查询参数格式. 编译时自动编码 View ID 与参数, 运行时由 EventDelegator 解析分发
+
+模板语法
+
+| 语法                                        | 说明                          |
+| ------------------------------------------- | ----------------------------- |
+| {{=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}}                          | 变量声明                      |
+
+Framework 全局方法
+
+| 方法                                       | 说明                |
+| ------------------------------------------ | ------------------- |
+| 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?) | 移除状态事件监听     |