@lark.js/mvc 0.0.5 → 0.0.6

package/README.md

@@ -1,131 +1,59 @@
----
-name: lark-mvc
-description: >
-  Comprehensive guide to the Lark MVC Framework (@lark.js/mvc) for building
-  TypeScript SPAs. Use this skill any time the user works with Lark — creating
-  Views with View.extend() or defineView(), defining reactive Stores with
-  defineStore() / computed() / multi(), wiring State for cross-view data,
-  setting up Router (including Router.beforeEach async guards), writing
-  HTML templates with {{=}}/{{forOf}}/{{if}}/@event/v-lark syntax, configuring
-  the Vite plugin or Webpack loader, registering Views with registerViewClass,
-  integrating Module Federation with CrossSite, calling Service for API
-  requests with caching/dedup/queue, or anything mentioning Frame trees,
-  hash routing, real-DOM diff, capture-phase event delegation, or the v-lark
-  attribute. Also trigger on Lark-related debugging (window.__lark_Debug,
-  Frame Visualizer Bridge, ldk/lak/lvk attributes) and on questions about
-  Lark's three data pipelines (Updater / State / Store) or migration patterns
-  between them.
----
+## @lark.js/mvc
 
-# Lark MVC Framework
+A TypeScript MVC framework designed for back-office single-page applications and micro-frontend scenarios.
 
-`@lark.js/mvc` is a TypeScript MVC framework for single-page applications. It pairs a strict Model-View-Controller layout with Proxy-based reactive state, hash-based routing, and a real-DOM diff renderer. The framework treats micro-frontend integration (Module Federation) as a first-class concern.
+`@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).
 
-This guide walks through architecture, the full public API, project layout, the three data pipelines, the template language, the build-tool integrations, and the common pitfalls. For exhaustive API signatures and template syntax, follow the pointers in [References](#references) at the end.
+- 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
 
-## When to reach for this skill
+## Table of Contents
 
-Any task that names — or clearly implies — Lark:
+- 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
 
-- Creating, extending, or registering Views; wiring view event handlers; setting up view lifecycle (`init`, `make`, `assign`, `render`, `destroy`).
-- Designing reactive state with `defineStore`, `cell`, `computed`, `multi`, or cross-view sharing through `State`.
-- Routing tasks: hash navigation, route guards (`Router.beforeEach`), two-phase `change`/`changed` events, `Router.to(...)`.
-- Authoring `.html` templates with the `{{=}}` / `{{forOf}}` / `{{if}}` / `@event` / `v-lark` syntax.
-- Configuring the Vite plugin (`larkMvcPlugin`) or Webpack loader (`larkMvcLoader`).
-- Embedding remote views via Module Federation (`CrossSite`, `FrameworkConfig.require`).
-- API request layers using `Service.extend`, `Service.add`, `service.all/one/save`, `cleanKeys`.
-- Debugging Frame trees, working with `window.__lark_Debug`, or the Frame Visualizer Bridge.
+## Design Goals and Use Cases
 
-## Architecture
+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.
 
-Lark separates code along three orthogonal axes:
+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.
 
-- **Model**: `State` (simple global singleton, recommended for lightweight cross-view values), `defineStore` (Proxy-based reactive store with handlers, `computed`, multi-instance support — recommended for complex reactive state), `cell`/`observeCell` (standalone reactive cells), `Service` (API request manager with LFU cache + deduplication + serial queue).
-- **View**: `View.extend()` and the typed `defineView()` factory both produce View subclasses. Views own templates, event handlers, the lifecycle, the per-view `Updater`, and resource bookkeeping.
-- **Controller**: `Router` (hash routing, two-phase change confirmation, `beforeEach` async guards), `Updater` (per-view data binding, change tracking, VDOM diff), `Frame` (the runtime tree of view containers, mount/unmount lifecycle, deferred `invoke` queue).
+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.
 
-### The three data pipelines
+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.
 
-Lark exposes three ways to flow data to a view. Pick the simplest one that solves the task.
+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.
 
-1. **Updater pipeline** (view-local). Use when only the current view reads and writes the data.
-   `updater.set(data)` → `updater.digest()` → compiled template function → HTML string → `vdomGetNode` parses it into a temporary DOM tree → `vdomSetChildNodes` diffs against the live DOM → DOM ops applied → `endUpdate()` notifies child frames.
+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.
 
-2. **State pipeline** (simple cross-view, recommended for lightweight shared values like counters, toggles, page title, session info).
-   `State.set(data)` → `State.digest()` → `changed` event fires with `keys: ReadonlySet<string>` → views listening read via `State.get()` in their `assign()` → standard Updater path. State uses key reference counting; pair with `mixins: [State.clean("a,b")]` so keys are removed when the last view unmounts.
+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.
 
-3. **Store pipeline** (complex cross-view, recommended when you need reactive handlers, derived data, multi-instance isolation, or store-internal reactions).
-   `store.key = value` → Proxy `set` trap → `trigger()` → `GlobalDeps` lookup → microtask-batched `Queue` → `store.observe` callbacks → standard Updater path. Supports `computed(deps, fn)` for derived state.
+## Installation and Build Tool Configuration
 
-### Boot sequence (order matters)
-
-`Framework.boot(config)` runs these steps in this exact order:
-
-1. Merge user config into the shared `config` object.
-2. Inject the merged config into `Router` via `Router._setConfig`.
-3. Set the EventDelegator's frame getter so global events can find views.
-4. Subscribe Router and State `changed` events to the dispatcher.
-5. Mark Framework / Router / State as booted.
-6. Install the Frame Visualizer Bridge (`postMessage` listener for DevTools).
-7. **Create the root Frame with `Frame.createRoot(config.rootId)` BEFORE step 8.**
-8. **Bind `Router._bind()` so hashchange/popstate/beforeunload fire — and Router.diff() runs once initially.**
-9. Mount the `defaultView` ONLY if Router didn't already mount one (e.g., after a page reload with `#!/counter`).
-
-The root must exist before `Router._bind()` because the initial `diff()` may immediately fire CHANGED → `dispatcherNotifyChange` → `Frame.getRoot()`. If the root didn't exist yet, Router would default to `"root"` and the view would render into the wrong element.
-
-### Window globals
-
-After boot, the framework attaches these to `window` for debugging and HMR:
-
-| 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_registerViewClass`    | function         | HMR helper: re-register a View class  |
-| `window.__lark_invalidateViewClass`  | function         | HMR helper: drop a View from registry |
-| `window.__lark_getViewClassRegistry` | function         | HMR helper: read the View registry    |
-| `window.__lark_Debug`                | boolean (opt-in) | Enables Safeguard Proxy debug checks  |
-
-Set `window.__lark_Debug = true` before boot to enable Safeguard Proxy wrapping on `State.get()` reads, `Router.diff()` results, Location params, and `Updater.get()` — it warns when data set on one page is read from a different page, and when something tries to mutate `State.get()` data directly instead of going through `State.set()` + `State.digest()`.
-
-## Project structure
-
-```
-project/
-├─ index.html            # entry, references <script type="module" src="/src/boot.ts">
-├─ vite.config.ts        # OR webpack.config.mjs
-└─ src/
-   ├─ boot.ts            # registerViewClass(...) + Framework.boot(config)
-   ├─ view.ts            # project-wide base view (re-export of defineView/View.extend)
-   ├─ styles.css
-   ├─ store/
-   │  └─ count.ts        # defineStore declarations
-   ├─ views/
-   │  ├─ home.ts
-   │  ├─ home.html       # compiled by larkMvcPlugin / larkMvcLoader
-   │  ├─ about.ts
-   │  └─ about.html
-   └─ components/        # sub-views embedded via v-lark
-      ├─ counter-store.ts
-      └─ counter-store.html
-```
-
-`boot.ts` must live inside `src/` — `index.html` references it as `/src/boot.ts`. Putting it at the project root breaks the import resolution at runtime.
-
-## Quick start
-
-### 1. Install
+### Installation
 
 ```bash
 pnpm add @lark.js/mvc
 ```
 
-### 2. Configure your bundler
-
-Vite (recommended):
+### Vite (Recommended)
 
 ```ts
 // vite.config.ts
