@saolabs/client 1.0.0 → 1.0.2

package/dist/src/core/view/ViewController.js

@@ -1,22 +1,29 @@
-import { ViewState } from "./ViewState";
-import { LoopContext } from "./LoopContext";
-import { Reactive } from "../elements/Reactive";
-import BlockManager from "../services/BlockManager";
-import { Component } from "../elements/Component";
-import { generateUUID } from "../hellpers/utils";
-import { Output } from "../elements/Output";
-import { Section } from "./Section";
-import { Block, BlockOutlet, Fragment, Html } from "../elements";
-import { Wrapper } from "../elements/Wrapper";
-import { YieldElement } from "../elements/Yield";
-import { app } from "../hellpers/app";
+import { ViewState } from "./ViewState.js";
+import { ResourceScope } from './ResourceScope.js';
+import { LoopContext } from "./LoopContext.js";
+import { Reactive } from "../elements/Reactive.js";
+import BlockManager 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 { Section } from "./Section.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 { ForeachSlotCache } from "../elements/ForeachSlotCache.js";
+import { reuseStaticText } from '../elements/reconcileChildren.js';
+import AssetManager from "../services/AssetManager.js";
 /**
  * ViewController — the brain behind a View.
  *
  * 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
@@ -32,10 +39,30 @@ import { app } from "../hellpers/app";
  *   this.__ctrl__.__foreach(items, (item, key, index, loop) => [...])
  */
 export class ViewController {
+    /** Deferred child factories retain the row scope in which they were created. */
+    scopeFactory(factory) {
+        const registry = this.foreachRegistry;
+        if (!registry)
+            return factory;
+        return ((...args) => this.inForeachScope(registry, () => factory(...args)));
+    }
+    inForeachScope(registry, run) {
+        const previous = this.foreachRegistry;
+        const skip = this._foreachSkipRegistry;
+        this.foreachRegistry = registry;
+        this._foreachSkipRegistry = false;
+        try {
+            return run();
+        }
+        finally {
+            this.foreachRegistry = previous;
+            this._foreachSkipRegistry = skip;
+        }
+    }
     // ─── Constructor ────────────────────────────────────────────
     constructor(view, path = '', viewType = 'view', viewId = null) {
         // ─── Identity ───────────────────────────────────────────────
-        this.oneType = 'ViewController';
+        this.saoType = 'ViewController';
         // ─── View Hierarchy ─────────────────────────────────────────
         /** Parent view controller (for nested views) */
         this.parent = null;
@@ -52,6 +79,13 @@ export class ViewController {
         // ─── Data & Config ──────────────────────────────────────────
         /** Raw input data from route/parent */
         this.data = {};
+        /**
+         * 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}.
+         */
+        this.ownerComponent = null;
         /** User-defined config from setup() */
         this.config = {};
         /** Typed runtime config from compiled $__setup__ */
@@ -84,17 +118,34 @@ export class ViewController {
         this.hasScheduledUpdate = false;
         /** Centralized AbortController for all event listeners */
         this.eventAbortController = new AbortController();
+        /** Exact listener references for cleanup when an individual Html node dies. */
+        this.elementEventHandlers = new Map();
         // ─── Loop ───────────────────────────────────────────────────
         /** Current loop context stack (@foreach, @for, @while) */
         this.loopContext = 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ề.
+         */
+        this._currentForeachCache = null;
+        this._foreachSkipRegistry = false;
+        this.foreachRegistry = null;
+        this.elementRegistries = new WeakMap();
+        this.inlineForeachCaches = new WeakMap();
         // ─── Layout (Sections & Blocks) ─────────────────────────────
         /** Section management across views */
         this.sections = new Map();
         /** Block slots in layout views */
         this.blocks = new Map();
         this.elements = new Map();
+        /** element → key của nó trong `elements` (xem registerElement/releaseElement) */
+        this.elementKeys = new WeakMap();
         this.preloadElement = null; // For pre-rendering elements before the main render
         this.mainElement = 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ó */
+        this.wrapperInstances = { render: null, prerender: null };
         // ─── Lifecycle Flags ────────────────────────────────────────
         /** Whether this view is currently active (mounted in DOM) */
         this.isActive = false;
@@ -102,13 +153,34 @@ export class ViewController {
         this._isDataCommitted = false;
         /** Whether the view has been mounted */
         this._isMounted = false;
+        /** Whether the reactive element tree has been started. */
+        this._isStarted = false;
         /** Whether the view has been fully destroyed */
         this._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. */
+        this._assetsLive = false;
         /** For future use: scanning DOM for bindings */
         this.isScanMode = false;
         // --- Route params for reference in blocks and sections (set by ViewManager on navigate) ---
         this.urlPath = null;
         this.callingMethod = null; // For debugging: track which method is currently executing
+        this.afterDomCallbacks = new Set();
+        this.afterDomRAF = null;
+        this.afterDomRevision = 0;
+        /** Đang chạy onError của chính controller này — chặn đệ quy nếu handler tự throw. */
+        this._handlingError = false;
+        // ─── 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.
+        this._lifecycleState = 'created';
+        /** Data nhận được trong lúc paused (async fetch về muộn) — apply khi resume */
+        this._bufferedData = null;
+        /** Only children paused by this controller may be resumed by it. */
+        this._pausedChildren = [];
+        /** Deterministic fallback counter for the (contract-violating) missing-id path. */
+        this._missingIncludeIdCounter = 0;
         this.__App = app();
         this.view = view;
         this.path = path;
@@ -116,6 +188,69 @@ export class ViewController {
         this.viewId = viewId ?? this.generateViewId();
         this.states = new ViewState(this);
     }
+    get scope() {
+        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;
+    }
+    /** One-shot callback after this view's state and DOM queues settle. */
+    afterDom(callback) {
+        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;
+            }
+        };
+    }
+    flushAfterDom() {
+        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);
+            }
+        }
+    }
+    cancelAfterDom() {
+        if (this.afterDomRAF !== null)
+            cancelAnimationFrame(this.afterDomRAF);
+        this.afterDomRAF = null;
+        this.afterDomCallbacks.clear();
+    }
     // ─── Lifecycle ──────────────────────────────────────────────
     /**
      * Setup — called by compiled $__setup__ with full config.
@@ -142,7 +277,7 @@ export class ViewController {
     }
     getConfig(key, defaultValue) {
         if (key) {
-            return this.runtimeConfig?.[key] ?? (this.config[key] ?? defaultValue);
+            return this.runtimeConfig[key] ?? (this.config[key] ?? defaultValue);
         }
         return { ...this.runtimeConfig, ...this.config };
     }
@@ -150,6 +285,43 @@ export class ViewController {
     setStaticConfig(config) {
         this.config = config || {};
     }
+    /**
+     * 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, info) {
+        devtools.emit('error', {
+            viewId: this.viewId,
+            path: info.path,
+            detail: { phase: info.phase, message: err instanceof Error ? err.message : String(err) },
+        });
+        let ctrl = this;
+        while (ctrl) {
+            const handler = ctrl.getConfig('onError');
+            const self = ctrl;
+            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) {
         for (const [key, value] of Object.entries(userConfig)) {
@@ -186,6 +358,11 @@ export class ViewController {
             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.start === 'function' && output.saoType !== 'View') {
+            this._rootTree = output;
+        }
         this.callingMethod = oldCallingMethod;
         return output;
     }
@@ -197,6 +374,11 @@ export class ViewController {
             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.start === 'function' && output.saoType !== 'View') {
+            this._rootTree = output;
+        }
         this.callingMethod = oldCallingMethod;
         return output;
     }
@@ -215,9 +397,111 @@ export class ViewController {
         this.initMode = 'create';
         return output;
     }
-    mount(root) {
+    // ─── 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. */
+    callHook(name) {
+        const fn = this.view?.[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 = null) {
+        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() {
+        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). */
+    acquireAssets() {
+        if (this._assetsLive)
+            return;
+        const styles = this.getConfig('styles');
+        const scripts = this.getConfig('scripts');
+        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). */
+    releaseAssets() {
+        if (!this._assetsLive)
+            return;
+        this._assetsLive = false;
+        const styles = this.getConfig('styles');
+        const scripts = this.getConfig('scripts');
+        AssetManager.release(this.path, styles, scripts);
+    }
+    /** Các Element gốc của instance (giữa markers của Wrapper) — để tag scoped style. */
+    getSubtreeRoots() {
+        const wrapper = this.mainElement ?? this.preloadElement;
+        const open = wrapper?.openTag ?? null;
+        const close = wrapper?.closeTag ?? null;
+        if (!open || !close || !open.parentNode)
+            return [];
+        const roots = [];
+        let cur = open.nextSibling;
+        while (cur && cur !== close) {
+            if (cur.nodeType === 1)
+                roots.push(cur);
+            cur = cur.nextSibling;
+        }
+        return roots;
     }
     /**
      * Start — activate reactive subscriptions throughout the element tree.
@@ -227,99 +511,334 @@ export class ViewController {
      * This ensures initial state values are set before subscriptions fire.
      */
     start() {
-        if (this._isDestroyed || !this._rootTree)
+        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
+    }
+    get lifecycleState() {
+        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() {
+        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() {
+        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() {
+        if (this.hasScheduledUpdate || this.pendingReactiveUpdates.size > 0) {
+            this.flushReactiveUpdates();
+            this.hasScheduledUpdate = false;
+        }
+        else
+            this.flushAfterDom();
     }
     /**
      * Stop — deactivate reactive subscriptions (for caching/deactivation).
      * DOM stays intact but reactive updates are paused.
      */
     stop() {
-        if (this._isDestroyed || !this._rootTree)
+        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() {
         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();
         // 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() {
+        this.isActive = true;
+    }
+    deactive() {
+        this.isActive = false;
     }
     // ─── Data Lifecycle ─────────────────────────────────────────
+    /**
+     * `this` context cho các hàm compiled config (updateVariableData dùng
+     * this.config.updateVariableItemData và this.data).
+     */
+    makeConfigThis() {
+        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() {
+        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) {
-        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();
+            }
+        }
     }
     /**
-     * Update single data item.
+     * 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, ...args) {
+        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 */
+    applyDataTrait(newData) {
+        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 — cùng contract với updateData (xem trên).
      */
     updateDataItem(key, value) {
+        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 ───────────────────────────────────────
     /**
@@ -331,7 +850,34 @@ export class ViewController {
      *   - Object with handler + params: { handler: fn, params: [...] }
      *   - Object with string handler (method name on view): { handler: 'handleClick' }
      */
-    addEventListener(element, event, handlers) {
+    /**
+     * 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.
+     */
+    wrapEventModifiers(fn, modifiers) {
+        const checkSelf = modifiers.includes('self');
+        const prevent = modifiers.includes('prevent');
+        const stop = modifiers.includes('stop');
+        if (!checkSelf && !prevent && !stop)
+            return fn;
+        return function (event) {
+            if (checkSelf && event.target !== event.currentTarget)
+                return;
+            if (prevent)
+                event.preventDefault();
+            if (stop)
+                event.stopPropagation();
+            return fn.call(this, event);
+        };
+    }
+    addEventListener(element, event, handlers, modifiers = []) {
+        // 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 = [];
+        const once = modifiers.includes('once');
         for (const h of handlers) {
             let fn;
             if (typeof h === 'function') {
@@ -379,8 +925,29 @@ export class ViewController {
             else {
                 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, event) {
+        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 ────────────────────────────────────
     /**
@@ -396,6 +963,15 @@ export class ViewController {
             requestAnimationFrame(() => this.flushReactiveUpdates());
         }
     }
+    /**
+     * 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() {
+        return this.pendingReactiveUpdates.size > 0;
+    }
     flushReactiveUpdates() {
         if (this._isDestroyed)
             return;
@@ -410,26 +986,53 @@ export class ViewController {
                 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() {
+        // 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, config, contentRenderFactory) {
-        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);
         this.sections.set(name, section);
+        SectionManager.add(section);
         return section;
     }
+    /** `this.yieldContent(name, default)` — synchronous resolve, used inside attribute/prop binding factories. */
+    yieldContent(name, defaultValue = null) {
+        return SectionManager.resolve(name, defaultValue);
+    }
+    /** Decode a raw SSR echo as RCDATA, preserving literal angle brackets. */
+    decodeTextContent(value) {
+        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, name, contentRenderFactory) {
         if (!id) {
-            id = `b-${name}`;
+            id = `block-${name}`;
         }
+        id = `${this.viewId}-${id}`;
         const existing = this.blocks.get(id);
         const initMode = this.initMode;
         if (existing) {
@@ -448,15 +1051,19 @@ export class ViewController {
         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.__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;
     }
     mountBlock(id = null, name, parent) {
@@ -471,7 +1078,7 @@ export class ViewController {
         return this.blockOutlet(id, name, parent);
     }
     yield(id, name, defaultValue = null, parentElement = null) {
-        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;
@@ -479,31 +1086,33 @@ export class ViewController {
         }
         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, defaultValue = null) {
-        return this.App.View?.yieldContent?.(name, defaultValue) ?? defaultValue;
-    }
     wrapper(factory) {
-        const callingMethod = this.callingMethod;
-        let key = callingMethod === 'prerender' ? 'preloadElement' : 'mainElement';
-        let wrapper = this[key];
-        if (!wrapper) {
+        const which = this.callingMethod === 'prerender' ? 'prerender' : 'render';
+        const key = which === 'prerender' ? 'preloadElement' : 'mainElement';
+        let wrapper = this.wrapperInstances[which];
+        if (!wrapper || wrapper.__destroyed__) {
             wrapper = new Wrapper({ ctx: this, initMode: this.initMode, parentElement: this.parentElement, childrenFactory: factory });
-            this[key] = wrapper;
+            this.wrapperInstances[which] = wrapper;
         }
         else {
             wrapper.setChildrenFactory(factory);
         }
+        this[key] = wrapper;
         return wrapper;
     }
     fragment(id = null, parentElement, childrenFactory) {
+        childrenFactory = this.scopeFactory(childrenFactory);
         if (!id) {
             id = `fr-${generateUUID(5)}`;
         }
-        const existing = this.elements.get(id);
-        if (existing instanceof Fragment) {
+        const existing = this.aliveFromRegistry(id, Fragment);
+        if (existing) {
             if (childrenFactory) {
                 existing.setChildrenFactory(childrenFactory);
             }
@@ -511,7 +1120,7 @@ export class ViewController {
         }
         const initMode = this.initMode;
         const fragment = new Fragment({ ctx: this, id, initMode, parentElement, childrenFactory });
-        this.elements.set(id, fragment);
+        this.registerElement(id, fragment);
         return fragment;
     }
     /**
@@ -519,11 +1128,13 @@ export class ViewController {
      * These methods are called by the compiled output for loops, conditionals, and other directives.
      */
     html(id = null, tagName, parentElement, config, childrenFactory) {
+        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) {
                 existing.setChildrenFactory(childrenFactory);
@@ -531,16 +1142,21 @@ export class ViewController {
             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, type, parentReactive, parentElement, stateKeys, childrenFactory) {
+        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;
@@ -552,17 +1168,18 @@ export class ViewController {
             parentReactive,
             parentElement,
             stateKeys,
-            childrenFactory
+            childrenFactory,
+            initMode: this.initMode,
         });
-        this.elements.set(id, reactive);
+        this.registerElement(id, reactive);
         return reactive;
     }
     output(id, parent, isEscapeHTML = true, stateKeys = [], contentFactory = () => '') {
         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;
@@ -574,20 +1191,95 @@ export class ViewController {
             stateKeys,
             isEscapeHTML,
             contentFactory,
+            initMode: this.initMode,
         });
-        this.elements.set(id, output);
+        this.registerElement(id, output);
         return output;
     }
+    /**
+     * 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) {
-        return document.createTextNode(text);
+        return new TextElement({ ctx: this, stateKeys: [], generateText: () => text });
     }
-    include(id = null, path = '', parentElement, stateKeys, dataFactory) {
-        if (!id) {
-            id = `cpn-${generateUUID(5)}`;
+    /**
+     * 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.
+     */
+    registerElement(id, el) {
+        this.elements.set(id, el);
+        this.elementKeys.set(el, id);
+        if (this.foreachRegistry) {
+            this.foreachRegistry.set(id, el);
+            this.elementRegistries.set(el, this.foreachRegistry);
         }
-        const existing = this.elements.get(id);
-        if (existing instanceof Component) {
+        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) {
+        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.
+     */
+    aliveFromRegistry(id, ctor) {
+        if (this._foreachSkipRegistry)
+            return null;
+        const existing = this.foreachRegistry ? this.foreachRegistry.get(id) : this.elements.get(id);
+        if (existing instanceof ctor && !existing.__destroyed__) {
+            return existing;
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    resolveIncludeId(id, kind, path) {
+        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(id = null, path = '', parentElement, stateKeys, dataFactory, listeners = {}) {
+        id = this.resolveIncludeId(id, 'include', path);
+        const existing = this.aliveFromRegistry(id, Component);
+        if (existing) {
             existing.setDataFactory(dataFactory);
+            existing.setListeners(listeners);
             if (stateKeys) {
                 existing.setStateKeys(stateKeys);
             }
@@ -595,23 +1287,24 @@ export class ViewController {
         }
         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 = null, path, parentElement, stateKeys, dataFactory) {
-        if (!id) {
-            id = `c-${generateUUID(5)}`;
-        }
-        const existing = this.elements.get(id);
-        if (existing instanceof Component) {
+    includeIf(id = null, path, parentElement, stateKeys, dataFactory, listeners = {}) {
+        id = this.resolveIncludeId(id, 'includeIf', path);
+        const existing = this.aliveFromRegistry(id, Component);
+        if (existing) {
             existing.setDataFactory(dataFactory);
+            existing.setListeners(listeners);
             if (stateKeys) {
                 existing.setStateKeys(stateKeys);
             }
@@ -619,22 +1312,22 @@ export class ViewController {
         }
         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, condition, path, parentElement, stateKeys, dataFactory) {
-        if (!id) {
-            id = `cpn-${generateUUID(5)}`;
-        }
-        const existing = this.elements.get(id);
-        if (existing instanceof Component) {
+    includeWhen(id, condition, path, parentElement, stateKeys, dataFactory, listeners = {}) {
+        id = this.resolveIncludeId(id, 'includeWhen', path);
+        const existing = this.aliveFromRegistry(id, Component);
+        if (existing) {
             existing.setDataFactory(dataFactory);
             existing.setCondition(condition);
             if (stateKeys) {
@@ -644,20 +1337,23 @@ export class ViewController {
         }
         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, data = {}) {
         this.superViewPath = path;
-        const superView = this.App.View?.view(path, data, true);
+        // Sync: render() trả superView ngay (xem ViewManager.resolveViewSync).
+        const superView = this.App.View?.resolveViewSync(path, data, true);
         if (superView) {
             this.setSuperView(superView?.__ctrl__);
             return superView;
@@ -691,48 +1387,118 @@ export class ViewController {
      * @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 → []).
      */
-    __foreach(list, callback) {
+    __children(content, parentElement) {
+        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(list, callback, keyFn, reconcile = false, scopeId) {
         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 = [];
+        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[key], key, index, loopCtx);
-                    if (output !== undefined && output !== null) {
-                        if (Array.isArray(output))
-                            result.push(...output);
-                        else
-                            result.push(output);
+            keys.forEach((key, index) => {
+                // Sparse arrays retain their actual index and loop count.
+                const loopIndex = Array.isArray(list) ? Number(key) : index;
+                const item = list[key];
+                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() : 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;
+                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?.();
                 });
-            }
-        }
-        catch (e) {
-            console.error(`[ViewController] @foreach error in "${this.path}":`, e);
         }
         finally {
             this.__resetLoopContext();
@@ -789,6 +1555,87 @@ export class ViewController {
         }
         return result;
     }
+    // ─── 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, styles) {
+        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) {
+        if (!Array.isArray(configs))
+            return '';
+        const classes = [];
+        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
     // ─── Config & App Access ────────────────────────────────────
     setApp(app) {
@@ -819,7 +1666,15 @@ export class ViewController {
         this.parent = parent;
     }
     addChild(child) {
-        this.children.push(child);
+        if (!this.children.includes(child))
+            this.children.push(child);
+    }
+    removeChild(child) {
+        const index = this.children.indexOf(child);
+        if (index >= 0)
+            this.children.splice(index, 1);
+        if (child.parent === this)
+            child.setParent(null);
     }
     /**
      * For nested views: set the chain of super views up to the root, so each view has a reference to its layout parents.