@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.5

package/src/tailwind.preset.ts

@@ -0,0 +1,66 @@
+import type { Config } from 'tailwindcss'
+
+const mintPreset = {
+  theme: {
+    extend: {
+      colors: {
+        mint: {
+          primary: 'var(--color-primary)',
+          'primary-hover': 'var(--color-primary-hover)',
+          'primary-light': 'var(--color-primary-light)',
+          cta: 'var(--color-cta)',
+          'cta-hover': 'var(--color-cta-hover)',
+          danger: 'var(--mint-error)',
+          'danger-hover': 'var(--mint-error-hover)',
+          success: 'var(--mint-success)',
+          'success-hover': 'var(--mint-success-hover)',
+          warning: 'var(--mint-warning)',
+          'warning-hover': 'var(--mint-warning-hover)',
+          brand: 'var(--mint-brand)',
+          'brand-hover': 'var(--mint-brand-hover)',
+          experiment: 'var(--color-experiment)',
+          'experiment-hover': 'var(--color-experiment-hover)',
+          project: 'var(--color-project)',
+          'project-hover': 'var(--color-project-hover)',
+        },
+        bg: {
+          primary: 'var(--mint-bg-primary)',
+          secondary: 'var(--mint-bg-secondary)',
+          card: 'var(--mint-bg-card)',
+          hover: 'var(--mint-bg-hover)',
+          input: 'var(--mint-bg-input)',
+        },
+        text: {
+          primary: 'var(--mint-text-primary)',
+          secondary: 'var(--mint-text-secondary)',
+          muted: 'var(--mint-text-muted)',
+          inverse: 'var(--mint-text-inverse)',
+        },
+        border: {
+          DEFAULT: 'var(--mint-border)',
+          focus: 'var(--mint-border-focus)',
+        },
+      },
+      fontFamily: {
+        sans: ['Fira Sans', 'system-ui', '-apple-system', 'sans-serif'],
+        mono: ['Fira Code', 'ui-monospace', 'SFMono-Regular', 'monospace'],
+      },
+      borderRadius: {
+        mint: '0.5rem',
+        'mint-sm': '0.375rem',
+        'mint-lg': '0.75rem',
+      },
+      boxShadow: {
+        mint: '0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)',
+        'mint-md': '0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)',
+        'mint-lg': '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)',
+        'mint-card': 'var(--card-shadow)',
+      },
+      transitionDuration: {
+        mint: '150ms',
+      },
+    },
+  },
+} satisfies Partial<Config>
+
+export default mintPreset

package/src/templates/adapters.ts

