@lark.js/mvc 0.0.4 → 0.0.6

package/README.md

@@ -1,97 +1,61 @@
----
-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.js/mvc
 
-# Lark MVC Framework
+A TypeScript MVC framework designed for back-office single-page applications and micro-frontend scenarios.
 
-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.
+`@lark.js/mvc` explicitly separates Model, View, and Controller layers: state management aligns with the zustand design (`create` / `getState` / `setState` / `subscribe`), routing supports both history and hash modes, templates compile to functions and render via real DOM diff, and micro-frontends are natively supported through the built-in CrossSite bridge and first-class Webpack Module Federation integration. The framework has zero runtime third-party dependencies; the template runtime helper module weighs approximately 1 KB (`dist/runtime.js` measured at 964 bytes).
 
-## Architecture Overview
+- Package: `@lark.js/mvc`
+- Version: see `package.json` (currently 0.0.5)
+- Entry points: `./` main entry, `./vite` build plugin, `./webpack` loader, `./runtime` template runtime
+- Build: tsup, producing ESM + CJS + `.d.ts` in `dist/`
+- Tests: vitest, 16 test files covering core modules
 
-Lark follows a strict MVC separation:
+## Table of Contents
 
-- **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
+- Design Goals and Use Cases
+- Installation and Build Tool Configuration
+- Five-Minute Quick Start
+- Three Data Pipelines: Updater / State / Store
+- View Definition and Lifecycle
+- Router and Route Guards
+- Service Request Layer
+- Template Syntax
+- Frame and the View Tree
+- Module Federation Micro-Frontend
+- Debugging and DevTools Bridge
+- Public API Reference
+- Common Pitfalls
+- Recent API Changes
+- Comparison with Vue 3 / React 19
+- Testing and Local Development
 
-Data flows through three pipelines (use Store when possible, State is the default when no store is specified):
+## Design Goals and Use Cases
 
-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
+Lark's trade-offs center around one category of requirements: back-office business systems with deep route hierarchies, heavy forms and API calls, and the need to compose several independent applications into a single shell. The framework makes explicit choices along the following dimensions.
 
-### Boot Sequence (Critical Order)
+First, explicit layering. The Model layer provides `State` / `Store` (zustand-style) / `Service`, the View layer provides `View` / `Updater`, and the Controller layer provides `Router` (history/hash dual mode) / `Frame`. These communicate through explicit interfaces and events, allowing new team members to locate code by layer.
 
-`Framework.boot()` executes in a specific order that must not be changed:
+Second, native micro-frontend support. The `CrossSite` bridge view + `FrameworkConfig.require` + Module Federation form a complete pipeline. Write `v-lark="remote-app/views/home"` in a template and the remote view loads and mounts automatically, eliminating the need for secondary containers like single-spa or qiankun.
 
-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
+Third, zero runtime dependencies. `@babel/parser` / `@babel/types` are used only at build time for template parsing. The runtime helper module `@lark.js/mvc/runtime` contains five functions (`strSafe` / `encHtml` / `encUri` / `encQuote` / `refFn`) and weighs approximately 1 KB as ESM.
 
-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.
+Fourth, real DOM diff. Templates compile to functions that produce HTML strings, which are parsed into temporary DOM via `document.implementation.createHTMLDocument` and then diffed against the live DOM using keyed comparison. The advantage is that context-sensitive tags like `<table>` / `<select>` / `<svg>` are handled by the native parser. The trade-off is that large templates incur parse overhead, and SSR is not supported.
 
-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)`).
+Fifth, debug-friendly. `window.__lark_Debug = true` enables Safeguard Proxy protection against cross-page pollution and accidental writes. `installFrameVisualizerBridge` exposes the Frame tree to visual DevTools via `postMessage`. A set of `window.__lark_*` global shortcuts cover Framework / State / Router / Frame / View and HMR helpers.
 
-### Window Globals
+Not suitable for: projects requiring SSR/streaming rendering, cross-platform needs like React Native, or projects needing off-the-shelf Chrome extension panels. For those, consider the React or Vue ecosystems.
 
-After boot, the framework sets these globals for debugging and extension:
+## Installation and Build Tool Configuration
 
-| 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
-
-```
-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
+### Installation
 
 ```bash
 pnpm add @lark.js/mvc
 ```
 
-### 2. Configure Vite Integration
+### Vite (Recommended)
 
-```typescript
+```ts
 // vite.config.ts
 import { defineConfig } from "vite";
 import { resolve } from "path";
@@ -99,128 +63,46 @@ import { larkMvcPlugin } from "@lark.js/mvc/vite";
 
 export default defineConfig({
   plugins: [larkMvcPlugin()],
-  resolve: {
-    alias: {
-      "@": resolve(__dirname, "./src"),
-    },
-  },
+  resolve: { alias: { "@": resolve(__dirname, "./src") } },
 });
 ```
 
-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.
+`larkMvcPlugin()` registers at the `enforce: "pre"` stage: the `resolveId` hook appends a `?lark-template` suffix to `.html` imports to prevent Vite from treating them as static assets; the `load` hook calls `extractGlobalVars()` and `compileTemplate()` to compile templates into ES modules exporting a render function of the form `(data, viewId, refData) => string`. With `{ debug: true }`, source location markers are injected into the output so runtime errors can be traced back to the original HTML line.
 
-How it works internally:
+### Webpack
 
-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
+```js
 // 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: /\.ts$/, use: "ts-loader", exclude: /node_modules/ },
       {
         test: /\.html$/,
         use: [{ loader: larkMvcLoader }],
-        exclude: /index\.html$/, // Exclude the entry HTML page
+        exclude: /index\.html$/,
       },
     ],
   },
-  plugins: [
-    new HtmlWebpackPlugin({
-      template: "./index.html",
-      inject: "body",
-      minify: false,
-    }),
-  ],
-  devServer: {
-    port: 3001,
-    open: true,
-    hot: true,
-  },
-  devtool: "source-map",
 };
 ```
 
-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:
+Two important notes: the `loader` field must be imported as a value (`loader: larkMvcLoader`), not as a string name; you must use `exclude: /index\.html$/` to let `HtmlWebpackPlugin` handle the entry HTML, otherwise it will be compiled as a template.
 
-- 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$/,
-},
-```
+Both integrations share the same compilation pipeline: `extractGlobalVars` extracts external variables referenced in the template, and `compileTemplate` produces an ES module that imports helper functions from `@lark.js/mvc/runtime`.
 
-The `debug` option enables line tracking and detailed compile-time/runtime error messages with source mapping.
+## Five-Minute Quick Start
 
-### 4. Create Entry HTML
+### 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>
+    <title>Lark App</title>
   </head>
   <body>
     <div id="app"></div>
