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

package/src/index.ts

@@ -44,6 +44,10 @@ export { ChatPrompt } from './components/ChatPrompt'
 export { ScratchpadPanel } from './components/ScratchpadPanel'
 export { dispatchScratchpad, useScratchpadState } from './stores/scratchpad-store'
 
+// Data Verification Components (v3.1.0)
+export { VerifiedText } from './components/VerifiedText'
+export { DataPreviewSection } from './components/DataPreviewSection'
+
 // Autocomplete Components
 export { GhostText, GhostTextInput } from './components/GhostText'
 export { AutocompleteDropdown } from './components/AutocompleteDropdown'
@@ -62,6 +66,8 @@ export type { ExpandableWrapperProps } from './components/ExpandableWrapper'
 export type { ComponentToolbarProps, ToolbarAction, ToolbarIcon } from './components/ComponentToolbar'
 export type { ChatPromptProps } from './components/ChatPrompt'
 export type { ScratchpadPanelProps } from './components/ScratchpadPanel'
+export type { VerifiedTextProps } from './components/VerifiedText'
+export type { DataPreviewSectionProps } from './components/DataPreviewSection'
 export type { GhostTextProps, GhostTextInputProps } from './components/GhostText'
 export type { AutocompleteDropdownProps } from './components/AutocompleteDropdown'
 export type { AutocompleteFormFieldProps, AutocompleteFormFieldParams } from './components/AutocompleteFormField'
