@hraness/slopcamera 3.4.0 → 3.5.0

package/README.md

@@ -1,16 +1,18 @@
 # Slopcamera
 
-[![Slopcamera: a visual studio for coding agents](https://slopcamera.com/og.png)](https://slopcamera.com)
+[![Slopcamera: Visual work your agent can keep revising.](https://slopcamera.com/og.png)](https://slopcamera.com)
 
-**Slopcamera (formerly Atet) is a local visual studio for coding agents. Author scenes, combine
-generated and recorded media, and export images, diagrams, animation, and video
-from retained sources.**
+**Slopcamera is a media studio for coding agents. Codex, Claude Code, and other
+agents make images, diagrams, animation, 3D scenes, and edited video from source
+files they can keep revising.**
 
-Describe a finished result to Codex, Claude, or another coding agent. Slopcamera gives
-it a Bun CLI, TypeScript SDK, and version-matched Agent Skill to inspect sources,
-direct cameras, edit a composition, and render the result. A separate MCP server
-exposes fixed tools for diagrams, images, and scene inspection and planning. There is no Slopcamera account or hosted
-project database.
+Describe the result you want to Codex, Claude Code, or another coding agent.
+Slopcamera gives the agent a Bun CLI, a TypeScript SDK, and an Agent Skill matched
+to the CLI version, so it can inspect sources, set up cameras, edit a composition,
+and render. `slopcamera mcp` runs an MCP server with a smaller, fixed set of diagram,
+image, and scene tools. Projects stay in local files, and there is no Slopcamera
+account. Generation uses your own Vercel AI Gateway account or, for prompt-only
+images, prepaid Hraness Credits.
 
 [Install](#install-slopcamera) · [Make a first diagram](#make-your-first-diagram) · [Capabilities](#what-slopcamera-does) · [Documentation](https://slopcamera.com/docs) · [slopcamera.com](https://slopcamera.com)
 
@@ -38,20 +40,21 @@ the rendered output with source, runtime requirements and reproduction steps.
   timing, framing, captions, and effects as project decisions. Preview and final
   renders use the same timeline and composition.
 - **Choose where computation happens.** Local rendering and editing use your
-  machine. Optional model-backed work uses your Vercel AI Gateway access, with
-  explicit acknowledgement before named local media is uploaded. Native Python
+  machine. Optional model-backed work uses your Vercel AI Gateway access and
+  uploads named local media only after you acknowledge it. Prompt-only images can
+  instead run on the hosted API with prepaid Hraness Credits. Native Python
   authoring requires separate trust because it runs as your current user.
 
 ## Install Slopcamera
 
-Slopcamera v3.3.6 fixes `credits wait` dropping the issued device token on pickup, on top of v3.3.5's paid hosted image generation through Hraness Credits top-up (`slopcamera credits`, `ai image --hosted`), public hosted model discovery, and checked patent-style vector drawing sheets.
+Slopcamera v3.4.0 includes 17 reusable film and animation direction profiles, deterministic exposure helpers, and a sample renderer that defaults to native 4K. Use the [style direction guide](docs/how-to/direct-visual-styles.md) to author cel animation, pixel art, mathematical explanations, and historical film treatments from retained sources.
 
 Install [Bun 1.3.14 or newer](https://bun.sh), then install the verified
-[Slopcamera v3.3.6 release](https://github.com/hraness/slopcamera/releases/tag/v3.3.6)
+[Slopcamera v3.4.0 release](https://github.com/hraness/slopcamera/releases/tag/v3.4.0)
 from its canonical archive:
 
 ```sh
-bun add --global https://github.com/hraness/slopcamera/releases/download/v3.3.6/hraness-slopcamera-3.3.6.tgz
+bun add --global https://github.com/hraness/slopcamera/releases/download/v3.4.0/hraness-slopcamera-3.4.0.tgz
 slopcamera skill install --target agents
 ```
 
@@ -134,7 +137,8 @@ architecture from dimensions, [build a parametric design](https://slopcamera.com
 
 ## What Slopcamera does
 
-Slopcamera is a local visual studio for coding agents.
+Slopcamera lets your coding agent make images, diagrams, animation, 3D scenes,
+and video from source files it can keep revising.
 
 ### Author scenes and direct cameras
 
@@ -153,7 +157,7 @@ rigged/morph profile in v3.3.1 admits bounded skins and morph targets. Saved spl
 capture appearance; they do not establish collision geometry or editable native
 meshes. See [Directed scenes](docs/spatial-scenes.md).
 
-Slopcamera v3.3.1 includes the cinematic planning loop: a `slopcamera.spatial-direction`
+Slopcamera v3.3.1 introduced the cinematic planning loop: a `slopcamera.spatial-direction`
 document describes beats, actions, camera coverage, and look intents, compiles
 into proposed performance/camera/cinema/material-lighting/shot documents, and
 fans out into bounded galleries per axis. Declared effects bind into renders,
@@ -308,7 +312,7 @@ declarative graphs, approvals, and resuming work.
   workflows run with the current user's access. Hashes and receipts identify
   observed inputs and outputs; they do not make arbitrary code hermetic.
 - **MCP is a subset.** Its 17 fixed tools check and render diagrams, plan and audit
-  scenes, and run six bounded portable operation codes in v3.3.1. It does not
+  scenes, and run six bounded operation codes. It does not
   expose every local CLI operation and never mutates project state.
 
 ## Design and trust
@@ -333,6 +337,14 @@ source identity alone does not promise identical pixels on another machine.
 See [Architecture](docs/architecture.md), [`SECURITY.md`](SECURITY.md),
 [`PRIVACY.md`](PRIVACY.md), and [`NOTICE.md`](NOTICE.md) for the detailed boundaries.
 
+Your agent renders images, diagrams, scenes, animation, and video from source
+files you keep, and important operations record their inputs and outputs in
+receipts, so a rendered result arrives with the record of how it was made: the
+design every Hraness project shares. [The thread through
+hraness](https://hraness.com/writing/the-thread-through-hraness) follows that
+design across the projects, and the [ALGAL
+vision](https://algal.computer/docs/vision/) states the bet behind it.
+
 ## Documentation
 
 - **Learn:** [Your first diagram](docs/tutorials/first-diagram.md) · [Your first native film](docs/tutorials/first-native-film.md).

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.4.0" as const;
+export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.5.0" as const;
 
 export const OPERATION_KINDS = [
   "scene.audit",

package/apps/desktop/cli/args.ts

@@ -3659,7 +3659,7 @@ export function parseCliArgs(argv: readonly string[]): CliCommand {
     case "menubar": {
       const parsed = parseOptions(argv.slice(1), { ...JSON_SPEC, "--foreground": "flag", "--background": "flag" });
       const positionals = parsed.positionals;
-      if (positionals.length > 1 || (positionals[0] !== undefined && !["install", "uninstall", "status"].includes(positionals[0]))) throw new CliError("usage", "Use slopcamera menubar [--foreground|--background] | install|uninstall|status");
+      if (positionals.length > 1 || (positionals[0] !== undefined && !["install", "uninstall", "status"].includes(positionals[0]))) throw new CliError("usage", "Use slopcamera menubar [--foreground|--background] or slopcamera menubar install|uninstall|status. See slopcamera help menubar.");
       if (positionals[0] !== undefined && (optionFlag(parsed, "--foreground") || optionFlag(parsed, "--background"))) throw new CliError("usage", "Choose a menu-bar action or a run mode, not both.");
       return { kind: "menubar", action: (positionals[0] as "install" | "uninstall" | "status" | undefined) ?? "run", mode: optionFlag(parsed, "--background") ? "background" : "foreground", json: optionFlag(parsed, "--json") };
     }

package/apps/desktop/cli/commands.ts

@@ -362,7 +362,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.4.0";
+export const SLOPCAMERA_VERSION = "3.5.0";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one
@@ -739,6 +739,13 @@ function humanTime(microseconds: number): string {
 
 function requireCapability(capabilities: readonly Capability[], name: Capability["name"]): string {
   const capability = capabilityByName(capabilities, name);
+  if ((!capability.available || capability.command === undefined) && name === "face-analyzer") {
+    throw new CliError(
+      "unavailable",
+      "Face analysis needs a small helper that isn't built on this Mac yet. In a Slopcamera checkout, run bun run build:desktop:analysis:macos; it uses Apple's command line tools and asks before installing them.",
+      { capability: name, ...(capability.reason === undefined ? {} : { reason: capability.reason }) },
+    );
+  }
   if (!capability.available || capability.command === undefined) {
     throw new CliError(
       "unavailable",

package/apps/desktop/cli/help.ts

@@ -3,13 +3,13 @@ import { HTML_OVERLAY_SCAFFOLD_KINDS } from "../html-overlay";
 const HTML_OVERLAY_SCAFFOLD_KIND_HELP =
   HTML_OVERLAY_SCAFFOLD_KINDS.join("|");
 
-const GLOBAL_HELP = `slopcamera — creative scenes and non-destructive media editing for coding agents
+const GLOBAL_HELP = `slopcamera: a media studio for coding agents
 
 Usage: slopcamera <command> [options]
 
 Commands:
-  capabilities                   Discover the exact static capability modules and qualification status
-  operations list|show           Discover host-owned typed operations and policies
+  capabilities                   List what this build can do and how well each part is tested
+  operations list|show           List the operations agents can run and their limits
   diagram init|check|render      Create, validate, or render portable diagram sources
   diagram sheets init|check|render
                                  Create and render black-and-white drawing sheets
@@ -35,8 +35,9 @@ Commands:
   credits status|topup|wait|forget
                                  Buy and inspect hosted generation credits
   media audio|color              Apply local non-destructive audio and video effects
-  menubar [--background]         Run the prebuilt menu-bar companion
-  menubar install|uninstall|status  Manage its per-user LaunchAgent
+  menubar [--foreground|--background]
+                                 Show your outputs in the menu bar
+  menubar install|uninstall|status  Open it at login, stop that, or check it
   support [--json|protocol --json|offer --json|shown <id>|release <id>|dismiss|snooze|enable|status --json]
                                  Optional support; no feature requires payment
   outputs                        Print the agent outputs directory
@@ -55,13 +56,36 @@ Commands:
   render plan|run <recording>    Resolve or execute a render plan
   assets emoji search|resolve    Find checked local emoji overlays
 
-Agents: after useful work, read slopcamera support protocol --json for the optional
-closeout protocol. Discovery uses stderr; it does not claim an invitation.
-HRANESS_SUPPORT_AUDIENCE=off suppresses offers and incidental discovery.
+Examples:
+  slopcamera doctor                          Check what this Mac can render
+  slopcamera html scaffold plain --output intro.html
+                                             Start an HTML scene
+  slopcamera render run REC --output out.mp4  Render a recording
 
-Run slopcamera help <command> for command-specific help.`;
+Run slopcamera help <command> for command-specific help.
+Optional support: slopcamera support · Turn off: HRANESS_SUPPORT_AUDIENCE=off`;
 
 const HELP: Readonly<Record<string, string>> = {
+  menubar: `Usage:
+  slopcamera menubar [--foreground|--background] [--json]
+  slopcamera menubar install|uninstall|status [--json]
+
+Shows 📷 in the menu bar with your recent outputs. It only lists and opens
+files in the outputs folder (slopcamera outputs).
+
+  menubar               Open it now; it closes when this command ends
+  menubar --background  Open it now and return
+  menubar install       Open it now and every time you log in
+  menubar uninstall     Stop opening it at login and remove the installed copy
+  menubar status        Check whether it opens at login and is running
+
+If it's already in your menu bar, starting it again says so and succeeds.
+macOS shows a notice that slopcamera-menubar can open at login. Turn it off any
+time in System Settings › General › Login Items & Extensions.
+
+The menu bar isn't in released packages yet. In a Slopcamera checkout, build it
+with cargo build --release --manifest-path desktop/Cargo.toml and slopcamera
+finds it; elsewhere, set SLOPCAMERA_MENUBAR to the built file.`,
   capabilities: `Usage: slopcamera capabilities [--json]
 
 Print the exact statically assembled capability manifest for this CLI build. Each module owns named operation, workflow, MCP-tool, command, and runtime-profile identities. The manifest includes trust classes, resource/effect policies, runtime requirements, qualification status, and a canonical SHA-256. It reads no workspace source, loads no plugin, probes no runtime, and grants no authority. Use doctor separately to inspect this machine's currently available executables.`,

package/apps/desktop/cli/menubar.ts

@@ -208,33 +208,109 @@ export function uninstallLaunchAgent(_binary: string, environment: Environment =
   if (infoAt(stable) !== null) rmSync(stable);
   return "absent";
 }
-async function runBinary(binary: string, foreground: boolean): Promise<number> {
+/** `slopcamera-menubar` exits with this code when another copy already holds the menu bar. */
+export const ALREADY_RUNNING_EXIT = 3;
+const NOT_BUILT = "The Slopcamera menu bar isn't in this release yet. Build it with cargo build --release --manifest-path desktop/Cargo.toml in a Slopcamera checkout; slopcamera finds it there, or set SLOPCAMERA_MENUBAR to the built file.";
+const LOGIN_ITEMS = "System Settings › General › Login Items & Extensions";
+
+export type Launched = "running" | "already-running" | "exited";
+export type BinaryRunner = (binary: string, foreground: boolean) => Promise<number | null>;
+
+/** Resolves the exit code, or null when a background copy is still running after startup. */
+async function spawnBinary(binary: string, foreground: boolean): Promise<number | null> {
   let child: Bun.Subprocess;
-  try { child = Bun.spawn([binary], foreground ? { stdin: "inherit", stdout: "inherit", stderr: "inherit" } : { stdin: "ignore", stdout: "ignore", stderr: "ignore" }); } catch { throw new CliError("unavailable", "The Slopcamera menu bar could not start."); }
-  if (!foreground) { child.unref(); const settled = await Promise.race([child.exited.then((code) => code as number | null), Bun.sleep(SETTLE_MS).then(() => null)]); if (settled !== null) throw new CliError("unavailable", "The Slopcamera menu bar exited during startup."); return 0; }
+  try { child = Bun.spawn([binary], foreground ? { stdin: "inherit", stdout: "inherit", stderr: "inherit" } : { stdin: "ignore", stdout: "ignore", stderr: "ignore" }); } catch { throw new CliError("unavailable", "The Slopcamera menu bar couldn't start."); }
+  if (!foreground) { child.unref(); return await Promise.race([child.exited.then((code) => code as number | null), Bun.sleep(SETTLE_MS).then(() => null)]); }
   return await child.exited;
 }
-export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: boolean, mode: "foreground" | "background" = "foreground"): Promise<void> {
+
+/** Interprets the companion's exit: another running copy is success, not a failure. */
+export function launchOutcome(code: number | null, foreground: boolean): Launched {
+  if (code === ALREADY_RUNNING_EXIT) return "already-running";
+  if (code === null && !foreground) return "running";
+  if (code === 0 && foreground) return "exited";
+  throw new CliError("unavailable", "The Slopcamera menu bar stopped while starting. Run it in the foreground to see why: slopcamera menubar --foreground");
+}
+
+interface Marks { readonly ok: string; readonly warn: string; readonly note: string; readonly next: string }
+/** ✓ ⚠ 🔐 → with ASCII fallbacks for dumb terminals and non-UTF-8 locales. */
+export function marks(env: Readonly<Record<string, string | undefined>>): Marks {
+  const utf8 = [env.LC_ALL, env.LC_CTYPE, env.LANG].some((value) => value !== undefined && /utf-?8/i.test(value));
+  const ascii = env.TERM === "dumb" || !utf8 || env.HRANESS_ASCII === "1";
+  return ascii ? { ok: "OK", warn: "WARN", note: "NOTE", next: "->" } : { ok: "✓", warn: "⚠", note: "🔐", next: "→" };
+}
+
+/** The LOGIN_ITEM notice (notifies, so there is no confirm line). The requester is the bare companion until Slopcamera ships as an app. */
+export function loginItemNotice(env: Readonly<Record<string, string | undefined>>): string {
+  return `${marks(env).note} macOS will show a notice that slopcamera-menubar can open at login. That's Slopcamera's menu bar.\n   It lists your outputs and opens when you log in. Nothing else runs in the background. Turn it off any time in ${LOGIN_ITEMS}.\n`;
+}
+
+export function launchMessage(outcome: Launched, env: Readonly<Record<string, string | undefined>>): string {
+  const mark = marks(env);
+  if (outcome === "already-running") return `${mark.ok} Slopcamera is already in your menu bar. Look for 📷.`;
+  if (outcome === "running") return `${mark.ok} Slopcamera is in your menu bar. Look for 📷.`;
+  return "The Slopcamera menu bar closed.";
+}
+
+export function stateMessage(action: "install" | "uninstall" | "status", state: LaunchAgentState, running: boolean, env: Readonly<Record<string, string | undefined>>): string {
+  const mark = marks(env);
+  if (state === "conflict") return `${mark.warn} Another menu-bar setup that this command didn't create is in the way. It was left untouched.\n  Remove ~/Library/LaunchAgents/${LABEL}.plist yourself if you don't need it.`;
+  if (state === "absent") return action === "uninstall" ? `${mark.ok} Slopcamera no longer opens in your menu bar at login.` : `Slopcamera doesn't open at login.\n${mark.next} slopcamera menubar install`;
+  if (action === "install") return `${mark.ok} Slopcamera opens in your menu bar now and at every login. Look for 📷.\n  Remove it any time: slopcamera menubar uninstall`;
+  return running
+    ? `${mark.ok} Slopcamera opens at login and is in your menu bar now.`
+    : `${mark.warn} Slopcamera is set to open at login but isn't running. It may be turned off in ${LOGIN_ITEMS}.\n${mark.next} slopcamera menubar install`;
+}
+
+/** Whether launchd reports the loaded companion as running. Reads state only. */
+export function serviceRunning(runLaunchctl: LaunchctlRunner): boolean {
+  const output = runLaunchctl(["print", `gui/{uid}/${LABEL}`], true);
+  return output !== null && output.split("\n").some((line) => line.trim() === "state = running");
+}
+
+export type ProcessProbe = () => boolean;
+/** Whether any copy of the companion runs for this user, including one started by hand. */
+function companionProcessRunning(): boolean {
+  const uid = process.getuid?.();
+  if (uid === undefined) return false;
+  try {
+    return Bun.spawnSync(["/usr/bin/pgrep", "-x", "-U", String(uid), "slopcamera-menubar"], { stdin: "ignore", stdout: "ignore", stderr: "ignore", timeout: 5_000 }).exitCode === 0;
+  } catch { return false; }
+}
+
+/** The menu bar is showing when launchd runs the login item or another copy holds it. */
+async function menubarShowing(runLaunchctl: LaunchctlRunner, probe: ProcessProbe, waitMs: number): Promise<boolean> {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    if (serviceRunning(runLaunchctl) || probe()) return true;
+    if (Date.now() >= deadline) return false;
+    await Bun.sleep(200);
+  }
+}
+
+export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: boolean, mode: "foreground" | "background" = "foreground", runBinary: BinaryRunner = spawnBinary): Promise<void> {
   const binary = resolveMenubarBinary(repositoryRoot, io.env);
-  if (binary === null) throw new CliError("unavailable", "The Slopcamera menu bar is not installed. Build it separately or set SLOPCAMERA_MENUBAR.");
-  const code = await runBinary(binary, mode === "foreground");
-  if (code !== 0) throw new CliError("unavailable", "The Slopcamera menu bar exited during startup.");
-  if (asJson) writeJson(io, { running: mode === "background", foreground: mode === "foreground" });
-  else writeLine(io, mode === "foreground" ? "Slopcamera menu bar exited." : "Slopcamera menu bar is running.");
+  if (binary === null) throw new CliError("unavailable", NOT_BUILT);
+  const outcome = launchOutcome(await runBinary(binary, mode === "foreground"), mode === "foreground");
+  if (asJson) writeJson(io, { running: outcome !== "exited", foreground: mode === "foreground", alreadyRunning: outcome === "already-running" });
+  else writeLine(io, launchMessage(outcome, io.env));
 }
-export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean): Promise<void> {
+export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean, runLaunchctl: LaunchctlRunner = launchctl, probe: ProcessProbe = companionProcessRunning): Promise<void> {
   assertMac(io.platform);
   const stable = installedBinaryPath(io.env);
   let state: LaunchAgentState;
   if (action === "install") {
     const binary = resolveMenubarBinary(repositoryRoot, io.env);
-    if (binary === null) throw new CliError("unavailable", "The Slopcamera menu bar is not installed. Build it separately or set SLOPCAMERA_MENUBAR.");
-    state = installLaunchAgent(binary, io.env, io.platform);
+    if (binary === null) throw new CliError("unavailable", NOT_BUILT);
+    if (!asJson) io.stderr(loginItemNotice(io.env));
+    state = installLaunchAgent(binary, io.env, io.platform, runLaunchctl);
   } else {
-    state = action === "uninstall" ? uninstallLaunchAgent(stable, io.env, io.platform) : launchAgentState(stable, io.env);
+    state = action === "uninstall" ? uninstallLaunchAgent(stable, io.env, io.platform, runLaunchctl) : launchAgentState(stable, io.env);
   }
-  if (asJson) writeJson(io, { launchAgent: state });
-  else writeLine(io, `Slopcamera menu-bar LaunchAgent: ${state}.`);
+  // A fresh login item may take a moment to start, so install waits briefly.
+  const running = state === "installed" && await menubarShowing(runLaunchctl, probe, action === "install" ? 1_000 : 0);
+  if (asJson) writeJson(io, { launchAgent: state, running });
+  else writeLine(io, stateMessage(action, state, running, io.env));
 }
 export async function reportOutputsRoot(io: CliIo, stateRoot: string, asJson: boolean): Promise<void> {
   const directory = outputsRoot(stateRoot);