@hraness/slopcamera 3.5.0 → 3.7.0

package/skills/slopcamera/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: slopcamera
-description: Create, inspect, edit and render visual media with the Slopcamera CLI and SDK. Use for diagrams, raster-to-SVG conversion, existing screen or camera recordings, video editing and captions, social collage banners, music videos from authored scenes and local tracks, AI images/video/speech/transcription, Three.js scenes and world-space media, Blender rigs and simulation, CadQuery models, parametric architectural designs, Manim educational films, HTML/WGSL motion graphics, and durable agent workflows.
+description: Create, inspect, edit and render visual media with the SlopCamera CLI and SDK. Use for diagrams, raster-to-SVG conversion, existing screen or camera recordings, video editing and captions, social collage banners, music videos from authored scenes and local tracks, AI images/video/speech/transcription, Three.js scenes and world-space media, Blender rigs and simulation, CadQuery models, parametric architectural designs, Manim educational films, HTML/WGSL motion graphics, and durable agent workflows.
 ---
 
-# Create visual media with Slopcamera
+# Create visual media with SlopCamera
 
 Start from the requested result and existing source. Use the installed `slopcamera` CLI, inspect its real capabilities and retain the authored source beside its derived media. Read only the references needed by the task.
 
@@ -32,6 +32,7 @@ Slopcamera installs from its verified release archive or from source. Historical
 | Raster artwork converted to SVG | [Vectorization](references/vectorization.md) |
 | Clean up, caption, frame, or deliver existing recordings and footage | [Video projects](references/video-projects.md) |
 | Music video, dancing mascot or timed HTML scene with a local soundtrack | [Music videos](references/music-video.md) |
+| Product launch film, UI mockup motion, kinetic type, or coming from HyperFrames or Remotion | [Launch films](references/launch-films.md) |
 | Authorized YouTube or other public web-media excerpt (`yt-dlp` / `youtube-dl`) | [Web-media excerpts](references/web-media-excerpts.md) |
 | Generate images, clips, narration or transcripts | [Gateway media](references/gateway-media.md) |
 | Product mark, marketing illustration or topic icon | [Brand illustrations](references/brand-illustrations.md) |

package/skills/slopcamera/references/install.md

@@ -1,4 +1,4 @@
-# Install and diagnose Slopcamera
+# Install and diagnose SlopCamera
 
 Use this reference when the CLI is unavailable, a command differs from the installed release, or `slopcamera doctor` reports a missing dependency for the selected workflow.
 
