@saolabs/client 1.0.0 → 1.1.0

package/src/core/view/ViewController.ts

@@ -1,30 +1,41 @@
-import type { BlockInterface, BlockOutletInterface, BlockRenderFactory } from "../contracts/BlockInterface";
-import type { FragmentInterface, HtmlInterface, OneChildrenFactory, OneElementEventHandler, OneNodeInterface, OutputInterface, TextInterface, WrapperInterface, YieldInterface } from "../contracts/ElementInterface";
-import type { LoopContextInterface } from "../contracts/LoopContextInterface";
-import type { ReactiveChildrenFactory, ReactiveInterface } from "../contracts/ReactiveInterface";
-import type { ViewControllerInterface, ViewType, ViewConfig, ViewRuntimeConfig, ViewControllerConfig } from "../contracts/ViewControllerInterface";
-import type { ViewInterface, ViewRenderFactory } from "../contracts/ViewInterface";
-import type { ViewStateInterface } from "../contracts/ViewStateInterface";
-import type { OneObjectType } from "../types/utils";
-import { ViewState } from "./ViewState";
-import { LoopContext } from "./LoopContext";
-import { Reactive } from "../elements/Reactive";
-import BlockManager, { BlockManagerService } from "../services/BlockManager";
-import { Component } from "../elements/Component";
-import { generateUUID } from "../hellpers/utils";
-import { Output } from "../elements/Output";
-import { View } from "./View";
-import { ApplicationInterface } from "../contracts/ApplicationInterface";
-import { SectionConstruvtorArgs, SectionContentRenderer, SectionContentType, SectionInterface, SectionItemType } from "../contracts/views";
-import { Section } from "./Section";
-import { InitMode } from "../contracts/common";
-import { Block, BlockOutlet, Fragment, Html, TextElement } from "../elements";
-import { Wrapper } from "../elements/Wrapper";
-import { YieldElement } from "../elements/Yield";
-import { app } from "../hellpers/app";
-import { ComponentInterface } from "../contracts/ComponentInterface";
-
-type ElementChild = ReactiveInterface | ComponentInterface | HtmlInterface | TextInterface | FragmentInterface | OutputInterface | BlockOutletInterface | YieldInterface | OneNodeInterface;
+import type { BlockInterface, BlockOutletInterface, BlockRenderFactory } from "../contracts/BlockInterface.js";
+import type {
+    FragmentInterface, HtmlInterface, SaoChildrenFactory, SaoChildrenFactoryOutput,
+    SaoChildrenSlotContent, SaoElementEventHandler, SaoNodeInterface, OutputInterface,
+    TextInterface, WrapperInterface, YieldInterface, EventModifier
+} from "../contracts/ElementInterface.js";
+import type { LoopContextInterface } from "../contracts/LoopContextInterface.js";
+import type { ReactiveChildrenFactory, ReactiveInterface } from "../contracts/ReactiveInterface.js";
+import type { ViewControllerInterface, ViewType, ViewConfig, ViewRuntimeConfig, ViewControllerConfig, ViewConfigThis, ErrorInfo, ErrorBoundaryHandler } from "../contracts/ViewControllerInterface.js";
+import type { ViewInterface, ViewRenderFactory } from "../contracts/ViewInterface.js";
+import type { ViewStateInterface } from "../contracts/ViewStateInterface.js";
+import type { SaoObjectType } from "../types/utils.js";
+import { ViewState } from "./ViewState.js";
+import { ResourceScope } from './ResourceScope.js';
+import { LoopContext } from "./LoopContext.js";
+import { Reactive } from "../elements/Reactive.js";
+import BlockManager, { BlockManagerService } from "../services/BlockManager.js";
+import SectionManager from "../services/SectionManager.js";
+import devtools from "../devtools/hook.js";
+import { Component } from "../elements/Component.js";
+import { generateUUID } from "../helpers/utils.js";
+import { Output } from "../elements/Output.js";
+import { View } from "./View.js";
+import type { ViewUserConfig } from "./View.js";
+import { ApplicationInterface } from "../contracts/ApplicationInterface.js";
+import { SectionConstruvtorArgs, SectionContentRenderer, SectionContentType, SectionInterface, SectionItemType } from "../contracts/SectionInterface.js";
+import { Section } from "./Section.js";
+import { InitMode } from "../contracts/common.js";
+import { Block, BlockOutlet, Fragment, Html, TextElement } from "../elements/index.js";
+import { Wrapper } from "../elements/Wrapper.js";
+import { YieldElement } from "../elements/Yield.js";
+import { app } from "../helpers/app.js";
+import { ComponentInterface } from "../contracts/ComponentInterface.js";
+import { ForeachSlotCache } from "../elements/ForeachSlotCache.js";
+import { reuseStaticText } from '../elements/reconcileChildren.js';
+import AssetManager, { StyleSpec, ScriptSpec } from "../services/AssetManager.js";
+
+type ElementChild = ReactiveInterface | ComponentInterface | HtmlInterface | TextInterface | FragmentInterface | OutputInterface | BlockOutletInterface | YieldInterface | SaoNodeInterface;
 
 /**
  * ViewController — the brain behind a View.
@@ -32,7 +43,8 @@ type ElementChild = ReactiveInterface | ComponentInterface | HtmlInterface | Tex
  * Manages:
  *   - Reactive state (ViewState) — useState, subscribe, batch flush
  *   - DOM element tree — via Html, Reactive, TextElement, Fragment
- *   - Event delegation — addEventListener with centralized cleanup
+ *   - Events — addEventListener TRỰC TIẾP trên từng element (KHÔNG delegation),
+ *     dọn hàng loạt bằng một AbortController chung. Giống React 17+/Vue/Svelte.
  *   - Loop contexts — @foreach, @for, @while with LoopContext stack
  *   - Block management — for layout views with @useBlock
  *   - Lifecycle — setup, render, destroy
@@ -48,9 +60,9 @@ type ElementChild = ReactiveInterface | ComponentInterface | HtmlInterface | Tex
  *   this.__ctrl__.__foreach(items, (item, key, index, loop) => [...])
  */
 export class ViewController implements ViewControllerInterface {
-    
+
     // ─── Identity ───────────────────────────────────────────────
-    oneType: OneObjectType = 'ViewController';
+    saoType: SaoObjectType = 'ViewController';
     public viewId: string;
     public path: string;
     public viewType: ViewType;
@@ -81,10 +93,18 @@ export class ViewController implements ViewControllerInterface {
     // ─── Data & Config ──────────────────────────────────────────
     /** Raw input data from route/parent */
     public data: Record<string, any> = {};
+
+    /**
+     * Component (@include) đã dựng view này — null với view gốc của route.
+     *
+     * Đây là lớp trung gian cha↔con: cha khai báo listener tại thẻ, Component
+     * giữ bảng đó, con phát qua {@link emit}.
+     */
+    public ownerComponent: ComponentInterface | null = null;
     /** User-defined config from setup() */
     private config: ViewConfig = {};
     /** Typed runtime config from compiled $__setup__ */
-    private runtimeConfig: ViewRuntimeConfig | null = {};
+    private runtimeConfig: ViewRuntimeConfig = {};
     /** Track own properties to avoid conflicts when setting user config */
     private ownProperties: Set<string> = new Set(['__ctrl__']);
 
@@ -103,7 +123,7 @@ export class ViewController implements ViewControllerInterface {
     /** Compiled prerender factory — produces the prerender element tree */
     private prerenderFactory: ViewRenderFactory | null = null;
 
-    public childrenFactory: OneChildrenFactory | null = null;
+    public childrenFactory: SaoChildrenFactory | null = null;
 
     /** Stored render output for lifecycle management */
     public renderOutput: any = null;
@@ -121,11 +141,40 @@ export class ViewController implements ViewControllerInterface {
     private hasScheduledUpdate = false;
     /** Centralized AbortController for all event listeners */
     private eventAbortController: AbortController = new AbortController();
+    /** Exact listener references for cleanup when an individual Html node dies. */
+    public elementEventHandlers: Map<HTMLElement, Map<string, EventListener[]>> = new Map();
 
     // ─── Loop ───────────────────────────────────────────────────
     /** Current loop context stack (@foreach, @for, @while) */
     public loopContext: LoopContext | null = null;
 
+    /**
+     * Active ForeachSlotCache — được set bởi Reactive.renderForeach() trước khi
+     * gọi childrenFactory. __foreach() đọc cache này để quyết định reuse hay create.
+     * Reset về null ngay sau khi childrenFactory trả về.
+     */
+    public _currentForeachCache: ForeachSlotCache | null = null;
+    public _foreachSkipRegistry: boolean = false;
+    private foreachRegistry: Map<string, any> | null = null;
+    private elementRegistries = new WeakMap<object, Map<string, any>>();
+    private inlineForeachCaches = new WeakMap<Map<string, any>, Map<string, ForeachSlotCache>>();
+
+    /** Deferred child factories retain the row scope in which they were created. */
+    private scopeFactory<F extends (...args: any[]) => any>(factory: F): F {
+        const registry = this.foreachRegistry;
+        if (!registry) return factory;
+        return ((...args: any[]) => this.inForeachScope(registry, () => factory(...args))) as F;
+    }
+
+    private inForeachScope<T>(registry: Map<string, any>, run: () => T): T {
+        const previous = this.foreachRegistry;
+        const skip = this._foreachSkipRegistry;
+        this.foreachRegistry = registry;
+        this._foreachSkipRegistry = false;
+        try { return run(); }
+        finally { this.foreachRegistry = previous; this._foreachSkipRegistry = skip; }
+    }
+
     // ─── Layout (Sections & Blocks) ─────────────────────────────
     /** Section management across views */
     public sections: Map<string, SectionInterface> = new Map();
@@ -133,9 +182,14 @@ export class ViewController implements ViewControllerInterface {
     public blocks: Map<string, BlockInterface> = new Map();
 
     public elements: Map<string, ElementChild> = new Map();
+    /** element → key của nó trong `elements` (xem registerElement/releaseElement) */
+    private elementKeys: WeakMap<object, string> = new WeakMap();
 
     public preloadElement: WrapperInterface | null = null; // For pre-rendering elements before the main render
     public mainElement: WrapperInterface | null = null; // The main rendered element tree
+    /** Wrapper instance RIÊNG cho render/prerender — dùng chung sẽ làm
+     *  preloadElement === mainElement → swap skeleton→main destroy nhầm chính nó */
+    private wrapperInstances: { render: WrapperInterface | null; prerender: WrapperInterface | null } = { render: null, prerender: null };
     // ─── Lifecycle Flags ────────────────────────────────────────
     /** Whether this view is currently active (mounted in DOM) */
     public isActive: boolean = false;
@@ -143,8 +197,13 @@ export class ViewController implements ViewControllerInterface {
     private _isDataCommitted = false;
     /** Whether the view has been mounted */
     private _isMounted = false;
+    /** Whether the reactive element tree has been started. */
+    private _isStarted = false;
     /** Whether the view has been fully destroyed */
     private _isDestroyed = false;
+    /** Whether this instance's styles/scripts are currently counted in AssetManager
+     *  (true = đang góp 1 ref vào real DOM). Giữ acquire/release cân bằng. */
+    private _assetsLive = false;
     /** For future use: scanning DOM for bindings */
     protected isScanMode: boolean = false;
 
@@ -165,6 +224,67 @@ export class ViewController implements ViewControllerInterface {
         this.states = new ViewState(this);
     }
 
+    private _scope?: ResourceScope;
+    get scope(): ResourceScope {
+        if (!this._scope) {
+            this._scope = new ResourceScope(this.states.__, callback => this.afterDom(callback), error => {
+                if (!this.handleError(error, { phase: 'update', path: this.path }).handled) {
+                    console.error(`[ViewController] Watch error in "${this.path}":`, error);
+                }
+            });
+            if (this._isDestroyed) this._scope.destroy();
+            else if (this._isStarted && this._lifecycleState === 'active') this._scope.resume();
+        }
+        return this._scope;
+    }
+
+    private afterDomCallbacks = new Set<() => void>();
+    private afterDomRAF: number | null = null;
+    private afterDomRevision = 0;
+
+    /** One-shot callback after this view's state and DOM queues settle. */
+    afterDom(callback: () => void): () => void {
+        if (this._isDestroyed || this._lifecycleState === 'paused') return () => {};
+        this.afterDomCallbacks.add(callback);
+        if (this.afterDomRAF === null) {
+            this.afterDomRAF = requestAnimationFrame(() => {
+                this.afterDomRAF = null;
+                const revision = this.afterDomRevision;
+                this.states.__.flushNow();
+                if (revision === this.afterDomRevision) this.flushReactiveUpdatesNow();
+            });
+        }
+        return () => {
+            this.afterDomCallbacks.delete(callback);
+            if (this.afterDomCallbacks.size === 0 && this.afterDomRAF !== null) {
+                cancelAnimationFrame(this.afterDomRAF);
+                this.afterDomRAF = null;
+            }
+        };
+    }
+
+    private flushAfterDom(): void {
+        if (this._isDestroyed || this._lifecycleState === 'paused') return;
+        this.afterDomRevision++;
+        if (this.afterDomRAF !== null) cancelAnimationFrame(this.afterDomRAF);
+        this.afterDomRAF = null;
+        // Callbacks queued by another callback belong to the next frame.
+        const callbacks = Array.from(this.afterDomCallbacks);
+        for (const callback of callbacks) {
+            if (!this.afterDomCallbacks.delete(callback)) continue;
+            try { callback(); }
+            catch (error) {
+                if (!this.handleError(error, { phase: 'update', path: this.path }).handled) console.error(error);
+            }
+        }
+    }
+
+    private cancelAfterDom(): void {
+        if (this.afterDomRAF !== null) cancelAnimationFrame(this.afterDomRAF);
+        this.afterDomRAF = null;
+        this.afterDomCallbacks.clear();
+    }
+
     // ─── Lifecycle ──────────────────────────────────────────────
 
     /**
@@ -174,7 +294,7 @@ export class ViewController implements ViewControllerInterface {
      * CHƯA gọi commitConstructorData — đợi ViewManager gọi commitData().
      */
     setup(config: ViewRuntimeConfig): void {
-        this.runtimeConfig = config as ViewRuntimeConfig;
+        this.runtimeConfig = config;
 
         // Extract metadata
         if (config.viewId) this.viewId = config.viewId;
@@ -195,7 +315,7 @@ export class ViewController implements ViewControllerInterface {
 
     getConfig(key?: string, defaultValue?: any): ViewControllerConfig | any {
         if (key) {
-            return this.runtimeConfig?.[key] ?? (this.config[key] ?? defaultValue);
+            return this.runtimeConfig[key] ?? (this.config[key] ?? defaultValue);
         }
         return { ...this.runtimeConfig, ...this.config };
     }
@@ -205,8 +325,46 @@ export class ViewController implements ViewControllerInterface {
         this.config = config || {};
     }
 
+    /** Đang chạy onError của chính controller này — chặn đệ quy nếu handler tự throw. */
+    private _handlingError = false;
+
+    /**
+     * Error boundary: tìm handler gần nhất theo chuỗi `parent`, gọi nó, trả fallback.
+     *
+     * Bất biến:
+     *   - handler trả undefined → coi như KHÔNG xử lý, bubble tiếp lên cha
+     *     (cho phép chỉ log mà không đổi UI).
+     *   - handler tự throw → bỏ qua boundary đó, bubble tiếp (không lặp vô hạn).
+     *   - không boundary nào xử lý → { handled:false }, caller giữ hành vi cũ.
+     */
+    handleError(err: unknown, info: ErrorInfo): { handled: boolean; fallback?: any } {
+        devtools.emit('error', {
+            viewId: this.viewId,
+            path: info.path,
+            detail: { phase: info.phase, message: err instanceof Error ? err.message : String(err) },
+        });
+        let ctrl: ViewControllerInterface | null = this;
+        while (ctrl) {
+            const handler = ctrl.getConfig('onError') as ErrorBoundaryHandler | undefined;
+            const self = ctrl as ViewController;
+            if (typeof handler === 'function' && !self._handlingError) {
+                self._handlingError = true;
+                try {
+                    const fallback = handler.call(ctrl.view, err, info);
+                    if (fallback !== undefined) return { handled: true, fallback };
+                } catch (e) {
+                    console.error(`[ViewController] onError of "${ctrl.path}" threw:`, e);
+                } finally {
+                    self._handlingError = false;
+                }
+            }
+            ctrl = ctrl.parent;
+        }
+        return { handled: false };
+    }
+
     /** Set user-defined properties/methods on the View instance */
-    setUserDefinedConfig(userConfig: Record<string, any>): void {
+    setUserDefinedConfig<T extends object>(userConfig: ViewUserConfig<T>): void {
         for (const [key, value] of Object.entries(userConfig)) {
             if (!this.ownProperties.has(key)) {
                 (this.view as any)[key] = typeof value === 'function' && value.bind
@@ -245,6 +403,11 @@ export class ViewController implements ViewControllerInterface {
             return output;
         }
         this.renderOutput = output;
+        // FIX(baseline#9): gán _rootTree để start()/stop()/destroy() theo controller hoạt động.
+        // Chỉ gán khi output là element tree (Wrapper) — không gán khi return superView (View).
+        if (output && typeof (output as any).start === 'function' && (output as any).saoType !== 'View') {
+            this._rootTree = output;
+        }
         this.callingMethod = oldCallingMethod;
         return output;
     }
@@ -257,6 +420,11 @@ export class ViewController implements ViewControllerInterface {
             return output;
         }
         this.prerenderOutput = output;
+        // Skeleton là tree đang live cho tới khi async render thay thế nó.
+        // Controller phải start/pause/destroy được tree này như render tree thường.
+        if (output && typeof (output as any).start === 'function' && (output as any).saoType !== 'View') {
+            this._rootTree = output;
+        }
         this.callingMethod = oldCallingMethod;
         return output;
     }
@@ -278,12 +446,110 @@ export class ViewController implements ViewControllerInterface {
         return output;
     }
 
-    mount(root: HTMLElement): void {
+    // ─── Lifecycle Hooks Dispatcher ─────────────────────────────
+    // Bộ hook vòng đời (mẫu examples/sao/app.sao) — mỗi transition một cặp
+    // before/after. Hook là method tuỳ chọn trên View (this.view[name]):
+    //   mount   → mounting / mounted       (DOM gắn vào real DOM)
+    //   start   → starting / started       (subscribe reactive + attach events)
+    //   pause   → pausing  / paused        (vào PageCache — rời real DOM)
+    //   resume  → resuming / resumed       (khôi phục từ PageCache)
+    //   stop    → stopping / stopped       (huỷ subscribe — deactivate)
+    //   unmount → unmounting / unmounted   (gỡ DOM khỏi real DOM)
+    //   destroy → destroying / destroyed   (cleanup toàn bộ)
+    // Legacy alias (tương thích test/app cũ): onMounted≈started, onPause≈paused,
+    // onResume≈resumed, onDeactivated≈stopped, onDestroy≈destroyed.
+
+    /** Gọi an toàn một lifecycle hook nếu user có định nghĩa trên View. */
+    private callHook(name: string): void {
+        const fn = (this.view as any)?.[name];
+        if (typeof fn === 'function') {
+            try {
+                const result = fn.call(this.view);
+                // Lifecycle transitions are deliberately synchronous. If a user hook
+                // is async, do not block navigation, but never leave a rejected promise
+                // unhandled either.
+                if (result && typeof result.then === 'function') {
+                    Promise.resolve(result).catch((e) => {
+                        console.error(`[ViewController] async hook "${name}" error in "${this.path}":`, e);
+                    });
+                }
+            }
+            catch (e) { console.error(`[ViewController] hook "${name}" error in "${this.path}":`, e); }
+        }
+    }
 
+    /**
+     * Mount — instance vào real DOM.
+     *   - root != null: gắn DOM tree (mainElement/preloadElement) vào root.
+     *   - root == null: nội dung đã được đặt sẵn (block outlets / component markers),
+     *     chỉ fire hook + acquire asset.
+     * Fire mounting/mounted MỘT lần mỗi vòng đời; pause→resume dùng resuming/resumed.
+     */
+    mount(root: HtmlInterface | null = null): void {
+        if (this._isDestroyed) return;
+        const firstMount = !this._isMounted;
+        if (firstMount) this.callHook('mounting');
+
+        if (root) {
+            this.setParentElement(root);
+            const el = this.mainElement ?? this.preloadElement;
+            if (el) {
+                el.setParentElement(root);
+                el.mountTo(root);
+            }
+        }
+
+        this._isMounted = true;
+        this.acquireAssets();
+        if (firstMount) {
+            this.callHook('mounted');
+            devtools.emit('view:mounted', { viewId: this.viewId, path: this.path });
+        }
     }
 
+    /** Unmount — gỡ instance khỏi real DOM (fire hook + release asset). */
     unmount(): void {
-    
+        if (this._isDestroyed || !this._isMounted) return;
+        this.callHook('unmounting');
+        this.releaseAssets();
+        this._isMounted = false;
+        this.callHook('unmounted');
+    }
+
+    // ─── Style/Script asset (AssetManager, ref-count theo path) ──
+
+    /** Đăng ký style/script của component vào real DOM (insert khi ref 0→1). */
+    private acquireAssets(): void {
+        if (this._assetsLive) return;
+        const styles = this.getConfig('styles') as StyleSpec[] | undefined;
+        const scripts = this.getConfig('scripts') as ScriptSpec[] | undefined;
+        if ((!styles || !styles.length) && (!scripts || !scripts.length)) return;
+        this._assetsLive = true;
+        AssetManager.acquire(this.path, styles, scripts, this.getSubtreeRoots());
+    }
+
+    /** Gỡ đăng ký style/script (remove khi ref 1→0). */
+    private releaseAssets(): void {
+        if (!this._assetsLive) return;
+        this._assetsLive = false;
+        const styles = this.getConfig('styles') as StyleSpec[] | undefined;
+        const scripts = this.getConfig('scripts') as ScriptSpec[] | undefined;
+        AssetManager.release(this.path, styles, scripts);
+    }
+
+    /** Các Element gốc của instance (giữa markers của Wrapper) — để tag scoped style. */
+    private getSubtreeRoots(): Node[] {
+        const wrapper: any = this.mainElement ?? this.preloadElement;
+        const open: Node | null = wrapper?.openTag ?? null;
+        const close: Node | null = wrapper?.closeTag ?? null;
+        if (!open || !close || !open.parentNode) return [];
+        const roots: Node[] = [];
+        let cur: Node | null = open.nextSibling;
+        while (cur && cur !== close) {
+            if (cur.nodeType === 1) roots.push(cur);
+            cur = cur.nextSibling;
+        }
+        return roots;
     }
 
     /**
@@ -294,21 +560,137 @@ export class ViewController implements ViewControllerInterface {
      * This ensures initial state values are set before subscriptions fire.
      */
     start(): void {
-        if (this._isDestroyed || !this._rootTree) return;
+        if (this._isDestroyed || this._isStarted) return;
+        // Page extends layout không có _rootTree (render trả về superView) —
+        // tree thật của nó là block content, được BlockManager.startAll() kích hoạt.
+        if (!this._rootTree && this.blocks.size === 0) return;
+
+        this.callHook('starting');
+        this._isStarted = true;
 
         // Recursively start all children (Output, TextElement, Html, Reactive, Fragment)
-        if ('start' in this._rootTree && typeof this._rootTree.start === 'function') {
+        if (this._rootTree && 'start' in this._rootTree && typeof this._rootTree.start === 'function') {
             this._rootTree.start();
         }
 
-        // Fire onMounted hook
-        if (typeof this.view.onMounted === 'function') {
-            try {
-                this.view.onMounted();
-            } catch (e) {
-                console.error(`[ViewController] onMounted error in "${this.path}":`, e);
-            }
+        this._lifecycleState = 'active';
+        this.isActive = true;
+
+        this._scope?.resume();
+
+        this.callHook('started');
+        this.callHook('onMounted'); // legacy alias
+    }
+
+    // ─── Pause / Resume (PageCache lifecycle) ───────────────────
+    // State machine: created → active ⇄ paused → destroyed
+    // Thiết kế: ROUTE_RENDER_FLOW.md §7. pause/resume là API công khai;
+    // stop()/start() là chi tiết nội bộ + đường mount ban đầu.
+
+    private _lifecycleState: 'created' | 'active' | 'paused' | 'destroyed' = 'created';
+    /** Data nhận được trong lúc paused (async fetch về muộn) — apply khi resume */
+    private _bufferedData: Record<string, any> | null = null;
+    /** Only children paused by this controller may be resumed by it. */
+    private _pausedChildren: ViewControllerInterface[] = [];
+
+    get lifecycleState(): string {
+        return this._lifecycleState;
+    }
+
+    /**
+     * Pause — tạm dừng để vào PageCache:
+     *   1. Flush nốt RAF pending (không mất update đang chờ)
+     *   2. State listeners → dirty-mode (KHÔNG unsubscribe — ghi sổ key đổi)
+     *   3. Hook onPause cho user dọn tài nguyên thô
+     * DOM event listeners giữ nguyên — DOM sẽ bị detach nên vô hại.
+     */
+    pause(): void {
+        if (this._lifecycleState !== 'active') {
+            if (this._lifecycleState === 'paused') return;
+            console.warn(`[ViewController] pause() bị bỏ qua: "${this.path}" đang ở trạng thái "${this._lifecycleState}".`);
+            return;
         }
+
+        this.callHook('pausing');
+        this._scope?.pause();
+        this.cancelAfterDom();
+
+        // 1. Flush nốt mọi update đang chờ → DOM là snapshot nhất quán
+        this.states.__.flushNow();
+        this.flushReactiveUpdatesNow();
+
+        // Parent pauses before descendants; descendants finish before parent.
+        // Snapshot prevents resuming children that were already inactive on entry.
+        this._pausedChildren = this.children.filter((child) => child.lifecycleState === 'active');
+        for (let i = this._pausedChildren.length - 1; i >= 0; i--) {
+            this._pausedChildren[i].pause();
+        }
+
+        // 2. Dirty-mode
+        this.states.__.pause();
+
+        this._lifecycleState = 'paused';
+        this.isActive = false;
+
+        // 3. Rời real DOM (sắp detach vào PageCache) → gỡ style/script (ref--)
+        this.releaseAssets();
+
+        // 4. Hook
+        this.callHook('paused');
+        this.callHook('onPause'); // legacy alias
+    }
+
+    /**
+     * Resume — khôi phục từ PageCache:
+     *   1. Apply buffered data (async về trong lúc paused)
+     *   2. Thoát dirty-mode → flush đúng các vùng phụ thuộc dirty keys
+     *   3. Hook onResume — nơi user quyết định refetch (theo TTL riêng...)
+     */
+    resume(): void {
+        if (this._lifecycleState !== 'paused') {
+            console.warn(`[ViewController] resume() bị bỏ qua: "${this.path}" đang ở trạng thái "${this._lifecycleState}".`);
+            return;
+        }
+
+        this.callHook('resuming');
+
+        this._lifecycleState = 'active';
+        this.isActive = true;
+
+        // 1. Quay lại real DOM → insert lại style/script (ref++)
+        this.acquireAssets();
+
+        // 2. Buffered async data → updateData thật (key đổi sẽ vào pending → flush ngay sau)
+        const buffered = this._bufferedData;
+        this._bufferedData = null;
+
+        // 3. Thoát dirty-mode; resume() của StateManager tự notify các key dirty
+        this.states.__.resume();
+
+        if (buffered) {
+            this.updateData(buffered);
+        }
+
+        // Resume outside-in: parent state is live before child subscriptions flush.
+        const pausedChildren = this._pausedChildren;
+        this._pausedChildren = [];
+        for (const child of pausedChildren) {
+            if (child.lifecycleState === 'paused') child.resume();
+        }
+
+        this._scope?.resume();
+
+        // 4. Hook
+        this.callHook('resumed');
+        this.callHook('onResume'); // legacy alias
+    }
+
+    /** Flush đồng bộ các reactive update đang chờ RAF */
+    flushReactiveUpdatesNow(): void {
+        if (this.hasScheduledUpdate || this.pendingReactiveUpdates.size > 0) {
+            this.flushReactiveUpdates();
+            this.hasScheduledUpdate = false;
+        } else this.flushAfterDom();
     }
 
     /**
@@ -316,44 +698,70 @@ export class ViewController implements ViewControllerInterface {
      * DOM stays intact but reactive updates are paused.
      */
     stop(): void {
-        if (this._isDestroyed || !this._rootTree) return;
+        if (!this._isStarted) return;
+
+        this.callHook('stopping');
+        this._isStarted = false;
+        this._scope?.pause();
+        this.cancelAfterDom();
 
         // Recursively stop all children
-        if ('stop' in this._rootTree && typeof this._rootTree.stop === 'function') {
+        if (this._rootTree && 'stop' in this._rootTree && typeof this._rootTree.stop === 'function') {
             this._rootTree.stop();
         }
 
-        // Fire onDeactivated hook
-        if (typeof this.view.onDeactivated === 'function') {
-            try {
-                this.view.onDeactivated();
-            } catch (e) {
-                console.error(`[ViewController] onDeactivated error in "${this.path}":`, e);
-            }
-        }
+        this.isActive = false;
+
+        this.callHook('stopped');
+        this.callHook('onDeactivated'); // legacy alias
     }
 
     /** Full destroy — cleanup everything */
     destroy(): void {
         if (this._isDestroyed) return;
-        this._isDestroyed = true;
 
-        // Stop reactive subscriptions first
+        this.callHook('destroying');
+
+        // stop() must run while the instance is still valid so user cleanup hooks
+        // and the element tree are not skipped.
         this.stop();
 
+        // Gỡ style/script nếu instance còn đang giữ ref (chưa qua pause)
+        this.releaseAssets();
+
+        this._isDestroyed = true;
+        this._lifecycleState = 'destroyed';
+        this._scope?.destroy();
+        this.cancelAfterDom();
+
         // Cancel pending updates
         this.pendingReactiveUpdates.clear();
         this.hasScheduledUpdate = false;
 
         // Abort all event listeners
         this.eventAbortController.abort();
+        this.elementEventHandlers.clear();
+
+        // Sắp gỡ DOM khỏi real DOM
+        const wasMounted = this._isMounted;
+        if (wasMounted) this.callHook('unmounting');
 
         // Destroy root tree
         if (this._rootTree && 'destroy' in this._rootTree && typeof this._rootTree.destroy === 'function') {
             this._rootTree.destroy();
         }
         this._rootTree = null;
+        this._isMounted = false;
+
+        // A child controller can exist outside _rootTree (for layout/block paths).
+        // Destroy remaining children in reverse ownership order; destroy is idempotent.
+        for (let i = this.children.length - 1; i >= 0; i--) {
+            this.children[i].destroy();
+        }
+        this.children = [];
+        this._pausedChildren = [];
 
+        if (wasMounted) this.callHook('unmounted');
 
         // Destroy state
         this.states.__.destroy();
@@ -361,45 +769,175 @@ export class ViewController implements ViewControllerInterface {
         // Cleanup loop context stack
         this.loopContext = null;
 
-        // Fire onDestroy hook
-        if (typeof this.view.onDestroy === 'function') {
-            try {
-                this.view.onDestroy();
-            } catch (e) {
-                console.error(`[ViewController] onDestroy error in "${this.path}":`, e);
-            }
-        }
+        // Fire onDestroy hook (legacy alias của 'destroyed')
+        this.callHook('onDestroy');
+
+        // Gỡ block content + outlets của view này khỏi BlockManager (tránh leak qua navigation)
+        BlockManager.unmountView(this.viewId);
+        BlockManager.removeOutletsOfView(this.viewId);
+
+        // Gỡ sections + yields của view này khỏi SectionManager (tránh leak qua navigation)
+        SectionManager.unmountView(this.viewId);
+        SectionManager.removeYieldsOfView(this.viewId);
+
+        // Clear element registry — tránh giữ reference corpse elements (memory leak)
+        this.elements.clear();
+        this.sections.clear();
+        this.blocks.clear();
+
+        const parent = this.parent;
+        this.parent = null;
+        parent?.removeChild(this);
 
         // Nullify references
         this.rootElement = null;
         this.renderFactory = null;
         this.prerenderFactory = null;
         this._isMounted = false;
+
+        this.callHook('destroyed');
+        devtools.emit('view:destroyed', { viewId: this.viewId, path: this.path });
+    }
+
+    active(): void {
+        this.isActive = true;
+    }
+    deactive(): void {
+        this.isActive = false;
     }
 
     // ─── Data Lifecycle ─────────────────────────────────────────
 
+    /**
+     * `this` context cho các hàm compiled config (updateVariableData dùng
+     * this.config.updateVariableItemData và this.data).
+     */
+    private makeConfigThis(): ViewConfigThis {
+        return {
+            config: this.runtimeConfig,
+            data: this.data,
+            ctrl: this,
+            view: this.view,
+        };
+    }
+
     /**
      * Commit initial data — set initial state values.
      * Called by ViewManager AFTER render + block mounting.
-     * 
+     *
      * Flow: commitConstructorData() → update$xxx(initial) → lockUpdateRealState()
+     * FIX(Phase2): trước đây method này RỖNG — compiled commitConstructorData
+     * không bao giờ được gọi.
      */
     commitData(): void {
+        if (this._isDataCommitted || this._isDestroyed) return;
+        const fn = this.runtimeConfig.commitConstructorData;
+        if (typeof fn === 'function') {
+            try {
+                fn.call(this.makeConfigThis());
+            } catch (e) {
+                console.error(`[ViewController] commitData error in "${this.path}":`, e);
+            }
+        }
+        // Lock ENFORCE ở runtime — không phụ thuộc compiler emit lockUpdateRealState()
+        // cuối commitConstructorData (view không có state → compiled fn rỗng, không lock).
+        // Từ đây update$xxx chỉ chạy được trong cửa sổ unlock của updateData.
+        this.states.__.lockUpdateRealState();
+        this._isDataCommitted = true;
     }
 
     /**
-     * Update data from external source (navigate same view, different params).
-     * Flow: unlock → updateVariableData(newData) → re-set states → lock
+     * Update data from external source (navigate same view, props từ parent...).
+     *
+     * Contract data vs state (mô hình React — data:props từ ngoài, state:của instance):
+     *   - TRƯỚC commitData (constructor phase): chỉ merge vào this.data. Factory
+     *     đã destructure __data__ lúc khởi tạo; state sẽ do commitData() init MỘT
+     *     lần. KHÔNG chạy updateVariableData ở đây — nếu chạy, sequence
+     *     unlock→lock của nó làm commitConstructorData về sau thành no-op
+     *     (update$xxx bị lock chặn) → state init phụ thuộc data rỗng hay không.
+     *   - SAU commitData: đường props-update chuẩn — unlock → updateVariableData
+     *     (trait cập nhật biến data + notify các key dẫn xuất từ data) → lock.
+     *     Instance state (init bằng literal) KHÔNG được reset ở đây — đó là
+     *     trách nhiệm của compiled updateVariableData (COMPILER_CONTRACT).
+     * Khi paused: buffer lại, apply lúc resume (ROUTE_RENDER_FLOW §8.2).
      */
     updateData(newData: Record<string, any>): void {
-        this.runtimeConfig?.updateVariableData?.(newData);
+        if (this._isDestroyed) return;
+        if (this._lifecycleState === 'paused') {
+            this._bufferedData = { ...(this._bufferedData ?? {}), ...newData };
+            return;
+        }
+        this.data = { ...this.data, ...newData };
+        if (!this._isDataCommitted) {
+            // Constructor phase (data mount / async data về TRƯỚC commit):
+            // áp data vào biến data qua TRAIT-ONLY (updateVariableItemData từng key)
+            // — closure vars nhận giá trị mới để commitData init state từ đó.
+            // KHÔNG chạy updateVariableData (tránh re-init state) và KHÔNG
+            // đụng lock (commitData cần cửa unlock của constructor phase).
+            this.applyDataTrait(newData);
+            return;
+        }
+        const fn = this.runtimeConfig.updateVariableData;
+        if (typeof fn === 'function') {
+            this.states.__.unlockUpdateRealState();
+            try {
+                fn.call(this.makeConfigThis(), newData);
+            } catch (e) {
+                console.error(`[ViewController] updateData error in "${this.path}":`, e);
+            } finally {
+                this.states.__.lockUpdateRealState();
+            }
+        }
+    }
+
+    /**
+     * Con phát sự kiện lên ĐÚNG cha đã include nó: `emit('edit', card['id'])`.
+     *
+     * Kênh trực tiếp, không qua App.Event — hai instance cùng view không nghe
+     * nhầm của nhau, và không có gì để gỡ đăng ký lúc destroy. Không ai lắng
+     * nghe thì im lặng, đúng như một DOM event không listener.
+     *
+     * Trả về giá trị handler trả về, nên con hỏi cha được (`if (!emit('close'))`).
+     */
+    emit(event: string, ...args: any[]): any {
+        const fn = this.ownerComponent?.listeners?.[event];
+        return typeof fn === 'function' ? fn(...args) : undefined;
+    }
+
+    /** Áp data vào biến data (trait) từng key — không đụng state, không đụng lock */
+    private applyDataTrait(newData: Record<string, any>): void {
+        const itemFn = this.runtimeConfig.updateVariableItemData;
+        if (typeof itemFn !== 'function') return;
+        for (const key of Object.keys(newData)) {
+            try {
+                itemFn.call(this.makeConfigThis(), key, newData[key]);
+            } catch (e) {
+                console.error(`[ViewController] applyDataTrait error in "${this.path}" (key: ${key}):`, e);
+            }
+        }
     }
 
     /**
-     * Update single data item.
+     * Update single data item — cùng contract với updateData (xem trên).
      */
     updateDataItem(key: string, value: any): void {
+        this.data[key] = value;
+        if (!this._isDataCommitted) {
+            // Constructor phase: trait-only, không đụng lock (như updateData)
+            this.applyDataTrait({ [key]: value });
+            return;
+        }
+        const fn = this.runtimeConfig.updateVariableItemData;
+        if (typeof fn === 'function') {
+            this.states.__.unlockUpdateRealState();
+            try {
+                fn.call(this.makeConfigThis(), key, value);
+            } catch (e) {
+                console.error(`[ViewController] updateDataItem error in "${this.path}":`, e);
+            } finally {
+                this.states.__.lockUpdateRealState();
+            }
+        }
     }
 
     // ─── Event Management ───────────────────────────────────────
@@ -413,7 +951,37 @@ export class ViewController implements ViewControllerInterface {
      *   - Object with handler + params: { handler: fn, params: [...] }
      *   - Object with string handler (method name on view): { handler: 'handleClick' }
      */
-    addEventListener(element: HTMLElement, event: string, handlers: OneElementEventHandler): void {
+    /**
+     * Bọc handler theo modifier của `@click.prevent.stop(...)`.
+     * `self` kiểm TRƯỚC: event từ element con thì coi như không xảy ra, nên
+     * cũng không được preventDefault/stopPropagation (giống Vue).
+     * `once` KHÔNG xử lý ở đây — nó là option của addEventListener.
+     */
+    private wrapEventModifiers(fn: EventListener, modifiers: EventModifier[]): EventListener {
+        const checkSelf = modifiers.includes('self');
+        const prevent = modifiers.includes('prevent');
+        const stop = modifiers.includes('stop');
+        if (!checkSelf && !prevent && !stop) return fn;
+
+        return function (this: any, event: Event) {
+            if (checkSelf && event.target !== event.currentTarget) return;
+            if (prevent) event.preventDefault();
+            if (stop) event.stopPropagation();
+            return (fn as any).call(this, event);
+        } as EventListener;
+    }
+
+    addEventListener(
+        element: HTMLElement,
+        event: string,
+        handlers: SaoElementEventHandler,
+        modifiers: EventModifier[] = [],
+    ): void {
+        // Compiled Html supplies the complete handler list for one event. Replacing
+        // the previous set makes render/hydrate initialization idempotent.
+        this.removeEventListener(element, event);
+        const registered: EventListener[] = [];
+        const once = modifiers.includes('once');
         for (const h of handlers) {
             let fn: EventListener;
 
@@ -456,8 +1024,29 @@ export class ViewController implements ViewControllerInterface {
                 continue;
             }
 
-            element.addEventListener(event, fn, { signal: this.eventAbortController.signal });
+            if (modifiers.length) fn = this.wrapEventModifiers(fn, modifiers);
+            element.addEventListener(event, fn, { signal: this.eventAbortController.signal, once });
+            registered.push(fn);
+        }
+
+        if (registered.length > 0) {
+            let events = this.elementEventHandlers.get(element);
+            if (!events) {
+                events = new Map();
+                this.elementEventHandlers.set(element, events);
+            }
+            events.set(event, registered);
+        }
+    }
+
+    removeEventListener(element: HTMLElement, event: string): void {
+        const events = this.elementEventHandlers.get(element);
+        const listeners = events?.get(event) ?? [];
+        for (const listener of listeners) {
+            element.removeEventListener(event, listener);
         }
+        events?.delete(event);
+        if (events?.size === 0) this.elementEventHandlers.delete(element);
     }
 
     // ─── Reactive Scheduling ────────────────────────────────────
@@ -477,6 +1066,16 @@ export class ViewController implements ViewControllerInterface {
         }
     }
 
+    /**
+     * Có vùng reactive nào đang chờ re-render trong frame này không?
+     *
+     * StateManager dùng để phân biệt "factory ném vì vùng bọc nó sắp bị dựng
+     * lại" với lỗi thật (xem StateManager.retryAfterReactiveFlush).
+     */
+    hasPendingReactiveUpdate(): boolean {
+        return this.pendingReactiveUpdates.size > 0;
+    }
+
     private flushReactiveUpdates(): void {
         if (this._isDestroyed) return;
         this.hasScheduledUpdate = false;
@@ -491,31 +1090,63 @@ export class ViewController implements ViewControllerInterface {
                 console.error(`[ViewController] Reactive update error in "${this.path}":`, e);
             }
         }
+        this.flushAfterDom();
     }
 
 
+    // Element & Block Creation Methods — called by compiled output to build the element tree directly, instead of returning HTML strings.
+
+    pushBlockAndSections(): void {
+        // This method is called by compiled output after rendering blocks and sections, to ensure they are registered in the manager before any child views try to access them.
+
+
+    }
+
+    /**
+     * @section(name, ...) — registers content for a matching @yield(name) to
+     * consume (possibly in a different controller — page declares, layout
+     * yields, same cross-controller relationship as @block/@useBlock).
+     */
     section(name: string, config: { type: SectionItemType; contentType?: SectionContentType; stateKeys?: string[], [key: string]: any }, contentRenderFactory: SectionContentRenderer): SectionInterface {
-        if (this.sections.has(name)) {
-            const section = this.sections.get(name);
-            if (section) {
-                return section;
-            }
+        const existing = this.sections.get(name);
+        if (existing) {
+            // Re-render với closure mới (state/props đổi) — cập nhật factory tại chỗ,
+            // SectionManager giữ nguyên đăng ký/subscription.
+            existing.renderFactory = contentRenderFactory;
+            existing.type = config.type;
+            if (config.contentType) existing.contentType = config.contentType;
+            existing.stateKeys = config.stateKeys ?? existing.stateKeys;
+            return existing;
         }
         config.ctx = this;
         config.name = name;
         config.renderFactory = contentRenderFactory;
         const section = new Section(config as SectionConstruvtorArgs);
         this.sections.set(name, section);
+        SectionManager.add(section);
         return section;
     }
 
+    /** `this.yieldContent(name, default)` — synchronous resolve, used inside attribute/prop binding factories. */
+    yieldContent(name: string, defaultValue: any = null): any {
+        return SectionManager.resolve(name, defaultValue);
+    }
+
+    /** Decode a raw SSR echo as RCDATA, preserving literal angle brackets. */
+    decodeTextContent(value: string): string {
+        const decoder = document.createElement('textarea');
+        decoder.innerHTML = value;
+        return decoder.textContent ?? '';
+    }
+
 
     // template methods called by compiled output — these build the element tree directly
 
     block(id: string | null, name: string, contentRenderFactory: BlockRenderFactory): BlockInterface {
         if (!id) {
-            id = `b-${name}`;
+            id = `block-${name}`;
         }
+        id = `${this.viewId}-${id}`;
         const existing = this.blocks.get(id);
         const initMode = this.initMode;
         if (existing) {
@@ -533,18 +1164,22 @@ export class ViewController implements ViewControllerInterface {
 
     blockOutlet(id: string | null = null, name: string, parentElement: HtmlInterface | null): BlockOutletInterface {
         const initMode = this.initMode;
-        if(!id) {
+        if (!id) {
             id = `ob-${name}`;
         }
-        const existing = this.elements.get(id);
-        if (existing instanceof BlockOutlet) {
+        id = `${this.viewId}-${id}`;
+        const existing = this.foreachRegistry ? this.foreachRegistry.get(id) : this.elements.get(id);
+        if (existing instanceof BlockOutlet && !(existing as any).__destroyed__) {
             existing.setParentElement(parentElement);
             existing.initMode = initMode;
+            // Re-register: BlockManager có thể đã bị reset/clear giữa các lần mount
+            // (addOutlet idempotent) — thiếu dòng này mountAll() sẽ không thấy outlet
+            BlockManager.addOutlet(id, existing);
             return existing;
         }
         const outlet = new BlockOutlet({ ctx: this, name, id, parentElement, initMode });
-        this.elements.set(id, outlet);
-        // do something if needed
+        this.registerElement(id, outlet);
+        BlockManager.addOutlet(id, outlet); // đăng ký để mountAll tìm được outlet theo name
         return outlet;
     }
 
@@ -559,12 +1194,12 @@ export class ViewController implements ViewControllerInterface {
      * Creates a Reactive region between markers that will hold the block content.
      * BlockManager.mountAll() later inserts the page view's block content here.
      */
-    useBlock(id: string | null = null, name: string, parent: HtmlInterface): BlockOutlet {
+    useBlock(id: string | null = null, name: string, parent: HtmlInterface): BlockOutletInterface {
         return this.blockOutlet(id, name, parent);
     }
 
     yield(id: string, name: string, defaultValue: any = null, parentElement: HtmlInterface | null = null): YieldInterface {
-        const existing = this.elements.get(id);
+        const existing = this.foreachRegistry ? this.foreachRegistry.get(id) : this.elements.get(id);
         if (existing instanceof YieldElement) {
             existing.setParentElement(parentElement);
             existing.defaultValue = defaultValue;
@@ -572,42 +1207,43 @@ export class ViewController implements ViewControllerInterface {
         }
         const yieldEl = new YieldElement({ ctx: this, name, initMode: this.initMode, id, defaultValue });
         yieldEl.setParentElement(parentElement);
-        this.elements.set(id, yieldEl);
+        this.registerElement(id, yieldEl);
+        // yieldEl.id đã prefix viewId (globally unique) — dùng làm key trong SectionManager,
+        // đăng ký để SectionManager.mountViewSections() tìm được outlet theo name.
+        SectionManager.addYield(yieldEl.id, yieldEl);
         return yieldEl;
     }
 
-    yieldContent(name: string, defaultValue: any = null): any {
-        return this.App.View?.yieldContent?.(name, defaultValue) ?? defaultValue;
-    }
-
-    wrapper(factory: OneChildrenFactory): WrapperInterface {
-        const callingMethod = this.callingMethod;
-        let key: 'preloadElement' | 'mainElement' = callingMethod === 'prerender' ? 'preloadElement' : 'mainElement';
-        let wrapper = this[key];
-        if (!wrapper) {
+    wrapper(factory: SaoChildrenFactory): WrapperInterface {
+        const which: 'render' | 'prerender' = this.callingMethod === 'prerender' ? 'prerender' : 'render';
+        const key: 'preloadElement' | 'mainElement' = which === 'prerender' ? 'preloadElement' : 'mainElement';
+        let wrapper = this.wrapperInstances[which];
+        if (!wrapper || (wrapper as any).__destroyed__) {
             wrapper = new Wrapper({ ctx: this, initMode: this.initMode, parentElement: this.parentElement, childrenFactory: factory });
-            this[key] = wrapper;
-        }else{
+            this.wrapperInstances[which] = wrapper;
+        } else {
             wrapper.setChildrenFactory(factory);
         }
+        this[key] = wrapper;
         return wrapper;
     }
 
 
-    fragment(id: string | null = null, parentElement: HtmlInterface | null, childrenFactory: OneChildrenFactory): FragmentInterface {
+    fragment(id: string | null = null, parentElement: HtmlInterface | null, childrenFactory: SaoChildrenFactory): FragmentInterface {
+        childrenFactory = this.scopeFactory(childrenFactory);
         if (!id) {
             id = `fr-${generateUUID(5)}`;
         }
-        const existing = this.elements.get(id);
-        if (existing instanceof Fragment) {
-            if(childrenFactory) {
+        const existing = this.aliveFromRegistry(id, Fragment);
+        if (existing) {
+            if (childrenFactory) {
                 existing.setChildrenFactory(childrenFactory);
             }
             return existing;
         }
         const initMode = this.initMode;
-        const fragment = new Fragment({ctx: this, id, initMode, parentElement, childrenFactory });
-        this.elements.set(id, fragment);
+        const fragment = new Fragment({ ctx: this, id, initMode, parentElement, childrenFactory });
+        this.registerElement(id, fragment);
         return fragment;
     }
 
@@ -617,31 +1253,37 @@ export class ViewController implements ViewControllerInterface {
      * These methods are called by the compiled output for loops, conditionals, and other directives.
      */
 
-    html(id: string | null = null, tagName: string, parentElement: HtmlInterface | null, config: any, childrenFactory?: OneChildrenFactory): OneNodeInterface {
+    html(id: string | null = null, tagName: string, parentElement: HtmlInterface | null, config: any, childrenFactory?: SaoChildrenFactory): SaoNodeInterface {
+        if (childrenFactory) childrenFactory = this.scopeFactory(childrenFactory);
         if (!id) {
             id = `el-${tagName}-${generateUUID(5)}`;
         }
-        const existing = this.elements.get(id);
-        if (existing instanceof Html) {
+        const existing = this.aliveFromRegistry(id, Html);
+        if (existing) {
             existing.updateConfig(config);
-            if(childrenFactory) {
+            if (childrenFactory) {
                 existing.setChildrenFactory(childrenFactory);
             }
             return existing;
         }
         const element = new Html({ ctx: this, tagName, id, parentElement, initMode: this.initMode, config, childrenFactory });
-        this.elements.set(id, element);
+        this.registerElement(id, element);
         return element;
     }
 
 
     reactive(id: string | null, type: string, parentReactive: ReactiveInterface | null, parentElement: HtmlInterface | null, stateKeys: string[], childrenFactory: ReactiveChildrenFactory): ReactiveInterface {
+        childrenFactory = this.scopeFactory(childrenFactory);
         // check
         if (!id) {
             id = `r-${type}-${generateUUID(5)}`;
         }
-        const existing = this.elements.get(id);
-        if (existing instanceof Reactive) {
+        // Prefix viewId để khớp marker id server phát ra (RUNTIME_CONTRACT §5):
+        // compiler emit cùng hash cho JS + Blade, server hoá thành `${viewId}-${hash}`.
+        // Giống output()/block()/blockOutlet() — Reactive trước đây bị thiếu bước này.
+        id = `${this.viewId}-${id}`;
+        const existing = this.aliveFromRegistry(id, Reactive);
+        if (existing) {
             existing.setChildrenFactory(childrenFactory);
             existing.setStateKeys(stateKeys);
             return existing;
@@ -653,18 +1295,19 @@ export class ViewController implements ViewControllerInterface {
             parentReactive,
             parentElement,
             stateKeys,
-            childrenFactory
+            childrenFactory,
+            initMode: this.initMode,
         });
-        this.elements.set(id, reactive);
+        this.registerElement(id, reactive);
         return reactive;
     }
 
     output(id: string | null, parent: HtmlInterface | null, isEscapeHTML: boolean = true, stateKeys: string[] = [], contentFactory: () => string = () => ''): OutputInterface {
-        if(!id) {
+        if (!id) {
             id = `o-${generateUUID(5)}`;
         }
-        const existing = this.elements.get(id);
-        if (existing instanceof Output) {
+        const existing = this.aliveFromRegistry(id, Output);
+        if (existing) {
             existing.setStateKeys(stateKeys);
             existing.contentFactory = contentFactory;
             return existing;
@@ -676,13 +1319,93 @@ export class ViewController implements ViewControllerInterface {
             stateKeys,
             isEscapeHTML,
             contentFactory,
+            initMode: this.initMode,
         });
-        this.elements.set(id, output);
+        this.registerElement(id, output);
         return output;
     }
 
-    text(text: string): Text{
-        return document.createTextNode(text) as Text;
+    /**
+     * FIX(baseline#2): trả về TextElement (có saoType) thay vì raw Text node.
+     * Raw Text node bị mountElementList/Reactive.render bỏ qua → text tĩnh biến mất.
+     */
+    text(text: string): TextInterface {
+        return new TextElement({ ctx: this, stateKeys: [], generateText: () => text });
+    }
+
+    /**
+     * Ghi element vào registry + nhớ key để destroy() gỡ lại được.
+     * Key là id THÔ; `element.id` phần lớn đã prefix viewId (`${viewId}-${id}`)
+     * nên element KHÔNG tự suy ra key được — WeakMap giữ ánh xạ, không giữ
+     * element sống.
+     */
+    private registerElement<T extends object>(id: string, el: T): T {
+        this.elements.set(id, el as any);
+        this.elementKeys.set(el, id);
+        if (this.foreachRegistry) {
+            this.foreachRegistry.set(id, el);
+            this.elementRegistries.set(el, this.foreachRegistry);
+        }
+        return el;
+    }
+
+    /**
+     * Element tự gỡ khỏi registry trong destroy() — nếu không, `elements` chỉ
+     * co lại lúc destroy view, còn id sinh theo item (`{hash}-${item.id}`) thì
+     * mỗi trang/mỗi lần refresh lại thêm một corpse vĩnh viễn (đo được:
+     * 32 → 182 entry sau 6 trang trong khi DOM vẫn 10 item).
+     *
+     * Guard `=== el` là bắt buộc: pass mới đã ghi element MỚI vào cùng id TRƯỚC
+     * khi prunePass destroy element cũ — xoá vô điều kiện sẽ gỡ nhầm bản mới.
+     */
+    releaseElement(el: object): void {
+        const id = this.elementKeys.get(el);
+        if (id === undefined) return;
+        this.elementKeys.delete(el);
+        const registry = this.elementRegistries.get(el);
+        if (registry?.get(id) === el) registry.delete(id);
+        this.elementRegistries.delete(el);
+        if (this.elements.get(id) === el) this.elements.delete(id);
+    }
+
+    /**
+     * Registry guard: element đã destroy không được reuse — trả về corpse
+     * (events đã abort, markers đã gỡ) gây render rỗng / stale closure.
+     * Xem docs/RUNTIME_CONTRACT.md §2.
+     */
+    private aliveFromRegistry<T>(id: string, ctor: abstract new (...args: any[]) => T): T | null {
+        if (this._foreachSkipRegistry) return null;
+        const existing = this.foreachRegistry ? this.foreachRegistry.get(id) : this.elements.get(id);
+        if (existing instanceof ctor && !(existing as any).__destroyed__) {
+            return existing as T;
+        }
+        return null;
+    }
+
+    /** Deterministic fallback counter for the (contract-violating) missing-id path. */
+    private _missingIncludeIdCounter = 0;
+
+    /**
+     * Resolve the hydrate id for an @include component.
+     *
+     * The compiler ALWAYS emits a deterministic id (md5[:8] of the position-based
+     * base id) so the client marker `s:c:{viewId}-{id}` matches the server-rendered
+     * one. A missing id therefore means a compiler/runtime contract violation — and
+     * in HYDRATE mode it guarantees a marker mismatch (claimSSRMarkers finds nothing
+     * → silent CSR re-render / duplicated DOM).
+     *
+     * Never invent a RANDOM id here: a random id also makes every `elements.get(id)`
+     * lookup miss, so the component is recreated on each render (cache broken). We
+     * surface the violation loudly and fall back to a render-stable deterministic id
+     * so behaviour stays idempotent even in the broken case.
+     */
+    private resolveIncludeId(id: string | null, kind: string, path: string): string {
+        if (id) return id;
+        console.error(
+            `[Saola] ${kind}(): missing hydrate id for view "${path}". The compiler must ` +
+            `pass a deterministic id — marker sync with the server is broken for this component.`
+        );
+        return `cpn-missing-${this._missingIncludeIdCounter++}`;
     }
 
     include(
@@ -690,89 +1413,93 @@ export class ViewController implements ViewControllerInterface {
         path: string = '',
         parentElement: HtmlInterface | null,
         stateKeys: string[],
-        dataFactory: (parentElement: HtmlInterface | null) => Record<string, any>
+        dataFactory: (parentElement: HtmlInterface | null) => Record<string, any>,
+        listeners: Record<string, (...args: any[]) => any> = {}
     ): Component {
-        if(!id) {
-            id = `cpn-${generateUUID(5)}`;
-        }
-        const existing = this.elements.get(id);
-        if (existing instanceof Component) {
+        id = this.resolveIncludeId(id, 'include', path);
+        const existing = this.aliveFromRegistry(id, Component);
+        if (existing) {
             existing.setDataFactory(dataFactory);
-            if(stateKeys) {
+            existing.setListeners(listeners);
+            if (stateKeys) {
                 existing.setStateKeys(stateKeys);
             }
             return existing;
         }
         let component = new Component({
             ctx: this,
-            id: id ?? generateUUID(10),
+            id,
             stateKeys,
             parent: parentElement,
             dataFactory,
             path,
             type: 'default',
+            initMode: this.initMode,
+            listeners,
         });
-        this.elements.set(id, component);
+        this.registerElement(id, component);
 
         return component;
     }
 
-    includeIf(id: string | null = null, path: string, parentElement: HtmlInterface | null, stateKeys: string[], dataFactory: (parentElement: HtmlInterface | null) => Record<string, any>): Component {
-        if(!id) {
-            id = `c-${generateUUID(5)}`;
-        }
-        const existing = this.elements.get(id);
-        if (existing instanceof Component) {
+    includeIf(id: string | null = null, path: string, parentElement: HtmlInterface | null, stateKeys: string[], dataFactory: (parentElement: HtmlInterface | null) => Record<string, any>, listeners: Record<string, (...args: any[]) => any> = {}): Component {
+        id = this.resolveIncludeId(id, 'includeIf', path);
+        const existing = this.aliveFromRegistry(id, Component);
+        if (existing) {
             existing.setDataFactory(dataFactory);
-            if(stateKeys) {
+            existing.setListeners(listeners);
+            if (stateKeys) {
                 existing.setStateKeys(stateKeys);
             }
             return existing;
         }
         let component = new Component({
             ctx: this,
-            id: id ?? generateUUID(10),
+            id,
             stateKeys,
             parent: parentElement,
             dataFactory,
             path,
             type: 'if',
+            initMode: this.initMode,
+            listeners,
         });
-        this.elements.set(id, component);
+        this.registerElement(id, component);
         return component;
     }
 
-    includeWhen(id: string | null, condition: { stateKeys: string[], checker: () => any }, path: string, parentElement: HtmlInterface | null, stateKeys: string[], dataFactory: (parentElement: HtmlInterface | null) => Record<string, any>): Component {
-        if(!id) {
-            id = `cpn-${generateUUID(5)}`;
-        }
-        const existing = this.elements.get(id);
-        if (existing instanceof Component) {
+    includeWhen(id: string | null, condition: { stateKeys: string[], checker: () => any }, path: string, parentElement: HtmlInterface | null, stateKeys: string[], dataFactory: (parentElement: HtmlInterface | null) => Record<string, any>, listeners: Record<string, (...args: any[]) => any> = {}): Component {
+        id = this.resolveIncludeId(id, 'includeWhen', path);
+        const existing = this.aliveFromRegistry(id, Component);
+        if (existing) {
             existing.setDataFactory(dataFactory);
             existing.setCondition(condition);
-            if(stateKeys) {
+            if (stateKeys) {
                 existing.setStateKeys(stateKeys);
             }
             return existing;
         }
         let component = new Component({
             ctx: this,
-            id: id ?? generateUUID(10),
+            id,
             stateKeys,
             parent: parentElement,
             dataFactory,
             path,
             type: 'when',
             condition,
+            initMode: this.initMode,
+            listeners,
         });
-        this.elements.set(id, component);
+        this.registerElement(id, component);
         return component;
     }
 
     extendView(path: string, data: Record<string, any> = {}): ViewInterface | null {
         this.superViewPath = path;
-        const superView:ViewInterface = this.App.View?.view(path, data, true);
-        if(superView){
+        // Sync: render() trả superView ngay (xem ViewManager.resolveViewSync).
+        const superView: ViewInterface = this.App.View?.resolveViewSync(path, data, true);
+        if (superView) {
             this.setSuperView(superView?.__ctrl__);
             return superView;
         }
@@ -809,60 +1536,127 @@ export class ViewController implements ViewControllerInterface {
     /**
      * @foreach directive — iterate over array or object.
      * Returns array of children (not HTML string like the old system).
-     * 
-     * @example Compiled output:
+     *
+     * # Cache-aware re-render (Phase 5 + 5b)
+     * Khi `_currentForeachCache` được set (bởi Reactive), __foreach claim slot
+     * cho từng item:
+     *   - Hit (key khớp + item ref giống) → reuse elements cũ (không recreate DOM)
+     *   - Miss → gọi callback → tạo elements mới → store vào cache
+     *
+     * Cache key:
+     *   - `keyFn` (compiler emit từ @key(expr)) → field keying (`item.id`)
+     *   - không có → object reference của item (identity keying)
+     * Duplicate keys/primitive items phân biệt bằng occurrence (ForeachSlotCache).
+     * Ref đổi nhưng key trùng → recreate (closure đóng gói item cũ) — slot cũ
+     * được Reactive.prunePass destroy.
+     *
+     * @example Compiled output (@key(item.id)):
      * ctrl.__foreach(items, (item, key, index, loop) => [
-     *     em.h(ctrl, parent, 'div', {}, () => [em.t(`Item: ${item}`)])
-     * ])
+     *     this.html(`id-${item.id}`, 'div', p, {}, () => [this.text(item.name)])
+     * ], (item) => item.id)
+     */
+    /**
+     * @children / {{ $children }} — materialize slot content from the parent
+     * include only when render traversal reaches ChildrenNode (compiler emit:
+     * `...this.__children(__ONE_CHILDREN_CONTENT__, parentElement)`).
+     *
+     * content có 2 dạng (xem COMPILER _gen_children_slot):
+     *   - function `(parentElement) => elements` — element factory từ
+     *     @importInclude/custom tag phía parent. Factory đóng gói `this` của
+     *     PARENT ctrl → elements thuộc parent scope (state/registry parent),
+     *     giống React children.
+     *   - string — SSR data hoặc default '' → render text tĩnh (rỗng → []).
      */
+    __children(content: SaoChildrenSlotContent, parentElement: HtmlInterface | null): SaoChildrenFactoryOutput {
+        if (typeof content === 'function') {
+            const out = content(parentElement);
+            if (out === null || out === undefined) return [];
+            return Array.isArray(out) ? out : [out];
+        }
+        if (content === null || content === undefined || content === '') return [];
+        return [this.text(String(content))];
+    }
+
     __foreach<T>(
         list: T[] | Record<string, T>,
-        callback: (item: T, key: string, index: number, loop: LoopContext) => any
+        callback: (item: T, key: string, index: number, loop: LoopContextInterface, identity: number) => any,
+        keyFn?: (item: T, index: number) => any,
+        reconcile = false,
+        scopeId?: string,
     ): any[] {
         if (!list || typeof list !== 'object') return [];
-
+        let cache = Array.isArray(list) || reconcile ? this._currentForeachCache : null;
+        let ownsPass = false;
+        if (!cache && reconcile && scopeId && this.foreachRegistry) {
+            let caches = this.inlineForeachCaches.get(this.foreachRegistry);
+            if (!caches) this.inlineForeachCaches.set(this.foreachRegistry, caches = new Map());
+            cache = caches.get(scopeId) ?? null;
+            if (!cache) caches.set(scopeId, cache = new ForeachSlotCache());
+            cache.beginPass();
+            ownsPass = true;
+        }
         const result: any[] = [];
+        const keys = Array.isArray(list)
+            ? Object.keys(list).filter(key => String(Number(key)) === key && Number(key) >= 0 && Number(key) < list.length)
+            : Object.keys(list);
+        const loopCtx = this.__setLoopContext(Array.isArray(list) ? list.length : keys.length);
+        loopCtx.setType('increment');
         try {
-            if (Array.isArray(list)) {
-                const loopCtx = this.__setLoopContext(list.length);
-                loopCtx.setType('increment');
-                list.forEach((item, index) => {
-                    loopCtx.setCurrentTimes(index);
-                    const output = callback(item, String(index), index, loopCtx);
-                    if (output !== undefined && output !== null) {
-                        if (Array.isArray(output)) result.push(...output);
-                        else result.push(output);
-                    }
-                });
-            } else {
-                const keys = Object.keys(list);
-                const loopCtx = this.__setLoopContext(keys.length);
-                loopCtx.setType('increment');
-                keys.forEach((key, index) => {
-                    loopCtx.setCurrentTimes(index);
-                    const output = callback((list as Record<string, T>)[key], key, index, loopCtx);
-                    if (output !== undefined && output !== null) {
-                        if (Array.isArray(output)) result.push(...output);
-                        else result.push(output);
-                    }
-                });
-            }
-        } catch (e) {
-            console.error(`[ViewController] @foreach error in "${this.path}":`, e);
+            keys.forEach((key, index) => {
+                // Sparse arrays retain their actual index and loop count.
+                const loopIndex = Array.isArray(list) ? Number(key) : index;
+                const item = (list as any)[key] as T;
+                loopCtx.setCurrentTimes(loopIndex);
+                const cacheKey = keyFn ? keyFn(item, loopIndex) : item;
+                const claim = cache?.claim(cacheKey, item, reconcile);
+                const slot = claim?.slot;
+                if (slot && !reconcile) {
+                    result.push(...slot.elements);
+                    return;
+                }
+                const registry = reconcile ? slot?.registry ?? new Map<string, any>() : null;
+                const identity = slot?.identity ?? (cache && reconcile ? cache.allocateIdentity(loopIndex) : loopIndex);
+                const previousCache = this._currentForeachCache;
+                const previousSkip = this._foreachSkipRegistry;
+                this._currentForeachCache = null; // nested inline loops own no outer slots
+                if (cache && !reconcile) this._foreachSkipRegistry = true;
+                let output: any;
+                try {
+                    const run = () => callback(item, key, loopIndex, loopCtx.snapshot(), identity);
+                    output = registry ? this.inForeachScope(registry, run) : run();
+                } finally {
+                    this._currentForeachCache = previousCache;
+                    this._foreachSkipRegistry = previousSkip;
+                }
+                let elements = output == null ? [] : Array.isArray(output) ? output : [output];
+                if (slot && reconcile) elements = reuseStaticText(slot.elements, elements);
+                result.push(...elements);
+                if (cache && claim) {
+                    if (slot && reconcile) {
+                        slot.item = item;
+                        slot.identity = identity;
+                        slot.elements = elements;
+                        for (const el of elements) cache.refreshedElements.add(el);
+                    } else cache.store(cacheKey, claim.occ, item, elements, registry ?? undefined).identity = identity;
+                }
+            });
+            if (ownsPass) cache!.prunePass(slot => {
+                for (const el of slot.elements) el.destroy?.();
+            });
         } finally {
             this.__resetLoopContext();
         }
         return result;
     }
 
-    __forelse<T>(list: T[], callback: (item: T, key: string, index: number, loop: LoopContext) => any, emptyCallback: () => any = () => []): any[] {
+    __forelse<T>(list: T[], callback: (item: T, key: string, index: number, loop: LoopContextInterface) => any, emptyCallback: () => any = () => []): any[] {
         if (this.App.Helper.count(list) === 0) {
             return emptyCallback();
         }
         return this.__foreach(list, callback);
     }
 
-    __each<T>(list: T[], callback: (item: T, key: string, index: number, loop: LoopContext) => any): any[] {
+    __each<T>(list: T[], callback: (item: T, key: string, index: number, loop: LoopContextInterface) => any): any[] {
         return this.__foreach(list, callback);
     }
 
@@ -911,6 +1705,91 @@ export class ViewController implements ViewControllerInterface {
     }
 
 
+    // ─── Directive Binding Helpers ──────────────────────────────
+    //
+    // Compiler pre-processes @style/@class directives thành template literal
+    // calls trước khi tạo element config.
+    // Ví dụ: @style([...]) → ${this.__styleBinding([...], [...])}
+    //        @class([...]) → ${this.__classBinding([...])}  (legacy path)
+    //
+    // Các method này được Html._applyAttr() gọi qua factory khi render và khi
+    // state thay đổi (Html đã subscribe stateKeys từ compiled config).
+    //
+    // `__showBinding` từng ở đây, cho `@show`. Compiler đã gỡ `@show`/`@hide`
+    // (chúng hỏng ở CẢ HAI nhánh và ra hai cây DOM khác nhau) nên không còn ai
+    // gọi tới — xem docs/SAO_ELEMENT_DIRECTIVES_RFC.md §10.1.
+    // ────────────────────────────────────────────────────────────
+
+    /**
+     * __styleBinding — tính inline CSS style string cho @style directive.
+     *
+     * Compiler emit (pre-process trước AST):
+     *   @style(['color' => $textColor, 'font-size' => $fontSize])
+     *   →  ${this.__styleBinding(['textColor', 'fontSize'], [['color', textColor], ['font-size', fontSize]])}
+     *
+     * Hành vi:
+     *   - Lọc bỏ entries có value null / undefined / false / '' (không set prop đó)
+     *   - Join thành "prop: value; prop: value" string
+     *
+     * @param _stateKeys - Danh sách state keys (đã encode trong config, không dùng ở đây)
+     * @param styles     - Mảng [cssProperty, value] pairs
+     *
+     * @example
+     *   __styleBinding([], [['color', 'red'], ['font-size', null], ['display', 'block']])
+     *   // → "color: red; display: block"
+     */
+    __styleBinding(_stateKeys: string[], styles: [string, any][]): string {
+        if (!Array.isArray(styles)) return '';
+        return styles
+            .filter(([, value]) => value !== null && value !== undefined && value !== false && value !== '')
+            .map(([prop, value]) => `${prop}: ${String(value)}`)
+            .join('; ');
+    }
+
+    /**
+     * __classBinding — tính CSS class string cho @class binding (legacy template path).
+     *
+     * Chỉ được gọi bởi OLD template_processor (flat compiler) fallback path.
+     * New AST path (RenderGenerator) emit class config trực tiếp vào options.classes[]
+     * → Html.initializeClasses() xử lý, KHÔNG dùng __classBinding.
+     *
+     * Format input (từ class_binding_handler.py):
+     *   [{ type: 'static', value: 'foo' },
+     *    { type: 'binding', value: 'is-active', states: ['isActive'], checker: () => isActive }]
+     *
+     * @param configs - Mảng class config objects
+     * @returns Space-joined class string
+     *
+     * @example
+     *   __classBinding([
+     *     { type: 'static', value: 'btn' },
+     *     { type: 'binding', value: 'btn-primary', checker: () => isPrimary }
+     *   ])
+     *   // isPrimary = true → "btn btn-primary"
+     *   // isPrimary = false → "btn"
+     */
+    __classBinding(configs: Array<{
+        type: 'static' | 'binding';
+        value: string;
+        states?: string[];
+        checker?: () => any;
+    }>): string {
+        if (!Array.isArray(configs)) return '';
+        const classes: string[] = [];
+        for (const config of configs) {
+            if (!config?.value) continue;
+            if (config.type === 'static') {
+                classes.push(config.value);
+            } else if (config.type === 'binding') {
+                // Thực thi checker để quyết định thêm class không
+                if (typeof config.checker === 'function' && config.checker()) {
+                    classes.push(config.value);
+                }
+            }
+        }
+        return classes.join(' ');
+    }
+
     // mounting
 
 
@@ -945,11 +1824,16 @@ export class ViewController implements ViewControllerInterface {
     setIsSuperView(isSuper: boolean): void {
         this.isSuperView = isSuper;
     }
-    setParent(parent: ViewControllerInterface): void {
+    setParent(parent: ViewControllerInterface | null): void {
         this.parent = parent;
     }
     addChild(child: ViewControllerInterface): void {
-        this.children.push(child);
+        if (!this.children.includes(child)) this.children.push(child);
+    }
+    removeChild(child: ViewControllerInterface): void {
+        const index = this.children.indexOf(child);
+        if (index >= 0) this.children.splice(index, 1);
+        if (child.parent === this) child.setParent(null);
     }
 
 
@@ -958,7 +1842,7 @@ export class ViewController implements ViewControllerInterface {
      * Called by ViewManager after creating the view and its super view(s).
      */
     setChainFromOrigin(): void {
-        if(this.superView){
+        if (this.superView) {
             this.superView.setOriginView(this);
             this.superView.setChainFromOrigin();
         }
@@ -968,7 +1852,7 @@ export class ViewController implements ViewControllerInterface {
      * When a view is destroyed, it should eject itself from the origin chain to prevent memory leaks.
      */
     ejectOriginChain(): void {
-        if(this.originView){
+        if (this.originView) {
             const origin = this.originView;
             this.originView = null;
             origin.ejectOriginChain();