@lark.js/mvc 0.0.4 → 0.0.5

package/README.md

@@ -1,97 +1,133 @@
 ---
 name: lark-mvc
 description: >
-  Lark MVC Framework (@lark.js/mvc) skill for building TypeScript frontend applications.
-  Use this skill whenever the user is working with the Lark framework, including:
-  creating Views, defining Stores, configuring Routes, writing templates, using Updater,
-  integrating with Vite or Webpack, or any question about Lark's API, architecture,
-  or conventions. Also trigger when the user mentions hash-based routing, Proxy-based
-  reactive state, VDOM diff rendering, event delegation, or the v-lark attribute pattern,
-  even if they do not explicitly name "Lark".
+  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 MVC Framework
 
-Lark is a TypeScript MVC framework for building single-page applications with hash-based routing, Proxy-based reactive state management, and real DOM diff rendering.
+`@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.
 
-## Architecture Overview
+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.
 
-Lark follows a strict MVC separation:
+## When to reach for this skill
 
-- **Model**: `defineStore` for reactive state (recommended), `cell`/`observeCell` for standalone reactive cells, `State` for global singleton data (default when no store is specified), `Service` for API request management
-- **View**: `View.extend()` creates view subclasses with template rendering, event delegation, and lifecycle hooks
-- **Controller**: `Router` for hash-based navigation, `Updater` for per-view data binding and VDOM diff, `Frame` for view lifecycle management
+Any task that names — or clearly implies — Lark:
 
-Data flows through three pipelines (use Store when possible, State is the default when no store is specified):
+- 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.
 
-1. **Updater Pipeline** (view-local): `updater.set(data)` -> `updater.digest()` -> template function -> HTML string -> VDOM diff -> DOM patch -> `endUpdate()`
-2. **State Pipeline** (default cross-view): `State.set(data)` -> `State.digest()` -> `changed` event -> views read `State.get()` in `assign()` -> `updater.digest()` -> VDOM diff -> DOM patch. State uses key reference counting: when no view observes a key, the data is automatically deleted on view destroy via `State.clean()`
-3. **Store Pipeline** (cross-view, recommended): `store.key = value` -> Proxy set trap -> `trigger()` -> `GlobalDeps` lookup -> Queue microtask batch -> `store.observe` callback -> `updater.digest()` / `updater.set()` -> VDOM diff -> DOM patch
+## Architecture
 
-### Boot Sequence (Critical Order)
+Lark separates code along three orthogonal axes:
 
-`Framework.boot()` executes in a specific order that must not be changed:
+- **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).
 
-1. Merge config -> 2. Set Router config -> 3. Set EventDelegator frame getter -> 4. Bind Router/State events -> 5. **Create rootFrame** -> 6. **Router.\_bind()** -> 7. Mount default view
+### The three data pipelines
 
-The rootFrame is created BEFORE `Router._bind()` so that the root element has a proper ID. If the order were reversed, rootId would default to `"root"` and views could render into `document.body` unexpectedly.
+Lark exposes three ways to flow data to a view. Pick the simplest one that solves the task.
 
-If a view was already mounted by the router (e.g. after a page reload with `#!/counter`), the default view is NOT mounted to avoid URL/display mismatch (`if (defaultView && !rootFrame.view)`).
+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.
 
-### Window Globals
+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.
 
-After boot, the framework sets these globals for debugging and extension:
+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.
 
-| Global                    | Value            | Purpose                           |
-| ------------------------- | ---------------- | --------------------------------- |
-| `window.__lark_Framework` | Framework object | Direct framework access           |
-| `window.__lark_State`     | State object     | Direct state access               |
-| `window.__lark_Router`    | Router object    | Direct router access              |
-| `window.__lark_Frame`     | Frame class      | Direct Frame class access         |
-| `window.__lark_View`      | View class       | Direct View class access          |
-| `window.__lark_Debug`     | boolean          | Enable safeguard Proxy debug mode |
+### Boot sequence (order matters)
 
-Setting `window.__lark_Debug = true` before boot enables:
+`Framework.boot(config)` runs these steps in this exact order:
 
-- Safeguard Proxy wrapping on State/Updater data reads (warns on cross-page reads, delays direct mutation warnings by 500ms)
-- Safeguard Proxy on Router `diff()` results and Location params
+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`).
 
-## Project Structure
+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 HTML with <script type="module" src="/src/boot.ts">
-  vite.config.ts              # Vite config with larkMvcPlugin()
-  webpack.config.mjs          # Webpack config with larkMvcLoader (alternative bundler)
-  src/
-    boot.ts                   # Bootstrap: registerViewClass + Framework.boot(config)
-    view.ts                   # Project-level View base class (View.extend)
-    styles.css                # Global styles
-    store/
-      count.ts                # defineStore declarations
-    views/
-      home.ts                 # View.extend({ template, init, render, event methods })
-      home.html               # Template file (compiled by larkMvcPlugin or larkMvcLoader)
-      about.ts
-      about.html
-    components/
-      counter-store.ts        # Sub-component views
-      counter-store.html
-```
-
-**Important**: `boot.ts` must be placed inside `src/` (not project root). The `index.html` entry references it as `/src/boot.ts`.
-
-## Step-by-Step Guide
-
-### 1. Install and Configure
+├─ 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
 
 ```bash
 pnpm add @lark.js/mvc
 ```
 