@@ -139,40 +67,42 @@ export default defineConfig({
 });
 ```
 
-The plugin runs in the `pre` phase. Its `resolveId` hook tags `.html` imports with a `?lark-template` suffix so Vite doesn't treat them as static assets, then its `load` hook compiles the raw HTML through `extractGlobalVars()` + `compileTemplate()` into an ES module exporting `(data, viewId, refData) => string`.
+`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.
 
-For Webpack, mirror the same idea with the loader:
+### Webpack
 
 ```js
 // webpack.config.mjs
 import { larkMvcLoader } from "@lark.js/mvc/webpack";
 
 export default {
-  // ...
   module: {
     rules: [
       { test: /\.ts$/, use: "ts-loader", exclude: /node_modules/ },
       {
         test: /\.html$/,
         use: [{ loader: larkMvcLoader }],
-        exclude: /index\.html$/, // HtmlWebpackPlugin handles the entry HTML
+        exclude: /index\.html$/,
       },
     ],
   },
 };
 ```
 
-Both integrations accept `{ debug: true }` to inject source-position markers into the compiled template, so runtime errors point back to the original `.html` line and expression.
+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.
+
+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`.
+
+## Five-Minute Quick Start
 
-### 3. Entry HTML
+### Entry HTML
 
 ```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>
@@ -181,9 +111,9 @@ Both integrations accept `{ debug: true }` to inject source-position markers int
 </html>
 ```
 
-The `<div id="app">` matches `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.
 
-### 4. A project-level base View
+### Project-Level Base View
 
 ```ts
 // src/view.ts
@@ -191,11 +121,8 @@ import { defineView, Router } from "@lark.js/mvc";
 
 export default defineView({
   make() {
-    // Called once per instance via the merged ctors[] pipeline.
     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);
@@ -203,9 +130,66 @@ export default defineView({
 });
 ```
 
-`defineView` is a thin, type-safe wrapper around `View.extend`: it threads the literal's own shape into `this` via `ThisType<P & ViewInterface>`, so `this.appName` inside `make` is typed without manual casts. Runtime behavior is identical to `View.extend({...})`.
+`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({...})`.
+
+### View and Template
+
+```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>
+```
+
+```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";
+
+export default View.extend({
+  template,
+  init() {
+    this.assign();
+    bindStore(this, useCountStore, (s) => ({ count: s.count }));
+  },
+  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();
+  },
+});
+```
 
-### 5. Boot
+### Boot
 
 ```ts
 // src/boot.ts
@@ -228,7 +212,7 @@ const config: FrameworkConfig = {
     "/about": "about",
   },
   unmatchedView: "404",
-  error(e: Error) {
+  error(e) {
     console.error("Lark error:", e);
   },
 };
@@ -236,397 +220,357 @@ const config: FrameworkConfig = {
 Framework.boot(config);
 ```
 
-All view classes must be registered _before_ `Framework.boot()`. The registry lives in `src/view-registry.ts` and is exposed through `registerViewClass` (re-exported from `@lark.js/mvc`).
+`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.
 
-## Defining Stores
+## Three Data Pipelines: Updater / State / Store
 
-### Basic store
+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.
 
-```ts
-// src/store/count.ts
-import { defineStore } from "@lark.js/mvc";
+### Updater: View-Private
 
-interface CountStore {
-  count: number;
-  step: number;
-  doubled: number; // computed
-  history: string[];
-  increment: () => void;
-  decrement: () => void;
-  reset: () => void;
-}
+`Updater` is each View's local data manager. All intra-view data flow ultimately goes through the Updater:
 
-const useCountStore = defineStore<CountStore>(
-  "count",
-  (store, { computed, lazySet, shallowSet }) => ({
-    count: 0,
-    step: 1,
-    doubled: computed(["count"], () => store.count * 2),
-    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 = [];
-    },
-  }),
-);
-
-export default useCountStore;
+```ts
+this.updater.set({ count: newCount });
+this.updater.digest();
 ```
 
-### How the creator runs
+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.
 
-The creator runs once at definition time. Lark walks the return value:
+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.
 
-- Function entries become **handlers** on the store proxy (`store.increment()` invokes the original closure).
-- `computed(deps, fn)` markers occupy a reactive state slot. After every other state key is initialized, `computed` fires its `fn()` to produce the initial value, then registers an internal `track` so the dep keys re-run `fn` when they change. Writes to a computed key are silently ignored.
-- Everything else becomes initial state and is registered with the reactive Proxy.
+### State: Lightweight Cross-View
 
-### How `useStore(view)` works
+`State` is a global singleton key-value container, suitable for lightweight shared values like page title, login info, or current theme:
 
-- `useStore()` (no view) — read-only access for module-level utilities.
-- `useStore(view)` — registers the view in the store's `boundViews` set; on view destroy, the view is automatically detached.
-- Reading a state key (e.g. `store.count`) outside the creator returns a **deep-cloned copy** (via the native `structuredClone` when available). Mutating the returned value does NOT trigger reactivity.
-- Writing a state key (`store.count = 5`) goes through the reactive Proxy and triggers observers.
-- **Inside the creator**, `store.count` returns the raw reactive Proxy — direct mutation works and is reactive.
+```ts
+import { State } from "@lark.js/mvc";
 
-### Subscribing a view
+State.set({ pageTitle: "Home", isLoggedIn: true });
+State.digest();
+```
 
