@saolabs/client 1.0.0 → 1.1.0

package/src/core/contracts/ViewControllerInterface.ts

@@ -1,45 +1,80 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewInterface, ViewRenderFactory } from "./ViewInterface";
-import type { ViewStateInterface } from "./ViewStateInterface";
-import type { HtmlInterface, FragmentInterface, OneElementEventHandler, OneElementChildren, OneChildrenFactory, WrapperInterface } from "./ElementInterface";
-import type { ReactiveInterface } from "./ReactiveInterface";
-import type { BlockInterface } from "./BlockInterface";
-import type { LoopContextInterface } from "./LoopContextInterface";
-import { SectionInterface } from "./views";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewInterface, ViewRenderFactory } from "./ViewInterface.js";
+import type { ViewUserConfig } from "../view/View.js";
+import type { ViewStateInterface } from "./ViewStateInterface.js";
+import type {
+    HtmlInterface, FragmentInterface, SaoElementEventHandler, SaoElementChildren,
+    SaoChildrenFactory, SaoChildrenFactoryOutput, SaoChildrenSlotContent, WrapperInterface,
+    EventModifier
+} from "./ElementInterface.js";
+import type { ReactiveInterface } from "./ReactiveInterface.js";
+import type { BlockInterface } from "./BlockInterface.js";
+import type { LoopContextInterface } from "./LoopContextInterface.js";
+import { SectionInterface } from "../contracts/SectionInterface.js";
+import type { ForeachSlotCache } from "../elements/ForeachSlotCache.js";
+import type { InitMode } from "./common.js";
+import type { ResourceScope } from '../view/ResourceScope.js';
 
 // ─── ViewController Interface ────────────────────────────────────
 
 export type ViewType = 'view' | 'layout' | 'component' | 'template';
 
 export interface ViewControllerInterface {
-    oneType: OneObjectType;
+    saoType: SaoObjectType;
     view: ViewInterface;
     viewId: string;
     path: string;
     viewType: ViewType;
     states: ViewStateInterface;
+    readonly scope: ResourceScope;
+    afterDom(callback: () => void): () => void;
     loopContext: LoopContextInterface | null;
     /** Raw input data reference */
     data: Record<string, any>;
     /** Whether this view defines a super view (layout) */
     hasSuperView: boolean;
+
+    /** Exact DOM listener references, used for element-level cleanup before destroy. */
+    elementEventHandlers: Map<HTMLElement, Map<string, EventListener[]>>;
+
+    /**
+     * Active ForeachSlotCache — set bởi Reactive.renderForeach() trước khi gọi factory.
+     * __foreach() dùng để quyết định reuse hay create elements.
+     * null = không có cache active (render bình thường).
+     */
+    _currentForeachCache: ForeachSlotCache | null;
+    /** Element gọi trong destroy() để tự gỡ khỏi registry (no-op nếu key đã trỏ bản mới) */
+    releaseElement(el: object): void;
+    /** Compiler helper for raw interpolation inside HTML RCDATA. */
+    decodeTextContent(value: string): string;
     /** Path to super view (layout) */
     superViewPath: string | null;
 
     /** Main element (Wrapper) for this view */
-    mainElement: any;
+    mainElement: WrapperInterface | null;
+    preloadElement: WrapperInterface | null;
 
     sections: Map<string, SectionInterface>;
     blocks: Map<string, BlockInterface>;
     urlPath: string | null;
+    isActive: boolean;
+    childrenFactory: SaoChildrenFactory | null;
 
-    childrenFactory: OneChildrenFactory | null;
-
-    wrapper: (factory: OneChildrenFactory) => WrapperInterface;
+    wrapper: (factory: SaoChildrenFactory) => WrapperInterface;
 
-    addEventListener(element: HTMLElement, event: string, handlers: OneElementEventHandler): void;
+    removeEventListener(element: HTMLElement, event: string): void;
+    addEventListener(element: HTMLElement, event: string, handlers: SaoElementEventHandler, modifiers?: EventModifier[]): void;
     /** Called by reactive system to schedule an update */
     scheduleUpdate(reactive: ReactiveInterface): void;
+    /** Còn vùng reactive chờ re-render trong frame này không? */
+    hasPendingReactiveUpdate(): boolean;
+    /** Flush đồng bộ các reactive update đang chờ (sau mount/hydrate). */
+    flushReactiveUpdatesNow(): void;
+    /**
+     * Chế độ khởi tạo của view: 'create' (CSR) hoặc 'hydrate' (SSR).
+     * Truyền xuống mọi element con để chúng tạo mới hay claim DOM server.
+     */
+    initMode: InitMode;
     /** Lifecycle */
     setup(config: Record<string, any>): void;
     /** Commit initial data — set initial state values after render */
@@ -48,20 +83,36 @@ export interface ViewControllerInterface {
     updateData(data: Record<string, any>): void;
     /** Update single data item */
     updateDataItem(key: string, value: any): void;
+    /** Mount — gắn instance vào real DOM (root!=null) + fire mounting/mounted + acquire asset */
+    mount(root?: HtmlInterface | null): void;
+    /** Unmount — gỡ instance khỏi real DOM + fire unmounting/unmounted + release asset */
+    unmount(): void;
     /** Start reactive subscriptions */
     start(): void;
     /** Stop reactive subscriptions (for caching) */
     stop(): void;
+    /** Pause — dirty-mode + buffer async, dùng khi vào PageCache (ROUTE_RENDER_FLOW §7) */
+    pause(): void;
+    /** Resume — flush dirty keys + apply buffered data, dùng khi restore từ PageCache */
+    resume(): void;
+    /** State machine: created → active ⇄ paused → destroyed */
+    readonly lifecycleState: string;
+    active(): void;
+    deactive(): void;
+    pushBlockAndSections(): void;
+    /** Materialize the lazy parent-owned slot only when ChildrenNode is rendered. */
+    __children(content: SaoChildrenSlotContent, parentElement: HtmlInterface | null): SaoChildrenFactoryOutput;
     /** Loop directives */
-    __foreach<T>(list: T[] | Record<string, T>, callback: (item: T, key: string, index: number, loop: any) => any): any[];
+    __foreach<T>(list: T[] | Record<string, T>, callback: (item: T, key: string, index: number, loop: any, identity: number) => any, keyFn?: (item: T, index: number) => any, reconcile?: boolean, scopeId?: string): any[];
     __for(loopType?: string, start?: number, end?: number, execute?: (loop: any) => any): any;
     __while(execute: (loop: any) => any, maxIterations?: number): any;
     /** App reference */
     App: any;
     setApp(app: any): void;
-    setUserDefinedConfig(config: Record<string, any>): void;
+    setUserDefinedConfig<T extends object>(config: ViewUserConfig<T>): void;
     /** Set root element — the container this view renders into */
     setRootElement(rootElement: HtmlInterface): void;
+    setParentElement(parentElement: HtmlInterface): void;
     /** Render the view's element tree into rootElement */
     render(): ViewInterface | FragmentInterface | null;
 
@@ -75,6 +126,13 @@ export interface ViewControllerInterface {
     setIsSuperView(isSuper: boolean): void;
     /** Set the parent layout's controller */
     setSuperView(superView: ViewControllerInterface): void;
+    /** Nested view tree (@include): parent controller */
+    parent: ViewControllerInterface | null;
+    /** Nested view tree (@include): child controllers */
+    children: ViewControllerInterface[];
+    setParent(parent: ViewControllerInterface | null): void;
+    addChild(child: ViewControllerInterface): void;
+    removeChild(child: ViewControllerInterface): void;
     /** Track the original page view's controller for block mounting */
     originView: ViewControllerInterface | null;
     /** Set the origin (page) controller reference */
@@ -88,6 +146,13 @@ export interface ViewControllerInterface {
     /** Get config value with optional default */
     getConfig(key?: string, defaultValue?: any): any;
     getConfig(): ViewControllerConfig;
+
+    /**
+     * Đưa lỗi cho error boundary gần nhất (chính controller này hoặc tổ tiên
+     * qua `parent`). Trả `{ handled: true, fallback }` nếu có boundary xử lý;
+     * `{ handled: false }` → caller giữ nguyên hành vi cũ (bubble lên trên).
+     */
+    handleError(err: unknown, info: ErrorInfo): { handled: boolean; fallback?: any };
 }
 
 // ─── View Config Types ───────────────────────────────────────────
@@ -130,6 +195,49 @@ export type ViewRuntimeConfig = {
     updateVariableItemData?: (key: string, value: any) => void;
     prerender?: ViewRenderFactory | null;
     render?: ViewRenderFactory | null;
+    /**
+     * Error boundary. Trả children → dùng làm fallback cho vùng lỗi;
+     * trả void → chỉ ghi nhận, lỗi tiếp tục bubble lên boundary cha.
+     */
+    onError?: ErrorBoundaryHandler;
     [key: string]: any;
 }
+
+/** Giai đoạn phát sinh lỗi — giúp handler phân biệt lỗi render lần đầu với lỗi sau tương tác. */
+export type ErrorPhase = 'render' | 'update' | 'async';
+
+export type ErrorInfo = {
+    phase: ErrorPhase;
+    /** path của view NƠI lỗi xảy ra (có thể là view con, khác với view chứa boundary) */
+    path: string;
+};
+
+export type ErrorBoundaryHandler = (err: unknown, info: ErrorInfo) => any;
 export type ViewControllerConfig = ViewConfig & ViewRuntimeConfig;
+
+/**
+ * `this` bên trong các hàm config do compiler sinh — `commitConstructorData`,
+ * `updateVariableData`, `updateVariableItemData`.
+ *
+ * Chúng được gọi bằng `fn.call(makeConfigThis(), …)`, tức receiver KHÔNG phải
+ * object chứa chúng. TypeScript mặc định suy `this` = chính object literal đó,
+ * nên `this.config` không tồn tại theo kiểu và `tsc --strict` báo TS2339.
+ *
+ * Compiler emit `function(this: ViewConfigThis)` cho đầu ra `.ts`; đầu ra `.js`
+ * không có tham số này vì tham số `this` là cú pháp chỉ có ở TypeScript và bị
+ * xoá khi emit — nó không bao giờ là đối số thật.
+ */
+export interface ViewConfigThis {
+    /**
+     * Config runtime của chính view — nơi các hàm sinh ra gọi lẫn nhau.
+     *
+     * KHÔNG nullable, và `ViewController.runtimeConfig` cũng vậy: nó khởi tạo
+     * `{}` rồi chỉ bị `setup()` ghi đè bằng config thật. Cái CÓ THỂ vắng là
+     * từng hàm trong đó (`commitConstructorData`… đều optional) — mỗi lời gọi
+     * đã tự canh bằng `typeof fn === 'function'`.
+     */
+    config: ViewRuntimeConfig;
+    data: Record<string, any>;
+    ctrl: ViewControllerInterface;
+    view: ViewInterface;
+}

package/src/core/contracts/ViewInterface.ts

@@ -1,11 +1,11 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface, ViewType } from "./ViewControllerInterface";
-import type { FragmentInterface } from "./ElementInterface";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface, ViewType } from "./ViewControllerInterface.js";
+import type { FragmentInterface } from "./ElementInterface.js";
 
 // ─── View Interface ──────────────────────────────────────────────
 
 export interface ViewInterface {
-    oneType: OneObjectType;
+    saoType: SaoObjectType;
     __ctrl__: ViewControllerInterface;
     path: string;
     viewType: ViewType;
@@ -20,12 +20,41 @@ export type ViewRenderFactory = () => FragmentInterface | ViewInterface | null;
 /** View class constructor signature */
 export type ViewConstructor = new (path: string, viewType: 'view' | 'layout' | 'component', viewControllerClass?: any) => ViewInterface;
 
-/** View lifecycle hooks — user can implement any of these */
+/**
+ * View lifecycle hooks — user có thể cài bất kỳ hook nào (mẫu examples/sao/app.sao).
+ * Mỗi transition có cặp before/after:
+ *   mount   → mounting / mounted        (gắn vào real DOM)
+ *   start   → starting / started        (subscribe reactive + attach events)
+ *   pause   → pausing  / paused         (vào PageCache — rời real DOM)
+ *   resume  → resuming / resumed        (khôi phục từ PageCache)
+ *   stop    → stopping / stopped        (deactivate reactive)
+ *   unmount → unmounting / unmounted    (gỡ khỏi real DOM)
+ *   destroy → destroying / destroyed    (cleanup toàn bộ)
+ */
 export interface ViewLifecycleHooks {
+    // ─── Cặp before/after (API chính) ───
+    mounting?(): void | Promise<void>;
+    mounted?(): void | Promise<void>;
+    starting?(): void | Promise<void>;
+    started?(): void | Promise<void>;
+    pausing?(): void | Promise<void>;
+    paused?(): void | Promise<void>;
+    resuming?(): void | Promise<void>;
+    resumed?(): void | Promise<void>;
+    stopping?(): void | Promise<void>;
+    stopped?(): void | Promise<void>;
+    unmounting?(): void | Promise<void>;
+    unmounted?(): void | Promise<void>;
+    destroying?(): void | Promise<void>;
+    destroyed?(): void | Promise<void>;
+
+    // ─── Legacy alias (giữ tương thích code/test cũ) ───
     onInit?(): void | Promise<void>;
     onMounted?(): void | Promise<void>;
     onUpdated?(): void | Promise<void>;
     onDestroy?(): void | Promise<void>;
     onActivated?(): void | Promise<void>;
     onDeactivated?(): void | Promise<void>;
+    onPause?(): void | Promise<void>;
+    onResume?(): void | Promise<void>;
 }

package/src/core/contracts/ViewManagerInterface.ts

@@ -1,6 +1,6 @@
-import type { ViewInterface } from "./ViewInterface";
-import type { ApplicationInterface } from "./ApplicationInterface";
-import { RouterNavigationType } from "./RouterInterface";
+import type { ViewInterface } from "./ViewInterface.js";
+import type { ApplicationInterface } from "./ApplicationInterface.js";
+import { RouterNavigationType } from "./RouterInterface.js";
 
 
 // ─── ViewManager Interface ───────────────────────────────────────
@@ -25,13 +25,27 @@ export interface ViewManagerInterface {
     /** Register a single view module */
     registerView(name: string, loader: ((...args: any[]) => any) | (() => Promise<any>)): void;
     /** Initialize with optional config */
-    init(config?: { container?: HTMLElement; registry?: Record<string, any> }): void;
+    init(config?: { container?: HTMLElement | string; registry?: Record<string, any>; systemData?: Record<string, any>; revision?: string; contextViews?: string; dataEndpoint?: string; fetchOptions?: Record<string, any> }): void;
+    /** Apply a newer server-authoritative view context. Returns true when changed. */
+    applyViewContext?(state: Record<string, any>): boolean;
+    /** A changed view namespace needs a full document load before it can be applied safely. */
+    requiresReloadForViewContext?(state: Record<string, any>): boolean;
+    /** Current server view-context fingerprint. */
+    getContextRevision?(): string | null;
     /** Mount a view by name — main entry point */
     mountView(name: string, data?: Record<string, any>, route?: any, navigationType?: RouterNavigationType ): any;
+    /**
+     * Hydrate a server-side rendered view.
+     * data PHẢI có __SSR_VIEW_ID__ — viewId mà Blade dùng để prefix element classes.
+     */
+    hydrateView(name: string, data: Record<string, any> & { __SSR_VIEW_ID__: string }, route?: any): any;
+    /** Còn SSR boot chưa consume? (route đầu tiên nên hydrate thay vì mount) */
+    hasSSRBoot?(): boolean;
+    /** Lấy + consume viewId SSR cho view name (chỉ trả 1 lần, cho route đầu) */
+    consumeSSRViewId?(viewName: string): string | null;
     /** Unmount all active views */
     unmountAll(): void;
     /** Unmount a specific view by path */
-    unmountView(path: string): void;
     /** Get currently active page view */
     getCurrentView(): ViewInterface | null;
     /** Get current layout view */
@@ -40,6 +54,27 @@ export interface ViewManagerInterface {
     getViewStack(): ViewInterface[];
     /** Check if a view is mounted */
     isViewMounted(path: string): boolean;
+    /** Invalidate async work of the navigation currently being rendered. */
+    cancelNavigation?(): void;
     /** Full destroy */
     destroy(): void;
+    /**
+     * generateViewId — tạo unique ID cho mỗi view instance.
+     * Compiled output gọi: App.View.generateViewId()
+     */
+    generateViewId(): string;
+    /**
+     * exists — kiểm tra view đã đăng ký trong registry chưa.
+     * Dùng bởi @includeIf directive.
+     */
+    exists(name: string): boolean;
+    /**
+     * view — lấy view instance từ registry, có thể cache.
+     */
+    /** Tạo View instance; hỗ trợ registry lazy (`() => import(...)`) — dùng cho view cấp route. */
+    view(name: string, data: Record<string, any>, cache: boolean): Promise<any>;
+    /** Bản đồng bộ cho `@include`/`@extends`; view lazy chưa preload → null. */
+    resolveViewSync(name: string, data: Record<string, any>, cache: boolean): any;
+    /** Nạp trước view lazy để dùng được đồng bộ sau đó. */
+    preloadView(name: string): Promise<boolean>;
 }

package/src/core/contracts/ViewStateInterface.ts

@@ -13,16 +13,53 @@ export interface ViewStateInterface {
 export interface StateManagerInterface {
     /** Create reactive state — returns [value, setter, key] */
     useState(value: any, key?: string | number): [any, (newValue: any) => void, string | number];
+    /**
+     * State dẫn xuất có memo hoá — chỉ tính lại khi `deps` đổi, và lazy
+     * (đánh dấu bẩn lúc dep đổi, tính lúc đọc). Đọc qua `getStateByKey(key)`
+     * hoặc `subscribe([key])` như state thường.
+     */
+    computed<T>(key: string, fn: () => T, deps?: string[]): () => T;
     /** Update state by key */
     updateStateByKey(key: string | number, value: any): any;
     /** Get state value by key (supports nested paths: 'user.name') */
     getStateByKey(key: string | number): any;
+    getStateVersion(key: string): number;
     /** Subscribe to state changes */
     subscribe(key: string | number | string[] | Record<string, (value: any) => void>, callback?: (value: any) => void): () => void;
     /** Unsubscribe */
     unsubscribe(key: string | number | string[] | Record<string, (value: any) => void>, callback?: (value: any) => void): void;
-    /** Register shorthand — useState alias */
-    register(key: string | number, value: any): (newValue: any) => void;
+    /**
+     * Register shorthand — pre-declare a state slot, returns setter.
+     * Value is optional — compiler calls register(key) with 1 arg;
+     * initial value is set later via update$xxx() in commitConstructorData.
+     */
+    register(key: string | number, value?: any): (newValue: any) => void;
+    /**
+     * Setter map — exposed for direct access by compiled views.
+     * e.g. __STATE__.__.setters.setCount = setCount;
+     */
+    setters: Record<string | number, (value: any) => void>;
+    /**
+     * Flag — true while commitConstructorData is running, false after lockUpdateRealState().
+     * Compiler-generated update$xxx() checks this before calling updateStateByKey.
+     */
+    readonly canUpdateStateByKey: boolean;
+    /**
+     * Lock — called at end of commitConstructorData() to prevent update$xxx from
+     * being accidentally triggered after initialization.
+     */
+    lockUpdateRealState(): void;
+    /**
+     * Unlock — called before updateVariableData() to allow update$xxx again.
+     */
+    unlockUpdateRealState(): void;
+    /**
+     * Flush đồng bộ pending state changes (huỷ RAF đang chờ nếu có).
+     * Dùng sau commitData()/mount để DOM phản ánh state ngay trong cùng tick.
+     */
+    flushNow(): void;
+    /** Opt into expensive mutation diagnostics; disabled by default in browsers. */
+    setMutationDiagnostics(enabled: boolean): void;
     /** Destroy — cleanup all listeners and states */
     destroy(): void;
 }

package/src/core/contracts/common.ts

@@ -4,13 +4,13 @@ export enum InitModes {
     HYDRATE = 'hydrate'
 }
 /**
- * Common types and utilities for OneView contracts
- * This file defines shared types and enums used across OneView's contracts, such as initialization modes and system keys for HTML elements.
+ * Common types and utilities for SaoView contracts
+ * This file defines shared types and enums used across SaoView's contracts, such as initialization modes and system keys for HTML elements.
  * 
  * Key exports:
  */
 /**
- * System keys for HTML elements used by OneView.
+ * System keys for HTML elements used by SaoView.
  * These keys are used to store metadata on HTML elements, such as IDs and view information.
  * @name ESK (Element System Keys)
  * @enum {string}

package/src/core/contracts/utils.ts

@@ -1,23 +1,23 @@
 // ─── Barrel Re-exports ───────────────────────────────────────────
 // All interfaces and related types re-exported for backward compatibility
 
-export type { LoopContextInterface } from "./LoopContextInterface";
-export type { ViewStateInterface, StateManagerInterface, StateListener, MultiKeyStateListener, StateItem } from "./ViewStateInterface";
-export type { OneNodeInterface, HtmlInterface, TextInterface, OutputInterface, FragmentInterface, OneElementConfig, HtmlElementConfig, OneElementEventHandler, OneElementChildren, OneChildrenFactoryOutput, OneChildrenFactory } from "./ElementInterface";
-export type { ReactiveInterface, ReactiveRenderFn, ReactiveChildrenFactory, ReactiveConfig } from "./ReactiveInterface";
-export type { BlockInterface, BlockOutletInterface, BlockManagerInterface, BlockRenderFactory } from "./BlockInterface";
-export type { ViewControllerInterface, ViewType, ViewConfig, ViewRuntimeConfig } from "./ViewControllerInterface";
-export type { ViewInterface, ViewRenderFactory, ViewConstructor, ViewLifecycleHooks } from "./ViewInterface";
-export type { ComponentInterface } from "./ComponentInterface";
-export type { ApplicationInterface, AppFactory, ServiceKey, ServiceFactory, ServiceBinding } from "./ApplicationInterface";
-export type { ServiceProviderInterface } from "./ServiceProviderInterface";
-export type { ViewCacheInterface } from "./ViewCacheInterface";
-export type { ViewManagerInterface, ActiveViewInfo } from "./ViewManagerInterface";
-export type { RouterInterface } from "./RouterInterface";
-export type { HelperInterface, CollectionProxyInterface } from "./HelperInterface";
-export type { EventServiceInterface, EventCallback } from "./EventServiceInterface";
-export type { HttpServiceInterface, HttpRequestConfig, HttpResponse, HttpInterceptor } from "./HttpServiceInterface";
-export type { StoreServiceInterface } from "./StoreServiceInterface";
-export type { StorageServiceInterface, StorageEventCallback } from "./StorageServiceInterface";
-export type { LoggerServiceInterface, LoggerConfig, LogEntry, LogLevel } from "./LoggerServiceInterface";
+export type { LoopContextInterface } from "./LoopContextInterface.js";
+export type { ViewStateInterface, StateManagerInterface, StateListener, MultiKeyStateListener, StateItem } from "./ViewStateInterface.js";
+export type { SaoNodeInterface, HtmlInterface, TextInterface, OutputInterface, FragmentInterface, SaoElementConfig, HtmlElementConfig, SaoElementEventHandler, SaoElementChildren, SaoChildrenFactoryOutput, SaoChildrenFactory } from "./ElementInterface.js";
+export type { ReactiveInterface, ReactiveRenderFn, ReactiveChildrenFactory, ReactiveConfig } from "./ReactiveInterface.js";
+export type { BlockInterface, BlockOutletInterface, BlockManagerInterface, BlockRenderFactory } from "./BlockInterface.js";
+export type { ViewControllerInterface, ViewType, ViewConfig, ViewRuntimeConfig } from "./ViewControllerInterface.js";
+export type { ViewInterface, ViewRenderFactory, ViewConstructor, ViewLifecycleHooks } from "./ViewInterface.js";
+export type { ComponentInterface } from "./ComponentInterface.js";
+export type { ApplicationInterface, AppFactory, ServiceKey, ServiceFactory, ServiceBinding } from "./ApplicationInterface.js";
+export type { ServiceProviderInterface } from "./ServiceProviderInterface.js";
+export type { ViewCacheInterface } from "./ViewCacheInterface.js";
+export type { ViewManagerInterface, ActiveViewInfo } from "./ViewManagerInterface.js";
+export type { RouterInterface } from "./RouterInterface.js";
+export type { HelperInterface, CollectionProxyInterface } from "./HelperInterface.js";
+export type { EventServiceInterface, EventCallback } from "./EventServiceInterface.js";
+export type { HttpServiceInterface, HttpRequestConfig, HttpResponse, HttpInterceptor } from "./HttpServiceInterface.js";
+export type { StoreServiceInterface } from "./StoreServiceInterface.js";
+export type { StorageServiceInterface, StorageEventCallback } from "./StorageServiceInterface.js";
+export type { LoggerServiceInterface, LoggerConfig, LogEntry, LogLevel } from "./LoggerServiceInterface.js";
 

package/src/core/contracts/views.ts

@@ -1,23 +1,3 @@
-import { HtmlInterface, OneElementChildren } from "./ElementInterface";
-import { ViewControllerInterface } from "./utils";
+import { HtmlInterface, SaoElementChildren } from "./ElementInterface.js";
+import { ViewControllerInterface } from "./utils.js";
 
-export type SectionItemType = 'static' | 'dynamic' | 'async' | 'reactive';
-export type SectionContentType = 'text' | 'html'
-export type SectionContentRenderer = (parentElement?: HtmlInterface | null | undefined) => string | OneElementChildren;
-export type SectionConstruvtorArgs = {
-    ctx?: ViewControllerInterface | null;
-    name: string;
-    type: SectionItemType;
-    contentType?: SectionContentType;
-    stateKeys?: string[];
-    renderFactory: SectionContentRenderer;
-    [key: string]: any;
-}
-export interface SectionInterface {
-    ctx? : ViewControllerInterface | null;
-    name: string;
-    type: SectionItemType;
-    contentType?: SectionContentType;
-    stateKeys?: string[];
-    renderFactory?: SectionContentRenderer;
-}

package/src/core/devtools/hook.ts

@@ -0,0 +1,142 @@
+/**
+ * DevTools runtime hook (GAP-05).
+ *
+ * Nền tảng cho MỌI UI devtools (overlay in-page, browser extension sau này):
+ * runtime chỉ phát sự kiện + cho phép đọc snapshot, KHÔNG biết gì về UI.
+ *
+ * Thiết kế:
+ *   - **Tắt mặc định, zero-cost.** `emit()` thoát ngay ở dòng đầu khi chưa bật.
+ *     Không tạo object, không serialize — không được làm chậm production.
+ *   - Bật bằng `App.devtools.enable()` hoặc đặt sẵn `window.__SAOLA_DEVTOOLS_HOOK__`
+ *     TRƯỚC khi app boot (cách extension sẽ dùng: content script inject sớm).
+ *   - Snapshot đọc từ ViewManager/ViewController, không giữ state riêng →
+ *     không có nguồn sự thật thứ hai để lệch.
+ */
+
+export type DevtoolsEventType =
+    | 'view:mounted' | 'view:destroyed'
+    | 'state:changed'
+    | 'error';
+
+export interface DevtoolsEvent {
+    type: DevtoolsEventType;
+    /** ms từ lúc trang load — đủ để xếp thứ tự trên timeline */
+    at: number;
+    viewId?: string;
+    path?: string;
+    /** state:changed → key nào đổi; error → phase */
+    detail?: any;
+}
+
+export interface DevtoolsViewNode {
+    viewId: string;
+    path: string;
+    viewType: string;
+    lifecycleState: string;
+    /** Ảnh chụp state hiện tại (đã lọc giá trị không serialize được) */
+    state: Record<string, any>;
+    /** Số element đang giữ trong registry — dò rò rỉ */
+    elementCount: number;
+    children: DevtoolsViewNode[];
+}
+
+type Listener = (e: DevtoolsEvent) => void;
+
+const MAX_LOG = 200;
+
+class DevtoolsHook {
+    private enabled = false;
+    private listeners: Listener[] = [];
+    /** Vòng đệm — devtools mở muộn vẫn xem được lịch sử gần đây */
+    private log: DevtoolsEvent[] = [];
+    /** ViewManager, gán lúc boot; dùng any để tránh vòng import */
+    private viewManager: any = null;
+
+    isEnabled(): boolean { return this.enabled; }
+
+    enable(): void { this.enabled = true; }
+    disable(): void { this.enabled = false; this.log = []; }
+
+    /** ViewManager tự đăng ký lúc init — hook không đi tìm global. */
+    attach(viewManager: any): void { this.viewManager = viewManager; }
+
+    subscribe(fn: Listener): () => void {
+        this.listeners.push(fn);
+        return () => { this.listeners = this.listeners.filter(l => l !== fn); };
+    }
+
+    /** Hot path — phải rẻ khi tắt. */
+    emit(type: DevtoolsEventType, data?: Omit<DevtoolsEvent, 'type' | 'at'>): void {
+        if (!this.enabled) return;
+        const event: DevtoolsEvent = { type, at: Math.round(performance.now()), ...data };
+        this.log.push(event);
+        if (this.log.length > MAX_LOG) this.log.shift();
+        for (const fn of this.listeners) {
+            try { fn(event); } catch (e) { console.error('[Devtools] listener error:', e); }
+        }
+    }
+
+    getLog(): DevtoolsEvent[] { return [...this.log]; }
+    clearLog(): void { this.log = []; }
+
+    /** Cây view đang mount: layout chain (ngoài → trong) rồi tới page. */
+    getViewTree(): DevtoolsViewNode[] {
+        const vm = this.viewManager;
+        if (!vm) return [];
+        const roots: any[] = [...(vm.getLayoutChain?.() ?? []), vm.getCurrentView?.()].filter(Boolean);
+        // Layout chain và page nối nhau theo thứ tự mount, không phải quan hệ
+        // parent/children (quan hệ đó chỉ dùng cho @include) → dựng phẳng ở
+        // gốc, rồi mỗi node mở rộng theo ctrl.children thật.
+        return roots.map(v => this.toNode(v.__ctrl__));
+    }
+
+    private toNode(ctrl: any): DevtoolsViewNode {
+        return {
+            viewId: ctrl.viewId,
+            path: ctrl.path,
+            viewType: ctrl.viewType,
+            lifecycleState: ctrl.lifecycleState,
+            state: this.snapshotState(ctrl),
+            elementCount: ctrl.elements?.size ?? 0,
+            children: (ctrl.children ?? []).map((c: any) => this.toNode(c)),
+        };
+    }
+
+    /**
+     * Ảnh chụp state — mọi giá trị đi qua JSON round-trip để cắt tham chiếu
+     * DOM/hàm/vòng lặp: devtools không được giữ sống object của app, và
+     * không được nổ khi state chứa cấu trúc vòng.
+     */
+    private snapshotState(ctrl: any): Record<string, any> {
+        const out: Record<string, any> = {};
+        const states = ctrl.states?.__?.states ?? {};
+        for (const key of Object.keys(states)) {
+            try {
+                const value = states[key]?.value; // computed: getter → tính lại ở đây
+                out[key] = value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+            } catch {
+                out[key] = '[không serialize được]';
+            }
+        }
+        return out;
+    }
+}
+
+export const devtools = new DevtoolsHook();
+
+/**
+ * Nếu môi trường đã cắm sẵn `window.__SAOLA_DEVTOOLS_HOOK__` trước khi app boot
+ * (browser extension làm vậy), tự bật và nối sự kiện sang đó.
+ */
+if (typeof window !== 'undefined') {
+    const external = (window as any).__SAOLA_DEVTOOLS_HOOK__;
+    if (external) {
+        devtools.enable();
+        devtools.subscribe((e) => { try { external.onEvent?.(e); } catch { /* của bên thứ 3 */ } });
+        external.getViewTree = () => devtools.getViewTree();
+        external.getLog = () => devtools.getLog();
+    }
+    (window as any).__SAOLA_DEVTOOLS__ = devtools;
+}
+
+export default devtools;