@@ -0,0 +1,137 @@
+import type { Well } from '../types'
+import type {
+  AssayMatrixTemplate,
+  BioTemplateEnvelope,
+  CalibrationCurveTemplate,
+  DataFrameTemplate,
+  FlowCytometryPanelTemplate,
+  InstrumentRunTemplate,
+  ProtocolStepsTemplate,
+  QpcrPlateTemplate,
+  ReagentListTemplate,
+  SamplePrepTemplate,
+  SampleSheetTemplate,
+  TimeCourseTemplate,
+  TemplateDataFrameAdapterResult,
+} from './types'
+import { toAssayMatrixDataFrame } from './assayMatrixAdapters'
+import { toCalibrationCurveDataFrame } from './calibrationCurveAdapters'
+import { toFlowPanelDataFrame } from './flowPanelAdapters'
+import { toInstrumentRunDataFrame } from './instrumentRunAdapters'
+import { toProtocolDataFrame } from './protocolAdapters'
+import { toQpcrDataFrame } from './qpcrAdapters'
+import { toReagentDataFrame } from './reagentAdapters'
+import { toSamplePrepDataFrame } from './samplePrepAdapters'
+import { toSampleDataFrame } from './sampleSheetAdapters'
+import { toTimeCourseDataFrame } from './timeCourseAdapters'
+
+export {
+  toAssayMatrixColumns,
+  toAssayMatrixDataFrame,
+  toAssayMatrixRows,
+  toAssayMatrixSampleOptions,
+} from './assayMatrixAdapters'
+
+export {
+  toCalibrationCurveColumns,
+  toCalibrationCurveDataFrame,
+  toCalibrationCurveRows,
+} from './calibrationCurveAdapters'
+
+export {
+  toDoseConditions,
+  toDoseLayoutState,
+} from './doseResponseAdapters'
+
+export {
+  toFlowPanelColumns,
+  toFlowPanelDataFrame,
+  toFlowPanelRows,
+} from './flowPanelAdapters'
+
+export {
+  toInstrumentRunColumns,
+  toInstrumentRunDataFrame,
+  toInstrumentRunRows,
+  toInstrumentRunScheduleEvents,
+  toInstrumentRunSteps,
+} from './instrumentRunAdapters'
+
+export {
+  toPlateMapEditorState,
+  toWellPlateWells,
+} from './plateMapAdapters'
+
+export {
+  toProtocolColumns,
+  toProtocolDataFrame,
+  toProtocolRows,
+  toProtocolSteps,
+} from './protocolAdapters'
+
+export {
+  toQpcrColumns,
+  toQpcrDataFrame,
+  toQpcrRows,
+  toQpcrWellPlateWells,
+} from './qpcrAdapters'
+
+export {
+  toReagentColumns,
+  toReagentDataFrame,
+  toReagentListItems,
+  toReagentRows,
+} from './reagentAdapters'
+
+export {
+  toSamplePrepColumns,
+  toSamplePrepDataFrame,
+  toSamplePrepRows,
+} from './samplePrepAdapters'
+
+export {
+  toSampleColumns,
+  toSampleDataFrame,
+  toSampleOptions,
+  toSampleRows,
+} from './sampleSheetAdapters'
+
+export {
+  toTimeCourseColumns,
+  toTimeCourseDataFrame,
+  toTimeCourseRows,
+  toTimeCourseSteps,
+} from './timeCourseAdapters'
+
+export function toTemplateDataFrame(
+  template: DataFrameTemplate | BioTemplateEnvelope<unknown>
+): TemplateDataFrameAdapterResult {
+  switch (template.template_id) {
+    case 'sample-sheet':
+      return toSampleDataFrame(template as SampleSheetTemplate)
+    case 'sample-prep':
+      return toSamplePrepDataFrame(template as SamplePrepTemplate)
+    case 'calibration-curve':
+      return toCalibrationCurveDataFrame(template as CalibrationCurveTemplate)
+    case 'time-course':
+      return toTimeCourseDataFrame(template as TimeCourseTemplate)
+    case 'protocol-steps':
+      return toProtocolDataFrame(template as ProtocolStepsTemplate)
+    case 'assay-matrix':
+      return toAssayMatrixDataFrame(template as AssayMatrixTemplate)
+    case 'reagent-list':
+      return toReagentDataFrame(template as ReagentListTemplate)
+    case 'flow-cytometry-panel':
+      return toFlowPanelDataFrame(template as FlowCytometryPanelTemplate)
+    case 'instrument-run':
+      return toInstrumentRunDataFrame(template as InstrumentRunTemplate)
+    case 'qpcr-plate':
+      return toQpcrDataFrame(template as QpcrPlateTemplate)
+    default:
+      throw new Error(`Template '${String(template.template_id)}' does not expose a DataFrame adapter.`)
+  }
+}
+
+export function toWellMapArray(wells: Record<string, Well>): Well[] {
+  return Object.values(wells)
+}

package/src/templates/assayLookups.ts

