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

package/src/components/SecretInput.story.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import SecretInput from './SecretInput.vue'
+import type { PluginSecretRef } from '../utils/pluginSecrets'
+
+const sizes = ['sm', 'md', 'lg'] as const
+
+const storedRef: PluginSecretRef = { $secret: 'sec_0f2a4c6e8a0c2e4a6c8e0a2c4e6a8c0e', set: true }
+const lockedRef: PluginSecretRef = { $secret: null, locked: true }
+
+const stored = ref<PluginSecretRef | string | null>({ ...storedRef })
+const unset = ref<PluginSecretRef | string | null>(null)
+const locked = ref<PluginSecretRef | string | null>({ ...lockedRef })
+</script>
+
+<template>
+  <Story title="Base Inputs/SecretInput">
+    <Variant title="Playground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px;">
+          <SecretInput
+            v-model="state.value"
+            :placeholder="state.placeholder"
+            :disabled="state.disabled"
+            :error="state.error"
+            :size="state.size"
+          />
+          <p style="margin-top: 1rem; font-size: 0.875rem; color: var(--text-muted, #94a3b8);">
+            Submits: <code>{{ JSON.stringify(state.value) }}</code>
+          </p>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstText v-model="state.placeholder" title="Placeholder" />
+        <HstSelect
+          v-model="state.size"
+          title="Size"
+          :options="sizes.map(size => ({ label: size, value: size }))"
+        />
+        <HstCheckbox v-model="state.disabled" title="Disabled" />
+        <HstCheckbox v-model="state.error" title="Error" />
+      </template>
+
+      <template #initState>
+        {{ {
+          value: { $secret: 'sec_0f2a4c6e8a0c2e4a6c8e0a2c4e6a8c0e', set: true },
+          placeholder: 'Enter a new value',
+          disabled: false,
+          error: false,
+          size: 'md',
+        } }}
+      </template>
+    </Variant>
+
+    <Variant title="States">
+      <div style="padding: 2rem; max-width: 600px; display: flex; flex-direction: column; gap: 1.5rem;">
+        <div>
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em;">
+            Stored
+          </p>
+          <SecretInput v-model="stored" />
+        </div>
+        <div>
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em;">
+            Not set
+          </p>
+          <SecretInput v-model="unset" />
+        </div>
+        <div>
+          <p style="margin: 0 0 0.5rem; font-size: 0.75rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em;">
+            Provided by environment
+          </p>
+          <SecretInput v-model="locked" />
+        </div>
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/SecretInput.vue