-### 2. Configure Vite Integration
+### 2. Configure your bundler
 
-```typescript
+Vite (recommended):
+
+```ts
 // vite.config.ts
 import { defineConfig } from "vite";
 import { resolve } from "path";
@@ -99,122 +135,38 @@ import { larkMvcPlugin } from "@lark.js/mvc/vite";
 
 export default defineConfig({
   plugins: [larkMvcPlugin()],
-  resolve: {
-    alias: {
-      "@": resolve(__dirname, "./src"),
-    },
-  },
+  resolve: { alias: { "@": resolve(__dirname, "./src") } },
 });
 ```
 
-The `larkMvcPlugin` automatically compiles `.html` template imports into JS function modules. Zero configuration required -- just add the plugin and import `.html` files in your views.
-
-How it works internally:
-
-1. **resolveId hook**: Intercepts `.html` import source strings. When a module imports a `.html` file, the plugin resolves the full path and appends the `?lark-template` suffix (internal constant `LARK_TEMPLATE_SUFFIX`). This prevents Vite from treating the file as a static asset.
-2. **load hook**: When Vite requests a module whose ID ends with `?lark-template`, the plugin reads the raw HTML file from disk, auto-extracts global variables via `extractGlobalVars()` AST analysis, and compiles the template through `compileTemplate()`. The compiled output is an ES module exporting a function with signature `(data, selfId, refData) => string`.
-3. **enforce: "pre"**: The plugin is registered as a pre-phase plugin to ensure it runs before other Vite plugins that might also handle `.html` files.
-
-For debug mode with line tracking and detailed error messages:
-
-```typescript
-plugins: [larkMvcPlugin({ debug: true })];
-```
+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`.
 
-### 3. Configure Webpack Integration
+For Webpack, mirror the same idea with the loader:
 
-```javascript
+```js
 // webpack.config.mjs
-import path from "path";
-import { fileURLToPath } from "url";
-import HtmlWebpackPlugin from "html-webpack-plugin";
 import { larkMvcLoader } from "@lark.js/mvc/webpack";
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
 export default {
-  entry: "./boot.ts",
-  output: {
-    path: path.resolve(__dirname, "dist"),
-    filename: "js/[name].[contenthash:8].js",
-    clean: true,
-  },
-  resolve: {
-    extensions: [".ts", ".js"],
-    alias: {
-      "@": path.resolve(__dirname, "src"),
-    },
-  },
+  // ...
   module: {
     rules: [
-      {
-        test: /\.ts$/,
-        use: "ts-loader",
-        exclude: /node_modules/,
-      },
-      {
-        test: /\.css$/,
-        use: ["style-loader", "css-loader", "postcss-loader"],
-      },
-      // Lark template processing - larkMvcLoader compiles .html to JS functions
+      { test: /\.ts$/, use: "ts-loader", exclude: /node_modules/ },
       {
         test: /\.html$/,
         use: [{ loader: larkMvcLoader }],
-        exclude: /index\.html$/, // Exclude the entry HTML page
+        exclude: /index\.html$/, // HtmlWebpackPlugin handles the entry HTML
       },
     ],
   },
-  plugins: [
-    new HtmlWebpackPlugin({
-      template: "./index.html",
-      inject: "body",
-      minify: false,
-    }),
-  ],
-  devServer: {
-    port: 3001,
-    open: true,
-    hot: true,
-  },
-  devtool: "source-map",
 };
 ```
 
-The `larkMvcLoader` is a standard Webpack loader that compiles `.html` template files into JS function modules at build time. It works by:
-
-1. Receiving the raw HTML source string as input from Webpack.
-2. Auto-extracting global variables via `extractGlobalVars()` AST analysis (the same function used by the Vite plugin).
-3. Compiling the template through `compileTemplate()` to produce an ES module string.
-4. Returning the compiled result to Webpack via `this.callback()`.
-
-Key configuration points:
-
-- Import `larkMvcLoader` from `@lark.js/mvc/webpack` (not from a file path).
-- Use the loader object directly as `loader: larkMvcLoader` (it is a function, not a string name).
-- Exclude `index.html` from the loader rule -- the entry HTML page should be processed by HtmlWebpackPlugin, not by larkMvcLoader.
-- Use `HtmlWebpackPlugin` to inject scripts into the entry HTML page.
+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.
 
-For debug mode, pass loader options:
-
-```javascript
-{
-  test: /\.html$/,
-  use: [
-    {
-      loader: larkMvcLoader,
-      options: { debug: true },
-    },
-  ],
-  exclude: /index\.html$/,
-},
-```
-
-The `debug` option enables line tracking and detailed compile-time/runtime error messages with source mapping.
-
-### 4. Create Entry HTML
+### 3. Entry HTML
 
 ```html
-<!-- index.html -->
 <!doctype html>
 <html lang="en">
   <head>
