@saolabs/client 1.0.0 → 1.0.2

package/src/core/bootstrap/providers/provider-order.test.ts

@@ -1,14 +1,11 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it, expect } from "vitest";
 import { NamedServiceProvider, resolveProviderOrder, PROVIDER_NAMES } from "./provider-order";
 
 function provider(name: string, dependsOn: string[] = []): NamedServiceProvider {
     return {
         name,
         dependsOn,
-        register() {
-            // noop for ordering test
-        }
+        register() {},
     };
 }
 
@@ -22,7 +19,7 @@ describe("resolveProviderOrder", () => {
         ]);
 
         const names = ordered.map((item) => item.name);
-        assert.deepEqual(names, ["core", "view", "router", "api"]);
+        expect(names).toEqual(["core", "view", "router", "api"]);
     });
 
     it("works with PROVIDER_NAMES constants", () => {
@@ -33,35 +30,27 @@ describe("resolveProviderOrder", () => {
         ]);
 
         const names = ordered.map((p) => p.name);
-        assert.equal(names.indexOf(PROVIDER_NAMES.CORE), 0);
-        assert.ok(names.indexOf(PROVIDER_NAMES.VIEW) < names.indexOf(PROVIDER_NAMES.ROUTER));
+        expect(names.indexOf(PROVIDER_NAMES.CORE)).toBe(0);
+        expect(names.indexOf(PROVIDER_NAMES.VIEW)).toBeLessThan(names.indexOf(PROVIDER_NAMES.ROUTER));
     });
 
     it("throws for missing dependency", () => {
-        assert.throws(
-            () => resolveProviderOrder([provider("view", ["core"])]),
-            /Missing provider dependency/
-        );
+        expect(() => resolveProviderOrder([provider("view", ["core"])]))
+            .toThrow(/Missing provider dependency/);
     });
 
     it("throws for circular dependency", () => {
-        assert.throws(
-            () => resolveProviderOrder([
-                provider("a", ["b"]),
-                provider("b", ["c"]),
-                provider("c", ["a"])
-            ]),
-            /Circular service provider dependency/
-        );
+        expect(() => resolveProviderOrder([
+            provider("a", ["b"]),
+            provider("b", ["c"]),
+            provider("c", ["a"])
+        ])).toThrow(/Circular service provider dependency/);
     });
 
     it("throws for duplicate provider names", () => {
-        assert.throws(
-            () => resolveProviderOrder([
-                provider("core"),
-                provider("core")
-            ]),
-            /Duplicate provider name/
-        );
+        expect(() => resolveProviderOrder([
+            provider("core"),
+            provider("core")
+        ])).toThrow(/Duplicate provider name/);
     });
 });

package/src/core/bootstrap/providers/provider-order.ts