-`store.observe(view, keys?, defaultCallback?)` subscribes the view to store changes. Variations:
+Subscription has two approaches. First, declare `observeState` in a view, and the framework automatically re-renders when the corresponding keys change:
 
 ```ts
-// Default: observe every state key in the store (including computeds).
-// Avoids the "two lists to keep in sync" pain point.
-store.observe(this);
+export default View.extend({
+  template,
+  observeState: "pageTitle,isLoggedIn",
+  assign() {
+    this.updater.snapshot();
+    this.updater.set({
+      title: State.get("pageTitle"),
+      logged: State.get("isLoggedIn"),
+    });
+    return this.updater.altered();
+  },
+});
+```
 
-// Explicit: only the listed keys trigger updates.
-store.observe(this, ["count", "step"]);
+Second, listen directly to the `changed` event where `e.keys` is a `ReadonlySet<string>`:
 
-// With a custom callback (override the default updater.digest behavior).
-store.observe(this, ["count"], (changedMap) => {
-  console.log("count changed", changedMap);
+```ts
+State.on("changed", (e) => {
+  if (e.keys?.has("pageTitle")) console.log("Title changed");
 });
+```
 
-// Fine-grained ObservePayload entries.
-store.observe(this, [
-  { key: "count", alias: "currentCount", lazy: false },
-  {
-    key: "items",
-    transform: (val) => ({ itemCount: (val as unknown[]).length }),
-  },
-]);
+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:
 
-// Inner observe — no view binding, for store-internal reactions.
-// Keys are required (no useful default for a callback-only observer).
-store.observe(undefined, ["step"], () => {
-  store.count = 0; // reset count when step changes
+```ts
+export default View.extend({
+  mixins: [State.clean("pageTitle,isLoggedIn")],
+  template,
 });
 ```
 
-`lazy: true` (the default) calls `updater.digest()` to merge data. `lazy: false` calls `updater.set()` first, then `digest()` — useful when the callback supplies a transformed value that should land on the data object before the next render.
+Without cleanup, keys persist on global State causing leaks.
 
-Inner observes are de-duplicated by `key + observeKeys.join("-") + cb.toString()`, so the same inner observe with identical key/callback won't register twice.
+### Store: Zustand-Style State Management
 
-### Multi-instance stores
-
-When a component is reused N times and each instance needs its own state:
+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.
 
 ```ts
-import { defineStore, multi } from "@lark.js/mvc";
+// src/store/count.ts
+import { create, computed } from "@lark.js/mvc";
 
-const useCounterStore = defineStore("counter", (store) => ({
+interface CountStore {
+  count: number;
+  step: number;
+  doubled: number;
+  history: string[];
+  increment: () => void;
+  decrement: () => void;
+  reset: () => void;
+}
+
+const useCountStore = create<CountStore>("count", (set, get) => ({
   count: 0,
+  step: 1,
+  doubled: computed(["count"], () => get().count * 2),
+  history: [] as string[],
   increment() {
-    store.count++;
+    const { count, step } = get();
+    set({
+      count: count + step,
+      history: [...get().history, `+${step} -> ${count + step}`],
+    });
+  },
+  decrement() {
+    const { count, step } = get();
+    set({ count: count - step });
+  },
+  reset() {
+    set({ count: 0, history: [] });
   },
 }));
 
-// multi() returns [useFn, mixinObj].
-const [useMultiCounter, counterMixin] = multi(useCounterStore);
-
-export default defineView({
-  mixins: [counterMixin], // its make() stamps a per-instance flag onto the view
-  template,
-  init() {
-    const store = useMultiCounter(this); // each instance gets its own store clone
-    store.observe(this, ["count"]);
-  },
-});
+export default useCountStore;
 ```
 
-`multi()` intercepts the parent frame's `mountFrame` to propagate a `lark-comp-<storeName>` flag down the Frame tree. When `useFn(view)` is called, it looks up the flag and either returns an existing store clone or creates one via `cloneStore()`.
+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.
 
-### Standalone reactive cells
-
-For one-off reactive values that don't need a full store:
+Reading and writing state:
 
 ```ts
-import { cell, observeCell } from "@lark.js/mvc";
-
-const count = cell({ value: 0 });
-const off = observeCell(count, () => console.log("changed:", count.value));
-count.value = 1; // triggers callback
-off(); // clean up
-```
-
-`cell(data)` creates a Proxy with `belong: "lark-global"` and a unique `linkKeys`. `observeCell(state, cb, immediate?)` registers a tracker (defaults to firing immediately).
+// Read
+const { count, step } = useCountStore.getState();
 
-## Defining Views
+// Write (shallow merge)
+useCountStore.setState({ count: 5 });
+useCountStore.setState((prev) => ({ count: prev.count + 1 }));
 
-### View template
-
-```html
-<!-- src/views/home.html -->
-<div>
-  <h1>{{=title}}</h1>
-  <div>Count: {{=count}}</div>
-  <button @click="navigateTo({path: '/about'})">About</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>
-
-  <!-- Sub-view embedding -->
-  <div v-lark="components/child"></div>
-</div>
+// Call action
+useCountStore.getState().increment();
 ```
 
-### View class
+Binding in a view:
 
 ```ts
-// src/views/home.ts
-import { Router } from "@lark.js/mvc";
-import View from "../view"; // project-level base
-import template from "./home.html";
-import useCountStore from "../store/count";
+import { bindStore } from "@lark.js/mvc";
 
 export default View.extend({
   template,
-
   init() {
-    this.assign();
+    // Bind all non-function state keys to view updater; auto-unsubscribes on destroy
+    bindStore(this, useCountStore);
 
-    const store = useCountStore(this);
-    store.observe(this); // observe every store key (D5 default)
+    // Or use a selector to sync only specific keys
+    bindStore(this, useCountStore, (s) => ({ count: s.count }));
   },
+  "increment<click>"() {
+    useCountStore.getState().increment();
+  },
+});
+```
 
-  // assign() pulls the latest store + State values into this.updater.
-  // Always call snapshot() at the top and return altered() at the end
-  // so the framework knows whether a re-digest is needed.
-  assign() {
-    this.updater.snapshot();
+Custom subscription callback (when data transformation is needed before sync):
 
-    const store = useCountStore();
-    this.updater.set({
-      title: "Home",
-      count: store.count,
-      step: store.step,
-      items: [
-        { id: "a", name: "Alpha" },
-        { id: "b", name: "Beta" },
-      ],
-    });
-
-    return this.updater.altered();
-  },
+```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();
+}
+```
 
-  // render() is wrapped by the framework to manage signature/lifecycle.
-  // The default implementation calls this.updater.digest().
-  render() {
-    this.updater.digest();
-  },
+Destroying a store:
 
-  // Event method naming: `name<eventType>`. See "Event methods" below.
-  "navigateTo<click>"(e: Record<string, unknown>) {
-    const params = e["params"] as Record<string, string> | undefined;
-    if (params?.path) Router.to(params.path);
-  },
-});
+```ts
+useCountStore.destroy(); // Clears all listeners, removes from registry
 ```
 
-### Event methods
+### Comparison
 
-Lark scans the View prototype once per class (in `View.prepare`) and builds three event maps on the prototype (`$evtObjMap`, `$selMap`, `$globalEvtList`). DOM events are delegated to `document.body` using **capture-phase** listeners with reference counting — the first binding installs the listener, the last unbinding removes it.
+| 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 |
 
-| Pattern                    | Meaning                                           |
-| -------------------------- | ------------------------------------------------- |
-| `handler<click>`           | Root event on the view element                    |
-| `$selector<click>`         | Delegated event matching CSS selector `.selector` |
-| `$<click>`                 | Empty selector — frame boundary event only        |
-| `$window<resize>`          | Global event on `window`                          |
-| `$document<keydown>`       | Global event on `document`                        |
-| `handler<click,mousedown>` | Multi-event binding                               |
-| `name<click><ctrl>`        | Modifier filter — only fires when Ctrl is pressed |
+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.
 
-Each event handler receives an event object with these augmented fields:
+## View Definition and Lifecycle
 
-- `e.eventTarget` — the actual DOM element that was clicked.
-- `e.params` — parsed parameters from `@event` attributes (URL query string format).
-- All standard DOM Event properties (`type`, `target`, etc.).
+### Two Definition Approaches
 
-When two mixins define the same event method, they're merged into a single function that calls both in sequence via a `handlerList` array.
+`View.extend({...})` is the low-level primitive approach where all mixins, event methods, and lifecycle hooks are declared in the passed object:
 
-### Resource management
+```ts
+import { View } from "@lark.js/mvc";
 
-`capture` and `release` manage objects whose lifetime tracks the view (timers, services, observers, etc.):
+export default View.extend({
+  template,
+  init() { /* ... */ },
+  assign() { /* ... */ },
+  render() { /* ... */ },
+});
+```
+
+`defineView({...})` is a typed wrapper that threads the literal's own fields into `this` via `ThisType<P & ViewInterface>`:
 
 ```ts
-const timer = setInterval(() => {
-  /* ... */
-}, 1000);
-this.capture(
-  "myTimer",
-  {
-    destroy() {
-      clearInterval(timer);
-    },
+import { defineView } from "@lark.js/mvc";
+
+export default defineView({
+  customField: "x",
+  init() {
+    console.log(this.customField);
   },
-  true,
-);
-// destroyOnRender=true: destroyed on next render call
-// destroyOnRender=false: destroyed only on view destroy
+});
 ```
 
-`release(key, destroy=true)` removes the entry (and calls `.destroy()` unless `destroy=false`).
+Both produce equivalent runtime artifacts; the difference is purely in TypeScript inference.
 
-### Async safety with `wrapAsync`
+### Lifecycle
 
-Async callbacks may resolve after the view has been re-rendered or destroyed. `wrapAsync` captures the current signature so the callback short-circuits if the view has moved on:
+- `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.
 
-```ts
-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); // no-op if view re-rendered or destroyed
-}
-```
+`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.
 