@@ -229,18 +181,17 @@ The `debug` option enables line tracking and detailed compile-time/runtime error
 </html>
 ```
 
-The `<div id="app">` corresponds to `rootId: "app"` in the boot config.
-
-For Webpack, the entry HTML uses HtmlWebpackPlugin instead of a `<script>` tag. HtmlWebpackPlugin automatically injects the bundled script.
+The `<div id="app">` matches `rootId: "app"` in the boot config.
 
-### 5. Create a Project Base View
+### 4. A project-level base View
 
-```typescript
+```ts
 // src/view.ts
-import { View, Router } from "@lark.js/mvc";
+import { defineView, Router } from "@lark.js/mvc";
 
-export default View.extend({
+export default defineView({
   make() {
+    // Called once per instance via the merged ctors[] pipeline.
     this.updater.set({ appName: "My App" });
     this.on("destroy", () => {
       console.log(`View destroyed: ${this.id}`);
@@ -252,100 +203,142 @@ export default View.extend({
 });
 ```
 
-**How View.extend() works internally**: It creates an ES6 class that extends the parent View. The `make` function is collected into a `ctors` array (along with mixin `make` functions). In the constructor, extend props (like `template`) are applied as **instance properties** after `super()`, because ES6 class field declarations (e.g., `template;` in View) would shadow prototype properties. **CRITICAL**: `render` is explicitly skipped as an instance property — it is wrapped on the prototype by `View.wrapMethod()` to manage signature checking and resource cleanup. Setting `render` on the instance would bypass signature checking, the `"render"` event, and `destroyAllResources()`.
+`defineView` is a 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({...})`.
+
+### 5. Boot
+
+```ts
+// src/boot.ts
+import { Framework, registerViewClass, View } from "@lark.js/mvc";
+import type { FrameworkConfig } from "@lark.js/mvc";
+import HomeView from "./views/home";
+import AboutView from "./views/about";
+import NotFoundView from "./views/404";
+
+registerViewClass("home", HomeView as typeof View);
+registerViewClass("about", AboutView as typeof View);
+registerViewClass("404", NotFoundView as typeof View);
+
+const config: FrameworkConfig = {
+  rootId: "app",
+  defaultPath: "/home",
+  defaultView: "home",
+  routes: {
+    "/home": "home",
+    "/about": "about",
+  },
+  unmatchedView: "404",
+  error(e: Error) {
+    console.error("Lark error:", e);
+  },
+};
+
+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`).
+
+## Defining Stores
 
-### 6. Define Stores
+### Basic store
 
-```typescript
+```ts
 // src/store/count.ts
-import { defineStore, cell, observeCell, multi } from "@lark.js/mvc";
+import { defineStore } from "@lark.js/mvc";
 
-export interface CountStore {
+interface CountStore {
   count: number;
   step: number;
+  doubled: number; // computed
   history: string[];
   increment: () => void;
   decrement: () => void;
   reset: () => void;
-  setStep: (val: number) => void;
-  clearHistory: () => void;
-  registerObservers: () => void;
 }
 
 const useCountStore = defineStore<CountStore>(
   "count",
-  (store, { lazySet, shallowSet }) => {
-    return {
-      count: 0,
-      step: 1,
-      history: [] as string[],
-      increment() {
-        store.count = store.count + store.step;
-        store.history = [...store.history, `+${store.step} -> ${store.count}`];
-      },
-      decrement() {
-        store.count = store.count - store.step;
-        store.history = [...store.history, `-${store.step} -> ${store.count}`];
-      },
-      reset() {
-        store.count = 0;
-        store.history = [...store.history, "Reset -> 0"];
-      },
-      setStep(val: number) {
-        store.step = val;
-      },
-      clearHistory() {
-        store.history = [];
-      },
-      registerObservers() {
-        // Inner observe (no view binding) for store-internal reactions
-        store.observe(undefined, ["step"], () => {
-          store.count = 0; // Reset count when step changes
-        });
-      },
-    };
-  },
+  (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;
 ```
 
-**Creator function signature**: `(store, apis) => initialState`
+### How the creator runs
 
-- `store` — InnerStore proxy for reading/writing reactive state. Reads return the raw reactive Proxy; writes through `store.key = value` trigger dependency tracking
-- `apis` — `{ lazySet, shallowSet }` utility functions:
-  - `lazySet(target, data)` — Batch-set properties without triggering observers (used during `createState` initialization)
-  - `shallowSet(target, key, data)` — Create a shallow reactive sub-state where only top-level property changes trigger observers
+The creator runs once at definition time. Lark walks the return value:
 
-### Standalone Reactive Cells
+- 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.
 
-For simple reactive data that doesn't need the full store pattern, use `cell` and `observeCell`:
+### How `useStore(view)` works
 
-```typescript
-import { cell, observeCell } from "@lark.js/mvc";
+- `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.
+
+### Subscribing a view
+
+`store.observe(view, keys?, defaultCallback?)` subscribes the view to store changes. Variations:
 
