@morscherlab/mint-sdk 1.2.0-beta.2 → 1.2.0-beta.20

package/src/composables/filePicker/usePickerSelection.ts

@@ -0,0 +1,259 @@
+import { computed, ref, shallowRef, watch } from 'vue'
+import type {
+  PickerCapability,
+  PickerExcluded,
+  PickerFile,
+  PickerNode,
+  PickerSelection,
+  PickerSelectionMode,
+} from '../../types/filePicker'
+import type { usePickerNavigation } from './usePickerNavigation'
+import { pickerExclusion } from './validation'
+
+type Navigation = ReturnType<typeof usePickerNavigation>
+export function usePickerSelection(
+  nav: Navigation,
+  mode: () => PickerSelectionMode,
+  capability: () => PickerCapability | undefined,
+  skipBlanks: () => boolean,
+) {
+  const keys = ref(new Set<string>())
+  const dropped = ref(new Set<string>())
+  const focusPath = shallowRef('')
+  const resolving = shallowRef(false)
+  const resolutionError = shallowRef('')
+  let anchor = ''
+  let generation = 0
+
+  function ancestorSelected(node: PickerNode, candidates = keys.value): boolean {
+    const seen = new Set<string>()
+    let parent = node.parentPath
+    while (parent && !seen.has(parent)) {
+      if (candidates.has(parent)) return true
+      seen.add(parent)
+      parent = nav.nodes.value.get(parent)?.parentPath
+    }
+    return false
+  }
+  function exclusion(node: PickerNode) {
+    if (!nav.isAllowed(node))
+      return { path: node.path, name: node.name, reason: 'forbidden' as const }
+    const own = pickerExclusion(node, capability(), skipBlanks())
+    if (own) return own
+    const seen = new Set<string>()
+    let parent = node.parentPath
+    while (parent && !seen.has(parent)) {
+      seen.add(parent)
+      const folder = nav.nodes.value.get(parent)
+      if (!folder) break
+      const inherited = pickerExclusion(folder, capability(), skipBlanks())
+      if (inherited) return { ...inherited, path: node.path, name: node.name }
+      parent = folder.parentPath
+    }
+    return null
+  }
+  function selected(node: PickerNode): boolean {
+    return (
+      !exclusion(node) &&
+      !dropped.value.has(node.path) &&
+      !ancestorSelected(node, dropped.value) &&
+      (keys.value.has(node.path) || (mode() === 'folder+files' && ancestorSelected(node)))
+    )
+  }
+  function selectable(node: PickerNode): boolean {
+    if (exclusion(node)) return false
+    return node.kind === 'folder'
+      ? mode() === 'folder' || mode() === 'folder+files'
+      : mode() !== 'folder'
+  }
+  function select(
+    node: PickerNode,
+    modifiers: { metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean; toggle?: boolean } = {},
+  ) {
+    if (exclusion(node)) return
+    focusPath.value = node.path
+    if (!selectable(node)) return
+    const multi = mode() === 'multi-file' || mode() === 'folder+files'
+    // Multi modes behave like a checklist: a plain click (or Space) adds or
+    // removes one row, Shift extends a range, Ctrl/Cmd is accepted for habit.
+    const additive = multi && (modifiers.metaKey || modifiers.ctrlKey || modifiers.toggle)
+    if (multi && modifiers.shiftKey && anchor) {
+      const rows = nav.rows.value.map((row) => row.node)
+      const from = rows.findIndex((item) => item.path === anchor)
+      const to = rows.findIndex((item) => item.path === node.path)
+      if (from >= 0 && to >= 0) {
+        keys.value = new Set([
+          ...(additive ? keys.value : []),
+          ...rows
+            .slice(Math.min(from, to), Math.max(from, to) + 1)
+            .filter(selectable)
+            .map((item) => item.path),
+        ])
+        dropped.value.clear()
+        return
+      }
+    }
+    if (additive || (modifiers.toggle && (selected(node) || dropped.value.has(node.path)))) {
+      if (mode() === 'folder+files' && ancestorSelected(node)) {
+        if (dropped.value.has(node.path)) dropped.value.delete(node.path)
+        else dropped.value.add(node.path)
+      } else if (keys.value.has(node.path)) keys.value.delete(node.path)
+      else {
+        keys.value.add(node.path)
+        dropped.value.delete(node.path)
+      }
+    } else {
+      keys.value = new Set([node.path])
+      dropped.value.clear()
+    }
+    anchor = node.path
+  }
+  function reset(selection?: PickerSelection | null) {
+    ++generation
+    keys.value.clear()
+    dropped.value.clear()
+    resolving.value = false
+    resolutionError.value = ''
+    focusPath.value = ''
+    if (selection?.source === 'server') {
+      const files =
+        mode() === 'folder'
+          ? []
+          : mode() === 'single-file'
+            ? selection.files.slice(0, 1)
+            : selection.files
+      const folders =
+        mode() === 'folder'
+          ? selection.folders.slice(0, 1)
+          : mode() === 'folder+files'
+            ? selection.folders
+            : []
+      nav.register(files)
+      folders.forEach((path) => {
+        if (!nav.nodes.value.has(path))
+          nav.register([
+            { kind: 'folder', path, name: 'Selected folder', parentName: 'Selected location' },
+          ])
+        keys.value.add(path)
+      })
+      files.forEach((file) => keys.value.add(file.path))
+      selection.excluded
+        .filter((item) => item.reason === 'deselected')
+        .forEach((item) => dropped.value.add(item.path))
+    }
+  }
+  const roots = computed(() =>
+    [...keys.value]
+      .map((key) => nav.nodes.value.get(key))
+      .filter((node): node is PickerNode => !!node && !ancestorSelected(node) && nav.isAllowed(node)),
+  )
+  const chosen = computed(() => {
+    const files: PickerFile[] = []
+    const excluded: PickerExcluded[] = []
+    for (const node of nav.nodes.value.values()) {
+      if (!nav.isAllowed(node)) continue
+      if (!keys.value.has(node.path) && !ancestorSelected(node)) continue
+      const reason =
+        exclusion(node) ??
+        (dropped.value.has(node.path)
+          ? { path: node.path, name: node.name, reason: 'deselected' as const }
+          : null)
+      // A dropped folder excludes its descendants as well.
+      const droppedByParent = ancestorSelected(node, dropped.value)
+      if (reason || droppedByParent) {
+        if (node.kind === 'file' || reason?.reason === 'unreadable')
+          excluded.push(reason ?? { path: node.path, name: node.name, reason: 'deselected' })
+      } else if (node.kind === 'file') files.push(node)
+    }
+    return { files, excluded, bytes: files.reduce((total, node) => total + (node.bytes ?? 0), 0) }
+  })
+  async function resolve() {
+    const token = ++generation
+    resolving.value = true
+    resolutionError.value = ''
+    let count = 0
+    const seen = new Set<string>()
+    async function walk(node: PickerNode, ancestors: string[] = []): Promise<PickerFile[]> {
+      if (token !== generation) throw new DOMException('Cancelled', 'AbortError')
+      if (!nav.isAllowed(node)) return []
+      if (node.kind === 'file') return [node]
+      if (node.unavailableReason) return []
+      if (ancestors.includes(node.path))
+        throw new Error('The adapter returned a circular folder tree.')
+      if (seen.has(node.path)) return []
+      seen.add(node.path)
+      if (++count > 500 || ancestors.length > 30)
+        throw new Error('This selection is too large to validate. Choose a smaller folder.')
+      const children = await nav.loadChildren(node.path, ancestors)
+      const files: PickerFile[] = []
+      for (const child of children) files.push(...(await walk(child, [...ancestors, node.path])))
+      if (token !== generation) throw new DOMException('Cancelled', 'AbortError')
+      const formats: Record<string, number> = {}
+      files.forEach((file) => {
+        formats[file.format] = (formats[file.format] ?? 0) + 1
+      })
+      nav.register([
+        {
+          ...node,
+          fileCount: files.length,
+          bytes: files.reduce((sum, file) => sum + (file.bytes ?? 0), 0),
+          formats,
+        },
+      ])
+      return files
+    }
+    try {
+      for (const node of roots.value) await walk(node)
+      if (token === generation) {
+        // Resolved descendants inherit their folder, including restored selections.
+        for (const key of [...keys.value]) {
+          const node = nav.nodes.value.get(key)
+          if (node && ancestorSelected(node)) keys.value.delete(key)
+        }
+      }
+    } catch (cause) {
+      if (token === generation)
+        resolutionError.value =
+          cause instanceof Error ? cause.message : 'Could not validate the selection.'
+    } finally {
+      if (token === generation) resolving.value = false
+    }
+  }
+  const focused = computed(() => {
+    const node = nav.nodes.value.get(focusPath.value)
+    return node && nav.isAllowed(node) ? node : roots.value[roots.value.length - 1] ?? null
+  })
+  watch(
+    () => new Map([...nav.nodes.value].map(([path, node]) => [path, nav.isAllowed(node)])),
+    (allowed, previous) => {
+      if (keys.value.size && [...allowed].some(([path, value]) =>
+        previous.has(path) && value !== previous.get(path),
+      )) void resolve()
+    },
+  )
+  function folderProgress(node: PickerNode): string {
+    if (node.kind !== 'folder' || node.fileCount == null) return ''
+    const allowed = chosen.value.files.filter((file) =>
+      ancestorSelected(file, new Set([node.path])),
+    ).length
+    return `${selected(node) ? allowed : 0} / ${node.fileCount}`
+  }
+  return {
+    keys,
+    dropped,
+    focusPath,
+    resolving,
+    resolutionError,
+    roots,
+    chosen,
+    focused,
+    select,
+    selected,
+    selectable,
+    exclusion,
+    reset,
+    resolve,
+    folderProgress,
+    ancestorSelected,
+  }
+}

