@saolabs/client 1.0.0 → 1.1.0

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;

package/src/core/elements/Block.ts

@@ -1,12 +1,12 @@
-import type { BlockInterface, BlockRenderFactory } from "../contracts/BlockInterface";
-import { InitMode } from "../contracts/common";
-import type { FragmentInterface, HtmlInterface } from "../contracts/ElementInterface";
-import type { ReactiveInterface } from "../contracts/ReactiveInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { generateUUID } from "../hellpers/utils";
-import markerRegistry from "../services/MarkerRegistry";
-import type { OneObjectType } from "../types/utils";
-import { Fragment } from "./Fragment";
+import type { BlockInterface, BlockRenderFactory } from "../contracts/BlockInterface.js";
+import { InitMode, InitModes } from "../contracts/common.js";
+import type { FragmentInterface, HtmlInterface } from "../contracts/ElementInterface.js";
+import type { ReactiveInterface } from "../contracts/ReactiveInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import type { SaoObjectType } from "../types/utils.js";
+import { Fragment } from "./Fragment.js";
 /**
  * Block — a named mounting slot used in layout views.
  * 
@@ -26,23 +26,24 @@ import { Fragment } from "./Fragment";
  *   4. Browser back → BlockManager restores cached content without re-render
  */
 export class Block implements BlockInterface {
-    oneType: OneObjectType = 'Block';
+    saoType: SaoObjectType = 'Block';
     id: string;
     name: string;
     ctx: ViewControllerInterface;
     viewId: string | null = null;
+    /** Key trả về bởi markerRegistry.register — destroy() dùng để gỡ lại */
+    private markerKey: string | null = null;
     fragment: FragmentInterface | null = null;
     contentRenderFactory: BlockRenderFactory | null = null;
     openTag: Comment;
     closeTag: Comment;
-
     domChildren: Node[] = [];
     initMode?: InitMode | undefined;
     parentElement: HtmlInterface | null = null;
 
     public readonly isOneBlock = true;
-    public readonly isOneElement = false;
-    
+    public readonly isSaoElement = false;
+
     constructor({
         ctx,
         name,
@@ -58,15 +59,27 @@ export class Block implements BlockInterface {
         id?: string | null;
         initMode?: InitMode;
     }) {
-        this.id = `${this.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+        this.id = id ?? generateUUID(10); // Unique ID for debugging
         this.ctx = ctx;
         this.name = name;
         this.viewId = viewId ?? ctx.viewId; // Associate block with current viewId
         this.initMode = initMode;
         this.contentRenderFactory = contentRenderFactory || ((parentElement: HtmlInterface) => []);
-        markerRegistry.register('block', this.id, { name, viewId }); // Register block in marker registry
-        this.openTag = markerRegistry.createMarkerStart('block', this.id);
-        this.closeTag = markerRegistry.createMarkerEnd('block', this.id);
+        // Hydrate: claim cặp marker server qua index O(1) của MarkerRegistry.
+        // (Bản cũ dùng chung một TreeWalker không reset nên chỉ block ĐẦU TIÊN
+        // claim được, các block sau lặng lẽ tạo marker mới.)
+        const claimed = (this.initMode === InitModes.HYDRATE)
+            ? markerRegistry.claim('block', this.id)
+            : null;
+
+        if (claimed) {
+            this.openTag = claimed.open;
+            this.closeTag = claimed.close;
+        } else {
+            this.openTag = markerRegistry.createMarkerStart('block', this.id);
+            this.closeTag = markerRegistry.createMarkerEnd('block', this.id);
+            this.markerKey = markerRegistry.register('block', this.id, { name, viewId }); // Register block in marker registry
+        }
 
     }
 
@@ -90,7 +103,7 @@ export class Block implements BlockInterface {
     }
 
     mount(mountCtx: ViewControllerInterface, parentElement: HtmlInterface): any {
-        if(this.fragment) {
+        if (this.fragment) {
             this.fragment.parent = parentElement;
             this.fragment.render();
         }
@@ -99,14 +112,23 @@ export class Block implements BlockInterface {
         // Unmount logic (e.g. hide or remove DOM nodes, stop reactions)
     }
     destroy(): void {
-        // Cleanup logic (e.g. remove DOM nodes, clear caches)
+        // MarkerRegistry là singleton toàn cục — không gỡ thì record sống qua navigate.
+        if (this.markerKey) {
+            markerRegistry.remove(this.markerKey);
+            this.markerKey = null;
+        }
+        // openTag/closeTag nay NẰM TRONG DOM (BlockManager.mountBlockIntoOutlet chèn
+        // chúng quanh content). Bỏ lại comment mồ côi thì lần hydrate sau
+        // markerRegistry.claim('block', id) có thể bắt trúng cặp cũ và claim nhầm vùng.
+        this.openTag.remove();
+        this.closeTag.remove();
     }
     update(): void {
         // Update logic (e.g. re-render content on state change)
     }
 
-     /** Set the block's parent element (used for mounting) */
-     setParentElement(parentElement: HtmlInterface | null): void {
+    /** Set the block's parent element (used for mounting) */
+    setParentElement(parentElement: HtmlInterface | null): void {
         this.parentElement = parentElement;
     }
 

package/src/core/elements/BlockOutlet.ts

@@ -1,13 +1,13 @@
-import type { BlockOutletInterface } from "../contracts/BlockInterface";
-import { InitMode } from "../contracts/common";
-import type { HtmlInterface } from "../contracts/ElementInterface";
-import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { generateUUID } from "../hellpers/utils";
-import markerRegistry  from "../services/MarkerRegistry";
-import type { OneObjectType } from "../types/utils";
+import type { BlockOutletInterface } from "../contracts/BlockInterface.js";
+import { InitMode, InitModes } from "../contracts/common.js";
+import type { HtmlInterface } from "../contracts/ElementInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import markerRegistry from "../services/MarkerRegistry.js";
+import type { SaoObjectType } from "../types/utils.js";
 
 export class BlockOutlet implements BlockOutletInterface {
-    oneType: OneObjectType = 'BlockOutlet';
+    saoType: SaoObjectType = 'BlockOutlet';
     id: string;
     name: string;
     openTag: Comment;
@@ -15,38 +15,78 @@ export class BlockOutlet implements BlockOutletInterface {
     parent: HtmlInterface | null = null;
     parentElement: HtmlInterface | null = null;
     ctx: ViewControllerInterface;
-    initMode: InitMode = 'create';
-    constructor({ ctx, parentElement = null, name, id = null, initMode = 'create' }: { ctx: ViewControllerInterface, parentElement?: HtmlInterface | null, name: string, id?: string | null, initMode?: InitMode }) {
-        this.id = `${ctx.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+    initMode: InitMode = InitModes.CREATE;
+    constructor({ ctx, parentElement = null, name, id = null, initMode = InitModes.CREATE }: { ctx: ViewControllerInterface, parentElement?: HtmlInterface | null, name: string, id?: string | null, initMode?: InitMode }) {
+        this.id = id ?? generateUUID(10); // Unique ID for debugging
         this.ctx = ctx;
         this.name = name;
         this.parent = parentElement;
         this.parentElement = parentElement;
         this.initMode = initMode;
 
-        markerRegistry.register('blockoutlet', this.id, { name, viewId: ctx.viewId }); // Register this outlet in the MarkerRegistry
+        if (this.initMode === InitModes.HYDRATE) {
+            // Claim cặp marker server <!--s:bo:{id}-s--> ... <!--s:bo:{id}-e-->
+            const claimed = this.claimSSRMarkers();
+            if (claimed) {
+                this.openTag = claimed.open;
+                this.closeTag = claimed.close;
+            } else {
+                this.openTag = markerRegistry.createMarkerStart('blockoutlet', this.id);
+                this.closeTag = markerRegistry.createMarkerEnd('blockoutlet', this.id);
+                this.markerKey = markerRegistry.register('blockoutlet', this.id, { name, viewId: ctx.viewId });
+            }
+        }
+        else {
+            this.openTag = markerRegistry.createMarkerStart('blockoutlet', this.id);
+            this.closeTag = markerRegistry.createMarkerEnd('blockoutlet', this.id);
+            this.markerKey = markerRegistry.register('blockoutlet', this.id, { name, viewId: ctx.viewId }); // Register this outlet in the MarkerRegistry
+        }
 
-        this.openTag = markerRegistry.createMarkerStart('blockoutlet', this.id);
-        this.closeTag = markerRegistry.createMarkerEnd('blockoutlet', this.id);
+    }
+
+    /**
+     * Tìm cặp marker outlet từ server-rendered HTML (format chuẩn §5.1):
+     *   open:  s:bo:{id}-s   close: s:bo:{id}-e
+     * Tra index của MarkerRegistry, chặn trong parentElement nếu có.
+     */
+    private claimSSRMarkers(): { open: Comment; close: Comment } | null {
+        return markerRegistry.claim('blockoutlet', this.id, this.parentElement?.element ?? null);
     }
 
     hydrate(): void {
         // Hydration logic if needed (e.g. reattach event listeners)
     }
 
+    /** Registry guard */
+    public __destroyed__: boolean = false;
+    /** Key trả về bởi markerRegistry.register — destroy() dùng để gỡ lại */
+    private markerKey: string | null = null;
+
+    /** Render — idempotent: markers đã trong DOM thì giữ nguyên (same-layout reuse) */
     render(): void {
-        if (!this.parentElement || !this.parentElement.element) return;
+        if (this.__destroyed__) return;
+        if (this.openTag.parentNode) return; // đã đặt — không đặt lại
 
+        if (!this.parentElement || !this.parentElement.element) return;
         const parentEl = this.parentElement.element;
-
-        // Place markers
         parentEl.appendChild(this.openTag);
-        // Register this outlet in the MarkerRegistry for block mounting
         parentEl.appendChild(this.closeTag);
-
     }
 
     destroy(): void {
+        this.__destroyed__ = true;
+        this.ctx.releaseElement?.(this);
+        if (this.markerKey) {
+            markerRegistry.remove(this.markerKey);
+            this.markerKey = null;
+        }
+        // Clear nội dung giữa markers (block content nếu còn)
+        let current: Node | null = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            const next: Node | null = current.nextSibling;
+            (current as ChildNode).remove();
+            current = next;
+        }
         // Remove markers from DOM
         this.openTag.remove();
         this.closeTag.remove();
@@ -65,11 +105,11 @@ export class BlockOutlet implements BlockOutletInterface {
         this.parentElement = parentElement;
     }
 
-    get isOneElement(): boolean {
+    get isSaoElement(): boolean {
         return true;
     }
 
-    set isOneElement(value: boolean) {
+    set isSaoElement(value: boolean) {
         // No-op setter to satisfy OneElement interface
     }