-// Create a standalone reactive cell
-const count = cell(0);
+```ts
+// Default: observe every state key in the store (including computeds).
+// Avoids the "two lists to keep in sync" pain point.
+store.observe(this);
 
-// Observe changes
-const unobserve = observeCell(count, () => {
-  console.log("count changed:", count.count);
+// Explicit: only the listed keys trigger updates.
+store.observe(this, ["count", "step"]);
+
+// With a custom callback (override the default updater.digest behavior).
+store.observe(this, ["count"], (changedMap) => {
+  console.log("count changed", changedMap);
 });
 
-// Mutate (triggers observer)
-count.count = 1;
+// Fine-grained ObservePayload entries.
+store.observe(this, [
+  { key: "count", alias: "currentCount", lazy: false },
+  {
+    key: "items",
+    transform: (val) => ({ itemCount: (val as unknown[]).length }),
+  },
+]);
 
-// Clean up
-unobserve();
+// 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
+});
 ```
 
-`cell(data)` creates a Proxy-based reactive state with `belong: "lark-global"` and a unique `linkKeys`. `observeCell(state, cb, immediate?)` tracks changes and calls `cb` when any property changes. By default `immediate = true` (fires callback immediately).
+`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.
 
-### Multi-Instance Stores
+Inner observes are de-duplicated by `key + observeKeys.join("-") + cb.toString()`, so the same inner observe with identical key/callback won't register twice.
 
-When a component is used multiple times on the same page and each instance needs independent state, use `multi`:
+### Multi-instance stores
 
-```typescript
+When a component is reused N times and each instance needs its own state:
+
+```ts
 import { defineStore, multi } from "@lark.js/mvc";
 
 const useCounterStore = defineStore("counter", (store) => ({
@@ -355,28 +348,70 @@ const useCounterStore = defineStore("counter", (store) => ({
   },
 }));
 
-// multi() returns [useFn, mixinObj]
+// multi() returns [useFn, mixinObj].
 const [useMultiCounter, counterMixin] = multi(useCounterStore);
 
-// In the view:
-export default View.extend({
-  mixins: [counterMixin], // make() generates per-instance flag
+export default defineView({
+  mixins: [counterMixin], // its make() stamps a per-instance flag onto the view
   template,
   init() {
-    const store = useMultiCounter(this); // Each view instance gets its own store clone
+    const store = useMultiCounter(this); // each instance gets its own store clone
     store.observe(this, ["count"]);
   },
 });
 ```
 
-`multi()` works by intercepting `mountFrame` calls to propagate a per-instance flag (`lark-comp-{storeName}`) down the Frame tree. When `useFn(view)` is called, it checks the flag and either returns an existing store clone or creates one via `cloneStore()`.
+`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()`.
+
+### Standalone reactive cells
+
+For one-off reactive values that don't need a full store:
+
+```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).
+
+## Defining Views
+
+### 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>
+```
 
-### 7. Create a View with Template
+### View class
 
-```typescript
+```ts
 // src/views/home.ts
 import { Router } from "@lark.js/mvc";
-import View from "../view";
+import View from "../view"; // project-level base
 import template from "./home.html";
 import useCountStore from "../store/count";
 
@@ -386,11 +421,13 @@ export default View.extend({
   init() {
     this.assign();
 
-    // Observe count store -- changes trigger automatic view re-render
     const store = useCountStore(this);
-    store.observe(this, ["count", "step"]);
+    store.observe(this); // observe every store key (D5 default)
   },
 
+  // 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();
 
@@ -399,315 +436,655 @@ export default View.extend({
       title: "Home",
       count: store.count,
       step: store.step,
+      items: [
+        { id: "a", name: "Alpha" },
+        { id: "b", name: "Beta" },
+      ],
     });
 
     return this.updater.altered();
   },
 
+  // render() is wrapped by the framework to manage signature/lifecycle.
+  // The default implementation calls this.updater.digest().
   render() {
     this.updater.digest();
   },
 
+  // Event method naming: `name<eventType>`. See "Event methods" below.
   "navigateTo<click>"(e: Record<string, unknown>) {
     const params = e["params"] as Record<string, string> | undefined;
-    const path = params?.path;
-    if (path) Router.to(path);
+    if (params?.path) Router.to(params.path);
   },
 });
 ```
 
-### 8. Write Templates
+### Event methods
 
-```html
-<!-- src/views/home.html -->
-<div>
-  <h1>{{=title}}</h1>
-  <div>Count: {{=count}}</div>
-  <button @click="navigateTo({path: '/about'})">About</button>
+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.
 
-  {{if count > 0}}
-  <p>Positive</p>
-  {{else}}
-  <p>Zero or negative</p>
-  {{/if}}
+| 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 |
 
-  <ul>
-    {{forOf items as item idx}}
-    <li>{{=idx}}: {{=item}}</li>
-    {{/forOf}}
-  </ul>
+Each event handler receives an event object with these augmented fields:
 
-  <!-- Sub-view embedding -->
-  <div v-lark="components/child"></div>
-</div>
-```
+- `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.).
 
-### 9. Bootstrap the Application
+When two mixins define the same event method, they're merged into a single function that calls both in sequence via a `handlerList` array.
 