-### Location observation
+### Event Methods
 
-```ts
-// In a view:
-this.observeLocation("page,size", true); // params + observePath
-this.observeLocation(["page", "size"]); // array form
-this.observeLocation({ params: ["page"], path: true }); // object form
-```
+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`.
 
-When the listed params or path change, the framework re-runs the view's render automatically.
+| 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 |
 
-### State observation (for the State pipeline)
+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.
 
-```ts
-this.observeState("count,step"); // comma-separated
-this.observeState(["count", "step"]); // array
-```
+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.
 
-When State.digest() flips one of these keys, the framework re-renders the view.
+### Resource Management
 
-### Sub-view embedding
+`capture` registers "destroyable objects tied to the view lifecycle":
 
-```html
-<div v-lark="components/child-view"></div>
+```ts
+const timer = setInterval(tick, 1000);
+this.capture("myTimer", { destroy() { clearInterval(timer); } }, true);
 ```
 
-At mount time, `Frame.mountZone` runs `querySelectorAll("[v-lark]")` on the view's root, creates a child Frame for each match, and mounts the registered View class. The container's inner content is replaced by the child view's rendered output.
+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.
 
-For dynamic loading (no upfront `registerViewClass`), `mountView` automatically calls `Framework.use()` to load the View class through the configured `require` hook (see Module Federation below).
+### Async Safety
 
-## Defining the Framework Boot
-
-`Framework.boot(config)` config accepts:
+Async callbacks may arrive after a view has re-rendered or been destroyed. `wrapAsync` adds a signature check layer:
 
 ```ts
-interface FrameworkConfig {
-  rootId: string; // required — DOM id for the root frame
-  defaultView?: string; // default view path
-  defaultPath?: string; // path when URL hash is empty (defaults to "/")
-  routes?: Record<string, string | RouteViewConfig>; // path → view path mapping
-  hashbang?: string; // defaults to "#!"
-  unmatchedView?: string; // 404 view path
-  rewrite?: (path, params, routes) => string; // dynamic path rewriting
-  error?: (e: Error) => void; // global error handler (do not re-throw)
-  extensions?: string[]; // extension view paths loaded at startup
-  initModule?: string; // init module path
-  skipViewRendered?: boolean;
-  projectName?: string; // for Module Federation discriminator
-  crossConfigs?: CrossSiteConfig[]; // MF remote configs
-  require?: (names: string[], params?) => Promise<unknown[]>; // async View loader
-  [k: string]: unknown; // custom keys are allowed
+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
 }
 ```
 
-After boot, prefer `Framework.getConfig(key)` for reads and `Framework.setConfig(patch)` for writes. The older `Framework.config(...)` overload still works but is `@deprecated`.
+`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
+Router supports two routing modes, configured via `FrameworkConfig.routeMode`:
 
-### Navigation
+- `"history"` (default): uses `history.pushState` / `popstate`, URLs like `/home?page=2`
+- `"hash"`: uses URL hash fragment, URLs like `#!/home?page=2`
+
+All state parses into a single `Location` object; cache hits skip parsing.
+
+### Basic Usage
 
 ```ts
-Router.to("/list", { page: 2 }); // path + params
-Router.to({ page: 3 }); // params-only — keeps current path
-Router.to("/list", { page: 2 }, true); // replace (no history entry)
-Router.to("/list", { page: 2 }, false, true); // silent (no events)
-```
+import { Router } from "@lark.js/mvc";
 
-### Parsing
+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
+```
 
 ```ts
