@hraness/slopcamera 3.8.1 → 3.9.1

package/skills/slopcamera/references/icon-place.md

@@ -0,0 +1,76 @@
+# Compose and render vector icon scenes
+
+Use this workflow when the user wants a deterministic vector icon, a small
+composed scene of icons, or a drawn construction program, without a model or a
+network request. Slopcamera bundles the icon.place library at one exact version
+for this. For a generated product mark or topic icon from a text brief, use
+[brand illustrations](brand-illustrations.md) instead.
+
+## Pick a source
+
+Both commands read one local JSON file of at most 1 MiB. The kind is detected
+from its content:
+
+- A **scene**: up to eight placed icons with a canvas and a background.
+- A **collection**: up to six layered icons that compose into one scene.
+- A **construction program**: parts, operations and a drawing recipe that
+  compile to one drawing.
+- A **recipe** that an earlier render wrote. A recipe records the source, the
+  render settings and the output digests.
+
+Keep the source in the workspace as the authoritative file. The SVG is a
+replaceable derivative.
+
+## Compose
+
+`compose` parses and solves the source and reports its digests, element count
+and diagnostics. It writes nothing unless `--output` names a `.json` file for the
+canonical solved document:
+
+```sh
+slopcamera image icon compose icons/window.json --json
+slopcamera image icon compose icons/window.json --output icons/window.solved.json
+```
+
+Composing a solved document again gives the same digests. Report any
+diagnostics; they are the library's own layout findings.
+
+## Render
+
+`render` draws the source to an inert SVG. `--recipe` also writes a replayable
+recipe:
+
+```sh
+slopcamera image icon render icons/window.json --output icons/window.svg \
+  --recipe icons/window.recipe.json --size 256 --palette ink
+```
+
+- `--size` sets the output edge from 16 to 1024 pixels.
+- `--palette` (`original`, `ink`, `earth` or `night`) applies to scenes and
+  collections. `--background` paints the paper behind any source.
+- `--language` selects one of the drawing languages for a construction program,
+  such as `outline`, `woodcut` or `stipple`. `slopcamera help image` lists them.
+
+To reproduce an icon, render its recipe. A recipe fixes its own settings, so do
+not pass `--size`, `--palette`, `--background` or `--language` with it. Replay
+fails if the recipe was edited after it was written or if the drawing no longer
+matches the recorded digests; report that instead of re-rendering from scratch.
+
+The same renders are available as the `compose_icon` and `render_icon` MCP
+tools with root-relative paths, and as the `slopcamera.icon.compose` and
+`slopcamera.icon.render` operations.
+
+## Checks
+
+- The output is a path-only SVG. Scripts, styles, images, event handlers,
+  external references and foreign content are rejected before anything is
+  written.
+- Source, output and recipe must be three different files. Existing outputs are
+  replaced atomically.
+- Receipts record the source digest, the solved and SVG digests, and the
+  library version. Keep the receipt when provenance matters.
+- Inspect the SVG at its intended size. A clean render is not evidence that
+  the icon communicates the intended idea.
+
+For diagram icons from a third-party icon package, keep using a local adapter as
+described in [customization](customization.md).

package/skills/slopcamera/references/install.md