-```typescript
-// src/boot.ts
-import { Framework, Router, View, registerViewClass } from "@lark.js/mvc";
-import type { FrameworkConfig } from "@lark.js/mvc";
-import HomeView from "./views/home";
-import AboutView from "./views/about";
-import CounterView from "./views/counter";
-import NotFoundView from "./views/404";
-import CounterStoreComponent from "./components/counter-store";
-import CounterUpdaterComponent from "./components/counter-updater";
+### Resource management
 
-// Register View classes to Frame
-registerViewClass("home", HomeView as typeof View);
-registerViewClass("about", AboutView as typeof View);
-registerViewClass("counter", CounterView as typeof View);
-registerViewClass("404", NotFoundView as typeof View);
-registerViewClass(
-  "components/counter-store",
-  CounterStoreComponent as typeof View,
-);
-registerViewClass(
-  "components/counter-updater",
-  CounterUpdaterComponent as typeof View,
-);
+`capture` and `release` manage objects whose lifetime tracks the view (timers, services, observers, etc.):
 
-const config: FrameworkConfig = {
-  rootId: "app",
-  defaultPath: "/home",
-  defaultView: "home",
-  routes: {
-    "/home": "home",
-    "/about": "about",
-    "/counter": "counter",
-  },
-  unmatchedView: "404",
-  error(e: Error) {
-    console.error("Lark error:", e);
+```ts
+const timer = setInterval(() => {
+  /* ... */
+}, 1000);
+this.capture(
+  "myTimer",
+  {
+    destroy() {
+      clearInterval(timer);
+    },
   },
-};
-
-Framework.boot(config);
+  true,
+);
+// destroyOnRender=true: destroyed on next render call
+// destroyOnRender=false: destroyed only on view destroy
 ```
 
-## Key Patterns
+`release(key, destroy=true)` removes the entry (and calls `.destroy()` unless `destroy=false`).
 
-### Event Method Naming
+### Async safety with `wrapAsync`
 
-Event handlers use the `name<eventType>` pattern. The framework scans the View prototype at class preparation time (in `View.prepare()`) and builds three event maps on the prototype: `$evtObjMap`, `$selMap`, `$globalEvtList`.
-
-| Pattern                    | Meaning                                           |
-| -------------------------- | ------------------------------------------------- |
-| `handler<click>`           | Root event on the view element                    |
-| `$selector<click>`         | Delegated event matching CSS selector `.selector` |
-| `$window<resize>`          | Global event on `window`                          |
-| `$document<keydown>`       | Global event on `document`                        |
-| `handler<click,mousedown>` | Multi-event binding                               |
+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:
 
-All DOM events are delegated to `document.body` using **capture-phase** listeners (`addEventListener(type, handler, true)`). The EventDelegator uses reference counting: the first binding adds the listener, the last unbinding removes it. On event dispatch, the processor walks up the DOM from the target to `document.body`, checking `@<eventType>` attributes and selector matches at each level.
+```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
+}
+```
 
-The event object passed to handlers contains:
+### Location observation
 
-- `e.eventTarget` -- the actual DOM element that was clicked
-- `e.params` -- parsed parameters from `@event` attributes (URL query string format)
-- Standard DOM Event properties (`type`, `target`, etc.)
+```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
+```
 
-When two mixins define the same event method, they are merged into a single function that calls both in sequence via a `handlerList` array.
+When the listed params or path change, the framework re-runs the view's render automatically.
 
-### Store Observe Variations
+### State observation (for the State pipeline)
 
-```typescript
-// Simple: auto-digest on key change
-store.observe(this, ["count", "step"]);
+```ts
+this.observeState("count,step"); // comma-separated
+this.observeState(["count", "step"]); // array
+```
 
-// With custom callback
-store.observe(this, ["count"], (changedMap) => {
-  console.log("count changed", changedMap);
-});
+When State.digest() flips one of these keys, the framework re-renders the view.
 
-// With ObservePayload for fine-grained control
-store.observe(this, [
-  { key: "count", alias: "currentCount", lazy: false },
-  { key: "items", transform: (val) => ({ itemCount: val.length }) },
-]);
+### Sub-view embedding
 
-// Inner observe (no view binding, for store-internal reactions)
-store.observe(undefined, ["step"], () => {
-  store.count = 0; // Reset count when step changes
-});
+```html
+<div v-lark="components/child-view"></div>
+```
 
-// Lazy observe (default: true) -- triggers updater.digest() on change
-// Non-lazy observe (lazy: false) -- triggers updater.set() then digest()
-// This means lazy: true merges data via digest(), lazy: false sets data first
+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.
+
+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).
+
+## Defining the Framework Boot
+
+`Framework.boot(config)` config accepts:
+
+```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
+}
 ```
 
-### Store Read/Write Behavior
+After boot, prefer `Framework.getConfig(key)` for reads and `Framework.setConfig(patch)` for writes. The older `Framework.config(...)` overload still works but is `@deprecated`.
 
-The `useStore()` function returns a Proxy that separates state reads from handler access:
+## Router
 