-const loc = Router.parse(); // current location
-const loc = Router.parse("https://x.com/?a=1#!/path?p=v");
-// loc.path, loc.params, loc.hash, loc.query, loc.view, loc.get("key", "default")
-const diff = Router.diff(); // last LocationDiff or undefined
+const loc = Router.parse();                // current Location
+const loc2 = Router.parse("https://x/?a=1#!/path?p=v");
+const diff = Router.diff();                // most recent LocationDiff
 ```
 
-### Two-phase change events (existing API)
+`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(); // pause subsequent processing
-  else if (mustReject)
-    e.reject(); // revert URL to lastHash
-  else e.resolve(); // commit (auto if neither called)
+  if (hasUnsavedChanges) e.prevent();
+  else if (mustReject) e.reject();
+  else e.resolve();
 });
 Router.on("changed", (diff) => {
-  // diff is a LocationDiff: { params, path?, view?, force, changed }
+  // diff: LocationDiff { params, path?, view?, force, changed }
 });
 ```
 
-### Async route guards (`Router.beforeEach`)
+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; // false → revert URL, throw → also reverts
+    return ok;
   }
-  return true; // or undefined — permits navigation
+  return true;
+});
+// Unregister
+off();
+```
+
+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) }));
+  },
 });
-// later, off() to unsubscribe
 ```
 
-Guards run in registration order. Any guard that returns/resolves to `false`, throws, or rejects aborts the navigation and reverts the URL. Returning `true`, `undefined`, or any non-`false` value permits it.
+Supports both history and hash routing modes.
+
+## Service Request Layer
 
-## Service (API requests)
+`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.
 
-`Service` is an opinionated layer around `fetch` (or any sync function) with LFU caching, in-flight deduplication, serial task queueing, and lifecycle events.
+### Defining Subclasses and Endpoints
 
 ```ts
 import { Service, type Payload } from "@lark.js/mvc";
@@ -636,19 +580,14 @@ const AppService = Service.extend(
     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,
+      body: payload.get("data") ? JSON.stringify(payload.get("data")) : undefined,
     })
       .then((r) => r.json())
-      .then((data) => {
-        payload.set(data);
-        callback();
-      })
+      .then((data) => { payload.set(data); callback(); })
       .catch(() => callback());
   },
   20, // cacheMax
-  5, // cacheBuffer
+  5,  // cacheBuffer
 );
 
 AppService.add([
@@ -658,94 +597,83 @@ AppService.add([
     url: "/api/users/:id",
     cache: 30_000,
     before(payload) {
-      payload.set(
-        "url",
-        payload.get<string>("url").replace(":id", payload.get<string>("id")),
-      );
+      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", // invalidate userList cache when this completes
+    cleanKeys: "userList",
   },
 ]);
 ```
 
-### Per-subclass isolation
-
-`Service.extend()` produces a subclass with its own `_metaList`, `_payloadCache`, `_pendingCacheKeys`, `_syncFn`, `_staticEmitter`, `_cacheMax`, and `_cacheBuffer` via `static override`. This isolation is intentional — endpoints registered on one subclass never leak into another. Refactoring these `static override` declarations away would break the isolation.
-
-### Using a service in a view
+### Using in Views
 
 ```ts
 export default View.extend({
   template,
   init() {
     const service = new AppService();
-    this.capture("userService", service, true); // auto-destroy on render
+    this.capture("userService", service, true);
     this.service = service;
     this.loadData();
   },
   loadData() {
-    this.service.all("userList", (errors, userListPayload) => {
-      if (!errors[0]) {
-        this.updater.set({ users: userListPayload.get("data") }).digest();
-      }
-    });
-  },
-  refreshDetail(id: string) {
-    // save() bypasses cache, always makes a real request.
-    this.service.save({ name: "userDetail", id }, (errors, payload) => {
+    this.service.all("userList", (errors, payload) => {
       if (!errors[0]) {
-        this.updater.set({ detail: payload.get("data") }).digest();
+        this.updater.set({ users: payload.get("data") }).digest();
       }
     });
   },
 });
 ```
 
-### Service method summary
+| 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 |
 
-| Method                      | Behavior                                                                      |
-| --------------------------- | ----------------------------------------------------------------------------- |
-| `service.all(attrs, done)`  | Fetch all endpoints; callback with `(errors, p1, p2, ...)` when ALL complete  |
-| `service.one(attrs, done)`  | Fetch all endpoints; callback PER endpoint: `(error, payload, isLast, index)` |
-| `service.save(attrs, done)` | Like `all` but always skips cache (force refresh)                             |
-| `service.enqueue(task)`     | Queue a task for serial execution                                             |
-| `service.dequeue(...args)`  | Pop and run the next queued task                                              |
-| `service.destroy()`         | Destroy instance; cancel further callbacks                                    |
+### Caching and Deduplication
 
-### Caching and dedup
+`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.
 
-The `Cache` class is an LFU cache with single-pass partial-selection eviction (O(n·k)) — see `cache.ts`. The pending-key map (`pendingCacheKeys`) deduplicates concurrent requests for the same `(endpoint, params)`. All pending callbacks are queued and called when the single in-flight request completes.
+`_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.
 
-`defaultCacheKey` memoizes `JSON.stringify(meta)` per `ServiceMetaEntry` via `WeakMap` — meta entries are immutable after `Service.add()`.
+`cleanKeys: "userList"` means the current endpoint, upon completion, clears the corresponding cache entry — commonly used to invalidate list queries after a write operation.
 
-## Templates
+## Template Syntax
 
-### Operators
+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.
 
-| Operator | Syntax          | Meaning                                                            |
-| -------- | --------------- | ------------------------------------------------------------------ |
-| `=`      | `{{=variable}}` | HTML-escaped output (`&`, `<`, `>`, `"`, `'`, backtick)            |
-| `!`      | `{{!variable}}` | Raw output (no escaping). Use with care for user-generated content |
-| `@`      | `{{@variable}}` | Reference lookup — stores a JS value in refData, emits a token     |
-| `:`      | `{{:variable}}` | Two-way binding marker (renders identically to `=`)                |
+### Expression Operators
 
-### Control flow
+| 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
-{{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}}
+{{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}}
 ```
 
-`forOf` REQUIRES the `as` keyword: `{{forOf list as item}}` is correct; `{{forOf list item}}` is a compile-time error.
+`forOf` requires the `as` keyword. `{{forOf list item}}` is a compile-time error; the correct form is `{{forOf list as item}}`.
 
-### Event binding
+### Event Binding
 
 ```html
 <button @click="handlerName({key: 'value', other: 123})">Go</button>
@@ -753,80 +681,91 @@ localVar = expr}}
 <form @submit.prevent="onSubmit()">...</form>
 ```
 
-The compiler converts JS object literal params (`{a: 1}`) into URL query format (`a=1`) so they can survive transport through DOM attributes. It also injects the current view's `$viewId` and a SPLITTER separator so the EventDelegator can route correctly across nested frames.
+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.
 
-### Sub-view embedding
+### 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>
-<!-- Module Federation -->
 ```
 
