@saolabs/client 1.0.0 → 1.0.2

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;

package/src/core/devtools/index.ts

@@ -0,0 +1,38 @@
+/**
+ * DevTools — API công khai, gắn vào DI container dưới tên `Devtools`
+ * (dùng `app('Devtools')` hoặc `App.devtools`).
+ *
+ * Tắt hoàn toàn mặc định: `emit()` thoát ngay ở dòng đầu khi chưa bật, nên
+ * production không trả phí gì ngoài vài hàm không bao giờ chạy.
+ *
+ * @example
+ * App.devtools.open();              // bật + mở panel
+ * App.devtools.enableShortcut();    // Ctrl+Shift+D bật/tắt panel
+ * App.devtools.getViewTree();       // đọc cây view bằng code
+ */
+import devtools from './hook.js';
+import inspector, { bindDevtoolsShortcut } from './inspector.js';
+
+export const Devtools = {
+    /** Bật thu thập sự kiện (chưa mở UI) — dùng khi chỉ cần đọc bằng code. */
+    enable: () => devtools.enable(),
+    disable: () => { inspector.close(); devtools.disable(); },
+    isEnabled: () => devtools.isEnabled(),
+
+    /** Bật + mở panel in-page. */
+    open: () => inspector.open(),
+    close: () => inspector.close(),
+    toggle: () => inspector.toggle(),
+    isOpen: () => inspector.isOpen(),
+
+    enableShortcut: () => bindDevtoolsShortcut(),
+
+    getViewTree: () => devtools.getViewTree(),
+    getLog: () => devtools.getLog(),
+    clearLog: () => devtools.clearLog(),
+    subscribe: (fn: Parameters<typeof devtools.subscribe>[0]) => devtools.subscribe(fn),
+};
+
+export { devtools, inspector };
+export type { DevtoolsEvent, DevtoolsEventType, DevtoolsViewNode } from './hook.js';
+export default Devtools;

package/src/core/devtools/inspector.ts

