@hraness/slopcamera 3.6.0 → 3.7.0

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.5.0/hraness-slopcamera-3.5.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.5.0/hraness-slopcamera-3.5.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,
@@ -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]
@@ -103,6 +115,13 @@ 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
@@ -250,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
 }
@@ -565,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",
@@ -573,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 ||
@@ -607,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)({
@@ -623,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),
     )

package/src/generation-pricing.ts

@@ -53,7 +53,7 @@ interface ImagePricedModel {
 
 export type SlopcameraImageModelPrice = TokenPricedImageModel | ImagePricedModel
 
-export const slopcameraProviderPricesCheckedAt = "2026-09-26"
+export const slopcameraProviderPricesCheckedAt = "2026-09-27"
 
 /**
  * Cited list prices. A model without an entry here cannot be billed: the
@@ -88,6 +88,26 @@ export const slopcameraImageModelPrices: Readonly<
     perImage: 35_000,
     source: "https://vercel.com/ai-gateway/models/recraft-v4.1-utility",
   }),
+  "bfl/flux-pro-1.1": Object.freeze({
+    kind: "image",
+    perImage: 40_000,
+    source: "https://vercel.com/ai-gateway/models/flux-pro-1.1",
+  }),
+  "bfl/flux-pro-1.1-ultra": Object.freeze({
+    kind: "image",
+    perImage: 60_000,
+    source: "https://vercel.com/ai-gateway/models/flux-pro-1.1-ultra",
+  }),
+  "bfl/flux-kontext-pro": Object.freeze({
+    kind: "image",
+    perImage: 40_000,
+    source: "https://vercel.com/ai-gateway/models/flux-kontext-pro",
+  }),
+  "bfl/flux-kontext-max": Object.freeze({
+    kind: "image",
+    perImage: 80_000,
+    source: "https://vercel.com/ai-gateway/models/flux-kontext-max",
+  }),
 })
 
 /**