-When `v-lark` carries a query string, the params are translated into the child view's `init` arguments. If the value contains a SPLITTER reference, `translateData` resolves it via the parent view's refData before the child mounts.
+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.
 
-### VDOM optimization hints
+### VDOM Optimization Hints
 
-| Attribute | Effect                                                                |
-| --------- | --------------------------------------------------------------------- |
-| `ldk`     | "Diff key" — if old and new have the same `ldk`, skip the entire diff |
-| `lak`     | "Attribute key" — skip attribute diff but still diff children         |
-| `lvk`     | "View key" — assign-optimization marker                               |
+| 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 |
 
-Mark large static subtrees with `ldk` to skip rendering work entirely.
+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.
 
-## Module Federation (micro-frontend)
+## Frame and the View Tree
 
-### Pattern 1 — Direct async loading
+`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.
 
-Configure `FrameworkConfig.require` to resolve unknown view paths through MF:
+### Typed API
 
-```ts
-declare const __webpack_init_sharing__: (name: string) => Promise<void>;
-declare const __webpack_share_scopes__: Record<string, Record<string, unknown>>;
+| 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",
-    },
+    { 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] as
-          | {
-              init: (s: Record<string, unknown>) => Promise<void>;
-              get: (m: string) => Promise<() => unknown>;
-            }
-          | undefined;
-        if (!rc) return undefined;
-        await rc.init(container);
-        const factory = await rc.get(`./${mod}`);
-        const raw = factory();
-        return raw && (raw as Record<string, unknown>).__esModule
-          ? (raw as Record<string, unknown>).default
-          : raw;
-      }),
-    );
+    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;
+    }));
   },
 });
 ```
 
-Then `v-lark="remote-app/views/home"` just works.
+Then write `v-lark="remote-app/views/home"` in templates to trigger async loading and mounting of the remote view.
 
-### Pattern 2 — CrossSite bridge view (with skeleton + prepare)
+### Mode 2: CrossSite Bridge View
 
-For richer scenarios that want a loading skeleton and a `prepare` hook on the remote side:
+For skeleton screens and remote `prepare` hooks, use `CrossSite`:
 
 ```ts
 import { CrossSite, registerViewClass } from "@lark.js/mvc";
@@ -837,30 +776,18 @@ registerViewClass("cross-site", CrossSite);
 <div v-lark="cross-site?view=remote-app/views/home&bizCode=mybiz"></div>
 ```
 
-CrossSite renders a skeleton container `mf_${viewId}` first, then loads the remote project's `prepare` module via `loadRemoteView()`, then mounts the actual view. Race condition is guarded by `$sign`: if the user navigates away during the async load, the stale mount is aborted. When the remote view path matches the previous one and the existing view supports `assign()`, CrossSite updates in place instead of re-mounting.
+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.
 
-`CrossSite.callView(name, ...args)` invokes a method on the embedded remote view via `Frame.invoke()`.
-
-### Module Federation Webpack config
+### Webpack Configuration
 
 Host:
 
 ```js
-import { ModuleFederationPlugin } from "webpack/container";
-
-export default {
-  plugins: [
-    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" },
-      },
-    }),
-  ],
-};
+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" } },
+});
 ```
 
 Remote:
@@ -869,222 +796,182 @@ Remote:
 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" },
-  },
+  exposes: { "./views/home": "./src/views/home", "./prepare": "./src/prepare" },
+  shared: { "@lark.js/mvc": { singleton: true, requiredVersion: "^1.0.0" } },
 });
 ```
 
-`@lark.js/mvc` MUST be shared as `singleton: true` so host and remote use the same View/Frame class instances — `instanceof` checks fail across boundaries otherwise.
-
-### `splitChunks.chunks` must be `"async"` in MF projects
-
-| Value       | Splits initial chunks | Splits async chunks |
-| ----------- | --------------------- | ------------------- |
-| `"initial"` | yes                   | no                  |
-| `"async"`   | no                    | yes                 |
-| `"all"`     | yes                   | yes                 |
-
-If `chunks: "all"` extracts `@lark.js/mvc` into a separate vendor chunk, the MF shared scope initialization fails — `remoteEntry.js` needs `@lark.js/mvc` synchronously available in the initial entry chunk. With `chunks: "async"`, shared singletons stay in the entry chunk and `window.<remote_name>` is set correctly.
-
-### `Frame.root()` vs `new Frame()` for MF
+`@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
+
+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 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).
 
-`Frame.root()` (and the newer `Frame.createRoot()`) is a singleton — always returns the first root, ignoring later `id` arguments. For MF containers that need independent rendering contexts, use `new Frame(containerId)` directly so each mount owns its frame tree.
+## Comparison with Vue 3 / React 19
 
-Use the new APIs (preferred):
+### vs Vue 3
 
-- `Frame.getRoot()` — pure getter, returns `undefined` if not yet created.
-- `Frame.createRoot(id)` — idempotent create (Framework.boot calls this).
-- `new Frame(containerId)` — independent root for MF or for an embeddable widget.
-- `Frame.root(id)` — `@deprecated` alias that delegates to `createRoot`.
+Similarities: templates compile to functions; reactivity via Proxy; derived data with `computed`; microtask batching; component-level granular updates.
 
-### Exposed mount function pattern
+| 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 |
 
-For React/other-host integrations, expose a mount function rather than raw View classes:
+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`).
 
-```ts
-// src/exposed/counter-view.ts
-import {
-  Framework,
-  Frame,
-  registerViewClass,
-  EventDelegator,
-  Router,
-  State,
-} from "@lark.js/mvc";
-import CounterView from "../views/counter";
-import "../index.css"; // MF remote must explicitly import CSS
-
-const MF_COUNTER = "mf/counter";
-registerViewClass(MF_COUNTER, CounterView);
-
-export function mountCounter(container: HTMLElement): () => void {
-  const containerId = container.id || "mf-counter-root";
-  container.id = containerId;
-
-  Framework.setConfig({ rootId: containerId, error: console.error });
-  EventDelegator.setFrameGetter((id: string) => Frame.get(id));
-  Reflect.set(Router, "_booted", true);
-  Reflect.set(State, "_booted", true);
-
-  const frame = new Frame(containerId); // NOT Frame.createRoot
-  frame.mountView(MF_COUNTER);
-
-  return () => {
-    frame.unmountView();
-    Frame.getAll().delete(containerId);
-    const el = document.getElementById(containerId);
-    if (el) Reflect.set(el, "frameBound", 0);
-  };
-}
-```
+### vs React 19
 
-The MF remote MUST explicitly import its CSS (`import "../index.css"`) — Webpack only bundles CSS reachable from the exposed module's import graph.
+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`).
 
-## Three pipelines side-by-side
+| 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 |
 
-```ts
-// Updater (view-local, manual)
-this.updater.set({ count: newCount }).digest();
+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.
 