@@ -229,22 +111,18 @@ The `debug` option enables line tracking and detailed compile-time/runtime error
 </html>
 ```
 
-The `<div id="app">` corresponds to `rootId: "app"` in the boot config.
+`<div id="app">` corresponds to `rootId: "app"` in the boot configuration. `boot.ts` must reside in `src/` because the HTML references `/src/boot.ts`; placing it at the project root will cause a runtime resolution failure.
 
-For Webpack, the entry HTML uses HtmlWebpackPlugin instead of a `<script>` tag. HtmlWebpackPlugin automatically injects the bundled script.
+### Project-Level Base View
 
-### 5. Create a Project Base View
-
-```typescript
+```ts
 // src/view.ts
-import { View, Router } from "@lark.js/mvc";
+import { defineView, Router } from "@lark.js/mvc";
 
-export default View.extend({
+export default defineView({
   make() {
     this.updater.set({ appName: "My App" });
-    this.on("destroy", () => {
-      console.log(`View destroyed: ${this.id}`);
-    });
+    this.on("destroy", () => console.log(`view destroyed: ${this.id}`));
   },
   navigate(path: string, params?: Record<string, unknown>) {
     Router.to(path, params);
@@ -252,462 +130,848 @@ export default View.extend({
 });
 ```
 
-**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()`.
+`defineView` is a typed wrapper around `View.extend`: via `ThisType<P & ViewInterface>` it threads the literal's own fields into `this`, so writing `this.appName` in `make` requires no cast. Runtime behavior is equivalent to `View.extend({...})`.
 
-### 6. Define Stores
+### View and Template
 
-```typescript
-// src/store/count.ts
-import { defineStore, cell, observeCell, multi } from "@lark.js/mvc";
+```html
+<!-- src/views/home.html -->
+<div>
+  <h1>{{=title}}</h1>
+  <p>Count: {{=count}}</p>
+  <button @click="incr()">+1</button>
+  {{if count > 0}}
+  <p>Positive</p>
+  {{else}}
+  <p>Zero or negative</p>
+  {{/if}}
+  <ul>
+    {{forOf items as item idx}}
+    <li id="item-{{=item.id}}">{{=idx}}: {{=item.name}}</li>
+    {{/forOf}}
+  </ul>
+  <div v-lark="components/counter-store"></div>
+</div>
+```
 
-export interface CountStore {
-  count: number;
-  step: number;
-  history: string[];
-  increment: () => void;
-  decrement: () => void;
-  reset: () => void;
-  setStep: (val: number) => void;
-  clearHistory: () => void;
-  registerObservers: () => void;
-}
+```ts
+// src/views/home.ts
+import { bindStore } from "@lark.js/mvc";
+import View from "../view";
+import template from "./home.html";
+import useCountStore from "../store/count";
 
-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
-        });
-      },
-    };
+export default View.extend({
+  template,
+  init() {
+    this.assign();
+    bindStore(this, useCountStore, (s) => ({ count: s.count }));
   },
-);
-
-export default useCountStore;
+  assign() {
+    this.updater.snapshot();
+    const { count } = useCountStore.getState();
+    this.updater.set({
+      title: "Home",
+      count,
+      items: [
+        { id: "a", name: "Alpha" },
+        { id: "b", name: "Beta" },
+      ],
+    });
+    return this.updater.altered();
+  },
+  render() {
+    this.updater.digest();
+  },
+  "incr<click>"() {
+    useCountStore.getState().increment();
+  },
+});
 ```
 
-**Creator function signature**: `(store, apis) => initialState`
+### Boot
 
-- `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
+```ts
+// src/boot.ts
+import { Framework, registerViewClass, View } from "@lark.js/mvc";
+import type { FrameworkConfig } from "@lark.js/mvc";
+import HomeView from "./views/home";
+import AboutView from "./views/about";
+import NotFoundView from "./views/404";
 
-### Standalone Reactive Cells
+registerViewClass("home", HomeView as typeof View);
+registerViewClass("about", AboutView as typeof View);
+registerViewClass("404", NotFoundView as typeof View);
 
-For simple reactive data that doesn't need the full store pattern, use `cell` and `observeCell`:
+const config: FrameworkConfig = {
+  rootId: "app",
+  defaultPath: "/home",
+  defaultView: "home",
+  routes: {
+    "/home": "home",
+    "/about": "about",
+  },
+  unmatchedView: "404",
+  error(e) {
+    console.error("Lark error:", e);
+  },
+};
 
-```typescript
-import { cell, observeCell } from "@lark.js/mvc";
+Framework.boot(config);
+```
 
-// Create a standalone reactive cell
-const count = cell(0);
+`Framework.boot()` executes the following steps in order (order is correctness-sensitive): merge user config (including `routeMode`), inject config into Router (which determines history/hash mode), set EventDelegator's frame getter, subscribe to Router/State `changed` events, mark Framework/Router/State as booted, install the Frame Visualizer Bridge, create the root Frame via `Frame.createRoot(config.rootId)`, call `Router._bind()` to bind route events (popstate for history mode, hashchange + popstate for hash mode) and trigger the first `diff()`, and finally mount `defaultView` if Router has not mounted a view. Step seven must precede step eight because the first `diff()` may immediately trigger `CHANGED` followed by `Frame.getRoot()`, and if the root Frame does not exist it degrades to rendering against the wrong element.
 
-// Observe changes
-const unobserve = observeCell(count, () => {
-  console.log("count changed:", count.count);
-});
+## Three Data Pipelines: Updater / State / Store
 
-// Mutate (triggers observer)
-count.count = 1;
+Lark provides three data flow mechanisms simultaneously, ranging from simple to complex, corresponding to "view-private", "lightweight cross-view sharing", and "complex reactive cross-view sharing". Choose the simplest approach that meets your needs to reduce cognitive overhead.
 
-// Clean up
-unobserve();
+### Updater: View-Private
+
+`Updater` is each View's local data manager. All intra-view data flow ultimately goes through the Updater:
+
+```ts
+this.updater.set({ count: newCount });
+this.updater.digest();
 ```
 
-`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).
+Full pipeline: `updater.set(data)` shallow-merges data into the internal data object and collects changed keys. `updater.digest()` calls the compiled template function to generate an HTML string. `vdomGetNode` uses `tmp.innerHTML = wrap + html` to parse it into temporary DOM. `vdomSetChildNodes` compares against the live DOM to produce a keyed diff. DOM operations are applied in batch. `endUpdate()` notifies child Frames to complete mounting.
 
-### Multi-Instance Stores
+Supports digest re-entry: calling `updater.digest()` during an active digest does not nest; instead it queues to `digestingQueue` and executes after the current digest completes. `null` serves as a digest boundary sentinel in the queue.
 
-When a component is used multiple times on the same page and each instance needs independent state, use `multi`:
+### State: Lightweight Cross-View
 
-```typescript
-import { defineStore, multi } from "@lark.js/mvc";
+`State` is a global singleton key-value container, suitable for lightweight shared values like page title, login info, or current theme:
 
