@snaptrude/plugin-core 0.7.0 → 0.7.1

package/src/api/presentation/aiInspiration.ts

@@ -10,6 +10,11 @@ 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",
@@ -24,6 +29,20 @@ 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
@@ -53,6 +72,28 @@ 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(),
@@ -151,6 +192,23 @@ export const PluginAIInspirationModel = z.object({
 })
 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),
@@ -159,6 +217,20 @@ 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(),
@@ -188,6 +260,59 @@ 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(),
@@ -230,13 +355,16 @@ export const PluginAIInspirationGenerateArgs = z.object({
   regionHint: PluginAIInspirationRegionHint.optional(),
   sketchGuidance: PluginAIInspirationSketchGuidance.optional(),
   video: PluginAIInspirationVideoOptions.optional(),
+  runMode: PluginAIInspirationRunMode.optional(),
 })
 export type PluginAIInspirationGenerateArgs = z.infer<
   typeof PluginAIInspirationGenerateArgs
 >
 
 export const PluginAIInspirationRunResult = z.object({
-  outputs: z.array(PluginAIInspirationOutput).min(1),
+  jobId: z.string().optional(),
+  output: PluginAIInspirationOutput.optional(),
+  outputs: z.array(PluginAIInspirationOutput).optional(),
   metadata: PluginAIInspirationRunMetadata.optional(),
 })
 export type PluginAIInspirationRunResult = z.infer<
@@ -248,11 +376,335 @@ export const PluginAIInspirationRefineArgs = z.object({
   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.
  *
@@ -260,6 +712,11 @@ export type PluginAIInspirationRefineArgs = z.infer<
  * 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 {
@@ -283,6 +740,29 @@ export abstract class PluginPresentationAIInspirationApi {
    */
   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.
    *
@@ -303,12 +783,47 @@ export abstract class PluginPresentationAIInspirationApi {
     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, and video options.
-   * @returns The created canvas output(s).
+   * 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
@@ -326,7 +841,7 @@ export abstract class PluginPresentationAIInspirationApi {
    *   referenceShapeIds: refs.slice(0, 2).map((r) => r.shapeId),
    *   referenceStrength: "medium",
    * })
-   * for (const out of outputs) console.log(out.outputType, out.shapeId, out.outputUrl)
+   * for (const out of outputs ?? []) console.log(out.outputType, out.shapeId, out.outputUrl)
    * ```
    */
   public abstract generate(
@@ -336,8 +851,9 @@ export abstract class PluginPresentationAIInspirationApi {
   /**
    * Refine/upscale an AI Inspiration source image.
    *
-   * @param args - Source shape and optional upscale factor.
-   * @returns The refined canvas output(s).
+   * @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
@@ -352,11 +868,249 @@ export abstract class PluginPresentationAIInspirationApi {
    *     sourceShapeId: image.shapeId,
    *     upscaleFactor: 2,
    *   })
-   *   console.log(outputs[0].shapeId)
+   *   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>
 }