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

package/src/services/validation.spec-migration.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Tests focused on the v5.5.0 spec-driven validation refactor (B.1 PR2).
+ *
+ * Complement to `validation.test.ts` (which is preserved untouched and
+ * verifies legacy behavior + codes are unchanged) — this file covers what's
+ * NEW in v5.5.0:
+ *   1. ZodIssue → ValidationError mapper preserves legacy `code` per type
+ *   2. Path translation: ZodIssue path → `params.<joined>`
+ *   3. Artifact validation drift FIX (url + filename + mimeType, not `content`)
+ *   4. Iframe + video: spec parse first, then chained domain whitelist
+ *   5. Imperative passthrough types (chart, table, form, map, modal) still
+ *      use the legacy validators with their rich codes
+ */
+
+import { describe, it, expect } from 'vitest'
+import { validateComponent } from './validation'
+import type { UIComponent, ComponentType } from '../types'
+
+function makeComponent(type: ComponentType, params: Record<string, unknown> = {}): UIComponent {
+  return {
+    id: `test-${type}`,
+    type,
+    position: { colStart: 1, colSpan: 12 },
+    params: params as any,
+  }
+}
+
+describe('v5.5.0 — ZodIssue → ValidationError mapper', () => {
+  it('emits the legacy code per ComponentType when shape parsing fails', () => {
+    const cases: Array<{ type: ComponentType; legacyCode: string }> = [
+      { type: 'metric', legacyCode: 'INVALID_METRIC' },
+      { type: 'text', legacyCode: 'INVALID_TEXT' },
+      { type: 'iframe', legacyCode: 'INVALID_IFRAME' },
+      { type: 'image', legacyCode: 'INVALID_IMAGE' },
+      { type: 'link', legacyCode: 'INVALID_LINK' },
+      { type: 'action', legacyCode: 'INVALID_ACTION' },
+      { type: 'video', legacyCode: 'INVALID_VIDEO' },
+      { type: 'carousel', legacyCode: 'EMPTY_CAROUSEL' },
+      { type: 'image-gallery', legacyCode: 'EMPTY_GALLERY' },
+      { type: 'action-group', legacyCode: 'EMPTY_ACTION_GROUP' },
+      { type: 'code', legacyCode: 'INVALID_CODE' },
+      { type: 'artifact', legacyCode: 'INVALID_ARTIFACT' },
+    ]
+
+    for (const { type, legacyCode } of cases) {
+      const result = validateComponent(makeComponent(type, {}))
+      expect(result.valid, `${type} should fail validation with empty params`).toBe(false)
+      const codes = result.errors?.map((e) => e.code) ?? []
+      expect(codes, `${type} errors should include ${legacyCode}`).toContain(legacyCode)
+    }
+  })
+
+  it('maps ZodIssue.path to `params.<joined>` shape', () => {
+    // metric is missing both `title` and `value` → 2 errors with paths
+    // `params.title` and `params.value`
+    const result = validateComponent(makeComponent('metric', {}))
+    expect(result.valid).toBe(false)
+
+    const paths = (result.errors ?? []).map((e) => e.path)
+    expect(paths).toContain('params.title')
+    expect(paths).toContain('params.value')
+  })
+
+  it('emits a top-level `params` path when the failure is at the root (e.g. params is wrong type)', () => {
+    // value=null fails the union(string, number); path is `params.value`
+    const result = validateComponent(makeComponent('metric', { title: 'X', value: null }))
+    expect(result.valid).toBe(false)
+    const paths = (result.errors ?? []).map((e) => e.path)
+    expect(paths.some((p) => p.startsWith('params.'))).toBe(true)
+  })
+})
+
+describe('v5.5.0 — Artifact validation drift fix', () => {
+  // Pre-v5.5.0 BUG: validation.ts checked `params.content` but ArtifactRenderer
+  // expects `url + filename + mimeType`. Any valid artifact (per renderer)
+  // would fail validation; any "valid" artifact (per old check) couldn't
+  // render. Fixed as a side-effect of the spec migration.
+
+  it('accepts a valid artifact with url + filename + mimeType', () => {
+    const result = validateComponent(
+      makeComponent('artifact', {
+        url: 'https://artifacts.example.com/file.csv',
+        filename: 'export.csv',
+        mimeType: 'text/csv',
+      })
+    )
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects an artifact with only `content` (the pre-v5.5.0 expected shape — was a bug)', () => {
+    const result = validateComponent(makeComponent('artifact', { content: 'data' }))
+    expect(result.valid).toBe(false)
+    expect(result.errors?.some((e) => e.code === 'INVALID_ARTIFACT')).toBe(true)
+  })
+
+  it('rejects an artifact missing filename', () => {
+    const result = validateComponent(
+      makeComponent('artifact', { url: 'https://x', mimeType: 'application/pdf' })
+    )
+    expect(result.valid).toBe(false)
+    const filenameError = result.errors?.find((e) => e.path === 'params.filename')
+    expect(filenameError).toBeDefined()
+  })
+})
+
+describe('v5.5.0 — Iframe + video chained domain whitelist', () => {
+  it('iframe with whitelisted domain (quickchart.io) passes validation', () => {
+    const result = validateComponent(
+      makeComponent('iframe', { url: 'https://quickchart.io/chart?c={}' })
+    )
+    expect(result.valid).toBe(true)
+  })
+
+  it('iframe domain check IS chained after spec parse (URL with malformed bracket throws → INVALID_URL)', () => {
+    // Spec parse accepts any non-empty string; we feed it a URL the WHATWG
+    // parser refuses (unbalanced bracket), which proves the chained
+    // validateIframeDomain ran and surfaced its INVALID_URL code.
+    const result = validateComponent(
+      makeComponent('iframe', { url: 'http://[bad' })
+    )
+    expect(result.valid).toBe(false)
+    const codes = result.errors?.map((e) => e.code) ?? []
+    expect(codes).toContain('INVALID_URL')
+  })
+
+  it('iframe with missing url emits INVALID_IFRAME and SKIPS the domain check (no cascading error)', () => {
+    const result = validateComponent(makeComponent('iframe', {}))
+    expect(result.valid).toBe(false)
+    const codes = result.errors?.map((e) => e.code) ?? []
+    expect(codes).toContain('INVALID_IFRAME')
+    // No domain whitelist error since url was absent — avoid noise
+    expect(codes.every((c) => c === 'INVALID_IFRAME')).toBe(true)
+  })
+
+  it('video with whitelisted domain (youtube.com) passes domain check (only spec strict-url applies)', () => {
+    // VideoComponentParamsSchema uses z.string().url() — strict
+    const result = validateComponent(
+      makeComponent('video', { url: 'https://www.youtube.com/embed/abc' })
+    )
+    expect(result.valid).toBe(true)
+  })
+})
+
+describe('v5.5.0 — Imperative passthrough types preserve their rich codes', () => {
+  it('chart still emits MISSING_DATA / MISSING_DATASETS / MISSING_LABELS via validateChartComponent', () => {
+    const result = validateComponent(makeComponent('chart', {}))
+    expect(result.valid).toBe(false)
+    expect(result.errors?.[0].code).toBe('MISSING_DATA')
+  })
+
+  it('table still emits EMPTY_COLUMNS via validateTableComponent', () => {
+    const result = validateComponent(makeComponent('table', { columns: [], rows: [] }))
+    expect(result.valid).toBe(false)
+    expect(result.errors?.some((e) => e.code === 'EMPTY_COLUMNS')).toBe(true)
+  })
+
+  it('form still emits EMPTY_FORM via the imperative path (spec form schema is too strict for LLM payloads)', () => {
+    const result = validateComponent(makeComponent('form', { fields: [] }))
+    expect(result.valid).toBe(false)
+    expect(result.errors?.some((e) => e.code === 'EMPTY_FORM')).toBe(true)
+  })
+
+  it('map with object center {lat, lng} still passes (spec tuple shape would have rejected — kept imperative for compat)', () => {
+    const result = validateComponent(
+      makeComponent('map', { center: { lat: 48.8566, lng: 2.3522 }, zoom: 13 })
+    )
+    // Pre-v5.5.0 behavior preserved: object-shaped center is accepted.
+    expect(result.valid).toBe(true)
+  })
+
+  it('modal with arbitrary minimal params still passes (no validation)', () => {
+    const result = validateComponent(makeComponent('modal', { title: 'OK' }))
+    expect(result.valid).toBe(true)
+  })
+})
+
+describe('v5.5.0 — Invariants preserved (regression guard)', () => {
+  it('truly unknown types still rejected with UNKNOWN_COMPONENT_TYPE', () => {
+    const result = validateComponent(makeComponent('zzz-not-a-type' as ComponentType))
+    expect(result.valid).toBe(false)
+    expect(result.errors?.some((e) => e.code === 'UNKNOWN_COMPONENT_TYPE')).toBe(true)
+  })
+
+  it('missing component.params still emits MISSING_PARAMS (early return, before spec dispatch)', () => {
+    const component = {
+      id: 'x',
+      type: 'metric' as ComponentType,
+      position: { colStart: 1, colSpan: 12 },
+      params: undefined as any,
+    }
+    const result = validateComponent(component)
+    expect(result.valid).toBe(false)
+    expect(result.errors?.some((e) => e.code === 'MISSING_PARAMS')).toBe(true)
+  })
+
+  it('grid position errors still emit (validateGridPosition runs before spec dispatch)', () => {
+    const broken: UIComponent = {
+      id: 'x',
+      type: 'metric',
+      position: { colStart: 99, colSpan: 1 },
+      params: { title: 'X', value: 1 },
+    }
+    const result = validateComponent(broken)
+    expect(result.valid).toBe(false)
+    expect(result.errors?.some((e) => e.code === 'INVALID_GRID_COL_START')).toBe(true)
+  })
+})

