@civitai/app-sdk 0.30.0 → 0.32.0

package/dist/blocks/types.js

@@ -4,5 +4,58 @@
  * Framework-agnostic. Hooks and transport classes that consume these types
  * live in a separate package so this module stays usable from any runtime.
  */
-export {};
+/**
+ * Narrow a {@link BlockContext} to {@link ModelSlotContext}.
+ *
+ * A real runtime check, not just a cast: the context arrived over
+ * `postMessage`, so its static type is the host's claim about it. Returning
+ * `true` here is what lets the block render a useful "wrong slot" state instead
+ * of `undefined`-ing its way through a generation body.
+ *
+ * 🔴 IT CHECKS EVERY FIELD IT ASSERTS, not just `slotId`. A `slotId`-only check
+ * is not enough, because {@link UnknownSlotContext} declares `slotId: string` —
+ * so a structurally-incomplete known slot (`{ slotId: 'model.sidebar_top' }` and
+ * nothing else) is a legal `BlockContext` that COMPILES, passes a `slotId`-only
+ * guard, and then hands the block `ctx.modelId` typed `number` and valued
+ * `undefined`. The five required fields are asserted individually so the
+ * predicate is true exactly when the type it claims is true.
+ *
+ * No legitimate host payload is rejected by the extra checks. The only
+ * production producer of a model slot (civitai/civitai
+ * `ModelVersionDetails.tsx`) sets all five unconditionally, and the host's own
+ * pinned allowlist test (`__tests__/projectBlockInit.test.ts`) asserts the
+ * projected context carries them as an EXACT key set. A payload that somehow
+ * lacked one is precisely the case the block must not treat as a model context.
+ */
+export function isModelSlotContext(ctx) {
+    if (ctx.slotId !== 'model.sidebar_top' &&
+        ctx.slotId !== 'model.below_images' &&
+        ctx.slotId !== 'model.actions_extra') {
+        return false;
+    }
+    const c = ctx;
+    return (typeof c.modelId === 'number' &&
+        typeof c.modelVersionId === 'number' &&
+        typeof c.modelName === 'string' &&
+        typeof c.modelType === 'string' &&
+        typeof c.modelNsfwLevel === 'number');
+}
+/**
+ * Narrow a {@link BlockContext} to {@link PageSlotContext}. Same shape and same
+ * reasoning as {@link isModelSlotContext}: the three fields `PageSlotContext`
+ * declares REQUIRED are checked, not just `slotId`.
+ *
+ * `subPath` is checked as a string, not a NON-EMPTY one — `''` is the real value
+ * on an app's own index (`PageBlockHost.buildContext()`), and rejecting it would
+ * make every app's landing route fail to narrow. `viewerUserId` is `number |
+ * null`, and `null` is the genuine anonymous value.
+ */
+export function isPageSlotContext(ctx) {
+    if (ctx.slotId !== 'app.page')
+        return false;
+    const c = ctx;
+    return (typeof c.slug === 'string' &&
+        typeof c.subPath === 'string' &&
+        (typeof c.viewerUserId === 'number' || c.viewerUserId === null));
+}
 //# sourceMappingURL=types.js.map

package/dist/blocks/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/blocks/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/blocks/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2ZH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAiB;IAClD,IACE,GAAG,CAAC,MAAM,KAAK,mBAAmB;QAClC,GAAG,CAAC,MAAM,KAAK,oBAAoB;QACnC,GAAG,CAAC,MAAM,KAAK,qBAAqB,EACpC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,CAAC,GAAG,GAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ;QACpC,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,CACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,CAAC,GAAG,GAA+B,CAAC;IAC1C,OAAO,CACL,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAC7B,CAAC,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,CAChE,CAAC;AACJ,CAAC"}

package/dist/orchestrator/index.d.ts

@@ -27,8 +27,30 @@ export type TerminalStatus = (typeof TERMINAL_STATUSES)[number];
  * at the matching `build*Body` helper (if one exists) or fall back to
  * {@link callOrchestrator} with a hand-crafted body.
  *
