@seed-ship/mcp-ui-solid 5.3.1 → 5.5.0

package/src/utils/logger.ts

@@ -1,12 +1,65 @@
 /**
  * Simple internal logger utility
  *
- * Provides basic logging functionality for the package.
- * Consumers can disable logging by setting NODE_ENV=production
- * or by implementing their own logging solution.
+ * Logging is enabled when EITHER:
+ *   1. `process.env.NODE_ENV !== 'production'` (dev build), OR
+ *   2. `process.env.MCP_UI_DEBUG === 'true'` (server-side opt-in for prod), OR
+ *   3. `globalThis.__MCP_UI_DEBUG__ === true` (browser-side runtime toggle), OR
+ *   4. `setDebugMode(true)` has been called from app code.
+ *
+ * `error` always logs regardless of mode.
+ *
+ * @see setDebugMode, isDebugEnabled — runtime controls (v5.4.0)
+ */
+
+declare global {
+  // Browser-side runtime flag — settable from devtools console:
+  //   `globalThis.__MCP_UI_DEBUG__ = true`
+  // eslint-disable-next-line no-var
+  var __MCP_UI_DEBUG__: boolean | undefined
+}
+
+let debugOverride: boolean | null = null
+
+function readEnvFlag(): boolean {
+  if (typeof process !== 'undefined' && process.env) {
+    if (process.env.MCP_UI_DEBUG === 'true') return true
+    if (process.env.NODE_ENV !== 'production') return true
+  }
+  if (typeof globalThis !== 'undefined' && globalThis.__MCP_UI_DEBUG__ === true) {
+    return true
+  }
+  return false
+}
+
+function isDebugActive(): boolean {
+  if (debugOverride !== null) return debugOverride
+  return readEnvFlag()
+}
+
+/**
+ * Programmatically enable/disable verbose logging at runtime.
+ *
+ * Pass `null` to clear the override and fall back to env-based detection.
+ *
+ * @example
+ * ```ts
+ * import { setDebugMode } from '@seed-ship/mcp-ui-solid'
+ * setDebugMode(true)   // turn on verbose logs
+ * setDebugMode(false)  // turn off (overrides NODE_ENV=development)
+ * setDebugMode(null)   // restore env-based behavior
+ * ```
  */
+export function setDebugMode(enabled: boolean | null): void {
+  debugOverride = enabled
+}
 
