@morscherlab/mint-sdk 1.0.39 → 1.0.42

package/src/composables/autoGroup/compose.ts

@@ -7,6 +7,7 @@ import type {
   SampleClass,
 } from '../../types/auto-group'
 import type { SampleGroup } from '../../types/components'
+import type { TreeNode } from '../../types/componentLabTypes'
 import { DEFAULT_COLORS, QC_OVERLAY_COLOR } from './colors'
 import { classKey } from './classKey'
 
@@ -66,6 +67,14 @@ export function composeGroups(input: ComposeInput): AutoGroupResult {
   const metadata: MetadataRow[] = []
   let colorIdx = 0
 
+  // Nested hierarchy (class → groupBy levels → sample leaves) built alongside
+  // the flat groups. `treeIndex` lets repeated members reuse the same path node.
+  // PATH_SEP is a control char so it never collides with a real token value.
+  const PATH_SEP = String.fromCharCode(1)
+  const groupTree: TreeNode[] = []
+  const treeIndex = new Map<string, TreeNode>()
+  let treeColorIdx = 0
+
   for (const cls of input.classes) {
     const schema = input.schemas[classKey(cls)]
     if (!schema) continue
@@ -80,6 +89,12 @@ export function composeGroups(input: ComposeInput): AutoGroupResult {
     const groupMap = new Map<string, { name: string; samples: string[] }>()
     const colByIdx = new Map(schema.columns.map(c => [c.index, c]))
 
+    // Only experimental (group) classes form the nested tree; overlay/QC stay flat.
+    const buildsTree = cls.disposition === 'group'
+    const runCol = schema.columns.find(c => c.role === 'run-order')
+    const classNodeId = classKey(cls)
+    let classNode: TreeNode | null = null
+
     for (const m of cls.members) {
       const tokens = input.tokenizedSamples[m]
       const rowName = input.sampleNames[m]
@@ -143,6 +158,46 @@ export function composeGroups(input: ComposeInput): AutoGroupResult {
       }
 
       metadata.push({ sampleName: rowName, fields: fieldValues, group: groupKey })
+
+      // Grow the nested tree: class root → one node per groupBy column → leaf.
+      if (buildsTree) {
+        if (!classNode) {
+          classNode = {
+            id: classNodeId,
+            label: cls.label,
+            badge: 0,
+            children: [],
+            metadata: { color: DEFAULT_COLORS[treeColorIdx++ % DEFAULT_COLORS.length] },
+          }
+          treeIndex.set(classNodeId, classNode)
+          groupTree.push(classNode)
+        }
+        classNode.badge = (classNode.badge as number) + 1
+        let cursor = classNode
+        let pathId = classNodeId
+        // Reuse the already-computed groupBy values (`keyParts`) so the tree
+        // levels can never drift from the flat group key.
+        for (const val of keyParts) {
+          pathId += PATH_SEP + val
+          let node = treeIndex.get(pathId)
+          if (!node) {
+            node = { id: pathId, label: val, badge: 0, children: [] }
+            cursor.children!.push(node)
+            treeIndex.set(pathId, node)
+          }
+          node.badge = (node.badge as number) + 1
+          cursor = node
+        }
+        // Injection value goes through the column's op pipeline (alias/exclude)
+        // via `fieldValues`, matching what every other surface shows.
+        const injection = runCol ? fieldValues[runCol.displayName ?? runCol.name] : undefined
+        const leaf: TreeNode = { id: pathId + PATH_SEP + rowName, label: rowName, type: 'sample' }
+        if (injection) {
+          leaf.badge = injection
+          leaf.metadata = { injection }
+        }
+        cursor.children!.push(leaf)
+      }
     }
 
     for (const { name, samples } of groupMap.values()) {
@@ -163,5 +218,6 @@ export function composeGroups(input: ComposeInput): AutoGroupResult {
     metadata,
     excludedSamples,
     schemas: Object.values(input.schemas),
+    groupTree,
   }
 }

package/src/composables/autoGroup/fingerprint.ts

@@ -6,6 +6,7 @@ export function serializeFingerprint(schemas: ClassSchema[]): SchemaFingerprint
     classes: schemas.map(s => ({
       kind: s.classKind,
       subKind: s.subKind,
+      tokenLength: s.tokenLength,
       columns: s.columns.map(c => ({
         name: c.displayName ?? c.name,
         role: c.role ?? 'factor',
@@ -23,7 +24,20 @@ export function restoreFingerprint(
   current: ClassSchema[],
 ): ClassSchema[] {
   return fp.classes.map(snap => {
-    const target = current.find(c => c.classKind === snap.kind && c.subKind === snap.subKind)
+    // Match on token length too when the snapshot carries one, so length-split
+    // classes sharing a (kind, subKind) restore to the right schema. Snapshots
+    // saved before token-length splitting have no `tokenLength`; for those we
+    // match on (kind, subKind) and prefer the candidate with the same column
+    // count, so an old single-class fingerprint lands on the compatible split
+    // instead of throwing on the first (wrong-arity) hit.
+    const candidates = current.filter(
+      c =>
+        c.classKind === snap.kind &&
+        c.subKind === snap.subKind &&
+        (snap.tokenLength == null || c.tokenLength === snap.tokenLength),
+    )
+    const target =
+      candidates.find(c => c.columns.length === snap.columns.length) ?? candidates[0]
     if (!target) {
       throw new Error(
         `Fingerprint class not present in current input: ${snap.kind}${snap.subKind ? '/' + snap.subKind : ''}`,

package/src/composables/autoGroup/index.ts

@@ -16,5 +16,7 @@ export {
   stripReplicateTokens,
   preGroupReplicates,
   expandGroupsWithReplicates,
+  expandTreeWithReplicates,
 } from './replicatePreGroup'
 export type { ReplicatePreGrouping } from './replicatePreGroup'
+export { splitByTokenLength } from './tokenLength'

package/src/composables/autoGroup/replicatePreGroup.ts

@@ -11,6 +11,7 @@
  * before tokenisation removes a class of fragile cardinality heuristics.
  */
 
+import type { TreeNode } from '../../types/componentLabTypes'
 import vocabData from './vocab.json'
 
 const STRIP_PATTERNS: RegExp[] = (vocabData.replicateStripPatterns as string[]).map(
@@ -88,3 +89,36 @@ export function expandGroupsWithReplicates<G extends { samples: string[] }>(
     }),
   }))
 }
+
+/**
+ * Expand a group hierarchy (built over base names) back to original samples.
+ * Each leaf node's `label` is a base name; it is replaced by one leaf per
+ * original sample that collapsed onto it (sharing the leaf's injection badge,
+ * since collapsed replicates have identical base tokens). Every ancestor's
+ * `badge` (sample count) is recomputed from the expanded leaf count so the tree
+ * agrees with the flat groups produced by `expandGroupsWithReplicates`.
+ */
+export function expandTreeWithReplicates(
+  nodes: TreeNode[],
+  preGrouping: ReplicatePreGrouping,
+): TreeNode[] {
+  const baseToOriginals = new Map<string, string[]>()
+  for (let i = 0; i < preGrouping.baseNames.length; i++) {
+    baseToOriginals.set(
+      preGrouping.baseNames[i],
+      preGrouping.membersByBase[i].map(m => preGrouping.originalSamples[m]),
+    )
+  }
+  const leafCount = (n: TreeNode): number =>
+    n.children && n.children.length ? n.children.reduce((acc, c) => acc + leafCount(c), 0) : 1
+  const expand = (node: TreeNode): TreeNode[] => {
+    if (node.children && node.children.length) {
+      const children = node.children.flatMap(expand)
+      return [{ ...node, children, badge: children.reduce((acc, c) => acc + leafCount(c), 0) }]
+    }
+    const originals = baseToOriginals.get(node.label)
+    if (!originals || originals.length === 0) return [node]
+    return originals.map((name, k) => ({ ...node, id: `${node.id}
${k}`, label: name }))
+  }
+  return nodes.flatMap(expand)
+}

package/src/composables/autoGroup/template.ts

@@ -62,14 +62,14 @@ export function composeTemplate(
 
   const schemaByKey = new Map<string, ClassSchema>()
   for (const s of schemas) {
-    const k = s.subKind ? `${s.classKind}:${s.subKind}` : s.classKind
+    const k = classKey({ kind: s.classKind, subKind: s.subKind, tokenLength: s.tokenLength })
     schemaByKey.set(k, s)
   }
 
   const colByNameByKey = new Map<string, Map<string, ColumnInfo>>()
   const groupBySetByKey = new Map<string, Set<number>>()
   for (const s of schemas) {
-    const k = s.subKind ? `${s.classKind}:${s.subKind}` : s.classKind
+    const k = classKey({ kind: s.classKind, subKind: s.subKind, tokenLength: s.tokenLength })
     const m = new Map<string, ColumnInfo>()
     for (const c of s.columns) m.set(c.displayName ?? c.name, c)
     colByNameByKey.set(k, m)

package/src/composables/autoGroup/tokenLength.ts

@@ -0,0 +1,53 @@
+import type { SampleClass } from '../../types/auto-group'
+
+/**
+ * Token-length pre-grouping.
+ *
+ * After type classification (`detectClass`), members of one class can still have
+ * different token counts — e.g. a Plasma batch where some names carry an extra
+ * descriptor field. Splitting each class so every member shares the same token
+ * length is the "group same token-length sample, then extract tokens inside the
+ * group" step: it guarantees `buildClassSchema` sees a rectangular token matrix,
+ * so column index N means the same field for every sample in the group.
+ *
+ * Each output class carries `tokenLength`; `classKey` folds that into the schema
+ * key so length-split classes never collide. The label only gains a `· N fields`
+ * suffix when a (kind, subKind) genuinely spans more than one length, keeping the
+ * common (uniform) case visually identical to before.
+ */
+export function splitByTokenLength(
+  classes: SampleClass[],
+  tokenized: string[][],
+): SampleClass[] {
+  const out: SampleClass[] = []
+
+  for (const cls of classes) {
+    // Bucket members by token count, preserving first-seen order of lengths.
+    const byLength = new Map<number, number[]>()
+    const lengthOrder: number[] = []
+    for (const m of cls.members) {
+      const len = tokenized[m]?.length ?? 0
+      const bucket = byLength.get(len)
+      if (bucket) {
+        bucket.push(m)
+      } else {
+        byLength.set(len, [m])
+        lengthOrder.push(len)
+      }
+    }
+
+    const multipleLengths = lengthOrder.length > 1
+    for (const len of lengthOrder) {
+      out.push({
+        ...cls,
+        members: byLength.get(len)!,
+        tokenLength: len,
+        // Drop class-tag positions that fall outside this split's token range.
+        classTagPositions: cls.classTagPositions.filter(p => p < len),
+        label: multipleLengths ? `${cls.label} · ${len} fields` : cls.label,
+      })
+    }
+  }
+
+  return out
+}

package/src/composables/autoGroup/vocab.json

@@ -7,7 +7,7 @@
     "matrixVocab": "Lowercase token → canonical display name. Tokens are normalised to lowercase before lookup, so adding 'tissues' handles 'Tissues' / 'TISSUES' / 'tissues' uniformly. Multiple aliases map to one canonical (e.g. cell + cells → Cells).",
     "ionizationModes": "Lowercase polarity tokens (pos / positive / neg / negative). Suffixed to the subKind so POS and NEG acquisitions get independent schemas.",
     "tissueParentTokens": "Tokens that flag the immediately-following token as the organ subKind (so `tissues / kidney` becomes Biological/Tissues, tagging both positions).",
-    "replicateStripPatterns": "Regex sources stripped from each sample name during the replicate pre-grouping pass. Samples whose stripped (base) names match are treated as replicates of one another and grouped together before tokenisation. Default set covers: trailing run-order numbers, _T<n>, _B<n>, and _Rep<n> markers."
+    "replicateStripPatterns": "Regex sources stripped from each sample name during the replicate pre-grouping pass. Samples whose stripped (base) names match are treated as replicates of one another and grouped together before tokenisation. Default set covers _T<n>, _B<n>, and _Rep<n> markers. The trailing injection / run-order number is intentionally NOT stripped here — it survives tokenisation and is surfaced as a 'run-order' column (named 'Injection #'), then excluded from the default group key so replicates still collapse."
   },
 
   "patterns": {
@@ -59,7 +59,6 @@
   "tissueParentTokens": ["tissue", "tissues"],
 
   "replicateStripPatterns": [
-    "[_-]\\d{2,4}[A-Za-z]?$",
     "[_-]T\\d+(?=[_-]|$)",
     "[_-]B\\d+(?=[_-]|$)",
     "[_-](?:rep(?:licate)?)\\d+(?=[_-]|$)"

package/src/composables/index.ts

@@ -445,6 +445,7 @@ export {
   resolvePluginBaseUrl,
   uploadPluginEndpoint,
   usePluginClient,
+  usePluginEventStream,
   usePluginSettings,
   useCurrentExperiment,
   type BuildPluginEndpointUrlOptions,
@@ -456,9 +457,14 @@ export {
   type PluginHttpMethod,
   type PluginNavItemContract,
   type PluginEndpointRequestOptions,
+  type PluginEventStreamMessage,
+  type PluginEventStreamOptions,
   type PluginFormDataPayload,
   type PluginFormDataValue,
   type CreatePluginClientOptions,
   type UseCurrentExperimentOptions,
   type UseCurrentExperimentReturn,
+  type UsePluginEventStreamReturn,
+  type UsePluginSettingsOptions,
+  type UsePluginSettingsReturn,
 } from './usePluginClient'

package/src/composables/useAutoGroup.ts

@@ -22,11 +22,13 @@ import {
   composeTemplate,
   detectClass,
   expandGroupsWithReplicates,
+  expandTreeWithReplicates,
   findMerges,
   pickPrimaryDelimiter,
   preGroupReplicates,
   restoreFingerprint,
   serializeFingerprint,
+  splitByTokenLength,
   splitMulti,
   type ReplicatePreGrouping,
   type TemplateOptions,
@@ -142,11 +144,13 @@ export function useAutoGroup() {
       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`.
+    // Replicate pre-pass: strip _T<n> / _B<n> / _Rep<n> markers, then collapse
+    // samples whose stripped names match into one base entry. The trailing
+    // injection / run-order number is deliberately NOT stripped here — it
+    // survives tokenisation and is surfaced as a 'run-order' column below. The
+    // tokenize → classify → split-by-length → 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
 
@@ -156,17 +160,27 @@ export function useAutoGroup() {
     // 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 })
+    // Classify by sample type, THEN split each class by token length so every
+    // member of a class shares the same field count. This keeps the per-class
+    // token matrix rectangular, so column index N means the same field for
+    // every sample and the trailing injection number lands in its own column.
+    const detected = splitByTokenLength(
+      detectClass(tokenized.value, { sampleTypeHints: hints }),
+      tokenized.value,
+    )
     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,
-      )
+      newSchemas[classKey(cls)] = {
+        ...buildClassSchema(
+          memberTokens,
+          cls.kind,
+          cls.subKind,
+          cls.classTagPositions,
+        ),
+        tokenLength: cls.tokenLength,
+      }
     }
     schemas.value = newSchemas
     if (detected.length > 0) {
@@ -215,6 +229,11 @@ export function useAutoGroup() {
       qcGroups: composed.qcGroups
         ? expandGroupsWithReplicates(composed.qcGroups, pre)
         : undefined,
+      // The tree is built over base names too; expand its leaves to the original
+      // samples so it agrees with the flat experimental-groups panel.
+      groupTree: composed.groupTree
+        ? expandTreeWithReplicates(composed.groupTree, pre)
+        : composed.groupTree,
     }
   })
 
@@ -330,7 +349,9 @@ export function useAutoGroup() {
   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
+    for (const s of restored) {
+      next[classKey({ kind: s.classKind, subKind: s.subKind, tokenLength: s.tokenLength })] = s
+    }
     schemas.value = next
   }