@hraness/slopcamera 3.9.1 → 3.10.0

package/README.md

@@ -1,53 +1,44 @@
 # SlopCamera
 
-[![A brass optical instrument rendered in Blender from a SlopCamera native starter](apps/web/media/native-product-poster-51b1658c46d3.webp)](https://slopcamera.com/docs/tutorials/first-native-film#inspect-the-finished-example)
+[![Rain, bottled: a cloud rains inside a glass vessel with brass fittings](apps/web/media/rain-bottled-poster-479a32b54a03.webp)](https://slopcamera.com/docs/how-to/remix-the-showcase#rain-bottled)
 
-**SlopCamera is a media studio for coding agents.** SlopCamera lets your coding
+**A multimedia studio for your coding agent.** SlopCamera lets your coding
 agent make images, diagrams, animation, 3D scenes, and video from source files
-it can keep revising. It works with Codex, Claude Code, and other agents.
-
-A frontier model such as Claude Opus can write a video or a graphic from
-scratch in one pass. SlopCamera gives the agent packaged, tested techniques to
-reuse instead, for diagrams, motion graphics, 3D scenes, native Blender,
-CadQuery, and Manim films, and footage edits. The agent writes a short source
-file, and the SlopCamera CLI renders it, checks it, and writes the variants each
-technique supports, such as light and dark diagrams or 16:9 and 9:16 cuts of a
-video. The source stays beside the output, so a revision is an edit to that
-file and a new render.
-
-[Install](#install-slopcamera) · [First diagram](#make-your-first-diagram) · [Techniques](https://slopcamera.com/docs/reference/techniques) · [Docs](https://slopcamera.com/docs) · [Compare](#compared-with-other-tools) · [slopcamera.com](https://slopcamera.com)
-
-## Why SlopCamera
-
-- **The agent writes the part that is specific to your request.** A diagram
-  is a JSON file of boxes and arrows, a title animation is an HTML scaffold
-  for one of seven profiles, and a 3D shot is scene JSON with a named camera.
-  The renderer, frame timing, encoding, and export formats are already
-  installed. This does not make it cheaper in tokens: in our
-  [benchmark](https://slopcamera.com/docs/explanation/token-benchmark), the median cost with
-  SlopCamera installed was higher than without it on all four tasks.
-- **Revisions change the source, not the whole result.** Change one label,
-  camera, or cut and render again. Every export comes from the same source, so
-  light and dark versions, or 16:9 and 9:16 cuts, stay in step.
-- **Checks run before the agent reports back.** A strict diagram checker,
-  scene audits, render plans, and `doctor` catch problems the agent can
-  fix before you look. They check structure, not taste; you still review the
-  render.
-- **The techniques match the installed CLI.** The Bun CLI, a TypeScript SDK,
-  and an Agent Skill ship at the same version. The skill sends the agent to
-  the guide for its current job instead of loading every guide at once.
-- **Work stays on your machine.** Projects are local files and there is no
-  SlopCamera account. Generation is optional: it uses your own Vercel AI
-  Gateway access or, for prompt-only images, prepaid Hraness Credits.
+it can keep revising. Use it with Codex, Claude Code, or another coding agent.
+Direct the style, timing, camera, and sound, then refine the result.
+
+Your agent writes the scene or edit as source. SlopCamera renders it with the
+appropriate engine and keeps the inputs so the agent can change a shot,
+rework a composition, or deliver another format. Combine authored scenes,
+generated media, and your own footage in the same project.
+
+[Watch the films](https://slopcamera.com/#examples) · [Install](#install-slopcamera) · [Direct a film](https://slopcamera.com/docs/how-to/direct-a-film) · [Docs](https://slopcamera.com/docs) · [GitHub examples](examples/showcase)
+
+## What you can make
+
+- **Films and animation.** Author motion graphics, illustrated scenes, and
+  native Blender shots. Control camera, materials, lighting, and timing.
+- **Visual explanations.** Make diagrams and educational films with editable
+  labels, mathematics, narration, and graphics.
+- **Images and designs.** Create illustrations, trace raster artwork to SVG,
+  or revise a parametric architectural model.
+- **Edits of your footage.** Compose shots, sound, overlays, and captions,
+  then export horizontal, vertical, square, or portrait versions.
+
+The [techniques catalog](https://slopcamera.com/docs/reference/techniques)
+connects each job to its supported commands and requirements. SlopCamera is
+free and open source. Local editing and rendering need no SlopCamera account.
+Generation uses your own Vercel AI Gateway account, or prepaid Hraness Credits
+for prompt-only hosted images; model usage is billed separately.
 
 ## Install SlopCamera
 
 Install [Bun 1.3.14 or newer](https://bun.sh), then install the
-[SlopCamera v3.9.0 release](https://github.com/hraness/slopcamera/releases/tag/v3.9.0)
+[SlopCamera v3.9.2 release](https://github.com/hraness/slopcamera/releases/tag/v3.9.2)
 and its matching Agent Skill:
 
 ```sh
-bun add --global https://github.com/hraness/slopcamera/releases/download/v3.9.0/hraness-slopcamera-3.9.0.tgz
+bun add --global https://github.com/hraness/slopcamera/releases/download/v3.9.2/hraness-slopcamera-3.9.2.tgz
 slopcamera skill install --target agents
 ```
 
@@ -56,8 +47,10 @@ The `agents` target works for agents that read `~/.agents/skills`. Use
 inside a repository for a project-only install. Start a new
 agent session so it loads the skill, then ask for a result:
 
-> Create a two-box diagram showing ingestion flowing into review, render it,
-> and show me the dark PNG.
+> Make a short illustrated film of a late-night tram whose destination
+> changes to the moon. Give it warm windows, a rainy city, and a quiet ending.
+> Start with a frame and a motion test so we can direct it before the final
+> render. Keep the source and sound editable.
 
 Setup guides: [Claude Code](https://slopcamera.com/docs/tutorials/claude-code) ·
 [Codex](https://slopcamera.com/docs/tutorials/codex) ·
@@ -67,16 +60,13 @@ Blender install separately; the
 [capability reference](docs/reference/capabilities.md) lists what each
 technique needs.
 
-From 3.8.0, SlopCamera is a CLI with no menu-bar app or background process.
-`slopcamera status` shows what is running, how the last job ended, your last
-known credits balance, the newest outputs and whether the retired menu-bar
-companion still opens at login. `slopcamera tui` keeps
-that screen open and refreshes it; `slopcamera tui --snapshot` prints it once
-and `--json` returns the data. `slopcamera outputs list|open|reveal` lists the
-newest outputs or opens one on this Mac, `slopcamera commands --json` lists
-every command with what it may change, and `slopcamera legacy retire` stops
-the retired menu-bar companion opening at login by moving its LaunchAgent aside; it
-deletes nothing, and `slopcamera doctor` prints the command that restores it.
+On macOS, start with [your first animation](https://slopcamera.com/docs/tutorials/first-animation)
+for a supplied scene you can render and revise without a model account. It
+needs the browser and FFmpeg runtimes reported by `slopcamera doctor --json`.
+For a first result on macOS, Linux, or Windows with no browser or paid model,
+follow [your first diagram](https://slopcamera.com/docs/tutorials/first-diagram).
+The [directing guide](docs/how-to/direct-a-film.md) explains how to ask for useful
+changes to composition, timing, camera, and sound.
 
 <details>
 <summary>Build from source</summary>
@@ -110,70 +100,32 @@ placement and resuming long runs.
 
 </details>
 
-## Make your first diagram
-
-This local task needs no model account. In a new directory, create the
-included diagram, check it, and render it:
+CLI updates in SlopCamera 3.10.0 and newer are enabled by default for supported
+Bun and npm global installations. See [update controls](docs/reference/capabilities.md#cli-updates)
+to keep a version or check for a release.
 
-```sh
-mkdir slopcamera-first
-cd slopcamera-first
-slopcamera diagram init first.diagram.json
-slopcamera diagram check first.diagram.json --strict
-slopcamera diagram render first.diagram.json
-```
+## Make a film. Then direct it again.
 
-You now have `example-flow.tldr`, `example-flow.light.svg`,
-`example-flow.dark.svg`, `example-flow.light.png`, and
-`example-flow.dark.png`. The JSON stays editable, and the `.tldr` file opens in
-tldraw. Rendering again replaces those five files.
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="apps/web/media/source-to-film-dark-png-b8db55ec6e42.png">
-  <img alt="Diagram export, rendered scene, and footage point into Project, which points to Preview and Delivery." src="apps/web/media/source-to-film-light-png-c3c24c460490.png">
-</picture>
-
-The diagram above was rendered from one
-[JSON file](examples/showcase/diagram/source-to-film.diagram.json). Each box in
-it is a short object the agent writes:
-
-```json
-{
-  "id": "diagram",
-  "type": "rect",
-  "x": 100,
-  "y": 140,
-  "width": 320,
-  "height": 140,
-  "radius": 24,
-  "label": "Diagram export",
-  "labelFontSize": 36,
-  "labelWeight": 500,
-  "tone": "blue"
-}
-```
+[Last tram to the moon](https://slopcamera.com/docs/tutorials/first-animation)
+is a complete first project: original illustrated artwork, a twelve-second
+journey, and a visible revision. The tutorial renders locally without a model
+account or downloaded artwork.
 
-To revise it, the agent changed one label, and the file name for the new
-outputs, in a
-[copy of that file](examples/showcase/diagram/source-to-film-revised.diagram.json):
+The two supplied render requests use the same scene. The first sets the city
+and departure; the second enlarges the moon while keeping the journey, palette,
+and timing. Ask your agent:
 
-```diff
--  "name": "source-to-film",
-+  "name": "source-to-film-revised",
-...
--      "label": "Delivery",
-+      "label": "Social delivery",
-```
+> Make the moon dominate the destination. Preserve the copper tram and rainy
+> city. Keep both versions so I can compare their endings.
 
-```sh
-slopcamera diagram render source-to-film-revised.diagram.json
-```
+[Follow the animation tutorial](https://slopcamera.com/docs/tutorials/first-animation),
+then [remix the showcase](https://slopcamera.com/docs/how-to/remix-the-showcase):
+a bottled storm, a paper ocean, a dancing laundromat, a band of harmonics,
+and three edits of the same eclipse footage. Each piece has source,
+production instructions, and a suggested creative revision.
 
-That two-line change produced a new `.tldr` file, both SVGs, and both PNGs,
-including the
-[revised light PNG](apps/web/media/source-to-film-revised-light-png-9ad9767c2bdf.png).
-[Your first diagram](https://slopcamera.com/docs/tutorials/first-diagram) walks
-through the same edit.
+For a smaller first task, [make a diagram](https://slopcamera.com/docs/tutorials/first-diagram)
+and export its editable tldraw document, light and dark SVGs, and PNGs.
 
 ## What SlopCamera does
 
@@ -210,10 +162,10 @@ characters, cloth, and liquid caches; CadQuery for parametric solids and STEP;
 and Manim Community for mathematical animation. Seven editable starters
 include a product, character, shaded street, cloth, liquid, CAD bracket, and
 educational presenter. Watch the
-[six-second product film](https://slopcamera.com/docs/tutorials/first-native-film),
-then change its [geometry, materials, and camera](examples/showcase/native/product).
+[Rain, bottled](https://slopcamera.com/docs/how-to/remix-the-showcase#rain-bottled),
+then change its [weather, materials, and camera](examples/showcase/studio-relaunch/rain-bottled).
 For 2D motion, try the
-[editable editorial animation](https://slopcamera.com/docs/tutorials/first-animation).
+[illustrated tram film](https://slopcamera.com/docs/tutorials/first-animation).
 The [portrait geometry lesson](https://slopcamera.com/docs/how-to/educational-video)
 adds mathematical typesetting, a presenter, and captions.
 

package/apps/desktop/application/operation.ts

@@ -4,7 +4,7 @@ import type { z } from "zod";
 
 import type { ApplicationContext } from "./context";
 
-export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.9.1" as const;
+export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.10.0" as const;
 
 export const OPERATION_KINDS = [
   "scene.audit",

package/apps/desktop/cli/commands.ts

@@ -365,7 +365,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.9.1";
+export const SLOPCAMERA_VERSION = "3.10.0";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one

package/apps/desktop/cli/entry.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+import { fileURLToPath } from "node:url";
+import type { CliUpdateOptions, StartupResult } from "@hraness/cli-update";
+import { SLOPCAMERA_VERSION } from "../../../src/version";
+import { slopcameraUpdatePolicy } from "./update-policy";
+
+type EntryPorts = {
+  update(options: CliUpdateOptions): Promise<StartupResult>;
+  main(): Promise<void>;
+};
+
+export async function runSlopcameraEntrypoint(argv = process.argv.slice(2), ports: Partial<EntryPorts> = {}): Promise<void> {
+  const main = ports.main ?? (async () => (await import("./main")).runMainEntrypoint({}, true));
+  // Compiled private binaries and their embedded workers keep the native installer.
+  if (import.meta.path.includes("$bunfs")) { await main(); return; }
+  // The product renders its own command help; the updater sees an inert help request.
+  const gateArgv = argv[0] === "update" && argv.slice(1).some(arg => arg === "--help" || arg === "-h")
+    ? ["help", "update"] : argv;
+  const update = await (ports.update ?? (async options => (await import("@hraness/cli-update")).runCliUpdate(options)))({
+    packageName: "@hraness/slopcamera", version: SLOPCAMERA_VERSION, binName: "slopcamera",
+    entrypoint: fileURLToPath(import.meta.url), argv: gateArgv,
+    provider: { kind: "github", repository: "hraness/slopcamera", assetName: "hraness-slopcamera-{version}.tgz" },
+    ...slopcameraUpdatePolicy(gateArgv),
+    verifyArtifact: async artifact => (await import("./update-verification")).verifySlopcameraUpdate(artifact),
+  });
+  if (update.handled) { process.exitCode = update.exitCode; return; }
+  try { await main(); }
+  finally { await update.release(); }
+}
+
+if (import.meta.main) await runSlopcameraEntrypoint();

package/apps/desktop/cli/help.ts

@@ -33,6 +33,7 @@ Commands:
   runs list|show|resume|approve|cancel
                                  Inspect and control durable workflow runs
   doctor                         Check local render and asset capabilities
+  update                         Update the CLI or manage automatic updates
   ai models|image|video|speech|transcribe
                                  Discover and run Vercel AI Gateway media models
   credits status|topup|wait|forget
@@ -719,6 +720,13 @@ compiles a bounded set of single-axis candidate plans under cinema/galleries/, e
 re-hashed through the canonical composition digest; it never selects a candidate.
 
 Imported media starts unverified. Align its audio before relying on synchronization. Structural edits are project-time operations and affect every placement. Camera moves address any placed video stream; metadata-driven screen zooms still require a recording-backed source placement. Face analysis and geometry tracks remain local. --select largest follows the largest currently visible prepared-layer face per frame. --require-all-selected makes a missing explicit/all-selected face invoke the chosen gap policy.`,
+  update: `Usage: slopcamera update [check|status|enable|disable] [--json]
+
+Supported Bun and npm global installations on macOS and Linux check the immutable
+GitHub release before work starts, at most once a day. Verification needs GitHub CLI.
+Use slopcamera update disable to keep this version, or HRANESS_NO_UPDATE=1 for one
+invocation. Exact Bun version pins require slopcamera update enable. Local image
+vectorization, SDK imports, and the private compiled binary do not update automatically.`,
   render: `Usage: slopcamera render <plan|run> <recording> [--display <id|primary>] [--output <path>] [--dry-run] [--keep-inactivity] [--json]
 
 Long inactivity is analyzed and removed by default; use --keep-inactivity to opt out.`,
@@ -731,10 +739,11 @@ export function commandHelp(topic: readonly string[]): string {
 
 export function completions(words: readonly string[]): readonly string[] {
   const topLevel = [
-    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "style", "workflows", "code", "runs", "doctor", "ai", "credits", "media", "support", "outputs", "status", "tui", "commands", "legacy", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
+    "update", "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "style", "workflows", "code", "runs", "doctor", "ai", "credits", "media", "support", "outputs", "status", "tui", "commands", "legacy", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
   ];
   if (words.length <= 1) return topLevel;
   const command = words[0];
+  if (command === "update") return ["check", "status", "enable", "disable"];
   if (command === "support") return ["protocol", "offer", "shown", "release", "dismiss", "snooze", "enable", "status"];
   if (command === "html") return ["catalog", "scaffold", "init", "render", "still", "preview", "deliver"];
   if (command === "style") return ["list", "show"];

package/apps/desktop/cli/update-policy.ts

@@ -0,0 +1,18 @@
+export function slopcameraUpdatePolicy(argv: readonly string[]): { effectFree: boolean; offline: boolean } {
+  const [command, action] = argv;
+  const portable = ["diagram", "mcp", "canvas", "skill"].includes(command ?? "")
+    || (command === "style" && !argv.includes("--help") && !argv.includes("-h"))
+    || (command === "code" && ["search", "execute"].includes(action ?? ""))
+    || (command === "media" && action === "soundtrack")
+    || (command === "image" && ["vectorize", "icon", "gallery"].includes(action ?? ""))
+    || (command === "image" && action === "generate" && argv.includes("--output"));
+  const registry = ["status", "tui", "commands", "outputs", "legacy", "support"].includes(command ?? "");
+  return {
+    effectFree: command === undefined || ["help", "--help", "-h", "version", "--version", "__complete", "capabilities"].includes(command)
+      || (command === "diagram" && ["help", "--help", "-h"].includes(action ?? ""))
+      || (!portable && !registry && (argv.includes("--help") || argv.includes("-h"))),
+    offline: command === "diagram"
+      || (command === "image" && ["vectorize", "icon"].includes(action ?? ""))
+      || (command === "media" && action === "soundtrack"),
+  };
+}

package/apps/desktop/cli/update-verification.ts

@@ -0,0 +1,76 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const repository = "hraness/slopcamera";
+const maximumMetadataBytes = 2 * 1024 * 1024;
+type Gh = (args: readonly string[]) => Promise<Buffer>;
+
+const runGh: Gh = args => new Promise((resolve, reject) => {
+  execFile("gh", [...args], {
+    encoding: "buffer", timeout: 30_000, maxBuffer: maximumMetadataBytes,
+    env: { ...process.env, GH_HOST: "github.com", GH_PROMPT_DISABLED: "1", GH_PAGER: "cat" },
+  }, (error, stdout) => {
+    // gh's error can include authenticated response bodies. Keep diagnostics fixed.
+    if (error !== null) reject(new Error("SlopCamera release verification failed. Check GitHub CLI access and retry slopcamera update."));
+    else resolve(stdout);
+  });
+});
+
+function record(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid SlopCamera release metadata.");
+  return value as Record<string, unknown>;
+}
+
+/** Keep the install guide's immutable-release and source-bound attestation checks. */
+export async function verifySlopcameraUpdate(
+  artifact: { path: string; version: string; sha256: string },
+  gh: Gh = runGh,
+): Promise<void> {
+  if (!/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/u.test(artifact.version)
+    || artifact.version.length > 50 || !/^[a-f0-9]{64}$/u.test(artifact.sha256)) throw new Error("Invalid SlopCamera update identity.");
+  const tag = `v${artifact.version}`;
+  const json = async (path: string) => {
+    const bytes = await gh(["api", path]);
+    if (bytes.length > maximumMetadataBytes) throw new Error("SlopCamera release metadata is too large.");
+    return record(JSON.parse(bytes.toString("utf8")) as unknown);
+  };
+  await gh(["release", "verify", tag, "--repo", repository]);
+  await gh(["release", "verify-asset", tag, artifact.path, "--repo", repository]);
+  const reference = record((await json(`repos/${repository}/git/ref/tags/${tag}`)).object);
+  if (reference.type !== "tag" || typeof reference.sha !== "string" || !/^[a-f0-9]{40}$/u.test(reference.sha)) {
+    throw new Error("SlopCamera updates require an annotated release tag.");
+  }
+  const annotated = await json(`repos/${repository}/git/tags/${reference.sha}`);
+  const source = record(annotated.object);
+  if (annotated.tag !== tag || source.type !== "commit" || typeof source.sha !== "string" || !/^[a-f0-9]{40}$/u.test(source.sha)) {
+    throw new Error("SlopCamera release tag does not identify its source commit.");
+  }
+  const release = await json(`repos/${repository}/releases/tags/${tag}`);
+  if (release.tag_name !== tag || release.immutable !== true || !Array.isArray(release.assets)) {
+    throw new Error("SlopCamera release is not immutable.");
+  }
+  const bundles = release.assets.map(record).filter(asset => asset.name === "provenance.jsonl");
+  const bundle = bundles[0];
+  if (bundles.length !== 1 || bundle === undefined || bundle.state !== "uploaded"
+    || typeof bundle.id !== "number" || !Number.isSafeInteger(bundle.id) || bundle.id <= 0
+    || typeof bundle.size !== "number" || !Number.isSafeInteger(bundle.size) || bundle.size < 1 || bundle.size > maximumMetadataBytes
+    || typeof bundle.digest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(bundle.digest)) {
+    throw new Error("SlopCamera release lacks a checked provenance bundle.");
+  }
+  const bytes = await gh(["api", `repos/${repository}/releases/assets/${bundle.id}`, "--header", "Accept: application/octet-stream"]);
+  if (bytes.length !== bundle.size || `sha256:${createHash("sha256").update(bytes).digest("hex")}` !== bundle.digest) {
+    throw new Error("SlopCamera provenance bundle differs from the immutable release.");
+  }
+  const directory = await mkdtemp(join(tmpdir(), "slopcamera-update-verification-"));
+  try {
+    const path = join(directory, "provenance.jsonl");
+    await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
+    await gh(["attestation", "verify", artifact.path, "--repo", repository,
+      "--signer-workflow", `${repository}/.github/workflows/release.yml`,
+      "--signer-digest", source.sha, "--source-digest", source.sha,
+      "--source-ref", `refs/tags/${tag}`, "--deny-self-hosted-runners", "--bundle", path]);
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}

package/apps/desktop/cli/verbs.ts

@@ -21,6 +21,11 @@ export interface VerbRow {
 const row = (words: string, opClass: OpClass, summary: string): VerbRow => ({ path: words.split(" "), opClass, summary });
 
 export const CLI_VERBS: readonly VerbRow[] = [
+  row("update", "operate", "Install a verified newer CLI release"),
+  row("update check", "operate", "Check release availability and save the check time"),
+  row("update status", "read", "Show installation support and update preferences"),
+  row("update enable", "operate", "Enable automatic CLI updates"),
+  row("update disable", "operate", "Keep the installed CLI version"),
   row("capabilities", "read", "List what this build can do and how well each part is tested"),
   row("doctor", "read", "Check local render tools, asset caches and old login items"),
   row("operations list", "read", "List the operations agents can run and their limits"),