@@ -0,0 +1,150 @@
+<script setup lang="ts">
+/** Edits one plugin secret setting: shows set / not set / provided by environment, and submits a `$secret` reference, a new value, or `null`. */
+import { computed, ref, watch } from 'vue'
+import BaseInput from './BaseInput.vue'
+import BaseButton from './BaseButton.vue'
+import {
+  clearPluginSecret,
+  isPluginSecretLocked,
+  isPluginSecretRef,
+  keepPluginSecret,
+  pluginSecretLabel,
+  pluginSecretState,
+  setPluginSecret,
+  type PluginSecretRef,
+  type PluginSecretState,
+} from '../utils/pluginSecrets'
+
+type SecretValue = PluginSecretRef | string | null
+
+interface Props {
+  /** The `$secret` marker from the settings response, a typed string, or `null`. */
+  modelValue?: SecretValue
+  placeholder?: string
+  disabled?: boolean
+  error?: boolean
+  size?: 'sm' | 'md' | 'lg'
+  /** Label on the control that starts entering a replacement value. */
+  changeLabel?: string
+  /** Label on the control that clears a stored secret. */
+  clearLabel?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  modelValue: null,
+  placeholder: 'Enter a new value',
+  disabled: false,
+  error: false,
+  size: 'md',
+  changeLabel: 'Change',
+  clearLabel: 'Clear',
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: SecretValue]
+}>()
+
+/** The reference this field started from, so an abandoned edit can restore it. */
+const storedReference = ref<PluginSecretRef | null>(keepPluginSecret(props.modelValue))
+const isEditing = ref(typeof props.modelValue === 'string')
+
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (isPluginSecretRef(value)) {
+      storedReference.value = keepPluginSecret(value)
+      isEditing.value = false
+    }
+  },
+)
+
+const state = computed<PluginSecretState>(() => pluginSecretState(props.modelValue))
+const locked = computed(() => isPluginSecretLocked(props.modelValue)
+  || isPluginSecretLocked(storedReference.value))
+const statusLabel = computed(() => isEditing.value
+  ? 'New value'
+  : pluginSecretLabel(props.modelValue))
+const typedValue = computed(() => typeof props.modelValue === 'string' ? props.modelValue : '')
+const canClear = computed(() => !locked.value && (state.value === 'set' || isEditing.value))
+
+function startEditing(): void {
+  if (props.disabled || locked.value) return
+  isEditing.value = true
+  emit('update:modelValue', setPluginSecret(''))
+}
+
+function updateTyped(value: string | number | null): void {
+  emit('update:modelValue', setPluginSecret(value == null ? '' : String(value)))
+}
+
+function cancelEditing(): void {
+  isEditing.value = false
+  emit('update:modelValue', storedReference.value ? { ...storedReference.value } : null)
+}
+
+function clear(): void {
+  if (props.disabled || locked.value) return
+  isEditing.value = false
+  storedReference.value = null
+  emit('update:modelValue', clearPluginSecret())
+}
+</script>
+
+<template>
+  <div class="mint-secret-input" :class="{ 'mint-secret-input--error': error }">
+    <div class="mint-secret-input__status">
+      <span
+        class="mint-secret-input__badge"
+        :class="`mint-secret-input__badge--${isEditing ? 'pending' : state}`"
+      >{{ statusLabel }}</span>
+      <span v-if="locked" class="mint-secret-input__hint">
+        This value comes from the environment and cannot be edited here.
+      </span>
+    </div>
+
+    <BaseInput
+      v-if="isEditing"
+      type="password"
+      autocomplete="new-password"
+      :model-value="typedValue"
+      :placeholder="placeholder"
+      :disabled="disabled"
+      :error="error"
+      :size="size"
+      @update:model-value="updateTyped"
+    />
+
+    <div class="mint-secret-input__actions">
+      <BaseButton
+        v-if="!isEditing"
+        type="button"
+        variant="secondary"
+        :size="size === 'lg' ? 'md' : 'sm'"
+        :disabled="disabled || locked"
+        @click="startEditing"
+      >
+        {{ changeLabel }}
+      </BaseButton>
+      <BaseButton
+        v-else
+        type="button"
+        variant="ghost"
+        :size="size === 'lg' ? 'md' : 'sm'"
+        :disabled="disabled"
+        @click="cancelEditing"
+      >
+        Cancel
+      </BaseButton>
+      <BaseButton
+        v-if="canClear"
+        type="button"
+        variant="ghost"
+        :size="size === 'lg' ? 'md' : 'sm'"
+        :disabled="disabled"
+        @click="clear"
+      >
+        {{ clearLabel }}
+      </BaseButton>
+    </div>
+  </div>
+</template>

package/src/components/index.ts

@@ -7,12 +7,14 @@ export { default as BaseCheckbox } from './BaseCheckbox.vue'
 export { default as BaseToggle } from './BaseToggle.vue'
 export { default as BaseRadioGroup } from './BaseRadioGroup.vue'
 export { default as BaseSlider } from './BaseSlider.vue'
+/** Range slider with a gradient color track and color-coded value badge for threshold visualization. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `BaseSlider` instead. */
 export { default as ColorSlider } from './ColorSlider.vue'
 export { default as BaseTabs } from './BaseTabs.vue'
 export { default as BaseModal } from './BaseModal.vue'
 export { default as SegmentedControl } from './SegmentedControl.vue'
 export { default as MultiSelect } from './MultiSelect.vue'
 export { default as BasePill } from './BasePill.vue'
