@saolabs/client 1.0.0 → 1.1.0

package/src/core/elements/Wrapper.ts

@@ -1,8 +1,13 @@
-import { InitMode, InitModes } from "../contracts/common";
-import type { FragmentInterface, HtmlInterface, OneChildrenFactory, OneChildrenFactoryOutput, OneElementChildren, WrapperInterface } from "../contracts/ElementInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { generateUUID } from "../hellpers/utils";
-import type { OneObjectType } from "../types/utils";
+import { InitMode, InitModes } from "../contracts/common.js";
+import type { DOMElement, FragmentInterface, HtmlInterface, SaoChildrenFactory, SaoChildrenFactoryOutput, SaoElement, SaoElementChildren, WrapperInterface } from "../contracts/ElementInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { app } from "../helpers/app.js";
+import { generateUUID } from "../helpers/utils.js";
+import { mountElementList } from "../helpers/view.js";
+import { MarkerRegistryService } from "../services/index.js";
+import type { SaoObjectType } from "../types/utils.js";
+import { Html } from "./Html.js";
+import { TextElement } from "./TextElement.js";
 
 /**
  * Wrapper — renders multiple root nodes into a parent without a wrapping tag.
@@ -14,13 +19,13 @@ import type { OneObjectType } from "../types/utils";
  * similar to Reactive but without the reactivity overhead.
  */
 export class Wrapper implements WrapperInterface {
-    oneType: OneObjectType = 'Wrapper';
+    saoType: SaoObjectType = 'Wrapper';
     public parent: HtmlInterface | null;
     public nodes: Node[] = [];
     /** Tracked child element wrappers (Html, Output, Reactive, TextElement, etc.) */
-    public children: OneElementChildren = [];
+    public children: SaoElementChildren = [];
     private ctx: ViewControllerInterface;
-    private childrenFactory: OneChildrenFactory;
+    private childrenFactory: SaoChildrenFactory;
     public openTag: Comment;
     public closeTag: Comment;
     public id: string; // Unique ID for debugging and marker registry
@@ -37,7 +42,7 @@ export class Wrapper implements WrapperInterface {
         ctx: ViewControllerInterface,
         initMode?: InitMode,
         parentElement?: HtmlInterface | null,
-        childrenFactory: OneChildrenFactory
+        childrenFactory: SaoChildrenFactory
     }) {
         this.ctx = ctx;
         this.parent = parentElement;
@@ -45,18 +50,75 @@ export class Wrapper implements WrapperInterface {
         this.id = ctx.viewId;
         this.initMode = initMode;
 
-        this.openTag = document.createComment('wrapper-start');
-        this.closeTag = document.createComment('wrapper-end');
+        this.init();
+        const registry = app<MarkerRegistryService>("Registry");
+        if (this.initMode === InitModes.HYDRATE) {
+            // ── Hydrate: tìm view markers SSR trong DOM ─────────────────
+            // Format MarkerRegistry: open = `v:id`, close = `/v:id`
+            // (v = shortcut cho 'view'). Nếu không có (vd partial hydration
+            // khi root element CHÍNH là boundary của view) → tạo markers mới,
+            // không cảnh báo vì đây là trường hợp hợp lệ.
+            const claimed = this.claimSSRMarkers(registry);
+            if (claimed) {
+                this.openTag = claimed.open;
+                this.closeTag = claimed.close;
+            } else {
+                this.openTag = registry.createMarkerStart('view', this.id);
+                this.closeTag = registry.createMarkerEnd('view', this.id);
+            }
+        }
+        else {
+            this.openTag = registry.createMarkerStart('view', this.id);
+            this.closeTag = registry.createMarkerEnd('view', this.id);
+        }
+
+    }
+
+    /**
+     * Tìm cặp view markers từ server-rendered HTML.
+     * Format MarkerRegistry: open = `v:id`, close = `/v:id`.
+     * Quét comment nodes trong parent element (fallback document.body).
+     */
+    private claimSSRMarkers(
+        registry: MarkerRegistryService
+    ): { open: Comment; close: Comment } | null {
+        return registry.claim('view', this.id, this.parent?.element ?? null);
+    }
+
+    init() {
 
     }
+
+
     setParentElement(parent: HtmlInterface | null): void {
         this.parent = parent;
     }
-    render(): void {
-        
+    render(): SaoElementChildren {
+        this.children = [];
+        const children = this.childrenFactory(this.parent);
+        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, parent: this.parent, stateKeys: [], generateText: () => String(child) });
+                }
+                return child;
+            });
+        return this.children;
+    }
+    appendTo(parent: HtmlInterface): void {
+        this.parent = parent;
+        this.parent.appendElement(this.openTag);
+        mountElementList(this.parent, this.render());
+        this.parent.appendElement(this.closeTag);
+    }
+
+    mountTo(parent: HtmlInterface): void {
+        parent.clearHTML();
+        this.appendTo(parent);
     }
 
