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

package/src/components/UIResourceRenderer.tsx

@@ -4,11 +4,28 @@
  */
 
 import DOMPurify from 'dompurify'
-import { Component, createSignal, Show, For, createMemo, createEffect } from 'solid-js'
+import { Component, createSignal, Show, For, createMemo, createEffect, onMount } from 'solid-js'
 import { isServer } from 'solid-js/web'
 import type { UIComponent, UILayout, RendererError, TableVirtualizeOptions } from '../types'
 import { validateComponent, DEFAULT_RESOURCE_LIMITS, getIframeSandbox } from '../services/validation'
 import { GenerativeUIErrorBoundary } from './GenerativeUIErrorBoundary'
+import { markRenderStart, markRenderEnd } from '../utils/perf'
+
+/**
+ * How `<UIResourceRenderer>` reacts when `validateComponent()` rejects a
+ * component (v5.4.0).
+ *
+ * - `'block'`  : full-slot red error card (default — backward compatible)
+ * - `'inline-warn'` : compact yellow chip in the slot, tooltip carries the
+ *                    error message — keeps the surrounding layout clean
+ *                    (e.g. inside a chat message)
+ * - `'silent'` : render nothing in the slot; `onError` still fires so the
+ *                consumer can log/alert
+ *
+ * Runtime errors caught by `<GenerativeUIErrorBoundary>` are NOT affected by
+ * this prop — they always show the boundary's fallback UI.
+ */
+export type ValidationErrorMode = 'block' | 'inline-warn' | 'silent'
 import { GridRenderer } from './GridRenderer'
 import { FooterRenderer } from './FooterRenderer'
 import { CarouselRenderer } from './CarouselRenderer'
