qdadm 1.13.0 → 1.19.2

package/src/kernel/Kernel.i18n.ts

@@ -0,0 +1,29 @@
+/**
+ * Patch Kernel prototype with i18n-related methods.
+ *
+ * Adds:
+ *   - kernel.i18n  : I18n instance
+ *   - _createI18n() : init step
+ *   - _bootstrapI18n() : warmup step (loads default + fallback locales)
+ */
+
+import { I18n } from '../i18n/I18n'
+import type { I18nOptions } from '../i18n/types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyI18nMethods(KernelClass: { prototype: any }): void {
+  const proto = KernelClass.prototype as Self
+
+  proto._createI18n = function (this: Self): void {
+    const opts = (this.options.i18n as I18nOptions | undefined) ?? {}
+    this.i18nInstance = new I18n(opts, { signals: this.signals })
+  }
+
+  proto._bootstrapI18n = function (this: Self): Promise<void> {
+    if (!this.i18nInstance) return Promise.resolve()
+    return this.i18nInstance.bootstrap()
+  }
+}

package/src/kernel/Kernel.modules.ts

@@ -15,6 +15,12 @@ export function applyModuleMethods(KernelClass: { prototype: any }): void {
    * Fire entity cache warmups
    */
   proto._fireWarmups = function (this: Self): void {
+    if (this.i18nInstance) {
+      // Fire-and-forget bootstrap; locale-sensitive pages await
+      // 'i18n:locale:{loc}:ready' via DeferredRegistry if needed.
+      void this._bootstrapI18n()
+    }
+
     const warmup = this.options.warmup ?? true
     if (!warmup) return
 

package/src/kernel/Kernel.registries.ts

@@ -24,9 +24,18 @@ export function applyRegistryMethods(KernelClass: { prototype: any }): void {
   const proto = KernelClass.prototype as Self
 
   /**
-   * Create signal bus for event-driven communication
+   * Create signal bus for event-driven communication.
+   *
+   * When `options.existingSignals` is provided (host shell already
+   * owns a bus), reuse it instead of spinning up a fresh one. This
+   * is what lets qdcms and qdadm share entity events when they're
+   * mounted on the same Vue app.
    */
   proto._createSignalBus = function (this: Self): void {
+    if (this.options.existingSignals) {
+      this.signals = this.options.existingSignals
+      return
+    }
     const debug = this.options.debug ?? false
     this.signals = createSignalBus({ debug })
   }
@@ -189,7 +198,6 @@ export function applyRegistryMethods(KernelClass: { prototype: any }): void {
     const debug = this.options.debug ?? false
     this.eventRouter = createEventRouter({
       signals: this.signals!,
-      orchestrator: this.orchestrator,
       routes,
       debug,
     })

package/src/kernel/Kernel.routing.ts

@@ -19,7 +19,14 @@ export function applyRoutingMethods(KernelClass: { prototype: any }): void {
   const proto = KernelClass.prototype as Self
 
   /**
-   * Create Vue Router
+   * Create Vue Router.
+   *
+   * When `options.existingRouter` is provided, the Kernel reuses it
+   * and registers its computed routes via `addRoute()` instead of
+   * calling `createRouter()`. Combined with `options.routePrefix`,
+   * this lets a host mount the whole admin tree under a sub-path
+   * (e.g. `routePrefix: '/admin'` shifts the layout to `/admin` and
+   * the catch-all to `/admin/:pathMatch(.*)*`).
    */
   proto._createRouter = function (this: Self): void {
     const { pages, homeRoute, coreRoutes, basePath } = this.options
@@ -111,6 +118,26 @@ export function applyRoutingMethods(KernelClass: { prototype: any }): void {
 
     routes.push(notFoundRoute)
 
+    // ──────────────────────────────────────────────────────────────
+    // routePrefix: prepend to every Kernel-built route so the whole
+    // tree mounts under a sub-path (host scenarios like a CMS that
+    // lives at `/` and hosts qdadm at `/admin`). Empty by default.
+    const prefix = (this.options.routePrefix ?? '').replace(/\/+$/, '')
+    if (prefix) {
+      routes = routes.map((r) => prefixRoute(r, prefix))
+    }
+
+    if (this.options.existingRouter) {
+      // Host shell owns the router. Skip createRouter, register on
+      // the supplied instance. We do NOT touch history mode here —
+      // the host is responsible for that.
+      this.router = this.options.existingRouter
+      for (const r of routes) {
+        this.router.addRoute(r)
+      }
+      return
+    }
+
     const { hashMode } = this.options
     const history = hashMode
       ? createWebHashHistory(basePath)
@@ -290,3 +317,18 @@ export function applyRoutingMethods(KernelClass: { prototype: any }): void {
     this.activeStack!.set(levels)
   }
 }
+
+/**
+ * Prepend a path prefix to a top-level route record. Children inherit
+ * relative paths so we only touch the outer record. Used by the
+ * `routePrefix` option to mount the whole admin tree under a sub-path
+ * of the host router.
+ */
+function prefixRoute(route: RouteRecordRaw, prefix: string): RouteRecordRaw {
+  if (!route.path) return route
+  // Normalise: ensure single leading slash.
+  const tail = route.path.startsWith('/') ? route.path : `/${route.path}`
+  // `/` becomes the prefix itself, otherwise prefix + tail.
+  const newPath = tail === '/' ? prefix : `${prefix}${tail}`
+  return { ...route, path: newPath }
+}

package/src/kernel/Kernel.ts

@@ -75,6 +75,8 @@ import { applyModuleMethods } from './Kernel.modules'
 import { applyRegistryMethods } from './Kernel.registries'
 import { setQdadmDebugBar, applyVueMethods } from './Kernel.vue'
 import { applyApiMethods } from './Kernel.api'
+import { applyI18nMethods } from './Kernel.i18n'
+import type { I18n } from '../i18n/I18n'
 
 export class Kernel {
   options: KernelOptions
@@ -94,6 +96,7 @@ export class Kernel {
   activeStack: ActiveStack | null = null
   stackHydrator: StackHydrator | null = null
   notificationStore: NotificationStore | null = null
+  i18nInstance: I18n | null = null
 
   /** Pending provides from modules (applied after vueApp creation) */
   _pendingProvides: Map<string | symbol, unknown> = new Map()
@@ -152,6 +155,7 @@ export class Kernel {
   createApp(): App {
     this._resolveEntityAuthAdapter()
     this._createSignalBus()
+    this._createI18n()
     this._createHookRegistry()
     this._createZoneRegistry()
     this._createActiveStack()
@@ -185,6 +189,7 @@ export class Kernel {
   async createAppAsync(): Promise<App> {
     this._resolveEntityAuthAdapter()
     this._createSignalBus()
+    this._createI18n()
     this._createHookRegistry()
     this._createZoneRegistry()
     this._createActiveStack()
@@ -355,6 +360,39 @@ export class Kernel {
     const debugModule = this.getDebugModule()
     return debugModule?.getBridge?.() ?? null
   }
+
+  /**
+   * I18n subsystem accessor
+   */
+  get i18n(): I18n | null {
+    return this.i18nInstance
+  }
+
+  /**
+   * Build the merged context every qdadm debug collector expects.
+   *
+   * Used by hosts that own a shared `DebugBridge` (passed via
+   * `debugBar.bridge`) and need to install it themselves with a
+   * context covering both qdadm internals and host-side data. Hosts
+   * should `Object.assign({}, kernel.getDebugContext(), { … })` to
+   * weave in their own keys (e.g. cms) before calling
+   * `bridge.install()`.
+   *
+   * Returning a flat object keeps the surface stable as Kernel
+   * internals evolve — the host pokes nothing.
+   */
+  getDebugContext(): Record<string, unknown> {
+    return {
+      signals: this.signals,
+      router: this.router,
+      orchestrator: this.orchestrator,
+      zones: this.zoneRegistry,
+      hooks: this.hookRegistry,
+      activeStack: this.activeStack,
+      stackHydrator: this.stackHydrator,
+      i18n: this.i18nInstance,
+    }
+  }
 }
 
 // Declare prototype-patched methods
@@ -383,6 +421,10 @@ export interface Kernel {
   _wireModulesAsync(): Promise<void>
   _fireWarmups(): void
 
+  // i18n (Kernel.i18n.ts)
+  _createI18n(): void
+  _bootstrapI18n(): Promise<void>
+
   // Registries (Kernel.registries.ts)
   _createSignalBus(): void
   _createHookRegistry(): void
@@ -415,3 +457,4 @@ applyModuleMethods(Kernel)
 applyRegistryMethods(Kernel)
 applyVueMethods(Kernel)
 applyApiMethods(Kernel)
+applyI18nMethods(Kernel)

package/src/kernel/Kernel.types.ts

@@ -10,6 +10,7 @@ import type { RoutesConfig } from './EventRouter'
 import type { EntityManager } from '../entity/EntityManager'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
+import type { I18nOptions } from '../i18n/types'
 
 /**
  * Auth adapter interface (app-level authentication)
@@ -115,6 +116,15 @@ export interface DebugBarConfig {
   component?: Component
   enabled?: boolean
   _kernelManaged?: boolean
+  /**
+   * Optional shared `DebugBridge` to register qdadm collectors onto.
+   * When provided, the host shell owns the bridge (collectors from
+   * other frameworks like qdcms can be added too) and is responsible
+   * for calling `bridge.install(mergedCtx)` once everything is
+   * registered. Without it, the DebugModule creates and installs its
+   * own bridge as before.
+   */
+  bridge?: unknown
   [key: string]: unknown
 }
 
@@ -135,7 +145,12 @@ export type HomeRoute = string | { name?: string; component?: Component }
  * Kernel options
  */
 export interface KernelOptions {
-  root: Component
+  /**
+   * Root component the Kernel should mount. Required UNLESS
+   * `existingApp` is provided (host shell already created and owns
+   * the Vue app). Validated at runtime in `_createVueApp`.
+   */
+  root?: Component
   modules?: Record<string, unknown>
   modulesOptions?: Record<string, unknown>
   moduleDefs?: unknown[]
@@ -167,6 +182,42 @@ export interface KernelOptions {
   toast?: Record<string, unknown>
   debug?: boolean
   onAuthExpired?: (payload: unknown) => void
+  i18n?: I18nOptions
+  /**
+   * Existing Vue app to install qdadm onto. When provided, the Kernel
+   * skips its own `createApp(WrappedRoot)` and reuses the supplied
+   * instance — useful when a host shell (e.g. a CMS) already owns the
+   * Vue app and wants qdadm as a guest. The host is responsible for
+   * rendering qdadm's DOM extras (debug bar, toast root); see
+   * `<QdadmRoot />` for a drop-in helper.
+   *
+   * Pinia / PrimeVue / vue-router are still installed by the Kernel
+   * unless the host has already done so — re-install is idempotent for
+   * the standard plugins.
+   */
+  existingApp?: import('vue').App
+  /**
+   * Existing vue-router to register Kernel routes onto. When provided,
+   * the Kernel skips `createRouter()` and adds its computed routes via
+   * `existingRouter.addRoute(...)` instead. Combine with `routePrefix`
+   * to mount qdadm under a sub-path of the host (e.g. `/admin`).
+   */
+  existingRouter?: import('vue-router').Router
+  /**
+   * Existing SignalBus to use instead of creating one. Critical when
+   * the host already runs a SignalBus that other frameworks (e.g.
+   * qdcms) emit on / listen to — sharing the bus is what makes
+   * cross-framework reactivity work.
+   */
+  existingSignals?: SignalBus
+  /**
+   * Prefix prepended to every route the Kernel registers. Use with
+   * `existingRouter` to mount the whole admin tree under a sub-path
+   * (e.g. `routePrefix: '/admin'` makes the layout-children land at
+   * `/admin/home`, `/admin/users`, etc., and the catch-all becomes
+   * `/admin/:pathMatch(.*)*`). Default: '' (no prefix — root mount).
+   */
+  routePrefix?: string
 }
 
 /**

package/src/kernel/Kernel.vue.ts

@@ -2,8 +2,10 @@ import {
   createApp,
   h,
   defineComponent,
+  ref,
   type App,
   type Component,
+  type Ref,
 } from 'vue'
 import { createPinia } from 'pinia'
 import ToastService from 'primevue/toastservice'
@@ -13,17 +15,43 @@ import Toast from 'primevue/toast'
 import ToastListener from '../toast/ToastListener.vue'
 import { createQdadm } from '../plugin.js'
 import { createNotificationStore, NOTIFICATION_KEY } from '../notifications/NotificationStore'
+import { I18N_INJECTION_KEY } from '../i18n/useI18n'
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type Self = any
 
-// Module-level reference to debug bar component (set by constructor)
-let _QdadmDebugBar: Component | null = null
+/**
+ * Reactive reference to the debug bar component, set by the Kernel
+ * constructor when `debugBar.component` is provided.
+ *
+ * Why a window-stashed ref instead of a plain module-level export:
+ * Vite's HMR can fragment a single source module into multiple live
+ * instances (each importer getting a different `?t=…` version after
+ * HMR), so a module-level `const ref` is NOT shared across
+ * importers. Stashing the ref on `window.__qdadmDebugBarRef` (and
+ * lazy-initialising) is the only way to guarantee a single instance
+ * across all callers in dev. The Kernel writes via
+ * `setQdadmDebugBar()`; `<QdadmRoot />` reads via the same getter.
+ */
+const QDADM_DEBUG_BAR_GLOBAL_KEY = '__qdadmDebugBarRef'
+
+export function getQdadmDebugBarRef(): Ref<Component | null> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const w = typeof window !== 'undefined' ? (window as any) : null
+  if (w && w[QDADM_DEBUG_BAR_GLOBAL_KEY]) return w[QDADM_DEBUG_BAR_GLOBAL_KEY]
+  const r = ref<Component | null>(null)
+  if (w) w[QDADM_DEBUG_BAR_GLOBAL_KEY] = r
+  return r
+}
+
+/** Back-compat alias — same instance as `getQdadmDebugBarRef()`. */
+export const qdadmDebugBarRef: Ref<Component | null> = getQdadmDebugBarRef()
 
 /**
- * Set the debug bar component reference (called from Kernel constructor)
+ * Set the debug bar component reference (called from Kernel
+ * constructor). Equivalent to `getQdadmDebugBarRef().value = component`.
  */
 export function setQdadmDebugBar(component: Component | null): void {
-  _QdadmDebugBar = component
+  getQdadmDebugBarRef().value = component
 }
 
 /**
@@ -47,16 +75,33 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
   }
 
   /**
-   * Create Vue app instance
+   * Create Vue app instance.
+   *
+   * When `options.existingApp` is provided, the Kernel reuses the
+   * host's app and skips its own `createApp(WrappedRoot)`. The host
+   * is then responsible for rendering qdadm's DOM extras (Toast,
+   * ToastListener, DebugBar) — see `<QdadmRoot />` for a drop-in
+   * helper that does it.
+   *
+   * `options.root` is ignored in this mode (the host already mounted
+   * its own root).
    */
   proto._createVueApp = function (this: Self): void {
+    if (this.options.existingApp) {
+      this.vueApp = this.options.existingApp
+      return
+    }
+
     if (!this.options.root) {
-      throw new Error('[Kernel] root component is required')
+      throw new Error('[Kernel] root component is required (or pass options.existingApp)')
     }
 
     const OriginalRoot = this.options.root
+    const debugBarRef = getQdadmDebugBarRef()
     const DebugBarComponent =
-      this.options.debugBar?.component && _QdadmDebugBar ? _QdadmDebugBar : null
+      this.options.debugBar?.component && debugBarRef.value
+        ? debugBarRef.value
+        : null
     const hasPrimeVue = !!this.options.primevue?.plugin
     const appKey = this._appKey
 
@@ -88,15 +133,32 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
   }
 
   /**
-   * Install all plugins on Vue app
+   * Install all plugins on Vue app.
+   *
+   * When a host shell uses `existingApp`, it may have already
+   * installed Pinia / PrimeVue / vue-router. Calling `app.use(plugin)`
+   * twice is harmless for stateless plugins (vue-router, Pinia
+   * recognise the duplicate and no-op), but PrimeVue does not — guard
+   * with `_qdadmPluginsInstalled` markers on globalProperties so the
+   * Kernel never double-installs PrimeVue, ToastService, or
+   * ConfirmationService.
    */
   proto._installPlugins = function (this: Self): void {
     const app = this.vueApp!
-    const { authAdapter, features, primevue } = this.options
+    const { authAdapter, features, primevue, existingApp } = this.options
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const marks = (app.config.globalProperties as any).__qdadmInstalled ??= {
+      pinia: false,
+      primevue: false,
+      router: false,
+    }
 
-    app.use(createPinia())
+    if (!marks.pinia) {
+      app.use(createPinia())
+      marks.pinia = true
+    }
 
-    if (primevue?.plugin) {
+    if (primevue?.plugin && !marks.primevue) {
       const pvConfig = {
         theme: {
           preset: primevue.theme,
@@ -110,9 +172,20 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
       app.use(ToastService)
       app.use(ConfirmationService)
       app.directive('tooltip', Tooltip)
+      marks.primevue = true
     }
 
-    app.use(this.router!)
+    // Skip vue-router install when the host owned the router from the
+    // start — they already called `app.use(router)`. Calling it again
+    // emits Vue's "Plugin has already been applied" warning. When
+    // Kernel created the router itself, install is required.
+    if (!marks.router && !this.options.existingRouter) {
+      app.use(this.router!)
+      marks.router = true
+    }
+
+    // Avoid eslint unused-var warning when host owns the app
+    void existingApp
 
     for (const [key, value] of this._pendingProvides) {
       app.provide(key, value)
@@ -133,6 +206,31 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
     app.provide('qdadmStackHydrator', this.stackHydrator)
 
     if (this.options.debug && typeof window !== 'undefined') {
+      const self = this
+      // Single namespaced surface for browser-console & agent introspection.
+      // The `debug` sub-object proxies to whatever DebugBridge the DebugModule
+      // installed (resolved lazily so we don't depend on module load order).
+      const debugProxy = {
+        get bridge() {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const debugMod = (self as any).moduleLoader?.getModules?.()?.get?.('debug')
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          return debugMod?.getBridge?.() ?? (debugMod as any)?._bridge ?? null
+        },
+        describe(): unknown {
+          const b = this.bridge
+          return b ? b.describe() : null
+        },
+        dump(): unknown {
+          const b = this.bridge
+          return b ? b.dump() : null
+        },
+        call(name: string, action: string, args: Record<string, unknown> = {}): Promise<unknown> {
+          const b = this.bridge
+          if (!b) return Promise.reject(new Error('[qdadm] DebugBridge unavailable'))
+          return b.call(name, action, args)
+        },
+      }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       ;(window as any).__qdadm = {
         kernel: this,
@@ -144,18 +242,23 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
         stackHydrator: this.stackHydrator,
         deferred: this.deferred,
         router: this.router,
+        i18n: this.i18nInstance,
         get: (name: string) => this.orchestrator!.get(name),
         managers: () => this.orchestrator!.getRegisteredNames(),
+        debug: debugProxy,
       }
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      ;(window as any).__qdadmZones = this.zoneRegistry
       console.debug(
-        '[qdadm] Debug mode: window.__qdadm exposed (orchestrator, signals, hooks, zones, deferred, router)'
+        '[qdadm] Debug mode: window.__qdadm.{kernel,orchestrator,signals,hooks,zones,router,i18n,debug.{describe,dump,call}}'
       )
     }
 
     app.provide('qdadmSignals', this.signals)
 
+    if (this.i18nInstance) {
+      app.provide(I18N_INJECTION_KEY, this.i18nInstance)
+      app.provide('qdadmI18n', this.i18nInstance)
+    }
+
     if (this.sseBridge) {
       app.provide('qdadmSSEBridge', this.sseBridge)
     }
@@ -163,6 +266,9 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
     app.provide('qdadmHooks', this.hookRegistry)
     app.provide('qdadmDeferred', this.deferred)
     app.provide('qdadmLayoutComponents', this.layoutComponents)
+    // Surface PrimeVue presence so host-rendered <QdadmRoot /> can
+    // decide whether to mount Toast / ToastListener.
+    app.provide('qdadmHasPrimeVue', !!primevue?.plugin)
 
     if (this.securityChecker) {
       app.provide('qdadmSecurityChecker', this.securityChecker)

package/src/kernel/KernelContext.entities.ts

@@ -0,0 +1,80 @@
+/**
+ * Patch KernelContext prototype with entity registration methods:
+ *   - entity(name, config)   — generic EntityManager registration
+ *   - userEntity(options)    — UsersManager registration with conventions
+ */
+
+import { managerFactory, type ManagerFactoryContext } from '../entity/factory.js'
+import type { EntityManager } from '../entity/EntityManager'
+import { UsersManager } from '../security/UsersManager'
+import type { UserEntityOptions } from './KernelContext.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyEntityMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  /**
+   * Register an entity manager.
+   *
+   * Uses managerFactory to resolve config into a manager instance.
+   * Registers with Orchestrator for CRUD operations.
+   */
+  proto.entity = function (
+    this: Self,
+    name: string,
+    config: string | Record<string, unknown> | EntityManager
+  ): Self {
+    const factoryContext = {
+      storageResolver: this._kernel.options.storageResolver,
+      managerResolver: this._kernel.options.managerResolver,
+      managerRegistry: this._kernel.options.managerRegistry || {},
+    } as ManagerFactoryContext
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const manager = managerFactory(config as any, name, factoryContext)
+
+    if (this._kernel.orchestrator) {
+      this._kernel.orchestrator.register(name, manager)
+    }
+
+    if (this._kernel.permissionRegistry) {
+      this._kernel.permissionRegistry.registerEntity(name, {
+        module: (this._module?.constructor as { name?: string })?.name || 'unknown',
+        // Register entity-own:* permissions if manager has isOwn configured
+        hasOwnership: !!(manager as unknown as { _isOwn?: unknown })._isOwn,
+      })
+    }
+
+    // Track entity → module for the 'module' i18n key strategy
+    if (this._kernel.i18nInstance) {
+      const moduleName = (this._module?.constructor as { name?: string })?.name
+      if (moduleName) {
+        this._kernel.i18nInstance.registerEntityModule(name, moduleName)
+      }
+    }
+
+    return this
+  }
+
+  /**
+   * Register a users entity with standard fields and role linking.
+   */
+  proto.userEntity = function (this: Self, options: UserEntityOptions): Self {
+    const manager = new UsersManager(options)
+
+    if (this._kernel.orchestrator) {
+      this._kernel.orchestrator.register('users', manager)
+    }
+
+    if (this._kernel.permissionRegistry) {
+      this._kernel.permissionRegistry.registerEntity('users', {
+        module: (this._module?.constructor as { name?: string })?.name || 'unknown',
+      })
+    }
+
+    return this
+  }
+}

package/src/kernel/KernelContext.events.ts

@@ -0,0 +1,57 @@
+/**
+ * Patch KernelContext prototype with event-bus / hook / deferred methods:
+ *   - on(signal, handler, options)    — signal subscription, auto-cleaned on
+ *                                        module disconnect
+ *   - hook(hookName, handler, options) — hook registration
+ *   - defer(name, factory)             — queue a deferred task
+ */
+
+import type { ListenerOptions } from '@quazardous/quarkernel'
+import type {
+  DeferredFactory,
+  HookHandler,
+  SignalHandler,
+} from './KernelContext.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyEventMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  proto.on = function (
+    this: Self,
+    signal: string,
+    handler: SignalHandler,
+    options: ListenerOptions = {}
+  ): Self {
+    if (this._kernel.signals) {
+      const cleanup = this._kernel.signals.on(signal, handler, options)
+      // Register cleanup with module for automatic unsubscribe on disconnect
+      if (this._module && typeof this._module._addSignalCleanup === 'function') {
+        this._module._addSignalCleanup(cleanup)
+      }
+    }
+    return this
+  }
+
+  proto.hook = function (
+    this: Self,
+    hookName: string,
+    handler: HookHandler,
+    options: Record<string, unknown> = {}
+  ): Self {
+    if (this._kernel.hookRegistry) {
+      this._kernel.hookRegistry.register(hookName, handler, options)
+    }
+    return this
+  }
+
+  proto.defer = function (this: Self, name: string, factory: DeferredFactory): Self {
+    if (this._kernel.deferred) {
+      this._kernel.deferred.queue(name, factory)
+    }
+    return this
+  }
+}