@@ -81,6 +87,8 @@ export {
   useResize,
   // Autocomplete hooks
   useAutocomplete,
+  // Data Validator hooks (v3.1.0)
+  useDataValidator,
 } from './hooks'
 
 export type {
@@ -107,6 +115,9 @@ export type {
   // Autocomplete types
   UseAutocompleteOptions,
   UseAutocompleteReturn,
+  // Data Validator types (v3.1.0)
+  UseDataValidatorOptions,
+  UseDataValidatorReturn,
 } from './hooks'
 
 // Context (Phase 5.0)
@@ -177,10 +188,14 @@ export type {
   GalleryImage,
   ImageGalleryParams,
   VideoComponentParams,
-  // Code & Maps types (Sprint 6)
+  // Code & Maps types (Sprint 6 + v3.1.0)
   CodeComponentParams,
   MapMarker,
   MapComponentParams,
+  MapPopupConfig,
+  MapGeoJSONStyle,
+  MapLayer,
+  MapPMTilesConfig,
   // Validation options (v2.0.0)
   IframePolicy,
   ValidationOptions,
@@ -217,6 +232,7 @@ export {
   createCommandHandler,
   createChatBus,
   mergeScratchpadSections,
+  validateAgainstSource,
 } from './services'
 
 // Chat Bus Types (v2.4.0 — @experimental)
@@ -246,4 +262,13 @@ export type {
   Citation,
   ToolCallEvent,
   ClarificationEvent,
+  // Data Validation types (v3.1.0)
+  DataValidation,
+  LLMNumber,
+  HallucinatedNumber,
+  DataValidationOptions,
+  VerifiedTextContent,
+  DataPreviewColumn,
+  DataPreviewContent,
+  MapSectionContent,
 } from './types/chat-bus'

package/src/services/data-validator.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Tests for validateAgainstSource — anti-hallucination data validator
+ */
+
+import { describe, it, expect } from 'vitest'
+import { validateAgainstSource } from './data-validator'
+
+const SAMPLE_ROWS = [
+  { type: 'Appartement', ventes: 22306, prix_m2: 3337 },
+  { type: 'Maison', ventes: 2492, prix_m2: 4230 },
+]
+
+describe('validateAgainstSource', () => {
+  it('validates text with exact source numbers', () => {
+    const text = 'On observe 22 306 ventes appartements et 3 337 EUR/m2 moyen.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    expect(result.valid).toBe(true)
+    expect(result.hallucinated).toHaveLength(0)
+    expect(result.confidence).toBe(1)
+  })
+
+  it('detects hallucinated numbers', () => {
+    const text = 'On observe 18 245 ventes en 2023, prix moyen 2 850 EUR.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    expect(result.valid).toBe(false)
+    expect(result.hallucinated.length).toBeGreaterThan(0)
+    expect(result.confidence).toBeLessThan(1)
+  })
+
+  it('returns hallucinated items with closest source number', () => {
+    const text = 'On observe 18 245 ventes.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    expect(result.hallucinated).toHaveLength(1)
+    expect(result.hallucinated[0].value).toBe(18245)
+    expect(result.hallucinated[0].closest).toBeDefined()
+    expect(result.hallucinated[0].distance).toBeDefined()
+  })
+
+  it('accepts rounding within tolerance', () => {
+    // 3337 rounded to 3340 is 0.09% — within 1% tolerance
+    const text = 'Le prix moyen est de 3 340 EUR.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS, { tolerance: 0.01 })
+
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects rounding beyond tolerance', () => {
+    // 3337 vs 3500 is ~4.9% — beyond 1% tolerance
+    const text = 'Le prix moyen est de 3 500 EUR.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS, { tolerance: 0.01 })
+
+    expect(result.valid).toBe(false)
+  })
+
+  it('ignores years by default', () => {
+    const text = 'En 2023, on observe 22 306 ventes.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    // 2023 should be ignored, 22306 should be verified
+    expect(result.valid).toBe(true)
+    expect(result.llmNumbers).toHaveLength(1) // only 22306
+  })
+
+  it('ignores postal/INSEE codes by default', () => {
+    const text = 'Code commune 34172, on observe 22 306 ventes.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    // 34172 should be ignored (5-digit pattern)
+    expect(result.valid).toBe(true)
+  })
+
+  it('ignores specified columns', () => {
+    const rows = [
+      { code_geo: '34172', ventes: 22306 },
+    ]
+    const text = 'Le code est 34172 avec 22 306 ventes.'
+    const result = validateAgainstSource(text, rows, {
+      ignoreColumns: ['code_geo'],
+    })
+
+    expect(result.valid).toBe(true)
+  })
+
+  it('handles string-encoded numbers in source', () => {
+    const rows = [
+      { prix: '3 337', total: '22306' },
+    ]
+    const text = 'Prix 3 337, total 22 306.'
+    const result = validateAgainstSource(text, rows)
+
+    expect(result.valid).toBe(true)
+  })
+
+  it('returns confidence = 1 for text with no numbers', () => {
+    const text = 'Les données sont stables et cohérentes.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    expect(result.valid).toBe(true)
+    expect(result.confidence).toBe(1)
+    expect(result.llmNumbers).toHaveLength(0)
+  })
+
+  it('handles empty source rows', () => {
+    const text = 'On observe 22 306 ventes.'
+    const result = validateAgainstSource(text, [])
+
+    // With empty source, any number in text is hallucinated
+    expect(result.valid).toBe(false)
+  })
+
+  it('mixes verified and hallucinated', () => {
+    const text = 'On observe 22 306 ventes reelles et 15 000 ventes estimees.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    expect(result.valid).toBe(false)
+    expect(result.hallucinated).toHaveLength(1)
+    expect(result.hallucinated[0].value).toBe(15000)
+    // 1 hallucinated out of 2 = 50% confidence
+    expect(result.confidence).toBe(0.5)
+  })
+
+  it('provides context around numbers', () => {
+    const text = 'Le prix moyen est de 3 337 EUR/m2 a Montpellier.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS)
+
+    expect(result.llmNumbers[0].context).toContain('3 337')
+  })
+
+  it('handles custom ignorePatterns', () => {
+    const text = 'Parcelle 1234 avec 22 306 ventes.'
+    const result = validateAgainstSource(text, SAMPLE_ROWS, {
+      ignorePatterns: [/^\d{4}$/], // ignore 4-digit numbers
+    })
+
+    expect(result.valid).toBe(true)
+    expect(result.llmNumbers).toHaveLength(1) // only 22306
+  })
+
+  it('returns sourceNumbers as a Set', () => {
+    const result = validateAgainstSource('test', SAMPLE_ROWS)
+
+    expect(result.sourceNumbers).toBeInstanceOf(Set)
+    expect(result.sourceNumbers.has(22306)).toBe(true)
+    expect(result.sourceNumbers.has(3337)).toBe(true)
+    expect(result.sourceNumbers.has(2492)).toBe(true)
+    expect(result.sourceNumbers.has(4230)).toBe(true)
+  })
+})

package/src/services/data-validator.ts

@@ -0,0 +1,149 @@
+/**
+ * Data Validator — anti-hallucination for LLM-generated text
+ * v3.1.0: Pure regex-based number verification against source data
+ *
+ * Compares numbers in LLM text to numbers in source data rows.
+ * Detects ~90% of numerical hallucinations with zero LLM cost, <1ms latency.
+ */
+
+import type { DataValidation, DataValidationOptions, LLMNumber, HallucinatedNumber } from '../types/chat-bus'
+
+const DEFAULT_IGNORE_COLUMNS = new Set(['id', 'code_geo', 'code_parent'])
+const DEFAULT_IGNORE_PATTERNS: RegExp[] = [
+  /^20[012]\d$/,       // years 2000-2029
+  /^\d{5}$/,           // postal codes / INSEE codes
+  /^\d{1,2}$/,         // indices, ranks (1-99)
+]
+
+/**
+ * Extract all numeric values from source data rows.
+ * Handles both number types and string-encoded numbers (e.g. "22 306", "3,337").
+ */
+function extractSourceNumbers(
+  rows: Record<string, unknown>[],
+  ignoreColumns: Set<string>
+): Set<number> {
+  const numbers = new Set<number>()
+  for (const row of rows) {
+    for (const [col, val] of Object.entries(row)) {
+      if (ignoreColumns.has(col)) continue
+      if (typeof val === 'number' && isFinite(val)) {
+        numbers.add(val)
+      } else if (typeof val === 'string') {
+        const parsed = Number(val.replace(/\s/g, '').replace(',', '.'))
+        if (!isNaN(parsed) && isFinite(parsed)) {
+          numbers.add(parsed)
+        }
+      }
+    }
+  }
+  return numbers
+}
+
+/**
+ * Extract all numbers from LLM text.
+ * Handles French/European formats: "22 306", "3 337", "3,337", "22306".
+ */
+function extractLLMNumbers(
+  text: string,
+  ignorePatterns: RegExp[]
+): LLMNumber[] {
+  const numberRegex = /\d[\d\s,.]*\d|\d+/g
+  const results: LLMNumber[] = []
+  let match: RegExpExecArray | null
+
+  while ((match = numberRegex.exec(text)) !== null) {
+    const raw = match[0]
+    // Normalize: remove spaces/dots (thousand separators), comma → decimal point
+    const cleaned = raw.replace(/[\s.]/g, '').replace(',', '.')
+    const value = Number(cleaned)
+
+    if (isNaN(value) || !isFinite(value)) continue
+    if (ignorePatterns.some(p => p.test(raw.trim()))) continue
+
+    results.push({
+      value,
+      position: match.index,
+      context: text.slice(
+        Math.max(0, match.index - 10),
+        match.index + raw.length + 10
+      ),
+    })
+  }
+
+  return results
+}
+
+/**
+ * Validate LLM-generated text against source data rows.
+ *
+ * Pure function — no IO, no LLM calls, no side effects.
+ * Returns which numbers in the text are verified vs hallucinated.
+ *
+ * @example
+ * ```typescript
+ * const rows = [{ type: 'Appartement', ventes: 22306, prix_m2: 3337 }]
+ * const result = validateAgainstSource(
+ *   "On observe 22 306 ventes à 3 337 EUR/m². En 2023, 18 245 ventes.",
+ *   rows
+ * )
+ * // result.valid === false
+ * // result.hallucinated === [{ value: 18245, ... }]
+ * // result.confidence === 0.67
+ * ```
+ */
+export function validateAgainstSource(
+  text: string,
+  sourceRows: Record<string, unknown>[],
+  options: DataValidationOptions = {}
+): DataValidation {
+  const tolerance = options.tolerance ?? 0.01
+  const ignoreColumns = new Set(options.ignoreColumns || [...DEFAULT_IGNORE_COLUMNS])
+  const ignorePatterns = options.ignorePatterns || DEFAULT_IGNORE_PATTERNS
+
+  // 1. Extract source numbers
+  const sourceNumbers = extractSourceNumbers(sourceRows, ignoreColumns)
+
+  // 2. Extract LLM numbers
+  const llmNumbers = extractLLMNumbers(text, ignorePatterns)
+
+  // 3. Check each LLM number against source
+  const hallucinated: HallucinatedNumber[] = []
+
+  for (const num of llmNumbers) {
+    // Exact match
+    if (sourceNumbers.has(num.value)) continue
+
+    // Tolerance match (rounding)
+    let closest: number | undefined
+    let minDistance = Infinity
+
+    for (const src of sourceNumbers) {
+      const dist = Math.abs(num.value - src) / Math.max(Math.abs(src), 1)
+      if (dist < minDistance) {
+        minDistance = dist
+        closest = src
+      }
+    }
+
+    if (minDistance <= tolerance) continue // acceptable rounding
+
+    hallucinated.push({
+      ...num,
+      closest,
+      distance: minDistance,
+    })
+  }
+
+  const confidence = llmNumbers.length > 0
+    ? 1 - (hallucinated.length / llmNumbers.length)
+    : 1
+
+  return {
+    valid: hallucinated.length === 0,
+    llmNumbers,
+    sourceNumbers,
+    hallucinated,
+    confidence,
+  }
+}

package/src/services/index.ts

@@ -17,3 +17,5 @@ export {
 export { ComponentRegistry } from './component-registry'
 
 export { createEventEmitter, createCommandHandler, createChatBus, mergeScratchpadSections } from './chat-bus'
+
+export { validateAgainstSource } from './data-validator'

package/src/types/chat-bus.ts

@@ -366,7 +366,7 @@ export interface ScratchpadState {
 export interface ScratchpadSection {
   id: string
   title: string
-  type: 'data' | 'filter' | 'preview' | 'message' | 'action' | 'steps' | 'form' | 'understanding' | 'feedback' | 'prompt' | 'stepper' | 'error' | 'source_card' | 'diff'
+  type: 'data' | 'filter' | 'preview' | 'message' | 'action' | 'steps' | 'form' | 'understanding' | 'feedback' | 'prompt' | 'stepper' | 'error' | 'source_card' | 'diff' | 'verified_text' | 'data_preview' | 'map' | 'chart'
   content: unknown
   /** Can the human edit this section? */
   editable: boolean
@@ -438,3 +438,100 @@ export interface ClarificationEvent {
   }>
   original_message?: string
 }
+
+// ─── Data Validation (v3.1.0 — anti-hallucination) ──────────
+
+/**
+ * Result of validating LLM text against source data.
+ * Pure regex-based — zero LLM cost, <1ms latency.
+ */
+export interface DataValidation {
+  /** Is the text free of hallucinated numbers? */
+  valid: boolean
+  /** Numbers found in the LLM text */
+  llmNumbers: LLMNumber[]
+  /** Numbers present in the source data */
+  sourceNumbers: Set<number>
+  /** Numbers from the LLM NOT found in the source */
+  hallucinated: HallucinatedNumber[]
+  /** Confidence score 0-1 (1 = all numbers verified) */
+  confidence: number
+}
+
+export interface LLMNumber {
+  value: number
+  /** Character index in the text */
+  position: number
+  /** ~20 chars surrounding context */
+  context: string
+}
+
+export interface HallucinatedNumber extends LLMNumber {
+  /** Closest number in source data */
+  closest?: number
+  /** Distance as ratio (0.18 = 18% off) */
+  distance?: number
+}
+
+/** Options for validateAgainstSource */
+export interface DataValidationOptions {
+  /** Tolerance for rounding (default: 0.01 = 1%) */
+  tolerance?: number
+  /** Columns to ignore (e.g. 'id', 'code_geo') */
+  ignoreColumns?: string[]
+  /** Number patterns to ignore (e.g. years, postal codes) */
+  ignorePatterns?: RegExp[]
+}
+
+/** Content for verified_text scratchpad section */
+export interface VerifiedTextContent {
+  /** Original LLM text */
+  text: string
+  /** Validation result from validateAgainstSource */
+  validation: DataValidation
+  /** Display mode */
+  mode?: 'highlight' | 'strip' | 'annotate'
+}
+
+/** Column definition for data_preview section */
+export interface DataPreviewColumn {
+  key: string
+  label: string
+  type?: 'number' | 'string' | 'date'
+  format?: string
+  align?: 'left' | 'right' | 'center'
+}
+
+/** Content for data_preview scratchpad section */
+export interface DataPreviewContent {
+  columns: DataPreviewColumn[]
+  rows: Record<string, unknown>[]
+  /** Total rows (if paginated — e.g. 22306 total, 30 displayed) */
+  totalRows?: number
+  /** Data source attribution */
+  source?: string
+  /** Data freshness label */
+  freshness?: string
+  /** Enable export buttons (CSV/JSON) */
+  exportable?: boolean
+  /** Rows per page (default: 25) */
+  pageSize?: number
+}
+
+/** Content for map scratchpad section (v3.1.0) */
+export interface MapSectionContent {
+  /** GeoJSON FeatureCollection */
+  geojson: unknown
+  /** Map center [lat, lng] */
+  center?: [number, number]
+  /** Zoom level */
+  zoom?: number
+  /** GeoJSON style (including choropleth) */
+  style?: import('./index').MapGeoJSONStyle
+  /** Popup config for feature click */
+  popup?: import('./index').MapPopupConfig
+  /** Named layers */
+  layers?: import('./index').MapLayer[]
+  /** Map height (CSS, default: '300px') */
+  height?: string
+}

package/src/types/index.ts

@@ -94,10 +94,14 @@ export interface ChartComponentParams {
     labels: string[]
     datasets: Array<{
       label: string
-      data: number[]
+      data: number[] | Array<{ x: string | number; y: number }>
       backgroundColor?: string | string[]
       borderColor?: string | string[]
       borderWidth?: number
+      /** Fill area under line (useful for time-series) */
+      fill?: boolean | string
+      /** Line tension (0 = straight, 0.4 = smooth) */
+      tension?: number
     }>
   }
   options?: {
@@ -118,6 +122,22 @@ export interface ChartComponentParams {
    * Enable PNG export button (v2.2.0)
    */
   exportable?: boolean
+  /**
+   * Time-series axis configuration (v3.1.0).
+   * When set, x-axis labels are parsed as dates.
+   */
+  timeAxis?: {
+    /** Date format for parsing labels (Chart.js adapter format, e.g. 'yyyy-MM-dd') */
+    parser?: string
+    /** Display unit for x-axis ticks */
+    unit?: 'day' | 'week' | 'month' | 'quarter' | 'year'
+    /** Date format for tooltip display */
+    tooltipFormat?: string
+    /** Min date (ISO string) */
+    min?: string
+    /** Max date (ISO string) */
+    max?: string
+  }
   /**
    * Chart container height as CSS value (v2.2.0, default '250px')
    */
@@ -750,9 +770,60 @@ export interface MapClusterOptions {
   animateAddingMarkers?: boolean
 }
 
+/**
+ * GeoJSON feature popup configuration (v3.1.0)
+ */
+export interface MapPopupConfig {
+  /** Property key used as popup title */
+  titleField?: string
+  /** Property keys to display in popup body */
+  fields?: string[]
+  /** Custom HTML template (use {{property}} placeholders) */
+  template?: string
+}
+
+/**
+ * GeoJSON style configuration (v3.1.0)
+ * Supports static styles and choropleth (data-driven) coloring.
+ */
+export interface MapGeoJSONStyle {
+  /** Fill color (CSS color or choropleth config) */
+  fillColor?: string
+  /** Fill opacity (0-1, default: 0.6) */
+  fillOpacity?: number
+  /** Stroke color (default: '#333') */
+  strokeColor?: string
+  /** Stroke width (default: 1) */
+  strokeWeight?: number
+  /** Stroke opacity (0-1, default: 1) */
+  strokeOpacity?: number
+  /** Choropleth: property key for data-driven coloring */
+  choroplethField?: string
+  /** Choropleth: color scale stops [value, color][] sorted ascending */
+  choroplethScale?: Array<[number, string]>
+  /** Choropleth: color for features with missing/null values */
+  choroplethFallback?: string
+}
+
+/**
+ * Named GeoJSON layer for multi-layer maps (v3.1.0)
+ */
+export interface MapLayer {
+  /** Layer name (shown in layer control) */
+  name: string
+  /** Is this layer visible by default? */
+  visible?: boolean
+  /** GeoJSON FeatureCollection (inline or from API) */
+  geojson: unknown // GeoJSON.FeatureCollection — kept as unknown for zero-dep types
+  /** Per-layer style override */
+  style?: MapGeoJSONStyle
+  /** Per-layer popup config */
+  popup?: MapPopupConfig
+}
+
 /**
  * Map component parameters (Sprint 6)
- * Updated Sprint Ultimate U.2: Added clustering support
+ * Updated v3.1.0: GeoJSON, choropleth, popups, layers
  */
 export interface MapComponentParams {
   /**
@@ -776,7 +847,7 @@ export interface MapComponentParams {
   height?: string
 
   /**
-   * Auto-fit bounds to show all markers (default: false)
+   * Auto-fit bounds to show all markers/features (default: false)
    */
   fitBounds?: boolean
 
@@ -802,9 +873,6 @@ export interface MapComponentParams {
 
   /**
    * Enable marker clustering (Sprint Ultimate U.2)
-   * - true: Enable with default options
-   * - false: Disable clustering
-   * - MapClusterOptions: Enable with custom options
    */
   clustering?: boolean | MapClusterOptions
 
@@ -812,6 +880,77 @@ export interface MapComponentParams {
    * Custom CSS class (Sprint 7)
    */
   className?: string
+
+  // ─── GeoJSON (v3.1.0) ────────────────────
+
+  /**
+   * GeoJSON FeatureCollection to render on the map.
+   * Use this for polygons, lines, points from structured data.
+   */
+  geojson?: unknown // GeoJSON.FeatureCollection
+
+  /**
+   * Style for the GeoJSON layer.
+   * Supports static colors and choropleth (data-driven) coloring.
+   */
+  geojsonStyle?: MapGeoJSONStyle
+
+  /**
+   * Popup configuration for GeoJSON features.
+   * Shown on feature click.
+   */
+  popup?: MapPopupConfig
+
+  /**
+   * Named layers for multi-layer maps.
+   * Each layer has its own GeoJSON, style, and popup config.
+   * A Leaflet layer control is added when layers are present.
+   */
+  layers?: MapLayer[]
+
+  // ─── PMTiles (v3.1.0) ────────────────────
+
+  /**
+   * PMTiles vector tile source for large datasets (>5000 features).
+   * Requires protomaps-leaflet peer dependency.
+   * Pipeline: GeoParquet -> Tippecanoe -> PMTiles (static file on S3/CDN).
+   */
+  pmtiles?: MapPMTilesConfig
+}
+
+/**
+ * PMTiles configuration for large vector tile datasets (v3.1.0)
+ */
+export interface MapPMTilesConfig {
+  /** URL to the .pmtiles file (S3, CDN, local) */
+  url: string
+  /** Attribution text for this tile source */
+  attribution?: string
+  /** Style rules for vector features */
+  paintRules?: Array<{
+    /** Layer name in the PMTiles source */
+    dataLayer: string
+    /** Symbol type */
+    symbolizer: 'polygon' | 'line' | 'circle'
+    /** Fill/stroke color (CSS color or function name) */
+    color?: string
+    /** Stroke width */
+    width?: number
+    /** Fill opacity */
+    opacity?: number
+  }>
+  /** Label rules for text labels */
+  labelRules?: Array<{
+    dataLayer: string
+    /** Property key for label text */
+    textField: string
+    /** Font size */
+    fontSize?: number
+  }>
+  /** Max zoom level */
+  maxZoom?: number
+  /** Min zoom level */
+  minZoom?: number
 }
 
 /**