-- **Reading state keys** (e.g., `store.count`) — returns a deep-cloned copy of the value (frozen for React adapter). This prevents external mutation of reactive state
-- **Writing state keys** (e.g., `store.count = 5`) — sets the value on the internal reactive state, triggering dependency tracking
-- **Accessing handlers** (e.g., `store.increment()`) — calls the function defined in the creator
-- **Inside the creator**, `store.count` reads the raw reactive Proxy (no cloning), enabling direct mutation and reactivity
+### Navigation
 
-The store uses a microtask-based `Queue` scheduler (Promise.resolve().then()) for batching observer callbacks. Multiple state changes in the same synchronous block are batched and processed in a single microtask.
+```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)
+```
 
-### Router Two-Phase Change
+### Parsing
 
-Route changes go through two phases:
+```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
+```
 
-1. **`change` event** -- listeners can call `prevent()` or `reject()` to cancel navigation
-2. **`changed` event** -- URL has been updated, views are re-rendered
+### Two-phase change events (existing API)
 
-```typescript
+```ts
 Router.on("change", (e) => {
-  if (hasUnsavedChanges) {
-    e.prevent(); // Cancel navigation
-  }
+  if (hasUnsavedChanges)
+    e.prevent(); // pause subsequent processing
+  else if (mustReject)
+    e.reject(); // revert URL to lastHash
+  else e.resolve(); // commit (auto if neither called)
+});
+Router.on("changed", (diff) => {
+  // diff is a LocationDiff: { params, path?, view?, force, changed }
 });
 ```
 
-### Resource Management
+### Async route guards (`Router.beforeEach`)
 
-Use `capture/release` for automatic cleanup:
+```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 true; // or undefined — permits navigation
+});
+// later, off() to unsubscribe
+```
 
-```typescript
-const timer = setInterval(() => {
-  /* ... */
-}, 1000);
-this.capture(
-  "myTimer",
+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.
+
+## Service (API requests)
+
+`Service` is an opinionated layer around `fetch` (or any sync function) with LFU caching, in-flight deduplication, serial task queueing, and lifecycle events.
+
+```ts
+import { Service, type Payload } from "@lark.js/mvc";
+
+const AppService = Service.extend(
+  (payload, callback) => {
+    fetch(payload.get<string>("url"), {
+      method: payload.get<string>("method") || "GET",
+      headers: { "Content-Type": "application/json" },
+      body: payload.get("data")
+        ? JSON.stringify(payload.get("data"))
+        : undefined,
+    })
+      .then((r) => r.json())
+      .then((data) => {
+        payload.set(data);
+        callback();
+      })
+      .catch(() => callback());
+  },
+  20, // cacheMax
+  5, // cacheBuffer
+);
+
+AppService.add([
+  { name: "userList", url: "/api/users", cache: 60_000 },
   {
-    destroy() {
-      clearInterval(timer);
+    name: "userDetail",
+    url: "/api/users/:id",
+    cache: 30_000,
+    before(payload) {
+      payload.set(
+        "url",
+        payload.get<string>("url").replace(":id", payload.get<string>("id")),
+      );
+    },
+    after(payload) {
+      const data = payload.get("data");
+      payload.set({ formatted: formatUser(data) });
     },
+    cleanKeys: "userList", // invalidate userList cache when this completes
   },
-  true,
-);
-// destroyOnRender=true: destroyed on next render call
-// destroyOnRender=false: destroyed only on view destroy
+]);
 ```
 
-### Async Safety with wrapAsync
+### Per-subclass isolation
 
-```typescript
-async loadData() {
-  const safeCallback = this.wrapAsync((data) => {
-    this.updater.set({ items: data }).digest();
-  });
-  const data = await fetch("/api/items").then(r => r.json());
-  safeCallback(data); // Only executes if view has not been re-rendered/destroyed
-}
+`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
+
+```ts
+export default View.extend({
+  template,
+  init() {
+    const service = new AppService();
+    this.capture("userService", service, true); // auto-destroy on render
+    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) => {
+      if (!errors[0]) {
+        this.updater.set({ detail: payload.get("data") }).digest();
+      }
+    });
+  },
+});
 ```
 
-### Sub-View Embedding
+### Service method summary
+
+| 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                                    |
 
-Use the `v-lark` attribute to embed child views:
+### Caching and dedup
+
+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.
+
+`defaultCacheKey` memoizes `JSON.stringify(meta)` per `ServiceMetaEntry` via `WeakMap` — meta entries are immutable after `Service.add()`.
+
+## Templates
+
+### Operators
+
+| 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 `=`)                |
+
+### Control flow
 
 ```html
-<div v-lark="components/child-view"></div>
+{{if condition}}...{{else if other}}...{{else}}...{{/if}} {{forOf list as item}}
+... {{/forOf}} {{forOf list as item idx}} {{=idx}}: {{=item.name}} {{/forOf}}
+{{forOf list as {name, age} idx last first}} ... {{/forOf}} {{forIn object as
+value key}} ... {{/forIn}} {{for (let i = 0; i < n; i++)}} ... {{/for}} {{set
+localVar = expr}}
 ```
 
