@morscherlab/mint-sdk 1.0.62 → 1.1.0-beta.1

package/src/composables/useJobsStatusTray.ts

@@ -26,6 +26,127 @@ import type {
 
 export type JobsStatusTrayTab = 'active' | 'history'
 
+/**
+ * The canonical owner of a collection of plugin jobs.
+ *
+ * Sources, rather than job-center UI, own polling, event streams, and all job
+ * mutations. This keeps components and consumers on one reactive job graph.
+ */
+export interface PluginJobCenterSource {
+  jobs: MaybeRefOrGetter<readonly JobStateInput[]>
+  refreshJobs?: () => Promise<JobListPayload | readonly JobStateInput[] | void>
+  cancelJob?: (jobId: string) => Promise<JobStateInput | void>
+  deleteJob?: (jobId: string) => Promise<boolean | void>
+  clearFinishedJobs?: () => Promise<number | void>
+  dispose?: () => void
+}
+
+export interface CombinedPluginJobCenterSource extends PluginJobCenterSource {
+  jobs: ComputedRef<readonly JobStateInput[]>
+}
+
+/**
+ * Combines independent job runtimes without copying their reactive state.
+ *
+ * Job ids must be globally unique across the sources. A duplicate id throws
+ * when jobs are read or an id-routed action is requested, rather than silently
+ * dispatching a mutation to the wrong owner.
+ */
+export function combinePluginJobSources(
+  sources: readonly PluginJobCenterSource[],
+): CombinedPluginJobCenterSource {
+  const jobs = computed<readonly JobStateInput[]>(() => {
+    const combined: JobStateInput[] = []
+    const owners = new Set<string>()
+    for (const source of sources) {
+      for (const job of toValue(source.jobs)) {
+        if (owners.has(job.job_id)) throw duplicatePluginJobId(job.job_id)
+        owners.add(job.job_id)
+        combined.push(job)
+      }
+    }
+    return combined
+  })
+
+  function ownerFor(jobId: string): PluginJobCenterSource {
+    let owner: PluginJobCenterSource | undefined
+    for (const source of sources) {
+      if (!toValue(source.jobs).some(job => job.job_id === jobId)) continue
+      if (owner) throw duplicatePluginJobId(jobId)
+      owner = source
+    }
+    if (!owner) throw new Error(`Unknown plugin job id: ${jobId}`)
+    return owner
+  }
+
+  const combined: CombinedPluginJobCenterSource = { jobs }
+  if (sources.some(source => source.refreshJobs)) {
+    combined.refreshJobs = async () => {
+      await Promise.all(sources.map(source => source.refreshJobs?.()))
+      return jobs.value
+    }
+  }
+  if (sources.some(source => source.cancelJob)) {
+    combined.cancelJob = async (jobId) => {
+      const owner = ownerFor(jobId)
+      if (!owner.cancelJob) throw new Error(`Job ${jobId} cannot be cancelled by its source`)
+      return owner.cancelJob(jobId)
+    }
+  }
+  if (sources.length > 0 && sources.every(source => source.deleteJob)) {
+    combined.deleteJob = async (jobId) => {
+      const owner = ownerFor(jobId)
+      if (!owner.deleteJob) throw new Error(`Job ${jobId} cannot be deleted by its source`)
+      return owner.deleteJob(jobId)
+    }
+  }
+  // Never report a successful combined clear after mutating only a subset.
+  // Without bulk support from every source, the job center can still fall
+  // back to this source's id-routed deleteJob method when all owners expose it.
+  if (sources.length > 0 && sources.every(source => source.clearFinishedJobs)) {
+    combined.clearFinishedJobs = async () => {
+      const results = await Promise.all(
+        sources.map(source => source.clearFinishedJobs!()),
+      )
+      return results.every((result): result is number => typeof result === 'number')
+        ? results.reduce((total, result) => total + result, 0)
+        : undefined
+    }
+  }
+  if (sources.some(source => source.dispose)) {
+    combined.dispose = () => {
+      const errors: unknown[] = []
+      for (const source of sources) {
+        try {
+          source.dispose?.()
+        } catch (cause) {
+          errors.push(cause)
+        }
+      }
+      if (errors.length === 1) throw errors[0]
+      if (errors.length > 1) throw new PluginJobSourceDisposeError(errors)
+    }
+  }
+  return combined
+}
+
+class PluginJobSourceDisposeError extends Error {
+  readonly cause: unknown
+  readonly errors: readonly unknown[]
+
+  constructor(errors: readonly unknown[]) {
+    super('Failed to dispose plugin job sources')
+    this.name = 'PluginJobSourceDisposeError'
+    this.cause = errors[0]
+    this.errors = Object.freeze([...errors])
+  }
+}
+
+function duplicatePluginJobId(jobId: string): Error {
+  return new Error(`Duplicate plugin job id across combined sources: ${jobId}`)
+}
+
+/** @deprecated Prefer a {@link PluginJobCenterSource}. */
 export interface JobsStatusTrayAdapter {
   listJobs?: () => Promise<JobListPayload | readonly JobStateInput[]>
   cancelJob?: (job: JobState) => Promise<JobStateInput | void>
@@ -33,24 +154,34 @@ export interface JobsStatusTrayAdapter {
   clearFinishedJobs?: (jobs: readonly JobState[]) => Promise<number | void>
 }
 
-export interface UseJobsStatusTrayOptions {
+export interface UsePluginJobCenterOptions {
+  source?: MaybeRefOrGetter<PluginJobCenterSource | undefined>
+  /** @deprecated Pass a source with its canonical jobs ref. */
   jobs?: MaybeRefOrGetter<readonly JobStateInput[] | undefined>
+  /** @deprecated Pass source actions instead. */
   adapter?: MaybeRefOrGetter<JobsStatusTrayAdapter | undefined>
+  /** @deprecated Event handling belongs to the source runtime. */
   eventStream?: MaybeRefOrGetter<UsePluginEventStreamReturn<JobStreamData> | undefined>
   loadOnMount?: boolean
 }
 
+export interface UseJobsStatusTrayOptions extends UsePluginJobCenterOptions {}
+
 export interface JobStreamMessage {
   event: string
   data: JobStreamData
 }
 
-export interface UseJobsStatusTrayReturn {
-  jobs: ShallowRef<JobState[]>
+export interface UsePluginJobCenterReturn {
+  jobs: ComputedRef<JobState[]>
   activeJobs: ComputedRef<JobState[]>
   historyJobs: ComputedRef<JobState[]>
   deletableJobs: ComputedRef<JobState[]>
   featuredJob: ComputedRef<JobState | null>
+  canRefresh: ComputedRef<boolean>
+  canCancel: ComputedRef<boolean>
+  canDelete: ComputedRef<boolean>
+  canClearFinished: ComputedRef<boolean>
   isOpen: Ref<boolean>
   activeTab: Ref<JobsStatusTrayTab>
   isLoading: Ref<boolean>
@@ -67,6 +198,13 @@ export interface UseJobsStatusTrayReturn {
   isPending: (job: JobState) => boolean
 }
 
+export type UseJobsStatusTrayReturn = UsePluginJobCenterReturn
+
+interface LegacyJobsOverride {
+  readonly input: readonly JobStateInput[] | undefined
+  readonly jobs: JobState[]
+}
+
 function responseJobs(
   response: JobListPayload | readonly JobStateInput[],
 ): readonly JobStateInput[] {
@@ -81,11 +219,16 @@ function errorMessage(error: unknown, fallback: string): string {
   return error instanceof Error ? error.message : fallback
 }
 
-/** Headless state and action controller for the standard SDK jobs tray. */
-export function useJobsStatusTray(
-  options: UseJobsStatusTrayOptions = {},
-): UseJobsStatusTrayReturn {
-  const jobs = shallowRef<JobState[]>([])
+/**
+ * Headless controller for plugin job presentation and actions.
+ *
+ * When a source is supplied, every job list is derived directly from that
+ * source. The controller never mirrors source jobs into another ref.
+ */
+export function usePluginJobCenter(
+  options: UsePluginJobCenterOptions = {},
+): UsePluginJobCenterReturn {
+  const legacyOverride = shallowRef<LegacyJobsOverride | null>(null)
   const isOpen = ref(false)
   const activeTab = ref<JobsStatusTrayTab>('active')
   const isLoading = ref(false)
@@ -95,44 +238,70 @@ export function useJobsStatusTray(
   let stateRevision = 0
   let requestGeneration = 0
   let active = true
+  const source = computed(() => toValue(options.source))
   const adapter = computed(() => toValue(options.adapter))
 
+  const jobs = computed<JobState[]>(() => {
+    const currentSource = source.value
+    if (currentSource) {
+      return [...toValue(currentSource.jobs)].map(normalizeJobState)
+    }
+    const input = toValue(options.jobs)
+    const override = legacyOverride.value
+    if (override && override.input === input) return override.jobs
+    return input ? [...input].map(normalizeJobState) : []
+  })
   const activeJobs = computed(() => jobs.value.filter(job => isActiveJobStatus(job.status)))
   const historyJobs = computed(() => jobs.value.filter(job => !isActiveJobStatus(job.status)))
   const deletableJobs = computed(() => historyJobs.value.filter(job => job.can_delete))
   const featuredJob = computed(() => activeJobs.value[0] ?? historyJobs.value[0] ?? null)
+  const canRefresh = computed(() => Boolean(source.value?.refreshJobs || adapter.value?.listJobs))
+  const canCancel = computed(() => Boolean(source.value?.cancelJob || adapter.value?.cancelJob))
+  const canDelete = computed(() => Boolean(source.value?.deleteJob || adapter.value?.deleteJob))
+  const canClearFinished = computed(() => Boolean(
+    source.value?.clearFinishedJobs
+    || source.value?.deleteJob
+    || adapter.value?.clearFinishedJobs
+    || adapter.value?.deleteJob,
+  ))
 
   function bumpJobRevision(jobId: string): void {
     jobRevisions.set(jobId, (jobRevisions.get(jobId) ?? 0) + 1)
   }
 
-  function replaceJobs(nextJobs: readonly JobStateInput[]): void {
+  function replaceLegacyJobs(nextJobs: readonly JobStateInput[]): void {
     const normalized = nextJobs.map(normalizeJobState)
     const touchedJobIds = new Set([
       ...jobs.value.map(job => job.job_id),
       ...normalized.map(job => job.job_id),
     ])
     touchedJobIds.forEach(bumpJobRevision)
-    jobs.value = normalized
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: normalized,
+    }
     stateRevision += 1
   }
 
-  function upsertJob(nextJob: JobStateInput): void {
+  function upsertLegacyJob(nextJob: JobStateInput): void {
     const normalized = normalizeJobState(nextJob)
     const existingIndex = jobs.value.findIndex(job => job.job_id === normalized.job_id)
-    if (existingIndex === -1) {
-      jobs.value = [normalized, ...jobs.value]
-    } else {
-      const nextJobs = [...jobs.value]
-      nextJobs[existingIndex] = normalized
-      jobs.value = nextJobs
+    const nextJobs = [...jobs.value]
+    if (existingIndex === -1) nextJobs.unshift(normalized)
+    else nextJobs[existingIndex] = normalized
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: nextJobs,
     }
     bumpJobRevision(normalized.job_id)
     stateRevision += 1
   }
 
-  function removeJobs(jobIds: Set<string>): void {
-    jobs.value = jobs.value.filter(job => !jobIds.has(job.job_id))
+  function removeLegacyJobs(jobIds: Set<string>): void {
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: jobs.value.filter(job => !jobIds.has(job.job_id)),
+    }
     jobIds.forEach(bumpJobRevision)
     stateRevision += 1
   }
@@ -145,21 +314,22 @@ export function useJobsStatusTray(
   }
 
   function applyStreamMessage(message: JobStreamMessage): void {
-    if (!active) return
+    if (!active || source.value) return
     if (message.event === 'snapshot' && isSnapshotPayload(message.data)) {
-      replaceJobs(message.data.jobs)
+      replaceLegacyJobs(message.data.jobs)
       return
     }
     if (
       (message.event === 'job' || message.event === 'terminal')
       && !isSnapshotPayload(message.data)
     ) {
-      upsertJob(message.data)
+      upsertLegacyJob(message.data)
     }
   }
 
   async function refresh(): Promise<boolean> {
-    const listJobs = adapter.value?.listJobs
+    const currentSource = source.value
+    const listJobs = currentSource?.refreshJobs ?? adapter.value?.listJobs
     if (!listJobs) return false
     const generation = ++requestGeneration
     const revision = stateRevision
@@ -170,7 +340,7 @@ export function useJobsStatusTray(
       if (!active || generation !== requestGeneration || revision !== stateRevision) {
         return false
       }
-      replaceJobs(responseJobs(response))
+      if (!currentSource && response) replaceLegacyJobs(responseJobs(response))
       return true
     } catch (cause) {
       if (active && generation === requestGeneration) {
@@ -183,18 +353,21 @@ export function useJobsStatusTray(
   }
 
   async function cancelJob(job: JobState): Promise<boolean> {
-    const cancel = adapter.value?.cancelJob
-    if (!job.can_cancel || !cancel || pendingJobIds.value.has(job.job_id)) {
+    const sourceCancel = source.value?.cancelJob
+    const adapterCancel = adapter.value?.cancelJob
+    if (!job.can_cancel || (!sourceCancel && !adapterCancel) || pendingJobIds.value.has(job.job_id)) {
       return false
     }
     const revision = jobRevisions.get(job.job_id) ?? 0
     setPending(job.job_id, true)
     error.value = null
     try {
-      const updated = await cancel(job)
+      const updated = sourceCancel
+        ? await sourceCancel(job.job_id)
+        : await adapterCancel!(job)
       if (!active) return false
-      if (revision === (jobRevisions.get(job.job_id) ?? 0)) {
-        if (updated) upsertJob(updated)
+      if (!sourceCancel && revision === (jobRevisions.get(job.job_id) ?? 0)) {
+        if (updated) upsertLegacyJob(updated)
         else await refresh()
       }
       return true
@@ -207,17 +380,22 @@ export function useJobsStatusTray(
   }
 
   async function deleteJob(job: JobState): Promise<boolean> {
-    const deleteJobWithAdapter = adapter.value?.deleteJob
-    if (!job.can_delete || !deleteJobWithAdapter || pendingJobIds.value.has(job.job_id)) {
+    const sourceDelete = source.value?.deleteJob
+    const adapterDelete = adapter.value?.deleteJob
+    if (!job.can_delete || (!sourceDelete && !adapterDelete) || pendingJobIds.value.has(job.job_id)) {
       return false
     }
     setPending(job.job_id, true)
     error.value = null
     try {
-      const deleted = await deleteJobWithAdapter(job)
+      const deleted = sourceDelete
+        ? await sourceDelete(job.job_id)
+        : await adapterDelete!(job)
       if (!active) return false
-      if (deleted === false) await refresh()
-      else removeJobs(new Set([job.job_id]))
+      if (!sourceDelete) {
+        if (deleted === false) await refresh()
+        else removeLegacyJobs(new Set([job.job_id]))
+      }
       return deleted !== false
     } catch (cause) {
       if (active) error.value = errorMessage(cause, 'Failed to delete job')
@@ -232,6 +410,16 @@ export function useJobsStatusTray(
     if (targets.length === 0) return false
     error.value = null
     try {
+      const currentSource = source.value
+      if (currentSource?.clearFinishedJobs) {
+        const deleted = await currentSource.clearFinishedJobs()
+        if (!active) return false
+        return typeof deleted !== 'number' || deleted === targets.length
+      }
+      if (currentSource?.deleteJob) {
+        const results = await Promise.all(targets.map(job => deleteJob(job)))
+        return results.every(Boolean)
+      }
       const currentAdapter = adapter.value
       if (currentAdapter?.clearFinishedJobs) {
         const deleted = await currentAdapter.clearFinishedJobs(targets)
@@ -240,7 +428,7 @@ export function useJobsStatusTray(
           await refresh()
           return false
         }
-        removeJobs(new Set(targets.map(job => job.job_id)))
+        removeLegacyJobs(new Set(targets.map(job => job.job_id)))
         return true
       }
       if (!currentAdapter?.deleteJob) return false
@@ -252,16 +440,6 @@ export function useJobsStatusTray(
     }
   }
 
-  if (options.jobs !== undefined) {
-    watch(
-      () => toValue(options.jobs),
-      value => {
-        if (value) replaceJobs(value)
-      },
-      { immediate: true, deep: true },
-    )
-  }
-
   if (options.eventStream !== undefined) {
     watch(
       () => toValue(options.eventStream)?.lastMessage.value ?? null,
@@ -286,6 +464,10 @@ export function useJobsStatusTray(
     historyJobs,
     deletableJobs,
     featuredJob,
+    canRefresh,
+    canCancel,
+    canDelete,
+    canClearFinished,
     isOpen,
     activeTab,
     isLoading,
@@ -302,3 +484,10 @@ export function useJobsStatusTray(
     isPending: job => pendingJobIds.value.has(job.job_id),
   }
 }
+
+/** Backward-compatible name for the plugin job-center controller. */
+export function useJobsStatusTray(
+  options: UseJobsStatusTrayOptions = {},
+): UseJobsStatusTrayReturn {
+  return usePluginJobCenter(options)
+}

package/src/composables/usePluginClient.ts

@@ -28,7 +28,13 @@ import {
   pluginEndpointRequestParts,
   requestBodyFromPayload,
 } from './pluginEndpointBuilder'
-import type { ExperimentSummary, PageSelectorItem, SettingsModalSchema, TopBarSettingsConfig } from '../types'
+import type {
+  ExperimentSummary,
+  GeneratedJobDefinition,
+  PageSelectorItem,
+  SettingsModalSchema,
+  TopBarSettingsConfig,
+} from '../types'
 
 export {
   buildPluginEndpointUrl,
@@ -41,6 +47,7 @@ export interface PluginEndpointContract {
   name: string
   method: PluginHttpMethod
   path: string
+  requiresAuth?: boolean
   pathParams?: PluginEndpointParamContract[]
   queryParams?: PluginEndpointParamContract[]
   requestType?: string | null
@@ -90,12 +97,14 @@ export interface PluginContract {
     schema?: SettingsModalSchema | null
   }
   endpoints: PluginEndpointContract[]
+  jobs?: GeneratedJobDefinition[]
   hash: string
 }
 
 export interface PluginEndpointDefinition {
   method: PluginHttpMethod
   path: string
+  requiresAuth?: boolean
   pathParams?: PluginEndpointParamDefinition[]
   queryParams?: PluginEndpointParamDefinition[]
   hasBody?: boolean
@@ -157,7 +166,7 @@ export interface UsePluginSettingsOptions {
   apiBaseUrl?: string
   /** Platform API base URL for /plugins/{name}/config. Defaults to the injected platform API URL. */
   platformApiBaseUrl?: string
-  /** SettingsModal schema generated from the backend settings_model. */
+  /** SettingsModal schema generated from the backend plugin config model. */
   schema?: SettingsModalSchema | null
   /** SettingsModal title when using settingsConfig. */
   title?: string
@@ -383,7 +392,7 @@ function pluginPageIdFromPath(path: string, fallbackIndex: number): string {
   return normalizedPath.replace(/^\/+/, '').replace(/\/+/g, '-') || `page-${fallbackIndex + 1}`
 }
 
-/** Convert PluginMetadata.nav_items into AppTopBar pageSelector items for topbar page switches and homepage PluginCards. */
+/** Convert resolved @mint_plugin nav_items into page selectors for the topbar and homepage PluginCards. */
 export function getPluginPageSelectorItems(contract: PluginContract): PageSelectorItem[] {
   const pluginIcon = contract.plugin.icon ?? ''
   const navItems = contract.plugin.navItems ?? []
@@ -413,7 +422,10 @@ export function createPluginClient<TClient extends object = GeneratedPluginClien
         ? explicitOptions
         : (payloadOrOptions as PluginClientRequestOptions | undefined) ?? explicitOptions
       const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
-      const api = useApi({ baseUrl: parts.baseUrl })
+      const api = useApi({
+        baseUrl: parts.baseUrl,
+        withAuth: endpoint.requiresAuth !== false,
+      })
       const config = endpointRequestConfig(endpoint, parts.query, callOptions)
 
       if (endpoint.method === 'get') {
@@ -456,7 +468,10 @@ export async function uploadPluginEndpoint<TResponse = unknown>(
   }
 
   const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
-  const api = useApi({ baseUrl: parts.baseUrl })
+  const api = useApi({
+    baseUrl: parts.baseUrl,
+    withAuth: endpoint.requiresAuth !== false,
+  })
   const body = endpoint.hasBody
     ? requestBodyFromPayload(payload, parts.requestPayload, endpoint)
     : payload
@@ -491,7 +506,10 @@ export async function downloadPluginEndpoint(
   }
 
   const parts = pluginEndpointRequestParts(contract, endpoint, payload, options.baseUrl)
-  const api = useApi({ baseUrl: parts.baseUrl })
+  const api = useApi({
+    baseUrl: parts.baseUrl,
+    withAuth: endpoint.requiresAuth !== false,
+  })
   const config = {
     ...(endpointRequestConfig(endpoint, parts.query, { signal: options.signal }) ?? {}),
     responseType: 'blob' as const,
@@ -668,7 +686,10 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
   }
 }
 
-function streamRequestAuth(options: PluginEventStreamOptions<unknown>): {
+function streamRequestAuth(
+  options: PluginEventStreamOptions<unknown>,
+  policy: { requiresAuth: boolean },
+): {
   headers: Headers
   token?: string
 } {
@@ -677,11 +698,11 @@ function streamRequestAuth(options: PluginEventStreamOptions<unknown>): {
   if (!authStore.isInitialized) {
     authStore.initialize()
   }
-  if (authStore.token && !headers.has('Authorization')) {
+  if (policy.requiresAuth && authStore.token && !headers.has('Authorization')) {
     headers.set('Authorization', `Bearer ${authStore.token}`)
   }
   headers.set('Accept', 'text/event-stream')
-  const token = authStore.token
+  const token = policy.requiresAuth ? authStore.token : undefined
   return {
     headers,
     token: token && headers.get('Authorization') === `Bearer ${token}` ? token : undefined,
@@ -832,7 +853,10 @@ export function usePluginEventStream<TData = string>(
       const url = buildPluginEndpointUrl(contract, endpoint, payload, {
         baseUrl: options.baseUrl,
       })
-      const requestAuth = streamRequestAuth(options as PluginEventStreamOptions<unknown>)
+      const requestAuth = streamRequestAuth(
+        options as PluginEventStreamOptions<unknown>,
+        { requiresAuth: endpoint.requiresAuth !== false },
+      )
       const response = await fetch(url, {
         method: 'GET',
         headers: requestAuth.headers,

package/src/generated/schema.ts

@@ -0,0 +1,130 @@
+import type {
+  FormFieldSchema,
+  FormFieldType,
+  FormSchema,
+} from '../types/form-builder'
+import type {
+  GeneratedJsonSchema,
+  GeneratedJobDefinition,
+} from '../types/generated-ui'
+
+type GeneratedReference = 'path'
+
+interface ResolvedGeneratedField {
+  schema: GeneratedJsonSchema
+  reference?: GeneratedReference
+  hasDefault: boolean
+  defaultValue?: unknown
+}
+
+export function generatedJobFormSchema(definition: GeneratedJobDefinition): FormSchema & { sections: NonNullable<FormSchema['sections']> } {
+  const root = definition.input_schema
+  const required = new Set(root.required ?? [])
+  const fields = Object.entries(root.properties ?? {}).map(([name, schema]) =>
+    toFormField(name, resolveGeneratedField(root, schema), required.has(name)),
+  )
+  return {
+    sections: [{
+      id: definition.id,
+      title: definition.title,
+      description: definition.description || undefined,
+      columns: 1,
+      fields,
+    }],
+    submitLabel: 'Run analysis',
+  }
+}
+
+export function generatedJobDefaults(definition: GeneratedJobDefinition): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(definition.input_schema.properties ?? {})
+      .filter(([, schema]) => hasOwnDefault(schema))
+      .map(([name, schema]) => [name, structuredClone(schema.default)]),
+  )
+}
+
+export function normalizeGeneratedJobInput(
+  definition: GeneratedJobDefinition,
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const normalized: Record<string, unknown> = {}
+  for (const [name, value] of Object.entries(values)) {
+    const field = definition.input_schema.properties?.[name]
+    if (!field) continue
+    normalized[name] = value
+  }
+  return normalized
+}
+
+function toFormField(
+  name: string,
+  resolved: ResolvedGeneratedField,
+  required: boolean,
+): FormFieldSchema {
+  const { schema, reference } = resolved
+  const validation: NonNullable<FormFieldSchema['validation']> = {}
+  if (required) validation.required = true
+  if (schema.minimum !== undefined) validation.min = schema.minimum
+  if (schema.maximum !== undefined) validation.max = schema.maximum
+  if (schema.minLength !== undefined) validation.minLength = schema.minLength
+  if (schema.maxLength !== undefined) validation.maxLength = schema.maxLength
+
+  const props: Record<string, unknown> = {}
+  if (schema.enum) props.options = [...schema.enum]
+  if (reference === 'path' && schema.type === 'array') props.multiple = true
+  return {
+    name,
+    label: schema.title || humanize(name),
+    type: fieldType(schema, reference),
+    defaultValue: resolved.hasDefault ? structuredClone(resolved.defaultValue) : undefined,
+    hint: schema.description,
+    validation,
+    props,
+  }
+}
+
+function resolveGeneratedField(
+  root: GeneratedJsonSchema,
+  field: GeneratedJsonSchema,
+): ResolvedGeneratedField {
+  const hasDefault = hasOwnDefault(field)
+  const candidate = field.anyOf?.find(item => item.type !== 'null')
+    ?? field.allOf?.[0]
+    ?? field
+  if (candidate.$ref) {
+    const referenceParts = candidate.$ref.split('/')
+    const key = referenceParts[referenceParts.length - 1]
+    const schema = key ? root.$defs?.[key] : undefined
+    if (!schema) throw new Error(`Generated field reference is missing: ${candidate.$ref}`)
+    return {
+      schema: { ...schema, title: field.title ?? schema.title },
+      reference: field['x-mint-component'] ?? schema['x-mint-component'],
+      hasDefault,
+      defaultValue: field.default,
+    }
+  }
+  return {
+    schema: candidate,
+    reference: field['x-mint-component'] ?? candidate['x-mint-component'],
+    hasDefault,
+    defaultValue: field.default,
+  }
+}
+
+function fieldType(schema: GeneratedJsonSchema, reference?: GeneratedReference): FormFieldType {
+  if (reference === 'path') return 'path'
+  if (schema.enum) return 'select'
+  const type = Array.isArray(schema.type) ? schema.type.find(value => value !== 'null') : schema.type
+  if (type === 'boolean') return 'toggle'
+  if (type === 'number' || type === 'integer') return 'number'
+  if (type === 'array') return 'tags'
+  return 'text'
+}
+
+function hasOwnDefault(schema: GeneratedJsonSchema): boolean {
+  return Object.prototype.hasOwnProperty.call(schema, 'default')
+}
+
+function humanize(value: string): string {
+  return value.replace(/[_-]+/g, ' ').replace(/^\w/, character => character.toUpperCase())
+}