@morscherlab/mint-sdk 1.2.0-beta.1 → 1.2.0-beta.11

package/src/styles/components/secret-input.css

@@ -0,0 +1,60 @@
+/* SecretInput — plugin secret settings field with a set / not set / environment badge. */
+
+.mint-secret-input {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.mint-secret-input__status {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.mint-secret-input__badge {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 999px;
+  padding: 0.125rem 0.5rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  line-height: 1.4;
+  border: 1px solid transparent;
+  background-color: var(--bg-tertiary);
+  color: var(--text-secondary);
+}
+
+.mint-secret-input__badge--set {
+  background-color: color-mix(in srgb, var(--mint-success) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-success) 35%, transparent);
+  color: var(--mint-success);
+}
+
+.mint-secret-input__badge--environment {
+  background-color: color-mix(in srgb, var(--mint-info) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-info) 35%, transparent);
+  color: var(--mint-info);
+}
+
+.mint-secret-input__badge--pending {
+  background-color: color-mix(in srgb, var(--mint-warning) 12%, transparent);
+  border-color: color-mix(in srgb, var(--mint-warning) 35%, transparent);
+  color: var(--mint-warning);
+}
+
+.mint-secret-input__hint {
+  font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
+.mint-secret-input__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.mint-secret-input--error .mint-secret-input__badge {
+  border-color: color-mix(in srgb, var(--mint-error) 45%, transparent);
+}

package/src/styles/components/well-plate.css

@@ -284,3 +284,11 @@
   font-size: 0.75rem;
   color: var(--text-muted);
 }
+
+/* Empty / loading / error placeholder host (content comes from EmptyState) */
+.mint-well-plate__state {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 12rem;
+}

package/src/styles/index.css

@@ -30,6 +30,7 @@
 @import './components/radio-group.css';
 @import './components/sample-legend.css';
 @import './components/section-card.css';
+@import './components/secret-input.css';
 @import './components/select.css';
 @import './components/skeleton.css';
 @import './components/slider.css';
@@ -56,6 +57,7 @@
 @import './components/dropdown-button.css';
 @import './components/calendar.css';
 @import './components/dataframe.css';
+@import './components/data-state.css';
 @import './components/well-edit-popup.css';
 @import './components/rack-editor.css';
 @import './components/loading-spinner.css';
@@ -91,3 +93,10 @@
 @import './components/artifact-save-dialog.css';
 @import './components/experiment-popover.css';
 @import './components/fit-panel.css';
+@import './components/app-avatar-menu.css';
+@import './components/app-page-selector.css';
+@import './components/app-pill-nav.css';
+@import './components/app-plugin-switcher.css';
+@import './components/mobile-support-gate.css';
+@import './components/plugin-icon.css';
+@import './components/reagent-editor.css';

package/src/styles/variables.css

@@ -66,6 +66,32 @@
   /* The MINT 1.1 card system uses exactly one shadow for every card. */
   --card-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.04), 0 1px 3px 0 rgb(0 0 0 / 0.06);
 
+  /* Categorical sample scale — mirrored by SAMPLE_COLOR_SCALE in
+     src/utils/color.ts. The JS constant carries the same hexes as a
+     canvas/SVG/persistence-safe fallback; change both together. */
+  --mint-sample-1: #3B82F6;
+  --mint-sample-2: #10B981;
+  --mint-sample-3: #EF4444;
+  --mint-sample-4: #F59E0B;
+  --mint-sample-5: #8B5CF6;
+  --mint-sample-6: #F97316;
+  --mint-sample-7: #06B6D4;
+  --mint-sample-8: #14B8A6;
+  --mint-sample-9: #6B7280;
+
+  /* Rack / plate slot positions — mirrored by SLOT_COLORS in
+     src/utils/color.ts. */
+  --mint-slot-r: #ef4444;
+  --mint-slot-g: #22c55e;
+  --mint-slot-b: #3b82f6;
+  --mint-slot-y: #eab308;
+
+  /* Motion — the SDK's standard easing curve. */
+  --mint-ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);
+
+  /* Typography — Fira Code for data, code and routes. */
+  --font-mono: 'Fira Code', ui-monospace, SFMono-Regular, Menlo, monospace;
+
   /* Border radius */
   --radius-sm: 0.25rem;
   --radius: 0.375rem;