@@ -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.8.0/hraness-slopcamera-3.8.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.9.0/hraness-slopcamera-3.9.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.8.0/hraness-slopcamera-3.8.0.tgz
+bun add --global @hraness/slopcamera@https://github.com/hraness/slopcamera/releases/download/v3.9.0/hraness-slopcamera-3.9.0.tgz
 slopcamera --version
 ```
 

package/skills/slopcamera/references/music-video.md

@@ -18,8 +18,16 @@ delivery. Keep the scene's deliberate style and original media intact.
 
 Use the user's selected track and supplied tempo. Establish an explicit duration,
 beat-zero offset, and beats per bar from the task or relevant audio inspection.
-The first version does not detect tempo, downbeats, or track duration. Do not
-replace explicit musical timing with an unsupported automatic-analysis claim.
+The first version does not detect tempo, downbeats, or track duration from
+audio. Do not replace explicit musical timing with an unsupported
+automatic-analysis claim.
+
+When the track was made from a Soundfish score or a MIDI file, derive the timing
+from that source instead with
+`slopcamera media soundtrack grid <score> --start-us <n> --json`. Its `music`
+object drops straight into `parameters.music` below, and its section cue times
+mark shot changes. See [soundtracks](soundtracks.md). Take `timing.durationUs`
+from the audio file itself.
 
 Check the installed command and host before preparing exact source:
 

package/skills/slopcamera/references/soundtracks.md

@@ -0,0 +1,58 @@
+# Derive a soundtrack beat grid
+
+Use this workflow when a music video or timed HTML scene has a Soundfish score
+or a Standard MIDI file, and the scene needs the track's tempo, meter and
+section cue times. Slopcamera bundles the Soundfish library at one exact version
+to read scores. It renders no audio: pair the grid with the audio file the user
+mixes or supplies.
+
+## Supported sources
+
+One local file of at most 1 MiB, detected from its content or set with
+`--format`:
+
+- `compose`: Soundfish compose text for one loop.
+- `song`: Soundfish song text with named sections.
+- `json`: a Soundfish loop or song document.
+- `midi`: a Standard MIDI file with one constant tempo and meter.
+
+To write or edit scores, install the `@hraness/soundfish` package and use its
+own agent skill. Slopcamera does not bundle that skill.
+
+## Verify a score
+
+```sh
+slopcamera media soundtrack compose music/hook.song --json
+slopcamera media soundtrack compose music/hook.song --output music/hook.json
+```
+
+`compose` parses and verifies the score and reports its canonical digest, kind
+(loop or song), tempo, beats per bar, bars and duration. `--output` writes the
+verified score document as `.json`. Report any warnings the receipt carries.
+
+## Derive the grid
+
+```sh
+slopcamera media soundtrack grid music/hook.song --start-us 500000 \
+  --output music/hook.grid.json --json
+```
+
+The receipt's `music` object is exactly the `{ "bpm", "beatOffsetUs",
+"beatsPerBar" }` shape an HTML scene request accepts under
+`parameters.music`. `--start-us` is the timeline microsecond where the first
+beat lands; it defaults to `0`. Each section carries its label, repeat, bars,
+beats and `startUs`/`endUs` cue times on the same timeline.
+
+- Cue times are whole microseconds and never drift more than half a microsecond
+  from the beat they name.
+- Sections tile the score from `beatOffsetUs` to `endUs` with no gaps.
+- The same score always yields the same digest and grid.
+
+Use the grid in [music videos](music-video.md): copy `music` into the scene
+request and use the section cues for shot changes. Set `timing.durationUs` from
+the audio file, not only from the grid, because a mixed track can have a
+different tail.
+
+The same reads are available as the `compose_soundtrack` and
+`derive_soundtrack_grid` MCP tools with root-relative paths, and as the
+`slopcamera.soundtrack.compose` and `slopcamera.soundtrack.grid` operations.

package/src/bounded-file.ts

@@ -0,0 +1,135 @@
+import { createHash, randomUUID } from "node:crypto"
+import { constants } from "node:fs"
+import { mkdir, open, rename, rm, stat } from "node:fs/promises"
+import { dirname, join, resolve } from "node:path"
+
+/**
+ * Bounded local file reads and atomic replaceable writes shared by the
+ * icon-scene and soundtrack operations. Reads check the size before and
+ * after reading so a growing file cannot exceed the declared bound.
+ */
+
+export class BoundedFileError extends Error {
+  readonly code: "SOURCE_NOT_FOUND" | "SOURCE_NOT_FILE" | "SOURCE_TOO_LARGE" | "SOURCE_UNREADABLE"
+
+  constructor(code: BoundedFileError["code"], message: string) {
+    super(message)
+    this.name = "BoundedFileError"
+    this.code = code
+  }
+}
+
+function errorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String((error as { readonly code: unknown }).code)
+    : undefined
+}
+
+export async function readBoundedFile(
+  path: string,
+  maximumBytes: number,
+  label: string,
+): Promise<Uint8Array> {
+  let handle
+  try {
+    // Non-blocking so a FIFO or device fails the regular-file check instead of hanging.
+    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      throw new BoundedFileError("SOURCE_NOT_FOUND", `${label} does not exist.`)
+    }
+    throw new BoundedFileError("SOURCE_UNREADABLE", `${label} could not be opened.`)
+  }
+  try {
+    const metadata = await handle.stat()
+    if (!metadata.isFile()) {
+      throw new BoundedFileError("SOURCE_NOT_FILE", `${label} must be a regular file.`)
+    }
+    if (metadata.size > maximumBytes) {
+      throw new BoundedFileError(
+        "SOURCE_TOO_LARGE",
+        `${label} exceeds the ${String(maximumBytes)}-byte limit.`,
+      )
+    }
+    // Read one byte past the bound so a file that grew after stat fails closed.
+    const buffer = new Uint8Array(maximumBytes + 1)
+    let length = 0
+    for (;;) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length)
+      if (bytesRead === 0) break
+      length += bytesRead
+      if (length > maximumBytes) {
+        throw new BoundedFileError(
+          "SOURCE_TOO_LARGE",
+          `${label} exceeds the ${String(maximumBytes)}-byte limit.`,
+        )
+      }
+    }
+    return buffer.slice(0, length)
+  } finally {
+    await handle.close()
+  }
+}
+
+export function decodeUtf8Source(bytes: Uint8Array, label: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes)
+  } catch {
+    throw new BoundedFileError("SOURCE_UNREADABLE", `${label} must be UTF-8 text.`)
+  }
+}
+
+export function sha256Hex(value: string | Uint8Array): string {
+  return createHash("sha256").update(value).digest("hex")
+}
+
+/** Replace `path` atomically with `value`, creating its parent directory. */
+export async function publishReplaceableFile(
+  path: string,
+  value: string | Uint8Array,
+): Promise<void> {
+  const directory = dirname(path)
+  await mkdir(directory, { recursive: true })
+  // A fixed-length name stays under NAME_MAX whatever the target's basename.
+  const temporaryPath = join(directory, `.slopcamera-${randomUUID()}.tmp`)
+  try {
+    const handle = await open(temporaryPath, "wx")
+    try {
+      await handle.writeFile(value)
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    await rename(temporaryPath, path)
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined)
+  }
+}
+
+/**
+ * True when two declared paths name the same file, such as an output that
+ * would replace its source. Equal resolved spellings collide; existing files
+ * also collide by device and inode, which catches links and case-insensitive
+ * spellings of one file.
+ */
+export async function hasPathCollision(paths: readonly (string | undefined)[]): Promise<boolean> {
+  const spellings = new Set<string>()
+  const identities = new Set<string>()
+  for (const path of paths) {
+    if (path === undefined) continue
+    const absolute = resolve(path)
+    if (spellings.has(absolute)) return true
+    spellings.add(absolute)
+    let identity: string
+    try {
+      const metadata = await stat(absolute, { bigint: true })
+      identity = `${String(metadata.dev)}:${String(metadata.ino)}`
+    } catch (error) {
+      if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR") continue
+      throw new BoundedFileError("SOURCE_UNREADABLE", "A declared path could not be inspected.")
+    }
+    if (identities.has(identity)) return true
+    identities.add(identity)
+  }
+  return false
+}

package/src/cli.ts

@@ -42,6 +42,12 @@ import {
   withSlopcameraOperationHostAdmission,
 } from "./operations.js"
 import type { HostResourceCoordinator } from "./host-resources.js"
+import {
+  slopcameraIconLanguages,
+  slopcameraIconPalettes,
+  slopcameraIconSceneLimits,
+} from "./icon-scene.js"
+import { slopcameraSoundtrackFormats } from "./soundtrack.js"
 import { installSkill, type SkillScope, type SkillTarget } from "./skill-install.js"
 import { pathExists } from "./fs.js"
 import { checkDrawingFile, renderDrawingFile, starterDrawingSource } from "./drawing.js"
@@ -75,6 +81,14 @@ Usage:
   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]
+  slopcamera image icon compose <source.json> [--output <file.json>] [--json]
+  slopcamera image icon render <source.json> --output <file.svg> [--recipe <file.json>]
+    [--size <${slopcameraIconSceneLimits.sizeMin}-${slopcameraIconSceneLimits.sizeMax}>] [--background] [--palette <${slopcameraIconPalettes.join("|")}>]
+    [--language <language>] [--json]
+  slopcamera media soundtrack compose <score> [--output <file.json>]
+    [--format <${slopcameraSoundtrackFormats.join("|")}>] [--json]
+  slopcamera media soundtrack grid <score> [--output <file.json>] [--start-us <n>]
+    [--format <${slopcameraSoundtrackFormats.join("|")}>] [--json]
   slopcamera style list [--json]
   slopcamera style show <id> [--json]
   slopcamera code search [query] [--limit <number>]
@@ -122,6 +136,16 @@ 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.
 
+Icon compose and render are local and deterministic: they solve and draw
+vector icon scenes, collections, construction programs, and recipes with the
+bundled icon.place library, emit inert SVG, and replay a recipe only when its
+recorded digests match. Languages: ${slopcameraIconLanguages.join(", ")}.
+
+Media soundtrack verifies a Soundfish loop or song (compose text, song text,
+score JSON, or a Standard MIDI file) and derives its beat grid as the
+{bpm, beatOffsetUs, beatsPerBar} music timing HTML scene requests accept, plus
+section cue times. It renders no audio and makes no network requests.
+
 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
@@ -365,6 +389,10 @@ function canonicalArguments(args: readonly string[]): readonly string[] {
     }
     throw new Error("Use slopcamera diagram init, check, render, or sheets")
   }
+  if (surface === "media") {
+    if (subcommand === "soundtrack") return ["soundtrack", ...rest]
+    throw new Error("Use slopcamera media soundtrack compose or grid")
+  }
   if (surface === "image") {
     if (
       subcommand === "vectorize" ||
@@ -388,6 +416,161 @@ function canonicalArguments(args: readonly string[]): readonly string[] {
   return args
 }
 
+function rejectUnknownCliFlags(
+  parsed: ParsedArguments,
+  allowed: readonly string[],
+  command: string,
+): void {
+  const unknown = [...parsed.flags].find((flag) => !allowed.includes(flag))
+  if (unknown !== undefined) throw new Error(`Unknown ${command} option: --${unknown}`)
+}
+
+function exactlyOnePositional(parsed: ParsedArguments, usage: string): string {
+  if (parsed.positionals.length !== 1) throw new Error(`Use ${usage}`)
+  return parsed.positionals[0]!
+}
+
+function logOperationResult(
+  dependencies: SlopcameraCliDependencies,
+  json: boolean,
+  receipt: unknown,
+  summary: string,
+): void {
+  ;(dependencies.log ?? console.log)(json ? JSON.stringify(receipt, null, 2) : summary)
+  reportUsefulResult(dependencies.onUsefulResult)
+}
+
+async function runIconScene(
+  action: "compose" | "render",
+  args: readonly string[],
+  dependencies: SlopcameraCliDependencies,
+): Promise<void> {
+  if (action === "compose") {
+    const usage = "slopcamera image icon compose <source.json> [--output <file.json>] [--json]"
+    const parsed = parseArguments(args, new Set(["output"]))
+    rejectUnknownCliFlags(parsed, ["json"], "icon compose")
+    const sourcePath = exactlyOnePositional(parsed, usage)
+    const receipt = await executeSlopcameraOperation(
+      "slopcamera.icon.compose",
+      {
+        sourcePath,
+        ...(parsed.options.output === undefined ? {} : { outputPath: parsed.options.output }),
+      },
+      hostAdmissionOptions(dependencies),
+    )
+    logOperationResult(
+      dependencies,
+      parsed.flags.has("json"),
+      receipt,
+      `Composed ${receipt.form} "${receipt.title}": ${receipt.elementCount} element${receipt.elementCount === 1 ? "" : "s"}, geometry ${receipt.digests.geometry}` +
+        `${receipt.diagnostics.length === 0 ? "" : `, ${receipt.diagnostics.length} diagnostic${receipt.diagnostics.length === 1 ? "" : "s"}`}` +
+        `${receipt.output === null ? "" : ` -> ${receipt.output.path}`}`,
+    )
+    return
+  }
+  const parsed = parseArguments(args, new Set(["output", "recipe", "size", "palette", "language"]))
+  rejectUnknownCliFlags(parsed, ["json", "background"], "icon render")
+  const sourcePath = exactlyOnePositional(
+    parsed,
+    "slopcamera image icon render <source.json> --output <file.svg> [options]",
+  )
+  const size = parsed.options.size
+  if (size !== undefined && !/^\d{1,5}$/u.test(size)) {
+    throw new Error("--size must be an integer")
+  }
+  const receipt = await executeSlopcameraOperation(
+    "slopcamera.icon.render",
+    {
+      sourcePath,
+      outputPath: requiredOption(parsed, "output"),
+      ...(parsed.options.recipe === undefined ? {} : { recipePath: parsed.options.recipe }),
+      ...(size === undefined ? {} : { size: Number(size) }),
+      ...(parsed.flags.has("background") ? { background: true } : {}),
+      ...(parsed.options.palette === undefined ? {} : { palette: parsed.options.palette }),
+      ...(parsed.options.language === undefined ? {} : { language: parsed.options.language }),
+    },
+    hostAdmissionOptions(dependencies),
+  )
+  logOperationResult(
+    dependencies,
+    parsed.flags.has("json"),
+    receipt,
+    `Rendered ${receipt.form} "${receipt.title}"${receipt.replayed ? " (replayed recipe)" : ""}: ${receipt.output.path} ` +
+      `(${receipt.width}x${receipt.height}, svg ${receipt.digests.svg})` +
+      `${receipt.recipe === null ? "" : `\nRecipe: ${receipt.recipe.path}`}`,
+  )
+}
+
+async function runSoundtrack(
+  args: readonly string[],
+  dependencies: SlopcameraCliDependencies,
+): Promise<void> {
+  const [action, ...rest] = args
+  if (action === "compose") {
+    const parsed = parseArguments(rest, new Set(["output", "format"]))
+    rejectUnknownCliFlags(parsed, ["json"], "soundtrack compose")
+    const sourcePath = exactlyOnePositional(
+      parsed,
+      "slopcamera media soundtrack compose <score> [--output <file.json>] [--format <format>] [--json]",
+    )
+    const receipt = await executeSlopcameraOperation(
+      "slopcamera.soundtrack.compose",
+      {
+        sourcePath,
+        ...(parsed.options.output === undefined ? {} : { outputPath: parsed.options.output }),
+        ...(parsed.options.format === undefined ? {} : { format: parsed.options.format }),
+      },
+      hostAdmissionOptions(dependencies),
+    )
+    logOperationResult(
+      dependencies,
+      parsed.flags.has("json"),
+      receipt,
+      `Verified ${receipt.kind} "${receipt.title}": ${receipt.bpm} BPM, ${receipt.beatsPerBar}/bar, ${receipt.bars} bars, ` +
+        `${(receipt.durationUs / 1_000_000).toFixed(3)} s, digest ${receipt.digest}` +
+        `${receipt.output === null ? "" : ` -> ${receipt.output.path}`}`,
+    )
+    return
+  }
+  if (action === "grid") {
+    const parsed = parseArguments(rest, new Set(["output", "format", "start-us"]))
+    rejectUnknownCliFlags(parsed, ["json"], "soundtrack grid")
+    const sourcePath = exactlyOnePositional(
+      parsed,
+      "slopcamera media soundtrack grid <score> [--output <file.json>] [--start-us <n>] [--format <format>] [--json]",
+    )
+    const startUs = parsed.options["start-us"]
+    if (startUs !== undefined && !/^\d{1,10}$/u.test(startUs)) {
+      throw new Error("--start-us must be a non-negative integer")
+    }
+    const receipt = await executeSlopcameraOperation(
+      "slopcamera.soundtrack.grid",
+      {
+        sourcePath,
+        ...(parsed.options.output === undefined ? {} : { outputPath: parsed.options.output }),
+        ...(parsed.options.format === undefined ? {} : { format: parsed.options.format }),
+        ...(startUs === undefined ? {} : { startUs: Number(startUs) }),
+      },
+      hostAdmissionOptions(dependencies),
+    )
+    logOperationResult(
+      dependencies,
+      parsed.flags.has("json"),
+      receipt,
+      [
+        `Beat grid for ${receipt.scoreKind} "${receipt.title}": ${JSON.stringify(receipt.music)}`,
+        ...receipt.sections.map(
+          (section) =>
+            `  ${section.index}. ${section.label}  bars ${section.startBar}-${section.endBar}  ${section.startUs}-${section.endUs} us`,
+        ),
+        ...(receipt.output === null ? [] : [`Grid: ${receipt.output.path}`]),
+      ].join("\n"),
+    )
+    return
+  }
+  throw new Error("Use slopcamera media soundtrack compose or grid")
+}
+
 export async function main(
   args: readonly string[],
   dependencies: SlopcameraCliDependencies = {},
@@ -582,6 +765,14 @@ export async function main(
     return
   }
 
+  if (command === "icon" && (rest[0] === "compose" || rest[0] === "render")) {
+    await runIconScene(rest[0], rest.slice(1), dependencies)
+    return
+  }
+  if (command === "soundtrack") {
+    await runSoundtrack(rest, dependencies)
+    return
+  }
   if (command === "icon") {
     const parsed = parseArguments(
       rest,