-const useCounterStore = defineStore("counter", (store) => ({
-  count: 0,
-  increment() {
-    store.count++;
-  },
-}));
+```ts
+import { State } from "@lark.js/mvc";
+
+State.set({ pageTitle: "Home", isLoggedIn: true });
+State.digest();
+```
 
-// multi() returns [useFn, mixinObj]
-const [useMultiCounter, counterMixin] = multi(useCounterStore);
+Subscription has two approaches. First, declare `observeState` in a view, and the framework automatically re-renders when the corresponding keys change:
 
-// In the view:
+```ts
 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"]);
+  observeState: "pageTitle,isLoggedIn",
+  assign() {
+    this.updater.snapshot();
+    this.updater.set({
+      title: State.get("pageTitle"),
+      logged: State.get("isLoggedIn"),
+    });
+    return this.updater.altered();
   },
 });
 ```
 
-`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()`.
+Second, listen directly to the `changed` event where `e.keys` is a `ReadonlySet<string>`:
 
-### 7. Create a View with Template
+```ts
+State.on("changed", (e) => {
+  if (e.keys?.has("pageTitle")) console.log("Title changed");
+});
+```
 
-```typescript
-// src/views/home.ts
-import { Router } from "@lark.js/mvc";
-import View from "../view";
-import template from "./home.html";
-import useCountStore from "../store/count";
+State manages lifecycle through reference counting on keys. Best practice is to add a `State.clean` mixin to all consumers, ensuring that when the last observer is destroyed, the key is automatically reclaimed:
 
+```ts
 export default View.extend({
+  mixins: [State.clean("pageTitle,isLoggedIn")],
   template,
+});
+```
 
-  init() {
-    this.assign();
+Without cleanup, keys persist on global State causing leaks.
 
-    // Observe count store -- changes trigger automatic view re-render
-    const store = useCountStore(this);
-    store.observe(this, ["count", "step"]);
-  },
+### Store: Zustand-Style State Management
 
-  assign() {
-    this.updater.snapshot();
+The Store API aligns with zustand's design: `create(name, (set, get) => body)` returns a `StoreApi` object providing `getState` / `setState` / `subscribe` / `destroy`. State is a plain object with no Proxy; all writes must go through `setState` or actions. `bindStore(view, store, selector?)` binds a store to a Lark View with automatic unsubscription on view destruction.
 
-    const store = useCountStore();
-    this.updater.set({
-      title: "Home",
-      count: store.count,
-      step: store.step,
-    });
+```ts
+// src/store/count.ts
+import { create, computed } from "@lark.js/mvc";
 
-    return this.updater.altered();
-  },
+interface CountStore {
+  count: number;
+  step: number;
+  doubled: number;
+  history: string[];
+  increment: () => void;
+  decrement: () => void;
+  reset: () => void;
+}
 
-  render() {
-    this.updater.digest();
+const useCountStore = create<CountStore>("count", (set, get) => ({
+  count: 0,
+  step: 1,
+  doubled: computed(["count"], () => get().count * 2),
+  history: [] as string[],
+  increment() {
+    const { count, step } = get();
+    set({
+      count: count + step,
+      history: [...get().history, `+${step} -> ${count + step}`],
+    });
   },
-
-  "navigateTo<click>"(e: Record<string, unknown>) {
-    const params = e["params"] as Record<string, string> | undefined;
-    const path = params?.path;
-    if (path) Router.to(path);
+  decrement() {
+    const { count, step } = get();
+    set({ count: count - step });
   },
-});
+  reset() {
+    set({ count: 0, history: [] });
+  },
+}));
+
+export default useCountStore;
 ```
 
-### 8. Write Templates
+The creator function receives `(set, get)` and executes once during `create`. Lark iterates the return value: functions become actions (attached to state, unaffected by `setState`); `computed(deps, fn)` occupies a derived slot, running `fn()` once for the initial value and recomputing whenever any dep key changes via `setState`; all other fields become initial state. Writing to a computed key via `setState` is silently ignored.
 
-```html
-<!-- src/views/home.html -->
-<div>
-  <h1>{{=title}}</h1>
-  <div>Count: {{=count}}</div>
-  <button @click="navigateTo({path: '/about'})">About</button>
+Reading and writing state:
 
-  {{if count > 0}}
-  <p>Positive</p>
-  {{else}}
-  <p>Zero or negative</p>
-  {{/if}}
+```ts
+// Read
+const { count, step } = useCountStore.getState();
 
-  <ul>
-    {{forOf items as item idx}}
-    <li>{{=idx}}: {{=item}}</li>
-    {{/forOf}}
-  </ul>
+// Write (shallow merge)
+useCountStore.setState({ count: 5 });
+useCountStore.setState((prev) => ({ count: prev.count + 1 }));
 
-  <!-- Sub-view embedding -->
-  <div v-lark="components/child"></div>
-</div>
+// Call action
+useCountStore.getState().increment();
 ```
 
-### 9. Bootstrap the Application
+Binding in a view:
 
-```typescript
-// 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";
+```ts
+import { bindStore } from "@lark.js/mvc";
 