@@ -0,0 +1,270 @@
+/**
+ * DevTools inspector — panel in-page, không cần cài extension.
+ *
+ * Vì sao overlay chứ không phải browser extension: extension cần scaffolding
+ * riêng (manifest, content script, bridge, publish store) mà vẫn hiển thị đúng
+ * dữ liệu này. Overlay chạy ngay ở mọi môi trường (kể cả máy khác, mobile
+ * webview) với chi phí nhỏ hơn nhiều. Hook (`devtools/hook.ts`) đã tách riêng
+ * nên extension vẫn dựng được sau này trên CÙNG nguồn dữ liệu.
+ *
+ * Bật:  App.devtools.open()   — hoặc Ctrl+Shift+D sau khi App.devtools.enable()
+ *
+ * Toàn bộ DOM của panel dựng bằng createElement + textContent — panel hiển thị
+ * state/đường dẫn/thông báo lỗi do người dùng kiểm soát, nội suy chuỗi vào
+ * innerHTML ở đây là đường tiêm HTML (đúng lỗi đã vá ở GAP-07).
+ */
+import devtools, { DevtoolsEvent, DevtoolsViewNode } from './hook.js';
+
+const PANEL_ID = '__saola_devtools_panel__';
+const HIGHLIGHT_ID = '__saola_devtools_highlight__';
+
+class Inspector {
+    private panel: HTMLElement | null = null;
+    private unsubscribe: (() => void) | null = null;
+    private refreshQueued = false;
+    private selectedViewId: string | null = null;
+
+    isOpen(): boolean { return this.panel !== null; }
+
+    open(): void {
+        if (this.panel || typeof document === 'undefined') return;
+        devtools.enable();
+
+        this.panel = this.buildPanel();
+        document.body.appendChild(this.panel);
+
+        // Gom nhiều sự kiện trong cùng frame thành 1 lần vẽ — state đổi có thể
+        // bắn hàng loạt, vẽ lại từng cái sẽ tự làm chậm chính app đang debug.
+        this.unsubscribe = devtools.subscribe(() => this.queueRefresh());
+        this.refresh();
+    }
+
+    close(): void {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.panel?.remove();
+        this.panel = null;
+        this.clearHighlight();
+    }
+
+    toggle(): void { this.isOpen() ? this.close() : this.open(); }
+
+    private queueRefresh(): void {
+        if (this.refreshQueued) return;
+        this.refreshQueued = true;
+        requestAnimationFrame(() => { this.refreshQueued = false; this.refresh(); });
+    }
+
+    // ── Dựng khung ────────────────────────────────────────────────
+
+    private buildPanel(): HTMLElement {
+        const panel = document.createElement('div');
+        panel.id = PANEL_ID;
+        panel.style.cssText = [
+            'position:fixed', 'right:12px', 'bottom:12px', 'width:380px', 'max-height:70vh',
+            'z-index:2147483647', 'display:flex', 'flex-direction:column',
+            'background:#1e1e2e', 'color:#cdd6f4', 'border:1px solid #45475a', 'border-radius:8px',
+            'font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace',
+            'box-shadow:0 8px 32px rgba(0,0,0,.4)', 'overflow:hidden',
+        ].join(';');
+
+        const header = document.createElement('div');
+        header.style.cssText = 'display:flex;align-items:center;gap:8px;padding:8px 10px;background:#181825;border-bottom:1px solid #45475a';
+        const title = document.createElement('strong');
+        title.textContent = 'Saola DevTools';
+        title.style.cssText = 'flex:1;color:#89b4fa';
+        const btnClear = this.button('Xoá log', () => { devtools.clearLog(); this.refresh(); });
+        const btnClose = this.button('✕', () => this.close());
+        header.append(title, btnClear, btnClose);
+
+        const body = document.createElement('div');
+        body.setAttribute('data-role', 'body');
+        body.style.cssText = 'overflow:auto;padding:8px 10px';
+
+        panel.append(header, body);
+        return panel;
+    }
+
+    private button(label: string, onClick: () => void): HTMLButtonElement {
+        const b = document.createElement('button');
+        b.textContent = label;
+        b.style.cssText = 'background:#313244;color:#cdd6f4;border:1px solid #45475a;border-radius:4px;padding:2px 8px;cursor:pointer;font:inherit';
+        b.addEventListener('click', onClick);
+        return b;
+    }
+
+    private section(label: string): HTMLElement {
+        const h = document.createElement('div');
+        h.textContent = label;
+        h.style.cssText = 'margin:10px 0 4px;color:#a6adc8;text-transform:uppercase;font-size:10px;letter-spacing:.08em';
+        return h;
+    }
+
+    // ── Vẽ nội dung ───────────────────────────────────────────────
+
+    private refresh(): void {
+        const body = this.panel?.querySelector('[data-role="body"]') as HTMLElement | null;
+        if (!body) return;
+        body.replaceChildren();
+
+        const tree = devtools.getViewTree();
+        body.append(this.section(`Cây view (${tree.length} gốc)`));
+        if (tree.length === 0) {
+            body.append(this.muted('Chưa có view nào mount.'));
+        } else {
+            for (const node of tree) body.append(this.renderNode(node, 0));
+        }
+
+        const log = devtools.getLog().slice(-25).reverse();
+        body.append(this.section(`Sự kiện gần đây (${log.length})`));
+        if (log.length === 0) body.append(this.muted('Chưa có sự kiện.'));
+        else for (const e of log) body.append(this.renderEvent(e));
+    }
+
+    private muted(text: string): HTMLElement {
+        const d = document.createElement('div');
+        d.textContent = text;
+        d.style.cssText = 'color:#6c7086;padding:2px 0';
+        return d;
+    }
+
+    private renderNode(node: DevtoolsViewNode, depth: number): HTMLElement {
+        const wrap = document.createElement('div');
+        wrap.style.cssText = `margin-left:${depth * 12}px`;
+
+        const row = document.createElement('div');
+        row.style.cssText = 'display:flex;gap:6px;align-items:baseline;padding:2px 4px;border-radius:4px;cursor:pointer';
+        row.addEventListener('mouseenter', () => this.highlight(node.viewId));
+        row.addEventListener('mouseleave', () => this.clearHighlight());
+        row.addEventListener('click', () => {
+            this.selectedViewId = this.selectedViewId === node.viewId ? null : node.viewId;
+            this.refresh();
+        });
+
+        const path = document.createElement('span');
+        path.textContent = node.path || '(không tên)';
+        path.style.cssText = 'color:#a6e3a1;flex:1';
+
+        const meta = document.createElement('span');
+        meta.textContent = `${node.viewType} · ${node.lifecycleState} · ${node.elementCount}el`;
+        meta.style.cssText = `color:${node.lifecycleState === 'active' ? '#6c7086' : '#f9e2af'};font-size:10px`;
+
+        row.append(path, meta);
+        wrap.append(row);
+
+        // Bấm để mở/đóng state — mặc định đóng cho gọn khi cây lớn
+        if (this.selectedViewId === node.viewId) {
+            const keys = Object.keys(node.state);
+            if (keys.length === 0) {
+                wrap.append(this.muted('  (không có state)'));
+            } else {
+                for (const key of keys) {
+                    const line = document.createElement('div');
+                    line.style.cssText = 'display:flex;gap:6px;padding-left:10px';
+                    const k = document.createElement('span');
+                    k.textContent = key + ':';
+                    k.style.cssText = 'color:#f5c2e7';
+                    const v = document.createElement('span');
+                    // textContent — state có thể chứa chuỗi do người dùng nhập
+                    v.textContent = JSON.stringify(node.state[key]) ?? 'undefined';
+                    v.style.cssText = 'color:#cdd6f4;word-break:break-all';
+                    line.append(k, v);
+                    wrap.append(line);
+                }
+            }
+        }
+
+        for (const child of node.children) wrap.append(this.renderNode(child, depth + 1));
+        return wrap;
+    }
+
+    private renderEvent(e: DevtoolsEvent): HTMLElement {
+        const colors: Record<string, string> = {
+            'view:mounted': '#a6e3a1', 'view:destroyed': '#f38ba8',
+            'state:changed': '#89b4fa', 'error': '#fab387',
+        };
+        const row = document.createElement('div');
+        row.style.cssText = 'display:flex;gap:6px;padding:1px 0';
+
+        const t = document.createElement('span');
+        t.textContent = String(e.at).padStart(6, ' ');
+        t.style.cssText = 'color:#6c7086;flex-shrink:0';
+
+        const type = document.createElement('span');
+        type.textContent = e.type;
+        type.style.cssText = `color:${colors[e.type] ?? '#cdd6f4'};flex-shrink:0`;
+
+        const detail = document.createElement('span');
+        detail.textContent = this.describe(e);
+        detail.style.cssText = 'color:#a6adc8;word-break:break-all';
+
+        row.append(t, type, detail);
+        return row;
+    }
+
+    private describe(e: DevtoolsEvent): string {
+        if (e.type === 'state:changed') return `${e.path ?? ''} [${(e.detail?.keys ?? []).join(', ')}]`;
+        if (e.type === 'error') return `${e.detail?.phase ?? ''} ${e.path ?? ''}: ${e.detail?.message ?? ''}`;
+        return e.path ?? '';
+    }
+
+    // ── Highlight vùng DOM của view theo marker ───────────────────
+
+    /**
+     * View không có 1 element bọc ngoài (kiến trúc marker, no-VDOM) → lấy
+     * bounding box của TẤT CẢ node giữa cặp marker `<!--s:v:{viewId}-s/-e-->`.
+     */
+    private highlight(viewId: string): void {
+        this.clearHighlight();
+        const range = this.rangeOfView(viewId);
+        if (!range) return;
+        const rect = range.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return;
+
+        const box = document.createElement('div');
+        box.id = HIGHLIGHT_ID;
+        box.style.cssText = [
+            'position:fixed', `left:${rect.left}px`, `top:${rect.top}px`,
+            `width:${rect.width}px`, `height:${rect.height}px`,
+            'background:rgba(137,180,250,.25)', 'border:1px solid #89b4fa',
+            'pointer-events:none', 'z-index:2147483646',
+        ].join(';');
+        document.body.appendChild(box);
+    }
+
+    private rangeOfView(viewId: string): Range | null {
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_COMMENT);
+        let open: Comment | null = null;
+        let node: Comment | null;
+        while ((node = walker.nextNode() as Comment | null)) {
+            const v = node.nodeValue?.trim() ?? '';
+            if (v === `s:v:${viewId}-s`) { open = node; continue; }
+            if (open && v === `s:v:${viewId}-e`) {
+                const range = document.createRange();
+                range.setStartAfter(open);
+                range.setEndBefore(node);
+                return range;
+            }
+        }
+        return null;
+    }
+
+    private clearHighlight(): void {
+        document.getElementById(HIGHLIGHT_ID)?.remove();
+    }
+}
+
+export const inspector = new Inspector();
+
+/** Ctrl+Shift+D bật/tắt panel — chỉ gắn khi devtools đã enable. */
+export function bindDevtoolsShortcut(): void {
+    if (typeof window === 'undefined') return;
+    window.addEventListener('keydown', (e) => {
+        if (e.ctrlKey && e.shiftKey && (e.key === 'D' || e.key === 'd')) {
+            e.preventDefault();
+            inspector.toggle();
+        }
+    });
+}
+
+export default inspector;