@saolabs/client 1.0.0 → 1.0.2

package/src/core/contracts/HeadServiceInterface.ts

@@ -0,0 +1,41 @@
+// ─── Head Service Interface ───────────────────────────────────────
+
+/**
+ * `'page'` (default) — reverts to whatever was there before on the next
+ * `resetPage()` (called once per SPA navigation), so a tag set by page A
+ * never leaks into page B.
+ * `'persistent'` — survives navigation (site-wide defaults, e.g. a global
+ * robots directive or a fixed title suffix set once at boot).
+ */
+export type HeadTagScope = 'page' | 'persistent';
+
+export interface HeadTagOptions {
+    scope?: HeadTagScope;
+}
+
+export interface HeadLinkOptions extends HeadTagOptions {
+    /** Extra attributes beyond rel/href — e.g. { hreflang: 'vi' } for alternate links. */
+    attrs?: Record<string, string>;
+}
+
+/**
+ * HeadService — manages `<head>` tags (title, meta, link, JSON-LD) directly
+ * against `document`, independent of any View/ViewController. Registered in
+ * the DI container as `App.Head` / `app('Head')` so any code — a view's
+ * render, a route guard, an async data callback, app bootstrap — can call it.
+ */
+export interface HeadServiceInterface {
+    setTitle(title: string, options?: HeadTagOptions): void;
+    /** `<meta name="{name}" content="{content}">` — description, keywords, robots, viewport... */
+    setMeta(name: string, content: string, options?: HeadTagOptions): void;
+    /** `<meta property="{property}" content="{content}">` — Open Graph / Twitter card tags. */
+    setMetaProperty(property: string, content: string, options?: HeadTagOptions): void;
+    /** `<link rel="{rel}" href="{href}" ...attrs>` — canonical, alternate/hreflang, etc. */
+    setLink(rel: string, href: string, options?: HeadLinkOptions): void;
+    /** `<script type="application/ld+json">` — structured data, keyed by `id` (multiple blocks allowed). */
+    setJsonLd(id: string, data: Record<string, any>, options?: HeadTagOptions): void;
+    /** Revert one managed key immediately, regardless of its scope. */
+    unset(key: string): void;
+    /** Revert every `'page'`-scoped tag to its pre-managed state. Called once per navigation. */
+    resetPage(): void;
+}

package/src/core/contracts/HelperInterface.ts

@@ -1,6 +1,6 @@
 // ─── Collection Proxy Interface ─────────────────────────────────
 
