@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/src/api/presentation/aiInspiration.ts

@@ -0,0 +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>
+}