@@ -90,6 +116,8 @@
   --mint-warning-hover: #D97706;
   --mint-warning-bg: rgba(245, 158, 11, 0.1);
   --mint-warning-border: rgba(245, 158, 11, 0.3);
+  /* Readable warning label on --mint-warning-bg (amber-700, 5.9:1). */
+  --mint-warning-text: #B45309;
   --mint-info: #3B82F6;
   --mint-info-bg: rgba(59, 130, 246, 0.1);
   --mint-info-border: rgba(59, 130, 246, 0.3);
@@ -178,6 +206,7 @@ html.dark {
   --mint-success-bg: rgba(16, 185, 129, 0.15);
   --mint-error-bg: rgba(239, 68, 68, 0.15);
   --mint-warning-bg: rgba(245, 158, 11, 0.15);
+  --mint-warning-text: #FCD34D;
   --mint-info-bg: rgba(59, 130, 246, 0.15);
 
   /* Focus ring - dark mode offset uses bg-primary instead of white */

package/src/templates/builderPresetControls.ts

@@ -7,7 +7,7 @@ import {
   readString,
   readStringList,
 } from './builderReadUtils'
-import { readPlateFormat } from './plateGeometry'
+import { readPlateFormat } from '../components/WellPlate.geometry'
 import { getBioTemplatePresetInfo } from './presets'
 import type {
   CreateElisaAssayCollectionOptions,

package/src/templates/builderReadUtils.ts

@@ -1,6 +1,4 @@
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
+export { isRecord } from '../utils/records'
 
 export function readStringList(value: unknown, fallback: string[]): string[] {
   if (Array.isArray(value)) {

package/src/templates/componentPlateHelpers.ts

@@ -2,6 +2,7 @@ import type {
   PlateMapEditorState,
   WellLegendItem,
 } from '../types'
+import { SAMPLE_COLOR_SCALE } from '../utils/color'
 
 export function activePlateFromState(state: PlateMapEditorState) {
   return state.plates.find(plate => plate.id === state.activePlateId) ?? state.plates[0]
@@ -24,6 +25,7 @@ export function legendItemsFromPlateState(state: PlateMapEditorState): WellLegen
 }
 
 export function colorForIndex(index: number): string {
-  const colors = ['#3B82F6', '#10B981', '#EF4444', '#F59E0B', '#8B5CF6', '#F97316', '#06B6D4', '#14B8A6']
+  // The gray tail of the scale is reserved for "other"; component plates cycle the eight hues.
+  const colors = SAMPLE_COLOR_SCALE.slice(0, 8)
   return colors[index % colors.length]
 }

package/src/templates/componentTargetResolvers.ts

@@ -1,3 +1,4 @@
+import { isObjectLike as isRecord } from '../utils/records'
 import { extractTemplateCollection } from './templateEnvelopes'
 import { getBioTemplateInfo } from './catalog'
 import { getBioTemplatePackInfo } from './packs'
@@ -64,6 +65,3 @@ function collectionPackName(value: unknown): string | 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
-}

package/src/templates/controlSchemaTargets.ts

@@ -1,3 +1,4 @@
+import { isObjectLike as isRecord } from '../utils/records'
 import {
   getBioTemplateInfo,
 } from './catalog'
@@ -82,6 +83,3 @@ function collectionPackName(value: unknown): string | 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
-}

package/src/templates/doseResponseAdapters.ts

@@ -2,6 +2,7 @@ import type {
   PlateCondition,
   PlateMapEditorState,
 } from '../types'
+import { SAMPLE_COLOR_SCALE } from '../utils/color'
 import { toPlateMapEditorState } from './plateMapAdapters'
 import { getTemplateData } from './templateEnvelopes'
 import { validateDoseResponseData } from './templateValidators'
@@ -11,18 +12,6 @@ import type {
   DoseResponseTemplateData,
 } from './types'
 
-const CONDITION_COLORS = [
-  '#3B82F6',
-  '#10B981',
-  '#EF4444',
-  '#F59E0B',
-  '#8B5CF6',
-  '#F97316',
-  '#06B6D4',
-  '#14B8A6',
-  '#6B7280',
-]
-
 export function toDoseConditions(
   template: DoseResponseTemplate | DoseResponseTemplateData
 ): DoseConditionsAdapterResult {
@@ -30,7 +19,7 @@ export function toDoseConditions(
   validateDoseResponseData(data)
   return data.compounds.map((compound, index): PlateCondition => ({
     label: compound.name,
-    color: String(compound.metadata?.color ?? CONDITION_COLORS[index % CONDITION_COLORS.length]),
+    color: String(compound.metadata?.color ?? SAMPLE_COLOR_SCALE[index % SAMPLE_COLOR_SCALE.length]),
     concentrations: compound.concentrations,
     unit: data.unit,
   }))

package/src/templates/elisaAssayCollectionBuilder.ts

@@ -1,5 +1,5 @@
 import { createAssayMatrixTemplate } from './assayMatrixBuilder'
-import { DEFAULT_SAMPLE_COLORS } from './builderDefaults'
+import { SAMPLE_COLOR_SCALE } from '../utils/color'
 import { idFromName } from './builderIdUtils'
 import { createCalibrationCurveTemplate } from './calibrationCurveBuilder'
 import { createPlateMapTemplate } from './plateMapBuilder'
@@ -27,7 +27,7 @@ export function createElisaAssayCollection(
       ...sampleRecords.map((sample, index) => ({
         id: sample.sampleId,
         name: sample.name ?? sample.sampleId,
-        color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+        color: SAMPLE_COLOR_SCALE[index % SAMPLE_COLOR_SCALE.length],
       })),
     ],
   })

package/src/templates/plateMapBuilder.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_SAMPLE_COLORS } from './builderDefaults'
+import { SAMPLE_COLOR_SCALE } from '../utils/color'
 import { sampleIdFromName } from './builderIdUtils'
 import { createTemplateEnvelope } from './templateEnvelopes'
 import type {
@@ -23,7 +23,7 @@ export function createPlateMapTemplate(
     return {
       id: sampleIdFromName(sample, index),
       name: sample,
-      color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+      color: SAMPLE_COLOR_SCALE[index % SAMPLE_COLOR_SCALE.length],
     }
   })
 

package/src/templates/qpcrPlateBuilder.ts

@@ -1,5 +1,5 @@
 import { idFromName } from './builderIdUtils'
-import { wellIdsForFormat } from './plateGeometry'
+import { wellIdsForFormat } from '../components/WellPlate.geometry'
 import {
   normalizeQpcrSample,
   normalizeQpcrTarget,

package/src/templates/templateValidators.ts

@@ -12,7 +12,7 @@ import type {
   SampleSheetTemplateData,
   TimeCourseTemplateData,
 } from './types'
-import { assertWellInFormat } from './plateGeometry'
+import { assertWellInFormat } from '../components/WellPlate.geometry'
 
 export function validatePlateMapData(data: PlateMapTemplateData): void {
   if (!Array.isArray(data.plates) || data.plates.length === 0) {

package/src/templates/timeCourseBuilder.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_SAMPLE_COLORS } from './builderDefaults'
+import { SAMPLE_COLOR_SCALE } from '../utils/color'
 import {
   idFromName,
   timepointId,
@@ -36,7 +36,7 @@ export function createTimeCourseTemplate(
     return {
       id: idFromName(condition, `condition-${index + 1}`),
       name: condition,
-      color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+      color: SAMPLE_COLOR_SCALE[index % SAMPLE_COLOR_SCALE.length],
       metadata: {},
     }
   })

package/src/templates/wellPlateScreenCollectionBuilder.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_SAMPLE_COLORS } from './builderDefaults'
+import { SAMPLE_COLOR_SCALE } from '../utils/color'
 import { createDoseResponseTemplate } from './doseResponseBuilder'
 import { createPlateMapTemplate } from './plateMapBuilder'
 import { createSampleSheetTemplate } from './sampleSheetBuilder'
@@ -19,7 +19,7 @@ export function createWellPlateScreenCollection(
     samples: sampleRecords.map((sample, index) => ({
       id: sample.sampleId,
       name: sample.name ?? sample.sampleId,
-      color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+      color: SAMPLE_COLOR_SCALE[index % SAMPLE_COLOR_SCALE.length],
     })),
   })
   const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })

package/src/types/auth.ts

@@ -6,6 +6,7 @@ export interface AuthConfig {
   passkeyEnabled: boolean
   passkeyRegistered: boolean
   registrationEnabled: boolean
+  databaseMode: string
   experimentVisibilityMode?: 'open' | 'restricted'
 }
 

package/src/types/form-builder.ts

@@ -11,6 +11,7 @@ export type FormFieldType =
   | 'text'
   | 'email'
   | 'password'
+  | 'secret'
   | 'number'
   | 'tel'
   | 'url'

package/src/utils/color.ts

@@ -1,3 +1,54 @@
+/**
+ * Shared color scales and color math for the MINT SDK.
+ *
+ * ## Why the exported values are hex, not `var(--…)`
+ *
+ * Every scale below is mirrored by a CSS custom property in
+ * `styles/variables.css` (`--mint-sample-1…9`, `--mint-slot-r/g/b/y`), so
+ * stylesheets and `:style` bindings can stay theme-aware by referencing the
+ * token. The JavaScript constants deliberately carry the plain hex **fallback**
+ * for the same slot, because these values are also
+ *
+ * - persisted into experiment design data (`SampleType.color`), where a
+ *   `var(--…)` string would be meaningless outside the browser, and
+ * - handed to canvas / SVG / export code paths, which cannot resolve CSS
+ *   custom properties.
+ *
+ * Keep the two in sync: a change here must be mirrored in `variables.css`.
+ */
+
+import type { SlotPosition } from '../types/componentLabTypes'
+
+/**
+ * Canonical categorical scale for sample types, plate maps, dose-response
+ * series and legends. Mirrors `--mint-sample-1` … `--mint-sample-9`.
+ */
+export const SAMPLE_COLOR_SCALE: readonly string[] = [
+  '#3B82F6', // blue
+  '#10B981', // green
+  '#EF4444', // red
+  '#F59E0B', // amber
+  '#8B5CF6', // purple
+  '#F97316', // orange
+  '#06B6D4', // cyan
+  '#14B8A6', // teal
+  '#6B7280', // gray
+]
+
+/**
+ * Slot-position colors shared by `PlateMapEditor` and `RackEditor`.
+ * Mirrors `--mint-slot-r`, `--mint-slot-g`, `--mint-slot-b`, `--mint-slot-y`.
+ */
+export const SLOT_COLORS: Record<SlotPosition, string> = {
+  R: '#ef4444', // red
+  G: '#22c55e', // green
+  B: '#3b82f6', // blue
+  Y: '#eab308', // yellow
+}
+
+/** Slot positions in their canonical display order. */
+export const SLOT_ORDER: readonly SlotPosition[] = ['R', 'G', 'B', 'Y']
+
 /**
  * Color utilities for deriving same-hue-family shades.
  *

package/src/utils/errors.ts

@@ -0,0 +1,29 @@
+/**
+ * The one place a thrown value is turned into a developer-facing message.
+ *
+ * Five copies of this logic drifted apart across the composables and stores
+ * (some checked a bare `{ message }` object, some did not); this export is the
+ * union of what they all accepted, so every caller now reads the same message
+ * from the same value.
+ */
+export function readErrorMessage(value: unknown, fallback = 'Request failed.'): string {
+  if (value instanceof Error && value.message) {
+    return value.message
+  }
+
+  if (typeof value === 'string' && value.trim()) {
+    return value
+  }
+
+  if (
+    typeof value === 'object'
+    && value !== null
+    && 'message' in value
+    && typeof (value as { message?: unknown }).message === 'string'
+    && (value as { message: string }).message.trim()
+  ) {
+    return (value as { message: string }).message
+  }
+
+  return fallback
+}

