@saolabs/client 1.0.0 → 1.0.2

package/src/core/elements/Block.ts

@@ -1,12 +1,12 @@
-import type { BlockInterface, BlockRenderFactory } from "../contracts/BlockInterface";
-import { InitMode } from "../contracts/common";
-import type { FragmentInterface, HtmlInterface } from "../contracts/ElementInterface";
-import type { ReactiveInterface } from "../contracts/ReactiveInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { generateUUID } from "../hellpers/utils";
-import markerRegistry from "../services/MarkerRegistry";
-import type { OneObjectType } from "../types/utils";
-import { Fragment } from "./Fragment";
+import type { BlockInterface, BlockRenderFactory } from "../contracts/BlockInterface.js";
+import { InitMode, InitModes } from "../contracts/common.js";
+import type { FragmentInterface, HtmlInterface } from "../contracts/ElementInterface.js";
+import type { ReactiveInterface } from "../contracts/ReactiveInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import type { SaoObjectType } from "../types/utils.js";
+import { Fragment } from "./Fragment.js";
 /**
  * Block — a named mounting slot used in layout views.
  * 
@@ -26,23 +26,24 @@ import { Fragment } from "./Fragment";
  *   4. Browser back → BlockManager restores cached content without re-render
  */
 export class Block implements BlockInterface {
-    oneType: OneObjectType = 'Block';
+    saoType: SaoObjectType = 'Block';
     id: string;
     name: string;
     ctx: ViewControllerInterface;
     viewId: string | null = null;
+    /** Key trả về bởi markerRegistry.register — destroy() dùng để gỡ lại */
+    private markerKey: string | null = null;
     fragment: FragmentInterface | null = null;
     contentRenderFactory: BlockRenderFactory | null = null;
     openTag: Comment;
     closeTag: Comment;
-
     domChildren: Node[] = [];
     initMode?: InitMode | undefined;
     parentElement: HtmlInterface | null = null;
 
     public readonly isOneBlock = true;
-    public readonly isOneElement = false;
-    
+    public readonly isSaoElement = false;
+
     constructor({
         ctx,
         name,
@@ -58,15 +59,27 @@ export class Block implements BlockInterface {
         id?: string | null;
         initMode?: InitMode;
     }) {
-        this.id = `${this.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+        this.id = id ?? generateUUID(10); // Unique ID for debugging
         this.ctx = ctx;
         this.name = name;
         this.viewId = viewId ?? ctx.viewId; // Associate block with current viewId
         this.initMode = initMode;
         this.contentRenderFactory = contentRenderFactory || ((parentElement: HtmlInterface) => []);
-        markerRegistry.register('block', this.id, { name, viewId }); // Register block in marker registry
-        this.openTag = markerRegistry.createMarkerStart('block', this.id);
-        this.closeTag = markerRegistry.createMarkerEnd('block', this.id);
+        // Hydrate: claim cặp marker server qua index O(1) của MarkerRegistry.
+        // (Bản cũ dùng chung một TreeWalker không reset nên chỉ block ĐẦU TIÊN
+        // claim được, các block sau lặng lẽ tạo marker mới.)
+        const claimed = (this.initMode === InitModes.HYDRATE)
+            ? markerRegistry.claim('block', this.id)
+            : null;
+
+        if (claimed) {
+            this.openTag = claimed.open;
+            this.closeTag = claimed.close;
+        } else {
+            this.openTag = markerRegistry.createMarkerStart('block', this.id);
+            this.closeTag = markerRegistry.createMarkerEnd('block', this.id);
+            this.markerKey = markerRegistry.register('block', this.id, { name, viewId }); // Register block in marker registry
+        }
 
     }
 
@@ -90,7 +103,7 @@ export class Block implements BlockInterface {
     }
 
     mount(mountCtx: ViewControllerInterface, parentElement: HtmlInterface): any {
-        if(this.fragment) {
+        if (this.fragment) {
             this.fragment.parent = parentElement;
             this.fragment.render();
         }
@@ -99,14 +112,23 @@ export class Block implements BlockInterface {
         // Unmount logic (e.g. hide or remove DOM nodes, stop reactions)
     }
     destroy(): void {
-        // Cleanup logic (e.g. remove DOM nodes, clear caches)
+        // MarkerRegistry là singleton toàn cục — không gỡ thì record sống qua navigate.
+        if (this.markerKey) {
+            markerRegistry.remove(this.markerKey);
+            this.markerKey = null;
+        }
+        // openTag/closeTag nay NẰM TRONG DOM (BlockManager.mountBlockIntoOutlet chèn
+        // chúng quanh content). Bỏ lại comment mồ côi thì lần hydrate sau
+        // markerRegistry.claim('block', id) có thể bắt trúng cặp cũ và claim nhầm vùng.
+        this.openTag.remove();
+        this.closeTag.remove();
     }
     update(): void {
         // Update logic (e.g. re-render content on state change)
     }
 
-     /** Set the block's parent element (used for mounting) */
-     setParentElement(parentElement: HtmlInterface | null): void {
+    /** Set the block's parent element (used for mounting) */
+    setParentElement(parentElement: HtmlInterface | null): void {
         this.parentElement = parentElement;
     }
 

package/src/core/elements/BlockOutlet.ts

@@ -1,13 +1,13 @@
-import type { BlockOutletInterface } from "../contracts/BlockInterface";
-import { InitMode } from "../contracts/common";
-import type { HtmlInterface } from "../contracts/ElementInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { generateUUID } from "../hellpers/utils";
-import markerRegistry  from "../services/MarkerRegistry";
-import type { OneObjectType } from "../types/utils";
+import type { BlockOutletInterface } from "../contracts/BlockInterface.js";
+import { InitMode, InitModes } from "../contracts/common.js";
+import type { HtmlInterface } from "../contracts/ElementInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import type { SaoObjectType } from "../types/utils.js";
 
 export class BlockOutlet implements BlockOutletInterface {
-    oneType: OneObjectType = 'BlockOutlet';
+    saoType: SaoObjectType = 'BlockOutlet';
     id: string;
     name: string;
     openTag: Comment;
@@ -15,38 +15,78 @@ export class BlockOutlet implements BlockOutletInterface {
     parent: HtmlInterface | null = null;
     parentElement: HtmlInterface | null = null;
     ctx: ViewControllerInterface;
-    initMode: InitMode = 'create';
-    constructor({ ctx, parentElement = null, name, id = null, initMode = 'create' }: { ctx: ViewControllerInterface, parentElement?: HtmlInterface | null, name: string, id?: string | null, initMode?: InitMode }) {
-        this.id = `${ctx.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+    initMode: InitMode = InitModes.CREATE;
+    constructor({ ctx, parentElement = null, name, id = null, initMode = InitModes.CREATE }: { ctx: ViewControllerInterface, parentElement?: HtmlInterface | null, name: string, id?: string | null, initMode?: InitMode }) {
+        this.id = id ?? generateUUID(10); // Unique ID for debugging
         this.ctx = ctx;
         this.name = name;
         this.parent = parentElement;
         this.parentElement = parentElement;
         this.initMode = initMode;
 
-        markerRegistry.register('blockoutlet', this.id, { name, viewId: ctx.viewId }); // Register this outlet in the MarkerRegistry
+        if (this.initMode === InitModes.HYDRATE) {
+            // Claim cặp marker server <!--s:bo:{id}-s--> ... <!--s:bo:{id}-e-->
+            const claimed = this.claimSSRMarkers();
+            if (claimed) {
+                this.openTag = claimed.open;
+                this.closeTag = claimed.close;
+            } else {
+                this.openTag = markerRegistry.createMarkerStart('blockoutlet', this.id);
+                this.closeTag = markerRegistry.createMarkerEnd('blockoutlet', this.id);
+                this.markerKey = markerRegistry.register('blockoutlet', this.id, { name, viewId: ctx.viewId });
+            }
+        }
+        else {
+            this.openTag = markerRegistry.createMarkerStart('blockoutlet', this.id);
+            this.closeTag = markerRegistry.createMarkerEnd('blockoutlet', this.id);
+            this.markerKey = markerRegistry.register('blockoutlet', this.id, { name, viewId: ctx.viewId }); // Register this outlet in the MarkerRegistry
+        }
 
-        this.openTag = markerRegistry.createMarkerStart('blockoutlet', this.id);
-        this.closeTag = markerRegistry.createMarkerEnd('blockoutlet', this.id);
+    }
+
+    /**
+     * Tìm cặp marker outlet từ server-rendered HTML (format chuẩn §5.1):
+     *   open:  s:bo:{id}-s   close: s:bo:{id}-e
+     * Tra index của MarkerRegistry, chặn trong parentElement nếu có.
+     */
+    private claimSSRMarkers(): { open: Comment; close: Comment } | null {
+        return markerRegistry.claim('blockoutlet', this.id, this.parentElement?.element ?? null);
     }
 
     hydrate(): void {
         // Hydration logic if needed (e.g. reattach event listeners)
     }
 
+    /** Registry guard */
+    public __destroyed__: boolean = false;
+    /** Key trả về bởi markerRegistry.register — destroy() dùng để gỡ lại */
+    private markerKey: string | null = null;
+
+    /** Render — idempotent: markers đã trong DOM thì giữ nguyên (same-layout reuse) */
     render(): void {
-        if (!this.parentElement || !this.parentElement.element) return;
+        if (this.__destroyed__) return;
+        if (this.openTag.parentNode) return; // đã đặt — không đặt lại
 
+        if (!this.parentElement || !this.parentElement.element) return;
         const parentEl = this.parentElement.element;
-
-        // Place markers
         parentEl.appendChild(this.openTag);
-        // Register this outlet in the MarkerRegistry for block mounting
         parentEl.appendChild(this.closeTag);
-
     }
 
     destroy(): void {
+        this.__destroyed__ = true;
+        this.ctx.releaseElement?.(this);
+        if (this.markerKey) {
+            markerRegistry.remove(this.markerKey);
+            this.markerKey = null;
+        }
+        // Clear nội dung giữa markers (block content nếu còn)
+        let current: Node | null = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            const next: Node | null = current.nextSibling;
+            (current as ChildNode).remove();
+            current = next;
+        }
         // Remove markers from DOM
         this.openTag.remove();
         this.closeTag.remove();
@@ -65,11 +105,11 @@ export class BlockOutlet implements BlockOutletInterface {
         this.parentElement = parentElement;
     }
 
-    get isOneElement(): boolean {
+    get isSaoElement(): boolean {
         return true;
     }
 
-    set isOneElement(value: boolean) {
+    set isSaoElement(value: boolean) {
         // No-op setter to satisfy OneElement interface
     }
 

package/src/core/elements/Component.ts

@@ -1,13 +1,15 @@
-import { InitMode, InitModes } from "../contracts/common";
-import { ComponentInterface } from "../contracts/ComponentInterface";
-import { HtmlInterface, OneChildrenFactory } from "../contracts/ElementInterface";
-import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { ViewInterface } from "../contracts/ViewInterface";
-import { generateUUID } from "../hellpers/utils";
-import { OneObjectType } from "../types/utils";
+import { InitMode, InitModes } from "../contracts/common.js";
+import { ComponentInterface } from "../contracts/ComponentInterface.js";
+import { HtmlInterface, SaoChildrenFactory } from "../contracts/ElementInterface.js";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { ViewInterface } from "../contracts/ViewInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import { activateView, claimHydratedView, commitView, mountChildrenBeforeAnchor } from "../helpers/view.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import { SaoObjectType } from "../types/utils.js";
 
 export class Component implements ComponentInterface {
-    oneType: OneObjectType = 'Component';
+    saoType: SaoObjectType = 'Component';
     ctx: ViewControllerInterface;
     parent: HtmlInterface | null;
     domChildren: Node[] = []; // For compatibility with HtmlInterface; Component itself doesn't have a single root element
@@ -23,6 +25,18 @@ export class Component implements ComponentInterface {
     initMode: InitMode = InitModes.CREATE; // Default initialization mode
     subscribeFn: () => void = () => {};
     unsubscribeFn: () => void = () => {};
+    /**
+     * Listener khai báo tại thẻ cha: `<mycomp @edit(openEditor(event))>`.
+     *
+     * Con gọi `emit('edit', payload)` → ViewController.emit tra Ở ĐÂY, không đi
+     * qua event bus: không rò sang instance khác, không phải gỡ đăng ký.
+     *
+     * Đọc lúc phát chứ không copy vào data con: mỗi lần cha render lại,
+     * `ViewController.include()` thay bảng này bằng closure mới, nên handler
+     * luôn nhìn thấy biến vòng lặp / prop của LƯỢT RENDER hiện tại — kể cả khi
+     * component không có prop reactive nào để kích hoạt updateData.
+     */
+    listeners: Record<string, (...args: any[]) => any> = {};
     dataFactory: ((parentElement: HtmlInterface | null) => Record<string, any>) | null = null; 
 
     constructor({
@@ -36,6 +50,7 @@ export class Component implements ComponentInterface {
         type = 'default',
         condition = null,
         initMode = InitModes.CREATE,
+        listeners = {},
     }: {
         ctx: ViewControllerInterface;
         parent?: HtmlInterface | null;
@@ -47,19 +62,46 @@ export class Component implements ComponentInterface {
         type?: 'default' | 'if' | 'when';
         condition?: {stateKeys: string[], checker: () => any} | null;
         initMode?: InitMode;
+        listeners?: Record<string, (...args: any[]) => any>;
     }) {
         this.ctx = ctx;
         this.parent = parent;
         this.stateKeys = stateKeys;
         this.data = data || {};
-        this.openTag = document.createComment(`component-start`);
-        this.closeTag = document.createComment(`component-end`);
-        this.id = `${ctx.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+        // id khớp server: Blade emit @startMarker('component', '{hash}') →
+        // <!--s:c:{parentViewId}-{hash}-s--> (MarkerRegistryDirectiveService)
+        this.id = `${ctx.viewId}-${id ?? generateUUID(10)}`;
         this.dataFactory = dataFactory;
         this.path = path;
         this.type = type;
         this.condition = condition;
+        this.listeners = listeners || {};
         this.initMode = initMode ?? InitModes.CREATE;
+
+        if (this.initMode === InitModes.HYDRATE) {
+            // ── Hydrate: claim cặp marker component server đã render ─────
+            const claimed = this.claimSSRMarkers();
+            if (claimed) {
+                this.openTag = claimed.open;
+                this.closeTag = claimed.close;
+            } else {
+                // Partial hydration fallback (server không render vùng này)
+                this.openTag = markerRegistry.createMarkerStart('component', this.id);
+                this.closeTag = markerRegistry.createMarkerEnd('component', this.id);
+            }
+        } else {
+            // Format chuẩn s:c:{id}-s/-e — PHẢI khớp server để SSR/CSR cùng kết quả
+            this.openTag = markerRegistry.createMarkerStart('component', this.id);
+            this.closeTag = markerRegistry.createMarkerEnd('component', this.id);
+        }
+    }
+
+    /**
+     * Tìm cặp marker component từ server-rendered HTML (format chuẩn §5.1):
+     *   open: s:c:{id}-s   close: s:c:{id}-e
+     */
+    private claimSSRMarkers(): { open: Comment; close: Comment } | null {
+        return markerRegistry.claim('component', this.id, this.parent?.element ?? null);
     }
 
     mergeData(newData: Record<string, any>): void {
@@ -75,6 +117,9 @@ export class Component implements ComponentInterface {
     setStateKeys(stateKeys: string[]) {
         this.stateKeys = stateKeys;
     }
+    setListeners(listeners: Record<string, (...args: any[]) => any>) {
+        this.listeners = listeners || {};
+    }
     setParentElement(parent: HtmlInterface | null): void {
         this.parent = parent;
     }
@@ -86,23 +131,312 @@ export class Component implements ComponentInterface {
         this.parent = parent;
     }
 
+    /** Registry guard */
+    public __destroyed__: boolean = false;
+    private _isStarted = false;
+    private unsubscribeData: (() => void) | null = null;
+    private unsubscribeCondition: (() => void) | null = null;
+    /** 'when' type: trạng thái mounted hiện tại của child */
+    private _childMounted = false;
+
+    /**
+     * Render — @include (RUNTIME_CONTRACT.md §2):
+     *   1. Đặt component markers (idempotent — caller có thể đã đặt đúng vị trí)
+     *   2. Resolve child view từ registry (App.View)
+     *   3. Render child wrapper GIỮA markers, liên kết parent ↔ child
+     *   4. commitData cho child (start sẽ do lifecycle cascade gọi)
+     *
+     * Hydrate mode (markers claim được từ SSR): child view được tạo với đúng
+     * viewId server đã dùng (discover từ marker view bên trong) → toàn bộ cây
+     * con CLAIM DOM server thay vì tạo mới — SSR/CSR cho cùng kết quả.
+     */
+    render(): void {
+        if (this.__destroyed__) return;
+
+        // ── Hydrate path: markers đã có trong SSR DOM ──────────────────
+        if (this.initMode === InitModes.HYDRATE) {
+            if (this.openTag.parentNode) {
+                // Điều kiện đánh giá với state ĐÃ commit (hydrateView commit trước
+                // render) → kết quả khớp server-rendered output.
+                if (this.type === 'when' && this.condition && !this.condition.checker()) {
+                    this.initMode = InitModes.CREATE;
+                    return; // server cũng không render child (điều kiện falsy)
+                }
+                if (this.type === 'if') {
+                    const viewManager = (this.ctx as any).App?.View;
+                    if (!viewManager?.exists?.(this.path ?? '')) {
+                        this.initMode = InitModes.CREATE;
+                        return;
+                    }
+                }
+                this.guardChildMount(() => this.hydrateChild());
+                this.initMode = InitModes.CREATE; // re-render sau này dùng CSR flow
+                return;
+            }
+            // Partial hydration fallback: server không render component này → CSR
+            this.initMode = InitModes.CREATE;
+        }
+
+        // 1. Markers
+        if (!this.openTag.parentNode) {
+            const parentEl = this.parent?.element;
+            if (!parentEl) return;
+            parentEl.appendChild(this.openTag);
+            parentEl.appendChild(this.closeTag);
+        }
+
+        // 2. Điều kiện theo type
+        if (this.type === 'when' && this.condition) {
+            const shouldMount = !!this.condition.checker();
+            if (!shouldMount) {
+                this.unmountChild();
+                return;
+            }
+        }
+        if (this.type === 'if') {
+            const viewManager = (this.ctx as any).App?.View;
+            if (!viewManager?.exists?.(this.path ?? '')) {
+                return; // @includeIf: view không tồn tại → bỏ qua, không lỗi
+            }
+        }
+
+        this.guardChildMount(() => this.mountChild());
+    }
+
+    /**
+     * Error boundary cho subtree con (@include). Boundary được tìm từ ctx —
+     * controller CHỨA @include này, không phải view con — nên onError của một
+     * view không bắt lỗi render của chính nó (giống React ErrorBoundary).
+     * Không boundary nào xử lý → rethrow, giữ nguyên hành vi cũ (bubble lên
+     * try/catch của renderPageView).
+     */
+    private guardChildMount(mount: () => void): void {
+        try {
+            mount();
+        } catch (err) {
+            const result = this.ctx.handleError(err, { phase: 'render', path: this.path ?? '' });
+            if (!result.handled) throw err;
+            this.mountFallback(result.fallback);
+        }
+    }
+
+    /** Dọn DOM dở dang của lần render lỗi rồi chèn fallback giữa cặp marker. */
+    private mountFallback(fallback: any): void {
+        let current: Node | null = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            const next: Node | null = current.nextSibling;
+            current.parentNode?.removeChild(current);
+            current = next;
+        }
+        if (fallback === null || fallback === undefined) return;
+        mountChildrenBeforeAnchor(
+            this.closeTag,
+            Array.isArray(fallback) ? fallback : [fallback],
+            this.parent,
+        );
+    }
+
+    /**
+     * Discover viewId server đã dùng cho child view: quét comment giữa cặp
+     * marker component, tìm marker view mở đầu tiên <!--s:v:{id}-s-->.
+     */
+    private discoverChildViewId(): string | null {
+        let current: Node | null = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            if (current.nodeType === Node.COMMENT_NODE) {
+                const parsed = markerRegistry.parseComment(current.nodeValue ?? '');
+                if (parsed && parsed.tag === 'view' && !parsed.isClose) return parsed.id;
+            } else if (current.nodeType === Node.ELEMENT_NODE) {
+                const walker = document.createTreeWalker(current, NodeFilter.SHOW_COMMENT);
+                let node: Comment | null;
+                while ((node = walker.nextNode() as Comment | null)) {
+                    const parsed = markerRegistry.parseComment(node.nodeValue ?? '');
+                    if (parsed && parsed.tag === 'view' && !parsed.isClose) return parsed.id;
+                }
+            }
+            current = current.nextSibling;
+        }
+        return null;
+    }
+
+    /**
+     * Hydrate child view — thứ tự chuẩn hydration (như ViewManager.hydrateView):
+     * discover viewId → tạo instance → commit state → flush discard →
+     * render claim DOM → mount() (hook + asset). KHÔNG chèn node mới.
+     */
+    private hydrateChild(): void {
+        if (this._childMounted && this.viewRef) return;
+
+        // Không có marker view của server giữa cặp marker component → server
+        // KHÔNG render view con ở đây. Hydrate tiếp thì child giữ viewId do
+        // client sinh ('c…'), rồi đi tìm class "{c…}-{id}" và marker
+        // "s:v:c…" không tồn tại → dựng cây mới CẠNH cây server, tức nhân đôi
+        // DOM. Dọn phần server bỏ lại rồi đi đường CSR — giống nhánh
+        // "partial hydration fallback" ở render() khi marker component vắng.
+        const ssrViewId = this.discoverChildViewId();
+        if (!ssrViewId) {
+            this.unmountChild();
+            this.mountChild();
+            return;
+        }
+
+        const childView = this.resolveChildView();
+        if (!childView) return;
+        const childCtrl = childView.__ctrl__;
+
+        // Ghi đè viewId = viewId server (trước render — Wrapper/Html/Output của
+        // child claim theo marker/class prefix bằng viewId này)
+        childCtrl.viewId = ssrViewId;
+
+        // Commit state TRƯỚC render (factory @if/@foreach sinh đúng cây khớp SSR);
+        // flush ngay khi chưa subscribe → discard pending, không phá DOM claim.
+        childCtrl.initMode = InitModes.HYDRATE;
+        commitView(childCtrl, true);
+
+        const wrapper = childCtrl.render();
+        if (wrapper && typeof wrapper === 'object' && 'openTag' in wrapper && this.parent) {
+            claimHydratedView(childCtrl, this.parent, wrapper as any);
+        }
+
+        childCtrl.initMode = InitModes.CREATE;
+        this.finishChildMount(childCtrl);
+    }
+
+    /** Tạo + mount child view giữa markers (nếu chưa có) */
+    private mountChild(): void {
+        if (this._childMounted && this.viewRef) {
+            if (this.dataFactory) {
+                const ctrl = this.viewRef.__ctrl__;
+                ctrl.updateData(this.dataFactory(this.parent));
+                ctrl.states.__.flushNow();
+            }
+            return;
+        }
+        const childView = this.resolveChildView();
+        if (!childView) return;
+        const childCtrl = childView.__ctrl__;
+
+        // Render child tree giữa markers
+        const wrapper = childCtrl.render();
+        if (wrapper && typeof wrapper === 'object' && 'openTag' in wrapper) {
+            const insertBeforeClose = (node: Node) => {
+                this.closeTag.parentNode?.insertBefore(node, this.closeTag);
+            };
+            insertBeforeClose(wrapper.openTag);
+            insertBeforeClose(wrapper.closeTag);
+            // Wrapper render idempotent qua mountChildrenBeforeAnchor
+            mountChildrenBeforeAnchor(wrapper.closeTag, wrapper.render(), this.parent);
+        }
+
+        // mount(): nội dung child đã nằm giữa markers → fire mounting/mounted + acquire asset
+        childCtrl.mount();
+        commitView(childCtrl);
+        this.markChildMounted(childCtrl);
+    }
+
+    /** Resolve one child instance and establish ownership before either DOM strategy. */
+    private resolveChildView(): ViewInterface | null {
+        const viewManager = (this.ctx as any).App?.View;
+        if (!viewManager || !this.path) {
+            console.error(`[Component] Không resolve được view "${this.path}" — App.View chưa sẵn sàng.`);
+            return null;
+        }
+
+        const data = this.dataFactory ? this.dataFactory(this.parent) : this.data;
+        // Sync: render tree không await được (xem ViewManager.resolveViewSync).
+        const childView = viewManager.resolveViewSync(this.path, data ?? {}, false);
+        if (!childView) {
+            console.error(`[Component] View "${this.path}" không tồn tại trong registry.`);
+            return null;
+        }
+
+        this.viewRef = childView;
+        const childCtrl = childView.__ctrl__;
+        childCtrl.ownerComponent = this;
+        childCtrl.setParent(this.ctx);
+        this.ctx.addChild(childCtrl);
+        childCtrl.setParentElement(this.parent);
+        return childView;
+    }
+
+    /** Hydration mounts after commit/claim; CSR commits immediately after mount. */
+    private finishChildMount(childCtrl: ViewControllerInterface): void {
+        childCtrl.mount();
+        this.markChildMounted(childCtrl);
+    }
+
+    private markChildMounted(childCtrl: ViewControllerInterface): void {
+        this._childMounted = true;
+        if (this._isStarted) activateView(childCtrl);
+    }
+
+    /** Gỡ child (when=false hoặc destroy) */
+    private unmountChild(): void {
+        if (this.viewRef) {
+            this.viewRef.__ctrl__.destroy();
+            this.viewRef = null;
+        }
+        // Clear mọi node giữa markers
+        let current: Node | null = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            const next: Node | null = current.nextSibling;
+            (current as ChildNode).remove();
+            current = next;
+        }
+        this._childMounted = false;
+    }
+
+    /**
+     * Start — kích hoạt child + subscribe:
+     *   - stateKeys: props reactive — đổi → dataFactory mới → child.updateData()
+     *   - condition (type 'when'): đổi → mount/unmount child
+     */
     start(): void {
+        if (this._isStarted || this.__destroyed__) return;
+        this._isStarted = true;
+
+        if (this.viewRef) {
+            activateView(this.viewRef.__ctrl__);
+        }
+
+        if (this.stateKeys.length > 0) {
+            this.unsubscribeData = this.ctx.states.__.subscribe(this.stateKeys, () => {
+                if (this.viewRef && this.dataFactory) {
+                    this.viewRef.__ctrl__.updateData(this.dataFactory(this.parent));
+                }
+            });
+        }
+
+        if (this.type === 'when' && this.condition && this.condition.stateKeys.length > 0) {
+            this.unsubscribeCondition = this.ctx.states.__.subscribe(this.condition.stateKeys, () => {
+                this.render(); // re-evaluate checker → mount/unmount
+            });
+        }
     }
 
     stop(): void {
-    }
+        if (!this._isStarted) return;
+        this._isStarted = false;
 
-    render(): void {
-        // To be implemented by specific components
+        if (this.unsubscribeData) { this.unsubscribeData(); this.unsubscribeData = null; }
+        if (this.unsubscribeCondition) { this.unsubscribeCondition(); this.unsubscribeCondition = null; }
+        this.viewRef?.__ctrl__.stop();
     }
 
     destroy(): void {
-        // To be implemented by specific components
+        if (this.__destroyed__) return;
+        this.stop();
+        this.__destroyed__ = true;
+        this.ctx.releaseElement?.(this);
+        this.unmountChild();
+        this.openTag.remove();
+        this.closeTag.remove();
+        this.parent = null;
     }
-    get isOneElement(): boolean {
+    get isSaoElement(): boolean {
         return true;
     }
-    set isOneElement(value: boolean) {
+    set isSaoElement(value: boolean) {
         // No-op, just for type compatibility
     }
     get isOneComponent(): boolean {
@@ -111,4 +445,4 @@ export class Component implements ComponentInterface {
     set isOneComponent(value: boolean) {
         // No-op, just for type compatibility
     }
-}
+}