@seed-ship/mcp-ui-solid 3.0.5 → 4.0.0

package/src/components/MapRenderer.tsx

@@ -1,12 +1,12 @@
 /**
  * MapRenderer - Interactive map Component
- * Sprint 6: Code & Maps
- * Sprint Ultimate U.2: Marker Clustering Support
+ * Sprint 6: Markers + clustering
+ * v3.1.0: GeoJSON, choropleth, popups, multi-layer, PMTiles
  */
 
 import { Component, createEffect, onCleanup, createSignal, Show } from 'solid-js'
 import { isServer } from 'solid-js/web'
-import type { UIComponent, MapComponentParams, MapClusterOptions } from '../types'
+import type { UIComponent, MapComponentParams, MapClusterOptions, MapGeoJSONStyle, MapPopupConfig, MapLayer, MapPMTilesConfig } from '../types'
 
 // Lazy load leaflet (it doesn't support SSR well)
 let L: any = null
@@ -25,6 +25,146 @@ export interface MapRendererProps {
     params?: MapComponentParams
 }
 
+// ─── Helpers ────────────────────────────────────────────────
+
+/**
+ * Resolve choropleth color for a feature based on property value and scale stops.
+ */
+function getChoroplethColor(
+    value: unknown,
+    scale: Array<[number, string]>,
+    fallback: string
+): string {
+    if (value == null || typeof value !== 'number' || !isFinite(value)) return fallback
+
+    // Scale is sorted ascending: [[0, '#eff3ff'], [100, '#084594']]
+    if (scale.length === 0) return fallback
+    if (value <= scale[0][0]) return scale[0][1]
+    if (value >= scale[scale.length - 1][0]) return scale[scale.length - 1][1]
+
+    // Find surrounding stops and interpolate (use upper bracket color)
+    for (let i = 1; i < scale.length; i++) {
+        if (value <= scale[i][0]) return scale[i][1]
+    }
+    return scale[scale.length - 1][1]
+}
+
+/**
+ * Build a Leaflet style function from MapGeoJSONStyle config.
+ */
+function buildStyleFn(style: MapGeoJSONStyle | undefined): (feature: any) => Record<string, unknown> {
+    if (!style) {
+        return () => ({
+            fillColor: '#3388ff',
+            fillOpacity: 0.6,
+            color: '#333',
+            weight: 1,
+            opacity: 1,
+        })
+    }
+
+    return (feature: any) => {
+        let fillColor = style.fillColor || '#3388ff'
+
+        // Choropleth: override fillColor based on feature property
+        if (style.choroplethField && style.choroplethScale && feature?.properties) {
+            const val = feature.properties[style.choroplethField]
+            fillColor = getChoroplethColor(val, style.choroplethScale, style.choroplethFallback || '#ccc')
+        }
+
+        return {
+            fillColor,
+            fillOpacity: style.fillOpacity ?? 0.6,
+            color: style.strokeColor || '#333',
+            weight: style.strokeWeight ?? 1,
+            opacity: style.strokeOpacity ?? 1,
+        }
+    }
+}
+
+/**
+ * Build popup HTML from a feature's properties using popup config.
+ */
+function buildPopupContent(feature: any, popup: MapPopupConfig | undefined): string | null {
+    if (!popup || !feature?.properties) return null
+    const props = feature.properties
+
+    // Custom template
+    if (popup.template) {
+        return popup.template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+            const val = props[key]
+            return val != null ? String(val) : ''
+        })
+    }
+
+    // Auto-generated popup
+    const parts: string[] = []
+
+    if (popup.titleField && props[popup.titleField] != null) {
+        parts.push(`<strong>${escapeHtml(String(props[popup.titleField]))}</strong>`)
+    }
+
+    const fields = popup.fields || Object.keys(props).slice(0, 8)
+    for (const key of fields) {
+        if (key === popup.titleField) continue
+        const val = props[key]
+        if (val == null) continue
+        const formatted = typeof val === 'number' ? val.toLocaleString('fr-FR') : String(val)
+        parts.push(`<span style="color:#666;font-size:11px">${escapeHtml(key)}</span>: ${escapeHtml(formatted)}`)
+    }
+
+    return parts.join('<br/>')
+}
+
+function escapeHtml(str: string): string {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+}
+
+/**
+ * Add a GeoJSON layer to the map with style and popup support.
+ * Returns the layer for bounds calculation.
+ */
+function addGeoJSONLayer(
+    mapInst: any,
+    leaflet: any,
+    geojson: unknown,
+    style?: MapGeoJSONStyle,
+    popup?: MapPopupConfig
+): any {
+    const styleFn = buildStyleFn(style)
+
+    const layer = leaflet.geoJSON(geojson, {
+        style: styleFn,
+        pointToLayer: (feature: any, latlng: any) => {
+            // Render points as circle markers for consistency
+            const s = styleFn(feature)
+            return leaflet.circleMarker(latlng, {
+                radius: 6,
+                fillColor: s.fillColor,
+                fillOpacity: s.fillOpacity,
+                color: s.color,
+                weight: s.weight,
+                opacity: s.opacity,
+            })
+        },
+        onEachFeature: (feature: any, featureLayer: any) => {
+            const html = buildPopupContent(feature, popup)
+            if (html) {
+                featureLayer.bindPopup(html, { maxWidth: 300 })
+            }
+        },
+    })
+
+    layer.addTo(mapInst)
+    return layer
+}
+
+// ─── Component ──────────────────────────────────────────────
+
 export const MapRenderer: Component<MapRendererProps> = (props) => {
     let mapContainer: HTMLDivElement | undefined
     let mapInstance: any = null
@@ -82,38 +222,33 @@ export const MapRenderer: Component<MapRendererProps> = (props) => {
             })
         }
 
