@morscherlab/mint-sdk 1.0.63 → 1.1.0-beta.10

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,
@@ -39,8 +45,10 @@ export type PluginHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete'
 
 export interface PluginEndpointContract {
   name: string
+  operationId?: string
   method: PluginHttpMethod
   path: string
+  requiresAuth?: boolean
   pathParams?: PluginEndpointParamContract[]
   queryParams?: PluginEndpointParamContract[]
   requestType?: string | null
@@ -68,8 +76,16 @@ export interface PluginNavItemContract {
   requiresFeature?: string
 }
 
+export interface PluginContractSettings {
+  modelName: string | null
+  /** Pydantic JSON Schema used to generate typed settings values. */
+  valueSchema: Record<string, unknown> | null
+  /** SDK SettingsModal schema used to render the settings form. */
+  formSchema: SettingsModalSchema | null
+}
+
 export interface PluginContract {
-  schemaVersion: number
+  schemaVersion: 2
   plugin: {
     name?: string
     packageName?: string
@@ -85,17 +101,17 @@ export interface PluginContract {
     analysisResultReaders?: string[]
     capabilities?: Record<string, unknown>
   }
-  settings?: {
-    modelName?: string | null
-    schema?: SettingsModalSchema | null
-  }
+  settings: PluginContractSettings
   endpoints: PluginEndpointContract[]
+  schemas?: Record<string, Record<string, unknown>>
+  jobs?: GeneratedJobDefinition[]
   hash: string
 }
 
 export interface PluginEndpointDefinition {
   method: PluginHttpMethod
   path: string
+  requiresAuth?: boolean
   pathParams?: PluginEndpointParamDefinition[]
   queryParams?: PluginEndpointParamDefinition[]
   hasBody?: boolean
@@ -157,7 +173,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 +399,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 +429,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 +475,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 +513,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,
@@ -528,8 +553,14 @@ function normalizePluginSettingsOptions(options: UsePluginSettingsOptions | stri
   return typeof options === 'string' ? { pluginName: options } : options
 }
 
+const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
+
 function cloneRecord(value: Record<string, unknown>): Record<string, unknown> {
-  return { ...value }
+  return JSON.parse(JSON.stringify(value)) as Record<string, unknown>
+}
+
+function hasOwnSetting(settings: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(settings, key)
 }
 
 function responseSettingsPayload(response: unknown): Record<string, unknown> {
@@ -547,6 +578,43 @@ function responseSettingsPayload(response: unknown): Record<string, unknown> {
   return {}
 }
 
+function responseSettingsRevision(response: unknown): string | null {
+  if (!response || typeof response !== 'object') return null
+  const revision = (response as { revision?: unknown }).revision
+  return typeof revision === 'string' && revision ? revision : null
+}
+
+function topLevelSettingsPatch(
+  current: Record<string, unknown>,
+  keys: Iterable<string>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    [...keys].map(key => [
+      key,
+      hasOwnSetting(current, key) ? current[key] : null,
+    ]),
+  )
+}
+
+function changedTopLevelSettingKeys(
+  current: Record<string, unknown>,
+  saved: Record<string, unknown>,
+): Set<string> {
+  return new Set(
+    [...new Set([...Object.keys(current), ...Object.keys(saved)])].filter(
+      key => JSON.stringify(current[key]) !== JSON.stringify(saved[key]),
+    ),
+  )
+}
+
+function platformOwnedSettingsPatch(settings: Record<string, unknown>): Record<string, unknown> {
+  return {
+    [PLATFORM_OWNED_SETTINGS_KEY]: hasOwnSetting(settings, PLATFORM_OWNED_SETTINGS_KEY)
+      ? settings[PLATFORM_OWNED_SETTINGS_KEY]
+      : null,
+  }
+}
+
 /** Load, edit, and persist plugin settings from platform config or the plugin-local settings router. */
 export function usePluginSettings<TSettings = Record<string, unknown>>(
   options: UsePluginSettingsOptions | string = {},
@@ -557,8 +625,9 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
   const platformApi = useApi({ baseUrl: resolvedOptions.platformApiBaseUrl ?? injectedContext?.platformApiUrl })
   const pluginApi = useApi({ baseUrl: resolvedOptions.apiBaseUrl ?? injectedContext?.plugin?.api_prefix })
 
-  const values = shallowRef<PluginSettingsValues<TSettings>>({} as PluginSettingsValues<TSettings>)
+  const values = ref({}) as Ref<PluginSettingsValues<TSettings>>
   const savedValues = shallowRef<Record<string, unknown>>({})
+  const revision = ref<string | null>(null)
   const request = useRequestSyncState('Plugin settings request failed.')
   const isLoading = ref(false)
   const isSaving = ref(false)
@@ -566,8 +635,17 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
   const resolvedPluginName = computed(() =>
     resolvedOptions.pluginName ?? plugin.value?.name ?? injectedContext?.plugin?.name ?? '',
   )
+  const usesPluginSettingsApi = computed(() => {
+    const currentPlugin = injectedContext?.plugin ?? plugin.value
+    return currentPlugin?.settings_api === 'plugin'
+      && resolvedPluginName.value === currentPlugin.name
+  })
   const usesPlatformConfig = computed(() =>
-    Boolean((isIntegrated.value || injectedContext?.isIntegrated) && resolvedPluginName.value),
+    Boolean(
+      (isIntegrated.value || injectedContext?.isIntegrated)
+      && resolvedPluginName.value
+      && !usesPluginSettingsApi.value,
+    ),
   )
   const settings = computed(() => values.value)
   const isDirty = computed(() => JSON.stringify(values.value) !== JSON.stringify(savedValues.value))
@@ -582,10 +660,11 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
     values.value = cloneRecord(nextValues) as PluginSettingsValues<TSettings>
   }
 
-  function applyLoaded(nextValues: Record<string, unknown>): void {
+  function applyLoaded(nextValues: Record<string, unknown>, nextRevision: string | null): void {
     const cloned = cloneRecord(nextValues)
     values.value = cloned as PluginSettingsValues<TSettings>
     savedValues.value = cloneRecord(cloned)
+    revision.value = nextRevision
   }
 
   async function load(): Promise<void> {
@@ -602,7 +681,10 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
           () => pluginApi.get<{ settings: Record<string, unknown>; mode?: string }>('/settings'),
           { success: 'load', errorMessage: 'Failed to load plugin settings' },
         )
-      applyLoaded(responseSettingsPayload(response))
+      applyLoaded(
+        responseSettingsPayload(response),
+        responseSettingsRevision(response),
+      )
     } catch {
       // Error state is handled by request.run().
     } finally {
@@ -618,19 +700,65 @@ export function usePluginSettings<TSettings = Record<string, unknown>>(
     isSaving.value = true
     try {
       const payload = cloneRecord(values.value)
-      const response = usesPlatformConfig.value
-        ? await request.run(
-          () => platformApi.patch<{ plugin_name: string; config: Record<string, unknown> }>(
-            `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
-            { config: payload },
-          ),
-          { success: 'save', errorMessage: 'Failed to save plugin settings' },
+      let response: unknown
+      if (usesPlatformConfig.value) {
+        const dirtyKeys = changedTopLevelSettingKeys(payload, savedValues.value)
+        const platformOwnedChanged = dirtyKeys.has(PLATFORM_OWNED_SETTINGS_KEY)
+        const typedKeys = [...dirtyKeys].filter(
+          key => key !== PLATFORM_OWNED_SETTINGS_KEY,
         )
-        : await request.run(
-          () => pluginApi.put<{ settings: Record<string, unknown>; mode?: string }>('/settings', payload),
+        let nextRevision = revision.value
+
+        if (typedKeys.length) {
+          response = await request.run(
+            () => platformApi.patch<{
+              plugin_name: string
+              config: Record<string, unknown>
+              revision?: string
+            }>(
+              `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
+              { config: topLevelSettingsPatch(payload, typedKeys) },
+            ),
+            { success: 'save', errorMessage: 'Failed to save plugin settings' },
+          )
+          nextRevision = responseSettingsRevision(response) ?? nextRevision
+        }
+
+        if (platformOwnedChanged) {
+          response = await request.run(
+            () => platformApi.patch<{
+              plugin_name: string
+              config: Record<string, unknown>
+              revision?: string
+            }>(
+              `/plugins/${encodeURIComponent(resolvedPluginName.value)}/config`,
+              { config: platformOwnedSettingsPatch(payload) },
+            ),
+            { success: 'save', errorMessage: 'Failed to save plugin settings' },
+          )
+          nextRevision = responseSettingsRevision(response) ?? nextRevision
+        }
+
+        if (!response) return true
+        applyLoaded(responseSettingsPayload(response), nextRevision)
+        return true
+      } else {
+        const ifMatch = revision.value
+          ? { headers: { 'If-Match': `"${revision.value}"` } }
+          : undefined
+        response = await request.run(
+          () => pluginApi.put<{
+            settings: Record<string, unknown>
+            mode?: string
+            revision?: string
+          }>('/settings', payload, ifMatch),
           { success: 'save', errorMessage: 'Failed to save plugin settings' },
         )
-      applyLoaded(responseSettingsPayload(response))
+      }
+      applyLoaded(
+        responseSettingsPayload(response),
+        responseSettingsRevision(response) ?? revision.value,
+      )
       return true
     } catch {
       return false
@@ -668,7 +796,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 +808,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 +963,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/composables/usePluginConfig.ts

@@ -1,8 +1,57 @@
 import { ref, computed, onMounted, type Ref, type ComputedRef } from 'vue'
 import { useApi } from './useApi'
 import { usePlatformContext } from './usePlatformContext'
+import { getInjectedPlatformContext } from './platformContextHelpers'
 import { useRequestSyncState } from './useRequestSyncState'
 
+const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
+
+function cloneConfig(config: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(config)) as Record<string, unknown>
+}
+
+function hasOwnConfig(config: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(config, key)
+}
+
+function changedTopLevelKeys(
+  current: Record<string, unknown>,
+  saved: Record<string, unknown>,
+): Set<string> {
+  return new Set(
+    [...new Set([...Object.keys(current), ...Object.keys(saved)])].filter(
+      key => JSON.stringify(current[key]) !== JSON.stringify(saved[key]),
+    ),
+  )
+}
+
+function topLevelConfigPatch(
+  current: Record<string, unknown>,
+  keys: Iterable<string>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    [...keys].map(key => [
+      key,
+      hasOwnConfig(current, key) ? current[key] : null,
+    ]),
+  )
+}
+
+function platformOwnedConfigPatch(config: Record<string, unknown>): Record<string, unknown> {
+  return {
+    [PLATFORM_OWNED_SETTINGS_KEY]: hasOwnConfig(config, PLATFORM_OWNED_SETTINGS_KEY)
+      ? config[PLATFORM_OWNED_SETTINGS_KEY]
+      : null,
+  }
+}
+
+function responseConfigPayload(response: {
+  config?: Record<string, unknown>
+  settings?: Record<string, unknown>
+}): Record<string, unknown> {
+  return response.config ?? response.settings ?? {}
+}
+
 export interface UsePluginConfigReturn {
   /** Editable plugin configuration values. */
   config: Ref<Record<string, unknown>>
@@ -28,13 +77,25 @@ export interface UsePluginConfigReturn {
 
 /** Loads, saves, and tracks dirty state for a plugin's persistent configuration via the platform API. */
 export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
-  const api = useApi()
+  const injectedContext = getInjectedPlatformContext()
   const { plugin } = usePlatformContext()
+  const platformApi = useApi()
+  const pluginApi = useApi({
+    baseUrl: injectedContext?.plugin?.api_prefix ?? plugin.value?.api_prefix,
+  })
 
-  const resolvedName = computed(() => pluginName ?? plugin.value?.name ?? '')
+  const resolvedName = computed(
+    () => pluginName ?? plugin.value?.name ?? injectedContext?.plugin?.name ?? '',
+  )
+  const usesPluginSettingsApi = computed(() => {
+    const currentPlugin = injectedContext?.plugin ?? plugin.value
+    return currentPlugin?.settings_api === 'plugin'
+      && resolvedName.value === currentPlugin.name
+  })
 
   const config = ref<Record<string, unknown>>({})
   const savedConfig = ref<Record<string, unknown>>({})
+  const revision = ref<string | null>(null)
   const request = useRequestSyncState('Plugin config request failed.')
   const isLoading = ref(false)
   const isSaving = ref(false)
@@ -52,14 +113,29 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
 
     isLoading.value = true
     try {
-      const response = await request.run(
-        () => api.get<{ plugin_name: string; config: Record<string, unknown> }>(
-          `/plugins/${encodeURIComponent(name)}/config`,
-        ),
-        { success: 'load', errorMessage: 'Failed to load plugin config' },
-      )
-      config.value = { ...response.config }
-      savedConfig.value = { ...response.config }
+      const response = usesPluginSettingsApi.value
+        ? await request.run(
+          () => pluginApi.get<{
+            settings: Record<string, unknown>
+            mode?: string
+            revision?: string
+          }>('/settings'),
+          { success: 'load', errorMessage: 'Failed to load plugin config' },
+        )
+        : await request.run(
+          () => platformApi.get<{
+            plugin_name: string
+            config: Record<string, unknown>
+            revision?: string
+          }>(
+            `/plugins/${encodeURIComponent(name)}/config`,
+          ),
+          { success: 'load', errorMessage: 'Failed to load plugin config' },
+        )
+      const responseConfig = responseConfigPayload(response)
+      config.value = cloneConfig(responseConfig)
+      savedConfig.value = cloneConfig(responseConfig)
+      revision.value = response.revision ?? null
     } catch {
       // Error state is handled by request.run().
     } finally {
@@ -73,15 +149,75 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
 
     isSaving.value = true
     try {
-      const response = await request.run(
-        () => api.patch<{ plugin_name: string; config: Record<string, unknown> }>(
-          `/plugins/${encodeURIComponent(name)}/config`,
-          { config: config.value },
-        ),
-        { success: 'save', errorMessage: 'Failed to save plugin config' },
-      )
-      config.value = { ...response.config }
-      savedConfig.value = { ...response.config }
+      const payload = cloneConfig(config.value)
+      let response: {
+        plugin_name?: string
+        config?: Record<string, unknown>
+        settings?: Record<string, unknown>
+        mode?: string
+        revision?: string
+      } | undefined
+      let nextRevision = revision.value
+
+      if (usesPluginSettingsApi.value) {
+        response = await request.run(
+          () => pluginApi.put<{
+            settings: Record<string, unknown>
+            mode?: string
+            revision?: string
+          }>(
+            '/settings',
+            payload,
+            revision.value
+              ? { headers: { 'If-Match': `"${revision.value}"` } }
+              : undefined,
+          ),
+          { success: 'save', errorMessage: 'Failed to save plugin config' },
+        )
+        nextRevision = response.revision ?? nextRevision
+      } else {
+        const dirtyKeys = changedTopLevelKeys(payload, savedConfig.value)
+        const platformOwnedChanged = dirtyKeys.has(PLATFORM_OWNED_SETTINGS_KEY)
+        const typedKeys = [...dirtyKeys].filter(
+          key => key !== PLATFORM_OWNED_SETTINGS_KEY,
+        )
+
+        if (typedKeys.length) {
+          response = await request.run(
+            () => platformApi.patch<{
+              plugin_name: string
+              config: Record<string, unknown>
+              revision?: string
+            }>(
+              `/plugins/${encodeURIComponent(name)}/config`,
+              { config: topLevelConfigPatch(payload, typedKeys) },
+            ),
+            { success: 'save', errorMessage: 'Failed to save plugin config' },
+          )
+          nextRevision = response.revision ?? nextRevision
+        }
+
+        if (platformOwnedChanged) {
+          response = await request.run(
+            () => platformApi.patch<{
+              plugin_name: string
+              config: Record<string, unknown>
+              revision?: string
+            }>(
+              `/plugins/${encodeURIComponent(name)}/config`,
+              { config: platformOwnedConfigPatch(payload) },
+            ),
+            { success: 'save', errorMessage: 'Failed to save plugin config' },
+          )
+          nextRevision = response.revision ?? nextRevision
+        }
+      }
+
+      if (!response) return true
+      const responseConfig = responseConfigPayload(response)
+      config.value = cloneConfig(responseConfig)
+      savedConfig.value = cloneConfig(responseConfig)
+      revision.value = response.revision ?? nextRevision
       return true
     } catch {
       return false
@@ -91,7 +227,7 @@ export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
   }
 
   function reset(): void {
-    config.value = { ...savedConfig.value }
+    config.value = cloneConfig(savedConfig.value)
     request.clearError()
   }
 

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