@saolabs/client 1.0.0 → 1.1.0

package/src/core/elements/Html.ts

@@ -1,26 +1,91 @@
-import { ESK, InitMode, InitModes } from "../contracts/common";
-import type { HtmlInterface, OneChildrenFactory, OneChildrenFactoryOutput, OneElementChildren, OneElementConfig } from "../contracts/ElementInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import type { ViewManagerInterface } from "../contracts/ViewManagerInterface";
-import { hasData } from "../hellpers/utils";
-import type { OneObjectType } from "../types/utils";
+import { reconcileChildren, reuseStaticText } from './reconcileChildren.js';
+import { ESK, InitMode, InitModes } from "../contracts/common.js";
+import type { DOMElement, HtmlInterface, SaoChildrenFactory, SaoChildrenFactoryOutput, SaoElement, SaoElementChildren, SaoElementConfig } from "../contracts/ElementInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import type { ViewManagerInterface } from "../contracts/ViewManagerInterface.js";
+import { mountElementList, hydrateElementList } from "../helpers/view.js";
+import type { SaoObjectType } from "../types/utils.js";
+import { TextElement } from "./TextElement.js";
+import SectionManager from "../services/SectionManager.js";
+import { runEnter, runLeave } from "../helpers/transition.js";
+
+/**
+ * Escape một chuỗi để dùng làm CSS class/id selector. Class hydrate dạng
+ * "{viewId}-{id}" có viewId là hex (uniqid) CÓ THỂ bắt đầu bằng chữ số, làm
+ * ".6a3a..." trở thành selector không hợp lệ → querySelector ném SyntaxError.
+ * Dùng CSS.escape khi có; fallback escape thủ công ký tự đầu là số + ký tự đặc biệt.
+ */
+function cssEscape(value: string): string {
+    const g: any = typeof globalThis !== 'undefined' ? globalThis : {};
+    if (g.CSS && typeof g.CSS.escape === 'function') {
+        return g.CSS.escape(value);
+    }
+    // Fallback tối thiểu: escape chữ số đầu (\3N ) và ký tự không phải [-_a-zA-Z0-9].
+    return value
+        .replace(/^[0-9]/, ch => `\\3${ch} `)
+        .replace(/[^a-zA-Z0-9_-]/g, ch => `\\${ch}`);
+}
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/**
+ * `document.createElement('svg')` ra HTMLUnknownElement — SVG dựng bằng CSR
+ * không vẽ gì. Phải dùng createElementNS.
+ *
+ * Chỉ cần nhận ra `<svg>`: mọi thứ bên trong kế thừa namespace từ cha, kể cả
+ * tag không liệt kê được hết (`filter`, cả họ `fe*`, `textPath`…). Danh sách
+ * tag SVG là thừa và luôn thiếu.
+ *
+ * `foreignObject` CẮT chuỗi kế thừa: con của nó là HTML thật (đó là toàn bộ lý
+ * do nó tồn tại), parser của trình duyệt cũng làm đúng như vậy khi đọc markup
+ * SSR — không cắt ở đây thì SSR và CSR ra hai cây khác nhau.
+ *
+ * Tên tag phải giữ đúng hoa/thường: createElementNS KHÔNG có bảng điều chỉnh
+ * như parser HTML, `'clippath'` ra SVGElement trơ. Compiler đã trả về đúng
+ * `clipPath` (xem Parser::SVG_TAG_ADJUST).
+ */
+function createDomElement(tagName: string, parentElement?: HtmlInterface | null): HTMLElement {
+    const parent = parentElement?.element;
+    const isSvg = tagName === 'svg'
+        || (parent?.namespaceURI === SVG_NS && parent.tagName !== 'foreignObject');
+
+    return isSvg
+        ? document.createElementNS(SVG_NS, tagName) as unknown as HTMLElement
+        : document.createElement(tagName);
+}
+
+/** SVG phân biệt hoa thường — hạ chữ thường sẽ hỏng `clipPath`, `feGaussianBlur`… */
+function domTagName(el: Element): string {
+    return el.namespaceURI === SVG_NS ? el.tagName : el.tagName.toLowerCase();
+}
 
 export class Html implements HtmlInterface {
-    oneType: OneObjectType = 'Html';
+    saoType: SaoObjectType = 'Html';
     public element: HTMLElement;
     public parent: HtmlInterface | null;
     private tagName: string;
-    private config: OneElementConfig;
+    private config: SaoElementConfig;
     private ctx: ViewControllerInterface | ViewManagerInterface;
-    private children: OneElementChildren = [];
+    private children: SaoElementChildren = [];
 
     public domChildren: Node[] = []; // For compatibility with HtmlInterface; Html itself doesn't have a single root element
-    private childrenFactory: OneChildrenFactory | null = null;
+    private childrenFactory: SaoChildrenFactory | null = null;
     private abortController: AbortController = new AbortController();
 
     /** All state subscriptions for reactive bindings — cleanup on destroy */
     private bindingUnsubscribes: (() => void)[] = [];
+    /** Invalidates deferred/stale binding callbacks after a config reconciliation. */
+    private bindingGeneration = 0;
+    private contentUnsubscribe: (() => void) | null = null;
+    /** DOM state owned by this Html config, used for exact cleanup before reuse. */
+    private managedAttributeNames = new Set<string>();
+    private managedClassNames = new Set<string>();
+    private managedStyleNames = new Set<string>();
+    private managedPropertyNames = new Set<string>();
+    /** Events actually registered through ViewController, independent of current config. */
+    private registeredEventNames = new Set<string>();
     public initMode: InitMode = InitModes.CREATE;
+    private adoptedSSR = false;
 
     constructor({
         ctx,
@@ -37,8 +102,8 @@ export class Html implements HtmlInterface {
         parentElement?: HtmlInterface | null,
         tagName?: string,
         element?: HTMLElement | null,
-        config?: OneElementConfig,
-        childrenFactory?: OneChildrenFactory | null,
+        config?: SaoElementConfig,
+        childrenFactory?: SaoChildrenFactory | null,
         initMode?: InitMode;
     }) {
 
@@ -48,28 +113,72 @@ export class Html implements HtmlInterface {
         this.config = config;
         this.tagName = tagName;
         this.initMode = initMode;
-        const shouldHydrate = config.hydrate && initMode === InitModes.HYDRATE;
-
-        const onlySync = (initMode === InitModes.HYDRATE && config.element instanceof HTMLElement) || element instanceof HTMLElement;
-        if (onlySync) {
-            this.element = element || config.element as HTMLElement;
-            this.tagName = this.element.tagName.toLowerCase();
-        } else if (shouldHydrate && config.selector) {
-            const found = document.querySelector(`${tagName}[${ESK.ID}="${id}"]`) as HTMLElement | null;
-            if (found instanceof HTMLElement) {
+
+        // ── Ưu tiên element trực tiếp (ViewManager rootElement / test) ─────────
+        // config.element hoặc tham số element cho phép caller truyền HTMLElement sẵn có
+        // mà không cần lookup DOM.
+        const directElement = element instanceof HTMLElement
+            ? element
+            : (config.element instanceof HTMLElement ? config.element : null);
+
+        // ── Class hydrate = "{viewId}-{id}" ────────────────────────────────────
+        // Blade emit `$__VIEW_ID__ . '-' . $id` cho MỌI element, nên CSR phải gắn
+        // đúng class đó. Trước đây nhánh create dùng id THÔ ('e1') → cùng một view
+        // render bởi server và bởi client ra hai DOM khác nhau, và mọi element CSR
+        // dùng chung vài chục tên class ('e1', 'e13'...) trên toàn tài liệu.
+        const viewId = (ctx as any).viewId ?? null;
+        const hydrateClass = id ? (viewId ? `${viewId}-${id}` : id) : null;
+
+        if (directElement) {
+            this.element = directElement;
+            this.tagName = domTagName(this.element);
+            this.adoptedSSR = initMode === InitModes.HYDRATE;
+        } else if (initMode === InitModes.HYDRATE) {
+            // ── SSR Hydration: claim server-rendered DOM node bằng class ID ──────
+            //
+            // Blade compiler emit class: $__VIEW_ID__ . '-{id}' (e.g. "v12345-af0882bc-0-1").
+            // Tham chiếu: COMPILER_CONTRACT.md §hydration, docs/FOREACH_RECONCILIATION_DESIGN.md
+            //
+            // Thuật toán (top-down):
+            //   1. Tìm trong parentElement.element trước (để tránh cross-view collision)
+            //   2. Fallback: document.querySelector nếu không có parentElement
+            //   3. Không tìm thấy → tạo element mới (partial hydration)
+            let found: HTMLElement | null = null;
+
+            if (hydrateClass) {
+                // viewId (server uniqid) là hex CÓ THỂ bắt đầu bằng chữ số → class
+                // "6a3a...-32a9c14a" làm selector ".6a3a..." KHÔNG hợp lệ
+                // (querySelector ném SyntaxError). CSS.escape() escape ký tự đầu.
+                const selector = `${tagName}.${cssEscape(hydrateClass)}`;
+                const searchScope: Element | null = parentElement?.element ?? null;
+                if (searchScope) {
+                    // CÓ parent → chỉ tìm trong đó. KHÔNG hạ xuống quét cả tài
+                    // liệu: element không nằm dưới parent của nó thì cái tìm
+                    // thấy ở nơi khác là của cây khác — claim vào rồi mount sẽ
+                    // BỨNG node đó khỏi chỗ đúng, hỏng cả hai cây, không một
+                    // tiếng động. Server không render vùng này thì đường đúng là
+                    // partial hydration: tạo element mới ở dưới.
+                    found = searchScope.querySelector(selector) as HTMLElement | null;
+                } else {
+                    // Không có parent để giới hạn (element cấp gốc) — chỉ khi ấy
+                    // quét cả tài liệu mới là cách duy nhất.
+                    found = document.querySelector(selector) as HTMLElement | null;
+                }
+            }
+
+            if (found) {
                 this.element = found;
-                this.tagName = found.tagName.toLowerCase();
+                this.tagName = domTagName(found);
+                this.adoptedSSR = true;
             } else {
-                this.element = document.createElement(tagName);
-                this.element.setAttribute(ESK.ID, id || '');
-                console.warn(`[Html] Selector "${config.selector}" not found, created new <${tagName}>.`);
+                // Partial hydration fallback: element không có trong SSR output
+                this.element = createDomElement(tagName, parentElement);
+                if (hydrateClass) this.element.classList.add(hydrateClass);
             }
         } else {
-            this.element = document.createElement(this.tagName);
-            this.element.setAttribute(ESK.ID, id || '');
-            if (shouldHydrate) {
-                console.warn(`[Html] No selector for hydration, created new <${tagName}>.`);
-            }
+            // ── CSR (create mode): tạo element mới ───────────────────────────────
+            this.element = createDomElement(this.tagName, parentElement);
+            if (hydrateClass) this.element.classList.add(hydrateClass);
         }
 
 
@@ -78,10 +187,29 @@ export class Html implements HtmlInterface {
         this.initialize();
     }
 
-    updateConfig(newConfig: Partial<OneElementConfig>): void {
-        if(hasData(newConfig)){
-            this.config = { ...this.config, ...newConfig };
-        }
+    updateConfig(newConfig: Partial<SaoElementConfig>): void {
+        if (this.__destroyed__) return;
+
+        // Reuse must behave like a fresh initialization without replacing the DOM
+        // node: remove every resource owned by the previous config first, then make
+        // the new managed sections authoritative. This prevents stale attrs,
+        // duplicate events, and state subscriptions retaining old closures.
+        this.removeEventListeners();
+        this.cleanupBindingResources();
+        this.clearManagedDomState(newConfig);
+
+        this.config = {
+            ...this.config,
+            ...newConfig,
+            attrs: newConfig.attrs,
+            props: newConfig.props,
+            events: newConfig.events,
+            classes: newConfig.classes,
+            styles: newConfig.styles,
+            bind: newConfig.bind,
+            content: newConfig.content,
+        };
+        this.initialize();
     }
 
     private initialize() {
@@ -91,47 +219,204 @@ export class Html implements HtmlInterface {
         this.initializeEvents();
     }
 
+    private isBindingCurrent(generation: number): boolean {
+        return !this.__destroyed__ && generation === this.bindingGeneration;
+    }
 
+    private cleanupBindingResources(renewAbortController: boolean = true): void {
+        this.bindingGeneration++;
+        this.contentUnsubscribe?.();
+        this.contentUnsubscribe = null;
+        this.abortController.abort();
+        if (renewAbortController) {
+            this.abortController = new AbortController();
+        }
 
-    private initializeAttributes() {
-        if (this.config.attrs) {
-            for (const [attrName, attrConfig] of Object.entries(this.config.attrs)) {
-                if (attrConfig.type === 'value') {
-                    this.element.setAttribute(attrName, attrConfig.value);
-                } else if (attrConfig.type === 'binding') {
-                    const value = attrConfig.factory ? attrConfig.factory() : '';
-                    if (value !== undefined && value !== null && value !== false) {
-                        this.element.setAttribute(attrName, String(value));
-                    } else {
-                        this.element.removeAttribute(attrName);
-                    }
+        for (const unsubscribe of this.bindingUnsubscribes) {
+            try {
+                unsubscribe();
+            } catch (error) {
+                console.error('[Html] Failed to unsubscribe a reactive binding:', error);
+            }
+        }
+        this.bindingUnsubscribes = [];
+    }
 
-                    // Reactive binding for attributes
-                    if (attrConfig.stateKeys?.length) {
-                        const unsubscribe = this.ctx.states.__.subscribe(
-                            attrConfig.stateKeys,
-                            () => {
-                                const newValue = attrConfig.factory ? attrConfig.factory() : '';
-                                if (newValue !== undefined && newValue !== null && newValue !== false) {
-                                    this.element.setAttribute(attrName, String(newValue));
-                                } else {
-                                    this.element.removeAttribute(attrName);
-                                }
-                            }
-                        );
-                        this.bindingUnsubscribes.push(unsubscribe);
-                    }
+    private clearManagedDomState(next: Partial<SaoElementConfig> = {}): void {
+        const attrs = new Set(Object.keys(next.attrs ?? {}).map(name => this.normalizeAttrName(name)));
+        const classes = new Set<string>();
+        if (Array.isArray(next.classes)) {
+            for (const item of next.classes) if (item && item.type !== 'dynamic' && item.value) classes.add(String(item.value));
+        } else {
+            for (const [name, item] of Object.entries(next.classes ?? {})) {
+                if (item.type === 'binding' || item.value) classes.add(name);
+            }
+        }
+        for (const attrName of this.managedAttributeNames) {
+            if (!attrs.has(attrName)) this.element.removeAttribute(attrName);
+        }
+        this.managedAttributeNames.clear();
+
+        for (const className of this.managedClassNames) {
+            if (!classes.has(className)) this.removeClass(className);
+        }
+        this.managedClassNames.clear();
+
+        for (const prop of this.managedStyleNames) {
+            if (!(prop in (next.styles ?? {}))) this.element.style.removeProperty(prop);
+        }
+        this.managedStyleNames.clear();
+
+        const removedProps = [...this.managedPropertyNames].filter(name => !(name in (next.props ?? {})));
+        const defaults = removedProps.length ? createDomElement(this.tagName, this.parent) as any : {};
+        const target = this.element as any;
+        for (const propName of removedProps) {
+            try {
+                if (propName in defaults) {
+                    target[propName] = defaults[propName];
+                } else {
+                    delete target[propName];
                 }
+            } catch {
+                // Some host properties are readonly. Removing an own property is
+                // still safe and avoids retaining user/config objects where possible.
+                try { delete target[propName]; } catch { /* no-op */ }
+            }
+        }
+        this.managedPropertyNames.clear();
+    }
+
+
+
+    /**
+     * Chuẩn hóa tên attr từ camelCase → kebab-case cho data-* và aria-* attrs.
+     *
+     * Compiler emit camelCase: "dataCount" → client phải set "data-count" trên DOM.
+     * Tham chiếu: COMPILER_CONTRACT.md §3 — camelCase attrs.
+     *
+     * @example normalizeAttrName('dataCount') === 'data-count'
+     * @example normalizeAttrName('ariaLabel') === 'aria-label'
+     * @example normalizeAttrName('id') === 'id'  (không đổi)
+     */
+    private normalizeAttrName(name: string): string {
+        if (/^data[A-Z]/.test(name)) {
+            return 'data-' + name[4].toLowerCase() + name.slice(5).replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+        }
+        if (/^aria[A-Z]/.test(name)) {
+            return 'aria-' + name[4].toLowerCase() + name.slice(5).replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+        }
+        return name;
+    }
+
+    /**
+     * Thiết lập two-way data binding (v-model-like) theo compiler pattern:
+     *
+     *   config.bind = { key: "<stateKey>" }  — own bucket, sibling of attrs/props/events.
+     *
+     * Hành vi:
+     *   1. Khởi tạo: set element.value = state hiện tại
+     *   2. input event → update state
+     *   3. state change → update element.value
+     *
+     * Tham chiếu: COMPILER_CONTRACT.md §5 — @bind directive.
+     */
+    private setupTwoWayBinding(stateKey: string): void {
+        const manager = this.ctx.states.__;
+        const el = this.element as HTMLInputElement;
+        const generation = this.bindingGeneration;
+        const isSelect = el.tagName === 'SELECT';
+        const isMultiple = isSelect && (el as unknown as HTMLSelectElement).multiple;
+        const isCheckbox = el.type === 'checkbox';
+        const isRadio = el.type === 'radio';
+        const isNumber = el.type === 'number' || el.type === 'range';
+
+        const readValue = (): any => {
+            if (isMultiple) return Array.from((el as unknown as HTMLSelectElement).selectedOptions).map(option => option.value);
+            if (isCheckbox) return el.checked;
+            if (isNumber) return Number.isNaN(el.valueAsNumber) ? el.value : el.valueAsNumber;
+            return el.value;
+        };
+        const commitInput = () => {
+            if (!this.isBindingCurrent(generation) || (isRadio && !el.checked)) return;
+            const setter = manager.setters[stateKey];
+            if (typeof setter === 'function') setter(readValue());
+            else manager.updateStateByKey(stateKey, readValue());
+        };
+        const applyState = (value: any) => {
+            if (!this.isBindingCurrent(generation) || this.composing) return;
+            if (isMultiple) {
+                const selected = new Set(Array.isArray(value) ? value.map(String) : []);
+                for (const option of (el as unknown as HTMLSelectElement).options) {
+                    const next = selected.has(option.value);
+                    if (option.selected !== next) option.selected = next;
+                }
+            } else if (isCheckbox) {
+                if (el.checked !== !!value) el.checked = !!value;
+            } else if (isRadio) {
+                const checked = value != null && String(value) === el.value;
+                if (el.checked !== checked) el.checked = checked;
+            } else {
+                const next = value == null ? '' : String(value);
+                if (el.value !== next) el.value = next; // preserve caret on no-op patches
+            }
+        };
+        const initial = manager.getStateByKey(stateKey);
+        // Adopt user edits made while SSR HTML was visible before JS arrived.
+        const editedSSR = !this.bindingInitialized && this.adoptedSSR && (isSelect
+            ? Array.from((el as unknown as HTMLSelectElement).options).some(option => option.selected !== option.defaultSelected)
+            : isCheckbox || isRadio ? el.checked !== el.defaultChecked
+            : el.value !== (el as unknown as HTMLTextAreaElement).defaultValue);
+        this.bindingInitialized = true;
+        if (editedSSR) commitInput();
+        else if (initial != null) {
+            if (isSelect) queueMicrotask(() => applyState(manager.getStateByKey(stateKey)));
+            else applyState(initial);
+        }
+        const signal = this.abortController.signal;
+        const inputHandler = (event: Event) => {
+            if (this.composing || (event as InputEvent).isComposing) return;
+            commitInput();
+        };
+        const eventType = isCheckbox || isRadio || isSelect ? 'change' : 'input';
+        this.element.addEventListener(eventType, inputHandler, { signal });
+        if (!isSelect && !isCheckbox && !isRadio) {
+            this.element.addEventListener('compositionstart', () => { this.composing = true; }, { signal });
+            this.element.addEventListener('compositionend', () => {
+                this.composing = false;
+                commitInput();
+            }, { signal });
+        }
+        this.bindingUnsubscribes.push(manager.subscribe([stateKey], () => applyState(manager.getStateByKey(stateKey))));
+    }
+
+    private initializeAttributes() {
+        const attrs = this.config.attrs;
+
+        if (attrs) {
+            for (const [attrName, attrConfig] of Object.entries(attrs)) {
+                this._applyAttr(attrName, attrConfig);
             }
         }
+
+        // @bind/@val — own top-level config bucket (sibling of attrs/props/events,
+        // same shape/spirit as events — see ElementInterface.ts). Applied AFTER
+        // attrs: setupTwoWayBinding needs el.type ('checkbox', 'radio', 'number'...)
+        // already in place.
+        if (this.config.bind?.key) {
+            this.setupTwoWayBinding(this.config.bind.key);
+        }
+
+        // props độc lập với attrs/bind — element chỉ có props vẫn phải chạy
         if (this.config.props) {
             for (const [propName, propConfig] of Object.entries(this.config.props)) {
-                if (propConfig.type === 'value') {
-                    (this.element as any)[propName] = propConfig.value;
+                this.managedPropertyNames.add(propName);
+                if (propConfig.type === 'static' || propConfig.type === 'value') {
+                    if ((this.element as any)[propName] !== propConfig.value) (this.element as any)[propName] = propConfig.value;
                 } else if (propConfig.type === 'binding') {
+                    const generation = this.bindingGeneration;
                     const value = propConfig.factory ? propConfig.factory() : '';
                     if (value !== undefined && value !== null && value !== false) {
-                        (this.element as any)[propName] = value;
+                        if ((this.element as any)[propName] !== value) (this.element as any)[propName] = value;
                     } else {
                         (this.element as any)[propName] = false;
                         delete (this.element as any)[propName];
@@ -142,9 +427,10 @@ export class Html implements HtmlInterface {
                         const unsubscribe = this.ctx.states.__.subscribe(
                             propConfig.stateKeys,
                             () => {
+                                if (!this.isBindingCurrent(generation)) return;
                                 const newValue = propConfig.factory ? propConfig.factory() : '';
                                 if (newValue !== undefined && newValue !== null && newValue !== false) {
-                                    (this.element as any)[propName] = newValue;
+                                    if ((this.element as any)[propName] !== newValue) (this.element as any)[propName] = newValue;
                                 } else {
                                     (this.element as any)[propName] = false;
                                     delete (this.element as any)[propName];
@@ -158,30 +444,117 @@ export class Html implements HtmlInterface {
         }
     }
 
+    /**
+     * Apply một attr vào element, bao gồm:
+     *   - Chuẩn hóa tên (camelCase → kebab-case cho data-* / aria-*)
+     *   - Xử lý reactive binding
+     */
+    private _applyAttr(attrName: string, attrConfig: any): void {
+        // FIX(Phase4): chuẩn hóa tên — dataCount → data-count
+        const normalizedName = this.normalizeAttrName(attrName);
+        this.managedAttributeNames.add(normalizedName);
+
+        // FIX(baseline#1): contract chuẩn là 'static' (compiler emit); 'value' giữ làm legacy alias
+        if (attrConfig.type === 'static' || attrConfig.type === 'value') {
+            if (attrConfig.value !== undefined && attrConfig.value !== null && attrConfig.value !== false) {
+                if (this.element.getAttribute(normalizedName) !== String(attrConfig.value)) this.element.setAttribute(normalizedName, String(attrConfig.value));
+            } else {
+                this.element.removeAttribute(normalizedName);
+            }
+        } else if (attrConfig.type === 'binding') {
+            const generation = this.bindingGeneration;
+            const applyValue = () => {
+                const newValue = attrConfig.factory ? attrConfig.factory() : '';
+                if (newValue !== undefined && newValue !== null && newValue !== false) {
+                    if (this.element.getAttribute(normalizedName) !== String(newValue)) this.element.setAttribute(normalizedName, String(newValue));
+                } else {
+                    this.element.removeAttribute(normalizedName);
+                }
+            };
+            applyValue();
+
+            if (attrConfig.stateKeys?.length) {
+                const unsubscribe = this.ctx.states.__.subscribe(
+                    attrConfig.stateKeys,
+                    () => { if (this.isBindingCurrent(generation)) applyValue(); }
+                );
+                this.bindingUnsubscribes.push(unsubscribe);
+            }
+            // `@yield(name, ...)` — no static stateKeys (the section it resolves to is
+            // only known at runtime); subscribe to SectionManager by name instead, fires
+            // both when a different section becomes active and when its value changes.
+            if (attrConfig.yieldName) {
+                const unsubscribe = SectionManager.subscribe(
+                    attrConfig.yieldName,
+                    () => { if (this.isBindingCurrent(generation)) applyValue(); }
+                );
+                this.bindingUnsubscribes.push(unsubscribe);
+            }
+        }
+    }
+
     private initializeClasses(): void {
         if (!this.config.classes) return;
 
         // New simplified format: classes: [{ type, value, factory?, stateKeys? }]
         if (Array.isArray(this.config.classes)) {
             for (const classConfig of this.config.classes) {
-                if (!classConfig || !classConfig.value) continue;
+                if (!classConfig) continue;
+
+                // `class="language-{{ lang }}"` — factory trả về TÊN class chứ không
+                // phải boolean, nên không có `value` tĩnh để bật/tắt. Phải nhớ lại tên
+                // đã gắn để gỡ đúng chúng khi state đổi ('language-php' → 'language-js');
+                // tên còn lại trên element có thể do nơi khác quản lý.
+                if (classConfig.type === 'dynamic') {
+                    const generation = this.bindingGeneration;
+                    let applied: string[] = [];
+                    const applyDynamic = () => {
+                        const next = String(classConfig.factory ? classConfig.factory() : '')
+                            .split(/\s+/).filter(Boolean);
+                        for (const prev of applied) {
+                            if (next.indexOf(prev) === -1) {
+                                this.removeClass(prev);
+                                this.managedClassNames.delete(prev);
+                            }
+                        }
+                        for (const name of next) {
+                            this.addClass(name);
+                            this.managedClassNames.add(name);
+                        }
+                        applied = next;
+                    };
+                    applyDynamic();
+                    if (classConfig.stateKeys?.length) {
+                        const unsubscribe = this.ctx.states.__.subscribe(
+                            classConfig.stateKeys,
+                            () => { if (this.isBindingCurrent(generation)) applyDynamic(); }
+                        );
+                        this.bindingUnsubscribes.push(unsubscribe);
+                    }
+                    continue;
+                }
+
+                if (!classConfig.value) continue;
                 const className = classConfig.value;
+                this.managedClassNames.add(className);
 
                 if (classConfig.type === 'static') {
-                    this.element.classList.add(className);
+                    this.addClass(className);
                     continue;
                 }
 
                 if (classConfig.type === 'binding') {
+                    const generation = this.bindingGeneration;
                     const initialValue = classConfig.factory ? classConfig.factory() : false;
-                    this.element.classList.toggle(className, !!initialValue);
+                    this.toggleClass(className, !!initialValue);
 
                     if (classConfig.stateKeys?.length) {
                         const unsubscribe = this.ctx.states.__.subscribe(
                             classConfig.stateKeys,
                             () => {
+                                if (!this.isBindingCurrent(generation)) return;
                                 const newValue = classConfig.factory ? classConfig.factory() : false;
-                                this.element.classList.toggle(className, !!newValue);
+                                this.toggleClass(className, !!newValue);
                             }
                         );
                         this.bindingUnsubscribes.push(unsubscribe);
@@ -192,22 +565,25 @@ export class Html implements HtmlInterface {
         }
 
         for (const [className, classConfig] of Object.entries(this.config.classes)) {
+            this.managedClassNames.add(className);
             if (classConfig.type === 'static') {
                 if (classConfig.value) {
-                    this.element.classList.add(className);
+                    this.addClass(className);
                 }
             } else if (classConfig.type === 'binding') {
+                const generation = this.bindingGeneration;
                 // Initial value
                 const initialValue = classConfig.factory ? classConfig.factory() : !!classConfig.value;
-                this.element.classList.toggle(className, !!initialValue);
+                this.toggleClass(className, !!initialValue);
 
                 // Subscribe for reactive updates
                 if (classConfig.stateKeys?.length) {
                     const unsubscribe = this.ctx.states.__.subscribe(
                         classConfig.stateKeys,
                         () => {
+                            if (!this.isBindingCurrent(generation)) return;
                             const newValue = classConfig.factory ? classConfig.factory() : false;
-                            this.element.classList.toggle(className, !!newValue);
+                            this.toggleClass(className, !!newValue);
                         }
                     );
                     this.bindingUnsubscribes.push(unsubscribe);
@@ -216,24 +592,68 @@ export class Html implements HtmlInterface {
         }
     }
 
+    private addClass(className: string): void {
+        if (!className) return;
+        if (className.includes(' ')) {
+            const tokens = className.trim().split(/\s+/);
+            for (let i = 0; i < tokens.length; i++) {
+                if (tokens[i]) if (!this.element.classList.contains(tokens[i])) this.element.classList.add(tokens[i]);
+            }
+            return;
+        }
+        if (!this.element.classList.contains(className)) this.element.classList.add(className);
+    }
+
+    private removeClass(className: string): void {
+        if (!className) return;
+        if (className.includes(' ')) {
+            const tokens = className.trim().split(/\s+/);
+            for (let i = 0; i < tokens.length; i++) {
+                if (tokens[i]) if (this.element.classList.contains(tokens[i])) this.element.classList.remove(tokens[i]);
+            }
+            return;
+        }
+        if (this.element.classList.contains(className)) this.element.classList.remove(className);
+    }
+
+    private toggleClass(className: string, force: boolean): void {
+        if (!className) return;
+        if (className.includes(' ')) {
+            const tokens = className.trim().split(/\s+/);
+            for (let i = 0; i < tokens.length; i++) {
+                if (tokens[i]) if (this.element.classList.contains(tokens[i]) !== force) this.element.classList.toggle(tokens[i], force);
+            }
+            return;
+        }
+        if (this.element.classList.contains(className) !== force) this.element.classList.toggle(className, force);
+    }
+
+    private applyStyle(prop: string, value: any): void {
+        const text = String(value ?? '');
+        if (this.element.style.getPropertyValue(prop) !== text) this.element.style.setProperty(prop, text);
+    }
+
     private initializeStyles(): void {
         if (!this.config.styles) return;
 
         for (const [prop, styleConfig] of Object.entries(this.config.styles)) {
-            if (styleConfig.type === 'value') {
-                this.element.style.setProperty(prop, styleConfig.value ?? '');
+            this.managedStyleNames.add(prop);
+            if (styleConfig.type === 'static' || styleConfig.type === 'value') {
+                this.applyStyle(prop, styleConfig.value ?? '');
             } else if (styleConfig.type === 'binding') {
+                const generation = this.bindingGeneration;
                 // Initial value
                 const initialValue = styleConfig.factory ? styleConfig.factory() : (styleConfig.value ?? '');
-                this.element.style.setProperty(prop, initialValue);
+                this.applyStyle(prop, initialValue);
 
                 // Subscribe for reactive updates
                 if (styleConfig.stateKeys?.length) {
                     const unsubscribe = this.ctx.states.__.subscribe(
                         styleConfig.stateKeys,
                         () => {
+                            if (!this.isBindingCurrent(generation)) return;
                             const newValue = styleConfig.factory ? styleConfig.factory() : '';
-                            this.element.style.setProperty(prop, newValue);
+                            this.applyStyle(prop, newValue);
                         }
                     );
                     this.bindingUnsubscribes.push(unsubscribe);
@@ -243,13 +663,32 @@ export class Html implements HtmlInterface {
     }
 
     private initializeEvents() {
+        this.addEventListeners();
+    }
+
+    addEventListeners() {
         if (this.config.events) {
             for (const [eventName, handlers] of Object.entries(this.config.events)) {
-                this.ctx.addEventListener(this.element, eventName, handlers);
+                this.ctx.addEventListener(
+                    this.element, eventName, handlers,
+                    this.config.eventModifiers?.[eventName],
+                );
+                this.registeredEventNames.add(eventName);
             }
         }
     }
 
+    removeEventListeners() {
+        for (const eventName of this.registeredEventNames) {
+            try {
+                this.ctx.removeEventListener(this.element, eventName);
+            } catch (error) {
+                console.error(`[Html] Failed to remove "${eventName}" listener:`, error);
+            }
+        }
+        this.registeredEventNames.clear();
+    }
+
     setParentElement(parent: HtmlInterface | null): void {
         this.parent = parent;
     }
@@ -257,7 +696,7 @@ export class Html implements HtmlInterface {
     setParent(parent: HtmlInterface | null): void {
         this.parent = parent;
     }
-    setChildrenFactory(factory: OneChildrenFactory): void {
+    setChildrenFactory(factory: SaoChildrenFactory): void {
         this.childrenFactory = factory;
     }
 
@@ -265,46 +704,137 @@ export class Html implements HtmlInterface {
         return ['input', 'img', 'br', 'hr', 'meta', 'link'].includes(this.tagName.toLowerCase());
     }
 
+    getElement(): HTMLElement {
+        return this.element;
+    }
+
+    renderChildren(): SaoElementChildren {
+        const children = this.childrenFactory ? this.childrenFactory(this) : [];
+        this.children = [];
+        this.children = children
+            .filter((child): child is NonNullable<typeof child> => child !== null && child !== undefined)
+            .map((child) => {
+                if (typeof child === 'string' || typeof child === 'number') {
+                    return new TextElement({ ctx: this.ctx as ViewControllerInterface, parent: this.parent, stateKeys: [], generateText: () => String(child) });
+                }
+                return child;
+            });
+        return this.children;
+    }
+
+    private contentRendered = false;
+    private bindingInitialized = false;
+    private composing = false;
+    private isStarted = false;
+
     render(): HTMLElement {
+        const previous = this.children;
         if (this.isSingleElement()) {
             return this.element;
         }
-        let children: OneChildrenFactoryOutput = [];
+        if (this.config.content) {
+            this.renderTextContent();
+            return this.element;
+        }
+        let children: SaoElementChildren = [];
         if (this.childrenFactory) {
-            // Compiled output uses (parentElement) => [...] — pass `this` as parentElement
-            children = this.childrenFactory(this);
+            children = this.renderChildren();
         }
-        if (children && children.length > 0) {
-            children.forEach(child => {
-                if (typeof child === 'string' || typeof child === 'number') {
-                    const textNode = document.createTextNode(String(child));
-                    this.element.appendChild(textNode);
-                    this.children.push(textNode);
-                } else if (child && typeof child === 'object') {
-                    if ('element' in child) {
-                        // HtmlInterface, TextInterface
-                        this.element.appendChild(child.element);
-                        this.children.push(child);
-                        child.render();
-                    } else if ('openTag' in child && 'closeTag' in child) {
-                        // Output, Reactive, Fragment, BlockOutlet — they self-append markers
-                        if ('parent' in child) {
-                            (child as any).parent = this;
-                        }
-                        if ('parentElement' in child) {
-                            (child as any).parentElement = this;
-                        }
-                        this.children.push(child);
-                        child.render();
-                    }
-                }
-            });
+        children = this.children = reuseStaticText(previous, children) as SaoElementChildren;
+
+        if (this.initMode === InitModes.HYDRATE) {
+            // ── Hydrate mode: DOM đã có từ server ────────────────────────
+            // renderChildren() đã tạo JS objects (Html claim DOM, Output claim markers).
+            // hydrateElementList gọi render() đệ quy để children cũng claim DOM,
+            // nhưng KHÔNG appendChild — giữ nguyên server-rendered DOM.
+            if (children && children.length > 0) {
+                hydrateElementList(this, children);
+            }
+            this.initMode = InitModes.CREATE;
+            return this.element;
         }
+
+        reconcileChildren(this.element, previous, children);
+        // Drop unmanaged nodes left by previous renders, retaining marker ranges.
+        const keep = new Set<Node>();
+        for (const child of children as any[]) {
+            const first: Node | undefined = child.element ?? child.openTag;
+            const last: Node | undefined = child.element ?? child.closeTag;
+            let current = first;
+            while (current) {
+                keep.add(current);
+                if (current === last) break;
+                current = current.nextSibling ?? undefined;
+            }
+        }
+        for (const node of Array.from(this.element.childNodes)) if (!keep.has(node)) node.remove();
+        if (this.isStarted) for (const child of children as any[]) child.start?.();
+        this.maybeRunEnter();
         return this.element;
     }
 
+    private renderTextContent(): void {
+        this.contentUnsubscribe?.();
+        this.contentUnsubscribe = null;
+        const content = this.config.content!;
+        const isTextarea = this.tagName.toLowerCase() === 'textarea';
+        const generation = this.bindingGeneration;
+        const apply = () => {
+            if (!this.isBindingCurrent(generation)) return;
+            const value = String(content.factory() ?? '');
+            if (isTextarea) {
+                const textarea = this.element as HTMLTextAreaElement;
+                // @bind owns the live value when both forms are declared.
+                if (!this.config.bind && textarea.value !== value) textarea.value = value;
+            } else if (this.element.textContent !== value) {
+                this.element.textContent = value;
+            }
+        };
+        if (this.contentRendered) apply();
+        else if (!this.adoptedSSR) {
+            const value = String(content.factory() ?? '');
+            if (isTextarea) {
+                const textarea = this.element as HTMLTextAreaElement;
+                // Match HTML parsing: one initial LF after <textarea> is ignored.
+                textarea.defaultValue = value.replace(/^\n/, '');
+                if (!this.config.bind) textarea.value = textarea.defaultValue;
+            } else {
+                this.element.textContent = value;
+            }
+        }
+        this.contentRendered = true;
+        // Hydration adopts SSR content, including input typed before JS loaded.
+        // Future state changes patch the property, preserving the node itself.
+        if (content.stateKeys?.length && !(isTextarea && this.config.bind)) {
+            this.contentUnsubscribe = this.ctx.states.__.subscribe(content.stateKeys, apply);
+        }
+    }
+
+    /** Đã chạy enter rồi — re-render không được chạy lại. */
+    private _entered = false;
+
+    /**
+     * Enter chạy MỘT lần, khi element vừa được tạo và đã nằm trong DOM.
+     * Bỏ qua ở HYDRATE: DOM đó do server render, animate lại là nháy vô cớ
+     * (tương đương `appear = false` mặc định của Vue).
+     */
+    private maybeRunEnter(): void {
+        if (this._entered) return;
+        const name = this.config.transition?.name;
+        if (!name) return;
+        if (this.initMode === InitModes.HYDRATE) { this._entered = true; return; }
+        if (!this.element.isConnected) return;   // caller chưa chèn — thử lại lần render sau
+        this._entered = true;
+        void runEnter(this.element, name);
+    }
+
+    appendElement(element: HTMLElement | Comment | Text) {
+        this.element.appendChild(element);
+    }
+
     /** Start reactive bindings + children (Phase 2 lifecycle) */
     start(): void {
+        this.isStarted = true;
         for (const child of this.children) {
             if ('start' in child && typeof (child as any).start === 'function') {
                 (child as any).start();
@@ -314,6 +844,7 @@ export class Html implements HtmlInterface {
 
     /** Stop reactive bindings + children */
     stop(): void {
+        this.isStarted = false;
         for (const child of this.children) {
             if ('stop' in child && typeof (child as any).stop === 'function') {
                 (child as any).stop();
@@ -321,22 +852,70 @@ export class Html implements HtmlInterface {
         }
     }
 
+
+
+    clearHTML(): void {
+        this.element.innerHTML = '';
+    }
+
     remove() {
         this.element.remove();
     }
 
-    destroy() {
-        // Abort all registered event listeners
-        this.abortController.abort();
-        this.abortController = new AbortController();
+    /** Registry guard — element đã destroy không được reuse (xem RUNTIME_CONTRACT.md §2) */
+    public __destroyed__: boolean = false;
 
-        // Cleanup reactive binding subscriptions
-        for (const unsub of this.bindingUnsubscribes) {
-            unsub();
+    destroy() {
+        if (this.__destroyed__) return;
+        this.__destroyed__ = true;
+        this.ctx.releaseElement?.(this);
+
+        this.removeEventListeners();
+
+        // Abort @bind listeners and unsubscribe every reactive attr/prop/class/style.
+        this.cleanupBindingResources(false);
+
+        const transitionName = this.config.transition?.name;
+        if (transitionName && this.element.isConnected) {
+            // HOÃN teardown cây con: destroy() của child Html gỡ luôn DOM của nó,
+            // nên dọn ngay sẽ làm element bay ra trong trạng thái RỖNG. Element
+            // đã inert (listener gỡ, binding huỷ) nên giữ lại chỉ là phần nhìn.
+            // runLeave() tự gỡ node khi xong — không remove() ở đây.
+            //
+            // NHƯNG phải nhả id của CẢ CÂY CON khỏi registry NGAY. Một element
+            // đang leave là element đã chết về mặt logic; nếu id của nó còn
+            // trong `ctx.elements` thì pass render kế tiếp sẽ `aliveFromRegistry`
+            // trúng nó (chưa `__destroyed__` vì teardown bị hoãn) và tái dùng —
+            // Component thì `_childMounted` vẫn true nên `mountChild()` return
+            // ngay ⇒ vùng @include/@if của hàng mới RỖNG. Đây đúng là lớp lỗi
+            // §2.10, quay lại qua đường transition.
+            this.releaseSubtreeFromRegistry();
+            void runLeave(this.element, transitionName).then(() => this.teardownSubtree());
+            return;
         }
-        this.bindingUnsubscribes = [];
 
-        // Destroy children recursively
+        this.teardownSubtree();
+        // Gỡ element khỏi DOM — destroy là vĩnh viễn
+        this.element.remove();
+    }
+
+    /**
+     * Nhả id của element này và toàn bộ cây con khỏi `ctx.elements`, KHÔNG
+     * destroy. Dùng khi leave transition giữ DOM lại: registry phải sạch ngay
+     * để pass sau tạo element mới thay vì tái dùng xác sắp chết.
+     */
+    private releaseSubtreeFromRegistry(): void {
+        const release = (node: any): void => {
+            if (!node || typeof node !== 'object') return;
+            this.ctx.releaseElement?.(node);
+            const kids = node.children;
+            if (Array.isArray(kids)) for (const k of kids) release(k);
+        };
+        for (const child of this.children) release(child);
+    }
+
+    /** Destroy children + dọn nội dung. Tách riêng để leave hoãn được. */
+    private teardownSubtree(): void {
         this.children.forEach(child => {
             if ('destroy' in child && typeof child.destroy === 'function') {
                 child.destroy();
@@ -348,10 +927,10 @@ export class Html implements HtmlInterface {
         }
     }
 
-    get isOneElement(): boolean {
+    get isSaoElement(): boolean {
         return true;
     }
-    set isOneElement(value: boolean) {
+    set isSaoElement(value: boolean) {
         // No-op setter to satisfy the Interface; this property is always true for Html elements
     }