-        // Update markers and view - Sprint Ultimate U.2: Clustering support
+        // Update markers and view
         if (mapInstance && L) {
             const p = params()
+            const allBoundsLayers: any[] = []
 
-            // Clear existing layers (markers and cluster groups)
+            // Clear existing layers (markers, cluster groups, GeoJSON)
             mapInstance.eachLayer((layer: any) => {
-                if (layer instanceof L.Marker || layer._group || layer._featureGroup) {
+                if (layer instanceof L.Marker || layer instanceof L.GeoJSON
+                    || layer instanceof L.CircleMarker
+                    || layer._group || layer._featureGroup) {
                     mapInstance.removeLayer(layer)
                 }
             })
 
+            // ─── Markers (legacy) ────────────────────────
             const markers: any[] = []
             const shouldCluster = p?.clustering && p?.markers && p.markers.length > 0
 
             if (shouldCluster) {
-                // Sprint Ultimate U.2: Use marker clustering
                 try {
-                    // Lazy load markercluster plugin
-                    // Import markercluster plugin for side-effects (registers with Leaflet)
                     await import('leaflet.markercluster')
-
-                    // Load cluster CSS if not already loaded
                     if (!clusterCssLoaded) {
                         await import('leaflet.markercluster/dist/MarkerCluster.css')
                         await import('leaflet.markercluster/dist/MarkerCluster.Default.css')
                         clusterCssLoaded = true
                     }
-
-                    // Get cluster options
                     const clusterOpts: MapClusterOptions = typeof p.clustering === 'object' ? p.clustering : {}
-
-                    // Create cluster group with options
                     const clusterGroup = (L as any).markerClusterGroup({
                         maxClusterRadius: clusterOpts.maxClusterRadius ?? 80,
                         spiderfyOnMaxZoom: clusterOpts.spiderfyOnMaxZoom ?? true,
@@ -121,53 +256,119 @@ export const MapRenderer: Component<MapRendererProps> = (props) => {
                         disableClusteringAtZoom: clusterOpts.disableClusteringAtZoom,
                         animate: clusterOpts.animateAddingMarkers ?? true
                     })
-
-                    // Add markers to cluster group
                     p?.markers?.forEach(marker => {
                         const m = L.marker(marker.position)
-                        if (marker.tooltip) {
-                            m.bindTooltip(marker.tooltip)
-                        }
-                        if (marker.popup) {
-                            m.bindPopup(marker.popup)
-                        }
+                        if (marker.tooltip) m.bindTooltip(marker.tooltip)
+                        if (marker.popup) m.bindPopup(marker.popup)
                         clusterGroup.addLayer(m)
                         markers.push(m)
                     })
-
                     mapInstance.addLayer(clusterGroup)
-                } catch (e) {
-                    console.warn('Failed to load leaflet.markercluster, falling back to regular markers', e)
-                    // Fallback to regular markers
+                } catch {
                     p?.markers?.forEach(marker => {
                         const m = L.marker(marker.position).addTo(mapInstance)
-                        if (marker.tooltip) {
-                            m.bindTooltip(marker.tooltip)
-                        }
-                        if (marker.popup) {
-                            m.bindPopup(marker.popup)
-                        }
+                        if (marker.tooltip) m.bindTooltip(marker.tooltip)
+                        if (marker.popup) m.bindPopup(marker.popup)
                         markers.push(m)
                     })
                 }
             } else {
-                // Standard marker rendering (no clustering)
                 p?.markers?.forEach(marker => {
                     const m = L.marker(marker.position).addTo(mapInstance)
-                    if (marker.tooltip) {
-                        m.bindTooltip(marker.tooltip)
-                    }
-                    if (marker.popup) {
-                        m.bindPopup(marker.popup)
-                    }
+                    if (marker.tooltip) m.bindTooltip(marker.tooltip)
+                    if (marker.popup) m.bindPopup(marker.popup)
                     markers.push(m)
                 })
             }
 
-            // Handle fitBounds
-            if (p?.fitBounds && markers.length > 0) {
-                const group = L.featureGroup(markers)
-                mapInstance.fitBounds(group.getBounds().pad(0.1))
+            if (markers.length > 0) {
+                allBoundsLayers.push(...markers)
+            }
+
+            // ─── GeoJSON (v3.1.0) ───────────────────────
+            if (p?.geojson) {
+                const geoLayer = addGeoJSONLayer(mapInstance, L, p.geojson, p.geojsonStyle, p.popup)
+                allBoundsLayers.push(geoLayer)
+            }
+
+            // ─── Named layers (v3.1.0) ──────────────────
+            if (p?.layers && p.layers.length > 0) {
+                const overlays: Record<string, any> = {}
+
+                for (const layerDef of p.layers) {
+                    const geoLayer = addGeoJSONLayer(
+                        mapInstance, L,
+                        layerDef.geojson,
+                        layerDef.style || p?.geojsonStyle,
+                        layerDef.popup || p?.popup
+                    )
+
+                    overlays[layerDef.name] = geoLayer
+                    allBoundsLayers.push(geoLayer)
+
+                    // Respect initial visibility
+                    if (layerDef.visible === false) {
+                        mapInstance.removeLayer(geoLayer)
+                    }
+                }
+
+                // Add layer control if multiple layers
+                if (Object.keys(overlays).length > 1) {
+                    L.control.layers(null, overlays, { collapsed: true }).addTo(mapInstance)
+                }
+            }
+
+            // ─── PMTiles (v3.1.0) ────────────────────────
+            if (p?.pmtiles) {
+                try {
+                    // @ts-ignore — optional peer dependency, may not be installed
+                    const protomaps = await import(/* @vite-ignore */ 'protomaps-leaflet')
+                    const pmConfig = p.pmtiles
+
+                    const paintRules = pmConfig.paintRules?.map(rule => ({
+                        dataLayer: rule.dataLayer,
+                        symbolizer: new (protomaps as any)[
+                            rule.symbolizer === 'polygon' ? 'PolygonSymbolizer' :
+                            rule.symbolizer === 'line' ? 'LineSymbolizer' :
+                            'CircleSymbolizer'
+                        ]({
+                            fill: rule.color || '#3388ff',
+                            stroke: rule.color || '#333',
+                            width: rule.width ?? 1,
+                            opacity: rule.opacity ?? 0.6,
+                        }),
+                    })) || []
+
+                    const labelRules = pmConfig.labelRules?.map(rule => ({
+                        dataLayer: rule.dataLayer,
+                        symbolizer: new (protomaps as any).TextSymbolizer({
+                            label_props: [rule.textField],
+                            fontSize: rule.fontSize ?? 12,
+                        }),
+                    })) || []
+
+                    const pmLayer = (protomaps as any).leafletLayer({
+                        url: pmConfig.url,
+                        attribution: pmConfig.attribution,
+                        paintRules,
+                        labelRules,
+                        maxZoom: pmConfig.maxZoom,
+                        minZoom: pmConfig.minZoom,
+                    })
+
+                    pmLayer.addTo(mapInstance)
+                } catch (e) {
+                    console.warn('[MCP-UI] Failed to load protomaps-leaflet for PMTiles:', e)
+                }
+            }
+
+            // ─── Fit bounds ─────────────────────────────
+            if (p?.fitBounds && allBoundsLayers.length > 0) {
+                const group = L.featureGroup(allBoundsLayers)
+                const bounds = group.getBounds()
+                if (bounds.isValid()) {
+                    mapInstance.fitBounds(bounds.pad(0.1))
+                }
             } else if (p?.center) {
                 mapInstance.setView(p.center, p.zoom || mapInstance.getZoom())
             }
@@ -183,7 +384,7 @@ export const MapRenderer: Component<MapRendererProps> = (props) => {
     })
 
     return (
-        <div class="w-full bg-white dark:bg-gray-800 rounded-lg shadow-sm border border-gray-200 dark:border-gray-700 overflow-hidden">
+        <div class={`w-full bg-white dark:bg-gray-800 rounded-lg shadow-sm border border-gray-200 dark:border-gray-700 overflow-hidden ${params()?.className || ''}`}>
             <Show when={error()}>
                 <div class="p-4 text-red-500 bg-red-50 dark:bg-red-900/20 text-center">
                     {error()}

package/src/components/ScratchpadPanel.tsx

@@ -6,9 +6,13 @@
  */
 
 import { Component, Show, For, Switch, Match, createSignal, createEffect, onCleanup } from 'solid-js'
-import type { ScratchpadState, ScratchpadSection } from '../types/chat-bus'
-import type { FormFieldParams } from '../types'
+import type { ScratchpadState, ScratchpadSection, VerifiedTextContent, DataPreviewContent, MapSectionContent } from '../types/chat-bus'
+import type { FormFieldParams, ChartComponentParams } from '../types'
 import { FormFieldRenderer } from './FormFieldRenderer'
+import { VerifiedText } from './VerifiedText'
+import { DataPreviewSection } from './DataPreviewSection'
+import { MapRenderer } from './MapRenderer'
+import { ChartJSRenderer } from './ChartJSRenderer'
 
 export interface ScratchpadPanelProps {
   state: ScratchpadState
@@ -365,6 +369,10 @@ const SectionRenderer: Component<{
         <Match when={props.section.type === 'error'}><ErrorSectionRenderer content={props.section.content} onAction={props.onAction} /></Match>
         <Match when={props.section.type === 'source_card'}><SourceCardSection content={props.section.content} /></Match>
         <Match when={props.section.type === 'diff'}><DiffSection content={props.section.content} /></Match>
+        <Match when={props.section.type === 'verified_text'}><VerifiedText {...(props.section.content as VerifiedTextContent)} onHallucinationClick={(h) => props.onAction?.('hallucination_click', h)} /></Match>
+        <Match when={props.section.type === 'data_preview'}><DataPreviewSection content={props.section.content as DataPreviewContent} /></Match>
+        <Match when={props.section.type === 'map'}>{(() => { const c = props.section.content as MapSectionContent; return <MapRenderer params={{ geojson: c.geojson, center: c.center, zoom: c.zoom, geojsonStyle: c.style, popup: c.popup, layers: c.layers, height: c.height || '300px', fitBounds: true }} /> })()}</Match>
+        <Match when={props.section.type === 'chart'}><ChartJSRenderer component={{ id: props.section.id, type: 'chart', position: { colStart: 1, colSpan: 12 }, params: { ...(props.section.content as ChartComponentParams), renderer: 'native', height: (props.section.content as any)?.height || '250px' } }} /></Match>
         <Match when={true}><pre class="text-xs text-gray-500 overflow-auto">{JSON.stringify(props.section.content, null, 2)}</pre></Match>
       </Switch>
     </div>

package/src/components/VerifiedText.tsx

@@ -0,0 +1,187 @@
+/**
+ * VerifiedText — renders LLM text with inline verification badges
+ * v3.1.0: Highlights verified vs hallucinated numbers
+ *
+ * @experimental
+ *
+ * Modes:
+ * - highlight: ✅/⚠️ badges next to numbers (default)
+ * - strip: replaces hallucinated numbers with [non vérifié]
+ * - annotate: tooltip on hover with closest source number
+ */
+
+import { createMemo, For } from 'solid-js'
+import type { DataValidation, HallucinatedNumber } from '../types/chat-bus'
+
+export interface VerifiedTextProps {
+  text: string
+  validation: DataValidation
+  /** Display mode (default: 'highlight') */
+  mode?: 'highlight' | 'strip' | 'annotate'
+  /** Callback when a hallucinated number is clicked */
+  onHallucinationClick?: (item: HallucinatedNumber) => void
+}
+
+interface TextSegment {
+  type: 'text' | 'verified' | 'hallucinated'
+  content: string
+  item?: HallucinatedNumber
+}
+
+/**
+ * Build annotated segments by splitting text at number positions.
+ * Verified numbers get ✅, hallucinated get ⚠️.
+ */
+function buildAnnotatedSegments(text: string, validation: DataValidation): TextSegment[] {
+  // Build position maps
+  const hallucinatedPositions = new Map<number, HallucinatedNumber>()
+  for (const h of validation.hallucinated) {
+    hallucinatedPositions.set(h.position, h)
+  }
+
+  const verifiedPositions = new Set<number>()
+  for (const n of validation.llmNumbers) {
+    if (!hallucinatedPositions.has(n.position)) {
+      verifiedPositions.add(n.position)
+    }
+  }
+
+  // Build all number positions sorted
+  const allPositions = validation.llmNumbers
+    .map(n => ({ position: n.position, length: n.context.length - 20 })) // approximate original match length
+    .sort((a, b) => a.position - b.position)
+
+  // Re-extract number lengths from text for precise splitting
+  const numberRegex = /\d[\d\s,.]*\d|\d+/g
+  const matches: Array<{ start: number; end: number }> = []
+  let m: RegExpExecArray | null
+  while ((m = numberRegex.exec(text)) !== null) {
+    matches.push({ start: m.index, end: m.index + m[0].length })
+  }
+
+  // Build a lookup from position → match
+  const matchByPosition = new Map<number, { start: number; end: number }>()
+  for (const match of matches) {
+    matchByPosition.set(match.start, match)
+  }
+
+  // Build segments
+  const segments: TextSegment[] = []
+  let cursor = 0
+
+  for (const num of validation.llmNumbers) {
+    const match = matchByPosition.get(num.position)
+    if (!match) continue
+
+    // Text before this number
+    if (match.start > cursor) {
+      segments.push({ type: 'text', content: text.slice(cursor, match.start) })
+    }
+
+    const numberText = text.slice(match.start, match.end)
+    const hallucinated = hallucinatedPositions.get(num.position)
+
+    if (hallucinated) {
+      segments.push({ type: 'hallucinated', content: numberText, item: hallucinated })
+    } else {
+      segments.push({ type: 'verified', content: numberText })
+    }
+
+    cursor = match.end
+  }
+
+  // Remaining text
+  if (cursor < text.length) {
+    segments.push({ type: 'text', content: text.slice(cursor) })
+  }
+
+  return segments
+}
+
+export function VerifiedText(props: VerifiedTextProps) {
+  const mode = () => props.mode || 'highlight'
+
+  const segments = createMemo<TextSegment[]>(() => {
+    if (!props.validation || props.validation.valid) {
+      return [{ type: 'text' as const, content: props.text }]
+    }
+    return buildAnnotatedSegments(props.text, props.validation)
+  })
+
+  return (
+    <div class="verified-text text-sm leading-relaxed">
+      <For each={segments()}>
+        {(seg) => {
+          if (seg.type === 'text') {
+            return <span>{seg.content}</span>
+          }
+
+          if (seg.type === 'verified') {
+            return (
+              <span
+                class="inline-flex items-center gap-0.5 px-0.5 rounded bg-green-50 dark:bg-green-900/20 text-green-800 dark:text-green-300"
+                title="Verified against source data"
+              >
+                {seg.content}
+                <span class="text-xs opacity-70" aria-label="verified">&#x2705;</span>
+              </span>
+            )
+          }
+
+          // hallucinated
+          const h = seg.item!
+          const tooltipText = () => {
+            if (h.closest != null && h.distance != null) {
+              return `Not found in source data. Closest: ${h.closest} (${Math.round(h.distance * 100)}% off)`
+            }
+            return 'Not found in source data'
+          }
+
+          if (mode() === 'strip') {
+            return (
+              <span
+                class="inline-flex items-center px-1 rounded bg-amber-50 dark:bg-amber-900/20 text-amber-700 dark:text-amber-300 italic text-xs"
+                title={tooltipText()}
+              >
+                [non v&eacute;rifi&eacute;]
+              </span>
+            )
+          }
+
+          return (
+            <span
+              class="inline-flex items-center gap-0.5 px-0.5 rounded bg-amber-50 dark:bg-amber-900/20 text-amber-800 dark:text-amber-300 cursor-help"
+              title={tooltipText()}
+              onClick={() => props.onHallucinationClick?.(h)}
+              role={props.onHallucinationClick ? 'button' : undefined}
+            >
+              {seg.content}
+              <span class="text-xs" aria-label="unverified">&#x26A0;&#xFE0F;</span>
+            </span>
+          )
+        }}
+      </For>
+
+      {/* Confidence bar */}
+      {props.validation && !props.validation.valid && (
+        <div class="mt-2 flex items-center gap-2 text-xs text-gray-500 dark:text-gray-400">
+          <div class="flex-1 h-1.5 bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
+            <div
+              class="h-full rounded-full transition-all"
+              classList={{
+                'bg-green-500': props.validation.confidence >= 0.8,
+                'bg-amber-500': props.validation.confidence >= 0.5 && props.validation.confidence < 0.8,
+                'bg-red-500': props.validation.confidence < 0.5,
+              }}
+              style={{ width: `${Math.round(props.validation.confidence * 100)}%` }}
+            />
+          </div>
+          <span>
+            {Math.round(props.validation.confidence * 100)}% verified
+            ({props.validation.hallucinated.length} unverified)
+          </span>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/index.ts

@@ -64,6 +64,13 @@ export type { CodeBlockRendererProps } from './CodeBlockRenderer'
 export { MapRenderer } from './MapRenderer'
 export type { MapRendererProps } from './MapRenderer'
 
+// Data Verification (v3.1.0 — anti-hallucination)
+export { VerifiedText } from './VerifiedText'
+export type { VerifiedTextProps } from './VerifiedText'
+
+export { DataPreviewSection } from './DataPreviewSection'
+export type { DataPreviewSectionProps } from './DataPreviewSection'
+
 // Sprint Ultimate: RenderContext for circular dependency resolution
 export { RenderContext, RenderProvider, useRenderContext } from './RenderContext'
 export type { RenderContextValue, RenderComponentFn } from './RenderContext'

package/src/hooks/index.ts

@@ -57,3 +57,10 @@ export type {
   UseAutocompleteOptions,
   UseAutocompleteReturn,
 } from './useAutocomplete'
+
+// Data Validator hooks (v3.1.0 — anti-hallucination)
+export { useDataValidator } from './useDataValidator'
+export type {
+  UseDataValidatorOptions,
+  UseDataValidatorReturn,
+} from './useDataValidator'

package/src/hooks/useDataValidator.ts

@@ -0,0 +1,68 @@
+/**
+ * useDataValidator — reactive SolidJS hook for data validation
+ * v3.1.0: Wraps validateAgainstSource in a reactive memo
+ *
+ * @experimental
+ */
+
+import { createMemo } from 'solid-js'
+import { validateAgainstSource } from '../services/data-validator'
+import type { DataValidation, DataValidationOptions } from '../types/chat-bus'
+
+export interface UseDataValidatorOptions extends DataValidationOptions {
+  /** Disable validation (returns null) */
+  enabled?: boolean
+}
+
+export interface UseDataValidatorReturn {
+  /** Reactive validation result (null if disabled or no text) */
+  validation: () => DataValidation | null
+  /** Is the text valid (no hallucinations)? */
+  valid: () => boolean
+  /** Confidence score 0-1 */
+  confidence: () => number
+  /** Count of hallucinated numbers */
+  hallucinatedCount: () => number
+}
+
+/**
+ * Reactive hook that validates LLM text against source data rows.
+ * Re-validates automatically when text or rows change.
+ *
+ * @example
+ * ```tsx
+ * const { validation, valid, confidence } = useDataValidator(
+ *   () => llmResponse(),
+ *   () => sourceRows(),
+ *   { tolerance: 0.02, ignoreColumns: ['code_geo'] }
+ * )
+ *
+ * return (
+ *   <Show when={!valid()}>
+ *     <span>⚠️ {validation()!.hallucinated.length} unverified numbers</span>
+ *   </Show>
+ * )
+ * ```
+ */
+export function useDataValidator(
+  text: () => string,
+  sourceRows: () => Record<string, unknown>[],
+  options: UseDataValidatorOptions = {}
+): UseDataValidatorReturn {
+  const { enabled = true, ...validationOptions } = options
+
+  const validation = createMemo<DataValidation | null>(() => {
+    if (!enabled) return null
+    const t = text()
+    const rows = sourceRows()
+    if (!t || !rows || rows.length === 0) return null
+    return validateAgainstSource(t, rows, validationOptions)
+  })
+
+  return {
+    validation,
+    valid: () => validation()?.valid ?? true,
+    confidence: () => validation()?.confidence ?? 1,
+    hallucinatedCount: () => validation()?.hallucinated.length ?? 0,
+  }
+}