@morscherlab/mint-sdk 1.0.0-rc.2 → 1.0.0-rc.5

package/src/composables/useAutoGroup.ts

@@ -1,650 +1,496 @@
-import { ref, computed } from 'vue'
+import { computed, ref } from 'vue'
 import type {
+  AutoGroupResult,
+  ClassDisposition,
+  ClassSchema,
+  ColumnInfo,
+  ColumnRole,
   InputMode,
+  MergeSuggestion,
+  NumericBinning,
   OutlierAction,
   OutlierInfo,
-  ColumnInfo,
-  MetadataRow,
-  AutoGroupResult,
   ParsedCsvData,
+  SampleClass,
+  SchemaFingerprint,
+  ValueOps,
 } from '../types/auto-group'
-import type { SampleGroup } from '../types/components'
+import {
+  buildClassSchema,
+  classKey,
+  composeGroups,
+  composeTemplate,
+  detectClass,
+  expandGroupsWithReplicates,
+  findMerges,
+  pickPrimaryDelimiter,
+  preGroupReplicates,
+  restoreFingerprint,
+  serializeFingerprint,
+  splitMulti,
+  type ReplicatePreGrouping,
+  type TemplateOptions,
+} from './autoGroup'
 import { unwrapExperimentDesignData } from './experimentDesignData'
 
-export const DEFAULT_COLORS = [
-  '#3B82F6', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6',
-  '#EC4899', '#06B6D4', '#84CC16', '#F97316', '#6366F1',
-]
-
-const DELIMITER_CANDIDATES = ['_', '-', '.'] as const
+export { DEFAULT_COLORS } from './autoGroup'
 
-// --- Pure functions (exported for testing) ---
+let deprecationWarned = false
+let outlierDeprecationWarned = false
+function warnDeprecated(api: string) {
+  if (deprecationWarned) return
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') return
+  console.warn(
+    `[useAutoGroup] ${api} is deprecated; use the new class-first API (setClassDisposition / toggleGroupBy / setValueOps).`,
+  )
+  deprecationWarned = true
+}
 