-// State (simple cross-view)
-State.set({ count: newCount }).digest();
-// to react:
-State.on("changed", (e) => {
-  if (e.keys?.has("count")) this.assign();
-});
-// to clean up on view destroy:
-export default View.extend({ mixins: [State.clean("count")] });
+## Testing and Local Development
 
-// Store (complex cross-view, recommended for non-trivial state)
-const store = useCountStore(this);
-store.observe(this); // default: all keys (D5)
-useCountStore().increment(); // mutate from anywhere → all observers re-render
+```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
 ```
 
-Key distinctions:
-
-|                | State                                       | Store                                                       |
-| -------------- | ------------------------------------------- | ----------------------------------------------------------- |
-| Write API      | `State.set()` + `State.digest()`            | direct: `store.key = value`                                 |
-| Reactivity     | Manual `digest()` notification              | Automatic via Proxy                                         |
-| Subscribe      | `State.on("changed", ...)` + manual cleanup | `store.observe(view, ...)` with auto-cleanup                |
-| Memory         | Auto-deleted via `State.clean()` mixin      | Persists until `store.$destroyFn()`                         |
-| Derived data   | not supported                               | `computed(deps, fn)`                                        |
-| Multi-instance | not supported                               | `multi(useStore)`                                           |
-| Best for       | Counters, toggles, page title, session info | Reactive handlers, derived state, multi-instance components |
-
-## Updater APIs worth knowing
-
-- `updater.get(key?)` — read data; without key returns the whole data object.
-- `updater.set(data, excludes?)` — merge `data` into the view's data, track changed keys.
-- `updater.digest(data?, excludes?, callback?)` — render; optional `data` is set first. Supports re-digest during an active digest via an internal queue (the `null` sentinel marks digest boundaries).
-- `updater.snapshot()` — record the current monotonic `version`; pair with `altered()` to detect changes cheaply (no JSON.stringify).
-- `updater.altered()` — returns `boolean | undefined`. `undefined` if `snapshot` was never called.
-- `updater.translate(value)` — resolve a `SPLITTER + digits` ref token to its original value. Non-ref strings are returned as-is. The protocol is strict: only `SPLITTER` followed by ASCII digits qualifies.
-- `updater.parse(expr)` — **safe** path resolver. Accepts a dotted property path (`a.b.c`) or a numeric literal (`42`, `-1.5`). Anything else returns `undefined`. Does NOT eval arbitrary JS — CSP-safe.
-- `updater.getChangedKeys()` — `ReadonlySet<string>` of keys changed since the last digest.
-
-## Frame APIs worth knowing
-
-- `Frame.get(id)` — look up a Frame by DOM id.
-- `Frame.getAll()` — registry as `Map<string, Frame>`.
-- `Frame.getRoot()` — current root or `undefined`.
-- `Frame.createRoot(id)` — create root (idempotent; ignores `id` after first creation).
-- `Frame.root(id)` — `@deprecated` alias to `createRoot`.
-- `frame.invoke(name, args?)` — call a method on the frame's view. If the view isn't yet rendered, the call is deferred until render.
-- `frame.invokeTyped<V, K>(name, args)` — type-safe variant; carries the view's method signature through TS.
-- `frame.children()` — array of child Frame ids (order is not stable).
-- `frame.parent(level?)` — ancestor frame; defaults to parent (level=1).
-- `frame.mountFrame(id, viewPath, params?)` — explicit child Frame creation.
-- `frame.unmountFrame(id)` / `frame.mountZone(id?)` / `frame.unmountZone(id?)` — bulk operations.
-- `Frame.on("add" | "remove", handler)` — lifecycle events.
-- `frame.on("created" | "alter", handler)` — fires when all children have rendered / when child content changes.
-
-## Framework APIs worth knowing
-
-- `Framework.boot(config)` — start the app.
-- `Framework.getConfig()` / `Framework.getConfig(key)` — read config.
-- `Framework.setConfig(patch)` — merge into config; returns the merged result.
-- `Framework.config(...)` — `@deprecated`; still works.
-- `Framework.isBooted()` — boolean.
-- `Framework.use(names, callback?)` — async View loader. Returns `Promise<unknown[]>` when no callback is passed.
-- `Framework.mark(host, key)` / `Framework.unmark(host)` — async callback validity tracking. Stored in a module-level `WeakMap`, does NOT pollute the host object with magic keys.
-- `Framework.dispatch(target, type, init?)` — fire a custom DOM event.
-- `Framework.task(fn, args?, ctx?)` — schedule a function for chunked execution (`scheduler.postTask` → `requestIdleCallback` → `setTimeout(0)`).
-- `Framework.delay(ms)` — Promise-based setTimeout.
-- `Framework.waitZoneViewsRendered(viewId, timeout?)` — Promise resolving to `Framework.WAIT_OK` (1) or `Framework.WAIT_TIMEOUT_OR_NOT_FOUND` (0).
-- `Framework.applyStyle(idOrPairs, css?)` — inject CSS dynamically; returns a cleanup function.
-- `Framework.guid(prefix?)` / `Framework.toMap(list, key?)` / `Framework.toUrl(...)` / `Framework.parseUrl(url)` / `Framework.mix(target, ...sources)` / `Framework.keys(obj)` / `Framework.inside(a, b)` / `Framework.node(idOrEl)` / `Framework.nodeId(el)` — utility helpers.
-- `Framework.guard(o)` — Safeguard Proxy wrap (no-op outside debug mode).
-- `Framework.Base` / `Framework.View` / `Framework.Frame` / `Framework.Cache` / `Framework.State` / `Framework.Router` — class re-exports.
-
-## Vite vs Webpack at a glance
-
-| Feature             | Vite (`larkMvcPlugin`)                                   | Webpack (`larkMvcLoader`)                                    |
-| ------------------- | -------------------------------------------------------- | ------------------------------------------------------------ |
-| Import path         | `@lark.js/mvc/vite`                                      | `@lark.js/mvc/webpack`                                       |
-| Type                | Vite plugin (`resolveId` + `load` hooks, `enforce: pre`) | Standard Webpack loader                                      |
-| Configuration       | `plugins: [larkMvcPlugin()]`                             | `module.rules` with the loader rule                          |
-| Debug mode          | `larkMvcPlugin({ debug: true })`                         | `use: [{ loader: larkMvcLoader, options: { debug: true } }]` |
-| HTML entry handling | Vite handles `index.html` natively                       | MUST `exclude: /index\.html$/` so HtmlWebpackPlugin owns it  |
-| Dev server          | Vite dev server (fast HMR)                               | webpack-dev-server                                           |
-| Template pipeline   | Same: `extractGlobalVars` → `compileTemplate`            | Same: `extractGlobalVars` → `compileTemplate`                |
-
-Both produce compiled `.html` modules that import their runtime helpers from `@lark.js/mvc/runtime` (a 948-byte module containing `encHtml`, `strSafe`, `encUri`, `encQuote`, `refFn`).
-
-## Common pitfalls
-
-1. **`boot.ts` must live inside `src/`** — the entry HTML references `/src/boot.ts`, not `/boot.ts`.
-2. **`registerViewClass` before `Framework.boot()`** — all view classes (and their sub-components) must be registered before boot, OR you must provide a `FrameworkConfig.require` so unknown paths can be loaded on demand.
-3. **`.html` imports require the bundler integration** — they only work because the Vite plugin or Webpack loader compiles them at build time.
-4. **Use `State.set` + `State.digest`, not direct mutation** — direct mutation bypasses change detection. Debug mode (`window.__lark_Debug = true`) warns synchronously and dedupes the warning per key.
-5. **`observe` requires view binding for auto-cleanup** — `store.observe(this, ...)` tears down when the view destroys. Inner observes (no view) require explicit `keys` and explicit unsubscribe.
-6. **Event method names use `<>`, not `()`** — the pattern is `name<click>`, not `name(click)`.
-7. **`assign()` must call `snapshot()` and return `altered()`** — otherwise the framework can't tell if data actually changed.
-8. **Do not modify `view.signature`** — it's managed internally. Setting it to 0 destroys the view. The wrapped `render()` increments it.
-9. **`v-lark` containers are replaced** — content inside a `v-lark` element gets replaced by the child view's rendered output. Don't put authoring text there.
-10. **Webpack: exclude `index.html`** — `larkMvcLoader` must not process the entry HTML; HtmlWebpackPlugin owns it.
-11. **Webpack: import the loader as a value** — `loader: larkMvcLoader`, not `loader: "larkMvcLoader"`.
-12. **Store reads return cloned data** — `useStore(view).count` returns a deep clone (via `structuredClone`). Mutating it does NOT trigger reactivity. Only writes through `store.key = value` are reactive.
-13. **`forOf` requires `as`** — `{{forOf list item}}` is invalid; use `{{forOf list as item}}`.
-14. **Inner observe deduplication** — `store.observe(undefined, keys, callback)` is deduped on `key + observeKeys.join("-") + cb.toString()`. The same inner observe registers only once.
-15. **`wrapAsync` is signature-based** — the callback runs only if `view.signature` hasn't changed since `wrapAsync` was called.
-16. **Frame object pooling has a cap** — destroyed Frame objects are pooled up to `MAX_FRAME_POOL = 64`. Don't hold references to Frame instances after `unmountFrame()`.
-17. **Updater supports re-entrant digest** — calling `updater.digest()` inside an active digest is supported through `digestingQueue`. The `null` sentinel marks digest boundaries.
-18. **Store creator runs once** — at definition time. State persists across view mounts/unmounts. Call `useStore.$destroyFn()` (set via `Object.defineProperties` on the use-fn) to tear it down.
-19. **State for simple, Store for complex** — use `State.set` + `State.digest` for lightweight shared values. Reach for `defineStore` when you need reactive handlers, derived data via `computed(deps, fn)`, multi-instance isolation via `multi()`, or store-internal reactions via inner `observe`. Always pair State writes with `State.clean(keys)` mixin on consumers so data doesn't leak globally.
-20. **MF view paths use the remote project prefix** — `v-lark="remote-app/views/home"` triggers async loading through `FrameworkConfig.require` if the path isn't yet registered. Ensure `require` is configured AND `ModuleFederationPlugin` shares `@lark.js/mvc` as a singleton.
-21. **`CrossSite` is the export name** — register it as `registerViewClass("cross-site", CrossSite)`.
-22. **CrossSite uses `view=` not `xview=`** — `v-lark="cross-site?view=remote-app/views/home"`.
-23. **`Framework.use()` returns a Promise** — without the optional callback, it resolves to `unknown[]`. Without a configured `require`, it falls back to dynamic `import()`.
-24. **`Updater.parse` is path-only, no eval** — it accepts dotted paths and numeric literals. `updater.parse("1 + 2")` returns `undefined`. CSP-safe by design.
-25. **`LarkInnerKeys` for VDOM short-circuits** — `ldk` skips the entire diff for static elements; `lak` skips attribute diff but still diffs children; `lvk` is an assign-optimization marker.
-26. **MF: `splitChunks.chunks` MUST be `"async"`** — using `"all"` extracts `@lark.js/mvc` into a separate vendor chunk, breaking shared-scope initialization. The error surfaces as `ScriptExternalLoadError: Loading script failed (missing)`.
-27. **MF: `new Frame(containerId)` for independent contexts** — `Frame.createRoot()` (and the deprecated `Frame.root()`) is a singleton that ignores later id arguments. Each MF mount needs its own `new Frame()`.
-28. **MF: remote must explicitly import CSS** — Webpack bundles only CSS reachable from the exposed module's import graph. Without an `import "../index.css"` in the exposed entry, host pages won't receive utility classes used in the templates.
-29. **Sub-component `v-lark` paths must match exactly** — template strings embed the paths at build time; renaming a `registerViewClass` path without updating the template breaks the load.
-30. **Dynamic `import()` shape is unknown** — for chunk splitting, use a small `extractDefault()` helper to unwrap the ESM default, then cast with `as typeof View` (NOT `as any`).
-
-## Migration notes (recent API changes)
-
-- `ChangeEvent.keys` is now `ReadonlySet<string>` (was `Record<string, 1>`). Use `keys.has("foo")` instead of `keys.foo`. Affects `State.on("changed")` handlers and `view.observeState` callbacks.
-- `StateInterface.diff()` returns `ReadonlySet<string>`.
-- `Framework.toUrl(path, params, keepEmpty?)` — `keepEmpty` is now `Set<string>` (was `Record<string, number>`).
-- `Updater.set/digest`, `State.set/digest`, and `setData` take `excludes?: ReadonlySet<string>` (was `Set<string>`).
-- `Frame.root(id)` is `@deprecated`. Use `Frame.getRoot()` for reads, `Frame.createRoot(id)` for the explicit singleton creation, or `new Frame(id)` for independent mounts.
-- `Framework.config(...)` is `@deprecated`. Use `Framework.getConfig(key?)` and `Framework.setConfig(patch)`.
-- `Updater.parse` no longer evals — only safe path/literal resolution. Migrate to a small helper function if you needed expression eval.
-- `mark.ts` no longer writes magic keys onto host objects — it uses a module-level `WeakMap`. Works on frozen objects.
-- `Cache.del` now splices immediately (was leaving tombstones until the next eviction).
-
-## References
+`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/`.
 
-For deeper detail than this guide:
+## License
 
-- `references/api-reference.md` — Complete API signatures for every Lark module.
-- `references/template-syntax.md` — Full template language reference, including compilation pipeline, operators, control flow, encoders, and debug mode.
+ISC. See `LICENSE` in the repository root.