@@ -1,4 +1,4 @@
-import type { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface";
+import type { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface.js";
 
 /**
  * Tên các provider mặc định — dùng constant thay vì magic string.

package/src/core/bootstrap/ssr.ts

@@ -0,0 +1,136 @@
+/**
+ * SSR boot detection — đọc thông tin server nhúng để hydrate route đầu tiên.
+ * Tham chiếu: RUNTIME_CONTRACT.md §6 (Hydration boot).
+ */
+
+/** Thông tin boot server nhúng cho trang server-rendered. */
+export interface SSRBootInfo {
+    /** Registry path của page entry (vd 'web.modules.home'). */
+    view: string;
+    /** viewId server đã dùng prefix markers/classes của page. */
+    viewId: string;
+    /** CSS selector container chứa SSR HTML (mặc định '#app-root'). */
+    container?: string;
+}
+
+/**
+ * Đọc SSR boot info từ DOM:
+ *
+ *   <script type="application/json" data-ref="saola-ssr">
+ *     { "container": "#app-root", "view": "web.modules.home", "viewId": "v_abc" }
+ *   </script>
+ *
+ * viewId của layout chain được đọc từ APP_CONFIGS.view.ssrData khi server có
+ * cung cấp; DOM marker chỉ là fallback tương thích cho output cũ.
+ * Trả null nếu không phải trang server-rendered → CSR boot bình thường.
+ */
+export function readSSRBoot(): SSRBootInfo | null {
+    if (typeof document === 'undefined') return null;
+    const el = document.querySelector('script[type="application/json"][data-ref="saola-ssr"]');
+    if (!el || !el.textContent) return null;
+    try {
+        const info = JSON.parse(el.textContent);
+        if (info && typeof info.view === 'string' && typeof info.viewId === 'string') {
+            return {
+                view: info.view,
+                viewId: info.viewId,
+                container: typeof info.container === 'string' ? info.container : undefined,
+            };
+        }
+    } catch (e) {
+        console.warn('[Bootstrap] SSR boot JSON không hợp lệ:', e);
+    }
+    return null;
+}
+
+/**
+ * Đọc boot config server nhúng qua `window.APP_CONFIGS` (contract server hiện tại)
+ * và map về shape config của client (`{ view, router, api }`).
+ *
+ * Server (`_system/page/end.blade.php`) đã emit:
+ *   window.APP_CONFIGS = {
+ *     container: '#app-root',
+ *     router: { mode, base, allRoutes: [{name,path,params,component}], ... },
+ *     ...
+ *   }
+ * `allRoutes` đã đúng shape `Router.addRoutes` cần ({path, component}).
+ *
+ * Trả null nếu không có APP_CONFIGS (→ app tự truyền config cho App.start).
+ */
+export function readBootConfig(): Record<string, any> | null {
+    if (typeof window === 'undefined') return null;
+    const cfg = (window as any).APP_CONFIGS;
+    if (!cfg || typeof cfg !== 'object') return null;
+
+    const out: Record<string, any> = {};
+    if (cfg.i18n && typeof cfg.i18n === "object") out.i18n = cfg.i18n;
+
+    // view.systemData (server: __layout__/__base__/__page__/...) PHẢI tới được
+    // ViewManager: compiled factory destructure `__layout__` từ systemData để
+    // resolve superView (`${__layout__+"base"}`). Thiếu → 'undefinedbase' →
+    // "View not found in registry" + page render() trả rỗng.
+    const view: Record<string, any> = {};
+    if (typeof cfg.container === 'string') {
+        view.container = cfg.container;
+    }
+    if (typeof cfg.view?.dataEndpoint === 'string') view.dataEndpoint = cfg.view.dataEndpoint;
+    if (cfg.view?.fetchOptions && typeof cfg.view.fetchOptions === 'object') view.fetchOptions = cfg.view.fetchOptions;
+    if (cfg.api && typeof cfg.api === 'object') out.api = cfg.api;
+
+    if (cfg.view?.systemData && typeof cfg.view.systemData === 'object') {
+        view.systemData = cfg.view.systemData;
+    }
+    if (typeof cfg.view?.revision === 'string') {
+        view.revision = cfg.view.revision;
+    }
+    if (typeof cfg.view?.contextViews === 'string') {
+        view.contextViews = cfg.view.contextViews;
+    }
+    if (cfg.view?.ssrData && typeof cfg.view.ssrData === 'object') {
+        view.ssrData = cfg.view.ssrData;
+    }
+    if (Object.keys(view).length > 0) {
+        out.view = view;
+    }
+
+    // Danh sách bundle nạp rời (theme…) — server là chỗ DUY NHẤT biết theme nào
+    // đang bật, nên client không đoán đường dẫn. Xem EXTENSION_ARCHITECTURE §8.
+    if (Array.isArray(cfg.bundles)) {
+        out.bundles = cfg.bundles.filter((u: unknown) => typeof u === 'string' && u !== '');
+    }
+
+    const routes = cfg.router?.allRoutes ?? cfg.router?.routes;
+    if (Array.isArray(routes)) {
+        out.router = {
+            mode: cfg.router?.mode ?? 'history',
+            base: cfg.router?.base,
+            defaultRoute: cfg.router?.defaultRoute,
+            routes,
+        };
+    }
+
+    return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * Merge nông 2 tầng config boot (base) với config app truyền (override).
+ * Per top-level key (view/router/api): nếu cả hai là object thì merge nông,
+ * ngược lại override thắng. Dùng để config app truyền có ưu tiên hơn boot.
+ */
+export function mergeBootConfig(
+    base: Record<string, any>,
+    override: Record<string, any>
+): Record<string, any> {
+    const out: Record<string, any> = { ...base };
+    for (const key of Object.keys(override)) {
+        const b = out[key];
+        const o = override[key];
+        if (b && o && typeof b === 'object' && typeof o === 'object'
+            && !Array.isArray(b) && !Array.isArray(o)) {
+            out[key] = { ...b, ...o };
+        } else {
+            out[key] = o;
+        }
+    }
+    return out;
+}

package/src/core/cache/ViewCache.ts

@@ -1,4 +1,4 @@
-import type { ViewCacheInterface } from "../contracts/ViewCacheInterface";
+import type { ViewCacheInterface } from "../contracts/ViewCacheInterface.js";
 
 /**
  * ViewCache — stores rendered view DOM for instant restore on navigation.

package/src/core/cache/index.ts

@@ -1 +1 @@
-export { ViewCache } from './ViewCache';
+export { ViewCache } from './ViewCache.js';

package/src/core/contracts/ApplicationInterface.ts

@@ -1,15 +1,16 @@
 // ─── Application Interface ───────────────────────────────────────
 
-import { RouterInterface, ViewManagerInterface } from "./utils";
-import type { HelperInterface } from "./HelperInterface";
-import type { EventServiceInterface } from "./EventServiceInterface";
-import type { HttpServiceInterface } from "./HttpServiceInterface";
-import type { StoreServiceInterface } from "./StoreServiceInterface";
-import type { StorageServiceInterface } from "./StorageServiceInterface";
-import type { LoggerServiceInterface } from "./LoggerServiceInterface";
-import { APIClientInterface } from "./ApiInterface";
-import type { ServiceProviderInterface } from "./ServiceProviderInterface";
-import { OneObjectType } from "../types/utils";
+import { RouterInterface, ViewManagerInterface } from "./utils.js";
+import type { HelperInterface } from "./HelperInterface.js";
+import type { EventServiceInterface } from "./EventServiceInterface.js";
+import type { HttpServiceInterface } from "./HttpServiceInterface.js";
+import type { StoreServiceInterface } from "./StoreServiceInterface.js";
+import type { StorageServiceInterface } from "./StorageServiceInterface.js";
+import type { LoggerServiceInterface } from "./LoggerServiceInterface.js";
+import type { HeadServiceInterface } from "./HeadServiceInterface.js";
+import { APIClientInterface } from "./ApiInterface.js";
+import type { ServiceProviderInterface } from "./ServiceProviderInterface.js";
+import { SaoObjectType } from "../types/utils.js";
 
 export interface ApplicationInterface {
     [key: string]: any;
@@ -30,7 +31,7 @@ export interface ApplicationInterface {
     setMethod(name: string, method: Function, isOne?: boolean): void;
     get<T = any>(name: string): T;
 
-    oneType?: OneObjectType;
+    saoType?: SaoObjectType;
 
     // Service properties — set during bootstrap via App.set()
     isInitialized: boolean;
@@ -44,6 +45,7 @@ export interface ApplicationInterface {
     Store: StoreServiceInterface;
     Storage: StorageServiceInterface;
     Logger: LoggerServiceInterface;
+    Head: HeadServiceInterface;
 }
 
 // ─── App Factory (helper function type) ─────────────────────────

package/src/core/contracts/BlockInterface.ts

@@ -1,7 +1,7 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { HtmlInterface, FragmentInterface, OneChildrenFactoryOutput, OneNodeInterface } from "./ElementInterface";
-import { InitMode } from "./common";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { HtmlInterface, FragmentInterface, SaoChildrenFactoryOutput, SaoNodeInterface } from "./ElementInterface.js";
+import { InitMode } from "./common.js";
 
 // ─── Block / Layout Interfaces ───────────────────────────────────
 export type BlockConstructorParams = {
@@ -13,7 +13,7 @@ export type BlockConstructorParams = {
     initMode?: InitMode;
 };
 export interface BlockInterface {
-    oneType: OneObjectType;
+    saoType: SaoObjectType;
     /** Unique block slot name (e.g. 'content', 'sidebar') */
     name: string;
     id: string;
@@ -24,30 +24,30 @@ export interface BlockInterface {
     fragment: FragmentInterface | null;
     parentElement: HtmlInterface | null;
     domChildren: Node[];
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneBlock: boolean;
     initMode?: InitMode;
-     /** Initialize the block (e.g. during hydration) */
+    /** Initialize the block (e.g. during hydration) */
     init(): void;
-     /** Render the block's content into the parent element */
+    /** Render the block's content into the parent element */
     render(): void;
-     /** Mount the block's content into the DOM, finding matching outlets */
+    /** Mount the block's content into the DOM, finding matching outlets */
     mount(mountCtx: ViewControllerInterface, parentElement: HtmlInterface): any;
-     /** Unmount the block's content from the DOM */
+    /** Unmount the block's content from the DOM */
     unmount(): void;
-     /** Destroy the block and clean up resources */
+    /** Destroy the block and clean up resources */
     destroy(): void;
-     /** Update the block's content (e.g. on state change) */
+    /** Update the block's content (e.g. on state change) */
     update(): void;
-     /** Set the block's parent element (used for mounting) */
+    /** Set the block's parent element (used for mounting) */
     setParentElement(parentElement: HtmlInterface | null): void;
 
     contentRenderFactory: BlockRenderFactory | null;
     // new(params: BlockConstructorParams, ...args: any[]): BlockInterface;
 }
 
-export interface BlockOutletInterface extends OneNodeInterface {
-    oneType: OneObjectType;
+export interface BlockOutletInterface extends SaoNodeInterface {
+    saoType: SaoObjectType;
     id: string;
     name: string;
     parent: HtmlInterface | null;
@@ -56,9 +56,9 @@ export interface BlockOutletInterface extends OneNodeInterface {
     parentElement: HtmlInterface | null;
     ctx: ViewControllerInterface;
     initMode: InitMode;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneBlockOutlet: boolean;
-     /** Render the outlet's markers into the parent element */
+    /** Render the outlet's markers into the parent element */
     render(): any;
     hydrate(): any;
     destroy(): any;
@@ -73,4 +73,4 @@ export interface BlockManagerInterface {
 
 // ─── Block Types ────────────────────────────────────────────────
 
-export type BlockRenderFactory = (parentElement: HtmlInterface) => OneChildrenFactoryOutput;
+export type BlockRenderFactory = (parentElement: HtmlInterface) => SaoChildrenFactoryOutput;

package/src/core/contracts/BundleInterface.ts

@@ -0,0 +1,40 @@
+import type { ApplicationInterface } from "./ApplicationInterface.js";
+import type { ServiceProviderInterface } from "./ServiceProviderInterface.js";
+
+/** Factory view mà registry nhận: đồng bộ, hoặc lazy trả Promise<module>. */
+export type ViewFactory = ((...args: any[]) => any) | (() => Promise<any>);
+
+/**
+ * Manifest của một bundle nạp rời (theme, gói mở rộng).
+ *
+ * Cùng MỘT hình dạng cho mọi loại bundle: file chỉ có view thì điền `views`,
+ * file chỉ có code thì điền `providers`/`services`. Hai shape khác nhau = hai
+ * nhánh loader = hai chỗ để lệch.
+ */
+export interface SaolaBundle {
+    /** Định danh, dùng để báo lỗi và bắt trùng tên. */
+    name?: string;
+    /** Provider của bundle — class hoặc instance, đưa thẳng vào resolveProviderOrder. */
+    providers?: any[];
+    /** { Tên: Class | instance | object } → App.set(tên, …). */
+    services?: Record<string, any>;
+    /** { tên: fn } → gộp vào App.Helper. */
+    helpers?: Record<string, any>;
+    /** { 'dot.path': factory } → View.setViewRegistry(). Nạp sau ĐÈ nạp trước. */
+    views?: Record<string, ViewFactory>;
+    /** Chạy sau khi mọi bundle đã merge và App đã init. */
+    boot?(app: ApplicationInterface): void;
+}
+
+/** Kết quả gộp nhiều bundle, theo đúng thứ tự mảng URL. */
+export interface MergedBundles {
+    providers: (ServiceProviderInterface | any)[];
+    services: Record<string, any>;
+    helpers: Record<string, any>;
+    views: Record<string, ViewFactory>;
+    boots: Array<(app: ApplicationInterface) => void>;
+    /** Tên (hoặc URL) của bundle đã nạp được. */
+    loaded: string[];
+    /** [url, thông điệp lỗi] — nạp hỏng thì bỏ qua, KHÔNG làm sập boot. */
+    failed: Array<[string, string]>;
+}

package/src/core/contracts/ComponentInterface.ts

@@ -1,12 +1,12 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { ViewInterface } from "./ViewInterface";
-import type { HtmlInterface } from "./ElementInterface";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { ViewInterface } from "./ViewInterface.js";
+import type { HtmlInterface } from "./ElementInterface.js";
 
 // ─── Component Interface ─────────────────────────────────────────
 
 export interface ComponentInterface {
-    oneType: OneObjectType;
+    saoType: SaoObjectType;
     id: string;
     ctx: ViewControllerInterface;
     viewRef: ViewInterface | null;
@@ -15,12 +15,13 @@ export interface ComponentInterface {
     openTag: Comment;
     closeTag: Comment;
     stateKeys: string[];
+    listeners: Record<string, (...args: any[]) => any>;
     subscribeFn: () => void;
     unsubscribeFn: () => void;
     render(): void;
     destroy(): void;
     setParent(parent: HtmlInterface | null): void;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneComponent: boolean;
     [key: string]: any;
 }

package/src/core/contracts/ElementInterface.ts

@@ -1,39 +1,45 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { ReactiveInterface } from "./ReactiveInterface";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { ReactiveInterface } from "./ReactiveInterface.js";
 
 // ─── Element Interfaces ──────────────────────────────────────────
 
 /** Base for any renderable node in the tree */
-export interface OneNodeInterface {
-    oneType: OneObjectType;
+export interface SaoNodeInterface {
+    saoType: SaoObjectType;
     parent: HtmlInterface | null;
     render(): void;
     destroy(): void;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     setParentElement(parent: HtmlInterface | null): void;
     [key: string]: any;
 
 }
 
 /** Native HTML element wrapper */
-export interface HtmlInterface extends OneNodeInterface {
+export interface HtmlInterface extends SaoNodeInterface {
     element: HTMLElement;
     domChildren: Node[];
     [key: string]: any;
+    clearHTML(): void;
+    appendElement(element: HTMLElement | Comment | Text): void;
+    getElement(): HTMLElement;
+    renderChildren(): SaoElementChildren;
+    render(): HTMLElement;
 }
 
 /** Text node wrapper */
-export interface TextInterface extends OneNodeInterface {
+export interface TextInterface extends SaoNodeInterface {
     element: Text;
     text: string;
 
 
     domChildren: Node[];
     update(newText: string): void;
+    render(): HTMLElement | Text | Comment;
 }
 
-export interface OutputInterface extends OneNodeInterface {
+export interface OutputInterface extends SaoNodeInterface {
     ctx: ViewControllerInterface;
     parent: HtmlInterface | null;
     stateKeys: string[];
@@ -43,12 +49,11 @@ export interface OutputInterface extends OneNodeInterface {
     [key: string]: any;
 }
 
-export interface YieldInterface extends OneNodeInterface {
+export interface YieldInterface extends SaoNodeInterface {
     ctx: ViewControllerInterface;
     parent: HtmlInterface | null;
     name: string;
-    contentFactory: () => OneChildrenFactoryOutput;
-    setContentFactory(factory: () => OneChildrenFactoryOutput): void;
+    defaultValue: string;
     openTag: Comment;
     closeTag: Comment;
     domChildren: Node[];
@@ -56,40 +61,84 @@ export interface YieldInterface extends OneNodeInterface {
 }
 
 /** Fragment — renders multiple root nodes into a parent without a wrapping tag */
-export interface FragmentInterface extends OneNodeInterface {
+export interface FragmentInterface extends SaoNodeInterface {
     nodes: Node[];
     domChildren: Node[];
     [key: string]: any;
 
 }
 /** Wrapper — renders multiple root nodes into a parent without a wrapping tag */
-export interface WrapperInterface extends OneNodeInterface {
+export interface WrapperInterface extends SaoNodeInterface {
     nodes: Node[];
     domChildren: Node[];
     [key: string]: any;
+    /** Render — chạy childrenFactory, trả về danh sách children đã tạo. */
+    render(): SaoElementChildren;
+    appendTo(parent: HtmlInterface): void;
+    mountTo(parent: HtmlInterface): void;
+    clear(): void;
+    setChildrenFactory(factory: SaoChildrenFactory): void;
+    children: SaoElementChildren;
+    openTag: Comment;
+    closeTag: Comment;
+
 }
 
 // ─── Element Config Types ────────────────────────────────────────
 
-export type OneElementConfig = {
+/**
+ * Contract chuẩn (RUNTIME_CONTRACT.md §1.1): type = 'static' | 'binding'.
+ * 'value' giữ làm legacy alias của 'static' đến v0.2.
+ */
+export type BindingConfigType = 'static' | 'binding' | 'value';
+
+export type SaoElementConfig = {
+    /** Marker-free content for HTML RCDATA elements (textarea/title). */
+    content?: {
+        factory: () => any;
+        stateKeys?: string[];
+    },
     attrs?: {
         [key: string]: {
-            type: 'value' | 'binding';
+            type: BindingConfigType;
             value?: any;
             stateKeys?: string[];
             factory?: () => any;
+            /** `@yield(name, ...)` used as the whole attribute value — no static stateKeys
+             *  (the section it resolves to is only known at runtime), so Html subscribes to
+             *  SectionManager by name instead. */
+            yieldName?: string;
         }
     },
     props?: {
         [key: string]: {
-            type: 'value' | 'binding';
+            type: BindingConfigType;
             value?: any;
             stateKeys?: string[];
             factory?: () => any;
         }
     },
     events?: {
-        [key: string]: OneElementEventHandler;
+        [key: string]: SaoElementEventHandler;
+    },
+    /**
+     * `@click.prevent.stop(...)` — bucket RIÊNG cạnh `events` để shape
+     * `events: {click: [...]}` (contract sẵn có) không đổi; view compile trước
+     * khi có modifier không có key này và chạy y nguyên.
+     */
+    eventModifiers?: {
+        [key: string]: EventModifier[];
+    },
+    /** `@bind(key)`/`@val(key)` — two-way binding, own bucket (sibling of attrs/props/events). */
+    bind?: {
+        key: string;
+    },
+    /**
+     * `@transition('fade')` — tiền tố class enter/leave (`fade-enter-from`, ...).
+     * Bucket riêng như `bind`/`eventModifiers`; vắng mặt = hành vi cũ y nguyên.
+     */
+    transition?: {
+        name: string;
     },
     classes?: {
         [className: string]: {
@@ -99,14 +148,15 @@ export type OneElementConfig = {
             factory?: () => boolean;
         }
     } | Array<{
-        type: 'static' | 'binding';
+        /** 'dynamic' = factory trả về TÊN class (`class="language-{{ lang }}"`), không có `value`. */
+        type: 'static' | 'binding' | 'dynamic';
         value?: string;
         stateKeys?: string[];
-        factory?: () => boolean;
+        factory?: () => boolean | string;
     }>,
     styles?: {
         [prop: string]: {
-            type: 'value' | 'binding';
+            type: BindingConfigType;
             value?: string;
             stateKeys?: string[];
             factory?: () => string;
@@ -115,7 +165,7 @@ export type OneElementConfig = {
     [key: string]: any;
 }
 
-export type HtmlElementConfig = OneElementConfig & {
+export type HtmlElementConfig = SaoElementConfig & {
     ctx: ViewControllerInterface;
     parentElement?: HtmlInterface | null;
     parent?: HtmlInterface | null;
@@ -123,18 +173,36 @@ export type HtmlElementConfig = OneElementConfig & {
 
 // ─── Event Handler ──────────────────────────────────────────────
 
-export type OneElementEventHandler = Array<{
+/**
+ * Modifier của `@click.prevent.stop(...)`. Phải khớp `EVENT_MODIFIERS` trong
+ * `compiler/src/sao2js/template_ast.py` — compiler chỉ emit tên trong tập đó.
+ */
+export type EventModifier = 'prevent' | 'stop' | 'self' | 'once';
+
+export type SaoElementEventHandler = Array<{
     handler: string | ((event: Event) => any);
     params?: (any | ((event: Event) => any[]))[];
 } | ((event: Event) => any)>;
 
+export type SaoElement = WrapperInterface | HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface;
+export type DOMElement = HTMLElement | SVGElement | DocumentFragment | Text | Comment;
 // ─── Children Types ─────────────────────────────────────────────
 
 /** All possible rendered child node types */
-export type OneElementChildren = Array<HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface | HTMLElement | SVGElement | DocumentFragment | Text | Comment>;
+export type SaoElementChildren = Array<SaoElement | SaoNodeInterface | DOMElement>;
 
-/** What a children factory can return (before mounting) */
-export type OneChildrenFactoryOutput = Array<HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface | string | number | HTMLElement | SVGElement | DocumentFragment | Text | Comment>;
+/** What a children factory can return (before mounting).
+ *  SaoNodeInterface bao phủ các marker-based element (Output, Component, Block...)
+ *  mà compiled output vẫn trả về trong children factories. */
+export type SaoChildrenFactoryOutput = Array<SaoElement | SaoNodeInterface | DOMElement | string | number | null | undefined>;
 
 /** Factory function that produces children given parent element */
-export type OneChildrenFactory = (parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+export type SaoChildrenFactory = (parentElement: HtmlInterface | null) => SaoChildrenFactoryOutput;
+
+/**
+ * Lazy payload passed from a parent component to one ChildrenNode placeholder.
+ * A factory is deliberately not executed while component data is resolved; the
+ * child view invokes it only when its render traversal reaches the placeholder.
+ */
+export type SaoChildrenSlotFactory = SaoChildrenFactory;
+export type SaoChildrenSlotContent = SaoChildrenSlotFactory | string | number | null | undefined;