@saolabs/client 1.0.0 → 1.1.0

package/src/core/elements/Reactive.ts

@@ -1,10 +1,14 @@
-import { InitMode, InitModes } from "../contracts/common";
-import type { HtmlInterface, OneChildrenFactoryOutput, OneElementChildren } from "../contracts/ElementInterface";
-import type { ReactiveInterface, ReactiveChildrenFactory, ReactiveRenderFn } 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 { reconcileChildren } from './reconcileChildren.js';
+import { InitMode, InitModes } from "../contracts/common.js";
+import type { HtmlInterface, SaoChildrenFactoryOutput, SaoElementChildren } from "../contracts/ElementInterface.js";
+import type { ReactiveInterface, ReactiveChildrenFactory, ReactiveRenderFn } from "../contracts/ReactiveInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import { mountChildrenBeforeAnchor } from "../helpers/view.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import type { SaoObjectType } from "../types/utils.js";
+import { ForeachSlotCache } from "./ForeachSlotCache.js";
+import { isLeaving } from "../helpers/transition.js";
 
 /**
  * Reactive — a region in the DOM bounded by comment markers that 
@@ -22,27 +26,38 @@ import type { OneObjectType } from "../types/utils";
  */
 export class Reactive implements ReactiveInterface {
     static class = 'Reactive';
-    oneType: OneObjectType = 'Reactive';
+    saoType: SaoObjectType = 'Reactive';
     public id: string; // Unique ID for debugging and marker registry
     public type: string; // Custom type for different reactive behaviors (e.g. 'if', 'list')
     public openTag: Comment;
     public closeTag: Comment;
     public parentElement: HtmlInterface | null;
     public parentReactive: ReactiveInterface | null;
-    public parent: HtmlInterface | null = null; // Alias for parentReactive to satisfy OneNodeInterface
+    public parent: HtmlInterface | null = null; // Alias for parentReactive to satisfy SaoNodeInterface
 
     public ctx: ViewControllerInterface;
     public childrenFactory: ReactiveChildrenFactory;
-    public children: OneElementChildren = [];
+    public children: SaoElementChildren = [];
     private mounted: boolean = false;
     public stateKeys: string[];
-    public unsubscribe: () => void = () => {};
+    public unsubscribe: () => void = () => { };
     private _isStarted = false;
+    /** Marker model (hydration) — gán bởi BlockManager/SSR khi cần; mặc định null. */
+    /** Key trả về bởi markerRegistry.register — destroy() dùng để gỡ lại */
+    private markerKey: string | null = null;
 
 
 
     domChildren: Node[] = []; // For compatibility with HtmlInterface; Reactive itself doesn't have a single root element
     initMode: InitMode = InitModes.CREATE;
+
+    /**
+     * Slot cache cho @foreach reconciliation (Phase 5).
+     * Được tạo khi type === 'foreach', null cho tất cả các type khác.
+     * Cache maps item ref → Saola elements — cho phép reuse elements
+     * khi item object reference không thay đổi.
+     */
+    private _foreachCache: ForeachSlotCache | null = null;
     constructor({
         type = 'reactive',
         id = null,
@@ -65,19 +80,49 @@ export class Reactive implements ReactiveInterface {
         this.ctx = ctx;
         this.parentElement = parentElement;
         this.parentReactive = parentReactive;
-        this.id = `${ctx.viewId}-${id || generateUUID(5)}`;
+        this.id = id ? id : `${ctx.viewId}-${generateUUID(5)}`;
         this.type = type;
         this.childrenFactory = childrenFactory;
         this.stateKeys = stateKeys;
         this.initMode = initMode;
-        markerRegistry.register('reactive', this.id, {
-            type: this.type,
-            stateKeys: this.stateKeys,
-            viewID: this.ctx.viewId,
-        });
 
-        this.openTag = markerRegistry.createMarkerStart('reactive', this.id);
-        this.closeTag = markerRegistry.createMarkerEnd('reactive', this.id);
+        // foreach type: khởi tạo slot cache để hỗ trợ identity-keyed reconciliation
+        if (type === 'foreach') {
+            this._foreachCache = new ForeachSlotCache();
+        }
+
+        if (this.initMode === InitModes.CREATE) {
+            this.markerKey = markerRegistry.register('reactive', this.id, {
+                type: this.type,
+                stateKeys: this.stateKeys,
+                viewID: this.ctx.viewId,
+            });
+
+            this.openTag = markerRegistry.createMarkerStart('reactive', this.id);
+            this.closeTag = markerRegistry.createMarkerEnd('reactive', this.id);
+        }
+        else {
+            // ── Hydrate: tìm markers SSR trong DOM ──────────────────────
+            // Scan parent element cho cặp comment <!--r:id--> ... <!--/r:id-->
+            // (MarkerRegistry format). Fallback tạo mới nếu không tìm thấy.
+            const claimed = this.claimSSRMarkers();
+            if (claimed) {
+                this.openTag = claimed.open;
+                this.closeTag = claimed.close;
+            } else {
+                this.openTag = markerRegistry.createMarkerStart('reactive', this.id);
+                this.closeTag = markerRegistry.createMarkerEnd('reactive', this.id);
+            }
+        }
+    }
+
+    /**
+     * Tìm cặp comment markers từ server-rendered HTML.
+     * Format MarkerRegistry: open = `r:id`, close = `/r:id`
+     * (r = shortcut cho 'reactive').
+     */
+    private claimSSRMarkers(): { open: Comment; close: Comment } | null {
+        return markerRegistry.claim('reactive', this.id, this.parentElement?.element ?? null);
     }
 
     setParentElement(parent: HtmlInterface | null): void {
@@ -97,15 +142,62 @@ export class Reactive implements ReactiveInterface {
         }
     }
 
-    /** Mount markers into parent and render content */
+    /** Registry guard — element đã destroy không được reuse */
+    public __destroyed__: boolean = false;
+
+    /**
+     * Render — idempotent + position-aware (RUNTIME_CONTRACT.md §2):
+     *   - Markers chưa trong DOM → đặt markers (trước closeTag của parentReactive
+     *     nếu có, ngược lại append vào parentElement — đường mountElementList
+     *     duyệt tuần tự nên vị trí đúng).
+     *   - Markers đã trong DOM → chỉ thay nội dung GIỮA markers.
+     * Children loại marker-based (Output, nested Reactive, Fragment) được CALLER
+     * đặt markers vào đúng vị trí trước, rồi mới gọi child.render() — FIX(baseline#6).
+     * Children sinh ra khi đang active được start() ngay — FIX(baseline#7).
+     */
     render(): void {
-        const target = this.getInsertionTarget();
-        if (!target) return;
+        try {
+            this._render();
+        } catch (err) {
+            // Lỗi ở vùng reactive thường xảy ra SAU khi trang đã sống (state đổi do
+            // user tương tác) — ngoài mọi try/catch của renderPageView. 'render' cho
+            // lần đầu, 'update' cho re-render.
+            const phase = this.mounted ? 'update' : 'render';
+            const result = this.ctx.handleError(err, { phase, path: this.ctx.path });
+            if (!result.handled) throw err;
+            this.clearContent();
+            if (result.fallback !== null && result.fallback !== undefined) {
+                mountChildrenBeforeAnchor(
+                    this.closeTag,
+                    Array.isArray(result.fallback) ? result.fallback : [result.fallback],
+                    this.parentElement,
+                );
+            }
+        }
+    }
+
+    private _render(): void {
+        if (this.__destroyed__) return;
+
+        // ── Hydrate mode: markers đã trong DOM từ SSR ────────────────
+        // Tiền đề: ViewManager.hydrateView() đã gọi commitData() TRƯỚC bước này,
+        // nên closure state (vd `show`) đã có giá trị = trạng thái server.
+        // → childrenFactory sinh đúng element tree khớp với SSR DOM.
+        // _hydrateChildren tạo JS objects (Html claim DOM, Output claim markers)
+        // mà KHÔNG insert node mới — giữ nguyên DOM server-rendered.
+        if (this.initMode === InitModes.HYDRATE && this.openTag.parentNode) {
+            this._hydrateChildren();
+            this.mounted = true;
+            // Chuyển sang CREATE: re-render sau này (do state đổi) dùng CSR flow.
+            this.initMode = InitModes.CREATE;
+            return;
+        }
 
-        if (!this.mounted) {
-            // First render: place markers
-            if (this.parentReactive) {
-                // Insert before the parent's close marker
+        if (!this.openTag.parentNode) {
+            // ── Lần đầu mount: đặt markers vào DOM ───────────────────────────
+            const target = this.getInsertionTarget();
+            if (!target) return;
+            if (this.parentReactive && this.parentReactive.closeTag.parentNode === target) {
                 target.insertBefore(this.openTag, this.parentReactive.closeTag);
                 target.insertBefore(this.closeTag, this.parentReactive.closeTag);
             } else {
@@ -113,28 +205,114 @@ export class Reactive implements ReactiveInterface {
                 target.appendChild(this.closeTag);
             }
             this.mounted = true;
+
+            // Initial render — _renderChildren tự mở cửa sổ cache quanh factory call
+            this._renderChildren();
+        } else if (this._foreachCache) {
+            // ── Re-render @foreach: dùng reconciler ──────────────────────────
+            this.renderForeach();
         } else {
-            // Re-render: clear existing content between markers
-            this.clearContent();
+            // ── Re-render các type khác: clear + factory ──────────────────────
+            const output = this._runFactoryWithCache();
+            const next = output.filter(child => child != null).map(child =>
+                typeof child === 'string' || typeof child === 'number' ? document.createTextNode(String(child)) : child);
+            const parent = this.closeTag.parentNode;
+            if (parent) reconcileChildren(parent, this.children, next, this.closeTag);
+            this.children = next as any;
+            this._cleanOrphanNodes(next);
+            if (this._isStarted) for (const child of next) (child as any).start?.();
         }
+        this.mounted = true;
+    }
 
-        // Produce children
-        const output: OneChildrenFactoryOutput = this.childrenFactory(this, this.parentElement);
+    /**
+     * Phần render nội bộ: chạy childrenFactory, insert children vào DOM.
+     * Dùng cho initial render (mọi type) và re-render non-foreach.
+     * Precondition: markers đã trong DOM.
+     */
+    private _renderChildren(): void {
+        // Cửa sổ cache chỉ mở quanh factory call — KHÔNG mở trong child.render()
+        // phía dưới, tránh nested @foreach (chạy lúc render con) ghi nhầm entry
+        // vào cache của loop ngoài rồi bị prunePass destroy oan ở pass sau.
+        const output = this._runFactoryWithCache();
+        const newChildren: any[] = [];
 
-        // Insert children between markers
         for (const child of output) {
+            if (child === null || child === undefined) continue;
             if (typeof child === 'string' || typeof child === 'number') {
                 const textNode = document.createTextNode(String(child));
                 this.insertBeforeClose(textNode);
                 this.children.push(textNode);
-            } else if (child && typeof child === 'object') {
-                if ('element' in child) {
-                    // HtmlInterface, TextInterface, FragmentInterface
-                    this.insertBeforeClose(child.element);
+            } else if (child instanceof Node) {
+                this.insertBeforeClose(child);
+                this.children.push(child as any);
+            } else if (typeof child === 'object') {
+                if ('element' in child && (child as any).element) {
+                    // Html, TextElement — single root element
+                    this.insertBeforeClose((child as any).element);
+                    this.children.push(child);
+                    newChildren.push(child);
+                    child.render();
+                } else if ('openTag' in child) {
+                    // Marker-based: Output, nested Reactive, Fragment...
+                    this.insertBeforeClose((child as any).openTag);
+                    this.insertBeforeClose((child as any).closeTag);
+                    this.children.push(child);
+                    newChildren.push(child);
+                    child.render();
+                }
+            }
+        }
+
+        // Vùng active: children mới cần start() ngay (có subscription/event)
+        if (this._isStarted) {
+            for (const child of newChildren) {
+                if (typeof (child as any).start === 'function') {
+                    (child as any).start();
+                }
+            }
+        }
+    }
+
+    /**
+     * Chạy childrenFactory với cửa sổ cache foreach (nếu có) mở đúng quanh
+     * factory call. beginPass reset occurrence counters + touched set.
+     */
+    private _runFactoryWithCache(): SaoChildrenFactoryOutput {
+        if (!this._foreachCache) {
+            return this.childrenFactory(this, this.parentElement);
+        }
+        this._foreachCache.beginPass();
+        this.ctx._currentForeachCache = this._foreachCache;
+        try {
+            return this.childrenFactory(this, this.parentElement);
+        } finally {
+            this.ctx._currentForeachCache = null;
+        }
+    }
+
+    /**
+     * Hydrate children — tạo JS element objects từ factory nhưng KHÔNG insert DOM.
+     * Html children đã claim server DOM nodes trong constructor.
+     * Output/Reactive children gọi render() để claim markers.
+     * Sau hydrate, re-render tiếp theo dùng flow CSR bình thường.
+     */
+    private _hydrateChildren(): void {
+        const output = this._runFactoryWithCache();
+
+        for (const child of output) {
+            if (child === null || child === undefined) continue;
+            if (typeof child === 'string' || typeof child === 'number') continue;
+            if (child instanceof Node) continue;
+
+            if (typeof child === 'object') {
+                if ('element' in child && (child as any).element) {
                     this.children.push(child);
                     child.render();
                 } else if ('openTag' in child) {
-                    // Nested Reactive
+                    if (typeof (child as any).setParentElement === 'function') {
+                        (child as any).setParentElement(this.parentElement);
+                    }
                     this.children.push(child);
                     child.render();
                 }
@@ -142,6 +320,100 @@ export class Reactive implements ReactiveInterface {
         }
     }
 
+    /**
+     * renderForeach — identity-keyed reconciliation cho @foreach (Phase 5).
+     *
+     * # Thuật toán
+     * 1. Snapshot cache hiện tại (prevSlots) — biết item nào đang hiển thị
+     * 2. Chạy childrenFactory với cache active → __foreach trả về:
+     *    - cached elements nếu item ref giống (no DOM create)
+     *    - elements mới nếu item mới (và lưu vào cache)
+     * 3. Diff: items nào KHÔNG xuất hiện trong kết quả mới → destroy + xoá cache
+     * 4. Reorder DOM: insertBefore(closeTag) cho tất cả elements mới (move hoặc append)
+     * 5. Cleanup orphan DOM nodes (nodes còn sót từ destroyed items)
+     * 6. Start elements mới nếu vùng đang active
+     *
+     * # Complexity
+     * - O(n) forEach pass trong __foreach
+     * - O(n) destroy pass cho removed items
+     * - O(n) DOM move pass (insertBefore là O(1) mỗi node)
+     * → Tổng O(n) so với O(2n) của clear+recreate, nhưng tiết kiệm DOM create/destroy
+     *   cho unchanged items.
+     */
+    private renderForeach(): void {
+        // ── Step 1: Ghi nhớ children đang hiển thị (phân biệt reuse/new) ─────
+        const cache = this._foreachCache!;
+        const prevChildren = new Set(this.children); // old Saola elements
+
+        // ── Step 2: Chạy factory với cache active (beginPass + claim/store) ──
+        const output = this._runFactoryWithCache();
+
+        // Flatten output thành danh sách children mới
+        const newChildren: any[] = [];
+        for (const child of output) {
+            if (child === null || child === undefined) continue;
+            if (typeof child === 'object') {
+                newChildren.push(child);
+            }
+        }
+
+        // ── Step 3: Destroy slot không được claim/store trong pass ───────────
+        // = item đã rời list, hoặc bị thay bằng ref mới (key trùng nhưng ref đổi).
+        cache.prunePass((slot) => {
+            for (const el of slot.elements) {
+                if (el && typeof el.destroy === 'function') {
+                    el.destroy();
+                }
+            }
+        });
+
+        const trulyNew = newChildren.filter(child => !prevChildren.has(child));
+        const parent = this.closeTag.parentNode;
+        if (parent) reconcileChildren(parent, this.children, newChildren, this.closeTag,
+            child => cache.refreshedElements.has(child));
+        this._cleanOrphanNodes(newChildren);
+        this.children = newChildren;
+        if (this._isStarted) {
+            for (const child of trulyNew) child.start?.();
+        }
+    }
+
+    /**
+     * Xoá các DOM nodes "mồ côi" giữa openTag và closeTag của Reactive.
+     * Orphan = nodes không thuộc bất kỳ child nào trong newChildren.
+     *
+     * Build tập hợp "expected nodes" từ newChildren, sau đó scan DOM
+     * và remove nodes không nằm trong tập đó.
+     */
+    private _cleanOrphanNodes(newChildren: any[]): void {
+        // Thu thập tất cả DOM nodes hợp lệ (thuộc new children)
+        const validNodes = new Set<Node>();
+        for (const child of newChildren) {
+            if ('element' in child && (child as any).element) {
+                validNodes.add((child as any).element);
+            } else if ('openTag' in child) {
+                // Marker-based: collect tất cả nodes trong block
+                let node: Node | null = (child as any).openTag;
+                while (node && node !== (child as any).closeTag) {
+                    validNodes.add(node);
+                    node = node.nextSibling;
+                }
+                if (node) validNodes.add(node); // closeTag
+            }
+        }
+
+        // Scan từ openTag → closeTag, remove nodes không hợp lệ.
+        // Node đang chạy leave PHẢI nằm lại tới khi animation xong — nó tự gỡ.
+        let current = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            const next = current.nextSibling;
+            if (!validNodes.has(current) && !isLeaving(current)) {
+                current.remove();
+            }
+            current = next;
+        }
+    }
+
     /** Schedule a re-render through the ViewController */
     update(): void {
         this.ctx.scheduleUpdate(this);
@@ -157,11 +429,12 @@ export class Reactive implements ReactiveInterface {
         }
         this.children = [];
 
-        // Remove DOM nodes between markers
+        // Remove DOM nodes between markers — trừ node đang leave (child.destroy()
+        // phía trên vừa khởi động animation cho chúng; tự gỡ khi xong).
         let current = this.openTag.nextSibling;
         while (current && current !== this.closeTag) {
             const next = current.nextSibling;
-            current.remove();
+            if (!isLeaving(current)) current.remove();
             current = next;
         }
     }
@@ -208,7 +481,7 @@ export class Reactive implements ReactiveInterface {
 
         if (this.unsubscribe) {
             this.unsubscribe();
-            this.unsubscribe = () => {};
+            this.unsubscribe = () => { };
         }
 
         // Recursively stop children
@@ -219,18 +492,22 @@ export class Reactive implements ReactiveInterface {
         }
     }
 
-    /** Remove content but keep markers (for hide/show scenarios) */
-    hide(): void {
-        this.clearContent();
-    }
-
-    /** Re-render content (for show after hide) */
-    show(): void {
-        this.render();
-    }
-
     destroy(): void {
+        this.__destroyed__ = true;
+        this.ctx.releaseElement?.(this);
+        // MarkerRegistry là singleton TOÀN CỤC (sống qua navigate). Reactive trong
+        // loop có id kèm item (`{viewId}-{hash}-${item.id}`) → không gỡ thì mỗi
+        // trang/mỗi lần refresh để lại một record vĩnh viễn.
+        if (this.markerKey) {
+            markerRegistry.remove(this.markerKey);
+            this.markerKey = null;
+        }
+        this.stop();
         this.clearContent();
+        // Giải phóng cache — clearContent() đã destroy các elements
+        if (this._foreachCache) {
+            this._foreachCache.clear();
+        }
         this.openTag.remove();
         this.closeTag.remove();
         this.mounted = false;
@@ -244,10 +521,10 @@ export class Reactive implements ReactiveInterface {
     set isOneReactive(value: boolean) {
         // No-op setter to satisfy the Interface; this property is always true for Reactive elements
     }
-    set isOneElement(value: boolean) {
+    set isSaoElement(value: boolean) {
         // No-op setter to satisfy the Interface; Reactive is a type of OneElement
     }
-    get isOneElement(): boolean {
+    get isSaoElement(): boolean {
         return true;
     }
-}
+}

package/src/core/elements/TextElement.ts

@@ -1,7 +1,6 @@
-import type { HtmlInterface, TextInterface } from "../contracts/ElementInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { escapeHTML } from "../hellpers/utils";
-import { OneObjectType } from "../types/utils";
+import type { HtmlInterface, TextInterface } from "../contracts/ElementInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { SaoObjectType } from "../types/utils.js";
 
 /**
  * TextElement — wraps a DOM Text node.
@@ -11,7 +10,7 @@ import { OneObjectType } from "../types/utils";
  * no DOM removal/insertion needed.
  */
 export class TextElement implements TextInterface {
-    oneType: OneObjectType = 'TextElement';
+    saoType: SaoObjectType = 'TextElement';
     public element: Text;
     public parent: HtmlInterface | null;
     private ctx: ViewControllerInterface;
@@ -22,6 +21,7 @@ export class TextElement implements TextInterface {
     public shouldEscapeHTML: boolean = true; // Whether to escape HTML in text content
 
     public isStarted: boolean = false;
+    readonly isStatic: boolean;
 
 
     domChildren: Node[] = []; // For compatibility with HtmlInterface; Text itself doesn't have a single root element
@@ -30,11 +30,11 @@ export class TextElement implements TextInterface {
         this.generateText = generateText;
         this.parent = parent;
         this.statekeys = stateKeys;
+        this.isStatic = stateKeys.length === 0;
         this.shouldEscapeHTML = isEscapeHTML;
+        // FIX(baseline#3): KHÔNG escapeHTML khi ghi vào Text node — text node tự an toàn,
+        // escape thủ công gây double-escape. shouldEscapeHTML chỉ dùng cho SSR string path.
         this._text = this.generateText();
-        if (this.shouldEscapeHTML) {
-            this._text = escapeHTML(this._text);
-        }
         this.element = document.createTextNode(this._text);
     }
 
@@ -57,28 +57,37 @@ export class TextElement implements TextInterface {
         }
     }
     setParentElement(parent: HtmlInterface | null): void {
-        
+        this.parent = parent;
     }
 
     /** Update text content in-place */
     update(newText: string): void {
         if (this._text !== newText) {
             this._text = newText;
-            this.element.textContent = this.shouldEscapeHTML ? escapeHTML(newText) : newText;
+            this.element.textContent = newText;
         }
     }
 
-    render(): void {
-        if (this.parent && this.parent.element) {
-            this.parent.element.appendChild(this.element);
-        }
+    render(): HTMLElement | Text | Comment {
+        const text = this.generateText();
+        this.update(text);
+        return this.element;
+    }
+
+    replaceStaticText(text: string): void {
+        this.generateText = () => text;
+        this.update(text);
     }
 
     remove(): void {
         this.element.remove();
     }
 
+    /** Registry guard — element đã destroy không được reuse */
+    public __destroyed__: boolean = false;
+
     destroy(): void {
+        this.__destroyed__ = true;
         if (this.unsubscribe) {
             this.unsubscribe();
             this.unsubscribe = null;
@@ -95,10 +104,10 @@ export class TextElement implements TextInterface {
         this.update(newText);
     }
 
-    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 Text elements
     }
     get isOneText(): boolean {