+/** Button that opens a dropdown menu for selecting one option from a list. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `ActionMenu` instead. */
 export { default as DropdownButton } from './DropdownButton.vue'
 export { default as Calendar } from './Calendar.vue'
 export { default as DataFrame } from './DataFrame.vue'
@@ -22,6 +24,7 @@ export { default as FormField } from './FormField.vue'
 export { default as DatePicker } from './DatePicker.vue'
 export { default as TimePicker } from './TimePicker.vue'
 export { default as TagsInput } from './TagsInput.vue'
+export { default as SecretInput } from './SecretInput.vue'
 export { default as NumberInput } from './NumberInput.vue'
 export { default as FileUploader } from './FileUploader.vue'
 
@@ -97,11 +100,15 @@ export { default as ProtocolStepEditor } from './ProtocolStepEditor.vue'
 
 // Scientific display components
 export { default as ScientificNumber } from './ScientificNumber.vue'
+/** Renders a chemical formula string (H₂O, C₆H₁₂O₆, Ca(OH)₂) with typographically correct subscripts and superscripts for charges. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; no platform replacement is planned. */
 export { default as ChemicalFormula } from './ChemicalFormula.vue'
 export { default as SequenceProgressBar } from './SequenceProgressBar.vue'
+/** Filterable instrument alert/event list keyed by each alert's required stable event_key. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; instrument UI moves to the mld-ms plugins. */
 export { default as InstrumentAlertLog } from './InstrumentAlertLog.vue'
 export { default as InstrumentStateBadge } from './InstrumentStateBadge.vue'
+/** Compact card for live instrument monitor status, sample, method, sequence progress, and ETA. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; instrument UI moves to the mld-ms plugins. */
 export { default as InstrumentStatusCard } from './InstrumentStatusCard.vue'
+/** Table for Xcalibur-compatible LCMS sequence rows with optional reorder/remove/duplicate controls. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; instrument UI moves to the mld-ms plugins. */
 export { default as LcmsSequenceTable } from './LcmsSequenceTable.vue'
 
 // Scientific input components
@@ -125,8 +132,10 @@ export { default as ExperimentCodeBadge } from './ExperimentCodeBadge.vue'
 
 // Scheduling / booking components
 export { default as DateTimePicker } from './DateTimePicker.vue'
+/** Paired start/end time pickers that validate range order and display computed duration. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `TimePicker` instead. */
 export { default as TimeRangeInput } from './TimeRangeInput.vue'
 export { default as ScheduleCalendar } from './ScheduleCalendar.vue'
+/** Card displaying a lab resource with availability status, specs, tags, and a book action. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; no platform replacement is planned. */
 export { default as ResourceCard } from './ResourceCard.vue'
 export { default as SectionCard } from './SectionCard.vue'
 

package/src/components/internal/WellEditPopupInternal.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
-import { ref, watch, computed } from 'vue'
+import { onBeforeUnmount, onMounted, ref, watch, computed } from 'vue'
 import type { Well, WellEditData, WellEditField } from '../../types'
 import { useEventListener } from '../../composables/useEventListener'