- * Source of truth is `https://orchestration.civitai.com/openapi/v2-consumers.json`.
- * If a step type is missing here, the catalog is stale — open a PR.
+ * 🔴 SOURCE OF TRUTH — AND HOW IT IS HELD. The authoritative population is the
+ * `WorkflowStepTemplate` **discriminator mapping** in
+ * `https://orchestration.civitai.com/openapi/v2-consumers.json` (the submit-side
+ * union; `WorkflowStep`'s mapping is identical). That is the *defining* surface —
+ * enumerate it, do not sample the spec's type names or a generated client's
+ * exports, which include shapes that are not submittable step types.
+ *
+ * The keys below are pinned EXACTLY against that mapping two ways:
+ *  - `test/orchestrator.test.ts` compares this catalog's key set to a list
+ *    transcribed from the spec (hermetic, offline, order-insensitive), and
+ *  - `scripts/check-orchestrator-catalogs.mjs` re-fetches the LIVE spec and
+ *    diffs it (network; wired into CI as `pnpm check:catalogs`).
+ *
+ * The second one is what notices the orchestrator shipping a new step. When it
+ * fails, refresh both this catalog and the test's transcribed list in the same
+ * PR — the test is a deliberate second copy so a catalog edit cannot mark its
+ * own homework.
+ *
+ * 🔴 A SPOT-CHECK IS NOT A PIN. Until 2026-08 this catalog was guarded only by
+ * `expect(keys).toContain('textToImage')`-style assertions over 7 names. It
+ * carried a phantom `audioMix` — a `$type` that appears **0 times** in the spec
+ * and would have come back a 400 — and was missing 10 real step types, for as
+ * long as those assertions existed. An exact-set comparison is the whole
+ * difference.
  */
 export declare const WORKFLOW_STEP_TYPES: {
     /** Diffusion image gen (SDXL / Flux.1 / Pony / Illustrious / SD1.5 / etc.). Use {@link buildTextToImageBody}. */
@@ -41,8 +63,18 @@ export declare const WORKFLOW_STEP_TYPES: {
     readonly imageGen: "Closed-source image gen (Nano Banana, Gemini, GPT-Image, Flux Kontext, Seedream, Grok, fal, …)";
     /** Arbitrary ComfyUI workflow graphs. Pass a `prompt` object (node graph). */
     readonly comfy: "Custom ComfyUI node-graph workflows";
+    /**
+     * Raw ComfyUI graph + an explicit AIR download manifest (`resources`). The
+     * orchestrator forwards the graph opaquely, so anything the graph references
+     * must also be declared in `resources` or it fails at load time inside ComfyUI.
+     */
+    readonly customComfy: "Raw ComfyUI graph with a declared AIR resource manifest";
     /** Upscale an existing image. Input is a source image URL + scale factor. */
     readonly imageUpscaler: "Image upscaling";
+    /** Remove an image background via BiRefNet (runs as a comfy job under the hood). */
+    readonly imageBackgroundRemoval: "Image background removal (BiRefNet)";
+    /** Vectorize a raster image with a local StarVector / OmniSVG model. */
+    readonly imageToSvg: "Raster image → SVG vectorization";
     /** LoRA / DoRA / embedding training. Long-running. */
     readonly imageResourceTraining: "Train a LoRA / DoRA / embedding from a dataset";
     /** Pre-process an image (resize, ControlNet preprocessor, etc.). */
@@ -61,6 +93,8 @@ export declare const WORKFLOW_STEP_TYPES: {
     readonly videoEnhancement: "Per-frame video enhancement";
     /** Extract individual frames from a video. */
     readonly videoFrameExtraction: "Extract frames from a video";
+    /** Track a prompted foreground object and return a transparent animated WebP. */
+    readonly videoBackgroundRemoval: "Video background removal (prompted object tracking)";
     /** Read video metadata (duration, codec, dimensions). */
     readonly videoMetadata: "Read video file metadata";
     /** Transcode video format / codec. */
@@ -71,10 +105,27 @@ export declare const WORKFLOW_STEP_TYPES: {
     readonly aceStepAudio: "Music generation (ACE Step 1.5)";
     /** Speech-to-text transcription. */
     readonly transcription: "Speech-to-text transcription";
-    /** Mix multiple audio tracks. */
-    readonly audioMix: "Audio track mixing";
     /** Generate captions from audio. */
     readonly audioCaptioning: "Caption generation from audio";
+    /**
+     * Compose an ordered list of media `elements` into one output. Its output is
+     * discriminated on `type`: `'audio'` for a mixdown, `'video'` for a
+     * composition — so this covers audio mixing as well as video assembly.
+     *
+     * 🔴 This replaced a catalog entry named `audioMix`, which never existed in
+     * the orchestrator spec. If you were reaching for `audioMix`, this is it.
+     */
+    readonly composeMedia: "Compose media elements into one audio mixdown or video";
+    /** Generate a 3D model. Engines: `comfy`, `fal`. */
+    readonly polyGen: "3D model generation";
+    /** Render a preview of an existing 3D model. */
+    readonly model3DPreview: "3D model preview rendering";
+    /**
+     * Generic training step. Engines: `ai-toolkit`, `comfy`. Distinct from
+     * {@link WORKFLOW_STEP_TYPES.imageResourceTraining}, which is the older
+     * kohya/musubi/flux-dev-fast LoRA path.
+     */
+    readonly training: "Model training (ai-toolkit / comfy engines)";
     /** Hash an image / video / model for dedup or lookup. */
     readonly mediaHash: "Media content hashing";
     /** Hash a model file. */
@@ -89,6 +140,8 @@ export declare const WORKFLOW_STEP_TYPES: {
     readonly ageClassification: "Age range classification";
     /** xGuard NSFW / safety moderation. */
     readonly xGuardModeration: "NSFW / safety moderation";
+    /** Shieldstral text/prompt safety moderation (`mode: 'prompt' | 'text'`). */
+    readonly shieldstralModeration: "Text / prompt safety moderation (Shieldstral)";
     /** ClamAV scan a model file for malware. */
     readonly modelClamScan: "Antivirus scan a model file";
     /** Pickle-scan a model file for unsafe pickles. */
@@ -103,6 +156,10 @@ export declare const WORKFLOW_STEP_TYPES: {
     readonly echo: "Echo step — round-trip the input for testing";
     /** Package multiple blobs into a zip archive. */
     readonly blobArchive: "Zip multiple blobs into an archive";
+    /** Snapshot the installed ComfyUI custom-node packs on a worker. */
+    readonly comfyNodepackSnapshot: "Snapshot a worker’s installed ComfyUI node packs (internal)";
+    /** Qwen image benchmarking harness. */
+    readonly qwenImageBench: "Qwen image benchmarking (internal)";
 };
 export type WorkflowStepType = keyof typeof WORKFLOW_STEP_TYPES;
 /**
@@ -352,28 +409,116 @@ export declare function estimateWorkflow(client: OrchestratorClient, body: unkno
  * const urls = extractImageUrls(finished);
  */
 export declare function submitWorkflow(client: OrchestratorClient, body: unknown): Promise<WorkflowSnapshot>;
+/** Per-call controls for {@link getWorkflow}. */
+export interface GetWorkflowOptions {
+    /**
+     * 🔴 THE ORCHESTRATOR'S OWN LONG-POLL HOLD, IN **SECONDS**, NOT MILLISECONDS.
+     *
+     * Sent as the `?wait=` query parameter, which the orchestrator documents as
+     * *"Whether to wait for the workflow to complete before returning or to
+     * return immediately. The request may return a 202 if the client waits for
+     * the workflow to complete and the workflow does not complete within the
+     * requested timeout."*
+     *
+     * The unit is seconds. That is not obvious from the parameter's name and
+     * getting it wrong is silent in both directions — `wait: 30000` asks for
+     * ~8 hours and `wait: 0.03` rounds to nothing — so it is spelled out here and
+     * in the option's name. Omit (or `0`) for the pre-existing one-shot read.
+     *
+     * A 202 is a NORMAL outcome, not an error: `callOrchestrator` treats every
+     * 2xx as success, so a timed-out hold returns the current (non-terminal)
+     * snapshot exactly like a 200 would. Callers re-arm; see {@link pollWorkflow}.
+     */
+    waitSeconds?: number;
+    /**
+     * Abort signal forwarded to `fetch`, so a long hold is genuinely CANCELLED
+     * rather than merely abandoned. A `Promise.race` against a timer leaves the
+     * underlying request in flight holding a socket, which is precisely the
+     * failure mode a long poll makes expensive.
+     */
+    signal?: AbortSignal;
+}
 /**
- * Fetch a single workflow's current snapshot by id. One-shot; for "wait until
- * done" use {@link pollWorkflow}.
+ * Fetch a single workflow's current snapshot by id.
+ *
+ * One-shot by default. Pass {@link GetWorkflowOptions.waitSeconds} to have the
+ * ORCHESTRATOR hold the request open until the workflow reaches a terminal
+ * status (a real long poll, server-side) instead of returning immediately; for
+ * a full "wait until done, re-arming across timeouts" loop use
+ * {@link pollWorkflow}.
  *
  * @example
  * const snap = await getWorkflow(client, workflowId);
  * if (isTerminal(snap)) console.log(extractImageUrls(snap));
+ *
+ * @example  Long poll: one request that returns as soon as the workflow ends
+ * const snap = await getWorkflow(client, workflowId, { waitSeconds: 20 });
+ * // A non-terminal snapshot here means the hold elapsed (HTTP 202) — ask again.
+ * if (!isTerminal(snap)) await getWorkflow(client, workflowId, { waitSeconds: 20 });
  */
-export declare function getWorkflow(client: OrchestratorClient, workflowId: string): Promise<WorkflowSnapshot>;
+export declare function getWorkflow(client: OrchestratorClient, workflowId: string, opts?: GetWorkflowOptions): Promise<WorkflowSnapshot>;
+/**
+ * Default orchestrator-side hold per {@link pollWorkflow} attempt, in seconds.
+ *
+ * 20s rather than something larger because a held request occupies a socket on
+ * BOTH sides for its whole duration, and because the platforms these starters
+ * deploy to cap total request time (see PORTING.md's serverless note). It turns
+ * the default 30s budget from ~30 requests into ~2 while DETECTING completion
+ * sooner, not later — the hold returns the instant the workflow ends.
+ */
+export declare const DEFAULT_POLL_WAIT_SECONDS = 20;
 export interface PollWorkflowOptions {
-    /** Polling interval in ms. Default 1000. */
+    /**
+     * Delay BETWEEN attempts, in ms. Default 1000.
+     *
+     * 🔴 KEPT, AND LOAD-BEARING, EVEN THOUGH LONG POLLING MAKES IT LOOK
+     * REDUNDANT. With `waitSeconds > 0` an attempt normally consumes the whole
+     * hold, so this is ~3% overhead on a cycle. But if the orchestrator ever
+     * stops honouring `wait` — an older deployment, a proxy that strips the query
+     * string, a 202 returned instantly — a zero gap turns this loop into a hot
+     * loop hammering the API at fetch speed. This delay is the floor that makes
+     * that failure slow instead of catastrophic.
+     */
     intervalMs?: number;
     /** Max total time to poll in ms. Default 30000. */
     timeoutMs?: number;
-    /** Optional abort signal — checked between ticks. */
+    /** Optional abort signal — cancels the in-flight request and stops the loop. */
     signal?: AbortSignal;
+    /**
+     * Orchestrator-side hold per attempt, in **seconds**. Default
+     * {@link DEFAULT_POLL_WAIT_SECONDS}. Pass `0` to restore the pre-0.31
+     * pure-timer behaviour (one immediate read per `intervalMs`).
+     *
+     * Automatically clamped down to the time left on `timeoutMs`, so a long hold
+     * cannot overrun the caller's budget.
+     */
+    waitSeconds?: number;
 }
 /**
- * Server-side long-poll helper. Re-fetches the workflow every `intervalMs`
- * until it reaches a terminal status, the timeout elapses, or the signal
- * aborts. Returns the latest snapshot regardless of which condition tripped —
- * callers inspect {@link isTerminal} on the result to decide what to do.
+ * Wait for a workflow to reach a terminal status, using the orchestrator's
+ * SERVER-SIDE long poll (`?wait=`) and re-arming across each 202 until the
+ * workflow ends, the `timeoutMs` budget elapses, or `signal` aborts. Returns
+ * the latest snapshot regardless of which condition tripped — callers inspect
+ * {@link isTerminal} on the result to decide what to do.
+ *
+ * 🔴 THIS FUNCTION USED TO BE LABELLED A LONG POLL AND WAS NOT ONE. Until
+ * @civitai/app-sdk 0.31.0 it was a client-side `setTimeout` loop re-reading the
+ * workflow every `intervalMs` (default 1000) with no `wait` parameter — i.e. a
+ * TIMER poll wearing a long poll's docstring, and the same false claim had
+ * propagated into this package's README (its API table and the "`pollWorkflow`
+ * long-polls to terminal status" line). The label is now true rather than
+ * softened, because the orchestrator has supported the parameter all along and
+ * four non-blocks civitai call sites were already using it.
+ *
+ * (PORTING.md's "long-poll" wording is NOT part of that: it describes the
+ * BLOCK-IN-THE-HANDLER pattern, which the starters genuinely did regardless of
+ * the mechanism underneath, and its advice to cap `timeoutMs` under the
+ * platform budget is still correct — more so now that the hold is real.)
+ *
+ * WHAT A CALLER SEES THAT IS DIFFERENT: fewer requests (~2 instead of ~30 on
+ * the default budget) and terminal status detected sooner (the hold returns
+ * when the workflow ends, not on the next tick after it ended). The RETURN
+ * CONTRACT is unchanged.
  *
  * @example
  * const finished = await pollWorkflow(client, submitted.id, { timeoutMs: 30_000 });

package/dist/orchestrator/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestrator/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestrator/index.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/index.js

@@ -28,8 +28,30 @@ export const TERMINAL_STATUSES = ['succeeded', 'failed', 'expired', 'canceled'];
  * at the matching `build*Body` helper (if one exists) or fall back to
  * {@link callOrchestrator} with a hand-crafted body.
  *
- * Source of truth is `https://orchestration.civitai.com/openapi/v2-consumers.json`.
- * If a step type is missing here, the catalog is stale — open a PR.
+ * 🔴 SOURCE OF TRUTH — AND HOW IT IS HELD. The authoritative population is the
+ * `WorkflowStepTemplate` **discriminator mapping** in
+ * `https://orchestration.civitai.com/openapi/v2-consumers.json` (the submit-side
+ * union; `WorkflowStep`'s mapping is identical). That is the *defining* surface —
+ * enumerate it, do not sample the spec's type names or a generated client's
+ * exports, which include shapes that are not submittable step types.
+ *
+ * The keys below are pinned EXACTLY against that mapping two ways:
+ *  - `test/orchestrator.test.ts` compares this catalog's key set to a list
+ *    transcribed from the spec (hermetic, offline, order-insensitive), and
+ *  - `scripts/check-orchestrator-catalogs.mjs` re-fetches the LIVE spec and
+ *    diffs it (network; wired into CI as `pnpm check:catalogs`).
+ *
+ * The second one is what notices the orchestrator shipping a new step. When it
+ * fails, refresh both this catalog and the test's transcribed list in the same
+ * PR — the test is a deliberate second copy so a catalog edit cannot mark its
+ * own homework.
+ *
+ * 🔴 A SPOT-CHECK IS NOT A PIN. Until 2026-08 this catalog was guarded only by
+ * `expect(keys).toContain('textToImage')`-style assertions over 7 names. It
+ * carried a phantom `audioMix` — a `$type` that appears **0 times** in the spec
+ * and would have come back a 400 — and was missing 10 real step types, for as
+ * long as those assertions existed. An exact-set comparison is the whole
+ * difference.
  */
 export const WORKFLOW_STEP_TYPES = {
     // ----- Image gen ---------------------------------------------------------
@@ -43,8 +65,18 @@ export const WORKFLOW_STEP_TYPES = {
     imageGen: 'Closed-source image gen (Nano Banana, Gemini, GPT-Image, Flux Kontext, Seedream, Grok, fal, …)',
     /** Arbitrary ComfyUI workflow graphs. Pass a `prompt` object (node graph). */
     comfy: 'Custom ComfyUI node-graph workflows',
+    /**
+     * Raw ComfyUI graph + an explicit AIR download manifest (`resources`). The
+     * orchestrator forwards the graph opaquely, so anything the graph references
+     * must also be declared in `resources` or it fails at load time inside ComfyUI.
+     */
+    customComfy: 'Raw ComfyUI graph with a declared AIR resource manifest',
     /** Upscale an existing image. Input is a source image URL + scale factor. */
     imageUpscaler: 'Image upscaling',
+    /** Remove an image background via BiRefNet (runs as a comfy job under the hood). */
+    imageBackgroundRemoval: 'Image background removal (BiRefNet)',
+    /** Vectorize a raster image with a local StarVector / OmniSVG model. */
+    imageToSvg: 'Raster image → SVG vectorization',
     /** LoRA / DoRA / embedding training. Long-running. */
     imageResourceTraining: 'Train a LoRA / DoRA / embedding from a dataset',
     /** Pre-process an image (resize, ControlNet preprocessor, etc.). */
@@ -64,6 +96,8 @@ export const WORKFLOW_STEP_TYPES = {
     videoEnhancement: 'Per-frame video enhancement',
     /** Extract individual frames from a video. */
     videoFrameExtraction: 'Extract frames from a video',
+    /** Track a prompted foreground object and return a transparent animated WebP. */
+    videoBackgroundRemoval: 'Video background removal (prompted object tracking)',
     /** Read video metadata (duration, codec, dimensions). */
     videoMetadata: 'Read video file metadata',
     /** Transcode video format / codec. */
@@ -75,10 +109,30 @@ export const WORKFLOW_STEP_TYPES = {
     aceStepAudio: 'Music generation (ACE Step 1.5)',
     /** Speech-to-text transcription. */
     transcription: 'Speech-to-text transcription',
-    /** Mix multiple audio tracks. */
-    audioMix: 'Audio track mixing',
     /** Generate captions from audio. */
     audioCaptioning: 'Caption generation from audio',
+    // ----- Media composition -------------------------------------------------
+    /**
+     * Compose an ordered list of media `elements` into one output. Its output is
+     * discriminated on `type`: `'audio'` for a mixdown, `'video'` for a
+     * composition — so this covers audio mixing as well as video assembly.
+     *
+     * 🔴 This replaced a catalog entry named `audioMix`, which never existed in
+     * the orchestrator spec. If you were reaching for `audioMix`, this is it.
+     */
+    composeMedia: 'Compose media elements into one audio mixdown or video',
+    // ----- 3D ----------------------------------------------------------------
+    /** Generate a 3D model. Engines: `comfy`, `fal`. */
+    polyGen: '3D model generation',
+    /** Render a preview of an existing 3D model. */
+    model3DPreview: '3D model preview rendering',
+    // ----- Training ----------------------------------------------------------
+    /**
+     * Generic training step. Engines: `ai-toolkit`, `comfy`. Distinct from
+     * {@link WORKFLOW_STEP_TYPES.imageResourceTraining}, which is the older
+     * kohya/musubi/flux-dev-fast LoRA path.
+     */
+    training: 'Model training (ai-toolkit / comfy engines)',
     // ----- Classification / tagging / moderation ----------------------------
     /** Hash an image / video / model for dedup or lookup. */
     mediaHash: 'Media content hashing',
@@ -94,6 +148,8 @@ export const WORKFLOW_STEP_TYPES = {
     ageClassification: 'Age range classification',
     /** xGuard NSFW / safety moderation. */
     xGuardModeration: 'NSFW / safety moderation',
+    /** Shieldstral text/prompt safety moderation (`mode: 'prompt' | 'text'`). */
+    shieldstralModeration: 'Text / prompt safety moderation (Shieldstral)',
     /** ClamAV scan a model file for malware. */
     modelClamScan: 'Antivirus scan a model file',
     /** Pickle-scan a model file for unsafe pickles. */
@@ -110,6 +166,14 @@ export const WORKFLOW_STEP_TYPES = {
     echo: 'Echo step — round-trip the input for testing',
     /** Package multiple blobs into a zip archive. */
     blobArchive: 'Zip multiple blobs into an archive',
+    // ----- Platform internals ------------------------------------------------
+    // Present in the consumer spec, so listed here for completeness — but these
+    // exist to serve Civitai's own pipelines. A third-party app has no reason to
+    // submit one, and the surrounding features may be gated or disabled.
+    /** Snapshot the installed ComfyUI custom-node packs on a worker. */
+    comfyNodepackSnapshot: 'Snapshot a worker’s installed ComfyUI node packs (internal)',
+    /** Qwen image benchmarking harness. */
+    qwenImageBench: 'Qwen image benchmarking (internal)',
 };
 /**
  * Engines that the `imageGen` step accepts. Each one has its own input shape;
@@ -345,21 +409,82 @@ export function submitWorkflow(client, body) {
     });
 }
 /**
- * Fetch a single workflow's current snapshot by id. One-shot; for "wait until
- * done" use {@link pollWorkflow}.
+ * Fetch a single workflow's current snapshot by id.
+ *
+ * One-shot by default. Pass {@link GetWorkflowOptions.waitSeconds} to have the
+ * ORCHESTRATOR hold the request open until the workflow reaches a terminal
+ * status (a real long poll, server-side) instead of returning immediately; for
+ * a full "wait until done, re-arming across timeouts" loop use
+ * {@link pollWorkflow}.
  *
  * @example
  * const snap = await getWorkflow(client, workflowId);
  * if (isTerminal(snap)) console.log(extractImageUrls(snap));
+ *
+ * @example  Long poll: one request that returns as soon as the workflow ends
+ * const snap = await getWorkflow(client, workflowId, { waitSeconds: 20 });
+ * // A non-terminal snapshot here means the hold elapsed (HTTP 202) — ask again.
+ * if (!isTerminal(snap)) await getWorkflow(client, workflowId, { waitSeconds: 20 });
  */
-export function getWorkflow(client, workflowId) {
-    return callOrchestrator(client, `/v2/consumer/workflows/${encodeURIComponent(workflowId)}`, { method: 'GET' });
+export function getWorkflow(client, workflowId, opts = {}) {
+    // Built with URLSearchParams rather than string concatenation so a future
+    // second parameter cannot reintroduce a `?`-vs-`&` bug, and so a non-finite
+    // `waitSeconds` can never be serialised into the URL.
+    const wait = typeof opts.waitSeconds === 'number' && Number.isFinite(opts.waitSeconds)
+        ? Math.max(0, Math.floor(opts.waitSeconds))
+        : 0;
+    const qs = wait > 0 ? `?${new URLSearchParams({ wait: String(wait) }).toString()}` : '';
+    return callOrchestrator(client, `/v2/consumer/workflows/${encodeURIComponent(workflowId)}${qs}`, {
+        method: 'GET',
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
 }
+// ---------- Polling ---------------------------------------------------------
+/**
+ * Default orchestrator-side hold per {@link pollWorkflow} attempt, in seconds.
+ *
+ * 20s rather than something larger because a held request occupies a socket on
+ * BOTH sides for its whole duration, and because the platforms these starters
+ * deploy to cap total request time (see PORTING.md's serverless note). It turns
+ * the default 30s budget from ~30 requests into ~2 while DETECTING completion
+ * sooner, not later — the hold returns the instant the workflow ends.
+ */
+export const DEFAULT_POLL_WAIT_SECONDS = 20;
 /**
- * Server-side long-poll helper. Re-fetches the workflow every `intervalMs`
- * until it reaches a terminal status, the timeout elapses, or the signal
- * aborts. Returns the latest snapshot regardless of which condition tripped —
- * callers inspect {@link isTerminal} on the result to decide what to do.
+ * Slack added to a per-attempt abort deadline, in ms.
+ *
+ * 🔴 THE ABORT MUST SIT ABOVE THE HOLD, NOT AT IT. `waitSeconds` is what we ASK
+ * the orchestrator to hold for; the abort is this side's defence against a
+ * socket it accepted and abandoned, which `wait` cannot cover because a request
+ * that never returns never times out. Set equal to the hold, the abort would
+ * race the orchestrator's own timely 202 and cancel healthy requests.
+ */
+const POLL_ABORT_SLACK_MS = 5_000;
+/**
+ * Wait for a workflow to reach a terminal status, using the orchestrator's
+ * SERVER-SIDE long poll (`?wait=`) and re-arming across each 202 until the
+ * workflow ends, the `timeoutMs` budget elapses, or `signal` aborts. Returns
+ * the latest snapshot regardless of which condition tripped — callers inspect
+ * {@link isTerminal} on the result to decide what to do.
+ *
+ * 🔴 THIS FUNCTION USED TO BE LABELLED A LONG POLL AND WAS NOT ONE. Until
+ * @civitai/app-sdk 0.31.0 it was a client-side `setTimeout` loop re-reading the
+ * workflow every `intervalMs` (default 1000) with no `wait` parameter — i.e. a
+ * TIMER poll wearing a long poll's docstring, and the same false claim had
+ * propagated into this package's README (its API table and the "`pollWorkflow`
+ * long-polls to terminal status" line). The label is now true rather than
+ * softened, because the orchestrator has supported the parameter all along and
+ * four non-blocks civitai call sites were already using it.
+ *
+ * (PORTING.md's "long-poll" wording is NOT part of that: it describes the
+ * BLOCK-IN-THE-HANDLER pattern, which the starters genuinely did regardless of
+ * the mechanism underneath, and its advice to cap `timeoutMs` under the
+ * platform budget is still correct — more so now that the hold is real.)
+ *
+ * WHAT A CALLER SEES THAT IS DIFFERENT: fewer requests (~2 instead of ~30 on
+ * the default budget) and terminal status detected sooner (the hold returns
+ * when the workflow ends, not on the next tick after it ended). The RETURN
+ * CONTRACT is unchanged.
  *
  * @example
  * const finished = await pollWorkflow(client, submitted.id, { timeoutMs: 30_000 });
@@ -368,16 +493,79 @@ export function getWorkflow(client, workflowId) {
 export async function pollWorkflow(client, workflowId, opts = {}) {
     const interval = opts.intervalMs ?? 1000;
     const timeout = opts.timeoutMs ?? 30_000;
+    const requestedWait = opts.waitSeconds ?? DEFAULT_POLL_WAIT_SECONDS;
     const deadline = Date.now() + timeout;
-    let snapshot = await getWorkflow(client, workflowId);
+    // The hold this attempt may ask for: the caller's `waitSeconds`, floored at 0
+    // and clamped to whatever is LEFT of the total budget, so a 20s hold started
+    // with 3s remaining asks for 3s rather than overrunning by 17.
+    const holdFor = () => {
+        if (!Number.isFinite(requestedWait) || requestedWait <= 0)
+            return 0;
+        const remainingSeconds = Math.floor((deadline - Date.now()) / 1000);
+        return Math.max(0, Math.min(Math.floor(requestedWait), remainingSeconds));
+    };
+    const attempt = (waitSeconds) => {
+        if (waitSeconds <= 0) {
+            return getWorkflow(client, workflowId, {
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+        }
+        // Per-attempt deadline as a real AbortController — the fetch is CANCELLED,
+        // not just stopped being awaited. Linked to the caller's signal by hand
+        // rather than via `AbortSignal.any`, which is too new to require of every
+        // browser this client-safe package runs in.
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), waitSeconds * 1000 + POLL_ABORT_SLACK_MS);
+        const onOuterAbort = () => ctl.abort();
+        opts.signal?.addEventListener('abort', onOuterAbort);
+        return getWorkflow(client, workflowId, { waitSeconds, signal: ctl.signal }).finally(() => {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onOuterAbort);
+        });
+    };
+    // The FIRST read is not wrapped: a throw here propagates, exactly as it did
+    // before long polling existed. There is no prior snapshot to fall back to, so
+    // swallowing it would return `undefined` typed as a snapshot.
+    let snapshot = await attempt(holdFor());
     while (!isTerminal(snapshot) && Date.now() + interval <= deadline) {
         if (opts.signal?.aborted)
             break;
         await new Promise((r) => setTimeout(r, interval));
-        snapshot = await getWorkflow(client, workflowId);
+        if (opts.signal?.aborted)
+            break;
+        try {
+            snapshot = await attempt(holdFor());
+        }
+        catch (err) {
+            // 🔴 A LATER ATTEMPT'S ABORT MUST NOT DESTROY A SNAPSHOT WE ALREADY HAVE.
+            // Both this function's own per-attempt deadline and the caller's signal
+            // surface as an abort throw. Neither is news about the workflow, and the
+            // documented contract is "returns the latest snapshot" — so we keep the
+            // one we hold and stop. Any OTHER error still propagates, which is what
+            // the pre-long-poll loop did for every error.
+            if (!isAbortError(err))
+                throw err;
+            break;
+        }
     }
     return snapshot;
 }
+/**
+ * Is this thrown value an abort (either our per-attempt deadline or the
+ * caller's signal)?
+ *
+ * Matched on `name`, not `instanceof DOMException`: the abort reason is
+ * produced by whichever fetch implementation is in play (undici, a browser, a
+ * test double), and those do not share a class. Node's undici throws a
+ * `DOMException` named `AbortError`; a polyfilled or mocked fetch may throw a
+ * plain `Error` with the same name.
+ */
+function isAbortError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'name' in err &&
+        err.name === 'AbortError');
+}
 // ---------- Snapshot inspection --------------------------------------------
 /**
  * True when a snapshot has reached a terminal status (`succeeded` | `failed` |