-The framework automatically creates a child Frame, mounts the registered View class, and manages its lifecycle. The `v-lark` attribute value must match a path registered via `registerViewClass`.
+`forOf` REQUIRES the `as` keyword: `{{forOf list as item}}` is correct; `{{forOf list item}}` is a compile-time error.
 
-### Updater vs State vs Store Data Flow
+### Event binding
 
-Three patterns for managing view data. When no store is specified, State is the default cross-view state management:
+```html
+<button @click="handlerName({key: 'value', other: 123})">Go</button>
+<input @input="onInput()" />
+<form @submit.prevent="onSubmit()">...</form>
+```
 
-**Updater pattern** (view-local, manual):
+The compiler converts JS object literal 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.
 
-```typescript
-this.updater.set({ count: newCount }).digest();
+### Sub-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 -->
 ```
 
-**State pattern** (default cross-view, key-ref counting):
+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.
 
-```typescript
-// Write: set data and digest to notify
-State.set({ count: newCount }).digest();
+### VDOM optimization hints
 
-// Read: in view's assign(), pull from State
-assign() {
-  this.updater.snapshot();
-  this.updater.set({ count: State.get("count") });
-  return this.updater.altered();
-}
+| Attribute | 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                               |
 
-// Observe: listen to State "changed" event to trigger re-render
-State.on("changed", (e) => {
-  if (e.keys.count) this.assign(); // Re-assign if count changed
+Mark large static subtrees with `ldk` to skip rendering work entirely.
+
+## Module Federation (micro-frontend)
+
+### Pattern 1 — Direct async loading
+
+Configure `FrameworkConfig.require` to resolve unknown view paths through MF:
+
+```ts
+declare const __webpack_init_sharing__: (name: string) => Promise<void>;
+declare const __webpack_share_scopes__: Record<string, Record<string, unknown>>;
+
+Framework.boot({
+  rootId: "app",
+  projectName: "host-app",
+  crossConfigs: [
+    {
+      projectName: "remote-app",
+      source: "remote_app@//cdn.example.com/remote-app/remoteEntry.js",
+    },
+  ],
+  require: async (names: string[]) => {
+    await __webpack_init_sharing__("default");
+    const container = __webpack_share_scopes__["default"];
+    return Promise.all(
+      names.map(async (name) => {
+        const slash = name.indexOf("/");
+        const remote = slash > -1 ? name.substring(0, slash) : name;
+        const mod = slash > -1 ? name.substring(slash + 1) : "./index";
+        const rc = (window as Record<string, unknown>)[remote] 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;
+      }),
+    );
+  },
 });
+```
 
-// Cleanup: use State.clean() in mixins to auto-delete keys on view destroy
-export default View.extend({
-  mixins: [State.clean("count")],
+Then `v-lark="remote-app/views/home"` just works.
+
+### Pattern 2 — CrossSite bridge view (with skeleton + prepare)
+
+For richer scenarios that want a loading skeleton and a `prepare` hook on the remote side:
+
+```ts
+import { CrossSite, registerViewClass } from "@lark.js/mvc";
+registerViewClass("cross-site", CrossSite);
+```
+
+```html
+<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.callView(name, ...args)` invokes a method on the embedded remote view via `Frame.invoke()`.
+
+### Module Federation Webpack config
+
+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" },
+      },
+    }),
+  ],
+};
+```
+
+Remote:
+
+```js
+new ModuleFederationPlugin({
+  name: "remote_app",
+  filename: "remoteEntry.js",
+  exposes: {
+    "./views/home": "./src/views/home",
+    "./prepare": "./src/prepare",
+  },
+  shared: {
+    "@lark.js/mvc": { singleton: true, requiredVersion: "^1.0.0" },
+  },
 });
 ```
 
-Key differences from Store:
+`@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.
 
-- State uses `State.set()` + `State.digest()` (manual notification), Store uses direct property assignment (automatic reactivity via Proxy)
-- State keys are auto-deleted when reference count reaches 0 (via `State.clean()` mixin), Store persists until `store.$destroyFn()` is called
-- State requires manual event listening (`State.on("changed", ...)`), Store provides `store.observe()` with auto-cleanup
+### `splitChunks.chunks` must be `"async"` in MF projects
 
-**Store pattern** (cross-view, reactive, recommended):
+| Value       | Splits initial chunks | Splits async chunks |
+| ----------- | --------------------- | ------------------- |
+| `"initial"` | yes                   | no                  |
+| `"async"`   | no                    | yes                 |
+| `"all"`     | yes                   | yes                 |
 
-```typescript
-const store = useCountStore(this);
-store.observe(this, ["count"]);
-// Later, from any view:
-useCountStore().increment(); // Automatically triggers re-render in all observing views
+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
+
+`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.
+
+Use the new APIs (preferred):
+
+- `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`.
+
+### Exposed mount function pattern
+
+For React/other-host integrations, expose a mount function rather than raw View classes:
+
+```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);
+  };
+}
 ```
 
-### Frame Tree Events
+The MF remote MUST explicitly import its CSS (`import "../index.css"`) — Webpack only bundles CSS reachable from the exposed module's import graph.
 
-Frame fires lifecycle events:
+## Three pipelines side-by-side
 
-- `add` -- new Frame created
-- `remove` -- Frame removed
-- `created` -- all child Frames rendered
-- `alter` -- child Frame content changed
+```ts
+// Updater (view-local, manual)
+this.updater.set({ count: newCount }).digest();
 
