qdadm 1.13.0 → 1.19.2

package/src/modules/debug/RouterCollector.ts

@@ -11,7 +11,14 @@
  * collector.install(ctx)
  */
 
-import { Collector, type CollectorContext, type CollectorEntry, type CollectorOptions } from './Collector'
+import {
+  Collector,
+  type CollectorContext,
+  type CollectorEntry,
+  type CollectorManifest,
+  type CollectorOptions,
+  type CollectorSnapshot,
+} from './Collector'
 import { computeSemanticBreadcrumb } from '../../composables/useSemanticBreadcrumb'
 import type { Router, RouteLocationNormalized, RouteRecordNormalized } from 'vue-router'
 import type { ActiveStack, StackLevel } from '../../chain/ActiveStack'
@@ -111,6 +118,8 @@ export class RouterCollector extends Collector<NavigationEntry> {
   private _guardInstalled: boolean = false
   private _activeStack: ActiveStack | null = null
   private _stackHydrator: StackHydrator | null = null
+  private _removeHydratedListener: (() => void) | null = null
+  private _removeStackChangeListener: (() => void) | null = null
 
   constructor(options: RouterCollectorOptions = {}) {
     super(options)
@@ -135,6 +144,20 @@ export class RouterCollector extends Collector<NavigationEntry> {
     this._activeStack = routerCtx.activeStack ?? null
     this._stackHydrator = routerCtx.stackHydrator ?? null
     // Router guard will be installed lazily when router becomes available
+
+    // Re-render the panel when the active stack changes or finishes hydrating —
+    // otherwise level.label stays on its loading placeholder until the next
+    // navigation triggers reactivity. afterEach (the navigation guard) only
+    // fires when the route changes, not when the async hydrator resolves.
+    const signals = ctx.signals
+    if (signals) {
+      this._removeStackChangeListener = signals.on('stack:change', () => {
+        this.notifyChange()
+      })
+      this._removeHydratedListener = signals.on('stack:hydrated', () => {
+        this.notifyChange()
+      })
+    }
   }
 
   /**
@@ -213,6 +236,14 @@ export class RouterCollector extends Collector<NavigationEntry> {
       this._removeGuard()
       this._removeGuard = null
     }
+    if (this._removeStackChangeListener) {
+      this._removeStackChangeListener()
+      this._removeStackChangeListener = null
+    }
+    if (this._removeHydratedListener) {
+      this._removeHydratedListener()
+      this._removeHydratedListener = null
+    }
     this._guardInstalled = false
     this._ctx = null
     this._history = []
@@ -346,4 +377,73 @@ export class RouterCollector extends Collector<NavigationEntry> {
     if (!this._router) return
     await this._router.push(path)
   }
+
+  override describe(): CollectorManifest {
+    return {
+      name: this.name,
+      records: true,
+      summary:
+        'Captures navigations (afterEach) and exposes the current route, registered routes and the live ActiveStack.',
+      entryShape: {
+        id: 'number',
+        to: 'SerializedRoute',
+        from: 'SerializedRoute?',
+        seen: 'boolean',
+        timestamp: 'number',
+      },
+      stateShape: {
+        currentRoute: 'SerializedRoute?',
+        routes: 'RouteListEntry[]',
+        breadcrumb: 'unknown[]',
+        activeStack: 'ActiveStackInfo?',
+      },
+      actions: [
+        ...this._builtinActionManifests(),
+        {
+          name: 'navigate',
+          summary: 'Push a path onto the router (router.push).',
+          args: { path: 'string' },
+          mutates: true,
+        },
+        {
+          name: 'getCurrentRoute',
+          summary: 'Return the serialized current route.',
+        },
+        {
+          name: 'getRoutes',
+          summary: 'List every registered route.',
+        },
+        {
+          name: 'getBreadcrumb',
+          summary: 'Return the semantic breadcrumb for the current route.',
+        },
+      ],
+    }
+  }
+
+  override snapshot(): CollectorSnapshot {
+    return {
+      name: this.name,
+      entries: this._history.map((e) => ({ ...e })),
+      count: this._history.length,
+      unseen: this.getBadge(),
+      state: {
+        currentRoute: this.getCurrentRoute(),
+        routes: this.getRoutes(),
+        breadcrumb: this.getBreadcrumb(),
+        activeStack: this.getActiveStack(),
+      },
+    }
+  }
+
+  override async call(actionName: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    if (actionName === 'navigate') {
+      await this.navigate(String(args.path ?? ''))
+      return { ok: true }
+    }
+    if (actionName === 'getCurrentRoute') return this.getCurrentRoute()
+    if (actionName === 'getRoutes') return this.getRoutes()
+    if (actionName === 'getBreadcrumb') return this.getBreadcrumb()
+    return super.call(actionName, args)
+  }
 }

package/src/modules/debug/SignalCollector.ts

@@ -1,152 +1,4 @@
 /**
- * SignalCollector - Debug collector for SignalBus events
- *
- * Extends the base Collector to capture all signals emitted through the SignalBus.
- * Uses wildcard subscription to capture all domain:action events.
- *
- * @example
- * const collector = new SignalCollector({ maxEntries: 50 })
- * collector.install(ctx) // ctx.signals is the SignalBus
- *
- * // Later, retrieve captured signals
- * collector.getEntries() // [{ name, data, source, timestamp }, ...]
+ * SignalCollector — qdadm re-export from @quazardous/qddebug.
  */
-
-import { Collector, type CollectorContext, type CollectorEntry } from './Collector'
-
-/**
- * Signal entry type
- */
-export interface SignalEntry extends CollectorEntry {
-  name: string
-  data: unknown
-  source: string | null
-}
-
-/**
- * Collector for SignalBus events
- *
- * Records all signals with their name, data, and source for debugging.
- * Uses the `**` wildcard pattern to capture all signals including
- * multi-segment names (e.g., entity:data-invalidate, auth:impersonate:start).
- */
-export class SignalCollector extends Collector<SignalEntry> {
-  /**
-   * Collector name for identification
-   */
-  static override collectorName = 'signals'
-
-  /**
-   * Signals to skip recording (internal kernel signals with non-serializable data)
-   * @private
-   */
-  private static _skipSignals = new Set(['kernel:ready', 'kernel:shutdown'])
-
-  private _unsubscribe: (() => void) | null = null
-
-  /**
-   * Internal install - subscribe to all signals
-   * @protected
-   */
-  protected override _doInstall(ctx: CollectorContext): void {
-    if (!ctx?.signals) {
-      console.warn('[SignalCollector] No signals bus found in context')
-      return
-    }
-
-    // Subscribe to all signals using wildcard pattern
-    // QuarKernel supports wildcards with the configured delimiter (:)
-    // '**' matches all signals including multi-segment (entity:data-invalidate)
-    this._unsubscribe = ctx.signals.on('**', (event) => {
-      // Skip internal signals with non-serializable data (kernel, orchestrator)
-      if (SignalCollector._skipSignals.has(event.name)) {
-        return
-      }
-
-      // Sanitize data to avoid cyclic references
-      const data = this._sanitizeData(event.data)
-
-      this.record({
-        name: event.name,
-        data,
-        source: (data as Record<string, unknown>)?.source as string ?? null
-      })
-    })
-  }
-
-  /**
-   * Sanitize event data to remove non-serializable objects
-   *
-   * Handles cases where data contains references to Kernel, Orchestrator,
-   * or other complex objects that would cause cyclic reference errors.
-   *
-   * @param data - Raw event data
-   * @returns Sanitized data safe for recording
-   * @private
-   */
-  private _sanitizeData(data: unknown): unknown {
-    if (data === null || data === undefined) return data
-    if (typeof data !== 'object') return data
-
-    // Try to create a simple clone, fallback to description if cyclic
-    try {
-      const obj = data as Record<string, unknown>
-      // Quick check for obviously problematic properties
-      if (obj.kernel || obj.orchestrator || obj._kernel) {
-        // Extract only safe properties
-        const safe: Record<string, unknown> = {}
-        for (const [key, value] of Object.entries(obj)) {
-          if (key !== 'kernel' && key !== 'orchestrator' && key !== '_kernel') {
-            if (typeof value !== 'object' || value === null) {
-              safe[key] = value
-            } else if (Array.isArray(value)) {
-              safe[key] = `[Array(${value.length})]`
-            } else {
-              safe[key] = '[Object]'
-            }
-          }
-        }
-        return safe
-      }
-
-      // For other objects, try JSON roundtrip to detect cycles
-      JSON.stringify(data)
-      return data
-    } catch {
-      // If serialization fails, return a safe representation
-      return { _type: 'unserializable', keys: Object.keys(data as object) }
-    }
-  }
-
-  /**
-   * Internal uninstall - cleanup subscription
-   * @protected
-   */
-  protected override _doUninstall(): void {
-    if (this._unsubscribe) {
-      this._unsubscribe()
-      this._unsubscribe = null
-    }
-  }
-
-  /**
-   * Get entries filtered by signal name pattern
-   *
-   * @param pattern - Pattern to match signal names
-   * @returns Filtered entries
-   */
-  getByPattern(pattern: string | RegExp): SignalEntry[] {
-    const regex = pattern instanceof RegExp ? pattern : new RegExp(pattern)
-    return this.entries.filter((entry) => regex.test(entry.name))
-  }
-
-  /**
-   * Get entries for a specific signal domain
-   *
-   * @param domain - Domain prefix (e.g., 'entity', 'auth', 'books')
-   * @returns Entries matching the domain
-   */
-  getByDomain(domain: string): SignalEntry[] {
-    return this.entries.filter((entry) => entry.name.startsWith(`${domain}:`))
-  }
-}
+export { SignalCollector, type SignalEntry } from '@quazardous/qddebug'

package/src/modules/debug/ToastCollector.ts

@@ -1,93 +1,4 @@
 /**
- * ToastCollector - Captures toast notifications via signal bus
- *
- * This collector listens to toast signals emitted on the signal bus
- * and records them for display in the debug panel.
- *
- * Toast signals should follow the pattern:
- * - signals.emit('toast:success', { summary: '...', detail: '...' })
- * - signals.emit('toast:error', { summary: '...', detail: '...' })
- * - signals.emit('toast:info', { summary: '...', detail: '...' })
- * - signals.emit('toast:warn', { summary: '...', detail: '...' })
- *
- * Use with ToastBridge module which handles displaying toasts via PrimeVue.
- *
- * @example
- * const collector = new ToastCollector()
- * collector.install(ctx)
- * // Toasts emitted via signals are now automatically recorded
+ * ToastCollector — qdadm re-export from @quazardous/qddebug.
  */
-
-import { Collector, type CollectorContext, type CollectorEntry } from './Collector'
-
-/**
- * Toast entry type
- */
-export interface ToastEntry extends CollectorEntry {
-  severity: string
-  summary?: string
-  detail?: string
-  life?: number
-  emitter: string
-}
-
-/**
- * Collector for toast notifications
- */
-export class ToastCollector extends Collector<ToastEntry> {
-  /**
-   * Collector name identifier
-   */
-  static override collectorName = 'toasts'
-
-  private _unsubscribe: (() => void) | null = null
-
-  /**
-   * Internal install - subscribe to toast signals
-   * @protected
-   */
-  protected override _doInstall(ctx: CollectorContext): void {
-    // Listen for toast signals on the signal bus
-    if (ctx?.signals) {
-      this._unsubscribe = ctx.signals.on('toast:*', (event) => {
-        const data = event.data as { summary?: string; detail?: string; life?: number; emitter?: string } | undefined
-        this.record({
-          severity: event.name.split(':')[1] ?? 'info', // toast:success -> success
-          summary: data?.summary,
-          detail: data?.detail,
-          life: data?.life,
-          emitter: data?.emitter ?? 'unknown'
-        })
-      })
-    } else {
-      console.warn('[ToastCollector] No signals bus in context - toast recording disabled')
-    }
-  }
-
-  /**
-   * Internal uninstall - cleanup
-   * @protected
-   */
-  protected override _doUninstall(): void {
-    if (this._unsubscribe) {
-      this._unsubscribe()
-      this._unsubscribe = null
-    }
-  }
-
-  /**
-   * Get entries by severity
-   * @param severity - Severity level (success, info, warn, error)
-   * @returns Filtered entries
-   */
-  getBySeverity(severity: string): ToastEntry[] {
-    return this.entries.filter((entry) => entry.severity === severity)
-  }
-
-  /**
-   * Get error toasts count for badge
-   */
-  getErrorCount(): number {
-    return this.entries.filter((e) => e.severity === 'error').length
-  }
-}
+export { ToastCollector, type ToastEntry } from '@quazardous/qddebug'

package/src/modules/debug/ZonesCollector.ts

@@ -15,7 +15,14 @@
  * collector.getZoneInfo() // { zones: [...], totalBlocks: n }
  */
 
-import { Collector, type CollectorContext, type CollectorEntry, type CollectorOptions } from './Collector'
+import {
+  Collector,
+  type CollectorContext,
+  type CollectorEntry,
+  type CollectorManifest,
+  type CollectorOptions,
+  type CollectorSnapshot,
+} from './Collector'
 import type { ZoneRegistry } from '../../zones/ZoneRegistry'
 import type { Router } from 'vue-router'
 
@@ -352,4 +359,89 @@ export class ZonesCollector extends Collector<ZoneEntry> {
       return true
     }
   }
+
+  override describe(): CollectorManifest {
+    return {
+      name: this.name,
+      records: false,
+      summary:
+        'Lists every zone defined in the running app and the blocks/wrappers registered in each. Reflects current page (filterable).',
+      entryShape: {
+        name: 'string',
+        isOnPage: 'boolean',
+        hasDefault: 'boolean',
+        defaultName: 'string?',
+        blocksCount: 'number',
+        blocks: 'ZoneBlock[]',
+      },
+      stateShape: {
+        showCurrentPageOnly: 'boolean',
+        showInternalZones: 'boolean',
+        highlightedZone: 'string?',
+      },
+      actions: [
+        ...this._builtinActionManifests(),
+        {
+          name: 'highlight',
+          summary: 'Draw an overlay on the page around a zone (browser-only).',
+          args: { name: 'string' },
+          mutates: true,
+        },
+        {
+          name: 'clearHighlights',
+          summary: 'Remove every zone overlay.',
+          mutates: true,
+        },
+        {
+          name: 'setShowCurrentPageOnly',
+          summary: 'Filter zones to those rendered on the current page.',
+          args: { value: 'boolean' },
+          mutates: true,
+        },
+        {
+          name: 'setShowInternalZones',
+          summary: 'Show internal zones (prefixed with _).',
+          args: { value: 'boolean' },
+          mutates: true,
+        },
+      ],
+    }
+  }
+
+  override snapshot(): CollectorSnapshot {
+    const entries = this.getEntries(true)
+    return {
+      name: this.name,
+      entries,
+      count: entries.length,
+      unseen: 0,
+      state: {
+        showCurrentPageOnly: this._showCurrentPageOnly,
+        showInternalZones: this._showInternalZones,
+        highlightedZone: this._highlightedZone,
+      },
+    }
+  }
+
+  override async call(actionName: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    if (actionName === 'highlight') {
+      this.highlightZone(String(args.name ?? ''))
+      return { ok: true }
+    }
+    if (actionName === 'clearHighlights') {
+      this.clearHighlights()
+      return { ok: true }
+    }
+    if (actionName === 'setShowCurrentPageOnly') {
+      this._showCurrentPageOnly = Boolean(args.value)
+      this.notifyChange()
+      return { ok: true, value: this._showCurrentPageOnly }
+    }
+    if (actionName === 'setShowInternalZones') {
+      this._showInternalZones = Boolean(args.value)
+      this.notifyChange()
+      return { ok: true, value: this._showInternalZones }
+    }
+    return super.call(actionName, args)
+  }
 }