package/src/composables/filePicker/validation.ts

@@ -0,0 +1,41 @@
+import type { PickerCapability, PickerExcluded, PickerNode } from '../../types/filePicker'
+
+export function normalizePickerFormat(format: string): string {
+  return format.trim().replace(/^\./, '').toLowerCase()
+}
+
+export function pickerExclusion(
+  node: PickerNode,
+  capability?: PickerCapability,
+  skipBlanks = false,
+): PickerExcluded | null {
+  const base = { path: node.path, name: node.name }
+  if (node.unavailableReason) return { ...base, reason: 'unreadable' }
+  if (skipBlanks && capability?.isBlank?.(node)) return { ...base, reason: 'blank' }
+  if (node.kind === 'folder') return null
+  const formats = capability?.formats.map(normalizePickerFormat) ?? []
+  if (formats.length && !formats.some((format) => node.name.toLowerCase().endsWith(`.${format}`))) {
+    return { ...base, reason: 'unsupported' }
+  }
+  if (capability?.maxBytes != null && node.bytes != null && node.bytes > capability.maxBytes) {
+    return { ...base, reason: 'tooLarge' }
+  }
+  return null
+}
+
+export function pickerReason(excluded: PickerExcluded | null, node?: PickerNode): string {
+  if (!excluded) return ''
+  return {
+    unsupported: 'This format is not supported by this source.',
+    tooLarge: 'This file exceeds the size limit for this source.',
+    blank: 'Skipped by the blank-file rule.',
+    unreadable: node?.unavailableReason || 'This item cannot be read.',
+    deselected: 'Removed from the selection.',
+    forbidden: 'This item is not permitted by the system filter.',
+  }[excluded.reason]
+}
+
+export function pickerFormat(name: string): string {
+  const compound = /\.(mzml|mzxml)\.gz$/i.exec(name)
+  return compound ? `${compound[1]}.gz` : name.includes('.') ? name.split('.').pop()! : ''
+}

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),
+  }
+}

