@saolabs/client 1.0.0 → 1.0.2

package/src/core/app/Application.ts

@@ -27,22 +27,23 @@
  * const router = app.make('router');
  */
 
-import type { ApplicationInterface, ServiceKey, ServiceFactory, ServiceBinding } from '../contracts/ApplicationInterface';
-import type { ServiceProviderInterface } from '../contracts/ServiceProviderInterface';
-import type { ViewManagerInterface, RouterInterface } from '../contracts/utils';
-import type { HelperInterface } from '../contracts/HelperInterface';
-import type { EventServiceInterface } from '../contracts/EventServiceInterface';
-import type { HttpServiceInterface } from '../contracts/HttpServiceInterface';
-import type { StoreServiceInterface } from '../contracts/StoreServiceInterface';
-import type { StorageServiceInterface } from '../contracts/StorageServiceInterface';
-import type { LoggerServiceInterface } from '../contracts/LoggerServiceInterface';
-import { APIClientInterface } from '../contracts/ApiInterface';
-import { OneObjectType, OOTEnum } from '../types/utils';
+import type { ApplicationInterface, ServiceKey, ServiceFactory, ServiceBinding } from '../contracts/ApplicationInterface.js';
+import type { ServiceProviderInterface } from '../contracts/ServiceProviderInterface.js';
+import type { ViewManagerInterface, RouterInterface } from '../contracts/utils.js';
+import type { HelperInterface } from '../contracts/HelperInterface.js';
+import type { EventServiceInterface } from '../contracts/EventServiceInterface.js';
+import type { HttpServiceInterface } from '../contracts/HttpServiceInterface.js';
+import type { StoreServiceInterface } from '../contracts/StoreServiceInterface.js';
+import type { StorageServiceInterface } from '../contracts/StorageServiceInterface.js';
+import type { LoggerServiceInterface } from '../contracts/LoggerServiceInterface.js';
+import type { HeadServiceInterface } from '../contracts/HeadServiceInterface.js';
+import { APIClientInterface } from '../contracts/ApiInterface.js';
+import { SaoObjectType, OOTEnum } from '../types/utils.js';
 
 // ─── Application ────────────────────────────────────────────────
 
 export class Application implements ApplicationInterface {
-    readonly oneType: OneObjectType = OOTEnum.APPLICATION;
+    readonly saoType: SaoObjectType = OOTEnum.APPLICATION;
     // Service properties — set during bootstrap via App.set()
     declare isInitialized: boolean;
     declare isStarted: boolean;
@@ -55,6 +56,7 @@ export class Application implements ApplicationInterface {
     declare Store: StoreServiceInterface;
     declare Storage: StorageServiceInterface;
     declare Logger: LoggerServiceInterface;
+    declare Head: HeadServiceInterface;
 
     /** Factory bindings — mỗi lần make() gọi factory tạo instance mới */
     private bindings = new Map<ServiceKey, ServiceFactory<any>>();
@@ -97,7 +99,7 @@ export class Application implements ApplicationInterface {
         '__store',
     ]; // Để track dynamic properties nếu cần
 
-    __store: Map<string, { isOverridable: boolean, value: any }> = new Map(); // Store cho dynamic properties nếu cần
+    __store: Map<any, { isOverridable: boolean, value: any }> = new Map(); // Store cho dynamic properties nếu cần
 
     [key: string]: any; // Cho phép dynamic properties nếu cần
 
@@ -179,6 +181,18 @@ export class Application implements ApplicationInterface {
      */
     instance<T>(key: ServiceKey<T>, value: T): this {
         this.singletons.set(key, value);
+        if (typeof key === 'string' && !this.ownProperties.includes(key)) {
+            this.__store.set(key, { value, isOverridable: true });
+            Object.defineProperty(this, key, {
+                get: () => this.__store.get(key)?.value,
+                set: (newValue) => {
+                    this.__store.set(key, { value: newValue, isOverridable: true });
+                    this.singletons.set(key, newValue);
+                },
+                configurable: true,
+                enumerable: false,
+            });
+        }
         return this;
     }
 
@@ -289,6 +303,15 @@ export class Application implements ApplicationInterface {
             (provider as any).initApplication();
         }
         provider.register();
+
+        // Đăng ký SAU khi app đã boot — plugin nạp muộn qua App.push(), hoặc
+        // provider của theme cắm vào giữa phiên. boot() vòng lặp chính đã chạy
+        // xong và có cờ chặn, nên nếu không gọi ở đây thì provider chỉ chạy nửa
+        // vòng đời: register() có, boot() không, và KHÔNG có lỗi nào phát ra.
+        if (this.booted && typeof provider.boot === 'function') {
+            provider.boot();
+        }
+
         return this;
     }
 
@@ -342,31 +365,35 @@ export class Application implements ApplicationInterface {
     }
 
 
-    set<T = any>(name: string, value: T, isOne: boolean = false): void {
-        if (this.ownProperties.includes(name)) {
-            return; // Không cho ghi đè lên thuộc tính có sẵn
-        }
+    set<T = any>(name: any, value: T, isOne: boolean = false): void {
         if (this.__store.has(name) && this.__store.get(name)?.isOverridable === false) {
             return; // Không cho ghi đè lên thuộc tính không thể override
         }
+        const isString = typeof name === 'string';
+        if (isString && this.ownProperties.includes(name)) {
+            return; // Không cho ghi đè lên thuộc tính có sẵn
+        }
         this.__store.set(name, { value, isOverridable: !isOne });
         this.singletons.set(name, value); // Sync → DI container
-        Object.defineProperty(this, name, {
-            get: () => this.__store.get(name)?.value,
-            set: (newValue) => {
-                if (this.__store.has(name) && this.__store.get(name)?.isOverridable === false) {
-                    return; // Không cho ghi đè nếu isOverridable là false
-                }
-                this.__store.set(name, { value: newValue, isOverridable: !isOne });
-                this.singletons.set(name, newValue); // Sync → DI container
-            },
-            configurable: isOne ? false : true,
-            enumerable: false,
-        });
+        if (isString) {
+            Object.defineProperty(this, name, {
+                get: () => this.__store.get(name)?.value,
+                set: (newValue) => {
+                    if (this.__store.has(name) && this.__store.get(name)?.isOverridable === false) {
+                        return; // Không cho ghi đè nếu isOverridable là false
+                    }
+                    this.__store.set(name, { value: newValue, isOverridable: !isOne });
+                    this.singletons.set(name, newValue); // Sync → DI container
+                },
+                configurable: isOne ? false : true,
+                enumerable: false,
+            });
+        }
     }
 
-    get<T = any>(name: string): T {
-        if (this.ownProperties.includes(name)) {
+    get<T = any>(name: any): T {
+        const isString = typeof name === 'string';
+        if (isString && this.ownProperties.includes(name)) {
             return (this as any)[name]; // Trả về thuộc tính có sẵn
         }
         // Check __store first (registered via set())

package/src/core/bootstrap/app.ts

@@ -1,7 +1,10 @@
-import { ApplicationInterface } from "../contracts/ApplicationInterface";
-import { app } from "../hellpers/app";
-import { Router } from "../routers";
-import { buildDefaultProviders, resolveProviderOrder } from "./providers";
+import { ApplicationInterface } from "../contracts/ApplicationInterface.js";
+import { app } from "../helpers/app.js";
+import { Router } from "../routers/index.js";
+import { buildDefaultProviders, resolveProviderOrder } from "./providers/index.js";
+import { readSSRBoot, readBootConfig, mergeBootConfig } from "./ssr.js";
+import { bootBundles, loadBundles } from "./bundle.js";
+import type { MergedBundles } from "../contracts/BundleInterface.js";
 
 const App: ApplicationInterface = app<ApplicationInterface>();
 
@@ -9,6 +12,41 @@ const App: ApplicationInterface = app<ApplicationInterface>();
 App.set<boolean>('isInitialized', false);
 App.set<boolean>('isStarted', false);
 
+/**
+ * Hàng đợi `App.push(fn)` — cửa cho mã KHÔNG đi qua bundler (snippet trong
+ * layout, plugin bên thứ ba, thư viện nạp bất đồng bộ).
+ *
+ * Mẫu `dataLayer.push`: trước khi file này chạy, `window.App` là một MẢNG và
+ * `.push(fn)` chỉ xếp hàng. Ở đây ta rút hàng đợi rồi thay bằng App thật, và
+ * gắn `App.push` = chạy NGAY. Nhờ vậy CÙNG MỘT dòng gọi
+ *
+ *     (window.App = window.App || []).push(fn)
+ *
+ * hoạt động ở cả ba mốc: trước khi app.js tải, trong lúc parse, và sau khi app
+ * đã boot. Tác giả plugin không phải biết mình chạy lúc nào.
+ *
+ * ⚠️ Hệ quả: `window.App` là MẢNG cho tới lúc boot. Đọc App phải đọc TRONG
+ * callback, đừng đọc ở tầng module.
+ */
+function drainPushQueue(): void {
+    if (typeof window === 'undefined') return;
+    const w = window as any;
+
+    const pending: unknown[] = Array.isArray(w.App) ? w.App : [];
+
+    (App as any).push = (fn: (app: ApplicationInterface) => void): void => {
+        if (typeof fn !== 'function') return;
+        try {
+            fn(App);
+        } catch (err) {
+            console.error('[App.push] callback ném lỗi:', err);
+        }
+    };
+    w.App = App;
+
+    for (const fn of pending) (App as any).push(fn);
+}
+
 /**
  * Khởi tạo app — đăng ký + boot tất cả providers theo dependency order.
  *
@@ -38,19 +76,55 @@ App.setMethod('init', function (config: Record<string, any> = {}) {
 /**
  * Start app — init nếu chưa, rồi start Router.
  *
+ * Nếu phát hiện SSR boot (script saola-ssr), inject vào config.view.ssr để
+ * ViewManager + Router hydrate route đầu tiên thay vì mount mới.
+ *
  * @example
  * App.start(); // init với config mặc định
  * App.start({ view: { container: '#app' } }); // init với config tùy chỉnh
  */
-App.setMethod('start', function (config?: Record<string, any>) {
+App.setMethod('start', async function (config?: Record<string, any>) {
     if (App.isStarted) {
         console.warn('[Bootstrap] App already started.');
         return;
     }
+    let bundles: MergedBundles | null = null;
     if (!App.isInitialized) {
-        App.init(config || {});
+        // Config app truyền có ưu tiên hơn boot config (window.APP_CONFIGS:
+        // routes + container từ server). Thiếu APP_CONFIGS → chỉ dùng config app.
+        const boot = readBootConfig() || {};
+        const cfg = mergeBootConfig(boot, config || {});
+
+        // SSR boot (script saola-ssr) → ssr + container cho hydrate route đầu.
+        const ssr = readSSRBoot();
+        if (ssr) {
+            cfg.view = {
+                ...(cfg.view || {}),
+                ssr: { view: ssr.view, viewId: ssr.viewId },
+                container: (cfg.view && cfg.view.container) || ssr.container,
+            };
+        }
+        // Bundle nạp rời (theme…): server phát danh sách URL trong
+        // APP_CONFIGS.bundles. Phải await TRƯỚC init để view/service/provider
+        // của chúng có mặt lúc provider boot và lúc render route đầu.
+        bundles = await loadBundles(cfg.bundles);
+        cfg.view = {
+            ...(cfg.view || {}),
+            // Bundle nạp sau ĐÈ registry của app — đúng ngữ nghĩa overlay theme.
+            registry: { ...(cfg.view?.registry || {}), ...bundles.views },
+        };
+        cfg.services = { ...(cfg.services || {}), ...bundles.services };
+        cfg.helpers = { ...(cfg.helpers || {}), ...bundles.helpers };
+        cfg.providers = [...(cfg.providers || []), ...bundles.providers];
+
+        App.init(cfg);
+        bootBundles(bundles, App);
     }
 
+    // Sau init (View/Router/Helper đã có), TRƯỚC khi render: chỗ duy nhất mà
+    // mã ngoài cắm vào được mà chắc chắn kịp.
+    drainPushQueue();
+
     App.get<Router>('Router').start();
     App.isStarted = true;
 }, true);

package/src/core/bootstrap/bundle.ts

@@ -0,0 +1,101 @@
+/**
+ * Bundle nạp rời — hợp đồng + loader.
+ *
+ * Bài toán: một gói build ĐỘC LẬP (theme) phải cắm được view / service /
+ * helper / provider vào app đang chạy, mà không chia sẻ module graph với app.
+ * Cầu nối là import map: `@saolabs/client` của gói đó resolve về đúng file
+ * entry của app, nên hai bên dùng CHUNG một instance runtime. Xem
+ * docs/EXTENSION_ARCHITECTURE.md §7.
+ */
+
+import type { ApplicationInterface } from "../contracts/ApplicationInterface.js";
+import type { MergedBundles, SaolaBundle } from "../contracts/BundleInterface.js";
+import logger from "../services/LoggerService.js";
+
+/**
+ * Khai báo một bundle. Chỉ là identity + kiểu — nó tồn tại để tên khoá là HỢP
+ * ĐỒNG chứ không phải quy ước truyền miệng, và để IDE gợi ý được.
+ *
+ * @example
+ * export default defineBundle({
+ *     name: 'theme:aurora',
+ *     views: { 'themes.aurora.modules.ping.index': factory },
+ * });
+ */
+export function defineBundle(bundle: SaolaBundle): SaolaBundle {
+    return bundle;
+}
+
+function emptyMerged(): MergedBundles {
+    return { providers: [], services: {}, helpers: {}, views: {}, boots: [], loaded: [], failed: [] };
+}
+
+/**
+ * Gộp nhiều manifest theo ĐÚNG THỨ TỰ mảng — không theo thứ tự resolve của
+ * mạng. Bundle sau ĐÈ bundle trước ở `views`/`services`/`helpers`; `providers`
+ * thì CỘNG THÊM chứ không thay, để một bundle không gỡ được provider của app.
+ */
+export function mergeBundles(bundles: Array<SaolaBundle | null | undefined>): MergedBundles {
+    const out = emptyMerged();
+
+    for (const bundle of bundles) {
+        if (!bundle || typeof bundle !== 'object') continue;
+        out.loaded.push(bundle.name ?? '(không tên)');
+        if (Array.isArray(bundle.providers)) out.providers.push(...bundle.providers);
+        if (bundle.services) Object.assign(out.services, bundle.services);
+        if (bundle.helpers) Object.assign(out.helpers, bundle.helpers);
+        if (bundle.views) Object.assign(out.views, bundle.views);
+        if (typeof bundle.boot === 'function') out.boots.push(bundle.boot.bind(bundle));
+    }
+
+    return out;
+}
+
+/**
+ * Nạp danh sách URL bundle rồi gộp lại.
+ *
+ * Tải SONG SONG nhưng gộp theo thứ tự mảng — thứ tự URL là thứ tự ưu tiên do
+ * server quyết định (`APP_CONFIGS.bundles`), không phải do mạng.
+ *
+ * Một URL hỏng KHÔNG làm sập boot: ghi vào `failed` rồi đi tiếp. Theme lỗi thì
+ * site chạy bằng view gốc, còn hơn trắng trang.
+ */
+export async function loadBundles(urls: string[] | null | undefined): Promise<MergedBundles> {
+    if (!Array.isArray(urls) || urls.length === 0) return emptyMerged();
+
+    const results = await Promise.all(urls.map(async (url): Promise<[string, SaolaBundle | null, string | null]> => {
+        try {
+            // URL đến từ runtime nên bundler không phân tích tĩnh được — đúng ý
+            // đồ. Viết literal ở đây sẽ làm GÃY build của app (rollup cố resolve
+            // một đường dẫn không có trong module graph).
+            const mod: any = await import(/* @vite-ignore */ /* webpackIgnore: true */ url);
+            // Bundle có thể khai manifest (export default) HOẶC tự đăng ký ngay
+            // trong thân module qua App.View/App.set — import đã await xong nên
+            // cả hai đều kịp trước khi render.
+            return [url, (mod?.default ?? null) as SaolaBundle | null, null];
+        } catch (err) {
+            return [url, null, String(err)];
+        }
+    }));
+
+    const merged = mergeBundles(results.map(([, bundle]) => bundle));
+    for (const [url, , error] of results) {
+        if (error) {
+            merged.failed.push([url, error]);
+            logger.error(`[Bundle] Không nạp được "${url}": ${error}`);
+        }
+    }
+
+    return merged;
+}
+
+/** Chạy `boot()` của các bundle, sau khi App đã init. Lỗi một cái không chặn cái sau. */
+export function bootBundles(merged: MergedBundles, app: ApplicationInterface): void {
+    for (const boot of merged.boots) {
+        try {
+            boot(app);
+        } catch (err) {
+            logger.error('[Bundle] boot() ném lỗi:', err);
+        }
+    }
+}

package/src/core/bootstrap/providers/ApiServiceProvider.ts

@@ -1,7 +1,7 @@
-import { APIClientInterface } from "../../contracts/ApiInterface";
-import { ApiClient } from "../../hellpers/ApiClient";
-import { PROVIDER_NAMES } from "./provider-order";
-import { ServiceProvider } from "./ServiceProvider";
+import { APIClientInterface } from "../../contracts/ApiInterface.js";
+import { ApiClient } from "../../helpers/ApiClient.js";
+import { PROVIDER_NAMES } from "./provider-order.js";
+import { ServiceProvider } from "./ServiceProvider.js";
 
 export class ApiServiceProvider extends ServiceProvider {
     readonly name = PROVIDER_NAMES.API;

package/src/core/bootstrap/providers/CoreServiceProvider.ts

@@ -1,19 +1,25 @@
-import { app } from "../../hellpers/app";
-import { EventService } from "../../services/EventService";
-import { HttpService } from "../../services/HttpService";
-import { MarkerService } from "../../services/MarkerService";
-import { StoreService } from "../../services/StoreService";
-import { PROVIDER_NAMES } from "./provider-order";
-import { ServiceProvider } from "./ServiceProvider";
+import { MarkerRegistryInterface } from "../../contracts/MarkerInterface.js";
+import { app } from "../../helpers/app.js";
+import { MarkerRegistry, MarkerRegistryService } from "../../services/index.js";
+import { EventService } from "../../services/EventService.js";
+import { HttpService } from "../../services/HttpService.js";
+import { StoreService } from "../../services/StoreService.js";
+import HeadService from "../../services/HeadService.js";
+import { Devtools } from "../../devtools/index.js";
+import type { HeadServiceInterface } from "../../contracts/HeadServiceInterface.js";
+import { PROVIDER_NAMES } from "./provider-order.js";
+import { ServiceProvider } from "./ServiceProvider.js";
 
 export class CoreServiceProvider extends ServiceProvider {
     readonly name = PROVIDER_NAMES.CORE;
 
     register(): void {
-        this.app.set<MarkerService>("Marker", app<MarkerService>(MarkerService), true);
         this.app.set<StoreService>("Store", StoreService.instance(), true);
         this.app.set<StoreService>("Storage", StoreService.instance(), true);
         this.app.set<EventService>("Event", EventService.instance(), true);
         this.app.set<HttpService>("Http", HttpService.instance(), true);
+        this.app.set<MarkerRegistryInterface>("Registry", MarkerRegistry, true);
+        this.app.set<HeadServiceInterface>("Head", HeadService, true);
+        this.app.set("Devtools", Devtools, true);
     }
 }

package/src/core/bootstrap/providers/HelperServiceProvider.ts

@@ -1,12 +1,17 @@
-import { HelperService } from "../../services/HelperService";
-import { PROVIDER_NAMES } from "./provider-order";
-import { ServiceProvider } from "./ServiceProvider";
+import { HelperService } from "../../services/HelperService.js";
+import { PROVIDER_NAMES } from "./provider-order.js";
+import { ServiceProvider } from "./ServiceProvider.js";
 
 export class HelperServiceProvider extends ServiceProvider {
     readonly name = PROVIDER_NAMES.HELPER;
     readonly dependsOn = [PROVIDER_NAMES.CORE, PROVIDER_NAMES.ROUTER, PROVIDER_NAMES.VIEW];
 
+    static config: Record<string, any> = {};
+
     register(): void {
         this.app.set<HelperService>("Helper", new HelperService(this.app), true);
     }
+    boot(): void {
+        if (HelperServiceProvider.config.i18n) this.app.get<HelperService>("Helper").initTranslations(HelperServiceProvider.config.i18n);
+    }
 }

package/src/core/bootstrap/providers/RouteServiceProvider.ts

@@ -1,9 +1,11 @@
-import { Router } from "../../routers";
-import { PROVIDER_NAMES } from "./provider-order";
-import { ServiceProvider } from "./ServiceProvider";
+import { Router } from "../../routers/index.js";
+import { ViewManager } from "../../view/index.js";
+import { PROVIDER_NAMES } from "./provider-order.js";
+import { ServiceProvider } from "./ServiceProvider.js";
 
 export class RouteServiceProvider extends ServiceProvider {
     readonly name = PROVIDER_NAMES.ROUTER;
+    /** ROUTER phải boot SAU VIEW để ViewManager đã sẵn sàng */
     readonly dependsOn = [PROVIDER_NAMES.VIEW];
     static config: Record<string, any> = {};
 
@@ -12,6 +14,15 @@ export class RouteServiceProvider extends ServiceProvider {
     }
 
     boot(): void {
-        this.app.get<Router>("Router").init(RouteServiceProvider.config);
+        const router = this.app.get<Router>("Router");
+
+        // Wire ViewManager → Router (Router cần để mountView khi navigate)
+        try {
+            const vm = this.app.get<ViewManager>("View");
+            if (vm) router.setViewManager(vm);
+        } catch (_) { /* View chưa register — Router sẽ fallback qua App.View */ }
+
+        // init: load routes config + auto-wire
+        router.init(RouteServiceProvider.config);
     }
 }

package/src/core/bootstrap/providers/ServiceProvider.ts

@@ -1,8 +1,8 @@
-import { ApplicationInterface } from "../../contracts/ApplicationInterface";
-import { ServiceProviderInterface } from "../../contracts/utils";
-import { app } from "../../hellpers/app";
-import { OneObjectType, OOTEnum } from "../../types/utils";
-import { NamedServiceProvider } from "./provider-order";
+import { ApplicationInterface } from "../../contracts/ApplicationInterface.js";
+import { ServiceProviderInterface } from "../../contracts/utils.js";
+import { app } from "../../helpers/app.js";
+import { SaoObjectType, OOTEnum } from "../../types/utils.js";
+import { NamedServiceProvider } from "./provider-order.js";
 
 /**
  * Base class cho Service Provider — API giống Laravel.
@@ -27,7 +27,7 @@ import { NamedServiceProvider } from "./provider-order";
  * }
  */
 export abstract class ServiceProvider implements ServiceProviderInterface {
-    readonly oneType: OneObjectType = OOTEnum.SERVICE_PROVIDER;
+    readonly saoType: SaoObjectType = OOTEnum.SERVICE_PROVIDER;
     abstract readonly name: string;
     readonly dependsOn?: string[];
     protected app: ApplicationInterface;
@@ -38,8 +38,8 @@ export abstract class ServiceProvider implements ServiceProviderInterface {
     }
 
     initApplication(App?: ApplicationInterface): void {
-        if (!this.app || typeof this.app !== 'object' || this.app.oneType !== OOTEnum.APPLICATION) {
-            this.app = (App && App.oneType === OOTEnum.APPLICATION) ? App : app<ApplicationInterface>();
+        if (!this.app || typeof this.app !== 'object' || this.app.saoType !== OOTEnum.APPLICATION) {
+            this.app = (App && App.saoType === OOTEnum.APPLICATION) ? App : app<ApplicationInterface>();
         }
     }
 

package/src/core/bootstrap/providers/ViewServiceProvider.ts

@@ -1,6 +1,6 @@
-import { ViewManager } from "../../view";
-import { PROVIDER_NAMES } from "./provider-order";
-import { ServiceProvider } from "./ServiceProvider";
+import { ViewManager } from "../../view/index.js";
+import { PROVIDER_NAMES } from "./provider-order.js";
+import { ServiceProvider } from "./ServiceProvider.js";
 
 export class ViewServiceProvider extends ServiceProvider {
     readonly name = PROVIDER_NAMES.VIEW;

package/src/core/bootstrap/providers/default-providers.ts

@@ -1,14 +1,14 @@
-import { ApplicationInterface } from "../../contracts/ApplicationInterface";
-import { app } from "../../hellpers/app";
-import { NamedServiceProvider, PROVIDER_NAMES } from "./provider-order";
-import { ApiServiceProvider } from "./ApiServiceProvider";
-import { CoreServiceProvider } from "./CoreServiceProvider";
-import { HelperServiceProvider } from "./HelperServiceProvider";
-import { RouteServiceProvider } from "./RouteServiceProvider";
-import { ServiceProvider } from "./ServiceProvider";
-import { ViewServiceProvider } from "./ViewServiceProvider";
-import { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface";
-import { OOTEnum } from "../../types/utils";
+import { ApplicationInterface } from "../../contracts/ApplicationInterface.js";
+import { app } from "../../helpers/app.js";
+import { NamedServiceProvider, PROVIDER_NAMES } from "./provider-order.js";
+import { ApiServiceProvider } from "./ApiServiceProvider.js";
+import { CoreServiceProvider } from "./CoreServiceProvider.js";
+import { HelperServiceProvider } from "./HelperServiceProvider.js";
+import { RouteServiceProvider } from "./RouteServiceProvider.js";
+import { ServiceProvider } from "./ServiceProvider.js";
+import { ViewServiceProvider } from "./ViewServiceProvider.js";
+import { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface.js";
+import { OOTEnum } from "../../types/utils.js";
 
 /** Provider class type — constructor nhận optional app */
 type ProviderClass = new (app?: ApplicationInterface) => ServiceProvider;
@@ -17,7 +17,7 @@ type ProviderClass = new (app?: ApplicationInterface) => ServiceProvider;
 const SYSTEM_PROVIDER_NAMES = new Set(Object.values(PROVIDER_NAMES));
 
 /** Tên system services — không cho phép ghi đè qua config.services */
-const SYSTEM_SERVICE_KEYS = new Set(['Marker', 'Store', 'Storage', 'Event', 'Http', 'View', 'Router', 'Helper', 'API']);
+const SYSTEM_SERVICE_KEYS = new Set(['Store', 'Storage', 'Event', 'Http', 'View', 'Router', 'Helper', 'API']);
 
 /**
  * Chuyển `config.services` dạng { name: Class } thành NamedServiceProvider[].
@@ -26,7 +26,7 @@ const SYSTEM_SERVICE_KEYS = new Set(['Marker', 'Store', 'Storage', 'Event', 'Htt
  * services: { Auth: AuthService, Toast: ToastService }
  * → 2 providers, mỗi cái dependsOn ['core'], register = app.set(name, new Class(app))
  */
-function servicesFromMap(map: Record<string, new (app: ApplicationInterface) => any>): ServiceProviderInterface[] {
+function servicesFromMap(map: Record<string, any>): ServiceProviderInterface[] {
     const appInstance = app<ApplicationInterface>();
     return Object.entries(map)
         .filter(([name]) => {
@@ -36,15 +36,44 @@ function servicesFromMap(map: Record<string, new (app: ApplicationInterface) =>
             }
             return true;
         })
-        .map(([name, ServiceClass]) => ({
+        .map(([name, value]) => ({
             name,
             dependsOn: [PROVIDER_NAMES.CORE],
             register() {
-                appInstance.set(name, new ServiceClass(appInstance));
+                // Bundle nạp rời (theme) hay gửi INSTANCE hoặc object thuần chứ
+                // không phải class — `new` vô điều kiện sẽ ném "is not a
+                // constructor". Chỉ dựng khi thật sự là class.
+                const isClass = typeof value === 'function' && value.prototype;
+                appInstance.set(name, isClass ? new value(appInstance) : value);
             }
         }));
 }
 
+/**
+ * `config.helpers` = { tên: fn } → MỘT provider gộp, phụ thuộc `helper`.
+ *
+ * Không gán tay sau `init()`: `App.Helper` chỉ tồn tại sau khi
+ * HelperServiceProvider register, nên phải để resolveProviderOrder xếp chỗ.
+ * Gán tay thì provider nào đọc helper trong boot() của mình sẽ nhận undefined.
+ */
+function helpersFromMap(map: Record<string, any>): ServiceProviderInterface[] {
+    const appInstance = app<ApplicationInterface>();
+    if (!map || Object.keys(map).length === 0) return [];
+
+    return [{
+        name: 'bundle.helpers',
+        dependsOn: [PROVIDER_NAMES.HELPER],
+        register() {
+            const helper = appInstance.get<Record<string, any>>('Helper');
+            if (!helper) {
+                console.warn('[Bootstrap] Helper chưa sẵn sàng, bỏ qua config.helpers.');
+                return;
+            }
+            Object.assign(helper, map);
+        }
+    }];
+}
+
 /**
  * Tạo danh sách providers mặc định.
  *
@@ -60,6 +89,7 @@ export function buildDefaultProviders(config: Record<string, any> = {}): NamedSe
     // Set static config cho default providers trước khi tạo instance
     ViewServiceProvider.config = config.view || {};
     RouteServiceProvider.config = config.router || {};
+    HelperServiceProvider.config = { i18n: config.i18n };
     ApiServiceProvider.config = config.api || {};
     const App = app<ApplicationInterface>();
     const defaults: NamedServiceProvider[] = [
@@ -75,6 +105,11 @@ export function buildDefaultProviders(config: Record<string, any> = {}): NamedSe
         ? servicesFromMap(config.services)
         : [];
 
+    // config.helpers: { tên: fn } → một provider phụ thuộc `helper`
+    const helperProviders = config.helpers
+        ? helpersFromMap(config.helpers)
+        : [];
+
     // config.providers: (ProviderClass | NamedServiceProvider)[] → instantiate classes
     const customProviders: NamedServiceProvider[] = Array.isArray(config.providers)
         ? config.providers
@@ -90,5 +125,5 @@ export function buildDefaultProviders(config: Record<string, any> = {}): NamedSe
             })
         : [];
 
-    return [...defaults, ...serviceProviders, ...customProviders];
+    return [...defaults, ...serviceProviders, ...helperProviders, ...customProviders];
 }

package/src/core/bootstrap/providers/index.ts

@@ -1,9 +1,9 @@
-export { NamedServiceProvider, resolveProviderOrder, PROVIDER_NAMES } from './provider-order';
-export type { ProviderName } from './provider-order';
-export { ServiceProvider } from './ServiceProvider';
-export { buildDefaultProviders } from './default-providers';
-export { CoreServiceProvider } from './CoreServiceProvider';
-export { ViewServiceProvider } from './ViewServiceProvider';
-export { RouteServiceProvider } from './RouteServiceProvider';
-export { HelperServiceProvider } from './HelperServiceProvider';
-export { ApiServiceProvider } from './ApiServiceProvider';
+export { NamedServiceProvider, resolveProviderOrder, PROVIDER_NAMES } from './provider-order.js';
+export type { ProviderName } from './provider-order.js';
+export { ServiceProvider } from './ServiceProvider.js';
+export { buildDefaultProviders } from './default-providers.js';
+export { CoreServiceProvider } from './CoreServiceProvider.js';
+export { ViewServiceProvider } from './ViewServiceProvider.js';
+export { RouteServiceProvider } from './RouteServiceProvider.js';
+export { HelperServiceProvider } from './HelperServiceProvider.js';
+export { ApiServiceProvider } from './ApiServiceProvider.js';