@hraness/slopcamera 3.4.0 → 3.6.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.5.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. On macOS, `slopcamera menubar` puts Slopcamera in the menu bar and explains each macOS notice before it appears.
 
 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.5.0 release](https://github.com/hraness/slopcamera/releases/tag/v3.5.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.5.0/hraness-slopcamera-3.5.0.tgz
 slopcamera skill install --target agents
 ```
 
@@ -87,8 +90,9 @@ Native engines install separately. The [source-install guide](docs/how-to/use-cu
 explains workspace placement and durable-run identity; the
 [capability reference](docs/reference/capabilities.md) names runtime requirements.
 
-Slopcamera is a CLI. On macOS, an optional unbundled menu-bar companion can show
-the files in the agent outputs directory; `slopcamera menubar` runs a prebuilt
+Slopcamera is a CLI. On macOS, an optional unbundled menu-bar companion shows
+what Slopcamera is rendering, how the last job ended, your last known credits
+balance and the newest files in the agent outputs directory; `slopcamera menubar` runs a prebuilt
 companion directly and does not install or launch an application bundle. The
 companion is a thin product binary over the shared
 [desktop-foundation](https://github.com/hraness/desktop-foundation) crate, pinned
@@ -134,7 +138,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 +158,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 +313,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 +338,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.6.0" as const;
 
 export const OPERATION_KINDS = [
   "scene.audit",

package/apps/desktop/cli/args.ts

@@ -3659,8 +3659,10 @@ 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", "start"].includes(positionals[0]))) throw new CliError("usage", "Use slopcamera menubar [--foreground|--background] or slopcamera menubar install|uninstall|status|start. 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.");
+      // `start` opens it now and returns, like --background; the login item's hints use it.
+      if (positionals[0] === "start") return { kind: "menubar", action: "run", mode: "background", json: optionFlag(parsed, "--json") };
       return { kind: "menubar", action: (positionals[0] as "install" | "uninstall" | "status" | undefined) ?? "run", mode: optionFlag(parsed, "--background") ? "background" : "foreground", json: optionFlag(parsed, "--json") };
     }
     case "outputs": {

package/apps/desktop/cli/commands.ts

@@ -1,3 +1,4 @@
+import { activityLabel, recordActivity, recordCredits } from "./menubar-status";
 import { reportUsefulResult, type UsefulResultObserver } from "../../../src/support-completion";
 import { SlopcameraCloudError } from "../../../src/cloud-errors";
 import {
@@ -362,7 +363,7 @@ import {
   workflowRunStore,
 } from "./workflow-runs";
 
-export const SLOPCAMERA_VERSION = "3.4.0";
+export const SLOPCAMERA_VERSION = "3.6.0";
 
 // Legacy direct renders predate per-target output contracts. Keep them
 // bounded generously enough for long-form production while preventing one
@@ -739,6 +740,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",
@@ -5541,6 +5549,7 @@ async function handleCreditsStatus(
   } catch (error) {
     throw creditsErrorToCli(error);
   }
+  recordCredits(context.stateRoot, { usd: balance.balance.usd, low: balance.lowBalance, checkedAt: context.clock() });
   const view = {
     configured: true,
     tokenSource: loaded.source,
@@ -8412,6 +8421,7 @@ async function resolveMutationTarget(
 export async function runCli(argv: readonly string[], dependencies: CliDependencies = {}): Promise<number> {
   const io = dependencies.io ?? processIo;
   let jsonRequested = argv.includes("--json") || argv.includes("--jsonl");
+  let activity: { readonly stateRoot: string; readonly label: string; readonly startedAt: number } | undefined;
   try {
     const command = parseCliArgs(argv);
     jsonRequested = "json" in command ? command.json : command.kind === "events" && command.format !== "human";
@@ -8506,6 +8516,11 @@ export async function runCli(argv: readonly string[], dependencies: CliDependenc
         ? {}
         : { renderGalleryScene: dependencies.renderGalleryScene }),
     };
+    const label = activityLabel(command);
+    if (label !== undefined) {
+      activity = { stateRoot, label, startedAt: context.clock() };
+      recordActivity(stateRoot, { state: "running", label, startedAt: activity.startedAt });
+    }
     const mutationTarget = await resolveMutationTarget(paths, stateRoot, command);
     await withCommandHostResources(context, command, async admittedContext => {
       if (mutationTarget === undefined) {
@@ -8528,9 +8543,15 @@ export async function runCli(argv: readonly string[], dependencies: CliDependenc
       || command.kind === "project-render" && command.action === "run" && !command.dryRun) {
       reportUsefulResult(dependencies.onUsefulResult);
     }
+    if (activity !== undefined) {
+      recordActivity(activity.stateRoot, { state: "done", label: activity.label, startedAt: activity.startedAt, finishedAt: io.now().getTime() });
+    }
     return 0;
   } catch (error) {
     const failure = asCliError(error);
+    if (activity !== undefined) {
+      recordActivity(activity.stateRoot, { state: "failed", label: activity.label, startedAt: activity.startedAt, finishedAt: io.now().getTime(), error: failure.code });
+    }
     const payload = {
       error: {
         code: failure.code,

package/apps/desktop/cli/help.ts

@@ -1,15 +1,17 @@
+import { slopcameraSupportAdvancedHelp, slopcameraSupportHelpLine } from "../../../src/support";
+
 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 globalHelp = () => `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,10 +37,6 @@ 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
-  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
   recordings list               List recording bundles
   projects list|create           List projects or create one from a recording
@@ -55,13 +53,39 @@ 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.
+${slopcameraSupportHelpLine()}`;
 
 const HELP: Readonly<Record<string, string>> = {
+  advanced: `${slopcameraSupportAdvancedHelp()}`,
+  menubar: `Usage:
+  slopcamera menubar [--foreground|--background] [--json]
+  slopcamera menubar install|uninstall|status|start [--json]
+
+Shows what Slopcamera is doing in the menu bar: a render in progress, how the
+last job ended and your last known credits balance, plus your newest outputs.
+It only reads that status and the outputs folder (slopcamera outputs).
+
+  menubar               Open it now; it closes when this command ends
+  menubar start         Open it now and return (same as --background)
+  menubar install       Open it 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, so it isn't listed in
+slopcamera help. 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.`,
@@ -677,8 +701,8 @@ Long inactivity is analyzed and removed by default; use --keep-inactivity to opt
 };
 
 export function commandHelp(topic: readonly string[]): string {
-  if (topic.length === 0) return GLOBAL_HELP;
-  return HELP[topic[0]!] ?? GLOBAL_HELP;
+  if (topic.length === 0) return globalHelp();
+  return HELP[topic[0]!] ?? globalHelp();
 }
 
 export function completions(words: readonly string[]): readonly string[] {

package/apps/desktop/cli/menubar-status.ts

@@ -0,0 +1,155 @@
+import { chmodSync, lstatSync, openSync, closeSync, readFileSync, renameSync, rmSync, writeSync, constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+import type { CliCommand } from "./args";
+
+/**
+ * The small status file the menu bar reads: what Slopcamera is doing now,
+ * how the last render ended, and the last credits balance a command saw.
+ * It holds plain labels, times and fixed error codes only — never paths,
+ * prompts, tokens or account identifiers. Writes are best effort: a status
+ * that can't be saved never fails the command.
+ */
+export const MENUBAR_STATUS_FILE = "menubar-status.json";
+const MAX_STATUS_BYTES = 16 * 1024;
+
+export type ActivityState = "running" | "done" | "failed";
+
+export interface MenubarActivity {
+  readonly state: ActivityState;
+  readonly label: string;
+  readonly startedAt: number;
+  readonly finishedAt?: number;
+  readonly error?: string;
+}
+
+export interface MenubarCredits {
+  readonly usd: string;
+  readonly low: boolean;
+  readonly checkedAt: number;
+}
+
+export interface MenubarStatus {
+  readonly schemaVersion: 1;
+  readonly activity?: MenubarActivity;
+  readonly credits?: MenubarCredits;
+}
+
+/** Plain labels for the commands that make media. Everything else leaves the status alone. */
+export function activityLabel(command: CliCommand): string | undefined {
+  switch (command.kind) {
+    case "render-run": return command.dryRun ? undefined : "Rendering a recording";
+    case "project-render": return command.action === "run" && !command.dryRun ? "Rendering a project" : undefined;
+    case "project-cinema": return "Rendering a project";
+    case "html-render": return "Rendering an HTML scene";
+    case "diagram-render": return "Rendering a diagram";
+    case "image-vectorize": return "Vectorizing an image";
+    case "ai-image-generate": return "Generating an image";
+    case "ai-video-generate": return "Generating a video";
+    case "ai-speech-generate": return "Generating speech";
+    case "directing": return "Directing a clip";
+    case "studio": return "Running a studio job";
+    case "spatial-scene": return command.action === "render" ? "Rendering a 3D scene" : undefined;
+    case "workflows-run": return "Running a workflow";
+    case "code-run": return "Running a workflow";
+    default: return undefined;
+  }
+}
+
+function parse(text: string): MenubarStatus {
+  try {
+    const value: unknown = JSON.parse(text);
+    if (typeof value !== "object" || value === null || (value as { schemaVersion?: unknown }).schemaVersion !== 1) return { schemaVersion: 1 };
+    const record = value as Record<string, unknown>;
+    const activity = record.activity as MenubarActivity | undefined;
+    const credits = record.credits as MenubarCredits | undefined;
+    return {
+      schemaVersion: 1,
+      ...(activity !== undefined && typeof activity === "object" && typeof activity.label === "string" ? { activity } : {}),
+      ...(credits !== undefined && typeof credits === "object" && typeof credits.usd === "string" ? { credits } : {}),
+    };
+  } catch {
+    return { schemaVersion: 1 };
+  }
+}
+
+export function readMenubarStatus(stateRoot: string): MenubarStatus {
+  const path = join(stateRoot, MENUBAR_STATUS_FILE);
+  try {
+    const info = lstatSync(path);
+    if (!info.isFile() || info.size > MAX_STATUS_BYTES) return { schemaVersion: 1 };
+    return parse(readFileSync(path, "utf8"));
+  } catch {
+    return { schemaVersion: 1 };
+  }
+}
+
+const LOCK_FILE = `.${MENUBAR_STATUS_FILE}.lock`;
+/** A held lock blocks a write for this long before it is skipped. */
+const LOCK_BUDGET_MS = 250;
+/** A lock older than this is a crashed writer's and is reclaimed. */
+const LOCK_STALE_MS = 10_000;
+
+function sleepSync(ms: number): void {
+  Bun.sleepSync(ms);
+}
+
+/**
+ * Runs `update` holding a small exclusive lock file, so a render finishing
+ * while `credits status` runs cannot overwrite the other slot. Returns
+ * undefined when the lock never comes free; the write is then skipped
+ * rather than lost-halfway.
+ */
+function withStatusLock<T>(stateRoot: string, update: () => T): T | undefined {
+  const lock = join(stateRoot, LOCK_FILE);
+  const deadline = Date.now() + LOCK_BUDGET_MS;
+  for (;;) {
+    let fd: number;
+    try {
+      fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") return undefined;
+      try {
+        if (Date.now() - lstatSync(lock).mtimeMs > LOCK_STALE_MS) rmSync(lock, { force: true });
+      } catch { /* races with the lock holder */ }
+      if (Date.now() >= deadline) return undefined;
+      sleepSync(5);
+      continue;
+    }
+    closeSync(fd);
+    try {
+      return update();
+    } finally {
+      try { rmSync(lock, { force: true }); } catch { /* best effort */ }
+    }
+  }
+}
+
+/** Replaces the status file atomically with an owner-only file. Never throws. */
+export function writeMenubarStatus(stateRoot: string, update: (current: MenubarStatus) => MenubarStatus): void {
+  withStatusLock(stateRoot, () => {
+    const path = join(stateRoot, MENUBAR_STATUS_FILE);
+    const staged = join(stateRoot, `.${MENUBAR_STATUS_FILE}.${randomUUID()}.tmp`);
+    try {
+      const root = lstatSync(stateRoot);
+      if (!root.isDirectory()) return;
+      const text = `${JSON.stringify(update(readMenubarStatus(stateRoot)))}\n`;
+      if (Buffer.byteLength(text) > MAX_STATUS_BYTES) return;
+      const fd = openSync(staged, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      try { writeSync(fd, text); } finally { closeSync(fd); }
+      chmodSync(staged, 0o600);
+      renameSync(staged, path);
+    } catch {
+      try { rmSync(staged, { force: true }); } catch { /* best effort */ }
+    }
+  });
+}
+
+export function recordActivity(stateRoot: string, activity: MenubarActivity): void {
+  writeMenubarStatus(stateRoot, (current) => ({ ...current, activity }));
+}
+
+export function recordCredits(stateRoot: string, credits: MenubarCredits): void {
+  writeMenubarStatus(stateRoot, (current) => ({ ...current, credits }));
+}