-```typescript
-Frame.on("add", ({ frame }) => {
-  /* ... */
+// 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")] });
+
+// 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
 ```
 
-### Vite vs Webpack Comparison
-
-| Feature              | Vite (larkMvcPlugin)                               | Webpack (larkMvcLoader)                            |
-| -------------------- | -------------------------------------------------- | -------------------------------------------------- |
-| Import path          | `@lark.js/mvc/vite`                                | `@lark.js/mvc/webpack`                             |
-| Type                 | Vite Plugin (resolveId + load hooks)               | Webpack Loader (standard loader interface)         |
-| Configuration        | `plugins: [larkMvcPlugin()]`                       | `module.rules` with loader rule                    |
-| Debug mode           | `larkMvcPlugin({ debug: true })`                   | `options: { debug: true }`                         |
-| HTML entry exclusion | Not needed (Vite handles index.html separately)    | `exclude: /index\.html$/`                          |
-| Dev server           | Vite dev server (fast HMR)                         | webpack-dev-server (standard HMR)                  |
-| Template compilation | Same pipeline: extractGlobalVars + compileTemplate | Same pipeline: extractGlobalVars + compileTemplate |
-
-## Common Pitfalls
-
-1. **boot.ts must be in `src/`** -- The index.html entry point references `/src/boot.ts`, not `/boot.ts`
-2. **registerViewClass before boot** -- All view classes must be registered before calling `Framework.boot()`
-3. **Template imports require larkMvcPlugin or larkMvcLoader** -- `.html` imports only work because the Vite plugin or Webpack loader compiles them at build time
-4. **Use State.set/digest, not direct mutation** -- Directly modifying State data bypasses change detection. In debug mode (`window.__lark_Debug = true`), safeguard Proxy warns about this with a 500ms delay
-5. **observe requires view binding for auto-cleanup** -- Always pass `this` to `store.observe(this, ...)` so the observation is cleaned up when the view is destroyed. Without view binding, you must manually call the returned unobserve function
-6. **Event method names use `<>` not `()`** -- The pattern is `name<click>`, not `name(click)`
-7. **assign must return altered()** -- The `assign` method should call `this.updater.snapshot()` at the start and return `this.updater.altered()` at the end to enable incremental updates
-8. **Do not modify view.signature** -- It is managed internally; setting it to 0 destroys the view. The wrapped render() increments signature automatically
-9. **v-lark containers are replaced** -- The content inside a `v-lark` element is replaced by the child view's rendered output
-10. **Webpack must exclude index.html** -- The larkMvcLoader rule must exclude `index.html` so HtmlWebpackPlugin can process it instead
-11. **Webpack uses loader object, not string name** -- Import `larkMvcLoader` from `@lark.js/mvc/webpack` and use it directly as `loader: larkMvcLoader`, not as a string like `"larkMvcLoader"`
-12. **Store reads return cloned data** — `useStore(view).count` returns a deep-cloned copy, not the reactive Proxy. Mutating the returned value does NOT trigger reactivity. Only writes through `store.key = value` are reactive
-13. **forOf requires "as" keyword** -- `{{forOf list item}}` is invalid. Must use `{{forOf list as item}}`
-14. **Inner observe deduplication** -- `store.observe(undefined, keys, callback)` uses a deduplication flag based on `key + observeKeys.join("-") + cb.toString()`. The same inner observe with identical key/callback won't register twice
-15. **View.wrapAsync is signature-based** -- The callback only executes if `view.signature` hasn't changed since `wrapAsync` was called. Re-rendering or destroying the view increments signature, invalidating the callback
-16. **Frame object pooling** -- Destroyed Frame objects are cached and reused. Don't hold references to Frame instances after unmountView() as they may be reinitialized for a different view
-17. **Updater re-digest support** -- Calling `updater.digest()` during an ongoing digest is supported via an internal queue. The sentinel pattern (`null` entry) marks the digest boundary, and callbacks are executed after all digest cycles complete
-18. **Store creator runs once** -- The creator function passed to `defineStore` runs once at definition time. Store state persists across view mounts/unmounts unless `store.$destroyFn()` is explicitly called
-19. **State is the default when no store is specified** -- Without `defineStore`, cross-view data flows through `State.set()` / `State.get()` / `State.digest()`. Always use `State.set()` + `State.digest()` to update data (never mutate `State.get()` directly). Use `State.clean()` in mixins to auto-delete keys on view destroy; otherwise, State data persists globally and is never garbage collected
+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
 
-For detailed API signatures and template syntax, consult the reference files:
+For deeper detail than this guide:
 
-- `references/api-reference.md` -- Complete API reference for all Lark modules
-- `references/template-syntax.md` -- Template syntax, operators, control flow, and event binding
+- `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.