+import { useFocusTrap } from '../../composables/useFocusTrap'
 
 interface Props {
   wellId: string
@@ -86,6 +87,22 @@ function handleKeydown(e: KeyboardEvent) {
 
 useEventListener(() => document, 'keydown', handleKeydown)
 
+// The popup has no open/close prop of its own — the parent mounts and unmounts it —
+// so the trap activates on mount and releases (restoring focus) just before unmount,
+// the same lifecycle BaseModal drives off `modelValue`.
+const containerRef = ref<HTMLElement | null>(null)
+const trapActive = ref(false)
+
+useFocusTrap({ containerRef, active: trapActive })
+
+onMounted(() => {
+  trapActive.value = true
+})
+
+onBeforeUnmount(() => {
+  trapActive.value = false
+})
+
 const sampleTypeButtons = [
   { type: 'sample', label: 'S', tooltip: 'Sample' },
   { type: 'blank', label: 'B', tooltip: 'Blank' },
@@ -101,8 +118,10 @@ const sampleTypeButtons = [
 
     <!-- Popup -->
     <div
+      ref="containerRef"
       class="mint-well-edit-popup"
       :style="popupStyle"
+      tabindex="-1"
       @click.stop
     >
       <!-- Header -->

package/src/components/internal/WorkspaceControlsInternal.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+/**
+ * Internal: renders PluginWorkspaceView's default (main content) slot bound to the
+ * control-schema-derived scoped-slot payload (active view, values, component bindings/props).
+ * Not part of the public SDK surface — see PluginWorkspaceView.vue for the public component.
+ */
+import type { PluginWorkspaceControlsModel } from '../../composables/pluginWorkspaceModel'
+
+defineProps<{
+  controls: PluginWorkspaceControlsModel
+}>()
+
+defineSlots<{
+  default?: (props: PluginWorkspaceControlsModel) => unknown
+}>()
+</script>
+
+<template>
+  <slot v-bind="controls" />
+</template>

package/src/components/internal/WorkspaceShellInternal.vue

@@ -0,0 +1,125 @@
+<script setup lang="ts">
+/**
+ * Internal: AppLayout + AppTopBar for PluginWorkspaceView, driven by a single `shell` model.
+ * Owns the responsive/collapse layout props and the top bar's default rendering; the caller
+ * decides whether to override the `topbar`/`sidebar` slots and supplies the sidebar content.
+ * Not part of the public SDK surface — see PluginWorkspaceView.vue for the public component.
+ */
+import type {
+  AccountMenuItem,
+  PageSelectorItem,
+  PillNavItem,
+  PillNavOption,
+  PluginSwitcherPlugin,
+} from '../../types'
+import AppLayout from '../AppLayout.vue'
+import AppTopBar from '../AppTopBar.vue'
+import type { PluginWorkspaceShellModel } from '../../composables/pluginWorkspaceModel'
+
+defineProps<{
+  shell: PluginWorkspaceShellModel
+}>()
+
+const emit = defineEmits<{
+  'page-selector-select': [page: PageSelectorItem]
+  'pill-select': [item: PillNavItem]
+  'pill-option-select': [option: PillNavOption, item: PillNavItem]
+  'plugin-switcher-select': [plugin: PluginSwitcherPlugin]
+  'plugin-switcher-install': []
+  'account-menu-select': [item: AccountMenuItem]
+  'sign-out': []
+  'notifications-click': []
+  'settings-values-change': [data: Record<string, unknown>]
+  'admin-click': []
+}>()
+
+function handlePillOptionSelect(option: PillNavOption, item: PillNavItem) {
+  emit('pill-option-select', option, item)
+}
+
+defineSlots<{
+  topbar?: (props: PluginWorkspaceShellModel['controls']) => unknown
+  sidebar?: (props: PluginWorkspaceShellModel['controls']) => unknown
+  default?: (props: PluginWorkspaceShellModel['controls']) => unknown
+  icon?: (props: Record<string, unknown>) => unknown
+  logo?: (props: Record<string, unknown>) => unknown
+  'page-selector-icon'?: (props: Record<string, unknown>) => unknown
+  'page-selector-item-icon'?: (props: Record<string, unknown>) => unknown
+  nav?: (props: Record<string, unknown>) => unknown
+  center?: (props: Record<string, unknown>) => unknown
+  actions?: (props: Record<string, unknown>) => unknown
+  'account-menu-items'?: (props: Record<string, unknown>) => unknown
+  'account-menu-item-icon'?: (props: Record<string, unknown>) => unknown
+  'settings-appearance'?: (props: Record<string, unknown>) => unknown
+}>()
+</script>
+
+<template>
+  <AppLayout
+    class="mint-plugin-workspace-view"
+    :sidebar-position="shell.sidebarPosition"
+    :sidebar-width="shell.sidebarWidth"
+    :floating="shell.floating"
+    :responsive-sidebar="shell.responsiveSidebar"
+    :sidebar-toggle-label="shell.sidebarToggleLabel"
+    :sidebar-close-label="shell.sidebarCloseLabel"
+  >
+    <template #topbar>
+      <slot name="topbar" v-bind="shell.controls">
+        <AppTopBar
+          :title="shell.title"
+          :subtitle="shell.subtitle"
+          :variant="shell.topBarVariant"
+          :home-path="shell.homePath"
+          :show-logo="shell.showLogo"
+          :page-selector="shell.pageSelector"
+          :current-page-selector-id="shell.currentPageSelectorId"
+          :plugin-switcher="shell.pluginSwitcher"
+          :pill-nav="shell.pillNav"
+          :current-pill-id="shell.currentPillId"
+          :show-theme-toggle="shell.showThemeToggle"
+          :show-settings="shell.showSettings"
+          :settings-config="shell.settingsConfig"
+          :show-standalone-label="shell.showStandaloneLabel"
+          :standalone-label="shell.standaloneLabel"
+          :account-menu="shell.accountMenu"
+          :show-notifications="shell.showNotifications"
+          :has-notification-dot="shell.hasNotificationDot"
+          :show-admin="shell.showAdmin"
+          :admin-path="shell.adminPath"
+          :user-name="shell.userName"
+          :user-initial="shell.userInitial"
+          :user-email="shell.userEmail"
+          @page-selector-select="emit('page-selector-select', $event)"
+          @pill-select="emit('pill-select', $event)"
+          @pill-option-select="handlePillOptionSelect"
+          @plugin-switcher-select="emit('plugin-switcher-select', $event)"
+          @plugin-switcher-install="emit('plugin-switcher-install')"
+          @account-menu-select="emit('account-menu-select', $event)"
+          @sign-out="emit('sign-out')"
+          @notifications-click="emit('notifications-click')"
+          @settings-values-change="emit('settings-values-change', $event)"
+          @admin-click="emit('admin-click')"
+        >
+          <template
+            v-for="slotName in shell.topBarSlotNames"
+            :key="slotName"
+            #[slotName]="slotProps"
+          >
+            <!-- @vue-ignore dynamic SDK slot forwarding for AppTopBar passthrough slots -->
+            <slot
+              :name="slotName"
+              v-bind="slotProps ?? {}"
+            />
+          </template>
+        </AppTopBar>
+      </slot>
+    </template>
+
+    <template v-if="shell.hasSidebarSurface" #sidebar>
+      <slot name="sidebar" v-bind="shell.controls" />
+    </template>
+
+    <slot v-bind="shell.controls" />
+  </AppLayout>
+</template>

package/src/components/internal/WorkspaceSidebarInternal.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+/**
+ * Internal: AppSidebar for PluginWorkspaceView, driven by a single `sidebar` model covering
+ * chrome, panels/forms, collapse behavior, and the compact control-schema props that drive
+ * AppSidebar's auto-generated form.
+ * Not part of the public SDK surface — see PluginWorkspaceView.vue for the public component.
+ */
+import AppSidebar from '../AppSidebar.vue'
+import type { PluginWorkspaceSidebarModel } from '../../composables/pluginWorkspaceModel'
+
+defineProps<{
+  sidebar: PluginWorkspaceSidebarModel
+}>()
+
+defineEmits<{
+  'update:modelValue': [values: Record<string, unknown>]
+  'update:collapsed': [value: boolean]
+  'update:toggle': [sectionId: string, value: boolean]
+  'section-action': [sectionId: string, actionId: string]
+  'form-submit': [sectionId: string, values: Record<string, unknown>]
+  'form-cancel': [sectionId: string]
+}>()
+
+defineSlots<{
+  header?: (props: Record<string, unknown>) => unknown
+  collapsed?: (props: Record<string, unknown>) => unknown
+  'collapsed-footer'?: (props: Record<string, unknown>) => unknown
+  footer?: (props: Record<string, unknown>) => unknown
+}>()
+</script>
+
+<template>
+  <AppSidebar
+    :title="sidebar.title"
+    :subtitle="sidebar.subtitle"
+    :badge="sidebar.badge"
+    :variant="sidebar.variant"
+    :panels="sidebar.panels"
+    :active-view="sidebar.activeView"
+    :floating="sidebar.floating"
+    :dense="sidebar.dense"
+    :width="sidebar.width"
+    :side="sidebar.side"
+    :forms="sidebar.forms"
+    :content-id="sidebar.contentId"
+    :show-when-empty="sidebar.showWhenEmpty"
+    :model="sidebar.model"
+    :controls="sidebar.controlSchema"
+    :control-options="sidebar.controlOptions"
+    :values="sidebar.values"
+    :form-enhancements="sidebar.formEnhancements"
+    :show-form-actions="sidebar.showFormActions"
+    :form-loading="sidebar.formLoading"
+    :form-disabled="sidebar.formDisabled"
+    :form-readonly="sidebar.formReadonly"
+    :form-size="sidebar.formSize"
+    :collapsible="sidebar.collapsible"
+    :collapsed="sidebar.collapsed"
+    :default-collapsed="sidebar.defaultCollapsed"
+    :collapsed-width="sidebar.collapsedWidth"
+    :collapse-button-label="sidebar.collapseButtonLabel"
+    :expand-button-label="sidebar.expandButtonLabel"
+    @update:model-value="$emit('update:modelValue', $event)"
+    @update:collapsed="$emit('update:collapsed', $event)"
+    @update:toggle="(sectionId, value) => $emit('update:toggle', sectionId, value)"
+    @section-action="(sectionId, actionId) => $emit('section-action', sectionId, actionId)"
+    @form-submit="(sectionId, values) => $emit('form-submit', sectionId, values)"
+    @form-cancel="$emit('form-cancel', $event)"
+  >
+    <template
+      v-for="slotName in sidebar.slotNames"
+      :key="slotName"
+      #[slotName]="slotProps"
+    >
+      <!-- @vue-ignore dynamic SDK slot forwarding for AppSidebar section-* passthrough slots -->
+      <slot
+        :name="slotName"
+        v-bind="slotProps ?? {}"
+      />
+    </template>
+  </AppSidebar>
+</template>

package/src/composables/experimentDesignData.ts

@@ -1,4 +1,5 @@
 import type { SelectOption } from '../types'
+import { isRecord } from '../utils/records'
 
 export interface ExperimentDesignDataResponse {
   experiment_id?: number
@@ -12,9 +13,6 @@ export interface ExtractExperimentSamplesOptions {
   includeControls?: boolean
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
 
 function isPlatformDesignDataResponse(value: Record<string, unknown>): boolean {
   return (

package/src/composables/flattenWorkspaceBindings.ts

@@ -0,0 +1,104 @@
+import { computed } from 'vue'
+import type { ComputedRef } from 'vue'
+import type {
+  BioTemplateComponentBinding,
+  BioTemplateComponentBindingsById,
+  BioTemplateComponentImport,
+  BioTemplateComponentPropsByComponent,
+  BioTemplateComponentPropsBinding,
+  BioTemplateComponentPropsById,
+  BioTemplateComponentPropsLookupOptions,
+  BioTemplateComponentSnippet,
+  BioTemplateComponentUsage,
+} from './useBioTemplateComponents'
+
+/**
+ * The template-component slice of `UseBioTemplateWorkspaceReturn`: the ~9 keys every
+ * bio-template workspace composable (`useBioTemplateWorkspace`, `useBioTemplatePackWorkspace`,
+ * `useBioTemplatePresetWorkspace`) re-exposes verbatim from `useBioTemplateComponents()`.
+ */
+export interface BioTemplateWorkspaceComponentBindings {
+  componentBindings: BioTemplateComponentBinding[]
+  componentBindingsById: BioTemplateComponentBindingsById
+  componentImports: BioTemplateComponentImport[]
+  componentProps: BioTemplateComponentPropsBinding[]
+  componentPropsById: BioTemplateComponentPropsById
+  componentPropsByComponent: BioTemplateComponentPropsByComponent
+  componentSnippets: BioTemplateComponentSnippet[]
+  componentUsage: BioTemplateComponentUsage | null
+  getComponentProps: (component: string, options?: BioTemplateComponentPropsLookupOptions) => Record<string, unknown> | undefined
+}
+
+/** Structural source shape accepted by {@link flattenWorkspaceComponentBindings}. */
+export interface BioTemplateWorkspaceComponentSource {
+  componentBindings: BioTemplateComponentBinding[]
+  componentBindingsById: BioTemplateComponentBindingsById
+  componentImports: BioTemplateComponentImport[]
+  componentProps: BioTemplateComponentPropsBinding[]
+  componentPropsById: BioTemplateComponentPropsById
+  componentPropsByComponent: BioTemplateComponentPropsByComponent
+  componentSnippets: BioTemplateComponentSnippet[]
+  componentUsage: BioTemplateComponentUsage | null
+  getComponentProps: (component: string, options?: BioTemplateComponentPropsLookupOptions) => Record<string, unknown> | undefined
+}
+
+/**
+ * Pick the shared template-component binding keys off a resolved bio-template workspace
+ * (or its `components` source directly), so composables that build on `useBioTemplateWorkspace`
+ * spread one object instead of re-listing all 9 keys by hand.
+ *
+ * @example Recommended
+ * ```ts
+ * const bindings = { renderer, ...flattenWorkspaceComponentBindings(components) }
+ * ```
+ */
+export function flattenWorkspaceComponentBindings(
+  source: BioTemplateWorkspaceComponentSource,
+): BioTemplateWorkspaceComponentBindings {
+  return {
+    componentBindings: source.componentBindings,
+    componentBindingsById: source.componentBindingsById,
+    componentImports: source.componentImports,
+    componentProps: source.componentProps,
+    componentPropsById: source.componentPropsById,
+    componentPropsByComponent: source.componentPropsByComponent,
+    componentSnippets: source.componentSnippets,
+    componentUsage: source.componentUsage,
+    getComponentProps: source.getComponentProps,
+  }
+}
+
+/** Keys of {@link BioTemplateWorkspaceComponentBindings} that are plain (non-reactive) values, lifted to `ComputedRef`s by {@link liftWorkspaceComponentBindings}. */
+export type LiftedBioTemplateWorkspaceComponentBindings =
+  { [K in Exclude<keyof BioTemplateWorkspaceComponentBindings, 'getComponentProps'>]: ComputedRef<BioTemplateWorkspaceComponentBindings[K]> }
+  & { getComponentProps: BioTemplateWorkspaceComponentBindings['getComponentProps'] }
+
+/**
+ * `computed()`-lifted version of {@link flattenWorkspaceComponentBindings} for composables
+ * that hold their resolved workspace behind a `ComputedRef` (e.g. a regenerated workspace
+ * swapped in via `shallowRef`/`effectScope`), so each key stays independently reactive
+ * instead of forcing consumers to unwrap the whole workspace to read one field.
+ * `getComponentProps` stays a plain callable function, matching the un-lifted composables.
+ *
+ * @example Recommended
+ * ```ts
+ * const workspace = computed(() => workspaceRef.value)
+ * const { componentBindings, componentProps, getComponentProps } = liftWorkspaceComponentBindings(workspace)
+ * ```
+ */
+export function liftWorkspaceComponentBindings<TSource extends BioTemplateWorkspaceComponentSource>(
+  workspace: ComputedRef<TSource>,
+): LiftedBioTemplateWorkspaceComponentBindings {
+  return {
+    componentBindings: computed(() => workspace.value.componentBindings),
+    componentBindingsById: computed(() => workspace.value.componentBindingsById),
+    componentImports: computed(() => workspace.value.componentImports),
+    componentProps: computed(() => workspace.value.componentProps),
+    componentPropsById: computed(() => workspace.value.componentPropsById),
+    componentPropsByComponent: computed(() => workspace.value.componentPropsByComponent),
+    componentSnippets: computed(() => workspace.value.componentSnippets),
+    componentUsage: computed(() => workspace.value.componentUsage),
+    getComponentProps: (component: string, options?: BioTemplateComponentPropsLookupOptions) =>
+      workspace.value.getComponentProps(component, options),
+  }
+}