@saolabs/client 1.0.0 → 1.1.0

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
     }
-}
+}

package/src/core/elements/ElementManager.ts

@@ -1,12 +1,12 @@
-import type { BlockRenderFactory } from "../contracts/BlockInterface";
-import type { HtmlInterface, OneElementConfig, OneChildrenFactory } from "../contracts/ElementInterface";
-import type { ReactiveRenderFn } from "../contracts/ReactiveInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { Html } from "./Html";
-import { TextElement } from "./TextElement";
-import { Reactive } from "./Reactive";
-import { Fragment } from "./Fragment";
-import { Block } from "./Block";
+import type { BlockRenderFactory } from "../contracts/BlockInterface.js";
+import type { HtmlInterface, SaoElementConfig, SaoChildrenFactory } from "../contracts/ElementInterface.js";
+import type { ReactiveRenderFn } from "../contracts/ReactiveInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { Html } from "./Html.js";
+import { TextElement } from "./TextElement.js";
+import { Reactive } from "./Reactive.js";
+import { Fragment } from "./Fragment.js";
+import { Block } from "./Block.js";
 
 /**
  * OneElementManager — factory/registry for creating One elements.

package/src/core/elements/ForeachSlotCache.ts

@@ -0,0 +1,170 @@
+/**
+ * ForeachSlotCache — keyed slot manager cho @foreach reconciliation.
+ *
+ * # Cơ chế
+ * Mỗi item được identify bằng một cache key:
+ *   - Có @key(expr)   → key = giá trị expr (field keying, vd `item.id`)
+ *   - Không có @key   → key = object reference của item (identity keying)
+ * Duplicate keys (primitive lists `['a','b','a']`, refs lặp) được phân biệt
+ * bằng occurrence index trong pass — key thứ n trùng nhau map vào slot thứ n.
+ *
+ * # Reuse contract
+ * Slot chỉ được REUSE khi cache key khớp VÀ item ref không đổi
+ * (`slot.item === item`). Ref đổi → recreate, vì compiled output đóng gói
+ * `item` trực tiếp vào closure (`() => item.name`) — reuse với ref cũ sẽ
+ * hiển thị data cũ. Field key vì vậy chủ yếu mang lại: bookkeeping đúng cho
+ * duplicate/primitive items + ý định tường minh của developer.
+ *
+ * # Pass protocol (một chu kỳ render)
+ *   1. `beginPass()`  — reset occurrence counters + tập slot touched
+ *   2. `claim(key, item)` mỗi item theo thứ tự list:
+ *        hit  (slot.item === item) → dùng lại, slot được mark touched
+ *        miss → caller tạo elements rồi `store(key, occ, item, elements)`
+ *   3. `prunePass(onRemove)` — slot KHÔNG được touch trong pass = item đã rời
+ *      list → callback destroy + gỡ khỏi cache. (Trước đây bước này là dead
+ *      code — cache không bao giờ gỡ entry → element của item bị xoá leak.)
+ *      Slot bị `store()` GHI ĐÈ (cùng key, ref mới) cũng đi qua đây: nó rơi khỏi
+ *      `_map` ngay lúc ghi đè nên prunePass không còn thấy → phải giữ tạm trong
+ *      `_evicted`. Thiếu bước này thì refresh list từ server (`@key` giữ nguyên,
+ *      ref đổi) KHÔNG destroy elements cũ → view con của @include bị tái dùng
+ *      trong DOM đã detach và biến mất khỏi trang.
+ *
+ * # Quan hệ với Reactive
+ * Reactive type 'foreach' giữ một instance; cửa sổ `_currentForeachCache`
+ * chỉ mở quanh CHÍNH childrenFactory call (không mở trong child.render() —
+ * tránh nested @foreach ghi nhầm vào cache của loop ngoài).
+ *
+ * @see Reactive.renderForeach()
+ * @see ViewController.__foreach()
+ */
+
+/** Một slot tương ứng với một item trong foreach list. */
+export interface ForeachSlot {
+    /** Reference tới item gốc — điều kiện reuse là ref không đổi */
+    item: any;
+    /** Saola elements sinh ra bởi item factory — Html, Output, Reactive, ... */
+    elements: any[];
+    /** Compiler opt-in: closures are refreshed within this occurrence's scope. */
+    registry?: Map<string, any>;
+    identity?: number;
+}
+
+/** Kết quả claim: slot khi reuse được, occ để store khi phải tạo mới. */
+export interface ForeachClaim {
+    slot: ForeachSlot | null;
+    occ: number;
+}
+
+export class ForeachSlotCache {
+    readonly refreshedElements = new Set<any>();
+    private nextIdentity = 0;
+
+    /** Initial SSR indexes, then monotonically allocated identities for new rows. */
+    allocateIdentity(index: number): number {
+        const identity = Math.max(index, this.nextIdentity);
+        this.nextIdentity = identity + 1;
+        return identity;
+    }
+    /** Map key → danh sách slot theo occurrence (duplicate keys) */
+    private _map: Map<any, ForeachSlot[]> = new Map();
+    /** Occurrence counter của pass hiện tại */
+    private _passOcc: Map<any, number> = new Map();
+    /** Slots được claim-hit hoặc store trong pass hiện tại */
+    private _touched: Set<ForeachSlot> = new Set();
+    /** Slots bị store() ghi đè trong pass hiện tại — prunePass destroy rồi clear */
+    private _evicted: ForeachSlot[] = [];
+
+    /** Tổng số slot đang cache (mọi occurrence). */
+    get size(): number {
+        let n = 0;
+        for (const slots of this._map.values()) n += slots.length;
+        return n;
+    }
+
+    /** Bắt đầu một chu kỳ render — reset counters + touched set. */
+    beginPass(): void {
+        this.refreshedElements.clear();
+        this._passOcc = new Map();
+        this._touched = new Set();
+        this._evicted = [];
+    }
+
+    /**
+     * Claim slot cho (key, item) theo thứ tự list.
+     * Trả slot khi reuse được (key khớp + ref không đổi); ngược lại slot=null
+     * và caller phải store(key, occ, ...) sau khi tạo elements.
+     */
+    claim(key: any, item: any, reconcile = false): ForeachClaim {
+        const occ = this._passOcc.get(key) ?? 0;
+        this._passOcc.set(key, occ + 1);
+
+        const slot = this._map.get(key)?.[occ] ?? null;
+        if (slot && (slot.item === item || (reconcile && slot.registry))) {
+            this._touched.add(slot);
+            return { slot, occ };
+        }
+        return { slot: null, occ };
+    }
+
+    /**
+     * Lưu slot mới tại (key, occ) — ghi đè slot cũ nếu ref đã đổi.
+     * Slot bị ghi đè KHÔNG còn nằm trong `_map` nên prunePass duyệt `_map` sẽ
+     * không thấy nó nữa → phải chuyển sang `_evicted` để vẫn được destroy.
+     */
+    store(key: any, occ: number, item: any, elements: any[], registry?: Map<string, any>): ForeachSlot {
+        const slot: ForeachSlot = { item, elements, registry };
+        let slots = this._map.get(key);
+        if (!slots) {
+            slots = [];
+            this._map.set(key, slots);
+        }
+        const evicted = slots[occ];
+        if (evicted && !this._touched.has(evicted)) {
+            this._evicted.push(evicted);
+        }
+        slots[occ] = slot;
+        this._touched.add(slot);
+        return slot;
+    }
+
+    /**
+     * Kết thúc pass: mọi slot không được touch = item đã rời list (hoặc bị
+     * thay bằng ref mới) → gọi onRemove(slot) để destroy elements, gỡ khỏi cache.
+     */
+    prunePass(onRemove: (slot: ForeachSlot) => void): void {
+        // Slot bị ghi đè: đã rời `_map` lúc store() nên chỉ cần destroy.
+        for (const slot of this._evicted) onRemove(slot);
+        this._evicted = [];
+
+        for (const [key, slots] of this._map) {
+            let hasRemoval = false;
+            for (const slot of slots) {
+                if (slot && !this._touched.has(slot)) {
+                    onRemove(slot);
+                    hasRemoval = true;
+                }
+            }
+            if (hasRemoval) {
+                const kept = slots.filter(s => s && this._touched.has(s));
+                if (kept.length) {
+                    this._map.set(key, kept);
+                } else {
+                    this._map.delete(key);
+                }
+            }
+        }
+    }
+
+    /**
+     * Xoá toàn bộ cache — dùng khi Reactive bị destroy.
+     * KHÔNG tự gọi destroy() trên elements — caller phải làm trước.
+     */
+    clear(): void {
+        this.nextIdentity = 0;
+        this.refreshedElements.clear();
+        this._map.clear();
+        this._passOcc = new Map();
+        this._touched = new Set();
+        this._evicted = [];
+    }
+}