-    setChildrenFactory(factory: OneChildrenFactory): void {
+    setChildrenFactory(factory: SaoChildrenFactory): void {
         this.childrenFactory = factory;
     }
 
@@ -108,24 +170,28 @@ export class Wrapper implements WrapperInterface {
         this.nodes = [];
     }
 
+    /** Registry guard — wrapper đã destroy không được reuse (ViewController.wrapper) */
+    public __destroyed__: boolean = false;
+
     destroy(): void {
+        this.__destroyed__ = true;
         this.clear();
         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 setter to satisfy the Interface; this property is always true for Fragment elements
     }
 
-    get isOneFragment(): boolean {
+    get isSaoFragment(): boolean {
         return true;
     }
-    set isOneFragment(value: boolean) {
+    set isSaoFragment(value: boolean) {
         // No-op setter to satisfy the Interface; this property is always true for Fragment elements
     }
 }

package/src/core/elements/Yield.ts

@@ -1,54 +1,63 @@
-import { InitMode, InitModes } from "../contracts/common";
-import { HtmlInterface, OneChildrenFactoryOutput, YieldInterface } from "../contracts/ElementInterface";
-import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { generateUUID } from "../hellpers/utils";
-import { MarkerModel, OneMarker } from "../services/MarkerService";
-import { OneObjectType } from "../types/utils";
+import { InitMode, InitModes } from "../contracts/common.js";
+import { HtmlInterface, YieldInterface } from "../contracts/ElementInterface.js";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import { SaoObjectType } from "../types/utils.js";
 
 export class YieldElement implements YieldInterface{
-    oneType: OneObjectType = "Yield";
+    saoType: SaoObjectType = "Yield";
     ctx: ViewControllerInterface;
     name: string
     id: string;
-    contentFactory: () => OneChildrenFactoryOutput = () => [];
     openTag!: Comment;
     closeTag!: Comment;
     initMode: InitMode = InitModes.CREATE
     domChildren: Node[] = [];
     parent: HtmlInterface | null = null;
     defaultValue: string = '';
+    /** Registry guard — thiếu field này thì aliveFromRegistry tái dùng Yield đã destroy */
+    public __destroyed__: boolean = false;
     constructor({ctx, name = '', initMode = InitModes.CREATE, id = null, defaultValue = ''} : {ctx: ViewControllerInterface, name: string, initMode?: InitMode, id?: string | null, defaultValue?: string}) {
         this.ctx = ctx;
         this.name = name;
         this.initMode = initMode;
-        this.id = id && id.length > 0 ? id : generateUUID();
+        // Marker id đầy đủ = {viewId}-{hash} — khớp quy ước server (HYDRATION.md §5.1),
+        // giống Component.ts. Trước đây thiếu prefix viewId → hydrate không tìm đúng marker.
+        const rawId = id && id.length > 0 ? id : generateUUID();
+        this.id = `${ctx.viewId}-${rawId}`;
         this.defaultValue = defaultValue;
-        
-        const yeildMarker: MarkerModel | null = (this.initMode === InitModes.HYDRATE) ? OneMarker.first('yield', this.id) : null;
-        if(yeildMarker){
-            this.openTag = yeildMarker.openTag;
-            this.closeTag = yeildMarker.closeTag;
-            this.domChildren = yeildMarker.nodes.map((el: Node) => el);
+
+        // Claim marker server qua index O(1) của MarkerRegistry — giống Reactive/
+        // Output/Component. Bản cũ duyệt TOÀN BỘ comment của tài liệu cho mỗi @yield.
+        const claimed = (this.initMode === InitModes.HYDRATE)
+            ? markerRegistry.claim('yield', this.id)
+            : null;
+
+        if (claimed) {
+            this.openTag = claimed.open;
+            this.closeTag = claimed.close;
+            for (let node = claimed.open.nextSibling; node && node !== claimed.close; node = node.nextSibling) {
+                this.domChildren.push(node);
+            }
         } else {
             this.createMarkers();
         }
         
     }
     private createMarkers(){
-        const key = OneMarker.addRegistry('yield', this.id, {name: this.name});
-        this.openTag = OneMarker.createOpenMarker('yield', this.id);
-        this.closeTag = OneMarker.createCloseMarker('yield', this.id);
+        markerRegistry.register('yield', this.id, {name: this.name});
+        this.openTag = markerRegistry.createMarkerStart('yield', this.id);
+        this.closeTag = markerRegistry.createMarkerEnd('yield', this.id);
     }
 
     setParentElement(parent: HtmlInterface | null): void {
         this.parent = parent;
     }
 
-    setContentFactory(factory: () => OneChildrenFactoryOutput): void {
-        this.contentFactory = factory;
-    }
-
+    /** Idempotent: markers already in DOM (hydrate claim, or same-layout reuse) → keep as-is. */
     render(): void {
+        if (this.openTag.parentNode) return;
         if (!this.parent?.element) return;
 
         const parentEl = this.parent.element;
@@ -57,14 +66,16 @@ export class YieldElement implements YieldInterface{
     }
 
     destroy(): void {
+        this.__destroyed__ = true;
+        this.ctx.releaseElement?.(this);
         this.openTag?.remove();
         this.closeTag?.remove();
         this.domChildren = [];
         this.parent = null;
     }
 
-    get isOneElement(): boolean { return true; }
-    set isOneElement(_: boolean) {}
+    get isSaoElement(): boolean { return true; }
+    set isSaoElement(_: boolean) {}
     get isOneYield(): boolean { return true; }
     set isOneYield(_: boolean) {}
 }

package/src/core/elements/helpers.ts

@@ -1,12 +1,12 @@
-import { BlockInterface, BlockOutletInterface } from "../contracts/BlockInterface";
-import { FragmentInterface, HtmlInterface, OutputInterface, OneChildrenFactoryOutput, OneElementChildren } from "../contracts/ElementInterface";
-import { ReactiveInterface } from "../contracts/ReactiveInterface";
-import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { OneObjectType } from "../types/utils";
+import { BlockInterface, BlockOutletInterface } from "../contracts/BlockInterface.js";
+import { FragmentInterface, HtmlInterface, OutputInterface, SaoChildrenFactoryOutput, SaoElementChildren } from "../contracts/ElementInterface.js";
+import { ReactiveInterface } from "../contracts/ReactiveInterface.js";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { SaoObjectType } from "../types/utils.js";
 
-export function getOneObjectType(instance: any): OneObjectType | null {
-    if (instance && typeof instance === 'object' && 'oneType' in instance) {
-        return instance.oneType;
+export function getSaoObjectType(instance: any): SaoObjectType | null {
+    if (instance && typeof instance === 'object' && 'saoType' in instance) {
+        return instance.saoType;
     }
     return null;
 }
@@ -14,9 +14,9 @@ export function getOneObjectType(instance: any): OneObjectType | null {
 export function parseElementChildren(
     oneElement: HtmlInterface | ReactiveInterface | BlockOutletInterface | OutputInterface | FragmentInterface | ViewControllerInterface, 
     parentElement: HTMLElement,
-    children: OneChildrenFactoryOutput
-): OneElementChildren {
-    const parsedChildren: OneElementChildren = [];
+    children: SaoChildrenFactoryOutput
+): SaoElementChildren {
+    const parsedChildren: SaoElementChildren = [];
 
     if(!children || !Array.isArray(children)) {
         console.warn('Children factory returned invalid output (not an array):', children);
@@ -39,7 +39,7 @@ export function parseElementChildren(
             console.warn('Skipping invalid child:', child);
             return;
         } 
-        let childType: OneObjectType = getOneObjectType(child);
+        let childType: SaoObjectType = getSaoObjectType(child);
         if(!childType) {
             return;
         }

package/src/core/elements/index.ts

@@ -1,26 +1,27 @@
-import type { BlockOutletInterface, BlockRenderFactory } from "../contracts/BlockInterface";
-import type { HtmlInterface, HtmlElementConfig, OneChildrenFactory } from "../contracts/ElementInterface";
-import type { ReactiveChildrenFactory } from "../contracts/ReactiveInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { ViewController } from "../view";
-import { Block } from "./Block";
-import BlockManager from "../services/BlockManager";
-import { BlockOutlet } from "./BlockOutlet";
-import { Fragment } from "./Fragment";
-import { Html } from "./Html";
-import { Output } from "./Output";
-import { Reactive } from "./Reactive";
-import { TextElement } from "./TextElement";
+import type { BlockOutletInterface, BlockRenderFactory } from "../contracts/BlockInterface.js";
+import type { HtmlInterface, HtmlElementConfig, SaoChildrenFactory } from "../contracts/ElementInterface.js";
+import type { ReactiveChildrenFactory } from "../contracts/ReactiveInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { ViewController } from "../view/index.js";
+import { Block } from "./Block.js";
+import BlockManager from "../services/BlockManager.js";
+import { BlockOutlet } from "./BlockOutlet.js";
+import { Fragment } from "./Fragment.js";
+import { Html } from "./Html.js";
+import { Output } from "./Output.js";
+import { Reactive } from "./Reactive.js";
+import { TextElement } from "./TextElement.js";
 
 
-export * from "./Block";
-export * from "./BlockOutlet";
-export * from './Component';
-export * from "./ElementManager";
-export * from "./Fragment";
-export * from "./helpers";
-export * from "./Html";
-export * from "./Output";
-export * from './Reactive';
-export * from "./TextElement";
-export * from "./Yield";
+export * from "./Block.js";
+export * from "./BlockOutlet.js";
+export * from './Component.js';
+export * from "./ElementManager.js";
+export * from "./Fragment.js";
+export * from "./helpers.js";
+export * from "./Html.js";
+export * from "./Output.js";
+export * from './Reactive.js';
+export * from './ForeachSlotCache.js';
+export * from "./TextElement.js";
+export * from "./Yield.js";

package/src/core/elements/reconcileChildren.ts

@@ -0,0 +1,70 @@
+import { TextElement } from './TextElement.js';
+
+/** Static compiler text has no lifecycle state; retain its existing Text node. */
+export function reuseStaticText(previous: readonly any[], next: any[]): any[] {
+    return next.map((child, index) => {
+        const old = previous[index];
+        if (old instanceof TextElement && child instanceof TextElement && old !== child
+            && old.isStatic && child.isStatic && !old.__destroyed__) {
+            old.replaceStaticText(child.text);
+            child.destroy();
+            return old;
+        }
+        return child;
+    });
+}
+
+/** Place an element or marker range without touching nodes already in order. */
+export function placeChild(parent: Node, child: any, before: Node | null): Node | null {
+    const first: Node | undefined = child instanceof Node ? child : child.element ?? child.openTag;
+    const last: Node | undefined = child instanceof Node ? child : child.element ?? child.closeTag;
+    if (!first || !last) return before;
+    if (first.parentNode === parent && last.parentNode === parent && last.nextSibling === before) return first;
+    const nodes: Node[] = [first];
+    if (first !== last) {
+        let current = first.nextSibling;
+        while (current && current !== last) {
+            nodes.push(current);
+            current = current.nextSibling;
+        }
+        nodes.push(last);
+    }
+    for (const node of nodes) {
+        // State-preserving native moves where available; detached/new nodes use
+        // normal insertion. Older browsers use the focus restoration below.
+        const moveBefore = (parent as any).moveBefore;
+        if (typeof moveBefore === 'function' && node.isConnected && parent.isConnected) moveBefore.call(parent, node, before);
+        else parent.insertBefore(node, before);
+    }
+    return first;
+}
+
+/** Reconcile Saola children by wrapper identity; factories refresh their config. */
+export function reconcileChildren(
+    parent: Node, previous: readonly any[], next: readonly any[],
+    anchor: Node | null = null, refresh: (child: any) => boolean = () => true,
+): void {
+    const focused = parent.ownerDocument?.activeElement as HTMLElement | null;
+    const containsFocus = focused && parent.contains(focused);
+    const selection = containsFocus && 'selectionStart' in focused
+        ? { start: (focused as HTMLInputElement).selectionStart, end: (focused as HTMLInputElement).selectionEnd,
+            direction: (focused as HTMLInputElement).selectionDirection } : null;
+    const nextSet = new Set(next);
+    const oldSet = new Set(previous);
+    for (const child of previous) {
+        if (nextSet.has(child)) continue;
+        if (typeof child.destroy === 'function') child.destroy();
+        else if (child instanceof Node) child.parentNode?.removeChild(child);
+    }
+    let before = anchor;
+    for (let i = next.length - 1; i >= 0; i--) before = placeChild(parent, next[i], before);
+    for (const child of next) {
+        if (!oldSet.has(child) || refresh(child)) child.render?.();
+    }
+    if (containsFocus && focused.isConnected && parent.ownerDocument?.activeElement !== focused) {
+        focused.focus({ preventScroll: true });
+        if (selection?.start != null && selection.end != null) {
+            (focused as HTMLInputElement).setSelectionRange(selection.start, selection.end, selection.direction ?? undefined);
+        }
+    }
+}

package/src/core/{hellpers → helpers}/ApiClient.ts

@@ -47,7 +47,14 @@ export class ApiClient implements APIClientInterface {
     }
 
     init(config: Record<string, any>): void {
-        // Placeholder for any future initialization logic
+        if (typeof config.baseUrl === 'string') this.http.setBaseUrl(config.baseUrl);
+        if (typeof config.timeout === 'number') this.http.setTimeout(config.timeout);
+        for (const [name, value] of Object.entries(config.headers || {})) {
+            this.http.setHeader(name, String(value));
+        }
+        if (config.endpoints && typeof config.endpoints === 'object') {
+            this.endpoints = { ...this.endpoints, ...config.endpoints };
+        }
     }
 
     /**

package/src/core/{hellpers → helpers}/app.ts

@@ -1,5 +1,5 @@
-import { Application } from "../app/Application";
-import { AppFactory, ServiceKey } from "../contracts/ApplicationInterface";
+import { Application } from "../app/Application.js";
+import { AppFactory, ServiceKey } from "../contracts/ApplicationInterface.js";
 
 
 /**
@@ -8,6 +8,12 @@ import { AppFactory, ServiceKey } from "../contracts/ApplicationInterface";
  */
 const AppInstance = new Application();
 
+// Tự đăng ký container dưới key 'App' — compiled view luôn gọi `app("App")`
+// để lấy Application (App.View, App.Helper, App.Router...). Thiếu dòng này thì
+// mọi view compiled ném "Cannot resolve: App". (Unit test cũ dùng `new View()`
+// trực tiếp nên không lộ; chỉ lộ khi chạy view compiled thật trên trình duyệt.)
+AppInstance.instance('App', AppInstance);
+
 /**
  * Helper function để lấy/đăng ký services
  * Cách dùng:
@@ -35,6 +41,11 @@ const appFactory = <T>(key?: ServiceKey, value?: any): Application | T | any | v
         // Không truyền gì → trả về container
         return AppInstance;
     }
+    // Compiler contract: mọi generated view dùng app("App"). Alias này phải
+    // tồn tại cả sau flush()/test teardown, không phụ thuộc singleton map.
+    if (key === 'App' && value === undefined) {
+        return AppInstance;
+    }
     if (value !== undefined) {
         // Truyền 2 tham số → đăng ký instance
         AppInstance.instance(key, value);

package/src/core/helpers/transition.ts

@@ -0,0 +1,127 @@
+/**
+ * Transition enter/leave cho element — `@transition('fade')`.
+ *
+ * # Quy ước class (giống Vue, để người dùng không phải học lại)
+ *   enter: `{n}-enter-from` `{n}-enter-active` → frame sau → `{n}-enter-to`
+ *   leave: `{n}-leave-from` `{n}-leave-active` → frame sau → `{n}-leave-to`
+ * `-active` có mặt suốt quá trình (chỗ đặt `transition:`), `-from`/`-to` là
+ * hai đầu giá trị.
+ *
+ * # Vì sao dùng `getAnimations()` chứ không nghe `transitionend`
+ * `transitionend` bắn MỘT lần cho MỖI property, không bắn nếu giá trị không
+ * đổi, và không phân biệt transition của element với của con nó — nên cách
+ * làm kinh điển phải parse `transition-duration` + hẹn giờ dự phòng.
+ * `element.getAnimations()` trả thẳng mọi animation/transition đang chạy trên
+ * element kèm promise `.finished`, xử lý đúng cả trường hợp nhiều property và
+ * bị huỷ giữa chừng. Không có animation nào → resolve ngay → hành vi y hệt
+ * lúc chưa có transition (đây cũng là đường chạy trong jsdom).
+ *
+ * # Vì sao cần `isLeaving()`
+ * Element rời đi phải NẰM LẠI DOM tới khi animation xong, trong khi
+ * `Reactive.clearContent()`/`_cleanOrphanNodes()` quét sạch mọi node giữa cặp
+ * marker. Hai vòng quét đó phải bỏ qua node đang leave, nếu không node bị giật
+ * đi ngay và animation không bao giờ thấy được.
+ */
+
+/** Node đang chạy leave — vòng quét DOM giữa marker phải BỎ QUA. */
+const leavingNodes = new WeakSet<Node>();
+
+/** Sequence hiện tại của mỗi element — chống enter/leave chồng nhau (reorder). */
+const generation = new WeakMap<Element, number>();
+
+/** True khi node đang chạy leave và chưa được gỡ. */
+export function isLeaving(node: Node): boolean {
+    return leavingNodes.has(node);
+}
+
+function bump(el: Element): number {
+    const next = (generation.get(el) ?? 0) + 1;
+    generation.set(el, next);
+    return next;
+}
+
+const isCurrent = (el: Element, token: number) => generation.get(el) === token;
+
+/** Đợi sang frame kế — để trình duyệt kịp áp `-from` trước khi đổi sang `-to`. */
+function nextFrame(): Promise<void> {
+    return new Promise(resolve => {
+        if (typeof requestAnimationFrame !== 'function') return resolve();
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+/**
+ * Đợi mọi animation/transition trên element kết thúc.
+ * `allSettled` vì `.finished` REJECT khi animation bị huỷ — với ta thì huỷ
+ * cũng là xong, không phải lỗi.
+ *
+ * ponytail: animation vô hạn (`animation-iteration-count: infinite`) trên
+ * element đang leave sẽ giữ node lại mãi. Thêm timeout trần nếu gặp thật.
+ */
+async function whenAnimationsDone(el: Element): Promise<void> {
+    const getAnimations = (el as any).getAnimations;
+    if (typeof getAnimations !== 'function') return;   // jsdom / browser cũ
+    const running = getAnimations.call(el) as Animation[];
+    if (!running || running.length === 0) return;
+    await Promise.allSettled(running.map(a => a.finished));
+}
+
+const classesOf = (name: string, phase: 'enter' | 'leave') => ({
+    from: `${name}-${phase}-from`,
+    active: `${name}-${phase}-active`,
+    to: `${name}-${phase}-to`,
+});
+
+/** Gỡ mọi class transition của cả 2 phase — dùng khi bị huỷ giữa chừng. */
+function clearClasses(el: Element, name: string): void {
+    for (const phase of ['enter', 'leave'] as const) {
+        const c = classesOf(name, phase);
+        el.classList.remove(c.from, c.active, c.to);
+    }
+}
+
+/** Chạy enter. Bị enter/leave khác chen ngang → thoát, không đụng DOM nữa. */
+export async function runEnter(el: Element, name: string): Promise<void> {
+    const token = bump(el);
+    const c = classesOf(name, 'enter');
+
+    clearClasses(el, name);
+    el.classList.add(c.from, c.active);
+
+    await nextFrame();
+    if (!isCurrent(el, token)) return;
+
+    el.classList.remove(c.from);
+    el.classList.add(c.to);
+
+    await whenAnimationsDone(el);
+    if (!isCurrent(el, token)) return;
+
+    el.classList.remove(c.active, c.to);
+}
+
+/**
+ * Chạy leave rồi GỠ node. Trả promise resolve sau khi node đã rời DOM.
+ * Element được đánh dấu leaving ngay lập tức để không ai giật mất giữa chừng.
+ */
+export async function runLeave(el: Element, name: string): Promise<void> {
+    const token = bump(el);
+    const c = classesOf(name, 'leave');
+
+    leavingNodes.add(el);
+    clearClasses(el, name);
+    el.classList.add(c.from, c.active);
+
+    await nextFrame();
+    if (!isCurrent(el, token)) { leavingNodes.delete(el); return; }
+
+    el.classList.remove(c.from);
+    el.classList.add(c.to);
+
+    await whenAnimationsDone(el);
+    if (!isCurrent(el, token)) { leavingNodes.delete(el); return; }
+
+    leavingNodes.delete(el);
+    el.classList.remove(c.active, c.to);
+    (el as ChildNode).remove();
+}

package/src/core/{hellpers → helpers}/utils.ts

@@ -80,8 +80,8 @@ export function isTextNode(value: any): boolean {
     return value instanceof Text;
 }
 
-export function isOneElement(value: any): boolean {
-    return value && typeof value === 'object' && 'isOneElement' in value && value.isOneElement === true;
+export function isSaoElement(value: any): boolean {
+    return value && typeof value === 'object' && 'isSaoElement' in value && value.isSaoElement === true;
 }
 
 export function isOneHtml(value: any): boolean {
@@ -100,8 +100,8 @@ export function isOneReactive(value: any): boolean {
     return value && typeof value === 'object' && 'isOneReactive' in value && value.isOneReactive === true;
 }
 
-export function isOneFragment(value: any): boolean {
-    return value && typeof value === 'object' && 'isOneFragment' in value && value.isOneFragment === true;
+export function isSaoFragment(value: any): boolean {
+    return value && typeof value === 'object' && 'isSaoFragment' in value && value.isSaoFragment === true;
 }
 
 export function isOneBlock(value: any): boolean {