-export function analyzeDelimiter(lines: string[]): {
-  delimiter: string
-  dominantFieldCount: number
-  minFieldCount: number
-  consistency: number
-} {
-  if (lines.length === 0) {
-    return { delimiter: '_', dominantFieldCount: 1, minFieldCount: 1, consistency: 0 }
-  }
+// Re-export `parseCSV` for callers that imported it from this file.
+export { parseCSV } from './autoGroup/csv-shim'
 
-  let bestDelimiter = '_'
-  let bestConsistency = -1
-  let bestFieldCount = 1
+export function useAutoGroup() {
+  const inputMode = ref<InputMode>('paste')
+  const rawText = ref('')
+  const csvData = ref<ParsedCsvData | null>(null)
+  const sampleTypeHints = ref<(string | undefined)[]>([])
 
-  for (const candidate of DELIMITER_CANDIDATES) {
-    const fieldCounts = lines.map(line => line.split(candidate).length)
-    const countFrequency = new Map<number, number>()
+  const classes = ref<SampleClass[]>([])
+  const schemas = ref<Record<string, ClassSchema>>({})
+  const activeClassKey = ref<string>('')
 
-    for (const count of fieldCounts) {
-      countFrequency.set(count, (countFrequency.get(count) ?? 0) + 1)
+  const samples = computed(() => {
+    if (csvData.value) {
+      return csvData.value.rows.map(r => r[csvData.value!.sampleColumn] ?? '')
     }
+    return rawText.value.split('\n').map(l => l.trim()).filter(l => l.length > 0)
+  })
 
-    // Find mode (most frequent field count)
-    let modeCount = 1
-    let modeFrequency = 0
-    for (const [count, freq] of countFrequency) {
-      if (freq > modeFrequency || (freq === modeFrequency && count > modeCount)) {
-        modeCount = count
-        modeFrequency = freq
-      }
-    }
+  const tokenized = ref<string[][]>([])
+  const delimiter = ref<'_' | '-' | '.'>('_')
+  // Replicate pre-grouping: strip injection-number / T<n> / B<n> / Rep<n> markers,
+  // collapse samples with the same base name into one "row" for tokenisation,
+  // then expand the resulting groups back to the original samples in `result`.
+  // null when the paste path hasn't run (CSV path keeps the old behaviour for now).
+  const preGrouping = ref<ReplicatePreGrouping | null>(null)
 
-    const rawConsistency = modeFrequency / lines.length
-    // A delimiter that produces field count 1 didn't actually split anything
-    const consistency = modeCount > 1 ? rawConsistency : 0
-
-    if (
-      consistency > bestConsistency ||
-      (consistency === bestConsistency &&
-        DELIMITER_CANDIDATES.indexOf(candidate) < DELIMITER_CANDIDATES.indexOf(bestDelimiter as typeof candidate))
-    ) {
-      bestDelimiter = candidate
-      bestConsistency = consistency
-      bestFieldCount = modeCount
+  function parseInput() {
+    if ((inputMode.value === 'csv' || inputMode.value === 'experiment') && csvData.value) {
+      parseInputFromCsv()
+      return
     }
+    parseInputFromPaste()
   }
 
-  const bestFieldCounts = lines.map(line => line.split(bestDelimiter).length)
-  const multiFieldCounts = bestFieldCounts.filter(c => c >= 2)
-  const minFieldCount = multiFieldCounts.length > 0 ? Math.min(...multiFieldCounts) : 1
-
-  return {
-    delimiter: bestDelimiter,
-    dominantFieldCount: bestFieldCount,
-    minFieldCount,
-    consistency: bestConsistency,
+  function parseInputFromCsv() {
+    // CSV input already exposes structured columns, so replicate pre-grouping
+    // isn't needed (and would interfere with header-aware role inference).
+    preGrouping.value = null
+    const csv = csvData.value!
+    const nonSampleCols = csv.columns.filter(c => c !== csv.sampleColumn && c !== 'sample_type')
+    if (nonSampleCols.length === 0) {
+      // No metadata columns — degenerate, single Unknown class
+      tokenized.value = csv.rows.map(() => [])
+      classes.value = [{
+        kind: 'unknown',
+        label: 'Unknown',
+        members: csv.rows.map((_, i) => i),
+        classTagPositions: [],
+        disposition: 'group',
+      }]
+      schemas.value = { unknown: { classKind: 'unknown', columns: [], groupBy: [] } }
+      activeClassKey.value = 'unknown'
+      return
+    }
+    const tokens = csv.rows.map(r => nonSampleCols.map(col => r[col] ?? ''))
+    tokenized.value = tokens
+    // Class detection: use explicit sample_type hint from csv.rows[i].sample_type
+    const hints = csv.rows.map(r => {
+      const t = String(r['sample_type'] ?? '').toLowerCase()
+      if (t === 'qc') return 'qc'
+      if (t === 'blank') return 'blank'
+      return undefined
+    })
+    const detected = detectClass(tokens, { sampleTypeHints: hints })
+    classes.value = detected
+    // Build schema per class with CSV header names
+    const newSchemas: Record<string, ClassSchema> = {}
+    for (const cls of detected) {
+      const memberTokens = cls.members.map(i => tokens[i])
+      const schema = buildClassSchema(memberTokens, cls.kind, cls.subKind, cls.classTagPositions)
+      // Override default Token N names with actual CSV header names
+      schema.columns = schema.columns.map((c, i) => ({
+        ...c,
+        name: nonSampleCols[i] ?? c.name,
+        originalName: nonSampleCols[i],
+      }))
+      newSchemas[classKey(cls)] = schema
+    }
+    schemas.value = newSchemas
+    if (detected.length > 0) activeClassKey.value = classKey(detected[0])
   }
-}
 
-export function detectOutliers(
-  lines: string[],
-  delimiter: string,
-  minFieldCount: number,
-): OutlierInfo[] {
-  const outliers: OutlierInfo[] = []
-
-  for (let i = 0; i < lines.length; i++) {
-    const fieldCount = lines[i].split(delimiter).length
-    if (fieldCount < minFieldCount) {
-      outliers.push({
-        sample: lines[i],
-        index: i,
-        fieldCount,
-        action: 'include',
-      })
+  function parseInputFromPaste() {
+    const lines = samples.value
+    if (lines.length === 0) {
+      classes.value = []
+      schemas.value = {}
+      preGrouping.value = null
+      return
+    }
+    // Replicate pre-pass: strip run-order / T<n> / B<n> / Rep<n> markers, then
+    // collapse samples whose stripped names match into one base entry. The
+    // tokenize → classify → schema pipeline runs on the *base* names; the
+    // `result` computed expands each resulting group back to the original
+    // samples via `expandGroupsWithReplicates`.
+    const pre = preGroupReplicates(lines)
+    preGrouping.value = pre
+
+    const d = pickPrimaryDelimiter(pre.baseNames)
+    delimiter.value = d
+    tokenized.value = pre.baseNames.map(l => splitMulti(l, d))
+    // sampleTypeHints align to original samples, so pick the first sample's
+    // hint per base group as the representative hint.
+    const hints = pre.membersByBase.map(members => sampleTypeHints.value[members[0]])
+    const detected = detectClass(tokenized.value, { sampleTypeHints: hints })
+    classes.value = detected
+    const newSchemas: Record<string, ClassSchema> = {}
+    for (const cls of detected) {
+      const memberTokens = cls.members.map(i => tokenized.value[i])
+      newSchemas[classKey(cls)] = buildClassSchema(
+        memberTokens,
+        cls.kind,
+        cls.subKind,
+        cls.classTagPositions,
+      )
+    }
+    schemas.value = newSchemas
+    if (detected.length > 0) {
+      activeClassKey.value = classKey(detected[0])
     }
   }
 
-  return outliers
-}
+  const activeSchema = computed<ClassSchema | null>(() => schemas.value[activeClassKey.value] ?? null)
 
-const QC_KEYWORDS = new Set([
-  'eqc', 'iqc', 'qc', 'blank', 'std', 'standard', 'test',
-])
-
-export function classifyOutlierAction(
-  sample: string,
-  delimiter: string,
-): OutlierAction {
-  const segments = sample.split(delimiter)
-  return segments.some(seg => QC_KEYWORDS.has(seg.toLowerCase()))
-    ? 'qc'
-    : 'include'
-}
-
-// A column is useful for grouping when it has more than one distinct value
-// AND it does not produce a unique value per row (which would create N
-// singleton groups instead of meaningful aggregation).
-export function isUsefulField(field: ColumnInfo, rowCount: number): boolean {
-  return field.cardinality > 1 && !(rowCount > 1 && field.cardinality === rowCount)
-}
-
-export function extractColumns(
-  samples: string[],
-  delimiter: string,
-  minFieldCount: number,
-): ColumnInfo[] {
-  if (samples.length === 0) return []
-
-  const suffixCount = minFieldCount - 1
-  const rows = samples.map(s => {
-    const parts = s.split(delimiter)
-    const splitAt = parts.length - suffixCount
-    return [
-      parts.slice(0, splitAt).join(delimiter),
-      ...parts.slice(splitAt),
-    ]
+  const suggestions = computed<MergeSuggestion[]>(() => {
+    const schema = activeSchema.value
+    if (!schema) return []
+    const activeClass = classes.value.find(
+      c => classKey(c) === activeClassKey.value,
+    )
+    if (!activeClass) return []
+    const memberTokens = activeClass.members.map(i => tokenized.value[i])
+    return findMerges(schema, memberTokens)
   })
 
-  const columnCount = minFieldCount
-  const columns: ColumnInfo[] = []
-  for (let col = 0; col < columnCount; col++) {
-    const values = rows.map(row => row[col])
-    const unique = [...new Set(values)]
-    columns.push({
-      index: col,
-      name: col === 0 ? 'Condition' : `Field ${col + 1}`,
-      uniqueValues: unique,
-      cardinality: unique.length,
-      type: col === 0 ? 'prefix' : 'suffix',
+  const result = computed<AutoGroupResult>(() => {
+    const pre = preGrouping.value
+    const composed = composeGroups({
+      tokenizedSamples: tokenized.value,
+      // After the pre-pass, sampleNames passed to compose are the *base* names
+      // (one per replicate group); fall back to the original samples when
+      // pre-grouping hasn't run (e.g. the CSV path or empty input).
+      sampleNames: pre ? pre.baseNames : samples.value,
+      schemas: schemas.value,
+      classes: classes.value,
     })
-  }
-
-  return columns
-}
-
-export function parseCSVLine(line: string, delimiter: string = ','): string[] {
-  const result: string[] = []
-  let current = ''
-  let inQuotes = false
-
-  for (let i = 0; i < line.length; i++) {
-    const char = line[i]
-    if (char === '"') {
-      inQuotes = !inQuotes
-    } else if (char === delimiter && !inQuotes) {
-      result.push(current.trim())
-      current = ''
-    } else {
-      current += char
+    if (!pre) return composed
+    // Expand each group's `samples` from base names back to the original
+    // sample names so the Preview panel shows real filenames, not stripped
+    // bases, and so `metadata` reflects each input row exactly once.
+    return {
+      ...composed,
+      groups: expandGroupsWithReplicates(composed.groups, pre),
+      experimentalGroups: composed.experimentalGroups
+        ? expandGroupsWithReplicates(composed.experimentalGroups, pre)
+        : undefined,
+      qcGroups: composed.qcGroups
+        ? expandGroupsWithReplicates(composed.qcGroups, pre)
+        : undefined,
     }
-  }
-  result.push(current.trim())
+  })
 
-  return result
-}
+  const fingerprint = computed<SchemaFingerprint>(() =>
+    serializeFingerprint(result.value.schemas ?? []),
+  )
 
-export function parseCSV(text: string): ParsedCsvData {
-  const lines = text.trim().split('\n')
-  if (lines.length < 2) {
-    throw new Error('CSV must have at least a header and one data row')
-  }
+  const groups = computed(() => result.value.groups)
+  const qcGroups = computed(() => result.value.qcGroups ?? [])
+  const metadata = computed(() => result.value.metadata)
+  const excludedSamples = computed(() => result.value.excludedSamples)
 
-  // Auto-detect delimiter: tab takes precedence if present in header
-  const firstLine = lines[0]
-  const csvDelimiter = firstLine.includes('\t') ? '\t' : ','
+  // ----- Mutators -----
 
-  const headers = parseCSVLine(firstLine, csvDelimiter)
-  const rows: Record<string, string>[] = []
+  function setClassDisposition(key: string, disposition: ClassDisposition) {
+    const target = classes.value.find(c => classKey(c) === key)
+    if (!target || target.disposition === disposition) return
+    classes.value = classes.value.map(c =>
+      classKey(c) === key ? { ...c, disposition } : c,
+    )
+  }
 
-  for (let i = 1; i < lines.length; i++) {
-    const values = parseCSVLine(lines[i], csvDelimiter)
-    if (values.length !== headers.length) continue
-    const row: Record<string, string> = {}
-    headers.forEach((header, idx) => {
-      row[header] = values[idx]
+  function setClassDispositions(
+    predicate: (c: SampleClass) => boolean,
+    disposition: ClassDisposition,
+  ) {
+    let changed = false
+    const next = classes.value.map(c => {
+      if (predicate(c) && c.disposition !== disposition) {
+        changed = true
+        return { ...c, disposition }
+      }
+      return c
     })
-    rows.push(row)
+    if (changed) classes.value = next
   }
 
-  // Auto-detect sample column
-  const sampleKeywords = ['sample', 'name', 'id', 'sample_name', 'samplename', 'file name', 'filename', 'file_name']
-  const sampleColumn =
-    headers.find(h => sampleKeywords.includes(h.toLowerCase())) ?? headers[0]
-
-  return { columns: headers, rows, sampleColumn, delimiter: csvDelimiter }
-}
-
-export function computeGroups(
-  allSamples: string[],
-  columns: ColumnInfo[],
-  enabledFields: Set<number>,
-  outlierActions: Map<number, OutlierAction>,
-  delimiter: string,
-  minFieldCount: number,
-): { groups: SampleGroup[]; metadata: MetadataRow[]; excludedSamples: string[] } {
-  const excludedSamples: string[] = []
-  const qcSamples: string[] = []
-  const conformingSamples: string[] = []
-
-  for (let i = 0; i < allSamples.length; i++) {
-    const action = outlierActions.get(i)
-    if (action === 'exclude') {
-      excludedSamples.push(allSamples[i])
-    } else if (action === 'qc') {
-      qcSamples.push(allSamples[i])
-    } else {
-      conformingSamples.push(allSamples[i])
+  function toggleGroupBy(key: string, idx: number) {
+    const schema = schemas.value[key]
+    if (!schema) return
+    const set = new Set(schema.groupBy)
+    if (set.has(idx)) set.delete(idx)
+    else set.add(idx)
+    schemas.value = {
+      ...schemas.value,
+      [key]: { ...schema, groupBy: [...set].sort((a, b) => a - b) },
     }
   }
 
-  // Build group map
-  const groupMap = new Map<string, string[]>()
-  const metadata: MetadataRow[] = []
-  const enabledIndices = [...enabledFields].sort((a, b) => a - b)
-
-  const suffixCount = minFieldCount - 1
-
-  for (const sample of conformingSamples) {
-    const parts = sample.split(delimiter)
-    const splitAt = Math.max(1, parts.length - suffixCount)
-    const row = [
-      parts.slice(0, splitAt).join(delimiter),
-      ...parts.slice(splitAt),
-    ]
-
-    // Build group key from enabled columns
-    const keyParts: string[] = []
-    for (const idx of enabledIndices) {
-      if (idx < row.length && idx < columns.length) {
-        keyParts.push(row[idx])
+  function updateColumn(key: string, idx: number, patch: Partial<ColumnInfo>) {
+    const schema = schemas.value[key]
+    if (!schema) return
+    const col = schema.columns.find(c => c.index === idx)
+    if (!col) return
+    let changed = false
+    for (const k of Object.keys(patch) as (keyof ColumnInfo)[]) {
+      if ((col as unknown as Record<string, unknown>)[k as string] !== (patch as unknown as Record<string, unknown>)[k as string]) {
+        changed = true
+        break
       }
     }
-    const groupKey = keyParts.join(' / ')
-
-    const group = groupMap.get(groupKey)
-    if (group) {
-      group.push(sample)
-    } else {
-      groupMap.set(groupKey, [sample])
+    if (!changed) return
+    schemas.value = {
+      ...schemas.value,
+      [key]: {
+        ...schema,
+        columns: schema.columns.map(c => (c.index === idx ? { ...c, ...patch } : c)),
+      },
     }
-
-    // Build metadata row with ALL columns
-    const fields: Record<string, string> = {}
-    for (const col of columns) {
-      if (col.index < row.length) {
-        fields[col.name] = row[col.index]
-      }
-    }
-    metadata.push({ sampleName: sample, fields, group: groupKey })
   }
 
-  // Convert to SampleGroup[]
-  const groups: SampleGroup[] = []
-  let colorIdx = 0
-  for (const [name, samples] of groupMap) {
-    groups.push({
-      name,
-      color: DEFAULT_COLORS[colorIdx % DEFAULT_COLORS.length],
-      samples,
-    })
-    colorIdx++
+  function setRole(key: string, idx: number, role: ColumnRole) {
+    updateColumn(key, idx, { role })
   }
 
-  // QC group
-  if (qcSamples.length > 0) {
-    groups.push({
-      name: 'QC',
-      color: '#6B7280',
-      samples: qcSamples,
-    })
-    for (const sample of qcSamples) {
-      metadata.push({ sampleName: sample, fields: {}, group: 'QC' })
-    }
+  function setColumnName(key: string, idx: number, name: string) {
+    updateColumn(key, idx, { displayName: name })
   }
 
-  return { groups, metadata, excludedSamples }
-}
-
-/**
- * Extract sample metadata from raw design_data into ParsedCsvData format.
- *
- * Looks for a `samples` array in the design data. For each sample, merges
- * the `conditions` dict (the metadata table) with the `sample_name` to
- * produce a flat tabular row. QC and blank samples are filtered out by
- * their explicit `sample_type` field.
- *
- * Returns null if no samples with conditions are found.
- */
-export function extractSamplesFromDesignData(
-  rawData: Record<string, unknown>,
-): ParsedCsvData | null {
-  const designData = unwrapExperimentDesignData(rawData)
-  if (!designData) return null
-
-  const samples = designData.samples
-  if (!Array.isArray(samples) || samples.length === 0) return null
-
-  // Single pass: filter QC/blank and collect all condition keys
-  const allConditionKeys: string[] = []
-  const keySet = new Set<string>()
-  const filteredSamples: Record<string, unknown>[] = []
-
-  for (const sample of samples) {
-    const sampleType = String((sample as Record<string, unknown>).sample_type ?? 'sample').toLowerCase()
-    if (sampleType === 'qc' || sampleType === 'blank') continue
-
-    filteredSamples.push(sample as Record<string, unknown>)
-    const conditions = (sample as Record<string, unknown>).conditions as Record<string, string> | undefined
-    if (conditions && typeof conditions === 'object') {
-      for (const key of Object.keys(conditions)) {
-        if (!keySet.has(key)) {
-          keySet.add(key)
-          allConditionKeys.push(key)
-        }
-      }
-    }
+  function setValueOps(key: string, idx: number, ops: ValueOps) {
+    updateColumn(key, idx, { ops })
   }
 
-  if (filteredSamples.length === 0 || allConditionKeys.length === 0) return null
-
-  const columns = ['sample_name', ...allConditionKeys]
-  const rows: Record<string, string>[] = filteredSamples.map((sample) => {
-    const conditions = (sample.conditions as Record<string, string>) ?? {}
-    const row: Record<string, string> = {
-      sample_name: String(sample.sample_name ?? ''),
-    }
-    for (const key of allConditionKeys) {
-      row[key] = conditions[key] ?? ''
-    }
-    return row
-  })
-
-  return { columns, rows, sampleColumn: 'sample_name', delimiter: ',' }
-}
+  function setBinning(key: string, idx: number, binning: NumericBinning) {
+    updateColumn(key, idx, { binning })
+  }
 
-export function computeGroupsFromCsv(
-  csvData: ParsedCsvData,
-  columns: ColumnInfo[],
-  enabledFields: Set<number>,
-): { groups: SampleGroup[]; metadata: MetadataRow[]; excludedSamples: string[] } {
-  const groupMap = new Map<string, string[]>()
-  const metadata: MetadataRow[] = []
-  const enabledCols = columns
-    .filter(c => enabledFields.has(c.index))
-    .sort((a, b) => a.index - b.index)
-
-  for (const row of csvData.rows) {
-    const sampleName = row[csvData.sampleColumn]
-
-    // Build group key from enabled CSV column values
-    // Use originalName for CSV row lookup (survives user renames), display name for group key
-    const keyParts = enabledCols.map(col => row[col.originalName ?? col.name])
-    const groupKey = keyParts.join(' / ')
-
-    const group = groupMap.get(groupKey)
-    if (group) {
-      group.push(sampleName)
-    } else {
-      groupMap.set(groupKey, [sampleName])
+  function mergeColumns(key: string, indices: number[]) {
+    const schema = schemas.value[key]
+    if (!schema || indices.length < 2) return
+    const sorted = [...indices].sort((a, b) => a - b)
+    const start = sorted[0]
+    const merged: ColumnInfo = {
+      index: start,
+      name: `Column ${sorted.map(i => i + 1).join('–')}`,
+      sourceIndices: sorted.flatMap(i => schema.columns.find(c => c.index === i)?.sourceIndices ?? [i]),
+      uniqueValues: [],
+      cardinality: 0,
+      role: 'factor',
     }
-
-    // Build metadata row with ALL columns — use display name as key, original for lookup
-    const fields: Record<string, string> = {}
-    for (const col of columns) {
-      fields[col.name] = row[col.originalName ?? col.name]
+    const dropped = new Set(sorted)
+    schemas.value = {
+      ...schemas.value,
+      [key]: {
+        ...schema,
+        columns: [merged, ...schema.columns.filter(c => !dropped.has(c.index))]
+          .sort((a, b) => a.index - b.index),
+        groupBy: schema.groupBy.filter(i => !dropped.has(i) || i === start),
+      },
     }
-    metadata.push({ sampleName, fields, group: groupKey })
   }
 
-  // Convert to SampleGroup[]
-  const groups: SampleGroup[] = []
-  let colorIdx = 0
-  for (const [name, samples] of groupMap) {
-    groups.push({
-      name,
-      color: DEFAULT_COLORS[colorIdx % DEFAULT_COLORS.length],
-      samples,
-    })
-    colorIdx++
+  function loadFingerprint(fp: SchemaFingerprint) {
+    const restored = restoreFingerprint(fp, Object.values(schemas.value))
+    const next: Record<string, ClassSchema> = {}
+    for (const s of restored) next[classKey({ kind: s.classKind, subKind: s.subKind })] = s
+    schemas.value = next
   }
 
-  return { groups, metadata, excludedSamples: [] }
-}
-
-// --- Reactive composable ---
-
-/** Parses sample names or CSV data to propose group assignments with outlier detection and preview. */
-export function useAutoGroup() {
-  const inputMode = ref<InputMode>('paste')
-  const rawText = ref('')
-  const csvData = ref<ParsedCsvData | null>(null)
-  const delimiter = ref('_')
-  const dominantFieldCount = ref(1)
-  const minFieldCount = ref(1)
-  const outliers = ref<OutlierInfo[]>([])
-  const fields = ref<ColumnInfo[]>([])
-  const fieldNames = ref<Record<number, string>>({})
-  const enabledFields = ref(new Set<number>())
-
-  const isTabularMode = computed(() =>
-    (inputMode.value === 'csv' || inputMode.value === 'experiment') && csvData.value !== null,
-  )
-
-  const samples = computed(() => {
-    const data = csvData.value
-    if (isTabularMode.value && data) {
-      return data.rows.map(r => r[data.sampleColumn])
-    }
-    return rawText.value
-      .split('\n')
-      .map(l => l.trim())
-      .filter(l => l.length > 0)
-  })
-
-  const hasOutliers = computed(() => outliers.value.length > 0)
-
-  const conformingSamples = computed(() => {
-    const outlierIndices = new Set(outliers.value.map(o => o.index))
-    return samples.value.filter((_, i) => !outlierIndices.has(i))
-  })
-
-  const outlierActions = computed(() => {
-    const map = new Map<number, OutlierAction>()
-    for (const o of outliers.value) {
-      map.set(o.index, o.action)
-    }
-    return map
-  })
-
-  const effectiveColumns = computed(() => {
-    return fields.value.map(col => ({
-      ...col,
-      name: fieldNames.value[col.index] ?? col.name,
-    }))
-  })
-
-  const _computedResult = computed((): AutoGroupResult => {
-    if (effectiveColumns.value.length === 0 || enabledFields.value.size === 0) {
-      return { groups: [], metadata: [], excludedSamples: [] }
-    }
+  // ----- Template download -----
 
-    if (isTabularMode.value && csvData.value) {
-      return computeGroupsFromCsv(
-        csvData.value,
-        effectiveColumns.value,
-        enabledFields.value,
-      )
-    }
+  const canDownloadTemplate = computed(() => samples.value.length > 0)
 
-    return computeGroups(
+  function downloadTemplate(mode: 'blank' | 'prefilled' = 'prefilled', format: 'csv' | 'tsv' = 'csv') {
+    const { content, filename } = composeTemplate(
       samples.value,
-      effectiveColumns.value,
-      enabledFields.value,
-      outlierActions.value,
-      delimiter.value,
-      minFieldCount.value,
+      mode === 'prefilled' ? Object.values(schemas.value) : null,
+      mode === 'prefilled' ? classes.value : null,
+      { mode, format, tokenizedSamples: tokenized.value },
     )
-  })
-
-  const groups = computed(() => _computedResult.value.groups)
-  const metadata = computed(() => _computedResult.value.metadata)
-  const excludedSamples = computed(() => _computedResult.value.excludedSamples)
-
-  const allSingletons = computed(() =>
-    groups.value.length > 1 && groups.value.every(g => g.samples.length === 1),
-  )
-
-  const result = _computedResult
-
-  function parseInput() {
-    if (isTabularMode.value) {
-      parseCsvInput()
-    } else {
-      parsePasteInput()
-    }
+    const blob = new Blob([content], { type: format === 'tsv' ? 'text/tab-separated-values' : 'text/csv' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = filename
+    document.body.appendChild(a)
+    a.click()
+    document.body.removeChild(a)
+    URL.revokeObjectURL(url)
   }
 
-  function parsePasteInput() {
-    const lines = samples.value
-    if (lines.length === 0) return
-
-    const analysis = analyzeDelimiter(lines)
-    delimiter.value = analysis.delimiter
-    dominantFieldCount.value = analysis.dominantFieldCount
-
-    // Use dominantFieldCount as outlier threshold so QC/test samples with
-    // fewer fields than the majority are correctly flagged
-    outliers.value = detectOutliers(lines, analysis.delimiter, analysis.dominantFieldCount)
-
-    // Apply smart default actions: auto-classify QC/test samples
-    for (const outlier of outliers.value) {
-      outlier.action = classifyOutlierAction(outlier.sample, analysis.delimiter)
-    }
-
-    const conforming = lines.filter(
-      (_, i) => !outliers.value.some(o => o.index === i)
-    )
-
-    // Recompute minFieldCount from conforming samples only
-    const conformingFieldCounts = conforming.map(s => s.split(analysis.delimiter).length)
-    minFieldCount.value = conformingFieldCounts.length > 0
-      ? Math.min(...conformingFieldCounts)
-      : analysis.dominantFieldCount
-
-    fields.value = extractColumns(conforming, analysis.delimiter, minFieldCount.value)
-
-    fieldNames.value = {}
-    const rowCount = conforming.length
-    enabledFields.value = new Set(
-      fields.value.filter(f => isUsefulField(f, rowCount)).map(f => f.index),
+  /** Test seam — exposes the template content/filename without triggering a browser download. */
+  function composeTemplateForTest(opts: Pick<TemplateOptions, 'mode' | 'format'>) {
+    return composeTemplate(
+      samples.value,
+      opts.mode === 'prefilled' ? Object.values(schemas.value) : null,
+      opts.mode === 'prefilled' ? classes.value : null,
+      { ...opts, tokenizedSamples: tokenized.value },
     )
   }
 
-  function parseCsvInput() {
-    if (!csvData.value) return
-
-    const csv = csvData.value
-    const nonSampleCols = csv.columns.filter(c => c !== csv.sampleColumn)
-
-    fields.value = nonSampleCols.map((col, i) => {
-      const values = csv.rows.map(r => r[col])
-      const unique = [...new Set(values)]
-      return {
-        index: i,
-        name: col,
-        originalName: col,
-        uniqueValues: unique,
-        cardinality: unique.length,
-      }
-    })
+  // ----- Legacy public refs and shims -----
 
-    // For CSV, no outliers
-    outliers.value = []
-    delimiter.value = csv.delimiter
-    dominantFieldCount.value = csv.columns.length
-
-    fieldNames.value = Object.fromEntries(fields.value.map(f => [f.index, f.name]))
-    const rowCount = csv.rows.length
-    enabledFields.value = new Set(
-      fields.value.filter(f => isUsefulField(f, rowCount)).map(f => f.index),
-    )
-  }
+  const outliers = ref<OutlierInfo[]>([])
+  const hasOutliers = computed(() => outliers.value.length > 0)
+  const conformingSamples = computed(() => samples.value)
+  const dominantFieldCount = computed(() => tokenized.value[0]?.length ?? 0)
+  const minFieldCount = computed(() => {
+    if (tokenized.value.length === 0) return 0
+    return Math.min(...tokenized.value.map(t => t.length))
+  })
+  const fields = computed(() => activeSchema.value?.columns ?? [])
+  const fieldNames = computed<Record<number, string>>(() => {
+    const out: Record<number, string> = {}
+    for (const c of fields.value) out[c.index] = c.displayName ?? c.name
+    return out
+  })
+  const enabledFields = computed<Set<number>>(() =>
+    activeSchema.value ? new Set(activeSchema.value.groupBy) : new Set(),
+  )
+  const effectiveColumns = fields
+  const allSingletons = computed(
+    () => groups.value.length > 1 && groups.value.every(g => g.samples.length === 1),
+  )
 
-  function setOutlierAction(index: number, action: OutlierAction) {
-    const outlier = outliers.value.find(o => o.index === index)
-    if (outlier) {
-      outlier.action = action
-      // Trigger reactivity
-      outliers.value = [...outliers.value]
+  function setOutlierAction(_: number, __: OutlierAction) {
+    if (!outlierDeprecationWarned) {
+      if (typeof process === 'undefined' || process.env?.NODE_ENV !== 'production') {
+        console.warn(
+          `[useAutoGroup] setOutlierAction is deprecated AND inactive in the class-first redesign. ` +
+          `Use setClassDisposition('iqc' | 'eqc' | …, 'group' | 'overlay' | 'exclude') instead.`,
+        )
+        outlierDeprecationWarned = true
+      }
     }
   }
 
-  function setAllOutlierActions(action: OutlierAction) {
-    for (const outlier of outliers.value) {
-      outlier.action = action
+  function setAllOutlierActions(__: OutlierAction) {
+    if (!outlierDeprecationWarned) {
+      if (typeof process === 'undefined' || process.env?.NODE_ENV !== 'production') {
+        console.warn(
+          `[useAutoGroup] setAllOutlierActions is deprecated AND inactive in the class-first redesign. ` +
+          `Use setClassDisposition('iqc' | 'eqc' | …, 'group' | 'overlay' | 'exclude') instead.`,
+        )
+        outlierDeprecationWarned = true
+      }
     }
-    outliers.value = [...outliers.value]
   }
 
   function toggleField(index: number) {
-    const newSet = new Set(enabledFields.value)
-    if (newSet.has(index)) {
-      newSet.delete(index)
-    } else {
-      newSet.add(index)
-    }
-    enabledFields.value = newSet
+    warnDeprecated('toggleField')
+    if (activeClassKey.value) toggleGroupBy(activeClassKey.value, index)
   }
 
   function renameField(index: number, name: string) {
-    fieldNames.value = { ...fieldNames.value, [index]: name }
+    warnDeprecated('renameField')
+    if (activeClassKey.value) setColumnName(activeClassKey.value, index, name)
   }
 
   function loadExperimentData(rawData: Record<string, unknown>): boolean {
     const parsed = extractSamplesFromDesignData(rawData)
     if (!parsed) return false
-
     inputMode.value = 'experiment'
     csvData.value = parsed
-    parseCsvInput()
+    sampleTypeHints.value = parsed.sampleTypeHints
+    parseInput()
     return true
   }
 
   function reset() {
     rawText.value = ''
     csvData.value = null
-    delimiter.value = '_'
-    dominantFieldCount.value = 1
-    minFieldCount.value = 1
+    classes.value = []
+    schemas.value = {}
+    activeClassKey.value = ''
+    tokenized.value = []
     outliers.value = []
-    fields.value = []
-    fieldNames.value = {}
-    enabledFields.value = new Set()
+    sampleTypeHints.value = []
   }
 
   return {
     // State
-    inputMode,
-    rawText,
-    csvData,
-    delimiter,
-    dominantFieldCount,
-    minFieldCount,
-    outliers,
-    fields,
-    fieldNames,
-    enabledFields,
+    inputMode, rawText, csvData, sampleTypeHints,
+    classes, schemas, activeClassKey,
+    delimiter, dominantFieldCount, minFieldCount,
     // Computed
-    samples,
-    hasOutliers,
-    conformingSamples,
-    groups,
-    metadata,
-    excludedSamples,
-    allSingletons,
-    result,
-    effectiveColumns,
+    samples, tokenized, activeSchema, suggestions,
+    groups, qcGroups, metadata, excludedSamples, result, fingerprint,
+    fields, fieldNames, enabledFields, effectiveColumns,
+    hasOutliers, outliers, conformingSamples, allSingletons,
+    canDownloadTemplate,
+    // Mutators
+    setClassDisposition, setClassDispositions, toggleGroupBy, setRole, setColumnName, setValueOps, setBinning,
+    mergeColumns, loadFingerprint,
     // Actions
-    parseInput,
-    loadExperimentData,
-    setOutlierAction,
-    setAllOutlierActions,
-    toggleField,
-    renameField,
-    reset,
+    parseInput, downloadTemplate, composeTemplateForTest, loadExperimentData, reset,
+    // Deprecated shims
+    setOutlierAction, setAllOutlierActions, toggleField, renameField,
+  }
+}
+
+export function extractSamplesFromDesignData(
+  rawData: Record<string, unknown>,
+): (ParsedCsvData & { sampleTypeHints: (string | undefined)[] }) | null {
+  const designData = unwrapExperimentDesignData(rawData)
+  if (!designData) return null
+  const samples = designData.samples
+  if (!Array.isArray(samples) || samples.length === 0) return null
+  const allConditionKeys: string[] = []
+  const keySet = new Set<string>()
+  const sampleTypeHints: (string | undefined)[] = []
+  for (const sample of samples) {
+    const rawType = (sample as Record<string, unknown>).sample_type
+    sampleTypeHints.push(typeof rawType === 'string' ? rawType.toLowerCase() : undefined)
+    const conditions = (sample as Record<string, unknown>).conditions as Record<string, string> | undefined
+    if (conditions && typeof conditions === 'object') {
+      for (const key of Object.keys(conditions)) {
+        if (!keySet.has(key)) {
+          keySet.add(key)
+          allConditionKeys.push(key)
+        }
+      }
+    }
   }
+  if (allConditionKeys.length === 0) return null
+  const columns = ['sample_name', ...allConditionKeys, 'sample_type']
+  const rows = (samples as Record<string, unknown>[]).map(s => {
+    const conditions = (s.conditions as Record<string, string>) ?? {}
+    const row: Record<string, string> = {
+      sample_name: String(s.sample_name ?? ''),
+      sample_type: String(s.sample_type ?? 'sample'),
+    }
+    for (const key of allConditionKeys) row[key] = conditions[key] ?? ''
+    return row
+  })
+  return { columns, rows, sampleColumn: 'sample_name', delimiter: ',', sampleTypeHints }
 }