package/src/services/validation.ts

@@ -8,6 +8,21 @@
  * - Security constraints (domain whitelist, XSS prevention)
  */
 
+import type { ZodIssue, ZodSchema } from 'zod'
+import {
+  MetricComponentParamsSchema,
+  TextComponentParamsSchema,
+  IframeComponentParamsSchema,
+  ImageComponentParamsSchema,
+  LinkComponentParamsSchema,
+  CarouselComponentParamsSchema,
+  ArtifactComponentParamsSchema,
+  ActionParamsSchema,
+  VideoComponentParamsSchema,
+  ImageGalleryParamsSchema,
+  ActionGroupParamsSchema,
+  CodeComponentParamsSchema,
+} from '@seed-ship/mcp-ui-spec'
 import type {
   UIComponent,
   UILayout,
@@ -31,6 +46,60 @@ const KNOWN_COMPONENT_TYPES: Set<string> = new Set<ComponentType>([
   'action-group', 'image-gallery', 'video', 'code', 'map',
 ])
 
+/**
+ * Spec-driven validation dispatch table (B.1 — v5.5.0).
+ *
+ * For each ComponentType where we delegate shape validation to a Zod schema
+ * from `@seed-ship/mcp-ui-spec`, this table maps:
+ *   - the schema to safeParse against
+ *   - the legacy error code to emit when shape parsing fails (preserves the
+ *     pre-v5.5.0 `errors[].code` API contract — see MCP-UI-AUDIT-2026-04-26.md
+ *     §I.3.a + §J.1)
+ *
+ * Types deliberately omitted (kept on the imperative path):
+ *   - `chart`, `table` — have rich imperative validators with their own
+ *     codes (MISSING_DATA, DATA_LENGTH_MISMATCH, RESOURCE_LIMIT_EXCEEDED, …)
+ *   - `form`           — spec FormFieldSchema has strict regex on field
+ *     names that could reject LLM-generated payloads. Conservative.
+ *   - `map`            — spec center is `tuple([number, number])`; production
+ *     payloads use `{lat, lng}` objects. Avoid backward-compat regression.
+ *   - `modal`          — all params are optional; nothing to enforce.
+ *   - `grid`, `footer`, `composite` — pass-through, validated elsewhere.
+ */
+const SPEC_VALIDATORS: Partial<Record<ComponentType, { schema: ZodSchema; legacyCode: string }>> = {
+  metric: { schema: MetricComponentParamsSchema, legacyCode: 'INVALID_METRIC' },
+  text: { schema: TextComponentParamsSchema, legacyCode: 'INVALID_TEXT' },
+  iframe: { schema: IframeComponentParamsSchema, legacyCode: 'INVALID_IFRAME' },
+  image: { schema: ImageComponentParamsSchema, legacyCode: 'INVALID_IMAGE' },
+  link: { schema: LinkComponentParamsSchema, legacyCode: 'INVALID_LINK' },
+  action: { schema: ActionParamsSchema, legacyCode: 'INVALID_ACTION' },
+  video: { schema: VideoComponentParamsSchema, legacyCode: 'INVALID_VIDEO' },
+  carousel: { schema: CarouselComponentParamsSchema, legacyCode: 'EMPTY_CAROUSEL' },
+  'image-gallery': { schema: ImageGalleryParamsSchema, legacyCode: 'EMPTY_GALLERY' },
+  'action-group': { schema: ActionGroupParamsSchema, legacyCode: 'EMPTY_ACTION_GROUP' },
+  code: { schema: CodeComponentParamsSchema, legacyCode: 'INVALID_CODE' },
+  artifact: { schema: ArtifactComponentParamsSchema, legacyCode: 'INVALID_ARTIFACT' },
+}
+
+/**
+ * Map a Zod issue list to the legacy `ValidationError[]` shape.
+ *
+ * Preserves the pre-v5.5.0 contract: `path` always begins with `params`,
+ * `code` is the per-type legacy code (so consumers that filtered by
+ * `errors[].code === 'EMPTY_CAROUSEL'` keep working), `message` is Zod's
+ * native human-readable message.
+ */
+function mapZodIssuesToErrors(
+  issues: readonly ZodIssue[],
+  legacyCode: string
+): NonNullable<ValidationResult['errors']> {
+  return issues.map((issue) => ({
+    path: issue.path.length > 0 ? `params.${issue.path.join('.')}` : 'params',
+    message: issue.message,
+    code: legacyCode,
+  }))
+}
+
 /**
  * Default resource limits (configurable via env)
  */
@@ -600,201 +669,86 @@ export function validateComponent(
     errors.push(...(sizeResult.errors || []))
   }
 
-  // Type-specific validation
-  switch (component.type) {
-    case 'chart': {
-      const chartResult = validateChartComponent(component.params as ChartComponentParams, limits)
-      if (!chartResult.valid) {
-        errors.push(...(chartResult.errors || []))
-      }
-      break
-    }
-
-    case 'table': {
-      const tableResult = validateTableComponent(component.params as TableComponentParams, limits)
-      if (!tableResult.valid) {
-        errors.push(...(tableResult.errors || []))
-      }
-      break
-    }
-
-    case 'metric': {
-      // Basic validation for metrics
-      const metricParams = component.params as any
-      if (!metricParams.title || !metricParams.value) {
-        errors.push({
-          path: 'params',
-          message: 'Metric must have title and value',
-          code: 'INVALID_METRIC',
-        })
-      }
-      break
-    }
-
-    case 'text': {
-      // Basic validation for text
-      const textParams = component.params as any
-      if (!textParams.content) {
-        errors.push({
-          path: 'params',
-          message: 'Text component must have content',
-          code: 'INVALID_TEXT',
-        })
-      }
-      break
-    }
-
-    case 'iframe': {
-      // Basic validation for iframe
-      const iframeParams = component.params as any
-      if (!iframeParams.url) {
-        errors.push({
-          path: 'params',
-          message: 'Iframe component must have url',
-          code: 'INVALID_IFRAME',
-        })
-      } else {
-        // Validate iframe domain against whitelist
-        const iframeResult = validateIframeDomain(iframeParams.url, {
+  // Type-specific validation (B.1 — v5.5.0).
+  //
+  // 12 types delegate shape validation to Zod schemas in `mcp-ui-spec` via
+  // SPEC_VALIDATORS. The 5 remaining types stay imperative because they
+  // need cross-field consistency, resource limits, or backward-compat logic
+  // that pure Zod can't express without `.refine()` (see SPEC_VALIDATORS docstring).
+  const specValidator = SPEC_VALIDATORS[component.type]
+  if (specValidator) {
+    const result = specValidator.schema.safeParse(component.params)
+    if (!result.success) {
+      errors.push(...mapZodIssuesToErrors(result.error.issues, specValidator.legacyCode))
+    }
+    // Iframe + video: chain the domain whitelist post-check ONLY when the
+    // shape parse succeeded (i.e. url is present and a string). Skipping the
+    // domain check when shape failed avoids cascading errors on the same field.
+    if (result.success && (component.type === 'iframe' || component.type === 'video')) {
+      const url = (component.params as { url?: string })?.url
+      if (typeof url === 'string') {
+        const domainResult = validateIframeDomain(url, {
           policy: options?.iframePolicy,
           customDomains: options?.customIframeDomains,
         })
-        if (!iframeResult.valid) {
-          errors.push(...(iframeResult.errors || []))
+        if (!domainResult.valid) {
+          errors.push(...(domainResult.errors || []))
         }
       }
-      break
-    }
-
-    case 'image': {
-      // Basic validation for image
-      const imageParams = component.params as any
-      if (!imageParams.url) {
-        errors.push({
-          path: 'params',
-          message: 'Image component must have url',
-          code: 'INVALID_IMAGE',
-        })
-      }
-      break
-    }
-
-    case 'link': {
-      // Basic validation for link
-      const linkParams = component.params as any
-      if (!linkParams.url) {
-        errors.push({
-          path: 'params',
-          message: 'Link component must have url',
-          code: 'INVALID_LINK',
-        })
-      }
-      break
-    }
-
-    case 'action': {
-      // Basic validation for action
-      const actionParams = component.params as any
-      if (!actionParams.label) {
-        errors.push({
-          path: 'params',
-          message: 'Action component must have label',
-          code: 'INVALID_ACTION',
-        })
-      }
-      break
     }
-
-    case 'video': {
-      const videoParams = component.params as any
-      if (!videoParams.url) {
-        errors.push({ path: 'params', message: 'Video component must have url', code: 'INVALID_VIDEO' })
-      } else {
-        // Reuse iframe domain validation for video URLs
-        const videoResult = validateIframeDomain(videoParams.url, {
-          policy: options?.iframePolicy,
-          customDomains: options?.customIframeDomains,
-        })
-        if (!videoResult.valid) {
-          errors.push(...(videoResult.errors || []))
+  } else {
+    // Imperative path for chart/table/form/map/modal/grid/footer/composite.
+    switch (component.type) {
+      case 'chart': {
+        const chartResult = validateChartComponent(component.params as ChartComponentParams, limits)
+        if (!chartResult.valid) {
+          errors.push(...(chartResult.errors || []))
         }
+        break
       }
-      break
-    }
-
-    case 'carousel': {
-      const carouselParams = component.params as any
-      if (!Array.isArray(carouselParams.items) || carouselParams.items.length === 0) {
-        errors.push({ path: 'params.items', message: 'Carousel must have non-empty items array', code: 'EMPTY_CAROUSEL' })
-      }
-      break
-    }
 
-    case 'image-gallery': {
-      const galleryParams = component.params as any
-      if (!Array.isArray(galleryParams.images) || galleryParams.images.length === 0) {
-        errors.push({ path: 'params.images', message: 'Gallery must have non-empty images array', code: 'EMPTY_GALLERY' })
-      }
-      break
-    }
-
-    case 'form': {
-      const formParams = component.params as any
-      if (!Array.isArray(formParams.fields) || formParams.fields.length === 0) {
-        errors.push({ path: 'params.fields', message: 'Form must have non-empty fields array', code: 'EMPTY_FORM' })
-      }
-      break
-    }
-
-    case 'action-group': {
-      const agParams = component.params as any
-      if (!Array.isArray(agParams.actions) || agParams.actions.length === 0) {
-        errors.push({ path: 'params.actions', message: 'Action group must have non-empty actions array', code: 'EMPTY_ACTION_GROUP' })
+      case 'table': {
+        const tableResult = validateTableComponent(component.params as TableComponentParams, limits)
+        if (!tableResult.valid) {
+          errors.push(...(tableResult.errors || []))
+        }
+        break
       }
-      break
-    }
 
-    case 'code': {
-      const codeParams = component.params as any
-      if (!codeParams.code) {
-        errors.push({ path: 'params.code', message: 'Code component must have code content', code: 'INVALID_CODE' })
+      case 'form': {
+        const formParams = component.params as { fields?: unknown[] }
+        if (!Array.isArray(formParams.fields) || formParams.fields.length === 0) {
+          errors.push({ path: 'params.fields', message: 'Form must have non-empty fields array', code: 'EMPTY_FORM' })
+        }
+        break
       }
-      break
-    }
 
-    case 'map': {
-      // Map can auto-detect center from markers, so center is not strictly required
-      const mapParams = component.params as any
-      if (!mapParams.center && (!Array.isArray(mapParams.markers) || mapParams.markers.length === 0)) {
-        errors.push({ path: 'params', message: 'Map must have center or markers', code: 'INVALID_MAP' })
+      case 'map': {
+        // Map can auto-detect center from markers, so center is not strictly required.
+        // Spec MapComponentParamsSchema would be too strict (tuple-only center) — kept imperative.
+        const mapParams = component.params as { center?: unknown; markers?: unknown[] }
+        if (!mapParams.center && (!Array.isArray(mapParams.markers) || mapParams.markers.length === 0)) {
+          errors.push({ path: 'params', message: 'Map must have center or markers', code: 'INVALID_MAP' })
+        }
+        break
       }
-      break
-    }
 
-    case 'modal': {
-      // Modal is valid with minimal params (title optional, content can be children)
-      break
-    }
+      case 'modal':
+        // Modal is valid with minimal params (title optional, content can be children).
+        break
 
-    case 'artifact': {
-      const artifactParams = component.params as any
-      if (!artifactParams.content) {
-        errors.push({ path: 'params.content', message: 'Artifact must have content', code: 'INVALID_ARTIFACT' })
-      }
-      break
+      default:
+        // Known types without specific validation pass through — renderer handles errors.
+        // Truly unknown types (e.g. typos in streamed JSON) are rejected.
+        if (!KNOWN_COMPONENT_TYPES.has(component.type)) {
+          errors.push({
+            path: 'type',
+            message: `Unknown component type: ${component.type}`,
+            code: 'UNKNOWN_COMPONENT_TYPE',
+          })
+        }
+        break
     }
-
-    default:
-      // Known types without specific validation pass through — renderer handles errors
-      // Truly unknown types (e.g. typos in streamed JSON) are rejected
-      if (!KNOWN_COMPONENT_TYPES.has(component.type)) {
-        errors.push({
-          path: 'type',
-          message: `Unknown component type: ${component.type}`,
-          code: 'UNKNOWN_COMPONENT_TYPE',
-        })
-      }
-      break
   }
 
   return {

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()
+  })
+})