@@ -93,6 +110,15 @@ export interface UIResourceRendererProps {
    * Custom CSS class
    */
   class?: string
+
+  /**
+   * How to react when a component fails `validateComponent()` (v5.4.0).
+   * Defaults to `'block'` (replaces the slot with a red error card —
+   * the pre-v5.4.0 behavior).
+   *
+   * @see ValidationErrorMode
+   */
+  errorMode?: ValidationErrorMode
 }
 
 /**
@@ -1102,7 +1128,13 @@ function LinkRenderer(props: { component: UIComponent }) {
 function ComponentRenderer(props: {
   component: UIComponent
   onError?: (error: RendererError) => void
+  errorMode?: ValidationErrorMode
 }) {
+  // Performance marks — visible in Chrome DevTools "Performance" panel under
+  // user timings. Always-on, SSR-safe (see utils/perf.ts).
+  markRenderStart(props.component.id)
+  onMount(() => markRenderEnd(props.component.id))
+
   // Validate component before rendering
   const validation = validateComponent(props.component)
   if (!validation.valid) {
@@ -1113,11 +1145,47 @@ function ComponentRenderer(props: {
       details: validation.errors,
     })
 
+    const mode: ValidationErrorMode = props.errorMode ?? 'block'
+    const firstError = validation.errors?.[0]?.message || 'Unknown validation error'
+
+    if (mode === 'silent') {
+      return null
+    }
+
+    if (mode === 'inline-warn') {
+      return (
+        <div
+          class="inline-flex items-center gap-1.5 px-2 py-1 rounded-md bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 text-xs text-yellow-800 dark:text-yellow-200"
+          role="alert"
+          aria-label="Component validation warning"
+          title={firstError}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            class="w-3.5 h-3.5"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z" />
+            <line x1="12" y1="9" x2="12" y2="13" />
+            <line x1="12" y1="17" x2="12.01" y2="17" />
+          </svg>
+          <span>Invalid {props.component.type}</span>
+        </div>
+      )
+    }
+
+    // mode === 'block' (default, pre-v5.4.0 behavior)
     return (
       <div class="w-full h-full bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4">
         <p class="text-sm font-medium text-red-900 dark:text-red-100">Validation Error</p>
         <p class="text-xs text-red-700 dark:text-red-300 mt-1">
-          {validation.errors?.[0]?.message || 'Unknown validation error'}
+          {firstError}
         </p>
       </div>
     )
@@ -1450,7 +1518,7 @@ export const UIResourceRenderer: Component<UIResourceRendererProps> = (props) =>
 
   // Wrapper function for RenderContext (breaks circular dependency)
   const renderComponent = (component: UIComponent, onError?: (error: RendererError) => void) => (
-    <ComponentRenderer component={component} onError={onError} />
+    <ComponentRenderer component={component} onError={onError} errorMode={props.errorMode} />
   )
 
   return (
@@ -1460,7 +1528,7 @@ export const UIResourceRenderer: Component<UIResourceRendererProps> = (props) =>
           <For each={layoutData.components}>
             {(component) => (
               <div style={getGridStyleString(component)}>
-                <ComponentRenderer component={component} onError={props.onError} />
+                <ComponentRenderer component={component} onError={props.onError} errorMode={props.errorMode} />
               </div>
             )}
           </For>

package/src/index.ts

@@ -89,6 +89,13 @@ export type {
   GenerativeUIErrorBoundaryProps,
 } from './components'
 
+// Validation error mode (v5.4.0)
+export type { ValidationErrorMode } from './components/UIResourceRenderer'
+
+// Runtime debug mode + perf marks (v5.4.0)
+export { setDebugMode, isDebugEnabled } from './utils/logger'
+export { markRenderStart, markRenderEnd, PERF_PREFIX } from './utils/perf'
+
 export type { DraggableGridItemProps } from './components/DraggableGridItem'
 export type { ResizeHandleProps as ResizeHandleComponentProps } from './components/ResizeHandle'
 export type { EditableUIResourceRendererProps } from './components/EditableUIResourceRenderer'

package/src/utils/logger.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for logger debug-mode controls — v5.4.0 (B.2)
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { createLogger, setDebugMode, isDebugEnabled } from './logger'
+
+describe('setDebugMode + isDebugEnabled (v5.4.0 — B.2)', () => {
+  let originalNodeEnv: string | undefined
+  let originalDebugEnv: string | undefined
+
+  beforeEach(() => {
+    originalNodeEnv = process.env.NODE_ENV
+    originalDebugEnv = process.env.MCP_UI_DEBUG
+    setDebugMode(null) // reset override
+    delete (globalThis as any).__MCP_UI_DEBUG__
+  })
+
+  afterEach(() => {
+    process.env.NODE_ENV = originalNodeEnv
+    process.env.MCP_UI_DEBUG = originalDebugEnv
+    setDebugMode(null)
+    delete (globalThis as any).__MCP_UI_DEBUG__
+  })
+
+  it('default (NODE_ENV=test, no override): isDebugEnabled returns true', () => {
+    // Vitest sets NODE_ENV='test' by default — that's !== 'production' so dev mode is on
+    expect(isDebugEnabled()).toBe(true)
+  })
+
+  it('NODE_ENV=production silences debug by default', () => {
+    process.env.NODE_ENV = 'production'
+    delete process.env.MCP_UI_DEBUG
+    expect(isDebugEnabled()).toBe(false)
+  })
+
+  it('MCP_UI_DEBUG=true re-enables debug in production', () => {
+    process.env.NODE_ENV = 'production'
+    process.env.MCP_UI_DEBUG = 'true'
+    expect(isDebugEnabled()).toBe(true)
+  })
+
+  it('globalThis.__MCP_UI_DEBUG__=true re-enables debug in production', () => {
+    process.env.NODE_ENV = 'production'
+    delete process.env.MCP_UI_DEBUG
+    ;(globalThis as any).__MCP_UI_DEBUG__ = true
+    expect(isDebugEnabled()).toBe(true)
+  })
+
+  it('setDebugMode(true) overrides NODE_ENV=production', () => {
+    process.env.NODE_ENV = 'production'
+    setDebugMode(true)
+    expect(isDebugEnabled()).toBe(true)
+  })
+
+  it('setDebugMode(false) overrides NODE_ENV=development', () => {
+    process.env.NODE_ENV = 'development'
+    setDebugMode(false)
+    expect(isDebugEnabled()).toBe(false)
+  })
+
+  it('setDebugMode(null) restores env-based detection', () => {
+    process.env.NODE_ENV = 'production'
+    setDebugMode(true)
+    expect(isDebugEnabled()).toBe(true)
+    setDebugMode(null)
+    expect(isDebugEnabled()).toBe(false)
+  })
+})
+
+describe('createLogger respects debug mode (v5.4.0)', () => {
+  let originalNodeEnv: string | undefined
+
+  beforeEach(() => {
+    originalNodeEnv = process.env.NODE_ENV
+    setDebugMode(null)
+  })
+
+  afterEach(() => {
+    process.env.NODE_ENV = originalNodeEnv
+    setDebugMode(null)
+    vi.restoreAllMocks()
+  })
+
+  it('info/warn/debug are silent when debug is off', () => {
+    process.env.NODE_ENV = 'production'
+    setDebugMode(false)
+
+    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {})
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+
+    const logger = createLogger('test')
+    logger.info('a')
+    logger.warn('b')
+    logger.debug('c')
+
+    expect(infoSpy).not.toHaveBeenCalled()
+    expect(warnSpy).not.toHaveBeenCalled()
+    expect(debugSpy).not.toHaveBeenCalled()
+  })
+
+  it('error always logs even when debug is off', () => {
+    process.env.NODE_ENV = 'production'
+    setDebugMode(false)
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const logger = createLogger('test')
+    logger.error('boom', { id: 1 })
+
+    expect(errorSpy).toHaveBeenCalledOnce()
+    expect(errorSpy.mock.calls[0][0]).toContain('[@seed-ship/mcp-ui-solid:test]')
+    expect(errorSpy.mock.calls[0][0]).toContain('boom')
+    expect(errorSpy.mock.calls[0][0]).toContain('"id":1')
+  })
+
+  it('toggling setDebugMode at runtime affects subsequent calls', () => {
+    process.env.NODE_ENV = 'production'
+    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {})
+
+    const logger = createLogger('toggle')
+    logger.info('off')
+    expect(infoSpy).not.toHaveBeenCalled()
+
+    setDebugMode(true)
+    logger.info('on')
+    expect(infoSpy).toHaveBeenCalledOnce()
+  })
+})

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.
+  }
+}