@@ -14,14 +14,14 @@ command -v slopcamera
 
 A restricted shell can omit package-manager paths. Check known host installation paths before declaring a tool unavailable. If Bun is genuinely absent, follow its official [installation guide](https://bun.sh/docs/installation) within the user’s authorized setup scope. Do not switch package managers or pipe an unreviewed installer into a shell.
 
-Slopcamera installs from its verified release archive: `bun add --global https://github.com/hraness/slopcamera/releases/download/v3.4.0/hraness-slopcamera-3.4.0.tgz`, then `slopcamera doctor --json`. Building from source is the contributor path. Historical Atet archives do not install the renamed CLI; never substitute `slopcamera` into an old archive URL.
+Slopcamera installs from its verified release archive: `bun add --global https://github.com/hraness/slopcamera/releases/download/v3.6.0/hraness-slopcamera-3.6.0.tgz`, then `slopcamera doctor --json`. Building from source is the contributor path. Historical Atet archives do not install the renamed CLI; never substitute `slopcamera` into an old archive URL.
 
 If an update from a previous local archive reports `DependencyLoop`, use Bun's
 [named tarball syntax](https://bun.com/docs/pm/cli/add#tarball-dependencies) with
 the same verified archive:
 
 ```sh
-bun add --global @hraness/slopcamera@https://github.com/hraness/slopcamera/releases/download/v3.4.0/hraness-slopcamera-3.4.0.tgz
+bun add --global @hraness/slopcamera@https://github.com/hraness/slopcamera/releases/download/v3.6.0/hraness-slopcamera-3.6.0.tgz
 slopcamera --version
 ```
 

package/skills/slopcamera/references/launch-films.md

@@ -0,0 +1,154 @@
+# Make a product launch film
+
+Use this workflow for a short film that walks through a product: kinetic type,
+the product's own UI in a browser frame with a moving camera, a cursor and a
+drawn highlight, a proof act with real numbers, a limits card and an end card.
+The film is plain HTML, CSS and JavaScript rendered by `slopcamera html render`.
+React is used only to turn the site's mockup components into static markup.
+
+The same source gives a web MP4 and WebM, a poster, a social still, square and
+vertical cuts, one short clip per act, and WebVTT captions. Each act's caption
+doubles as the source text for a social thread post.
+
+## Check the command
+
+```sh
+slopcamera help html
+slopcamera doctor --json
+```
+
+The installed CLI must list `html init`, `html still` and `html deliver`.
+Rendering needs the admitted local Chrome runtime and FFmpeg/FFprobe. Follow
+[installation and readiness](install.md) if the command is missing.
+
+## Start a film
+
+```sh
+slopcamera html init video --template launch-film --aspect 16:9
+cd video
+bun install
+bun run build
+```
+
+`--aspect` takes `16:9`, `1:1` or `9:16` and only sets the default in
+`film.json`; `bun build.ts --aspect 9:16` re-lays the same film at another size.
+The project pins the SlopCamera version that wrote it in `package.json`, so the
+CLI version is recorded next to the source.
+
+| File | Edit it to |
+| --- | --- |
+| `film.json` | Change copy, steps, proof items, colors, fonts and product CSS. |
+| `mockups.tsx` | Replace the placeholder product with the site's real mockup components. |
+| `timeline.ts` | Change act order and length. Captions and clips follow it. |
+| `film.css` | Restyle the stage, masks, grain and browser frame. |
+| `film.js` | Change the choreography. Keep every value a function of `t`. |
+
+`bun run build` writes `out/film.html`, `out/scene.json`, `out/captions.vtt`
+and `out/beats.json`. It inlines `@hraness/design-kit` `mockups.css` when the
+project can resolve it, then any `productCss` files and fonts, and validates the
+scene before writing it. The document limit is 1 MiB; the build prints its size.
+
+## Keep every frame a function of time
+
+A renderer can ask for any frame in any order, once or twice. Build each frame
+from `t` alone:
+
+- Read time from `SlopcameraOverlay.onFrame(({ timeMs }) => ...)`. Never use
+  `Date.now`, `requestAnimationFrame`, CSS transitions, CSS animations or a
+  counter carried between frames.
+- Hide finished scenes with `show(element, on)`. It sets both `visibility` and
+  `display`, so a hidden scene cannot leak a stale layer into a later frame.
+- Measure layout once, before the first frame, and store the rectangles. Do not
+  measure inside a scaled or transformed scene.
+- Load fonts and images through `SlopcameraOverlay.ready(...)` before frames.
+
+The helpers in `@hraness/slopcamera/local/html-film` follow these rules.
+`build.ts` bundles them into `out/film.html`.
+
+| Need | Helpers |
+| --- | --- |
+| Numbers and easing | `clamp`, `lerp`, `prog(t, start, end)`, `easings`, `spring` |
+| Kinetic type | `split(element, "word" \| "char")`, then `kin(element, t, inAt, outAt)` |
+| Acts and state | `defineTimeline`, `crossfade`, `stepValue`, `show` |
+| Product walk | `camera`, `cameraBetween`, `cameraTransform`, `cursor`, `placeCursor`, `drawMark` |
+| Captions | `captionsFromTimeline(timeline)` writes WebVTT from act captions |
+
+## Direct each act
+
+- **Cold open.** Two short lines over a collage of the problem. Stagger words
+  by 60 to 90 ms and hold each line long enough to read twice.
+- **Title.** The product name and the same one-line promise the product's site
+  uses. One idea, one hold.
+- **Product walk.** One step per entry in `film.json`. Each step names a
+  `data-film` surface for the camera `focus`, a `target` for the cursor click,
+  an optional `highlight` outline and an optional `after` state set on the target
+  once clicked. Let the camera settle before the cursor moves, click, then draw
+  the highlight. Keep steps near 4 seconds.
+- **Proof.** Count numbers up from a facts file or release record. Never type a
+  number into `film.json` by hand.
+- **Limits.** Say plainly what the product does not do.
+- **End card.** Name, address and one line.
+
+Keep public copy in plain words and sentence case, with no exclamation marks and
+no hype. Keep the placeholder illustration note until the surfaces show the real
+product.
+
+## Review stills before rendering
+
+```sh
+slopcamera html still --input out/scene.json --at 3,12.5,20 --output out/stills
+slopcamera html preview --input out/scene.json --every 2 --output out/preview
+```
+
+Both render with the same injected runtime as `html render`, so a still matches
+the rendered frame at that time. `preview` also writes `contact-sheet.png`. Look
+at each act's hold, each click and each highlight before a full render. For a
+quick draft render, `bun build.ts --scale 0.5 --fps 15 --until 3` keeps the
+layout and shrinks the canvas, frame rate and length.
+
+## Render and deliver
+
+```sh
+slopcamera html render --input out/scene.json --json > out/export.json
+slopcamera html deliver out/export.json --basename launch --poster-at 9 --social-at 9 \
+  --cuts 1:1,9:16 --per-beat-clips
+```
+
+`deliver` reads `output.path` from the export and checks its hash, then writes
+into `out/deliver/`:
+
+- `launch.mp4`, H.264 with faststart for the web, and `launch.webm`, VP9
+- `launch-poster.jpg` and a 1200x630 `launch-social.jpg`
+- `launch-1x1.mp4` and `launch-9x16.mp4`, the whole frame over a blurred fill
+- one 6 to 10 second clip per act from `beats.json` beside the export, or the file `--beats` names
+- `launch-receipt.json` with each file's size, hash and budget
+
+Budgets are 12 MB per MP4, 10 MB for the WebM and 250 KB per JPEG. `deliver`
+exits non-zero when a file is over budget; shorten the film, simplify the grain
+or lower the frame rate rather than raising the budget.
+
+## Turn beats into a thread
+
+`out/beats.json` lists each act's id, start, end and caption. Use one post per
+act, in order, with that act's clip or still attached. The captions are already
+short and in plain words; edit them in `film.json` so the film and the posts stay
+the same. The WebVTT file carries the same lines for the web player.
+
+## Coming from HyperFrames or Remotion
+
+There is no importer. The ideas map directly:
+
+| HyperFrames or Remotion | Launch film |
+| --- | --- |
+| A composition's HTML, CSS and JS | `film.html`, `film.css` and `film.js` in a `plain` scene |
+| `useCurrentFrame()` | `timeMs` from `SlopcameraOverlay.onFrame`, as `t` in seconds |
+| `interpolate(frame, [a, b], [x, y])` | `lerp(x, y, prog(t, a, b))` |
+| `spring({ frame, fps })` | `spring(seconds)` |
+| `<Sequence from durationInFrames>` | an act in `defineTimeline`, read with `timeline.local(t, id)` |
+| `<Series>` with overlaps | acts with `overlap`, blended by `crossfade` |
+| `staticFile()` | a declared resource read with `SlopcameraOverlay.asset(name)` |
+| `delayRender()` | `SlopcameraOverlay.ready(promise)` |
+| Rendering with the CLI | `slopcamera html render`, then `html deliver` |
+
+Keep React components as mockups rendered to static markup. Do not run React
+inside the film: every frame must come from `t`, not from component state.

package/skills/slopcamera/references/visual-communication.md

@@ -1,4 +1,4 @@
-# Slopcamera visual communication rules
+# SlopCamera visual communication rules
 
 Use these rules to turn supplied content into a diagram without adding content.
 

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { readFile, writeFile } from "node:fs/promises"
-import { resolve } from "node:path"
+import { dirname, resolve } from "node:path"
 import {
   artifactSummary,
   checkDiagramFile,
@@ -17,8 +17,16 @@ import {
 } from "./generate.js"
 import {
   generateSlopcameraIcon,
+  slopcameraIconContexts,
   slopcameraIconMaximumRounds,
+  type SlopcameraIconContext,
+  type SlopcameraIconPurpose,
 } from "./icon.js"
+import {
+  generateSlopcameraIconSet,
+  parseSlopcameraIconSetSpec,
+  slopcameraIconSetMaximumSetRounds,
+} from "./icon-set.js"
 import {
   generateSlopcameraImageGallery,
   parseSlopcameraGalleryVary,
@@ -40,11 +48,11 @@ import { checkDrawingFile, renderDrawingFile, starterDrawingSource } from "./dra
 import { SLOPCAMERA_VERSION } from "./version.js"
 import { createVisualStyleDirection, getVisualStyleProfile, VISUAL_STYLE_PROFILES } from "./visual-style.js"
 import { reportUsefulResult, type UsefulResultObserver } from "./support-completion.js"
-import { runProductSupportCommand, showProductSupportInvitation, standaloneSupportEnvironment } from "./support.js"
+import { runProductSupportCommand, showProductSupportInvitation, slopcameraSupportAdvancedHelp, slopcameraSupportHelpLine, standaloneSupportEnvironment } from "./support.js"
 
 export const slopcameraCliVersion = SLOPCAMERA_VERSION
 
-const help = `slopcamera ${slopcameraCliVersion}
+const help = () => `slopcamera ${slopcameraCliVersion}
 
 Turn source material into deterministic diagrams, images, and canvas assets.
 
@@ -59,7 +67,11 @@ Usage:
   slopcamera image generate <prompt> --output <file.png|jpg|webp> [--model <provider/model>] [--json]
   slopcamera image icon <subject> --output <file.svg> [--purpose <mark|illustration>]
     [--model <provider/model>] [--ink <#rgb|#rrggbb>] [--rounds <1-${slopcameraIconMaximumRounds}>]
+    [--context <${slopcameraIconContexts.join("|")}>] [--candidates <1-${slopcameraIconMaximumRounds}>]
     [--critique-model <provider/model>] [--keep-raster] [--json]
+  slopcamera image icon --set <file.json> --output-dir <directory>
+    [--context <${slopcameraIconContexts.join("|")}>] [--candidates <1-${slopcameraIconMaximumRounds}>]
+    [--set-rounds <1-${slopcameraIconSetMaximumSetRounds}>] [--keep-raster] [--json]
   slopcamera image gallery <subject> --output-dir <directory> [--kind <${slopcameraGalleryKinds.join("|")}>]
     [--count <1-${slopcameraGalleryLimits.candidates}>] [--vary <axis[=v1,v2][;axis...]>] [--candidates <file.json>]
     [--model <provider/model>] [--cell <${slopcameraGalleryLimits.cellEdgeMin}-${slopcameraGalleryLimits.cellEdgeMax}>] [--tile|--no-tile] [--json]
@@ -69,7 +81,6 @@ Usage:
   slopcamera code execute <operation> --input <JSON>
   slopcamera mcp --root <workspace>
   slopcamera doctor
-  slopcamera support [--json|protocol --json|offer --json|shown <id>|release <id>|dismiss|snooze|enable|status --json]
   slopcamera skill path
   slopcamera skill install [--target codex|claude|agents] [--scope user|project] [--force]
 
@@ -104,14 +115,21 @@ vectorizer, and (when --rounds exceeds 1) critiqued by a vision model whose
 feedback revises the prompt for the next attempt. Only Slopcamera's own
 generated output is uploaded for critique — never user media.
 
+Icon --set reads a bounded JSON manifest ({name?, ink?, context?, members:
+[{slug, subject, purpose?, context?}]}) and generates the whole family at
+once: each member keeps a small candidate pool, joint selection minimizes the
+measured coverage and stroke-weight spread across the set, and a
+contact-sheet critique reviews the family as a unit before SVGs publish.
+Manifests and receipts stay local.
+
 Gallery generates several bounded candidates in parallel and composes them
 into one labelled contact sheet plus a receipt. Use it to review texture,
 skybox, backdrop, sprite, or design alternatives, then promote a chosen
 candidate file explicitly — nothing is applied automatically.
 
-Optional support: after useful work, agents can read slopcamera support protocol --json.
-Discovery uses stderr without claiming an invitation; HRANESS_SUPPORT_AUDIENCE=off disables it.
-No feature requires payment. Imported CLI/SDK calls and probes stay quiet.
+${slopcameraSupportHelpLine()}
+
+Advanced verbs, including the support protocol, live under \`slopcamera help advanced\`.
 
 Code mode searches and executes a fixed semantic registry. Execute accepts
 typed JSON for one exact owned operation code; it never evaluates source text.
@@ -251,6 +269,7 @@ export interface SlopcameraCliDependencies {
   readonly generate?: typeof generateSlopcameraImageFile
   readonly hostResourceCoordinator?: HostResourceCoordinator
   readonly icon?: typeof generateSlopcameraIcon
+  readonly iconSet?: typeof generateSlopcameraIconSet
   readonly log?: (value: string) => void
   readonly vectorize?: typeof vectorizeImage
 }
@@ -364,7 +383,7 @@ function canonicalArguments(args: readonly string[]): readonly string[] {
     surface === "vectorize" ||
     surface === "generate"
   ) {
-    throw new Error(`The flat \`${surface}\` command moved to a namespaced Slopcamera surface.\n\n${help}`)
+    throw new Error(`The flat \`${surface}\` command moved to a namespaced Slopcamera surface.\n\n${help()}`)
   }
   return args
 }
@@ -408,8 +427,12 @@ export async function main(
     return
   }
   const [command, ...rest] = canonicalArguments(args)
-  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-    console.log(help)
+  if (command === undefined || command === "--help" || command === "-h") {
+    console.log(help())
+    return
+  }
+  if (command === "help") {
+    console.log(rest[0] === "advanced" ? slopcameraSupportAdvancedHelp() : help())
     return
   }
   if (command === "version" || command === "--version" || command === "-v") {
@@ -562,7 +585,19 @@ export async function main(
   if (command === "icon") {
     const parsed = parseArguments(
       rest,
-      new Set(["model", "output", "ink", "purpose", "rounds", "critique-model"]),
+      new Set([
+        "model",
+        "output",
+        "output-dir",
+        "ink",
+        "purpose",
+        "rounds",
+        "critique-model",
+        "context",
+        "candidates",
+        "set",
+        "set-rounds",
+      ]),
     )
     const unknownFlags = [...parsed.flags].filter(
       (flag) => flag !== "json" && flag !== "keep-raster",
@@ -570,13 +605,6 @@ export async function main(
     if (unknownFlags.length > 0) {
       throw new Error(`Unknown icon option: --${unknownFlags[0]}`)
     }
-    if (parsed.positionals.length !== 1) {
-      throw new Error("slopcamera image icon accepts exactly one subject")
-    }
-    const output = requiredOption(parsed, "output")
-    if (!output.toLowerCase().endsWith(".svg")) {
-      throw new Error("--output must end in .svg")
-    }
     const model = parsed.options.model ?? slopcameraImageModels[1]
     if (
       model.length > 256 ||
@@ -604,10 +632,97 @@ export async function main(
     if (purpose !== undefined && purpose !== "mark" && purpose !== "illustration") {
       throw new Error("--purpose must be mark or illustration")
     }
+    const context = parsed.options.context
+    if (
+      context !== undefined &&
+      !slopcameraIconContexts.includes(context as never)
+    ) {
+      throw new Error(
+        `--context must be one of: ${slopcameraIconContexts.join(", ")}`,
+      )
+    }
     const rounds = parsePositiveInteger(parsed.options.rounds, "rounds")
     if (rounds !== undefined && rounds > slopcameraIconMaximumRounds) {
       throw new Error(`--rounds must be at most ${slopcameraIconMaximumRounds}`)
     }
+    const candidates = parsePositiveInteger(parsed.options.candidates, "candidates")
+    if (candidates !== undefined && candidates > slopcameraIconMaximumRounds) {
+      throw new Error(`--candidates must be at most ${slopcameraIconMaximumRounds}`)
+    }
+    const setRounds = parsePositiveInteger(parsed.options["set-rounds"], "set-rounds")
+    if (setRounds !== undefined && setRounds > slopcameraIconSetMaximumSetRounds) {
+      throw new Error(`--set-rounds must be at most ${slopcameraIconSetMaximumSetRounds}`)
+    }
+
+    if (parsed.options.set !== undefined) {
+      if (parsed.positionals.length !== 0) {
+        throw new Error("slopcamera image icon --set takes no subject positional")
+      }
+      if (parsed.options.output !== undefined) {
+        throw new Error("--output cannot be combined with --set; use --output-dir")
+      }
+      const outputDir = requiredOption(parsed, "output-dir")
+      const manifestPath = parsed.options.set
+      let manifestText: string
+      try {
+        manifestText = await readFile(manifestPath, "utf8")
+      } catch {
+        throw new Error(`--set manifest could not be read: ${manifestPath}`)
+      }
+      if (Buffer.byteLength(manifestText, "utf8") > 256 * 1024) {
+        throw new Error("--set manifest exceeds the 256 KiB bound")
+      }
+      let manifestJson: unknown
+      try {
+        manifestJson = JSON.parse(manifestText)
+      } catch {
+        throw new Error("--set manifest must be valid JSON")
+      }
+      const spec = parseSlopcameraIconSetSpec(manifestJson)
+      const result = await withSlopcameraOperationHostAdmission(
+        "slopcamera.image.icon",
+        async (lease) =>
+          await (dependencies.iconSet ?? generateSlopcameraIconSet)({
+            keepRaster: parsed.flags.has("keep-raster"),
+            manifestDir: dirname(resolve(manifestPath)),
+            model,
+            outputDir,
+            spec,
+            inheritedFileDescriptors: [lease.inheritedFileDescriptor],
+            ...(critiqueModel === undefined ? {} : { critiqueModel }),
+            ...(ink === undefined ? {} : { ink }),
+            ...(context === undefined
+              ? {}
+              : { context: context as SlopcameraIconContext }),
+            ...(purpose === undefined
+              ? {}
+              : { purpose: purpose as SlopcameraIconPurpose }),
+            ...(rounds === undefined ? {} : { rounds }),
+            ...(candidates === undefined ? {} : { candidatesPerMember: candidates }),
+            ...(setRounds === undefined ? {} : { setRounds }),
+          }),
+        hostAdmissionOptions(dependencies),
+      )
+      if (parsed.flags.has("json")) {
+        ;(dependencies.log ?? console.log)(JSON.stringify(result, null, 2))
+      } else {
+        ;(dependencies.log ?? console.log)(
+          `Icon set ${result.name ?? "icon-set"}: ${result.members.length} members to ${result.outputDir} ` +
+            `(target coverage ${result.target.coverageRatio.toFixed(3)}, ` +
+            `stroke ${result.target.strokePx.toFixed(1)}px, ${result.setRoundsUsed} set rounds)`,
+        )
+      }
+      reportUsefulResult(dependencies.onUsefulResult)
+      return
+    }
+
+    if (parsed.positionals.length !== 1) {
+      throw new Error("slopcamera image icon accepts exactly one subject")
+    }
+    const output = requiredOption(parsed, "output")
+    if (!output.toLowerCase().endsWith(".svg")) {
+      throw new Error("--output must end in .svg")
+    }
     const result = await withSlopcameraOperationHostAdmission(
       "slopcamera.image.icon",
       async (lease) => await (dependencies.icon ?? generateSlopcameraIcon)({
@@ -620,6 +735,10 @@ export async function main(
         ...(ink === undefined ? {} : { ink }),
         ...(purpose === undefined ? {} : { purpose }),
         ...(rounds === undefined ? {} : { rounds }),
+        ...(context === undefined
+          ? {}
+          : { context: context as SlopcameraIconContext }),
+        ...(candidates === undefined ? {} : { candidatePool: candidates }),
       }),
       hostAdmissionOptions(dependencies),
     )
@@ -849,7 +968,7 @@ export async function main(
     throw new Error("Use slopcamera skill path or install")
   }
 
-  throw new Error(`Unknown command: ${command}\n\n${help}`)
+  throw new Error(`Unknown command: ${command}\n\n${help()}`)
 }
 
 if (import.meta.main) {

package/src/generate.ts

@@ -2,6 +2,13 @@ import { createHash, randomUUID } from "node:crypto"
 import { link, rm, writeFile } from "node:fs/promises"
 import { dirname, extname, resolve } from "node:path"
 import { SlopcameraCloudError } from "./cloud-errors.js"
+import {
+  imageCallCosts,
+  type SlopcameraImageUsage,
+  type SlopcameraProviderCost,
+} from "./generation-pricing.js"
+
+export type { SlopcameraProviderCost } from "./generation-pricing.js"
 
 export const slopcameraGatewayApiBaseUrl =
   "https://ai-gateway.vercel.sh/v4/ai" as const
@@ -85,6 +92,12 @@ export interface SlopcameraGenerateDependencies {
   readonly fetch?: SlopcameraGatewayFetch
   readonly loadRuntime?: () => Promise<GatewayRuntime>
   readonly maximumResponseBytes?: number
+  /**
+   * Called once for every image call that reached the provider, including a
+   * call that failed afterwards, with that call's provider cost lines.
+   * Billing uses it to settle or release with the actual cost.
+   */
+  readonly onProviderCost?: (costs: readonly SlopcameraProviderCost[]) => void
 }
 
 const defaultGenerationTimeoutMs = 5 * 60_000
@@ -522,6 +535,15 @@ function warningReceipt(value: unknown): string {
   return `${type} sha256:${createHash("sha256").update(detail).digest("hex")}`
 }
 
+function returnedUsage(value: unknown): SlopcameraImageUsage | undefined {
+  if (!isObject(value) || !isObject(value.usage)) return undefined
+  const { inputTokens, outputTokens } = value.usage
+  return {
+    inputTokens: typeof inputTokens === "number" ? inputTokens : undefined,
+    outputTokens: typeof outputTokens === "number" ? outputTokens : undefined,
+  }
+}
+
 function parseResult(
   value: unknown,
   model: string,
@@ -590,6 +612,24 @@ async function performGeneration(
   const prompt = validatePrompt(input.prompt)
   const credential = resolveSlopcameraGatewayCredential(dependencies.environment)
   const timeout = combineSignals(input.signal, validateTimeout(input.timeoutMs))
+  // Cost accounting: once the provider call starts it may be billed, so every
+  // exit after that point reports a cost, from returned usage when there is
+  // one, otherwise the worst case. A 4xx Gateway answer is a refusal the
+  // provider does not bill; a 5xx may come after the provider already
+  // produced the image, so it still reports the worst case.
+  let dispatched = false
+  let rejected = false
+  let reported = false
+  const report = (usage: SlopcameraImageUsage | undefined): void => {
+    if (reported || !dispatched || rejected) return
+    reported = true
+    dependencies.onProviderCost?.(imageCallCosts(model, prompt, usage))
+  }
+  const observedFetch: SlopcameraGatewayFetch = async (request, init) => {
+    const response = await (dependencies.fetch ?? globalThis.fetch)(request, init)
+    if (response.status >= 400 && response.status < 500) rejected = true
+    return response
+  }
   try {
     const generation = (async () => {
       assertGenerationActive(timeout.signal)
@@ -602,13 +642,14 @@ async function performGeneration(
         apiKey: credential.token,
         baseURL: slopcameraGatewayApiBaseUrl,
         fetch: createFixedGatewayFetch({
-          ...(dependencies.fetch === undefined ? {} : { fetch: dependencies.fetch }),
+          fetch: observedFetch,
           ...(dependencies.maximumResponseBytes === undefined
             ? {}
             : { maximumResponseBytes: dependencies.maximumResponseBytes }),
         }),
       })
       assertGenerationActive(timeout.signal)
+      dispatched = true
       const generated = await runtime.generateImage({
         abortSignal: timeout.signal,
         maxRetries: 0,
@@ -616,10 +657,12 @@ async function performGeneration(
         n: 1,
         prompt,
       })
+      report(returnedUsage(generated))
       return parseResult(generated, model)
     })()
     return await Promise.race([generation, timeout.interruption])
   } catch (error) {
+    report(undefined)
     if (error instanceof SlopcameraCloudError) throw error
     throw new SlopcameraCloudError(
       "GENERATION_FAILED",