-import { ApplicationInterface } from "./ApplicationInterface";
+import { ApplicationInterface } from "./ApplicationInterface.js";
 
 export interface CollectionProxyInterface {
     all(): any[];
@@ -52,6 +52,14 @@ export interface CollectionProxyInterface {
 // ─── Helper Interface ───────────────────────────────────────────
 
 export interface HelperInterface {
+    initTranslations(config: import('../services/TranslationService.js').TranslationConfig): void;
+    getLocale(): string;
+    setLocale(locale: string): void;
+    __(key: string, replace?: Record<string, any>, locale?: string): string;
+    trans(key: string, replace?: Record<string, any>, locale?: string): string;
+    lang(key: string, replace?: Record<string, any>, locale?: string): string;
+    choice(key: string, count: number, replace?: Record<string, any>, locale?: string): string;
+    trans_choice(key: string, count: number, replace?: Record<string, any>, locale?: string): string;
     [key: string]: any;
 
      // ─── App / Service Container ─────────────────────────────────

package/src/core/contracts/HttpServiceInterface.ts

@@ -3,6 +3,8 @@
 export interface HttpRequestConfig extends RequestInit {
     headers?: Record<string, string>;
     timeout?: number;
+    dedupe?: 'cancel-previous' | 'parallel';
+    requestKey?: string;
     [key: string]: any;
 }
 
@@ -45,6 +47,7 @@ export interface HttpServiceInterface {
     cancelAll(): void;
     /** Cancel a specific pending request */
     cancel(url: string, method?: string): void;
+    cancelKey(identity: string, method?: string): void;
 
     /** Destroy — cancel all + clear interceptors */
     destroy(): void;

package/src/core/contracts/MarkerInterface.ts

@@ -24,54 +24,27 @@ export type MarkerTagName =
 // ─── MarkerRegistry Service ─────────────────────────────────────
 
 
-export type MarkerFilter = string | Record<string, any>;
-export interface MarkerRecord {
-    name: string;
-    tagName: string;
-    registryID?: string | null;
-    attributes: Record<string, any>;
-    openTag: Comment;
-    closeTag: Comment;
-    children: Array<Node>;
-    [key: string]: any;
-}
-export interface MarkupAttributes {
-    [key: string]: string;
-}
-
-export interface MarkupQueryOptions {
-    multiple?: boolean;
-    recursive?: boolean;
-}
-
-export interface MarkupQuery {
-    pattern: string;
-    attributes?: MarkupAttributes;
-    options?: MarkupQueryOptions;
-    index?: number;
-}
-
-/**
- * RegistryTag Query Options
- */
-export interface RegistryTagQueryOptions {
-    tag?: string;
-    id?: string;
-    attributes?: Record<string, any>;
-    multiple?: boolean;
-}
+export interface MarkerRegistryInterface {
+    shortcut(tag: string): string;
+    fullTag(shortcut: string): string;
+    registerShortcut(tag: string, short: string): void;
+    register(tag: string, id?: string, attributes?: Record<string, any>): string;
+    createMarkerStart(tag: string, id?: string): Comment;
+    createMarkerEnd(tag: string, id?: string): Comment;
+    get(key: string): MarkerRegistryRecord | null;
+    getByTagAndId(tag: string, id: string): MarkerRegistryRecord | null;
+    has(key: string): boolean;
+    remove(key: string): boolean;
+    getByTag(tag: string): MarkerRegistryRecord[];
+    all(): Map<string, MarkerRegistryRecord>;
+    clear(): void;
+    size: number;
+    openComment(tag: string, id?: string): string;
+    closeComment(tag: string, id?: string): string;
+    parseComment(text: string): { tag: string; id: string; isClose: boolean } | null
+    /** Claim cặp marker SSR theo O(1) qua index (null = server không render vùng này) */
+    claim(tag: string, id: string, scope?: Element | null): { open: Comment; close: Comment } | null;
+    /** Bỏ index marker — gọi đầu mỗi lượt hydrate */
+    invalidateIndex(): void;
 
-/**
- * RegistryTagData
- */
-export interface RegistryTagData {
-    systemPrefix: string;
-    tag: string;
-    id: string;
-    key: string;
-    attributes?: Record<string, any>;
-    nodes: Array<Node>;
 }
-
-
-export type RegistryIDOrAttributes = string | Record<string, any> | undefined;

package/src/core/contracts/ReactiveInterface.ts

@@ -1,12 +1,12 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { HtmlInterface, OneChildrenFactoryOutput, OneElementChildren, OneNodeInterface } from "./ElementInterface";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { HtmlInterface, SaoChildrenFactoryOutput, SaoElementChildren, SaoNodeInterface } from "./ElementInterface.js";
 
 // ─── Reactive Interface ──────────────────────────────────────────
 
 /** Reactive region bounded by comment markers — re-renders when deps change */
-export interface ReactiveInterface extends OneNodeInterface {
-    oneType: OneObjectType;
+export interface ReactiveInterface extends SaoNodeInterface {
+    saoType: SaoObjectType;
     id: string;
     type: string;
     ctx: ViewControllerInterface;
@@ -15,24 +15,24 @@ export interface ReactiveInterface extends OneNodeInterface {
     parentReactive: ReactiveInterface | null;
     openTag: Comment;
     closeTag: Comment;
-    children: OneElementChildren;
+    children: SaoElementChildren;
     unsubscribe: () => void;
     childrenFactory: ReactiveChildrenFactory;
     setChildrenFactory(factory: ReactiveChildrenFactory): void;
     setStateKeys(stateKeys: string[]): void;
     render(): void;
     destroy(): void;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneReactive: boolean;
 }
 
 // ─── Reactive Types ──────────────────────────────────────────────
 
 /** Function called by Reactive to produce DOM content between markers */
-export type ReactiveRenderFn = (ctx: ViewControllerInterface, parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+export type ReactiveRenderFn = (ctx: ViewControllerInterface, parentElement: HtmlInterface | null) => SaoChildrenFactoryOutput;
 
 /** Factory function for reactive children rendering */
-export type ReactiveChildrenFactory = (parentReactive: ReactiveInterface, parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+export type ReactiveChildrenFactory = (parentReactive: ReactiveInterface, parentElement: HtmlInterface | null) => SaoChildrenFactoryOutput;
 
 /** Reactive configuration */
 export type ReactiveConfig = {

package/src/core/contracts/RouterInterface.ts

@@ -1,4 +1,4 @@
-import type { ViewManagerInterface } from "./ViewManagerInterface";
+import type { ViewManagerInterface } from "./ViewManagerInterface.js";
 
 // ─── Router Interface ────────────────────────────────────────────
 
@@ -18,6 +18,8 @@ export interface ActiveRouteInterface {
     $query: Record<string, any>;
     $params: Record<string, any>;
     $urlPath: string;
+    /** Request URI = path + query (không gồm hash) — cache key phía ViewManager */
+    $uri?: string;
     $fragment: string;
     new(route: RouteInterface, urlPath: string, fragment: string): ActiveRouteInterface;
     setQuery(query: Record<string, any>): void;
@@ -52,7 +54,8 @@ export interface RouterInterface {
     getCurrentRoute(): ActiveRouteInterface | null;
     /** Navigation guards */
     beforeEach(guard: (to: ActiveRouteInterface, from: ActiveRouteInterface, urlPath: string) => boolean | Promise<boolean>): this;
-    afterEach(hook: (to: ActiveRouteInterface, from: ActiveRouteInterface) => void): this;
+    /** Đăng ký hook sau điều hướng; trả về hàm huỷ đăng ký. Nhiều hook cùng sống được. */
+    afterEach(hook: (to: ActiveRouteInterface, from: ActiveRouteInterface) => void): () => void;
     /** Start listening to URL changes */
     start(skipInitial?: boolean): void;
     /** Stop listening */

package/src/core/contracts/SectionInterface.ts

@@ -0,0 +1,49 @@
+import type { SaoElementChildren, 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";
+
+export type SectionItemType = 'static' | 'dynamic' | 'async' | 'reactive';
+export type SectionContentType = 'text' | 'html'
+export type SectionContentRenderer = (parentElement?: HtmlInterface | null | undefined) => string | SaoElementChildren;
+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;
+    /** Owning view instance — mirrors Block/BlockOutlet keying (`name` + `viewId`). */
+    viewId?: string | null;
+    name: string;
+    type: SectionItemType;
+    contentType?: SectionContentType;
+    stateKeys?: string[];
+    renderFactory?: SectionContentRenderer;
+}
+export interface SectionManagerInterface {
+    sections: Map<string, SectionInterface>;
+    subscribers: Map<string, ((section: SectionInterface) => void)[]>;
+    add(section: SectionInterface): void;
+    subscribe(name: string, callback: (section: SectionInterface) => void): () => void;
+    unsubscribe(name: string, callback?: (section: SectionInterface) => void): void;
+    /** Register a @yield(...) marker so mountViewSections() can find it by name. */
+    addYield(id: string, yieldEl: any): void;
+    /** Resolve the current value of a named section synchronously — used by `this.yieldContent()` in attribute/prop bindings. */
+    resolve(name: string, defaultValue?: any): any;
+    /** Mount sections owned by one controller (page or layout) into their matching yields. Mirrors BlockManagerService.mountViewBlocks(). */
+    mountViewSections(viewId: string): void;
+    /** Hydrate counterpart — claim SSR content, no DOM insertion, only (re)subscribe. */
+    hydrateViewSections(viewId: string): void;
+    startAll(): void;
+    stopAll(): void;
+    unmountView(viewId: string): void;
+    removeYieldsOfView(viewId: string): void;
+    /** Revert every page-scoped head tag (title/meta) before mounting a new page's chain. */
+    resetPageHead(): void;
+    destroy(): void;
+}

package/src/core/contracts/ServiceProviderInterface.ts

@@ -1,9 +1,9 @@
-import { OneObjectType } from "../types/utils";
-import type { ApplicationInterface } from "./ApplicationInterface";
+import { SaoObjectType } from "../types/utils.js";
+import type { ApplicationInterface } from "./ApplicationInterface.js";
 
 /** Service Provider — register() đăng ký, boot() khởi động */
 export interface ServiceProviderInterface {
-    oneType?: OneObjectType;
+    saoType?: SaoObjectType;
     name: string;
     dependsOn?: string[];
     initApplication?(App?: ApplicationInterface): void;

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