-// Register View classes to Frame
-registerViewClass("home", HomeView as typeof View);
-registerViewClass("about", AboutView as typeof View);
-registerViewClass("counter", CounterView as typeof View);
-registerViewClass("404", NotFoundView as typeof View);
-registerViewClass(
-  "components/counter-store",
-  CounterStoreComponent as typeof View,
-);
-registerViewClass(
-  "components/counter-updater",
-  CounterUpdaterComponent as typeof View,
-);
+export default View.extend({
+  template,
+  init() {
+    // Bind all non-function state keys to view updater; auto-unsubscribes on destroy
+    bindStore(this, useCountStore);
 
-const config: FrameworkConfig = {
-  rootId: "app",
-  defaultPath: "/home",
-  defaultView: "home",
-  routes: {
-    "/home": "home",
-    "/about": "about",
-    "/counter": "counter",
+    // Or use a selector to sync only specific keys
+    bindStore(this, useCountStore, (s) => ({ count: s.count }));
   },
-  unmatchedView: "404",
-  error(e: Error) {
-    console.error("Lark error:", e);
+  "increment<click>"() {
+    useCountStore.getState().increment();
   },
-};
-
-Framework.boot(config);
+});
 ```
 
-## Key Patterns
+Custom subscription callback (when data transformation is needed before sync):
+
+```ts
+init() {
+  const syncToView = () => {
+    const s = useCountStore.getState();
+    this.updater.digest({ count: s.count, isPositive: s.count > 0 });
+  };
+  const off = useCountStore.subscribe(syncToView);
+  this.on("destroy", off);
+  syncToView();
+}
+```
 
-### Event Method Naming
+Destroying a store:
 
-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`.
+```ts
+useCountStore.destroy(); // Clears all listeners, removes from registry
+```
 
-| 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                               |
+### Comparison
 
-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.
+| Dimension | State | Store |
+|-----------|-------|-------|
+| Write | `State.set(...)` + `State.digest()` | `store.setState(partial)` or action |
+| Read | `State.get(key)` | `store.getState()` |
+| Subscribe | `observeState` or `on("changed")` | `store.subscribe(listener)` or `bindStore` |
+| View binding | `observeState("keys")` | `bindStore(view, store, selector?)` |
+| Lifecycle | `State.clean` mixin auto-reclaims keys | `store.destroy()` manual teardown |
+| Derived data | Not supported | `computed(deps, fn)` |
+| Use case | Page title, login state, theme | Business entities, forms, complex cross-view state |
 
-The event object passed to handlers contains:
+Selection guide: start with State; upgrade to Store when you need actions, derived data, or fine-grained subscriptions; view-private data always goes through Updater.
 
-- `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.)
+## View Definition and Lifecycle
 
-When two mixins define the same event method, they are merged into a single function that calls both in sequence via a `handlerList` array.
+### Two Definition Approaches
 
-### Store Observe Variations
+`View.extend({...})` is the low-level primitive approach where all mixins, event methods, and lifecycle hooks are declared in the passed object:
 
-```typescript
-// Simple: auto-digest on key change
-store.observe(this, ["count", "step"]);
+```ts
+import { View } from "@lark.js/mvc";
 
-// With custom callback
-store.observe(this, ["count"], (changedMap) => {
-  console.log("count changed", changedMap);
+export default View.extend({
+  template,
+  init() { /* ... */ },
+  assign() { /* ... */ },
+  render() { /* ... */ },
 });
+```
 
-// With ObservePayload for fine-grained control
-store.observe(this, [
-  { key: "count", alias: "currentCount", lazy: false },
-  { key: "items", transform: (val) => ({ itemCount: val.length }) },
-]);
+`defineView({...})` is a typed wrapper that threads the literal's own fields into `this` via `ThisType<P & ViewInterface>`:
+
+```ts
+import { defineView } from "@lark.js/mvc";
 
-// Inner observe (no view binding, for store-internal reactions)
-store.observe(undefined, ["step"], () => {
-  store.count = 0; // Reset count when step changes
+export default defineView({
+  customField: "x",
+  init() {
+    console.log(this.customField);
+  },
 });
+```
+
+Both produce equivalent runtime artifacts; the difference is purely in TypeScript inference.
+
+### Lifecycle
+
+- `init(params?)` — Called when the view is first instantiated. `params` comes from query strings on `v-lark`. Read stores and call `this.assign()` to prepare initial data here.
+- `make()` — Called by the merged ctors pipeline; each mixin's `make` executes in order. Suitable for "run once per instance" initialization.
+- `assign()` — Should be called when data may have changed. Pattern: `this.updater.snapshot()` at the top, `this.updater.set(...)` in the middle, `return this.updater.altered()` at the end. The framework uses `altered()` to determine whether re-render is needed.
+- `render()` — Default implementation is `this.updater.digest()`. Wrapped by `View.wrapMethod`: increments signature on entry, handles pending endUpdate cleanup on exit.
+- Destruction — The framework automatically calls `release(key, true)` to release all `capture`d resources, cleans up event delegation, and sets signature to 0.
+
+`view.signature` marks async operation validity: greater than 0 means the view is alive (incremented on each render), 0 means destroyed. Never modify it manually.
+
+### Event Methods
 
-// 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
+Event methods are named `name<eventType>` or `$selector<eventType>`. `View.prepare` scans the prototype at class definition time, parsing methods into three maps (`$evtObjMap` / `$selMap` / `$globalEvtList`) written to the prototype, managed at runtime by `EventDelegator`.
+
+| Syntax | Meaning |
+|--------|---------|
+| `handler<click>` | Event on the view's root element |
+| `$selector<click>` | Delegated to child elements matching `.selector` |
+| `$<click>` | Empty selector, triggers Frame boundary event only |
+| `$window<resize>` | Delegated to `window` |
+| `$document<keydown>` | Delegated to `document` |
+| `handler<click,mousedown>` | Multi-event binding |
+| `name<click><ctrl>` | Fires only when Ctrl modifier is held |
+
+The event callback receives an object `e` that, beyond standard Event fields, provides `e.eventTarget` (the actual hit DOM element) and `e.params` (parsed from the `@event` parameter string). Multiple mixins defining the same event method name are merged into a handler chain called in mixin order.
+
+Event delegation implementation: `EventDelegator` attaches listeners on `document.body` in the capture phase. When an event fires, it walks from `e.target` up to body, calling `findFrameInfo` at each level to locate the owning View and filter handlers by selector. Reference counting manages addition/removal of same-name events on body to prevent duplicate binding or premature unbinding.
+
+### Resource Management
+
+`capture` registers "destroyable objects tied to the view lifecycle":
+
+```ts
+const timer = setInterval(tick, 1000);
+this.capture("myTimer", { destroy() { clearInterval(timer); } }, true);
+```
+
+The third parameter `destroyOnRender` when `true` causes automatic destruction and removal on the next render call; when `false` cleanup happens only on view destruction. `release(key, destroy = true)` manually removes an entry.
+
+### Async Safety
+
+Async callbacks may arrive after a view has re-rendered or been destroyed. `wrapAsync` adds a signature check layer:
+
+```ts
+async loadData() {
+  const safe = this.wrapAsync((data: unknown) => {
+    this.updater.set({ items: data }).digest();
+  });
+  const data = await fetch("/api/items").then((r) => r.json());
+  safe(data); // Will not execute if view has re-rendered or been destroyed
+}
 ```
 
-### Store Read/Write Behavior
+`mark(host, key)` / `unmark(host)` is the lower-level equivalent mechanism: returns a `() => boolean` validator. All mark state is stored in a module-level `WeakMap` rather than polluting the host object, so it works on `Object.freeze`d objects.
+
+## Router and Route Guards
+
+Router supports two routing modes, configured via `FrameworkConfig.routeMode`:
 
-The `useStore()` function returns a Proxy that separates state reads from handler access:
+- `"history"` (default): uses `history.pushState` / `popstate`, URLs like `/home?page=2`
+- `"hash"`: uses URL hash fragment, URLs like `#!/home?page=2`
 
-- **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
+All state parses into a single `Location` object; cache hits skip parsing.
 
-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.
+### Basic Usage
 
-### Router Two-Phase Change
+```ts
+import { Router } from "@lark.js/mvc";
 
-Route changes go through two phases:
+Router.to("/list", { page: 2 });           // path + params
+Router.to({ page: 3 });                    // params only
+Router.to("/list", { page: 2 }, true);     // replace mode
+Router.to("/list", { page: 2 }, false, true); // silent, no events
+```
 
-1. **`change` event** -- listeners can call `prevent()` or `reject()` to cancel navigation
-2. **`changed` event** -- URL has been updated, views are re-rendered
+```ts
+const loc = Router.parse();                // current Location
+const loc2 = Router.parse("https://x/?a=1#!/path?p=v");
+const diff = Router.diff();                // most recent LocationDiff
+```
 
-```typescript
+`Location` provides `path` / `params` / `hash` / `query` / `view` and a `get(key, defaultValue?)` method.
+
+### Two-Phase Change Event
+
+```ts
 Router.on("change", (e) => {
-  if (hasUnsavedChanges) {
-    e.prevent(); // Cancel navigation
+  if (hasUnsavedChanges) e.prevent();
+  else if (mustReject) e.reject();
+  else e.resolve();
+});
+Router.on("changed", (diff) => {
+  // diff: LocationDiff { params, path?, view?, force, changed }
+});
+```
+
+The `change` phase allows `prevent` (suspend further processing), `reject` (rollback URL to `lastHash`), or `resolve` (commit; if none is called explicitly, resolve is the default). The `changed` phase is the final notification where the framework re-mounts views.
+
+### Async Route Guards
+
+```ts
+const off = Router.beforeEach(async (to, from) => {
+  if (to.path === "/admin") {
+    const ok = await checkPermission();
+    return ok;
   }
+  return true;
 });
+// Unregister
+off();
 ```
 
-### Resource Management
+Guards execute in registration order. Any guard that returns/resolves to `false`, throws, or rejects will abort the navigation and rollback the URL. Returning `true` / `undefined` / any non-`false` value allows passage.
+
+### useUrlState: URL Parameter State Sync
+
+`useUrlState(view, initialState?)` reads URL query parameters into a state object and provides a `setState` function that writes changes back to the URL (via `Router.to()`). It automatically observes the specified parameter keys, re-rendering the view when the URL changes.
+
+```ts
+import { useUrlState } from "@lark.js/mvc";
+
+export default View.extend({
+  template,
+  init() {
+    const [state, setState] = useUrlState(this, { page: "1", size: "20" });
+    this.updater.set({ page: state.page, size: state.size }).digest();
+    this.setPageState = setState;
+  },
+  "nextPage<click>"() {
+    this.setPageState((prev) => ({ page: String(Number(prev.page) + 1) }));
+  },
+});
+```
+
+Supports both history and hash routing modes.
 
-Use `capture/release` for automatic cleanup:
+## Service Request Layer
+
+`Service` is a request management layer built on `fetch` (or any synchronous function) with built-in LFU caching, concurrent deduplication, serial queuing, and lifecycle events.
+
+### Defining Subclasses and Endpoints
+
+```ts
+import { Service, type Payload } from "@lark.js/mvc";
+
+const AppService = Service.extend(
+  (payload, callback) => {
+    fetch(payload.get<string>("url"), {
+      method: payload.get<string>("method") || "GET",
+      headers: { "Content-Type": "application/json" },
+      body: payload.get("data") ? JSON.stringify(payload.get("data")) : undefined,
+    })
+      .then((r) => r.json())
+      .then((data) => { payload.set(data); callback(); })
+      .catch(() => callback());
+  },
+  20, // cacheMax
+  5,  // cacheBuffer
+);
 
-```typescript
-const timer = setInterval(() => {
-  /* ... */
-}, 1000);
-this.capture(
-  "myTimer",
+AppService.add([
+  { name: "userList", url: "/api/users", cache: 60_000 },
   {
-    destroy() {
-      clearInterval(timer);
+    name: "userDetail",
+    url: "/api/users/:id",
+    cache: 30_000,
+    before(payload) {
+      payload.set("url", payload.get<string>("url").replace(":id", payload.get<string>("id")));
+    },
+    after(payload) {
+      const data = payload.get("data");
+      payload.set({ formatted: formatUser(data) });
     },
+    cleanKeys: "userList",
   },
-  true,
-);
-// destroyOnRender=true: destroyed on next render call
-// destroyOnRender=false: destroyed only on view destroy
+]);
 ```
 
-### Async Safety with wrapAsync
+### Using in Views
 
-```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
-}
+```ts
+export default View.extend({
+  template,
+  init() {
+    const service = new AppService();
+    this.capture("userService", service, true);
+    this.service = service;
+    this.loadData();
+  },
+  loadData() {
+    this.service.all("userList", (errors, payload) => {
+      if (!errors[0]) {
+        this.updater.set({ users: payload.get("data") }).digest();
+      }
+    });
+  },
+});
 ```
 
-### Sub-View Embedding
+| Method | Behavior |
+|--------|----------|
+| `service.all(attrs, done)` | Fetch all endpoints; callback `(errors, p1, p2, ...)` when all complete |
+| `service.one(attrs, done)` | Fetch all endpoints; callback `(error, payload, isLast, index)` on each completion |
+| `service.save(attrs, done)` | Same as `all` but skips cache, always makes a fresh request |
+| `service.enqueue(task)` | Add to serial queue |
+| `service.dequeue(...args)` | Take one item and execute |
+| `service.destroy()` | Destroy instance and cancel pending callbacks |
+
+### Caching and Deduplication
+
+`Cache` implements an LFU-style bounded cache: sorted by `(frequency, lastTimestamp)`, evicting `bufferSize` entries via single-pass partial selection (O(n*k), k typically 5) when capacity exceeds `maxSize + bufferSize`. `del` immediately removes from the `entries` array and `lookup` Map.
+
+`_pendingCacheKeys` tracks in-flight requests per `(endpoint, params)` key. Concurrent calls to the same key are added to a callback chain; a single request completes and invokes all callbacks, avoiding redundant network round-trips.
+
+`cleanKeys: "userList"` means the current endpoint, upon completion, clears the corresponding cache entry — commonly used to invalidate list queries after a write operation.
+
+## Template Syntax
+
+Template files use the `.html` extension and are compiled at build time by `larkMvcPlugin` / `larkMvcLoader` into ES modules exporting a `(data, viewId, refData) => string` render function.
+
+### Expression Operators
 
-Use the `v-lark` attribute to embed child views:
+| Syntax | Meaning |
+|--------|---------|
+| `{{=variable}}` | HTML-escaped output (escapes `& < > " ' \``) |
+| `{{!variable}}` | Raw output, use with caution (potential XSS) |
+| `{{@variable}}` | Reference lookup: stores the JS value in refData and produces a token, used with `@event` to pass live references |
+| `{{:variable}}` | Two-way binding marker; renders equivalently to `=` |
+
+### Control Flow
 
 ```html
-<div v-lark="components/child-view"></div>
+{{if condition}}...{{else if other}}...{{else}}...{{/if}}
+{{forOf list as item}} ... {{/forOf}}
+{{forOf list as item idx}} {{=idx}}: {{=item.name}} {{/forOf}}
+{{forOf list as {name, age} idx last first}} ... {{/forOf}}
+{{forIn object as value key}} ... {{/forIn}}
+{{for (let i = 0; i < n; i++)}} ... {{/for}}
+{{set localVar = expr}}
 ```
 
-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`.
+`forOf` requires the `as` keyword. `{{forOf list item}}` is a compile-time error; the correct form is `{{forOf list as item}}`.
 
-### Updater vs State vs Store Data Flow
+### Event Binding
 
-Three patterns for managing view data. When no store is specified, State is the default cross-view state management:
+```html
+<button @click="handlerName({key: 'value', other: 123})">Go</button>
+<input @input="onInput()" />
+<form @submit.prevent="onSubmit()">...</form>
+```
 
-**Updater pattern** (view-local, manual):
+The compiler converts JS object literal parameters (`{a:1}`) to URL query string format (`a=1`) for transmission through DOM attributes, and injects the current view's `$viewId` with SPLITTER delimiters into the attribute so that EventDelegator routes events to the correct view and method across nested Frame boundaries.
 
-```typescript
-this.updater.set({ count: newCount }).digest();
+### Child View Embedding
+
+```html
+<div v-lark="components/child"></div>
+<div v-lark="components/child?title=hello&id=42"></div>
+<div v-lark="remote-app/views/home"></div>
 ```
 
-**State pattern** (default cross-view, key-ref counting):
+With query strings, parameters are translated into the first argument of the child view's `init`. When containing SPLITTER reference tokens, `translateData` resolves original JS values from the parent view's refData before passing them to the child.
 
-```typescript
-// Write: set data and digest to notify
-State.set({ count: newCount }).digest();
+### VDOM Optimization Hints
 
-// Read: in view's assign(), pull from State
-assign() {
-  this.updater.snapshot();
-  this.updater.set({ count: State.get("count") });
-  return this.updater.altered();
-}
+| Attribute | Purpose |
+|-----------|---------|
+| `ldk` | diff key: when old and new ldk match, the entire subtree's diff is skipped |
+| `lak` | attribute key: skips attribute diff but children continue to diff |
+| `lvk` | view key: assign optimization marker |
 
-// 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
-});
+Marking large static subtrees with `ldk` can completely skip rendering work. This is currently the framework's only "fine-grained skip diff" mechanism; the compiler does not automatically mark fully static subtrees.
 
-// Cleanup: use State.clean() in mixins to auto-delete keys on view destroy
-export default View.extend({
-  mixins: [State.clean("count")],
+## Frame and the View Tree
+
+`Frame` manages view mounting and unmounting, maintains parent-child relationships, and provides cross-view method invocation. Each Frame corresponds to one DOM container and one View instance.
+
+### Typed API
+
+| API | Description |
+|-----|-------------|
+| `Frame.get(id)` | Look up Frame by DOM id |
+| `Frame.getAll()` | All Frames as `Map<string, Frame>` |
+| `Frame.getRoot()` | Current root Frame; returns `undefined` if not created |
+| `Frame.createRoot(id)` | Idempotent root creation (`Framework.boot` calls this) |
+| `Frame.root(id)` | `@deprecated` alias, forwards to `createRoot` |
+| `new Frame(containerId)` | Independent Frame instance for micro-frontend / embedded widget scenarios |
+| `frame.invoke(name, args?)` | Call the owning view's method; if view not mounted, pushes to `invokeList`, flushed by `View.runInvokes(frame)` after mounting |
+| `frame.children()` | Child Frame id array (order not guaranteed) |
+| `frame.parent(level?)` | Ancestor Frame, defaults to one level up |
+| `frame.mountFrame(id, viewPath, params?)` | Explicitly create a child Frame |
+| `frame.unmountFrame(id)` | Unmount a specific child Frame |
+| `frame.mountZone(id?)` / `frame.unmountZone(id?)` | Batch mount/unmount all `v-lark` child nodes in a zone |
+| `Frame.on("add" \| "remove", handler)` | Frame instance lifecycle events (static emitter) |
+| `frame.on("created" \| "alter", handler)` | All child Frames rendered / child content changed (instance emitter) |
+
+Frame instances enter `frameCache` object pool upon destruction, caching up to `MAX_FRAME_POOL = 64`; beyond that threshold they are GC'd. Do not retain Frame references after unmounting as the object may be reused.
+
+## Module Federation Micro-Frontend
+
+Lark treats Module Federation as a first-class citizen, providing two integration modes.
+
+### Mode 1: Direct Async Loading
+
+Via `FrameworkConfig.require`, resolve unregistered view paths to remote modules:
+
+```ts
+Framework.boot({
+  rootId: "app",
+  projectName: "host-app",
+  crossConfigs: [
+    { projectName: "remote-app", source: "remote_app@//cdn.example.com/remote-app/remoteEntry.js" },
+  ],
+  require: async (names: string[]) => {
+    await __webpack_init_sharing__("default");
+    const container = __webpack_share_scopes__["default"];
+    return Promise.all(names.map(async (name) => {
+      const slash = name.indexOf("/");
+      const remote = slash > -1 ? name.substring(0, slash) : name;
+      const mod = slash > -1 ? name.substring(slash + 1) : "./index";
+      const rc = (window as Record<string, unknown>)[remote];
+      if (!rc) return undefined;
+      await rc.init(container);
+      const factory = await rc.get(`./${mod}`);
+      const raw = factory();
+      return raw && raw.__esModule ? raw.default : raw;
+    }));
+  },
 });
 ```
 
-Key differences from Store:
+Then write `v-lark="remote-app/views/home"` in templates to trigger async loading and mounting of the remote view.
 
-- 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
+### Mode 2: CrossSite Bridge View
 
-**Store pattern** (cross-view, reactive, recommended):
+For skeleton screens and remote `prepare` hooks, use `CrossSite`:
 
-```typescript
-const store = useCountStore(this);
-store.observe(this, ["count"]);
-// Later, from any view:
-useCountStore().increment(); // Automatically triggers re-render in all observing views
+```ts
+import { CrossSite, registerViewClass } from "@lark.js/mvc";
+registerViewClass("cross-site", CrossSite);
 ```
 
-### Frame Tree Events
+```html
+<div v-lark="cross-site?view=remote-app/views/home&bizCode=mybiz"></div>
+```
+
+CrossSite first renders as a normal view showing a skeleton (default `Loading...`, overridable via `skeleton` parameter) and occupies a `<div id="mf_${viewId}">` sub-container. `updateView()` uses `++this.$sign` to get a sequence number, loads the remote prepare module via `use(projectName/prepare)` and executes it. Race guard: if after loading `this.$sign !== sign`, return immediately (user navigated away). If the same view path as last time and the remote view exposes an `assign` method, it calls `assign` + `render` in-place to reuse the existing view; otherwise it calls `owner.mountFrame('mf_' + this.id, this.$view, this.$params)` to actually mount.
+
+### Webpack Configuration
+
+Host:
 
-Frame fires lifecycle events:
+```js
+new ModuleFederationPlugin({
+  name: "host_app",
+  remotes: { "remote-app": "remote_app@//cdn.example.com/remote-app/remoteEntry.js" },
+  shared: { "@lark.js/mvc": { singleton: true, requiredVersion: "^1.0.0" } },
+});
+```
 
-- `add` -- new Frame created
-- `remove` -- Frame removed
-- `created` -- all child Frames rendered
-- `alter` -- child Frame content changed
+Remote:
 
-```typescript
-Frame.on("add", ({ frame }) => {
-  /* ... */
+```js
+new ModuleFederationPlugin({
+  name: "remote_app",
+  filename: "remoteEntry.js",
+  exposes: { "./views/home": "./src/views/home", "./prepare": "./src/prepare" },
+  shared: { "@lark.js/mvc": { singleton: true, requiredVersion: "^1.0.0" } },
 });
 ```
 
-### Vite vs Webpack Comparison
+`@lark.js/mvc` must be `singleton: true`; otherwise host and remote hold different View/Frame class instances and all `instanceof` checks fail across boundaries.
+
+`splitChunks.chunks` must be `"async"`. Using `"all"` extracts `@lark.js/mvc` into a separate vendor chunk, breaking MF shared scope initialization (`ScriptExternalLoadError: Loading script failed`).
+
+## Debugging and DevTools Bridge
+
+### Global Objects
 
-| 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 |
+After `Framework.boot` completes, the following are attached to `window`:
+
+| Global | Value | Purpose |
+|--------|-------|---------|
+| `window.__lark_Framework` | Framework object | Direct access |
+| `window.__lark_State` | State object | Direct access |
+| `window.__lark_Router` | Router object | Direct access |
+| `window.__lark_Frame` | Frame class | Direct access |
+| `window.__lark_View` | View class | Direct access |
+| `window.__lark_registerViewClass` | Function | HMR: re-register View class |
+| `window.__lark_invalidateViewClass` | Function | HMR: remove View from registry |
+| `window.__lark_getViewClassRegistry` | Function | HMR: read registry |
+| `window.__lark_Debug` | boolean, must be set manually | Enable Safeguard Proxy debug checks |
+
+### Safeguard Debug Mode
+
+Set `window.__lark_Debug = true` before boot, and the framework wraps `State.get()` / `Router.diff()` results and `Updater.get()` return values with Safeguard Proxy:
+
+- Warns when reading data written by another page (potential cross-page pollution).
+- Warns immediately when assigning directly to objects returned by `State.get()` (deduplicated by key); the correct approach is `State.set(patch)` + `State.digest()`.
+
+### Frame Visualizer Bridge
+
+`installFrameVisualizerBridge()` is automatically installed during `Framework.boot`, listening for `window` message events and communicating with DevTools via postMessage:
+
+- `LARK_VIS_PING` — responds with `LARK_VIS_PONG` to confirm this page is a Lark application.
+- `LARK_VIS_REQUEST_TREE` — responds with `LARK_VIS_TREE` carrying `SerializedFrameTree`.
+- Internally listens to `Frame.on('add' | 'remove')` and automatically pushes `LARK_VIS_TREE_DELTA`; JSON.stringify is compared with `lastTreeJson` before pushing to avoid flooding when nothing changed.
+
+The `lark-visual` sub-project in this repository is the paired visual DevTools that loads the target application via iframe to display the real-time Frame tree.
+
+## Public API Reference
+
+### Framework
+
+- `Framework.boot(config)` — Start the application.
+- `Framework.getConfig()` / `Framework.getConfig(key)` — Read configuration.
+- `Framework.setConfig(patch)` — Merge configuration, returns merged result.
+- `Framework.use(names, callback?)` — Async view loader; returns `Promise<unknown[]>` when no callback.
+- `Framework.mark(host, key)` / `Framework.unmark(host)` — Async callback validity tracking via module-level `WeakMap`.
+- `Framework.dispatch(target, type, init?)` — Trigger custom DOM event.
+- `Framework.task(fn, args?, ctx?)` — Chunked execution: prefers `scheduler.postTask` then `requestIdleCallback` then `setTimeout(0)`, with a fixed 48ms budget or adaptive time slicing.
+- `Framework.delay(ms)` — Promise-wrapped setTimeout.
+- `Framework.waitZoneViewsRendered(viewId, timeout?)` — Wait until all views in a zone have rendered.
+- `Framework.applyStyle(idOrPairs, css?)` — Dynamically inject CSS, returns cleanup function.
+
+### Updater
+
+- `updater.get(key?)` — Read data; returns entire data object when no key.
+- `updater.set(data, excludes?)` — Shallow merge and collect changed keys.
+- `updater.digest(data?, excludes?, callback?)` — Render; supports re-entry via `digestingQueue`.
+- `updater.snapshot()` — Record current monotonic version.
+- `updater.altered()` — Check if changed, returns `boolean | undefined`.
+- `updater.translate(value)` — Resolve SPLITTER + number reference tokens to original values.
+- `updater.parse(expr)` — Safe path parser: dot paths (`a.b.c`) or numeric literals only, no eval.
+- `updater.getChangedKeys()` — `ReadonlySet<string>` of keys changed since last digest.
+
+### Store (zustand-style)
+
+- `create(name, (set, get) => body)` — Create store, returns `StoreApi`.
+- `store.getState()` — Read current state.
+- `store.setState(partial | updater)` — Shallow merge, notify all listeners.
+- `store.subscribe(listener)` — Listen for changes, returns unsubscribe function.
+- `store.destroy()` — Destroy store, clear listeners.
+- `computed(deps, fn)` — Declare derived state.
+- `bindStore(view, store, selector?)` — Bind to Lark View with auto-sync and auto-cleanup.
+- `useUrlState(view, initialState?)` — URL parameter state sync.
 
 ## 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
+1. `boot.ts` must be inside `src/`: HTML references `/src/boot.ts`; placing it at the project root causes runtime resolution failure.
+2. `registerViewClass` must precede `Framework.boot()`: all View classes (including sub-components) must either be pre-registered or loaded via `FrameworkConfig.require`.
+3. `.html` imports require build integration: only works in projects compiled by `larkMvcPlugin` / `larkMvcLoader`.
+4. Write State with `State.set` + `State.digest`, never mutate the returned object directly: Safeguard warns in debug mode, deduplicated by key.
+5. `bindStore` auto-unsubscribes on view destroy; manual `store.subscribe(listener)` calls need explicit cleanup (e.g., `this.on("destroy", off)`).
+6. Event methods use `<>` not `()`: write `name<click>`, not `name(click)`.
+7. `assign()` must have `snapshot` at the top and `return altered()` at the bottom: both are required for the framework to determine re-render necessity.
+8. Never modify `view.signature`: internally managed; 0 means destroyed, render wrapper auto-increments.
+9. `v-lark` container content is replaced: do not put scaffold text inside.
+10. Webpack must use `exclude: /index\.html$/`: entry HTML is handled by HtmlWebpackPlugin.
+11. Webpack loader must be imported as a value: `loader: larkMvcLoader`, not a string name.
+12. Store state is a plain object: `store.getState()` returns the actual state object; reads are direct access, writes must go through `setState()` or actions.
+13. `forOf` requires `as`: `{{forOf list item}}` is a compile error.
+14. `wrapAsync` validates by signature: callback only executes when `view.signature` matches the value at wrap time.
+15. Frame object pool caps at `MAX_FRAME_POOL = 64`: do not retain Frame references after `unmountFrame`.
+16. Updater supports digest re-entry: digest during digest enters `digestingQueue`; `null` is the boundary.
+17. Store creator runs once: state persists across view mount/unmount cycles; call `store.destroy()` to tear down.
+18. State is simple, Store is complex: lightweight shared values use State; use `create()` for actions, derived data, or fine-grained subscriptions; always pair State writes with `mixins: [State.clean("keys")]` to prevent leaks.
+19. MF view paths use the remote project name as prefix: `v-lark="remote-app/views/home"` triggers async loading via `FrameworkConfig.require` when unregistered; `@lark.js/mvc` must be `singleton: true`.
+20. `splitChunks.chunks` must be `"async"` in MF projects: `"all"` breaks shared scope initialization.
+
+## Recent API Changes
+
+- Store rewrite (zustand-style):
+  - `defineStore(name, (store) => body)` replaced by `create(name, (set, get) => body)`. `defineStore` retained as deprecated alias.
+  - `store.key = value` (Proxy write) replaced by `set({ key: value })`.
+  - `store.key` reads in actions replaced by `get().key`.
+  - `useStore(view)` + `store.observe(view, keys?)` replaced by `bindStore(view, store, selector?)`.
+  - `useStore()` (read-only access) replaced by `store.getState()`.
+  - `store.observe(undefined, keys, cb)` (internal reaction) replaced by `store.subscribe((state, prev) => ...)`.
+  - Removed: `multi()`, `cell()`, `observeCell()`, `cloneStore()`, `getStore()`, `delStore()`, `getUseStore()`, `isStoreActive()`, `createState()`, `shallowSet()`, `lazySet()`, `cloneData()`, `isState()`, `storeMark`, `storeUnmark`, `getPlatform`, `Platform`, `StoreConfig`, `ObservePayload`, `StoreMethods`, `LarkUseStore`, `ReactUseStore`, `NodeUseStore`.
+- Router history mode support:
+  - Added `FrameworkConfig.routeMode` (`"history"` default, `"hash"` optional).
+  - In history mode, path comes from `window.location.pathname`, params from search query string.
+  - Added `useUrlState(view, initialState?)` for URL parameter state sync.
+- `ChangeEvent.keys` changed to `ReadonlySet<string>` (was `Record<string, 1>`). Use `keys.has("foo")` instead of `keys.foo`.
+- `StateInterface.diff()` returns `ReadonlySet<string>`.
+- `Updater.set/digest`, `State.set/digest`, `setData` `excludes?` changed to `ReadonlySet<string>` (was `Set<string>`).
+- `Frame.root(id)` `@deprecated`. Read via `Frame.getRoot()`, create singleton via `Frame.createRoot(id)`, independent mount via `new Frame(id)`.
+- `Updater.parse` no longer evals; only supports safe paths and literals.
+- `mark.ts` no longer writes magic keys to host objects; uses module-level `WeakMap`, works on `Object.freeze`d objects.
+- `Cache.del` immediately removes from `entries` array and `lookup` Map (previously left tombstones until next eviction).
+
+## Comparison with Vue 3 / React 19
+
+### vs Vue 3
+
+Similarities: templates compile to functions; reactivity via Proxy; derived data with `computed`; microtask batching; component-level granular updates.
+
+| Dimension | Vue 3 | Lark |
+|-----------|-------|------|
+| Component abstraction | SFC / function components / Options | Class inheritance `View.extend` / `defineView` |
+| Render output | VNode patch | HTML string parsed to real DOM + diff |
+| Template syntax | `v-if` / `v-for` / `:bind` | `{{if}}` / `{{forOf}}` / `@event` / `v-lark` |
+| Dependency tracking | Automatic effect tracking | subscribe + bindStore + computed |
+| Compile optimizations | PatchFlag / hoistStatic / cacheHandler | Only `ldk` / `lak` / `lvk` user-manual markers |
+| Micro-frontend | Third-party (qiankun / wujie etc.) | Built-in `CrossSite` + `FrameworkConfig.require` |
+| Scheduling | Microtask batching + nextTick | Microtask batching + `Framework.task` sliceable queue |
+
+The key difference is render output: Vue uses virtual node patching; Lark generates HTML strings, parses them via innerHTML into a temporary div, then diffs the resulting real DOM. The advantage is that context-sensitive tags (`<table>` / `<select>` / `<svg>`) are handled by the native parser nearly for free; the disadvantage is the absence of PatchFlag-style compile-time annotations (only user-manual `ldk` / `lak` / `lvk`).
+
+### vs React 19
+
+Similarities: unidirectional data flow; immutable write-back style; async protection (`wrapAsync` is analogous to `useEffect` cleanup + AbortController); microtask batching; global error boundary (`FrameworkConfig.error` + `funcWithTry`).
+
+| Dimension | React 19 | Lark |
+|-----------|----------|------|
+| Component abstraction | Function components + Hooks | Class inheritance `View.extend` / `defineView` |
+| State encapsulation | `useState` / `useReducer` | View instance fields, `create()` store, `State` |
+| Side effects | `useEffect` / `useLayoutEffect` | `init` / `make` + `capture` / `release` |
+| Render interruption | Fiber time-slicing, Suspense, Transition | Synchronous digest, not interruptible |
+| Compile optimization | React Compiler (auto-memo) | Template compile-time only; no runtime auto-memo |
+| Server rendering | RSC, streaming SSR | Not supported (design trade-off) |
+| Cross-platform | React Native / DOM | Web DOM only |
+| Event system | Synthetic Event | `document.body` capture-phase delegation + selector matching |
+| Route guards | Third-party router libraries | Built-in `Router.beforeEach(asyncGuard)` + two-phase change |
+
+The key difference is scheduling: React 19's Concurrent mode can interrupt and restart renders by lane priority. Lark's `Updater.digest()` is synchronous (though the internal `digestingQueue` supports re-entry) and never yields the main thread. For large lists or frequent updates, Lark has no time-slicing mechanism, which may cause long tasks; the advantage is predictable behavior and simpler debugging.
+
+## Testing and Local Development
+
+```bash
+pnpm install
+pnpm test            # vitest unit tests
+pnpm test:coverage   # coverage report
+pnpm test:watch      # watch mode
+pnpm typecheck       # tsc --noEmit
+pnpm build           # tsup produces ESM + CJS + dts
+pnpm format          # prettier formatting
+```
+
+`vitest.config.ts` targets the `tests/` directory with 16 test files covering core modules. `tsup.config.ts` defines four entry points (`index` / `vite` / `webpack` / `runtime`) with output in `dist/`.
+
+## License
+
+ISC. See `LICENSE` in the repository root.