package/src/composables/formBuilderRegistry.ts

@@ -2,6 +2,7 @@ import type { Component } from 'vue'
 import type { FormFieldType } from '../types/form-builder'
 
 import BaseInput from '../components/BaseInput.vue'
+import SecretInput from '../components/SecretInput.vue'
 import BaseTextarea from '../components/BaseTextarea.vue'
 import BaseSelect from '../components/BaseSelect.vue'
 import MultiSelect from '../components/MultiSelect.vue'
@@ -34,6 +35,7 @@ const registry: Record<FormFieldType, RegistryEntry> = {
   text: { component: BaseInput, defaults: { type: 'text' }, vModel: true },
   email: { component: BaseInput, defaults: { type: 'email' }, vModel: true },
   password: { component: BaseInput, defaults: { type: 'password' }, vModel: true },
+  secret: { component: SecretInput, defaults: {}, vModel: true },
   tel: { component: BaseInput, defaults: { type: 'tel' }, vModel: true },
   url: { component: BaseInput, defaults: { type: 'url' }, vModel: true },
   search: { component: BaseInput, defaults: { type: 'search' }, vModel: true },
@@ -75,6 +77,9 @@ export function getTypeDefault(type: FormFieldType): unknown {
     case 'multiselect':
     case 'tags':
       return []
+    case 'secret':
+      // A secret field has no empty string state: `null` means "not stored".
+      return null
     default:
       return ''
   }

package/src/composables/index.ts

@@ -153,6 +153,7 @@ export {
   type UseGeneratedAnalysisReturn,
 } from './useGeneratedAnalysis'
 export { useAutoGroup, DEFAULT_COLORS, extractSamplesFromDesignData } from './useAutoGroup'
+export { usePluginConfig, type UsePluginConfigReturn } from './usePluginConfig'
 export {
   useReagentSeries,
   generateDilutionSeries,
@@ -173,6 +174,11 @@ export {
   type UseAnalysisArtifactsOptions,
   type UseAnalysisArtifactsReturn,
 } from './useAnalysisArtifacts'
+export {
+  useFileBrowser,
+  type UseFileBrowserOptions,
+  type UseFileBrowserReturn,
+} from './useFileBrowser'
 export {
   buildAnalysisArtifactTargetQuery,
   parseAnalysisArtifactTarget,
@@ -487,6 +493,7 @@ export {
   pluginFormDataFromPayload,
   resolvePluginBaseUrl,
   uploadPluginEndpoint,
+  usePluginClient,
   usePluginEventStream,
   usePluginSettings,
   useCurrentExperiment,
@@ -515,9 +522,52 @@ export {
 export {
   combinePluginJobSources,
   usePluginJobCenter,
+  useJobsStatusTray,
   type CombinedPluginJobCenterSource,
+  type JobsStatusTrayAdapter,
+  type JobStreamMessage,
   type PluginJobCenterSource,
   type JobsStatusTrayTab,
+  type UseJobsStatusTrayOptions,
+  type UseJobsStatusTrayReturn,
   type UsePluginJobCenterOptions,
   type UsePluginJobCenterReturn,
 } from './useJobsStatusTray'
+export {
+  usePluginWorkspace,
+  type PluginWorkspaceSlotsLike,
+  type UsePluginWorkspaceOptions,
+  type UsePluginWorkspaceReturn,
+} from './usePluginWorkspace'
+export {
+  type PluginWorkspaceControlsModel,
+  type PluginWorkspaceShellModel,
+  type PluginWorkspaceSidebarModel,
+} from './pluginWorkspaceModel'
+export {
+  useFocusTrap,
+  type UseFocusTrapOptions,
+  type UseFocusTrapReturn,
+} from './useFocusTrap'
+export {
+  useRovingFocus,
+  type UseRovingFocusOptions,
+  type UseRovingFocusReturn,
+} from './useRovingFocus'
+export {
+  reorderList,
+  useListReorder,
+  useReorderAnnouncer,
+  REORDER_ANNOUNCER_STYLE,
+  type ListReorderMove,
+  type UseListReorderOptions,
+  type UseListReorderReturn,
+  type UseReorderAnnouncerReturn,
+} from './useListReorder'
+export {
+  useMenuKeyboard,
+  type UseMenuKeyboardOptions,
+  type UseMenuKeyboardReturn,
+} from './useMenuKeyboard'
+
+export { usePlatformFilePickerAdapter, encodePlatformPickerPath, decodePlatformPickerPath } from './usePlatformFilePickerAdapter'

package/src/composables/pluginWorkspaceModel.ts

@@ -0,0 +1,182 @@
+import type {
+  AccountMenuItem,
+  PageSelectorItemInput,
+  PillNavItemInput,
+  PluginSwitcherInfo,
+  SidebarToolSection,
+  TopBarSettingsConfig,
+  TopBarVariant,
+} from '../types'
+import type { FormEnhancements, FormSchema } from '../types/form-builder'
+import type {
+  ControlComponentBinding,
+  ControlComponentBindingsById,
+  ControlModel,
+  ControlModelBinding,
+  ControlSchema,
+  ControlWorkspaceOptions,
+} from './useControlSchema'
+import type { PluginWorkspaceSidebarVariant } from '../components/PluginWorkspaceView.props'
+
+/**
+ * Scoped-slot payload shared by PluginWorkspaceView's `default`, `topbar`, and `sidebar`
+ * slots: the resolved active view plus the values and component bindings/props derived
+ * from the compact control schema. WorkspaceControlsInternal renders a component's default
+ * slot bound to exactly this shape.
+ */
+export interface PluginWorkspaceControlsModel {
+  /** Currently resolved workspace view id. */
+  activeView: string
+  /** Sets the active view, updating any uncontrolled state and emitting `update:activeView`. */
+  setActiveView: (viewId: string) => void
+  /** Current control values, shared between the auto-rendered sidebar form and the default slot. */
+  values: Record<string, unknown>
+  /** Ordered SDK component bindings resolved from the current control values. */
+  componentBindings: ControlComponentBinding[]
+  /** SDK component bindings resolved from the current control values, keyed by binding id. */
+  componentBindingsById: ControlComponentBindingsById
+  /** Flat component props resolved from the current control values. */
+  componentProps: Record<string, unknown>
+  /** Named component prop mappings resolved from the current control values. */
+  componentPropsById: Record<string, Record<string, unknown>>
+}
+
+/**
+ * Resolved AppLayout + AppTopBar configuration consumed by WorkspaceShellInternal: top bar
+ * chrome and navigation, plus the AppLayout layout/collapse props that own the responsive
+ * mobile sidebar toggle.
+ */
+export interface PluginWorkspaceShellModel {
+  /** AppLayout sidebar position. */
+  sidebarPosition: 'left' | 'right'
+  /** AppLayout sidebar width, forwarded so the layout can reserve space before AppSidebar mounts. */
+  sidebarWidth?: string
+  /** AppLayout floating style. */
+  floating: boolean
+  /** Convert the sidebar into an SDK-owned mobile overlay below the AppLayout breakpoint. */
+  responsiveSidebar: boolean
+  /** Accessible label for the mobile sidebar toggle. */
+  sidebarToggleLabel: string
+  /** Accessible label used when the mobile sidebar is open. */
+  sidebarCloseLabel: string
+  /** Whether AppLayout should render a `#sidebar` template at all. */
+  hasSidebarSurface: boolean
+  /** App or plugin title shown in the top bar. */
+  title: string
+  /** Secondary copy shown under the title. */
+  subtitle?: string
+  /** Top bar visual treatment. */
+  topBarVariant: TopBarVariant
+  /** Home link used by the top bar brand icon. */
+  homePath: string
+  /** Show the default MINT logo when no icon/logo slot is provided. */
+  showLogo: boolean
+  /** Preferred route-level page selector entries. */
+  pageSelector?: PageSelectorItemInput[]
+  /** Resolved active page selector id. */
+  currentPageSelectorId: string
+  /** Optional plugin switcher shown in the left navigation position. */
+  pluginSwitcher?: PluginSwitcherInfo
+  /** Resolved centered pill navigation, generated from the control schema when omitted. */
+  pillNav?: PillNavItemInput[]
+  /** Resolved active centered pill id. */
+  currentPillId: string
+  /** Show the theme toggle button. */
+  showThemeToggle: boolean
+  /** Show the settings button and modal. */
+  showSettings: boolean
+  /** Built-in settings modal configuration. */
+  settingsConfig?: TopBarSettingsConfig
+  /** Show the standalone badge when not integrated into the platform. */
+  showStandaloneLabel: boolean
+  /** Custom standalone badge label. */
+  standaloneLabel: string
+  /** Account dropdown entries. */
+  accountMenu?: AccountMenuItem[]
+  /** Show the notifications icon button. */
+  showNotifications: boolean
+  /** Draw a notification dot on the notifications icon. */
+  hasNotificationDot: boolean
+  /** Show the admin shortcut. */
+  showAdmin: boolean
+  /** Route used by the admin shortcut. */
+  adminPath: string
+  /** Account display name. */
+  userName?: string
+  /** Explicit account avatar initial. */
+  userInitial?: string
+  /** Account email shown in the avatar menu. */
+  userEmail?: string
+  /** Names of AppTopBar passthrough slots the caller actually provided. */
+  topBarSlotNames: string[]
+  /** Scoped-slot payload exposed to the `topbar` override slot. */
+  controls: PluginWorkspaceControlsModel
+}
+
+/**
+ * Resolved AppSidebar configuration consumed by WorkspaceSidebarInternal: sidebar chrome,
+ * panels/forms, collapse behavior, and the compact control-schema props that drive
+ * AppSidebar's auto-generated form.
+ */
+export interface PluginWorkspaceSidebarModel {
+  /** Sidebar chrome title. */
+  title?: string
+  /** Sidebar chrome subtitle. */
+  subtitle?: string
+  /** Optional compact badge/count rendered in the sidebar header. */
+  badge?: string | number
+  /** AppSidebar visual preset. */
+  variant: PluginWorkspaceSidebarVariant
+  /** Map of view IDs to sidebar tool sections. */
+  panels: Record<string, SidebarToolSection[]>
+  /** Resolved active view, used to pick which panels/forms render. */
+  activeView: string
+  /** AppSidebar floating style (always false: PluginWorkspaceView docks the sidebar inside AppLayout). */
+  floating: boolean
+  /** Compact AppSidebar density. */
+  dense: boolean
+  /** Sidebar CSS width. */
+  width?: string
+  /** Sidebar position, mirrors the shell's `sidebarPosition`. */
+  side: 'left' | 'right'
+  /** Optional FormBuilder schemas keyed by section ID. */
+  forms: Record<string, FormSchema>
+  /** DOM id for the AppSidebar scrollable content area. */
+  contentId?: string
+  /** Render the sidebar shell even when no panel matches the active view. */
+  showWhenEmpty: boolean
+  /** Optional compact control model for the generated sidebar form. */
+  model?: ControlModel | ControlModelBinding
+  /** Compact control schema for the generated sidebar form. */
+  controlSchema?: ControlSchema
+  /** Options passed to compact control schema generation. */
+  controlOptions: ControlWorkspaceOptions
+  /** Shared values for the auto-rendered sidebar form. */
+  values: Record<string, unknown>
+  /** Runtime FormBuilder enhancements for the auto-rendered sidebar form. */
+  formEnhancements?: FormEnhancements<Record<string, unknown>>
+  /** Show submit/cancel actions inside the auto-rendered sidebar form. */
+  showFormActions: boolean
+  /** Loading/saving state for the auto-rendered sidebar form. */
+  formLoading: boolean
+  /** Disabled state for the auto-rendered sidebar form. */
+  formDisabled: boolean
+  /** Readonly state for the auto-rendered sidebar form. */
+  formReadonly: boolean
+  /** Size passed to the auto-rendered sidebar form. */
+  formSize: 'sm' | 'md' | 'lg'
+  /** Show a built-in collapse/expand button in the sidebar chrome. */
+  collapsible?: boolean
+  /** Controlled sidebar collapsed state. */
+  collapsed?: boolean
+  /** Initial sidebar collapsed state when uncontrolled. */
+  defaultCollapsed: boolean
+  /** Sidebar width when collapsed. */
+  collapsedWidth: string
+  /** Accessible label for the sidebar collapse action. */
+  collapseButtonLabel: string
+  /** Accessible label for the sidebar expand action. */
+  expandButtonLabel: string
+  /** Names of AppSidebar passthrough slots the caller actually provided. */
+  slotNames: string[]
+}