-const isDev = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'
+/**
+ * Whether verbose logging is currently active (env + override combined).
+ */
+export function isDebugEnabled(): boolean {
+  return isDebugActive()
+}
 
 export interface Logger {
   info(message: string, context?: Record<string, unknown>): void
@@ -39,13 +92,13 @@ function formatLogMessage(
 export function createLogger(feature: string): Logger {
   return {
     info(message: string, context?: Record<string, unknown>) {
-      if (isDev) {
+      if (isDebugActive()) {
         console.info(formatLogMessage(feature, message, context))
       }
     },
 
     warn(message: string, context?: Record<string, unknown>) {
-      if (isDev) {
+      if (isDebugActive()) {
         console.warn(formatLogMessage(feature, message, context))
       }
     },
@@ -56,7 +109,7 @@ export function createLogger(feature: string): Logger {
     },
 
     debug(message: string, context?: Record<string, unknown>) {
-      if (isDev) {
+      if (isDebugActive()) {
         console.debug(formatLogMessage(feature, message, context))
       }
     },

package/src/utils/perf.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Tests for performance markers — v5.4.0 (B.4)
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { markRenderStart, markRenderEnd, PERF_PREFIX } from './perf'
+
+describe('performance marks (v5.4.0 — B.4)', () => {
+  beforeEach(() => {
+    if (typeof performance !== 'undefined' && typeof performance.clearMarks === 'function') {
+      performance.clearMarks()
+    }
+    if (typeof performance !== 'undefined' && typeof performance.clearMeasures === 'function') {
+      performance.clearMeasures()
+    }
+  })
+
+  it('PERF_PREFIX is the documented namespace', () => {
+    expect(PERF_PREFIX).toBe('mcp-ui:component:')
+  })
+
+  it('markRenderStart writes a `:render-start` mark with the component id', () => {
+    markRenderStart('cmp-A')
+    const entries = performance.getEntriesByName('mcp-ui:component:cmp-A:render-start')
+    expect(entries.length).toBe(1)
+    expect(entries[0].entryType).toBe('mark')
+  })
+
+  it('markRenderEnd writes both `:render-end` mark and a `:render` measure', () => {
+    markRenderStart('cmp-B')
+    markRenderEnd('cmp-B')
+
+    const endEntries = performance.getEntriesByName('mcp-ui:component:cmp-B:render-end')
+    expect(endEntries.length).toBe(1)
+
+    const measureEntries = performance.getEntriesByName('mcp-ui:component:cmp-B:render')
+    expect(measureEntries.length).toBe(1)
+    expect(measureEntries[0].entryType).toBe('measure')
+    expect(measureEntries[0].duration).toBeGreaterThanOrEqual(0)
+  })
+
+  it('markRenderEnd without a preceding markRenderStart still writes the end mark (no throw)', () => {
+    expect(() => markRenderEnd('cmp-orphan')).not.toThrow()
+    const endEntries = performance.getEntriesByName('mcp-ui:component:cmp-orphan:render-end')
+    expect(endEntries.length).toBe(1)
+    // measure may or may not be created, but it must NOT crash the render path
+  })
+
+  it('mark functions are no-ops when performance is undefined (SSR-safe)', () => {
+    const originalPerf = (globalThis as any).performance
+    ;(globalThis as any).performance = undefined
+    try {
+      expect(() => markRenderStart('ssr')).not.toThrow()
+      expect(() => markRenderEnd('ssr')).not.toThrow()
+    } finally {
+      ;(globalThis as any).performance = originalPerf
+    }
+  })
+})

package/src/utils/perf.ts

@@ -0,0 +1,50 @@
+/**
+ * Performance markers for component renders (v5.4.0)
+ *
+ * Emits `performance.mark()` entries that show up automatically in Chrome
+ * DevTools "Performance" panel under user timings. Consumers can also
+ * query them via `performance.getEntriesByName(...)` for custom tracing.
+ *
+ * Naming convention :
+ *   `mcp-ui:component:<id>:render-start`
+ *   `mcp-ui:component:<id>:render-end`
+ *   `mcp-ui:component:<id>:render`         (a `measure` between the two)
+ *
+ * Always-on: marks are cheap (sub-microsecond) and only matter when a
+ * profiler is recording. SSR-safe (`performance` is guarded).
+ */
+
+export const PERF_PREFIX = 'mcp-ui:component:'
+
+function hasPerf(): boolean {
+  return typeof performance !== 'undefined' && typeof performance.mark === 'function'
+}
+
+export function markRenderStart(componentId: string): void {
+  if (!hasPerf()) return
+  try {
+    performance.mark(`${PERF_PREFIX}${componentId}:render-start`)
+  } catch {
+    // Ignore — performance.mark can throw on malformed names; not worth crashing the render.
+  }
+}
+
+export function markRenderEnd(componentId: string): void {
+  if (!hasPerf()) return
+  try {
+    performance.mark(`${PERF_PREFIX}${componentId}:render-end`)
+    if (typeof performance.measure === 'function') {
+      try {
+        performance.measure(
+          `${PERF_PREFIX}${componentId}:render`,
+          `${PERF_PREFIX}${componentId}:render-start`,
+          `${PERF_PREFIX}${componentId}:render-end`
+        )
+      } catch {
+        // Start mark may be missing if the render path was short-circuited — ignore.
+      }
+    }
+  } catch {
+    // Ignore.
+  }
+}