@morscherlab/mint-sdk 1.0.0-beta.1 → 1.0.0-beta.3

package/src/templates/controlSchemas.ts

@@ -0,0 +1,718 @@
+import {
+  controlsToFormSchema,
+  controlsToSectionFormSchemas,
+  controlsToSidebarPanels,
+  getControlDefaults,
+  useControlSchema,
+  type ControlDefinition,
+  type ControlSchemaOptions,
+  type UseControlSchemaReturn,
+} from '../composables/useControlSchema'
+import {
+  extractTemplateCollection,
+} from './builders'
+import {
+  getBioTemplateInfo,
+} from './catalog'
+import {
+  getBioTemplatePresetInfo,
+} from './presets'
+import {
+  getBioTemplatePackInfo,
+} from './packs'
+import type {
+  BioTemplateEnvelope,
+  TemplateCollectionEnvelope,
+  TemplateId,
+  TemplatePackId,
+  TemplatePresetId,
+} from './types'
+
+export type BioTemplateControlSchema = Record<string, ControlDefinition>
+export type BioTemplateControlTarget =
+  | TemplateId
+  | TemplatePackId
+  | TemplatePresetId
+  | string
+  | BioTemplateEnvelope<unknown>
+  | TemplateCollectionEnvelope
+
+const ICONS = {
+  plate: ['M4 4h16v16H4z', 'M8 4v16', 'M12 4v16', 'M16 4v16', 'M4 8h16', 'M4 12h16', 'M4 16h16'],
+  samples: ['M16 21v-2a4 4 0 0 0-8 0v2', 'M12 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8'],
+  dose: ['M10 2v8L4 20h16l-6-10V2', 'M8 2h8', 'M7 14h10'],
+  table: ['M3 5h18', 'M3 12h18', 'M3 19h18', 'M8 5v14', 'M16 5v14'],
+  run: ['M4 17l6-6 4 4 6-8', 'M4 21h16'],
+  settings: ['M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8', 'M4 12h2', 'M18 12h2', 'M12 4v2', 'M12 18v2'],
+}
+
+const PLATE_FORMAT_OPTIONS = [6, 12, 24, 48, 96, 384] as const
+const CONCENTRATION_UNITS = ['nM', 'uM', 'mM', 'ug/mL', 'mg/mL'] as const
+
+const templateControlSchemas = {
+  'plate-map': {
+    plateName: {
+      label: 'Plate name',
+      default: 'Plate 1',
+      section: 'layout',
+      sectionLabel: 'Layout',
+      sectionSubtitle: 'Plate geometry',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    plateFormat: {
+      label: 'Format',
+      default: 96,
+      options: PLATE_FORMAT_OPTIONS,
+      section: 'layout',
+      view: 'design',
+    },
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['Control', 'Treatment'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Groups and legend',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+  },
+  'sample-sheet': {
+    sampleCount: {
+      type: 'number',
+      label: 'Sample count',
+      default: 2,
+      min: 1,
+      max: 10000,
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Metadata table',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    includeGroups: {
+      label: 'Include groups',
+      default: true,
+      section: 'samples',
+      view: 'design',
+    },
+    includeBatch: {
+      label: 'Include batch',
+      default: false,
+      section: 'columns',
+      sectionLabel: 'Columns',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+  },
+  'sample-prep': {
+    prepType: {
+      label: 'Prep type',
+      default: 'extraction',
+      options: ['extraction', 'dilution', 'normalization', 'transfer', 'quench', 'custom'],
+      section: 'protocol',
+      sectionLabel: 'Protocol',
+      sectionSubtitle: 'Prep workflow',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#f97316', iconBg: '#ffedd5' },
+    },
+    volumeUnit: {
+      label: 'Volume unit',
+      default: 'uL',
+      options: ['uL', 'mL'],
+      section: 'protocol',
+      view: 'design',
+    },
+    outputVolume: {
+      type: 'number',
+      label: 'Output volume',
+      default: 50,
+      min: 0,
+      section: 'protocol',
+      view: 'design',
+    },
+  },
+  'dose-response': {
+    unit: {
+      label: 'Dose unit',
+      default: 'uM',
+      options: CONCENTRATION_UNITS,
+      section: 'dose',
+      sectionLabel: 'Dose Design',
+      sectionSubtitle: 'Concentration series',
+      view: 'design',
+      sidebar: { icon: ICONS.dose, iconColor: '#8b5cf6', iconBg: '#ede9fe' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 24,
+      section: 'dose',
+      view: 'design',
+    },
+    includePlateLayout: {
+      label: 'Create plate layout',
+      default: true,
+      section: 'layout',
+      sectionLabel: 'Layout',
+      sectionSubtitle: 'Well assignment',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'calibration-curve': {
+    analyte: {
+      label: 'Analyte',
+      default: 'Analyte',
+      section: 'standards',
+      sectionLabel: 'Standards',
+      sectionSubtitle: 'Curve setup',
+      view: 'analysis',
+      sidebar: { icon: ICONS.dose, iconColor: '#8b5cf6', iconBg: '#ede9fe' },
+    },
+    model: {
+      label: 'Model',
+      default: 'linear',
+      options: ['linear', 'linear-weighted-1-x', 'linear-weighted-1-x2', 'quadratic', 'four-parameter-logistic'],
+      section: 'fit',
+      sectionLabel: 'Fit',
+      view: 'analysis',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    minRSquared: {
+      type: 'number',
+      label: 'Minimum R squared',
+      default: 0.99,
+      min: 0,
+      max: 1,
+      props: { step: 0.001 },
+      section: 'fit',
+      view: 'analysis',
+    },
+  },
+  'time-course': {
+    timeUnit: {
+      label: 'Time unit',
+      default: 'hour',
+      options: ['second', 'minute', 'hour', 'day', 'week'],
+      section: 'schedule',
+      sectionLabel: 'Schedule',
+      sectionSubtitle: 'Sampling timeline',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 24,
+      section: 'samples',
+      sectionLabel: 'Samples',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+  },
+  'protocol-steps': {
+    defaultDuration: {
+      type: 'number',
+      label: 'Default duration',
+      default: 30,
+      min: 0,
+      section: 'protocol',
+      sectionLabel: 'Protocol',
+      sectionSubtitle: 'Step defaults',
+      view: 'design',
+      sidebar: { icon: ICONS.run, iconColor: '#f97316', iconBg: '#ffedd5' },
+      props: { suffix: 'min' },
+    },
+    editable: {
+      label: 'Editable timeline',
+      default: true,
+      section: 'protocol',
+      view: 'design',
+    },
+  },
+  'assay-matrix': {
+    featureType: {
+      label: 'Feature type',
+      default: 'metabolite',
+      options: ['metabolite', 'protein', 'gene', 'cell', 'compound', 'readout', 'other'],
+      section: 'features',
+      sectionLabel: 'Features',
+      sectionSubtitle: 'Measurement matrix',
+      view: 'analysis',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    normalizeValues: {
+      label: 'Normalize values',
+      default: false,
+      section: 'analysis',
+      sectionLabel: 'Analysis',
+      view: 'analysis',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'reagent-list': {
+    reagentKind: {
+      label: 'Reagent kind',
+      default: 'reagent',
+      options: ['compound', 'antibody', 'primer', 'enzyme', 'buffer', 'media', 'kit', 'reagent', 'other'],
+      section: 'inventory',
+      sectionLabel: 'Inventory',
+      sectionSubtitle: 'Reagent metadata',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    trackStock: {
+      label: 'Track stock level',
+      default: true,
+      section: 'inventory',
+      view: 'design',
+    },
+  },
+  'flow-cytometry-panel': {
+    markers: {
+      type: 'tags',
+      label: 'Markers',
+      default: ['CD3', 'CD4', 'CD8'],
+      section: 'panel',
+      sectionLabel: 'Panel',
+      sectionSubtitle: 'Markers and controls',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    instrument: {
+      label: 'Instrument',
+      default: 'Flow cytometer',
+      section: 'panel',
+      sectionLabel: 'Panel',
+      sectionSubtitle: 'Markers and controls',
+      view: 'design',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    includeDefaultControls: {
+      label: 'Default controls',
+      default: true,
+      section: 'panel',
+      view: 'design',
+    },
+  },
+  'instrument-run': {
+    instrument: {
+      label: 'Instrument',
+      default: 'LC-MS',
+      options: ['LC-MS', 'GC-MS', 'Orbitrap', 'Triple quadrupole', 'Plate reader', 'Other'],
+      section: 'acquisition',
+      sectionLabel: 'Acquisition',
+      sectionSubtitle: 'Run queue',
+      view: 'run',
+      sidebar: { icon: ICONS.run, iconColor: '#ef4444', iconBg: '#fee2e2' },
+    },
+    method: {
+      label: 'Method',
+      default: 'Default method',
+      section: 'acquisition',
+      view: 'run',
+    },
+    includeQc: {
+      label: 'Include QC',
+      default: true,
+      section: 'quality',
+      sectionLabel: 'Quality Control',
+      view: 'run',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff', defaultOpen: false },
+    },
+  },
+  'qpcr-plate': {
+    chemistry: {
+      label: 'Chemistry',
+      default: 'sybr',
+      options: ['sybr', 'taqman', 'probe', 'evagreen', 'other'],
+      section: 'assay',
+      sectionLabel: 'Assay',
+      sectionSubtitle: 'qPCR setup',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    replicates: {
+      type: 'number',
+      label: 'Replicates',
+      default: 3,
+      min: 1,
+      max: 12,
+      section: 'assay',
+      view: 'design',
+    },
+    includeNoTemplateControls: {
+      label: 'No-template controls',
+      default: true,
+      section: 'controls',
+      sectionLabel: 'Controls',
+      view: 'design',
+      sidebar: { icon: ICONS.settings, iconColor: '#8b5cf6', iconBg: '#ede9fe', defaultOpen: false },
+    },
+  },
+} satisfies Record<TemplateId, BioTemplateControlSchema>
+
+const presetControlSchemas = {
+  'wellplate-screen': {
+    ...templateControlSchemas['plate-map'],
+    ...templateControlSchemas['dose-response'],
+    sampleNames: {
+      ...templateControlSchemas['plate-map'].sampleNames,
+      default: ['Control', 'Treatment'],
+    },
+  },
+  'qpcr-expression': {
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['Control', 'Treatment'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Expression groups',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    targets: {
+      type: 'tags',
+      label: 'Targets',
+      default: ['ACTB', 'GAPDH'],
+      section: 'assay',
+      sectionLabel: 'Assay',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    ...templateControlSchemas['qpcr-plate'],
+  },
+  'lcms-batch': {
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['S001', 'S002'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Batch samples',
+      view: 'run',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    featureNames: {
+      type: 'tags',
+      label: 'Features',
+      default: ['Glucose', 'Lactate'],
+      section: 'features',
+      sectionLabel: 'Features',
+      view: 'analysis',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    ...templateControlSchemas['instrument-run'],
+    ...templateControlSchemas['assay-matrix'],
+  },
+  'elisa-assay': {
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['Control', 'Treatment'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Unknowns and controls',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    analyte: {
+      label: 'Analyte',
+      default: 'Analyte',
+      section: 'standards',
+      sectionLabel: 'Standards',
+      sectionSubtitle: 'Calibration setup',
+      view: 'analysis',
+      sidebar: { icon: ICONS.dose, iconColor: '#8b5cf6', iconBg: '#ede9fe' },
+    },
+    standardConcentrations: {
+      type: 'tags',
+      label: 'Standards',
+      default: ['1000', '100', '10', '1'],
+      section: 'standards',
+      view: 'analysis',
+    },
+    unit: {
+      label: 'Concentration unit',
+      default: 'pg/mL',
+      options: ['pg/mL', 'ng/mL', 'ug/mL', 'nM', 'uM'],
+      section: 'standards',
+      view: 'analysis',
+    },
+    responseUnit: {
+      label: 'Response unit',
+      default: 'OD450',
+      section: 'readout',
+      sectionLabel: 'Readout',
+      view: 'analysis',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    plateName: {
+      label: 'Plate name',
+      default: 'ELISA plate',
+      section: 'layout',
+      sectionLabel: 'Layout',
+      sectionSubtitle: 'Plate geometry',
+      view: 'design',
+      sidebar: { icon: ICONS.plate, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+    plateFormat: {
+      label: 'Format',
+      default: 96,
+      options: PLATE_FORMAT_OPTIONS,
+      section: 'layout',
+      view: 'design',
+    },
+  },
+  'flow-cytometry-assay': {
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['Control', 'Treatment'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Assay groups',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    markers: {
+      ...templateControlSchemas['flow-cytometry-panel'].markers,
+      default: ['CD3', 'CD4', 'CD8'],
+    },
+    featureNames: {
+      type: 'tags',
+      label: 'Readouts',
+      default: ['CD3+ cells', 'CD4+ cells', 'CD8+ cells'],
+      section: 'features',
+      sectionLabel: 'Readouts',
+      sectionSubtitle: 'Assay matrix columns',
+      view: 'analysis',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    instrument: {
+      ...templateControlSchemas['flow-cytometry-panel'].instrument,
+      default: 'Flow cytometer',
+    },
+    includeDefaultControls: templateControlSchemas['flow-cytometry-panel'].includeDefaultControls,
+  },
+  'western-blot-assay': {
+    sampleNames: {
+      type: 'tags',
+      label: 'Samples',
+      default: ['Control', 'Treatment'],
+      section: 'samples',
+      sectionLabel: 'Samples',
+      sectionSubtitle: 'Blot lanes and groups',
+      view: 'design',
+      sidebar: { icon: ICONS.samples, iconColor: '#10b981', iconBg: '#d1fae5' },
+    },
+    targets: {
+      type: 'tags',
+      label: 'Targets',
+      default: ['Target protein'],
+      section: 'assay',
+      sectionLabel: 'Assay',
+      sectionSubtitle: 'Protein targets',
+      view: 'design',
+      sidebar: { icon: ICONS.table, iconColor: '#0ea5e9', iconBg: '#e0f2fe' },
+    },
+    loadingControl: {
+      label: 'Loading control',
+      default: 'ACTB',
+      section: 'normalization',
+      sectionLabel: 'Normalization',
+      view: 'analysis',
+      sidebar: { icon: ICONS.settings, iconColor: '#6366f1', iconBg: '#e0e7ff' },
+    },
+  },
+} satisfies Record<TemplatePresetId, BioTemplateControlSchema>
+
+export function listBioTemplateControlSchemas(): Record<TemplateId, BioTemplateControlSchema> {
+  return cloneSchemaMap(templateControlSchemas)
+}
+
+export function listBioTemplatePresetControlSchemas(): Record<TemplatePresetId, BioTemplateControlSchema> {
+  return cloneSchemaMap(presetControlSchemas)
+}
+
+export function getBioTemplateControlSchema(
+  target: BioTemplateControlTarget
+): BioTemplateControlSchema | undefined {
+  const resolved = resolveControlSchemaTarget(target)
+  if (!resolved) return undefined
+
+  if (resolved.kind === 'template') {
+    return cloneControlSchema(templateControlSchemas[resolved.name])
+  }
+  if (resolved.kind === 'preset') {
+    return cloneControlSchema(presetControlSchemas[resolved.name])
+  }
+  return mergeTemplateControlSchemas(resolved.templates)
+}
+
+export function requireBioTemplateControlSchema(
+  target: BioTemplateControlTarget
+): BioTemplateControlSchema {
+  const schema = getBioTemplateControlSchema(target)
+  if (!schema) {
+    throw new Error(`No built-in control schema found for '${describeControlTarget(target)}'.`)
+  }
+  return schema
+}
+
+export function createBioTemplateControlToolkit(
+  target: BioTemplateControlTarget,
+  options: ControlSchemaOptions = {}
+): UseControlSchemaReturn<BioTemplateControlSchema> {
+  return useControlSchema(requireBioTemplateControlSchema(target), options)
+}
+
+export function bioTemplateControlsToFormSchema(
+  target: BioTemplateControlTarget,
+  options: ControlSchemaOptions = {}
+) {
+  return controlsToFormSchema(requireBioTemplateControlSchema(target), options)
+}
+
+export function bioTemplateControlsToSidebarPanels(
+  target: BioTemplateControlTarget,
+  options: ControlSchemaOptions = {}
+) {
+  return controlsToSidebarPanels(requireBioTemplateControlSchema(target), options)
+}
+
+export function bioTemplateControlsToSectionFormSchemas(
+  target: BioTemplateControlTarget,
+  options: ControlSchemaOptions = {}
+) {
+  return controlsToSectionFormSchemas(requireBioTemplateControlSchema(target), options)
+}
+
+export function getBioTemplateControlDefaults(target: BioTemplateControlTarget) {
+  return getControlDefaults(requireBioTemplateControlSchema(target))
+}
+
+function resolveControlSchemaTarget(
+  target: BioTemplateControlTarget
+):
+  | { kind: 'template'; name: TemplateId }
+  | { kind: 'pack'; templates: TemplateId[] }
+  | { kind: 'preset'; name: TemplatePresetId }
+  | { kind: 'collection'; templates: TemplateId[] }
+  | undefined {
+  if (typeof target === 'string') {
+    const preset = getBioTemplatePresetInfo(target)
+    if (preset) return { kind: 'preset', name: preset.name }
+    const pack = getBioTemplatePackInfo(target)
+    if (pack) return { kind: 'pack', templates: [...pack.templates] }
+    const template = getBioTemplateInfo(target)
+    if (template) return { kind: 'template', name: template.template_id }
+    return undefined
+  }
+
+  if (isTemplateEnvelope(target)) {
+    const template = getBioTemplateInfo(target.template_id)
+    return template ? { kind: 'template', name: template.template_id } : undefined
+  }
+
+  const presetName = collectionPresetName(target)
+  if (presetName) {
+    const preset = getBioTemplatePresetInfo(presetName)
+    if (preset) return { kind: 'preset', name: preset.name }
+  }
+
+  const packName = collectionPackName(target)
+  if (packName) {
+    const pack = getBioTemplatePackInfo(packName)
+    if (pack) return { kind: 'pack', templates: [...pack.templates] }
+  }
+
+  const collection = extractTemplateCollection(target)
+  const templateIds = Object.keys(collection)
+    .map(id => getBioTemplateInfo(id)?.template_id)
+    .filter((id): id is TemplateId => id !== undefined)
+  return templateIds.length > 0 ? { kind: 'collection', templates: templateIds } : undefined
+}
+
+function mergeTemplateControlSchemas(templateIds: TemplateId[]): BioTemplateControlSchema {
+  const merged: BioTemplateControlSchema = {}
+  for (const templateId of templateIds) {
+    const schema = templateControlSchemas[templateId]
+    const template = getBioTemplateInfo(templateId)
+    for (const [name, definition] of Object.entries(schema)) {
+      const key = `${camelize(templateId)}${capitalize(name)}`
+      merged[key] = {
+        ...cloneControlDefinition(definition),
+        section: definition.section ?? templateId,
+        sectionLabel: definition.sectionLabel ?? template?.label ?? templateId,
+      }
+    }
+  }
+  return merged
+}
+
+function cloneSchemaMap<TName extends string>(
+  schemas: Record<TName, BioTemplateControlSchema>
+): Record<TName, BioTemplateControlSchema> {
+  const result = {} as Record<TName, BioTemplateControlSchema>
+  for (const name of Object.keys(schemas) as TName[]) {
+    result[name] = cloneControlSchema(schemas[name])
+  }
+  return result
+}
+
+function cloneControlSchema(schema: BioTemplateControlSchema): BioTemplateControlSchema {
+  return Object.fromEntries(
+    Object.entries(schema).map(([name, definition]) => [name, cloneControlDefinition(definition)])
+  )
+}
+
+function cloneControlDefinition(definition: BioTemplateControlSchema[string]): BioTemplateControlSchema[string] {
+  return {
+    ...definition,
+    options: definition.options ? [...definition.options] : undefined,
+    props: definition.props ? { ...definition.props } : undefined,
+    sidebar: typeof definition.sidebar === 'object' && definition.sidebar !== null
+      ? { ...definition.sidebar }
+      : definition.sidebar,
+  }
+}
+
+function isTemplateEnvelope(value: unknown): value is BioTemplateEnvelope<unknown> {
+  return isRecord(value) && typeof value.template_id === 'string' && 'data' in value
+}
+
+function collectionPresetName(value: unknown): string | undefined {
+  if (!isRecord(value) || !isRecord(value.metadata)) return undefined
+  return typeof value.metadata.preset === 'string' ? value.metadata.preset : undefined
+}
+
+function collectionPackName(value: unknown): string | undefined {
+  if (!isRecord(value) || !isRecord(value.metadata)) return undefined
+  return typeof value.metadata.pack === 'string' ? value.metadata.pack : undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function describeControlTarget(target: BioTemplateControlTarget): string {
+  if (typeof target === 'string') return target
+  if (isTemplateEnvelope(target)) return target.template_id
+  return collectionPresetName(target) ?? collectionPackName(target) ?? 'template collection'
+}
+
+function camelize(value: string): string {
+  return value.replace(/-([a-z0-9])/g, (_, char: string) => char.toUpperCase())
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1)
+}