@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/api/presentation/aiInspiration.ts

@@ -1,1116 +1,1116 @@
-import * as z from "zod"
-import type { PluginApiReturn } from "../../types"
-
-const JsonPrimitive = z.union([z.string(), z.number(), z.boolean(), z.null()])
-type JsonValue =
-  | z.infer<typeof JsonPrimitive>
-  | JsonValue[]
-  | { [key: string]: JsonValue }
-const JsonValue: z.ZodType<JsonValue> = z.lazy(() =>
-  z.union([JsonPrimitive, z.array(JsonValue), z.record(z.string(), JsonValue)]),
-)
-
-export const PluginAIInspirationRunMode = z.enum(["blocking", "job"])
-export type PluginAIInspirationRunMode = z.infer<
-  typeof PluginAIInspirationRunMode
->
-
-export const PluginAIInspirationOutputKind = z.enum([
-  "source",
-  "image",
-  "video",
-])
-export type PluginAIInspirationOutputKind = z.infer<
-  typeof PluginAIInspirationOutputKind
->
-
-export const PluginAIInspirationModelOutput = z.enum(["image", "video"])
-export type PluginAIInspirationModelOutput = z.infer<
-  typeof PluginAIInspirationModelOutput
->
-
-export const PluginAIInspirationRuntimeProvider = z.enum(["gpt", "fal"])
-export type PluginAIInspirationRuntimeProvider = z.infer<
-  typeof PluginAIInspirationRuntimeProvider
->
-
-export const PluginAIInspirationPromptStrategy = z.enum([
-  "gpt-image",
-  "fal-image",
-  "fal-video",
-])
-export type PluginAIInspirationPromptStrategy = z.infer<
-  typeof PluginAIInspirationPromptStrategy
->
-
-export const PluginAIInspirationShapeKind = z.enum(["image", "view", "video"])
-export type PluginAIInspirationShapeKind = z.infer<
-  typeof PluginAIInspirationShapeKind
->
-
-export const PluginAIInspirationVideoMode = z.enum([
-  "animate",
-  "references",
-  "keyframes",
-])
-export type PluginAIInspirationVideoMode = z.infer<
-  typeof PluginAIInspirationVideoMode
->
-
-export const PluginAIInspirationVideoMotion = z.enum([
-  "auto",
-  "slow-dolly",
-  "subtle-orbit",
-  "reveal",
-])
-export type PluginAIInspirationVideoMotion = z.infer<
-  typeof PluginAIInspirationVideoMotion
->
-
-export const PluginAIInspirationVideoDuration = z.enum(["4s", "6s", "8s"])
-export type PluginAIInspirationVideoDuration = z.infer<
-  typeof PluginAIInspirationVideoDuration
->
-
-export const PluginAIInspirationJobStatus = z.enum([
-  "queued",
-  "running",
-  "completed",
-  "failed",
-  "cancelled",
-])
-export type PluginAIInspirationJobStatus = z.infer<
-  typeof PluginAIInspirationJobStatus
->
-
-export const PluginAIInspirationWorkflowRunState = z.enum([
-  "current",
-  "stale",
-  "running",
-  "failed",
-  "superseded",
-])
-export type PluginAIInspirationWorkflowRunState = z.infer<
-  typeof PluginAIInspirationWorkflowRunState
->
-
-export const PluginAIInspirationRegionHint = z.object({
-  x: z.number().finite(),
-  y: z.number().finite(),
-  w: z.number().finite().positive(),
-  h: z.number().finite().positive(),
-})
-export type PluginAIInspirationRegionHint = z.infer<
-  typeof PluginAIInspirationRegionHint
->
-
-export const PluginAIInspirationPoint = z.object({
-  x: z.number().finite(),
-  y: z.number().finite(),
-})
-export type PluginAIInspirationPoint = z.infer<typeof PluginAIInspirationPoint>
-
-export const PluginAIInspirationTextAnnotation = z.object({
-  text: z.string().min(1),
-  x: z.number().finite().optional(),
-  y: z.number().finite().optional(),
-})
-export type PluginAIInspirationTextAnnotation = z.infer<
-  typeof PluginAIInspirationTextAnnotation
->
-
-export const PluginAIInspirationSketchGuidance = z.object({
-  visualShapeIds: z.array(z.string()).optional(),
-  textAnnotations: z.array(PluginAIInspirationTextAnnotation).optional(),
-})
-export type PluginAIInspirationSketchGuidance = z.infer<
-  typeof PluginAIInspirationSketchGuidance
->
-
-export const PluginAIInspirationSiteOptions = z.object({
-  includeSatellite: z.boolean().optional(),
-  includeStreetView: z.boolean().optional(),
-  includeAerial: z.boolean().optional(),
-  aerialBearing: z.number().finite().optional(),
-  aerialPitch: z.number().finite().optional(),
-  selectedDiagramIds: z.array(z.string()).optional(),
-  location: z
-    .object({
-      lat: z.number().finite(),
-      lng: z.number().finite(),
-    })
-    .optional(),
-})
-export type PluginAIInspirationSiteOptions = z.infer<
-  typeof PluginAIInspirationSiteOptions
->
-
-export const PluginAIInspirationAppliedPreset = z.object({
-  source: z.enum(["curated", "user"]),
-  presetId: z.string().min(1),
-  name: z.string().min(1),
-  savedPresetKind: z.enum(["prompt", "style"]).optional(),
-  stylePrompt: z.string().optional(),
-  modelId: z.string().optional(),
-  referenceImages: z
-    .array(
-      z.object({
-        url: z.string().min(1),
-        label: z.string().optional(),
-        weight: z.number().finite().optional(),
-      }),
-    )
-    .optional(),
-  siteDefaults: z
-    .object({
-      includeSatellite: z.boolean().optional(),
-      includeStreetView: z.boolean().optional(),
-      includeAerial: z.boolean().optional(),
-    })
-    .optional(),
-})
-export type PluginAIInspirationAppliedPreset = z.infer<
-  typeof PluginAIInspirationAppliedPreset
->
-
-export const PluginAIInspirationVideoOptions = z.object({
-  mode: PluginAIInspirationVideoMode.optional(),
-  endFrameShapeId: z.string().optional(),
-  motion: PluginAIInspirationVideoMotion.optional(),
-  duration: PluginAIInspirationVideoDuration.optional(),
-})
-export type PluginAIInspirationVideoOptions = z.infer<
-  typeof PluginAIInspirationVideoOptions
->
-
-export const PluginAIInspirationModel = z.object({
-  id: z.string(),
-  label: z.string(),
-  supportsMultiImage: z.boolean(),
-  output: PluginAIInspirationModelOutput,
-  isDefault: z.boolean().optional(),
-})
-export type PluginAIInspirationModel = z.infer<typeof PluginAIInspirationModel>
-
-export const PluginAIInspirationModelCapability = z.object({
-  id: z.string(),
-  output: PluginAIInspirationModelOutput,
-  provider: PluginAIInspirationRuntimeProvider,
-  supportsRegionEdit: z.boolean(),
-  supportsReferenceImages: z.boolean(),
-  supportsStylePresets: z.boolean(),
-  supportsSiteContext: z.boolean(),
-  supportsSketchGuidance: z.boolean(),
-  supportsKeyframes: z.boolean(),
-  maxExtraImages: z.number().int().nonnegative(),
-  promptStrategy: PluginAIInspirationPromptStrategy,
-})
-export type PluginAIInspirationModelCapability = z.infer<
-  typeof PluginAIInspirationModelCapability
->
-
-export const PluginAIInspirationListModelsResult = z.object({
-  defaultModelId: z.string(),
-  models: z.array(PluginAIInspirationModel),
-})
-export type PluginAIInspirationListModelsResult = z.infer<
-  typeof PluginAIInspirationListModelsResult
->
-
-export const PluginAIInspirationGetModelCapabilitiesArgs = z.object({
-  modelId: z.string().min(1),
-})
-export type PluginAIInspirationGetModelCapabilitiesArgs = z.infer<
-  typeof PluginAIInspirationGetModelCapabilitiesArgs
->
-
-export const PluginAIInspirationGetModelCapabilitiesResult = z.object({
-  capability: PluginAIInspirationModelCapability,
-})
-export type PluginAIInspirationGetModelCapabilitiesResult = z.infer<
-  typeof PluginAIInspirationGetModelCapabilitiesResult
->
-
-export const PluginAIInspirationShapeRef = z.object({
-  shapeId: z.string(),
-  assetId: z.string().optional(),
-  kind: PluginAIInspirationShapeKind,
-  name: z.string().optional(),
-  width: z.number().finite().optional(),
-  height: z.number().finite().optional(),
-  outputType: PluginAIInspirationOutputKind.optional(),
-  sourceUrl: z.string().optional(),
-})
-export type PluginAIInspirationShapeRef = z.infer<
-  typeof PluginAIInspirationShapeRef
->
-
-export const PluginAIInspirationListSourcesArgs = z.object({
-  includeGenerated: z.boolean().optional(),
-  includeSourceUrl: z.boolean().optional(),
-})
-export type PluginAIInspirationListSourcesArgs = z.infer<
-  typeof PluginAIInspirationListSourcesArgs
->
-
-export const PluginAIInspirationListSourcesResult = z.object({
-  sources: z.array(PluginAIInspirationShapeRef),
-})
-export type PluginAIInspirationListSourcesResult = z.infer<
-  typeof PluginAIInspirationListSourcesResult
->
-
-export const PluginAIInspirationGetSelectionResult = z.object({
-  selectedShapeIds: z.array(z.string()),
-  sources: z.array(PluginAIInspirationShapeRef),
-})
-export type PluginAIInspirationGetSelectionResult = z.infer<
-  typeof PluginAIInspirationGetSelectionResult
->
-
-export const PluginAIInspirationPresetReferenceImage = z.object({
-  url: z.string(),
-  label: z.string().optional(),
-  weight: z.number().finite().optional(),
-})
-export type PluginAIInspirationPresetReferenceImage = z.infer<
-  typeof PluginAIInspirationPresetReferenceImage
->
-
-export const PluginAIInspirationPreset = z.object({
-  id: z.string(),
-  name: z.string(),
-  source: z.enum(["curated", "user"]),
-  modelId: z.string(),
-  categoryId: z.string().optional(),
-  categoryLabel: z.string().optional(),
-  description: z.string().optional(),
-  previewImageUrl: z.string().optional(),
-  prompt: z.string().optional(),
-  stylePrompt: z.string().optional(),
-  tags: z.array(z.string()).optional(),
-  referenceImages: z.array(PluginAIInspirationPresetReferenceImage).optional(),
-  siteDefaults: PluginAIInspirationAppliedPreset.shape.siteDefaults.optional(),
-})
-export type PluginAIInspirationPreset = z.infer<
-  typeof PluginAIInspirationPreset
->
-
-export const PluginAIInspirationPresetCategory = z.object({
-  id: z.string(),
-  label: z.string(),
-  description: z.string().optional(),
-})
-export type PluginAIInspirationPresetCategory = z.infer<
-  typeof PluginAIInspirationPresetCategory
->
-
-export const PluginAIInspirationGetPresetCatalogResult = z.object({
-  categories: z.array(PluginAIInspirationPresetCategory),
-  presets: z.array(PluginAIInspirationPreset),
-})
-export type PluginAIInspirationGetPresetCatalogResult = z.infer<
-  typeof PluginAIInspirationGetPresetCatalogResult
->
-
-export const PluginAIInspirationOutput = z.object({
-  outputType: z.enum(["image", "video"]),
-  shapeId: z.string(),
-  assetId: z.string(),
-  outputUrl: z.string().optional(),
-  position: PluginAIInspirationPoint.optional(),
-})
-export type PluginAIInspirationOutput = z.infer<
-  typeof PluginAIInspirationOutput
->
-
-export const PluginAIInspirationDebugSummary = z.record(z.string(), JsonValue)
-export type PluginAIInspirationDebugSummary = z.infer<
-  typeof PluginAIInspirationDebugSummary
->
-
-export const PluginAIInspirationRunMetadata = z.object({
-  geometryFidelity: z.string().optional(),
-  debugSummary: PluginAIInspirationDebugSummary.optional(),
-  streetViewComposite: z
-    .object({
-      used: z.boolean(),
-      renderMode: z.enum(["prompt_refs_default", "masked_composite_pilot"]),
-      backgroundLabel: z.string().optional(),
-    })
-    .optional(),
-})
-export type PluginAIInspirationRunMetadata = z.infer<
-  typeof PluginAIInspirationRunMetadata
->
-
-export const PluginAIInspirationGenerateArgs = z.object({
-  sourceShapeId: z.string().min(1),
-  prompt: z.string().min(1).max(8000),
-  modelId: z.string().optional(),
-  referenceShapeIds: z.array(z.string()).max(12).optional(),
-  referenceStrength: z.enum(["low", "medium", "high"]).optional(),
-  appliedPreset: PluginAIInspirationAppliedPreset.optional(),
-  site: PluginAIInspirationSiteOptions.optional(),
-  regionHint: PluginAIInspirationRegionHint.optional(),
-  sketchGuidance: PluginAIInspirationSketchGuidance.optional(),
-  video: PluginAIInspirationVideoOptions.optional(),
-  runMode: PluginAIInspirationRunMode.optional(),
-})
-export type PluginAIInspirationGenerateArgs = z.infer<
-  typeof PluginAIInspirationGenerateArgs
->
-
-export const PluginAIInspirationRunResult = z.object({
-  jobId: z.string().optional(),
-  output: PluginAIInspirationOutput.optional(),
-  outputs: z.array(PluginAIInspirationOutput).optional(),
-  metadata: PluginAIInspirationRunMetadata.optional(),
-})
-export type PluginAIInspirationRunResult = z.infer<
-  typeof PluginAIInspirationRunResult
->
-
-export const PluginAIInspirationRefineArgs = z.object({
-  sourceShapeId: z.string().min(1),
-  upscaleFactor: z
-    .union([z.literal(1.5), z.literal(2), z.literal(4)])
-    .optional(),
-  runMode: PluginAIInspirationRunMode.optional(),
-})
-export type PluginAIInspirationRefineArgs = z.infer<
-  typeof PluginAIInspirationRefineArgs
->
-
-export const PluginAIInspirationJobProgress = z.object({
-  currentStep: z.number().int().nonnegative().optional(),
-  totalSteps: z.number().int().nonnegative().optional(),
-  message: z.string().optional(),
-})
-export type PluginAIInspirationJobProgress = z.infer<
-  typeof PluginAIInspirationJobProgress
->
-
-export const PluginAIInspirationJob = z.object({
-  jobId: z.string(),
-  status: PluginAIInspirationJobStatus,
-  createdAt: z.number(),
-  updatedAt: z.number(),
-  completedAt: z.number().optional(),
-  method: z.string(),
-  progress: PluginAIInspirationJobProgress.optional(),
-  result: PluginAIInspirationRunResult.optional(),
-  error: z.string().optional(),
-})
-export type PluginAIInspirationJob = z.infer<typeof PluginAIInspirationJob>
-
-export const PluginAIInspirationJobArgs = z.object({
-  jobId: z.string().min(1),
-})
-export type PluginAIInspirationJobArgs = z.infer<
-  typeof PluginAIInspirationJobArgs
->
-
-export const PluginAIInspirationGetJobResult = z.object({
-  job: PluginAIInspirationJob,
-})
-export type PluginAIInspirationGetJobResult = z.infer<
-  typeof PluginAIInspirationGetJobResult
->
-
-export const PluginAIInspirationCancelJobResult = z.object({
-  job: PluginAIInspirationJob,
-})
-export type PluginAIInspirationCancelJobResult = z.infer<
-  typeof PluginAIInspirationCancelJobResult
->
-
-export const PluginAIInspirationListJobsResult = z.object({
-  jobs: z.array(PluginAIInspirationJob),
-})
-export type PluginAIInspirationListJobsResult = z.infer<
-  typeof PluginAIInspirationListJobsResult
->
-
-export const PluginAIInspirationWorkflowVideoConfig = z.object({
-  mode: z.string().optional(),
-  motion: z.string().optional(),
-  duration: z.string().optional(),
-  endFrameShapeId: z.string().optional(),
-})
-export type PluginAIInspirationWorkflowVideoConfig = z.infer<
-  typeof PluginAIInspirationWorkflowVideoConfig
->
-
-export const PluginAIInspirationGenerationInputSnapshot = z.object({
-  version: z.literal(1),
-  meta: z.record(z.string(), JsonValue),
-  regionHint: PluginAIInspirationRegionHint.optional(),
-  sketchGuidance: z.record(z.string(), JsonValue).optional(),
-  sourceCameraHeading: z.number().finite().optional(),
-})
-export type PluginAIInspirationGenerationInputSnapshot = z.infer<
-  typeof PluginAIInspirationGenerationInputSnapshot
->
-
-export const PluginAIInspirationWorkflowOperation = z.object({
-  type: z.enum(["generate-image", "refine", "generate-video"]),
-  label: z.string(),
-  prompt: z.string().optional(),
-  modelId: z.string().optional(),
-  presetId: z.string().optional(),
-  presetName: z.string().optional(),
-  refineFactor: z.number().finite().optional(),
-  sourceRole: z.enum(["primary", "end-frame"]).optional(),
-  video: PluginAIInspirationWorkflowVideoConfig.optional(),
-  generationInput: PluginAIInspirationGenerationInputSnapshot.optional(),
-})
-export type PluginAIInspirationWorkflowOperation = z.infer<
-  typeof PluginAIInspirationWorkflowOperation
->
-
-export const PluginAIInspirationWorkflowNode = z.object({
-  id: z.string(),
-  shapeId: z.string(),
-  assetId: z.string().optional(),
-  kind: PluginAIInspirationOutputKind,
-  state: z.string(),
-  runState: PluginAIInspirationWorkflowRunState.optional(),
-  staleReason: z.string().optional(),
-  incomingEdgeIds: z.array(z.string()),
-  outgoingEdgeIds: z.array(z.string()),
-  createdAt: z.number(),
-  updatedAt: z.number(),
-})
-export type PluginAIInspirationWorkflowNode = z.infer<
-  typeof PluginAIInspirationWorkflowNode
->
-
-export const PluginAIInspirationWorkflowEdge = z.object({
-  id: z.string(),
-  sourceNodeId: z.string(),
-  targetNodeId: z.string(),
-  arrowShapeId: z.string().optional(),
-  operation: PluginAIInspirationWorkflowOperation,
-  state: z.string(),
-  runState: PluginAIInspirationWorkflowRunState.optional(),
-  staleReason: z.string().optional(),
-  supersededByEdgeId: z.string().optional(),
-  createdAt: z.number(),
-  updatedAt: z.number(),
-})
-export type PluginAIInspirationWorkflowEdge = z.infer<
-  typeof PluginAIInspirationWorkflowEdge
->
-
-export const PluginAIInspirationWorkflow = z.object({
-  id: z.string(),
-  rootNodeIds: z.array(z.string()),
-  nodeIds: z.array(z.string()),
-  edgeIds: z.array(z.string()),
-  nodes: z.record(z.string(), PluginAIInspirationWorkflowNode),
-  edges: z.record(z.string(), PluginAIInspirationWorkflowEdge),
-  createdAt: z.number(),
-  updatedAt: z.number(),
-})
-export type PluginAIInspirationWorkflow = z.infer<
-  typeof PluginAIInspirationWorkflow
->
-
-export const PluginAIInspirationGetWorkflowForShapeArgs = z.object({
-  shapeId: z.string().min(1),
-})
-export type PluginAIInspirationGetWorkflowForShapeArgs = z.infer<
-  typeof PluginAIInspirationGetWorkflowForShapeArgs
->
-
-export const PluginAIInspirationGetWorkflowForShapeResult = z.object({
-  workflow: PluginAIInspirationWorkflow.nullable(),
-  node: PluginAIInspirationWorkflowNode.nullable(),
-})
-export type PluginAIInspirationGetWorkflowForShapeResult = z.infer<
-  typeof PluginAIInspirationGetWorkflowForShapeResult
->
-
-export const PluginAIInspirationRerunPlanResult = z.discriminatedUnion(
-  "status",
-  [
-    z.object({
-      status: z.literal("ready"),
-      workflowId: z.string(),
-      sourceNode: PluginAIInspirationWorkflowNode,
-      edgeIds: z.array(z.string()),
-      edges: z.array(PluginAIInspirationWorkflowEdge),
-      recipe: z.lazy(() => PluginAIInspirationRecipe),
-      needsEndFrame: z.boolean(),
-      defaultEndFrameShapeId: z.string().nullable(),
-    }),
-    z.object({
-      status: z.literal("unavailable"),
-      reason: z.enum([
-        "not-in-workflow",
-        "source-only",
-        "running",
-        "missing-input",
-      ]),
-    }),
-  ],
-)
-export type PluginAIInspirationRerunPlanResult = z.infer<
-  typeof PluginAIInspirationRerunPlanResult
->
-
-export const PluginAIInspirationRerunSelectedBranchArgs = z.object({
-  shapeId: z.string().min(1),
-  endFrameShapeId: z.string().optional(),
-  runMode: PluginAIInspirationRunMode.optional(),
-})
-export type PluginAIInspirationRerunSelectedBranchArgs = z.infer<
-  typeof PluginAIInspirationRerunSelectedBranchArgs
->
-
-export const PluginAIInspirationRecipeSlot = z.object({
-  id: z.string(),
-  type: z.enum(["source-image", "end-frame"]),
-  label: z.string(),
-  required: z.boolean(),
-})
-export type PluginAIInspirationRecipeSlot = z.infer<
-  typeof PluginAIInspirationRecipeSlot
->
-
-export const PluginAIInspirationRecipeStep = z.object({
-  id: z.string(),
-  operation: PluginAIInspirationWorkflowOperation,
-  outputKind: z.enum(["image", "video"]),
-})
-export type PluginAIInspirationRecipeStep = z.infer<
-  typeof PluginAIInspirationRecipeStep
->
-
-export const PluginAIInspirationRecipeDraft = z.object({
-  name: z.string(),
-  summary: z.string(),
-  slots: z.array(PluginAIInspirationRecipeSlot),
-  steps: z.array(PluginAIInspirationRecipeStep).min(1).max(20),
-  outputKind: z.enum(["image", "video"]),
-  thumbnailUrl: z.string().optional(),
-})
-export type PluginAIInspirationRecipeDraft = z.infer<
-  typeof PluginAIInspirationRecipeDraft
->
-
-export const PluginAIInspirationRecipe: z.ZodType<
-  PluginAIInspirationRecipeDraft & {
-    version: 1
-    id: string
-    fingerprint?: string
-    createdAt: number
-    updatedAt: number
-  }
-> = PluginAIInspirationRecipeDraft.extend({
-  version: z.literal(1),
-  id: z.string(),
-  fingerprint: z.string().optional(),
-  createdAt: z.number(),
-  updatedAt: z.number(),
-})
-export type PluginAIInspirationRecipe = z.infer<
-  typeof PluginAIInspirationRecipe
->
-
-export const PluginAIInspirationExtractionResult = z.discriminatedUnion(
-  "status",
-  [
-    z.object({
-      status: z.literal("ready"),
-      draft: PluginAIInspirationRecipeDraft,
-    }),
-    z.object({
-      status: z.literal("unavailable"),
-      reason: z.enum([
-        "not-in-workflow",
-        "source-only",
-        "missing-workflow",
-        "missing-node",
-        "missing-input",
-        "invalid-workflow",
-      ]),
-    }),
-  ],
-)
-export type PluginAIInspirationExtractionResult = z.infer<
-  typeof PluginAIInspirationExtractionResult
->
-
-export const PluginAIInspirationListRecipesResult = z.object({
-  recipes: z.array(PluginAIInspirationRecipe),
-})
-export type PluginAIInspirationListRecipesResult = z.infer<
-  typeof PluginAIInspirationListRecipesResult
->
-
-export const PluginAIInspirationSaveRecipeArgs = z.object({
-  draft: PluginAIInspirationRecipeDraft,
-  name: z.string().min(1),
-})
-export type PluginAIInspirationSaveRecipeArgs = z.infer<
-  typeof PluginAIInspirationSaveRecipeArgs
->
-
-export const PluginAIInspirationSaveRecipeResult = z.discriminatedUnion(
-  "status",
-  [
-    z.object({ status: z.literal("saved"), recipe: PluginAIInspirationRecipe }),
-    z.object({
-      status: z.literal("duplicate"),
-      recipe: PluginAIInspirationRecipe,
-    }),
-    z.object({ status: z.literal("invalid-name"), recipe: z.null() }),
-    z.object({ status: z.literal("failed"), recipe: z.null() }),
-  ],
-)
-export type PluginAIInspirationSaveRecipeResult = z.infer<
-  typeof PluginAIInspirationSaveRecipeResult
->
-
-export const PluginAIInspirationDeleteRecipeArgs = z.object({
-  recipeId: z.string().min(1),
-})
-export type PluginAIInspirationDeleteRecipeArgs = z.infer<
-  typeof PluginAIInspirationDeleteRecipeArgs
->
-
-export const PluginAIInspirationDeleteRecipeResult = z.object({
-  deleted: z.boolean(),
-})
-export type PluginAIInspirationDeleteRecipeResult = z.infer<
-  typeof PluginAIInspirationDeleteRecipeResult
->
-
-export const PluginAIInspirationExtractRecipeFromShapeArgs = z.object({
-  shapeId: z.string().min(1),
-})
-export type PluginAIInspirationExtractRecipeFromShapeArgs = z.infer<
-  typeof PluginAIInspirationExtractRecipeFromShapeArgs
->
-
-export const PluginAIInspirationRunRecipeArgs = z.object({
-  recipeId: z.string().optional(),
-  recipe: PluginAIInspirationRecipe.optional(),
-  slotShapeIds: z.record(z.string(), z.string()),
-  runMode: PluginAIInspirationRunMode.optional(),
-})
-export type PluginAIInspirationRunRecipeArgs = z.infer<
-  typeof PluginAIInspirationRunRecipeArgs
->
-
-/**
- * Present-mode AI Inspiration APIs.
- *
- * These APIs operate on Present canvas shape IDs and inherit the current user's
- * AI quota. They create outputs on the Present canvas; pure backend generation
- * without canvas output is intentionally out of scope.
- *
- * Long-running generations can be started with `runMode: "job"` and tracked via
- * {@linkcode PluginPresentationAIInspirationApi.getJob} /
- * {@linkcode PluginPresentationAIInspirationApi.listJobs}; the default
- * `"blocking"` mode resolves with the canvas outputs directly.
- *
- * Accessed via `snaptrude.presentation.aiInspiration`.
- */
-export abstract class PluginPresentationAIInspirationApi {
-  constructor() {}
-
-  /**
-   * List AI Inspiration models that can be used for generation.
-   *
-   * @returns The default model ID and available model descriptors.
-   *
-   * @examplePrompt What AI inspiration models can I use?
-   * @examplePrompt List the available image and video models
-   * @examplePrompt Which generation model is the default?
-   *
-   * # Example
-   * ```ts
-   * const { defaultModelId, models } = await snaptrude.presentation.aiInspiration.listModels()
-   * const videoModels = models.filter((m) => m.output === "video")
-   * console.log(defaultModelId, videoModels.map((m) => m.id))
-   * ```
-   */
-  public abstract listModels(): PluginApiReturn<PluginAIInspirationListModelsResult>
-
-  /**
-   * Get capability flags for a model.
-   *
-   * @param args - Object containing `modelId`.
-   * @returns Capability flags such as reference, site-context, region, and keyframe support.
-   *
-   * @examplePrompt What can this model do?
-   * @examplePrompt Does the default model support reference images?
-   * @examplePrompt Check if the video model supports keyframes
-   *
-   * # Example
-   * ```ts
-   * const { defaultModelId } = await snaptrude.presentation.aiInspiration.listModels()
-   * const { capability } = await snaptrude.presentation.aiInspiration.getModelCapabilities({
-   *   modelId: defaultModelId,
-   * })
-   * console.log(capability.supportsReferenceImages, capability.maxExtraImages)
-   * ```
-   */
-  public abstract getModelCapabilities(
-    args: PluginAIInspirationGetModelCapabilitiesArgs,
-  ): PluginApiReturn<PluginAIInspirationGetModelCapabilitiesResult>
-
-  /**
-   * List image/view/video sources on the current Present page.
-   *
-   * @param args - Optional filters. Set `includeGenerated` to include AI outputs.
-   * @returns Serializable shape references using Present canvas shape IDs.
-   *
-   * @examplePrompt List the images I can generate from on this page
-   * @examplePrompt What source shapes are on the present canvas?
-   * @examplePrompt Show me the reference images available for AI generation
-   *
-   * # Example
-   * ```ts
-   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })
-   * for (const s of sources) console.log(s.kind, s.shapeId, s.name)
-   * ```
-   */
-  public abstract listSources(
-    args: PluginAIInspirationListSourcesArgs,
-  ): PluginApiReturn<PluginAIInspirationListSourcesResult>
-
-  /**
-   * Get selected Present canvas shapes that AI Inspiration can use.
-   *
-   * @returns Selected shape IDs and resolved source references.
-   *
-   * @examplePrompt Generate from what I have selected
-   * @examplePrompt Which of my selected shapes can be used as AI sources?
-   *
-   * # Example
-   * ```ts
-   * const { selectedShapeIds, sources } = await snaptrude.presentation.aiInspiration.getSelection()
-   * console.log(selectedShapeIds.length, "selected,", sources.length, "usable")
-   * ```
-   */
-  public abstract getSelection(): PluginApiReturn<PluginAIInspirationGetSelectionResult>
-
-  /**
-   * Get the curated AI Inspiration preset catalog.
-   *
-   * @returns Preset categories and presets.
-   *
-   * @examplePrompt What style presets are available?
-   * @examplePrompt List the curated AI generation presets
-   * @examplePrompt Show me the exterior render styles
-   *
-   * # Example
-   * ```ts
-   * const { categories, presets } = await snaptrude.presentation.aiInspiration.getPresetCatalog()
-   * const exterior = presets.filter((p) => p.categoryLabel === "Exterior")
-   * console.log(categories.map((c) => c.label), exterior.map((p) => p.name))
-   * ```
-   */
-  public abstract getPresetCatalog(): PluginApiReturn<PluginAIInspirationGetPresetCatalogResult>
-
-  /**
-   * Generate an image or video from a Present canvas source.
-   *
-   * @param args - Generation options including source, prompt, model, references, site context,
-   * region guidance, sketch guidance, video options, and run mode.
-   * @returns The created canvas output(s) in blocking mode, or a `jobId` when
-   * called with `runMode: "job"`.
-   *
-   * @examplePrompt Generate an image from this sketch
-   * @examplePrompt Render the selected view as a photorealistic image
-   * @examplePrompt Make an AI image of a modern facade from this source
-   * @examplePrompt Generate a video from this image
-   * @examplePrompt Turn this massing into a rendered street view
-   *
-   * # Example
-   * ```ts
-   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({})
-   * const [source, ...refs] = sources
-   * const { outputs } = await snaptrude.presentation.aiInspiration.generate({
-   *   sourceShapeId: source.shapeId,
-   *   prompt: "Photorealistic render of a modern timber facade at dusk",
-   *   referenceShapeIds: refs.slice(0, 2).map((r) => r.shapeId),
-   *   referenceStrength: "medium",
-   * })
-   * for (const out of outputs ?? []) console.log(out.outputType, out.shapeId, out.outputUrl)
-   * ```
-   */
-  public abstract generate(
-    args: PluginAIInspirationGenerateArgs,
-  ): PluginApiReturn<PluginAIInspirationRunResult>
-
-  /**
-   * Refine/upscale an AI Inspiration source image.
-   *
-   * @param args - Source shape, optional upscale factor, and run mode.
-   * @returns The refined canvas output(s) in blocking mode, or a `jobId` when
-   * called with `runMode: "job"`.
-   *
-   * @examplePrompt Upscale this AI image
-   * @examplePrompt Refine and sharpen the selected render
-   * @examplePrompt Make this generated image higher resolution
-   *
-   * # Example
-   * ```ts
-   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })
-   * const image = sources.find((s) => s.kind === "image")
-   * if (image) {
-   *   const { outputs } = await snaptrude.presentation.aiInspiration.refine({
-   *     sourceShapeId: image.shapeId,
-   *     upscaleFactor: 2,
-   *   })
-   *   console.log(outputs?.[0]?.shapeId)
-   * }
-   * ```
-   */
-  public abstract refine(
-    args: PluginAIInspirationRefineArgs,
-  ): PluginApiReturn<PluginAIInspirationRunResult>
-
-  /**
-   * Get a transient AI Inspiration job by ID.
-   *
-   * @param args - Object containing `jobId`.
-   * @returns The job with status, progress, and result when completed.
-   *
-   * @examplePrompt Is my render finished?
-   * @examplePrompt Check on the generation job
-   *
-   * # Example
-   * ```ts
-   * const { jobId } = await snaptrude.presentation.aiInspiration.generate({
-   *   sourceShapeId: source.shapeId,
-   *   prompt: "Aerial dusk render",
-   *   runMode: "job",
-   * })
-   * const { job } = await snaptrude.presentation.aiInspiration.getJob({ jobId })
-   * console.log(job.status, job.progress?.message)
-   * ```
-   */
-  public abstract getJob(
-    args: PluginAIInspirationJobArgs,
-  ): PluginApiReturn<PluginAIInspirationGetJobResult>
-
-  /**
-   * Cancel a transient AI Inspiration job.
-   *
-   * @param args - Object containing `jobId`.
-   * @returns The job after the cancel request.
-   *
-   * @examplePrompt Cancel the running generation
-   * @examplePrompt Stop that AI job
-   *
-   * # Example
-   * ```ts
-   * const { job } = await snaptrude.presentation.aiInspiration.cancelJob({ jobId })
-   * console.log(job.status) // "cancelled" (or a terminal state it already reached)
-   * ```
-   */
-  public abstract cancelJob(
-    args: PluginAIInspirationJobArgs,
-  ): PluginApiReturn<PluginAIInspirationCancelJobResult>
-
-  /**
-   * List transient AI Inspiration jobs created in the current host session.
-   *
-   * @returns Jobs with their statuses, newest first.
-   *
-   * @examplePrompt What AI jobs are running?
-   * @examplePrompt Show my generation queue
-   *
-   * # Example
-   * ```ts
-   * const { jobs } = await snaptrude.presentation.aiInspiration.listJobs()
-   * const running = jobs.filter((j) => j.status === "running" || j.status === "queued")
-   * console.log(running.map((j) => `${j.jobId}: ${j.method}`))
-   * ```
-   */
-  public abstract listJobs(): PluginApiReturn<PluginAIInspirationListJobsResult>
-
-  /**
-   * Get the sanitized workflow graph containing a Present shape.
-   *
-   * @param args - Object containing `shapeId`.
-   * @returns The workflow and matching node, or `null` values when the shape is not in a workflow.
-   *
-   * @examplePrompt Show the generation history of this image
-   * @examplePrompt What workflow produced this shape?
-   *
-   * # Example
-   * ```ts
-   * const { workflow, node } = await snaptrude.presentation.aiInspiration.getWorkflowForShape({
-   *   shapeId: selected.shapeId,
-   * })
-   * if (workflow && node) console.log(node.id, workflow.edgeIds.length, "edges")
-   * ```
-   */
-  public abstract getWorkflowForShape(
-    args: PluginAIInspirationGetWorkflowForShapeArgs,
-  ): PluginApiReturn<PluginAIInspirationGetWorkflowForShapeResult>
-
-  /**
-   * Build a rerun plan for the selected workflow branch ending at a shape.
-   *
-   * @param args - Object containing `shapeId`.
-   * @returns Ready plan data or an unavailable reason.
-   *
-   * @examplePrompt Can I rerun the steps that produced this output?
-   * @examplePrompt Preview the rerun for this generated image
-   *
-   * # Example
-   * ```ts
-   * const plan = await snaptrude.presentation.aiInspiration.getSelectedBranchRerunPlan({
-   *   shapeId: selected.shapeId,
-   * })
-   * if (plan.status === "ready") console.log(plan.edges.map((e) => e.operation.label))
-   * else console.log("Cannot rerun:", plan.reason)
-   * ```
-   */
-  public abstract getSelectedBranchRerunPlan(
-    args: PluginAIInspirationGetWorkflowForShapeArgs,
-  ): PluginApiReturn<PluginAIInspirationRerunPlanResult>
-
-  /**
-   * Rerun the selected workflow branch and supersede the previous branch.
-   *
-   * @param args - Selected shape, optional end frame shape, and run mode.
-   * @returns New canvas outputs in blocking mode, or a `jobId` when called with
-   * `runMode: "job"`.
-   *
-   * @examplePrompt Rerun this generation branch
-   * @examplePrompt Regenerate this output with the same steps
-   *
-   * # Example
-   * ```ts
-   * const { outputs } = await snaptrude.presentation.aiInspiration.rerunSelectedBranch({
-   *   shapeId: selected.shapeId,
-   * })
-   * console.log(outputs?.map((o) => o.shapeId))
-   * ```
-   */
-  public abstract rerunSelectedBranch(
-    args: PluginAIInspirationRerunSelectedBranchArgs,
-  ): PluginApiReturn<PluginAIInspirationRunResult>
-
-  /**
-   * Extract a reusable recipe draft from the workflow path ending at a shape.
-   *
-   * @param args - Object containing `shapeId`.
-   * @returns A recipe draft or an unavailable reason.
-   *
-   * @examplePrompt Turn this workflow into a reusable recipe
-   * @examplePrompt Save the generation steps behind this image
-   *
-   * # Example
-   * ```ts
-   * const extraction = await snaptrude.presentation.aiInspiration.extractRecipeFromShape({
-   *   shapeId: selected.shapeId,
-   * })
-   * if (extraction.status === "ready") console.log(extraction.draft.summary)
-   * ```
-   */
-  public abstract extractRecipeFromShape(
-    args: PluginAIInspirationExtractRecipeFromShapeArgs,
-  ): PluginApiReturn<PluginAIInspirationExtractionResult>
-
-  /**
-   * List project-level AI Inspiration recipes stored in Present document metadata.
-   *
-   * @returns Saved project recipes.
-   *
-   * @examplePrompt What AI recipes are saved in this project?
-   * @examplePrompt List my generation recipes
-   *
-   * # Example
-   * ```ts
-   * const { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()
-   * console.log(recipes.map((r) => `${r.name} → ${r.outputKind}`))
-   * ```
-   */
-  public abstract listRecipes(): PluginApiReturn<PluginAIInspirationListRecipesResult>
-
-  /**
-   * Save a project-level AI Inspiration recipe.
-   *
-   * @param args - Recipe draft and desired name.
-   * @returns Saved, duplicate, invalid-name, or failed status.
-   *
-   * @examplePrompt Save this recipe as "Dusk facade render"
-   * @examplePrompt Store these generation steps for reuse
-   *
-   * # Example
-   * ```ts
-   * const extraction = await snaptrude.presentation.aiInspiration.extractRecipeFromShape({
-   *   shapeId: selected.shapeId,
-   * })
-   * if (extraction.status === "ready") {
-   *   const saved = await snaptrude.presentation.aiInspiration.saveRecipe({
-   *     draft: extraction.draft,
-   *     name: "Dusk facade render",
-   *   })
-   *   console.log(saved.status, saved.recipe?.id)
-   * }
-   * ```
-   */
-  public abstract saveRecipe(
-    args: PluginAIInspirationSaveRecipeArgs,
-  ): PluginApiReturn<PluginAIInspirationSaveRecipeResult>
-
-  /**
-   * Delete a project-level AI Inspiration recipe.
-   *
-   * @param args - Object containing `recipeId`.
-   * @returns Whether a recipe was deleted.
-   *
-   * @examplePrompt Delete the facade render recipe
-   * @examplePrompt Remove that saved AI recipe
-   *
-   * # Example
-   * ```ts
-   * const { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()
-   * const stale = recipes.find((r) => r.name === "Old style test")
-   * if (stale) {
-   *   const { deleted } = await snaptrude.presentation.aiInspiration.deleteRecipe({ recipeId: stale.id })
-   *   console.log(deleted)
-   * }
-   * ```
-   */
-  public abstract deleteRecipe(
-    args: PluginAIInspirationDeleteRecipeArgs,
-  ): PluginApiReturn<PluginAIInspirationDeleteRecipeResult>
-
-  /**
-   * Run a saved or inline recipe against Present canvas slot shapes.
-   *
-   * @param args - Saved `recipeId` or inline `recipe`, slot shape IDs, and run mode.
-   * @returns Canvas outputs in blocking mode, or a `jobId` when called with
-   * `runMode: "job"`.
-   *
-   * @examplePrompt Apply my saved recipe to this image
-   * @examplePrompt Run the dusk-render recipe on the selected view
-   *
-   * # Example
-   * ```ts
-   * const { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()
-   * const recipe = recipes[0]
-   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({})
-   * const { outputs } = await snaptrude.presentation.aiInspiration.runRecipe({
-   *   recipeId: recipe.id,
-   *   slotShapeIds: { [recipe.slots[0].id]: sources[0].shapeId },
-   * })
-   * console.log(outputs?.map((o) => o.outputUrl))
-   * ```
-   */
-  public abstract runRecipe(
-    args: PluginAIInspirationRunRecipeArgs,
-  ): PluginApiReturn<PluginAIInspirationRunResult>
-}
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+
+const JsonPrimitive = z.union([z.string(), z.number(), z.boolean(), z.null()])
+type JsonValue =
+  | z.infer<typeof JsonPrimitive>
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+const JsonValue: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([JsonPrimitive, z.array(JsonValue), z.record(z.string(), JsonValue)]),
+)
+
+export const PluginAIInspirationRunMode = z.enum(["blocking", "job"])
+export type PluginAIInspirationRunMode = z.infer<
+  typeof PluginAIInspirationRunMode
+>
+
+export const PluginAIInspirationOutputKind = z.enum([
+  "source",
+  "image",
+  "video",
+])
+export type PluginAIInspirationOutputKind = z.infer<
+  typeof PluginAIInspirationOutputKind
+>
+
+export const PluginAIInspirationModelOutput = z.enum(["image", "video"])
+export type PluginAIInspirationModelOutput = z.infer<
+  typeof PluginAIInspirationModelOutput
+>
+
+export const PluginAIInspirationRuntimeProvider = z.enum(["gpt", "fal"])
+export type PluginAIInspirationRuntimeProvider = z.infer<
+  typeof PluginAIInspirationRuntimeProvider
+>
+
+export const PluginAIInspirationPromptStrategy = z.enum([
+  "gpt-image",
+  "fal-image",
+  "fal-video",
+])
+export type PluginAIInspirationPromptStrategy = z.infer<
+  typeof PluginAIInspirationPromptStrategy
+>
+
+export const PluginAIInspirationShapeKind = z.enum(["image", "view", "video"])
+export type PluginAIInspirationShapeKind = z.infer<
+  typeof PluginAIInspirationShapeKind
+>
+
+export const PluginAIInspirationVideoMode = z.enum([
+  "animate",
+  "references",
+  "keyframes",
+])
+export type PluginAIInspirationVideoMode = z.infer<
+  typeof PluginAIInspirationVideoMode
+>
+
+export const PluginAIInspirationVideoMotion = z.enum([
+  "auto",
+  "slow-dolly",
+  "subtle-orbit",
+  "reveal",
+])
+export type PluginAIInspirationVideoMotion = z.infer<
+  typeof PluginAIInspirationVideoMotion
+>
+
+export const PluginAIInspirationVideoDuration = z.enum(["4s", "6s", "8s"])
+export type PluginAIInspirationVideoDuration = z.infer<
+  typeof PluginAIInspirationVideoDuration
+>
+
+export const PluginAIInspirationJobStatus = z.enum([
+  "queued",
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+])
+export type PluginAIInspirationJobStatus = z.infer<
+  typeof PluginAIInspirationJobStatus
+>
+
+export const PluginAIInspirationWorkflowRunState = z.enum([
+  "current",
+  "stale",
+  "running",
+  "failed",
+  "superseded",
+])
+export type PluginAIInspirationWorkflowRunState = z.infer<
+  typeof PluginAIInspirationWorkflowRunState
+>
+
+export const PluginAIInspirationRegionHint = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  w: z.number().finite().positive(),
+  h: z.number().finite().positive(),
+})
+export type PluginAIInspirationRegionHint = z.infer<
+  typeof PluginAIInspirationRegionHint
+>
+
+export const PluginAIInspirationPoint = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+})
+export type PluginAIInspirationPoint = z.infer<typeof PluginAIInspirationPoint>
+
+export const PluginAIInspirationTextAnnotation = z.object({
+  text: z.string().min(1),
+  x: z.number().finite().optional(),
+  y: z.number().finite().optional(),
+})
+export type PluginAIInspirationTextAnnotation = z.infer<
+  typeof PluginAIInspirationTextAnnotation
+>
+
+export const PluginAIInspirationSketchGuidance = z.object({
+  visualShapeIds: z.array(z.string()).optional(),
+  textAnnotations: z.array(PluginAIInspirationTextAnnotation).optional(),
+})
+export type PluginAIInspirationSketchGuidance = z.infer<
+  typeof PluginAIInspirationSketchGuidance
+>
+
+export const PluginAIInspirationSiteOptions = z.object({
+  includeSatellite: z.boolean().optional(),
+  includeStreetView: z.boolean().optional(),
+  includeAerial: z.boolean().optional(),
+  aerialBearing: z.number().finite().optional(),
+  aerialPitch: z.number().finite().optional(),
+  selectedDiagramIds: z.array(z.string()).optional(),
+  location: z
+    .object({
+      lat: z.number().finite(),
+      lng: z.number().finite(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationSiteOptions = z.infer<
+  typeof PluginAIInspirationSiteOptions
+>
+
+export const PluginAIInspirationAppliedPreset = z.object({
+  source: z.enum(["curated", "user"]),
+  presetId: z.string().min(1),
+  name: z.string().min(1),
+  savedPresetKind: z.enum(["prompt", "style"]).optional(),
+  stylePrompt: z.string().optional(),
+  modelId: z.string().optional(),
+  referenceImages: z
+    .array(
+      z.object({
+        url: z.string().min(1),
+        label: z.string().optional(),
+        weight: z.number().finite().optional(),
+      }),
+    )
+    .optional(),
+  siteDefaults: z
+    .object({
+      includeSatellite: z.boolean().optional(),
+      includeStreetView: z.boolean().optional(),
+      includeAerial: z.boolean().optional(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationAppliedPreset = z.infer<
+  typeof PluginAIInspirationAppliedPreset
+>
+
+export const PluginAIInspirationVideoOptions = z.object({
+  mode: PluginAIInspirationVideoMode.optional(),
+  endFrameShapeId: z.string().optional(),
+  motion: PluginAIInspirationVideoMotion.optional(),
+  duration: PluginAIInspirationVideoDuration.optional(),
+})
+export type PluginAIInspirationVideoOptions = z.infer<
+  typeof PluginAIInspirationVideoOptions
+>
+
+export const PluginAIInspirationModel = z.object({
+  id: z.string(),
+  label: z.string(),
+  supportsMultiImage: z.boolean(),
+  output: PluginAIInspirationModelOutput,
+  isDefault: z.boolean().optional(),
+})
+export type PluginAIInspirationModel = z.infer<typeof PluginAIInspirationModel>
+
+export const PluginAIInspirationModelCapability = z.object({
+  id: z.string(),
+  output: PluginAIInspirationModelOutput,
+  provider: PluginAIInspirationRuntimeProvider,
+  supportsRegionEdit: z.boolean(),
+  supportsReferenceImages: z.boolean(),
+  supportsStylePresets: z.boolean(),
+  supportsSiteContext: z.boolean(),
+  supportsSketchGuidance: z.boolean(),
+  supportsKeyframes: z.boolean(),
+  maxExtraImages: z.number().int().nonnegative(),
+  promptStrategy: PluginAIInspirationPromptStrategy,
+})
+export type PluginAIInspirationModelCapability = z.infer<
+  typeof PluginAIInspirationModelCapability
+>
+
+export const PluginAIInspirationListModelsResult = z.object({
+  defaultModelId: z.string(),
+  models: z.array(PluginAIInspirationModel),
+})
+export type PluginAIInspirationListModelsResult = z.infer<
+  typeof PluginAIInspirationListModelsResult
+>
+
+export const PluginAIInspirationGetModelCapabilitiesArgs = z.object({
+  modelId: z.string().min(1),
+})
+export type PluginAIInspirationGetModelCapabilitiesArgs = z.infer<
+  typeof PluginAIInspirationGetModelCapabilitiesArgs
+>
+
+export const PluginAIInspirationGetModelCapabilitiesResult = z.object({
+  capability: PluginAIInspirationModelCapability,
+})
+export type PluginAIInspirationGetModelCapabilitiesResult = z.infer<
+  typeof PluginAIInspirationGetModelCapabilitiesResult
+>
+
+export const PluginAIInspirationShapeRef = z.object({
+  shapeId: z.string(),
+  assetId: z.string().optional(),
+  kind: PluginAIInspirationShapeKind,
+  name: z.string().optional(),
+  width: z.number().finite().optional(),
+  height: z.number().finite().optional(),
+  outputType: PluginAIInspirationOutputKind.optional(),
+  sourceUrl: z.string().optional(),
+})
+export type PluginAIInspirationShapeRef = z.infer<
+  typeof PluginAIInspirationShapeRef
+>
+
+export const PluginAIInspirationListSourcesArgs = z.object({
+  includeGenerated: z.boolean().optional(),
+  includeSourceUrl: z.boolean().optional(),
+})
+export type PluginAIInspirationListSourcesArgs = z.infer<
+  typeof PluginAIInspirationListSourcesArgs
+>
+
+export const PluginAIInspirationListSourcesResult = z.object({
+  sources: z.array(PluginAIInspirationShapeRef),
+})
+export type PluginAIInspirationListSourcesResult = z.infer<
+  typeof PluginAIInspirationListSourcesResult
+>
+
+export const PluginAIInspirationGetSelectionResult = z.object({
+  selectedShapeIds: z.array(z.string()),
+  sources: z.array(PluginAIInspirationShapeRef),
+})
+export type PluginAIInspirationGetSelectionResult = z.infer<
+  typeof PluginAIInspirationGetSelectionResult
+>
+
+export const PluginAIInspirationPresetReferenceImage = z.object({
+  url: z.string(),
+  label: z.string().optional(),
+  weight: z.number().finite().optional(),
+})
+export type PluginAIInspirationPresetReferenceImage = z.infer<
+  typeof PluginAIInspirationPresetReferenceImage
+>
+
+export const PluginAIInspirationPreset = z.object({
+  id: z.string(),
+  name: z.string(),
+  source: z.enum(["curated", "user"]),
+  modelId: z.string(),
+  categoryId: z.string().optional(),
+  categoryLabel: z.string().optional(),
+  description: z.string().optional(),
+  previewImageUrl: z.string().optional(),
+  prompt: z.string().optional(),
+  stylePrompt: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  referenceImages: z.array(PluginAIInspirationPresetReferenceImage).optional(),
+  siteDefaults: PluginAIInspirationAppliedPreset.shape.siteDefaults.optional(),
+})
+export type PluginAIInspirationPreset = z.infer<
+  typeof PluginAIInspirationPreset
+>
+
+export const PluginAIInspirationPresetCategory = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+})
+export type PluginAIInspirationPresetCategory = z.infer<
+  typeof PluginAIInspirationPresetCategory
+>
+
+export const PluginAIInspirationGetPresetCatalogResult = z.object({
+  categories: z.array(PluginAIInspirationPresetCategory),
+  presets: z.array(PluginAIInspirationPreset),
+})
+export type PluginAIInspirationGetPresetCatalogResult = z.infer<
+  typeof PluginAIInspirationGetPresetCatalogResult
+>
+
+export const PluginAIInspirationOutput = z.object({
+  outputType: z.enum(["image", "video"]),
+  shapeId: z.string(),
+  assetId: z.string(),
+  outputUrl: z.string().optional(),
+  position: PluginAIInspirationPoint.optional(),
+})
+export type PluginAIInspirationOutput = z.infer<
+  typeof PluginAIInspirationOutput
+>
+
+export const PluginAIInspirationDebugSummary = z.record(z.string(), JsonValue)
+export type PluginAIInspirationDebugSummary = z.infer<
+  typeof PluginAIInspirationDebugSummary
+>
+
+export const PluginAIInspirationRunMetadata = z.object({
+  geometryFidelity: z.string().optional(),
+  debugSummary: PluginAIInspirationDebugSummary.optional(),
+  streetViewComposite: z
+    .object({
+      used: z.boolean(),
+      renderMode: z.enum(["prompt_refs_default", "masked_composite_pilot"]),
+      backgroundLabel: z.string().optional(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationRunMetadata = z.infer<
+  typeof PluginAIInspirationRunMetadata
+>
+
+export const PluginAIInspirationGenerateArgs = z.object({
+  sourceShapeId: z.string().min(1),
+  prompt: z.string().min(1).max(8000),
+  modelId: z.string().optional(),
+  referenceShapeIds: z.array(z.string()).max(12).optional(),
+  referenceStrength: z.enum(["low", "medium", "high"]).optional(),
+  appliedPreset: PluginAIInspirationAppliedPreset.optional(),
+  site: PluginAIInspirationSiteOptions.optional(),
+  regionHint: PluginAIInspirationRegionHint.optional(),
+  sketchGuidance: PluginAIInspirationSketchGuidance.optional(),
+  video: PluginAIInspirationVideoOptions.optional(),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationGenerateArgs = z.infer<
+  typeof PluginAIInspirationGenerateArgs
+>
+
+export const PluginAIInspirationRunResult = z.object({
+  jobId: z.string().optional(),
+  output: PluginAIInspirationOutput.optional(),
+  outputs: z.array(PluginAIInspirationOutput).optional(),
+  metadata: PluginAIInspirationRunMetadata.optional(),
+})
+export type PluginAIInspirationRunResult = z.infer<
+  typeof PluginAIInspirationRunResult
+>
+
+export const PluginAIInspirationRefineArgs = z.object({
+  sourceShapeId: z.string().min(1),
+  upscaleFactor: z
+    .union([z.literal(1.5), z.literal(2), z.literal(4)])
+    .optional(),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationRefineArgs = z.infer<
+  typeof PluginAIInspirationRefineArgs
+>
+
+export const PluginAIInspirationJobProgress = z.object({
+  currentStep: z.number().int().nonnegative().optional(),
+  totalSteps: z.number().int().nonnegative().optional(),
+  message: z.string().optional(),
+})
+export type PluginAIInspirationJobProgress = z.infer<
+  typeof PluginAIInspirationJobProgress
+>
+
+export const PluginAIInspirationJob = z.object({
+  jobId: z.string(),
+  status: PluginAIInspirationJobStatus,
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  completedAt: z.number().optional(),
+  method: z.string(),
+  progress: PluginAIInspirationJobProgress.optional(),
+  result: PluginAIInspirationRunResult.optional(),
+  error: z.string().optional(),
+})
+export type PluginAIInspirationJob = z.infer<typeof PluginAIInspirationJob>
+
+export const PluginAIInspirationJobArgs = z.object({
+  jobId: z.string().min(1),
+})
+export type PluginAIInspirationJobArgs = z.infer<
+  typeof PluginAIInspirationJobArgs
+>
+
+export const PluginAIInspirationGetJobResult = z.object({
+  job: PluginAIInspirationJob,
+})
+export type PluginAIInspirationGetJobResult = z.infer<
+  typeof PluginAIInspirationGetJobResult
+>
+
+export const PluginAIInspirationCancelJobResult = z.object({
+  job: PluginAIInspirationJob,
+})
+export type PluginAIInspirationCancelJobResult = z.infer<
+  typeof PluginAIInspirationCancelJobResult
+>
+
+export const PluginAIInspirationListJobsResult = z.object({
+  jobs: z.array(PluginAIInspirationJob),
+})
+export type PluginAIInspirationListJobsResult = z.infer<
+  typeof PluginAIInspirationListJobsResult
+>
+
+export const PluginAIInspirationWorkflowVideoConfig = z.object({
+  mode: z.string().optional(),
+  motion: z.string().optional(),
+  duration: z.string().optional(),
+  endFrameShapeId: z.string().optional(),
+})
+export type PluginAIInspirationWorkflowVideoConfig = z.infer<
+  typeof PluginAIInspirationWorkflowVideoConfig
+>
+
+export const PluginAIInspirationGenerationInputSnapshot = z.object({
+  version: z.literal(1),
+  meta: z.record(z.string(), JsonValue),
+  regionHint: PluginAIInspirationRegionHint.optional(),
+  sketchGuidance: z.record(z.string(), JsonValue).optional(),
+  sourceCameraHeading: z.number().finite().optional(),
+})
+export type PluginAIInspirationGenerationInputSnapshot = z.infer<
+  typeof PluginAIInspirationGenerationInputSnapshot
+>
+
+export const PluginAIInspirationWorkflowOperation = z.object({
+  type: z.enum(["generate-image", "refine", "generate-video"]),
+  label: z.string(),
+  prompt: z.string().optional(),
+  modelId: z.string().optional(),
+  presetId: z.string().optional(),
+  presetName: z.string().optional(),
+  refineFactor: z.number().finite().optional(),
+  sourceRole: z.enum(["primary", "end-frame"]).optional(),
+  video: PluginAIInspirationWorkflowVideoConfig.optional(),
+  generationInput: PluginAIInspirationGenerationInputSnapshot.optional(),
+})
+export type PluginAIInspirationWorkflowOperation = z.infer<
+  typeof PluginAIInspirationWorkflowOperation
+>
+
+export const PluginAIInspirationWorkflowNode = z.object({
+  id: z.string(),
+  shapeId: z.string(),
+  assetId: z.string().optional(),
+  kind: PluginAIInspirationOutputKind,
+  state: z.string(),
+  runState: PluginAIInspirationWorkflowRunState.optional(),
+  staleReason: z.string().optional(),
+  incomingEdgeIds: z.array(z.string()),
+  outgoingEdgeIds: z.array(z.string()),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationWorkflowNode = z.infer<
+  typeof PluginAIInspirationWorkflowNode
+>
+
+export const PluginAIInspirationWorkflowEdge = z.object({
+  id: z.string(),
+  sourceNodeId: z.string(),
+  targetNodeId: z.string(),
+  arrowShapeId: z.string().optional(),
+  operation: PluginAIInspirationWorkflowOperation,
+  state: z.string(),
+  runState: PluginAIInspirationWorkflowRunState.optional(),
+  staleReason: z.string().optional(),
+  supersededByEdgeId: z.string().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationWorkflowEdge = z.infer<
+  typeof PluginAIInspirationWorkflowEdge
+>
+
+export const PluginAIInspirationWorkflow = z.object({
+  id: z.string(),
+  rootNodeIds: z.array(z.string()),
+  nodeIds: z.array(z.string()),
+  edgeIds: z.array(z.string()),
+  nodes: z.record(z.string(), PluginAIInspirationWorkflowNode),
+  edges: z.record(z.string(), PluginAIInspirationWorkflowEdge),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationWorkflow = z.infer<
+  typeof PluginAIInspirationWorkflow
+>
+
+export const PluginAIInspirationGetWorkflowForShapeArgs = z.object({
+  shapeId: z.string().min(1),
+})
+export type PluginAIInspirationGetWorkflowForShapeArgs = z.infer<
+  typeof PluginAIInspirationGetWorkflowForShapeArgs
+>
+
+export const PluginAIInspirationGetWorkflowForShapeResult = z.object({
+  workflow: PluginAIInspirationWorkflow.nullable(),
+  node: PluginAIInspirationWorkflowNode.nullable(),
+})
+export type PluginAIInspirationGetWorkflowForShapeResult = z.infer<
+  typeof PluginAIInspirationGetWorkflowForShapeResult
+>
+
+export const PluginAIInspirationRerunPlanResult = z.discriminatedUnion(
+  "status",
+  [
+    z.object({
+      status: z.literal("ready"),
+      workflowId: z.string(),
+      sourceNode: PluginAIInspirationWorkflowNode,
+      edgeIds: z.array(z.string()),
+      edges: z.array(PluginAIInspirationWorkflowEdge),
+      recipe: z.lazy(() => PluginAIInspirationRecipe),
+      needsEndFrame: z.boolean(),
+      defaultEndFrameShapeId: z.string().nullable(),
+    }),
+    z.object({
+      status: z.literal("unavailable"),
+      reason: z.enum([
+        "not-in-workflow",
+        "source-only",
+        "running",
+        "missing-input",
+      ]),
+    }),
+  ],
+)
+export type PluginAIInspirationRerunPlanResult = z.infer<
+  typeof PluginAIInspirationRerunPlanResult
+>
+
+export const PluginAIInspirationRerunSelectedBranchArgs = z.object({
+  shapeId: z.string().min(1),
+  endFrameShapeId: z.string().optional(),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationRerunSelectedBranchArgs = z.infer<
+  typeof PluginAIInspirationRerunSelectedBranchArgs
+>
+
+export const PluginAIInspirationRecipeSlot = z.object({
+  id: z.string(),
+  type: z.enum(["source-image", "end-frame"]),
+  label: z.string(),
+  required: z.boolean(),
+})
+export type PluginAIInspirationRecipeSlot = z.infer<
+  typeof PluginAIInspirationRecipeSlot
+>
+
+export const PluginAIInspirationRecipeStep = z.object({
+  id: z.string(),
+  operation: PluginAIInspirationWorkflowOperation,
+  outputKind: z.enum(["image", "video"]),
+})
+export type PluginAIInspirationRecipeStep = z.infer<
+  typeof PluginAIInspirationRecipeStep
+>
+
+export const PluginAIInspirationRecipeDraft = z.object({
+  name: z.string(),
+  summary: z.string(),
+  slots: z.array(PluginAIInspirationRecipeSlot),
+  steps: z.array(PluginAIInspirationRecipeStep).min(1).max(20),
+  outputKind: z.enum(["image", "video"]),
+  thumbnailUrl: z.string().optional(),
+})
+export type PluginAIInspirationRecipeDraft = z.infer<
+  typeof PluginAIInspirationRecipeDraft
+>
+
+export const PluginAIInspirationRecipe: z.ZodType<
+  PluginAIInspirationRecipeDraft & {
+    version: 1
+    id: string
+    fingerprint?: string
+    createdAt: number
+    updatedAt: number
+  }
+> = PluginAIInspirationRecipeDraft.extend({
+  version: z.literal(1),
+  id: z.string(),
+  fingerprint: z.string().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationRecipe = z.infer<
+  typeof PluginAIInspirationRecipe
+>
+
+export const PluginAIInspirationExtractionResult = z.discriminatedUnion(
+  "status",
+  [
+    z.object({
+      status: z.literal("ready"),
+      draft: PluginAIInspirationRecipeDraft,
+    }),
+    z.object({
+      status: z.literal("unavailable"),
+      reason: z.enum([
+        "not-in-workflow",
+        "source-only",
+        "missing-workflow",
+        "missing-node",
+        "missing-input",
+        "invalid-workflow",
+      ]),
+    }),
+  ],
+)
+export type PluginAIInspirationExtractionResult = z.infer<
+  typeof PluginAIInspirationExtractionResult
+>
+
+export const PluginAIInspirationListRecipesResult = z.object({
+  recipes: z.array(PluginAIInspirationRecipe),
+})
+export type PluginAIInspirationListRecipesResult = z.infer<
+  typeof PluginAIInspirationListRecipesResult
+>
+
+export const PluginAIInspirationSaveRecipeArgs = z.object({
+  draft: PluginAIInspirationRecipeDraft,
+  name: z.string().min(1),
+})
+export type PluginAIInspirationSaveRecipeArgs = z.infer<
+  typeof PluginAIInspirationSaveRecipeArgs
+>
+
+export const PluginAIInspirationSaveRecipeResult = z.discriminatedUnion(
+  "status",
+  [
+    z.object({ status: z.literal("saved"), recipe: PluginAIInspirationRecipe }),
+    z.object({
+      status: z.literal("duplicate"),
+      recipe: PluginAIInspirationRecipe,
+    }),
+    z.object({ status: z.literal("invalid-name"), recipe: z.null() }),
+    z.object({ status: z.literal("failed"), recipe: z.null() }),
+  ],
+)
+export type PluginAIInspirationSaveRecipeResult = z.infer<
+  typeof PluginAIInspirationSaveRecipeResult
+>
+
+export const PluginAIInspirationDeleteRecipeArgs = z.object({
+  recipeId: z.string().min(1),
+})
+export type PluginAIInspirationDeleteRecipeArgs = z.infer<
+  typeof PluginAIInspirationDeleteRecipeArgs
+>
+
+export const PluginAIInspirationDeleteRecipeResult = z.object({
+  deleted: z.boolean(),
+})
+export type PluginAIInspirationDeleteRecipeResult = z.infer<
+  typeof PluginAIInspirationDeleteRecipeResult
+>
+
+export const PluginAIInspirationExtractRecipeFromShapeArgs = z.object({
+  shapeId: z.string().min(1),
+})
+export type PluginAIInspirationExtractRecipeFromShapeArgs = z.infer<
+  typeof PluginAIInspirationExtractRecipeFromShapeArgs
+>
+
+export const PluginAIInspirationRunRecipeArgs = z.object({
+  recipeId: z.string().optional(),
+  recipe: PluginAIInspirationRecipe.optional(),
+  slotShapeIds: z.record(z.string(), z.string()),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationRunRecipeArgs = z.infer<
+  typeof PluginAIInspirationRunRecipeArgs
+>
+
+/**
+ * Present-mode AI Inspiration APIs.
+ *
+ * These APIs operate on Present canvas shape IDs and inherit the current user's
+ * AI quota. They create outputs on the Present canvas; pure backend generation
+ * without canvas output is intentionally out of scope.
+ *
+ * Long-running generations can be started with `runMode: "job"` and tracked via
+ * {@linkcode PluginPresentationAIInspirationApi.getJob} /
+ * {@linkcode PluginPresentationAIInspirationApi.listJobs}; the default
+ * `"blocking"` mode resolves with the canvas outputs directly.
+ *
+ * Accessed via `snaptrude.presentation.aiInspiration`.
+ */
+export abstract class PluginPresentationAIInspirationApi {
+  constructor() {}
+
+  /**
+   * List AI Inspiration models that can be used for generation.
+   *
+   * @returns The default model ID and available model descriptors.
+   *
+   * @examplePrompt What AI inspiration models can I use?
+   * @examplePrompt List the available image and video models
+   * @examplePrompt Which generation model is the default?
+   *
+   * # Example
+   * ```ts
+   * const { defaultModelId, models } = await snaptrude.presentation.aiInspiration.listModels()
+   * const videoModels = models.filter((m) => m.output === "video")
+   * console.log(defaultModelId, videoModels.map((m) => m.id))
+   * ```
+   */
+  public abstract listModels(): PluginApiReturn<PluginAIInspirationListModelsResult>
+
+  /**
+   * Get capability flags for a model.
+   *
+   * @param args - Object containing `modelId`.
+   * @returns Capability flags such as reference, site-context, region, and keyframe support.
+   *
+   * @examplePrompt What can this model do?
+   * @examplePrompt Does the default model support reference images?
+   * @examplePrompt Check if the video model supports keyframes
+   *
+   * # Example
+   * ```ts
+   * const { defaultModelId } = await snaptrude.presentation.aiInspiration.listModels()
+   * const { capability } = await snaptrude.presentation.aiInspiration.getModelCapabilities({
+   *   modelId: defaultModelId,
+   * })
+   * console.log(capability.supportsReferenceImages, capability.maxExtraImages)
+   * ```
+   */
+  public abstract getModelCapabilities(
+    args: PluginAIInspirationGetModelCapabilitiesArgs,
+  ): PluginApiReturn<PluginAIInspirationGetModelCapabilitiesResult>
+
+  /**
+   * List image/view/video sources on the current Present page.
+   *
+   * @param args - Optional filters. Set `includeGenerated` to include AI outputs.
+   * @returns Serializable shape references using Present canvas shape IDs.
+   *
+   * @examplePrompt List the images I can generate from on this page
+   * @examplePrompt What source shapes are on the present canvas?
+   * @examplePrompt Show me the reference images available for AI generation
+   *
+   * # Example
+   * ```ts
+   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })
+   * for (const s of sources) console.log(s.kind, s.shapeId, s.name)
+   * ```
+   */
+  public abstract listSources(
+    args: PluginAIInspirationListSourcesArgs,
+  ): PluginApiReturn<PluginAIInspirationListSourcesResult>
+
+  /**
+   * Get selected Present canvas shapes that AI Inspiration can use.
+   *
+   * @returns Selected shape IDs and resolved source references.
+   *
+   * @examplePrompt Generate from what I have selected
+   * @examplePrompt Which of my selected shapes can be used as AI sources?
+   *
+   * # Example
+   * ```ts
+   * const { selectedShapeIds, sources } = await snaptrude.presentation.aiInspiration.getSelection()
+   * console.log(selectedShapeIds.length, "selected,", sources.length, "usable")
+   * ```
+   */
+  public abstract getSelection(): PluginApiReturn<PluginAIInspirationGetSelectionResult>
+
+  /**
+   * Get the curated AI Inspiration preset catalog.
+   *
+   * @returns Preset categories and presets.
+   *
+   * @examplePrompt What style presets are available?
+   * @examplePrompt List the curated AI generation presets
+   * @examplePrompt Show me the exterior render styles
+   *
+   * # Example
+   * ```ts
+   * const { categories, presets } = await snaptrude.presentation.aiInspiration.getPresetCatalog()
+   * const exterior = presets.filter((p) => p.categoryLabel === "Exterior")
+   * console.log(categories.map((c) => c.label), exterior.map((p) => p.name))
+   * ```
+   */
+  public abstract getPresetCatalog(): PluginApiReturn<PluginAIInspirationGetPresetCatalogResult>
+
+  /**
+   * Generate an image or video from a Present canvas source.
+   *
+   * @param args - Generation options including source, prompt, model, references, site context,
+   * region guidance, sketch guidance, video options, and run mode.
+   * @returns The created canvas output(s) in blocking mode, or a `jobId` when
+   * called with `runMode: "job"`.
+   *
+   * @examplePrompt Generate an image from this sketch
+   * @examplePrompt Render the selected view as a photorealistic image
+   * @examplePrompt Make an AI image of a modern facade from this source
+   * @examplePrompt Generate a video from this image
+   * @examplePrompt Turn this massing into a rendered street view
+   *
+   * # Example
+   * ```ts
+   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({})
+   * const [source, ...refs] = sources
+   * const { outputs } = await snaptrude.presentation.aiInspiration.generate({
+   *   sourceShapeId: source.shapeId,
+   *   prompt: "Photorealistic render of a modern timber facade at dusk",
+   *   referenceShapeIds: refs.slice(0, 2).map((r) => r.shapeId),
+   *   referenceStrength: "medium",
+   * })
+   * for (const out of outputs ?? []) console.log(out.outputType, out.shapeId, out.outputUrl)
+   * ```
+   */
+  public abstract generate(
+    args: PluginAIInspirationGenerateArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+
+  /**
+   * Refine/upscale an AI Inspiration source image.
+   *
+   * @param args - Source shape, optional upscale factor, and run mode.
+   * @returns The refined canvas output(s) in blocking mode, or a `jobId` when
+   * called with `runMode: "job"`.
+   *
+   * @examplePrompt Upscale this AI image
+   * @examplePrompt Refine and sharpen the selected render
+   * @examplePrompt Make this generated image higher resolution
+   *
+   * # Example
+   * ```ts
+   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })
+   * const image = sources.find((s) => s.kind === "image")
+   * if (image) {
+   *   const { outputs } = await snaptrude.presentation.aiInspiration.refine({
+   *     sourceShapeId: image.shapeId,
+   *     upscaleFactor: 2,
+   *   })
+   *   console.log(outputs?.[0]?.shapeId)
+   * }
+   * ```
+   */
+  public abstract refine(
+    args: PluginAIInspirationRefineArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+
+  /**
+   * Get a transient AI Inspiration job by ID.
+   *
+   * @param args - Object containing `jobId`.
+   * @returns The job with status, progress, and result when completed.
+   *
+   * @examplePrompt Is my render finished?
+   * @examplePrompt Check on the generation job
+   *
+   * # Example
+   * ```ts
+   * const { jobId } = await snaptrude.presentation.aiInspiration.generate({
+   *   sourceShapeId: source.shapeId,
+   *   prompt: "Aerial dusk render",
+   *   runMode: "job",
+   * })
+   * const { job } = await snaptrude.presentation.aiInspiration.getJob({ jobId })
+   * console.log(job.status, job.progress?.message)
+   * ```
+   */
+  public abstract getJob(
+    args: PluginAIInspirationJobArgs,
+  ): PluginApiReturn<PluginAIInspirationGetJobResult>
+
+  /**
+   * Cancel a transient AI Inspiration job.
+   *
+   * @param args - Object containing `jobId`.
+   * @returns The job after the cancel request.
+   *
+   * @examplePrompt Cancel the running generation
+   * @examplePrompt Stop that AI job
+   *
+   * # Example
+   * ```ts
+   * const { job } = await snaptrude.presentation.aiInspiration.cancelJob({ jobId })
+   * console.log(job.status) // "cancelled" (or a terminal state it already reached)
+   * ```
+   */
+  public abstract cancelJob(
+    args: PluginAIInspirationJobArgs,
+  ): PluginApiReturn<PluginAIInspirationCancelJobResult>
+
+  /**
+   * List transient AI Inspiration jobs created in the current host session.
+   *
+   * @returns Jobs with their statuses, newest first.
+   *
+   * @examplePrompt What AI jobs are running?
+   * @examplePrompt Show my generation queue
+   *
+   * # Example
+   * ```ts
+   * const { jobs } = await snaptrude.presentation.aiInspiration.listJobs()
+   * const running = jobs.filter((j) => j.status === "running" || j.status === "queued")
+   * console.log(running.map((j) => `${j.jobId}: ${j.method}`))
+   * ```
+   */
+  public abstract listJobs(): PluginApiReturn<PluginAIInspirationListJobsResult>
+
+  /**
+   * Get the sanitized workflow graph containing a Present shape.
+   *
+   * @param args - Object containing `shapeId`.
+   * @returns The workflow and matching node, or `null` values when the shape is not in a workflow.
+   *
+   * @examplePrompt Show the generation history of this image
+   * @examplePrompt What workflow produced this shape?
+   *
+   * # Example
+   * ```ts
+   * const { workflow, node } = await snaptrude.presentation.aiInspiration.getWorkflowForShape({
+   *   shapeId: selected.shapeId,
+   * })
+   * if (workflow && node) console.log(node.id, workflow.edgeIds.length, "edges")
+   * ```
+   */
+  public abstract getWorkflowForShape(
+    args: PluginAIInspirationGetWorkflowForShapeArgs,
+  ): PluginApiReturn<PluginAIInspirationGetWorkflowForShapeResult>
+
+  /**
+   * Build a rerun plan for the selected workflow branch ending at a shape.
+   *
+   * @param args - Object containing `shapeId`.
+   * @returns Ready plan data or an unavailable reason.
+   *
+   * @examplePrompt Can I rerun the steps that produced this output?
+   * @examplePrompt Preview the rerun for this generated image
+   *
+   * # Example
+   * ```ts
+   * const plan = await snaptrude.presentation.aiInspiration.getSelectedBranchRerunPlan({
+   *   shapeId: selected.shapeId,
+   * })
+   * if (plan.status === "ready") console.log(plan.edges.map((e) => e.operation.label))
+   * else console.log("Cannot rerun:", plan.reason)
+   * ```
+   */
+  public abstract getSelectedBranchRerunPlan(
+    args: PluginAIInspirationGetWorkflowForShapeArgs,
+  ): PluginApiReturn<PluginAIInspirationRerunPlanResult>
+
+  /**
+   * Rerun the selected workflow branch and supersede the previous branch.
+   *
+   * @param args - Selected shape, optional end frame shape, and run mode.
+   * @returns New canvas outputs in blocking mode, or a `jobId` when called with
+   * `runMode: "job"`.
+   *
+   * @examplePrompt Rerun this generation branch
+   * @examplePrompt Regenerate this output with the same steps
+   *
+   * # Example
+   * ```ts
+   * const { outputs } = await snaptrude.presentation.aiInspiration.rerunSelectedBranch({
+   *   shapeId: selected.shapeId,
+   * })
+   * console.log(outputs?.map((o) => o.shapeId))
+   * ```
+   */
+  public abstract rerunSelectedBranch(
+    args: PluginAIInspirationRerunSelectedBranchArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+
+  /**
+   * Extract a reusable recipe draft from the workflow path ending at a shape.
+   *
+   * @param args - Object containing `shapeId`.
+   * @returns A recipe draft or an unavailable reason.
+   *
+   * @examplePrompt Turn this workflow into a reusable recipe
+   * @examplePrompt Save the generation steps behind this image
+   *
+   * # Example
+   * ```ts
+   * const extraction = await snaptrude.presentation.aiInspiration.extractRecipeFromShape({
+   *   shapeId: selected.shapeId,
+   * })
+   * if (extraction.status === "ready") console.log(extraction.draft.summary)
+   * ```
+   */
+  public abstract extractRecipeFromShape(
+    args: PluginAIInspirationExtractRecipeFromShapeArgs,
+  ): PluginApiReturn<PluginAIInspirationExtractionResult>
+
+  /**
+   * List project-level AI Inspiration recipes stored in Present document metadata.
+   *
+   * @returns Saved project recipes.
+   *
+   * @examplePrompt What AI recipes are saved in this project?
+   * @examplePrompt List my generation recipes
+   *
+   * # Example
+   * ```ts
+   * const { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()
+   * console.log(recipes.map((r) => `${r.name} → ${r.outputKind}`))
+   * ```
+   */
+  public abstract listRecipes(): PluginApiReturn<PluginAIInspirationListRecipesResult>
+
+  /**
+   * Save a project-level AI Inspiration recipe.
+   *
+   * @param args - Recipe draft and desired name.
+   * @returns Saved, duplicate, invalid-name, or failed status.
+   *
+   * @examplePrompt Save this recipe as "Dusk facade render"
+   * @examplePrompt Store these generation steps for reuse
+   *
+   * # Example
+   * ```ts
+   * const extraction = await snaptrude.presentation.aiInspiration.extractRecipeFromShape({
+   *   shapeId: selected.shapeId,
+   * })
+   * if (extraction.status === "ready") {
+   *   const saved = await snaptrude.presentation.aiInspiration.saveRecipe({
+   *     draft: extraction.draft,
+   *     name: "Dusk facade render",
+   *   })
+   *   console.log(saved.status, saved.recipe?.id)
+   * }
+   * ```
+   */
+  public abstract saveRecipe(
+    args: PluginAIInspirationSaveRecipeArgs,
+  ): PluginApiReturn<PluginAIInspirationSaveRecipeResult>
+
+  /**
+   * Delete a project-level AI Inspiration recipe.
+   *
+   * @param args - Object containing `recipeId`.
+   * @returns Whether a recipe was deleted.
+   *
+   * @examplePrompt Delete the facade render recipe
+   * @examplePrompt Remove that saved AI recipe
+   *
+   * # Example
+   * ```ts
+   * const { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()
+   * const stale = recipes.find((r) => r.name === "Old style test")
+   * if (stale) {
+   *   const { deleted } = await snaptrude.presentation.aiInspiration.deleteRecipe({ recipeId: stale.id })
+   *   console.log(deleted)
+   * }
+   * ```
+   */
+  public abstract deleteRecipe(
+    args: PluginAIInspirationDeleteRecipeArgs,
+  ): PluginApiReturn<PluginAIInspirationDeleteRecipeResult>
+
+  /**
+   * Run a saved or inline recipe against Present canvas slot shapes.
+   *
+   * @param args - Saved `recipeId` or inline `recipe`, slot shape IDs, and run mode.
+   * @returns Canvas outputs in blocking mode, or a `jobId` when called with
+   * `runMode: "job"`.
+   *
+   * @examplePrompt Apply my saved recipe to this image
+   * @examplePrompt Run the dusk-render recipe on the selected view
+   *
+   * # Example
+   * ```ts
+   * const { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()
+   * const recipe = recipes[0]
+   * const { sources } = await snaptrude.presentation.aiInspiration.listSources({})
+   * const { outputs } = await snaptrude.presentation.aiInspiration.runRecipe({
+   *   recipeId: recipe.id,
+   *   slotShapeIds: { [recipe.slots[0].id]: sources[0].shapeId },
+   * })
+   * console.log(outputs?.map((o) => o.outputUrl))
+   * ```
+   */
+  public abstract runRecipe(
+    args: PluginAIInspirationRunRecipeArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+}