package/src/utils/formModelSync.ts

@@ -1,4 +1,5 @@
 import type { FormSchema } from '../types/form-builder'
+import { isRecord } from './records'
 
 export function recordValuesEqualForKeys(
   left: Record<string, unknown>,
@@ -47,6 +48,3 @@ function valuesEqual(left: unknown, right: unknown): boolean {
   return false
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}

package/src/utils/pluginIcon.ts

@@ -1,3 +1,4 @@
+import { isRecord } from './records'
 export type PluginIconFormat = 'path' | 'data-url' | 'asset-url' | 'structured' | 'fallback'
 
 export interface StructuredPluginIconStop {
@@ -177,9 +178,6 @@ function parseOffset(value: unknown): string | undefined {
   return undefined
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
 
 function isSafeColor(value: unknown): value is string {
   return typeof value === 'string' && COLOR_REGEX.test(value)

package/src/utils/pluginSecrets.ts

@@ -0,0 +1,102 @@
+/**
+ * Stable references for plugin secret settings.
+ *
+ * A settings response never carries a secret's value. Every secret leaf is a
+ * marker instead:
+ *
+ * - `{ "$secret": "sec_…", "set": true }` — a stored secret, referenced by a
+ *   stable opaque id. Send the marker back unchanged to keep the stored value.
+ * - `null` — nothing stored at that position.
+ * - `{ "$secret": null, "locked": true }` — the effective value comes from the
+ *   environment and is never written back.
+ *
+ * On save each secret leaf accepts the reference, a plain string (a new value),
+ * or `null` (clear). Payloads carry `secret_format: "ref"` so a `null` reads as
+ * a deliberate clear rather than the deprecated "unchanged" placeholder.
+ */
+
+/** Reserved marker key that references a stored secret. */
+export const PLUGIN_SECRET_REF_KEY = '$secret'
+
+/** Reserved payload key declaring which secret wire format a client speaks. */
+export const PLUGIN_SECRET_FORMAT_KEY = 'secret_format'
+
+/** Wire format published and understood by this SDK. */
+export const PLUGIN_SECRET_FORMAT_REF = 'ref'
+
+/** One `$secret` marker as published by a settings response. */
+export interface PluginSecretRef {
+  $secret: string | null
+  set?: boolean
+  locked?: boolean
+}
+
+/** What a settings form should tell the user about one secret field. */
+export type PluginSecretState = 'set' | 'unset' | 'environment'
+
+const MARKER_KEYS = new Set([PLUGIN_SECRET_REF_KEY, 'set', 'locked'])
+
+/** Return whether one settings value is a `$secret` reference marker. */
+export function isPluginSecretRef(value: unknown): value is PluginSecretRef {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  if (!(PLUGIN_SECRET_REF_KEY in record)) return false
+  return Object.keys(record).every(key => MARKER_KEYS.has(key))
+}
+
+/** Return the stored secret id behind a marker, or `null` when nothing is stored. */
+export function pluginSecretId(value: unknown): string | null {
+  if (!isPluginSecretRef(value)) return null
+  return typeof value.$secret === 'string' ? value.$secret : null
+}
+
+/** Classify one secret field for display: stored, unset, or environment-provided. */
+export function pluginSecretState(value: unknown): PluginSecretState {
+  if (isPluginSecretRef(value)) {
+    if (value.locked) return 'environment'
+    return typeof value.$secret === 'string' ? 'set' : 'unset'
+  }
+  return typeof value === 'string' && value.length > 0 ? 'set' : 'unset'
+}
+
+/** Human label for one secret field's state. */
+export function pluginSecretLabel(value: unknown): string {
+  const state = pluginSecretState(value)
+  if (state === 'environment') return 'Provided by environment'
+  return state === 'set' ? 'Set' : 'Not set'
+}
+
+/** Whether a secret field is read-only because the environment supplies it. */
+export function isPluginSecretLocked(value: unknown): boolean {
+  return isPluginSecretRef(value) && value.locked === true
+}
+
+/**
+ * Value to submit for an untouched secret field: the reference, unchanged.
+ *
+ * A locked marker round-trips too, which is how the platform keeps a stored
+ * value that an environment variable currently hides.
+ */
+export function keepPluginSecret(current: unknown): PluginSecretRef | null {
+  if (isPluginSecretRef(current)) return { ...current }
+  return null
+}
+
+/** Value to submit when the user typed a new secret. */
+export function setPluginSecret(value: string): string {
+  return value
+}
+
+/** Value to submit when the user cleared a secret. */
+export function clearPluginSecret(): null {
+  return null
+}
+
+/** Whether a settings response declares the `$secret` reference wire format. */
+export function usesPluginSecretReferences(response: unknown): boolean {
+  if (!response || typeof response !== 'object') return false
+  return (
+    (response as Record<string, unknown>)[PLUGIN_SECRET_FORMAT_KEY]
+      === PLUGIN_SECRET_FORMAT_REF
+  )
+}

package/src/utils/records.ts

@@ -0,0 +1,9 @@
+/** Narrow an unknown value to a plain object (arrays and null excluded). */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Narrow an unknown value to any non-null object, arrays included. */
+export function isObjectLike(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}