@@ -0,0 +1,33 @@
+import type {
+  AssayFeature,
+  AssaySample,
+} from './types'
+import { idFromName } from './builderIdUtils'
+
+export function createAssaySampleLookup(samples: AssaySample[]): Map<string, string> {
+  const lookup = new Map<string, string>()
+  for (const sample of samples) {
+    addLookupAlias(lookup, sample.sampleId, sample.sampleId)
+    if (sample.name) {
+      addLookupAlias(lookup, sample.name, sample.sampleId)
+      addLookupAlias(lookup, idFromName(sample.name, sample.sampleId), sample.sampleId)
+    }
+  }
+  return lookup
+}
+
+export function createAssayFeatureLookup(features: AssayFeature[]): Map<string, string> {
+  const lookup = new Map<string, string>()
+  for (const feature of features) {
+    addLookupAlias(lookup, feature.id, feature.id)
+    addLookupAlias(lookup, feature.name, feature.id)
+    addLookupAlias(lookup, idFromName(feature.name, feature.id), feature.id)
+  }
+  return lookup
+}
+
+function addLookupAlias(lookup: Map<string, string>, alias: string, value: string): void {
+  if (!lookup.has(alias)) {
+    lookup.set(alias, value)
+  }
+}

package/src/templates/assayMatrixAdapters.ts

@@ -0,0 +1,78 @@
+import type { SelectOption } from '../types'
+import { getTemplateData } from './templateEnvelopes'
+import { validateAssayMatrixData } from './templateValidators'
+import type {
+  AssayMatrixColumnsAdapterResult,
+  AssayMatrixDataFrameAdapterResult,
+  AssayMatrixRowsAdapterResult,
+  AssayMatrixSampleOptionsAdapterResult,
+  AssayMatrixTemplate,
+  AssayMatrixTemplateData,
+} from './types'
+
+export function toAssayMatrixRows(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixRowsAdapterResult {
+  const data = getTemplateData(template, 'assay-matrix')
+  validateAssayMatrixData(data)
+  const measurements = new Map(
+    data.measurements.map(measurement => [
+      `${measurement.sampleId}:${measurement.featureId}`,
+      measurement.value ?? null,
+    ])
+  )
+
+  return data.samples.map(sample => {
+    const row: Record<string, unknown> = {
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      ...(sample.metadata ?? {}),
+    }
+    for (const feature of data.features) {
+      row[feature.id] = measurements.get(`${sample.sampleId}:${feature.id}`) ?? null
+    }
+    return row
+  })
+}
+
+export function toAssayMatrixColumns(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixColumnsAdapterResult {
+  const data = getTemplateData(template, 'assay-matrix')
+  validateAssayMatrixData(data)
+  return [
+    { key: 'sampleId', label: 'Sample ID', sortable: true },
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'group', label: 'Group', sortable: true },
+    ...data.features.map(feature => ({
+      key: feature.id,
+      label: feature.unit ? `${feature.name} (${feature.unit})` : feature.name,
+      sortable: true,
+      align: 'right' as const,
+    })),
+  ]
+}
+
+export function toAssayMatrixDataFrame(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixDataFrameAdapterResult {
+  return {
+    data: toAssayMatrixRows(template),
+    columns: toAssayMatrixColumns(template),
+    rowKey: 'sampleId',
+  }
+}
+
+/** Convert an assay-matrix template into SampleSelector options derived from assay samples. */
+export function toAssayMatrixSampleOptions(
+  template: AssayMatrixTemplate | AssayMatrixTemplateData
+): AssayMatrixSampleOptionsAdapterResult {
+  const data = getTemplateData(template, 'assay-matrix')
+  validateAssayMatrixData(data)
+  return data.samples.map((sample): SelectOption<string> => ({
+    value: sample.sampleId,
+    label: sample.name ?? sample.sampleId,
+    description: sample.group,
+  }))
+}

package/src/templates/assayMatrixBuilder.ts

@@ -0,0 +1,59 @@
+import {
+  createAssayFeatureLookup,
+  createAssaySampleLookup,
+} from './assayLookups'
+import {
+  normalizeAssayFeature,
+  normalizeAssaySample,
+} from './assayNormalizers'
+import { idFromName } from './builderIdUtils'
+import { createTemplateEnvelope } from './templateEnvelopes'
+import { validateAssayMatrixData } from './templateValidators'
+import type {
+  AssayFeature,
+  AssayMatrixTemplate,
+  AssayMatrixTemplateData,
+  AssaySample,
+  CreateAssayMatrixTemplateOptions,
+} from './types'
+
+export function createAssayMatrixTemplate(
+  options: CreateAssayMatrixTemplateOptions
+): AssayMatrixTemplate {
+  const samples = options.samples.map((sample, index): AssaySample => {
+    if (typeof sample !== 'string') return normalizeAssaySample(sample)
+    return {
+      sampleId: idFromName(sample, `sample-${index + 1}`),
+      name: sample,
+      metadata: {},
+    }
+  })
+  const features = options.features.map((feature, index): AssayFeature => {
+    if (typeof feature !== 'string') return normalizeAssayFeature(feature)
+    return {
+      id: idFromName(feature, `feature-${index + 1}`),
+      name: feature,
+      type: 'readout',
+      metadata: {},
+    }
+  })
+  const sampleLookup = createAssaySampleLookup(samples)
+  const featureLookup = createAssayFeatureLookup(features)
+  const measurements = Object.entries(options.values ?? {}).flatMap(([sampleId, featureValues]) =>
+    Object.entries(featureValues).map(([featureId, value]) => ({
+      sampleId: sampleLookup.get(sampleId) ?? sampleId,
+      featureId: featureLookup.get(featureId) ?? featureId,
+      value,
+      metadata: {},
+    }))
+  )
+
+  const data: AssayMatrixTemplateData = {
+    samples,
+    features,
+    measurements,
+    metadata: options.metadata ?? {},
+  }
+  validateAssayMatrixData(data)
+  return createTemplateEnvelope('assay-matrix', data, options.metadata ?? {})
+}

package/src/templates/assayNormalizers.ts

@@ -0,0 +1,34 @@
+import type {
+  AssayFeature,
+  AssaySample,
+  ReagentRecord,
+  ReagentTemplateInput,
+} from './types'
+
+export function normalizeAssaySample(sample: AssaySample): AssaySample {
+  return {
+    ...sample,
+    metadata: sample.metadata ?? {},
+  }
+}
+
+export function normalizeAssayFeature(feature: AssayFeature): AssayFeature {
+  return {
+    ...feature,
+    metadata: feature.metadata ?? {},
+  }
+}
+
+export function normalizeReagent(reagent: ReagentTemplateInput): ReagentRecord {
+  return {
+    ...reagent,
+    expiryDate: normalizeDateString(reagent.expiryDate),
+    kind: reagent.kind ?? 'reagent',
+    metadata: reagent.metadata ?? {},
+  }
+}
+
+function normalizeDateString(value: Date | string | null | undefined): string | undefined {
+  if (value === undefined || value === null) return undefined
+  return value instanceof Date ? value.toISOString() : value
+}

package/src/templates/builderDefaults.ts

@@ -0,0 +1,11 @@
+export const DEFAULT_SAMPLE_COLORS = [
+  '#3B82F6',
+  '#10B981',
+  '#EF4444',
+  '#F59E0B',
+  '#8B5CF6',
+  '#F97316',
+  '#06B6D4',
+  '#14B8A6',
+  '#6B7280',
+]

package/src/templates/builderIdUtils.ts

@@ -0,0 +1,20 @@
+export function sampleIdFromName(name: string, index: number): string {
+  return idFromName(name, `sample-${index + 1}`)
+}
+
+export function compoundIdFromName(name: string, index: number): string {
+  return idFromName(name, `compound-${index + 1}`)
+}
+
+export function idFromName(name: string, fallback: string): string {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+  return slug || fallback
+}
+
+export function timepointId(value: number, unit: string, index: number): string {
+  const raw = Number.isInteger(value)
+    ? String(value)
+    : String(value).replace(/0+$/, '').replace(/\.$/, '')
+  const token = raw.replace('.', 'p')
+  return token ? `t${token}-${unit}` : `timepoint-${index + 1}`
+}

package/src/templates/builderPresetControls.ts

@@ -0,0 +1,165 @@
+import {
+  readBoolean,
+  readInteger,
+  readNumber,
+  readNumberList,
+  readOptionalString,
+  readString,
+  readStringList,
+} from './builderReadUtils'
+import { readPlateFormat } from './plateGeometry'
+import { getBioTemplatePresetInfo } from './presets'
+import type {
+  CreateElisaAssayCollectionOptions,
+  CreateFlowCytometryAssayCollectionOptions,
+  CreateLcmsBatchCollectionOptions,
+  CreateQpcrExpressionCollectionOptions,
+  CreateQpcrPlateTemplateOptions,
+  CreateSamplePrepTemplateOptions,
+  CreateTargetedMetabolomicsCollectionOptions,
+  CreateWellPlateScreenCollectionOptions,
+  CreateWesternBlotAssayCollectionOptions,
+  TemplatePresetId,
+} from './types'
+
+export type BioTemplateControlValues = Record<string, unknown>
+
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'wellplate-screen',
+  values: BioTemplateControlValues
+): CreateWellPlateScreenCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'qpcr-expression',
+  values: BioTemplateControlValues
+): CreateQpcrExpressionCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'lcms-batch',
+  values: BioTemplateControlValues
+): CreateLcmsBatchCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'targeted-metabolomics',
+  values: BioTemplateControlValues
+): CreateTargetedMetabolomicsCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'elisa-assay',
+  values: BioTemplateControlValues
+): CreateElisaAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'flow-cytometry-assay',
+  values: BioTemplateControlValues
+): CreateFlowCytometryAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'western-blot-assay',
+  values: BioTemplateControlValues
+): CreateWesternBlotAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+):
+  | CreateWellPlateScreenCollectionOptions
+  | CreateQpcrExpressionCollectionOptions
+  | CreateLcmsBatchCollectionOptions
+  | CreateTargetedMetabolomicsCollectionOptions
+  | CreateElisaAssayCollectionOptions
+  | CreateFlowCytometryAssayCollectionOptions
+  | CreateWesternBlotAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+):
+  | CreateWellPlateScreenCollectionOptions
+  | CreateQpcrExpressionCollectionOptions
+  | CreateLcmsBatchCollectionOptions
+  | CreateTargetedMetabolomicsCollectionOptions
+  | CreateElisaAssayCollectionOptions
+  | CreateFlowCytometryAssayCollectionOptions
+  | CreateWesternBlotAssayCollectionOptions {
+  const preset = getBioTemplatePresetInfo(name)
+  if (!preset) {
+    throw new Error(`Unknown template preset '${name}'.`)
+  }
+
+  if (preset.name === 'wellplate-screen') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      plateName: readString(values.plateName, 'Screen plate'),
+      plateFormat: readPlateFormat(values.plateFormat, 96),
+      unit: readString(values.unit, 'uM'),
+      replicates: readInteger(values.replicates, 3),
+    }
+  }
+
+  if (preset.name === 'qpcr-expression') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      targets: readStringList(values.targets, ['ACTB', 'GAPDH']),
+      chemistry: readString(values.chemistry, 'sybr') as CreateQpcrPlateTemplateOptions['chemistry'],
+      format: readPlateFormat(values.plateFormat, 96),
+      includeNoTemplateControls: readBoolean(values.includeNoTemplateControls, true),
+      replicates: readInteger(values.replicates, 3),
+      instrument: readOptionalString(values.instrument),
+    }
+  }
+
+  if (preset.name === 'lcms-batch') {
+    return {
+      samples: readStringList(values.sampleNames, ['S001', 'S002']),
+      features: readStringList(values.featureNames, ['Glucose', 'Lactate']),
+      instrument: readString(values.instrument, 'LC-MS'),
+      method: readString(values.method, 'Default method'),
+      includeQc: readBoolean(values.includeQc, true),
+    }
+  }
+
+  if (preset.name === 'targeted-metabolomics') {
+    return {
+      samples: readStringList(values.sampleNames, ['S001', 'S002']),
+      metabolites: readStringList(values.metaboliteNames, ['Glucose', 'Lactate', 'Pyruvate']),
+      internalStandards: readStringList(
+        values.internalStandards,
+        ['Stable isotope internal standard mix'],
+      ),
+      standardConcentrations: readNumberList(values.standardConcentrations, [0.1, 1, 10, 100]),
+      concentrationUnit: readString(values.concentrationUnit, 'uM'),
+      responseUnit: readString(values.responseUnit, 'peak area ratio'),
+      calibrationAnalyte: readOptionalString(values.calibrationAnalyte),
+      instrument: readString(values.instrument, 'LC-MS'),
+      method: readString(values.method, 'Targeted metabolomics'),
+      prepType: readString(values.prepType, 'extraction') as CreateSamplePrepTemplateOptions['prepType'],
+      outputVolume: readNumber(values.outputVolume, 50),
+      includeQc: readBoolean(values.includeQc, true),
+    }
+  }
+
+  if (preset.name === 'elisa-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      analyte: readString(values.analyte, 'Analyte'),
+      standardConcentrations: readNumberList(values.standardConcentrations, [1000, 100, 10, 1]),
+      unit: readString(values.unit, 'pg/mL'),
+      responseUnit: readString(values.responseUnit, 'OD450'),
+      plateName: readString(values.plateName, 'ELISA plate'),
+      plateFormat: readPlateFormat(values.plateFormat, 96),
+    }
+  }
+
+  if (preset.name === 'flow-cytometry-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      markers: readStringList(values.markers, ['CD3', 'CD4', 'CD8']),
+      features: readStringList(values.featureNames, ['CD3+ cells', 'CD4+ cells', 'CD8+ cells']),
+      instrument: readString(values.instrument, 'Flow cytometer'),
+      includeDefaultControls: readBoolean(values.includeDefaultControls, true),
+    }
+  }
+
+  if (preset.name === 'western-blot-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      targets: readStringList(values.targets, ['Target protein']),
+      loadingControl: readString(values.loadingControl, 'ACTB'),
+    }
+  }
+
+  throw new Error(`Unknown template preset '${name}'.`)
+}

package/src/templates/builderReadUtils.ts

@@ -0,0 +1,55 @@
+export { isRecord } from '../utils/records'
+
+export function readStringList(value: unknown, fallback: string[]): string[] {
+  if (Array.isArray(value)) {
+    const items = value.map(item => String(item).trim()).filter(Boolean)
+    return items.length ? items : fallback
+  }
+  if (typeof value === 'string') {
+    const items = value.split(',').map(item => item.trim()).filter(Boolean)
+    return items.length ? items : fallback
+  }
+  return fallback
+}
+
+export function readNumberList(value: unknown, fallback: number[]): number[] {
+  const rawItems = Array.isArray(value)
+    ? value
+    : typeof value === 'string'
+      ? value.split(',')
+      : []
+  const items = rawItems
+    .map(item => Number(String(item).trim()))
+    .filter(item => Number.isFinite(item))
+  return items.length ? items : fallback
+}
+
+export function readString(value: unknown, fallback: string): string {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback
+}
+
+export function readOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+export function readInteger(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return Number.isFinite(parsed) ? Math.max(1, Math.round(parsed)) : fallback
+}
+
+export function readNumber(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+export function readBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback
+}