@hraness/slopcamera 3.2.4

package/skills/slopcamera/references/workflows-sdk.md

@@ -0,0 +1,45 @@
+# Use SDKs and durable workflows
+
+Use `slopcamera workflows list --json` and `slopcamera workflows show <id> --json` to discover checked recipes and their actual inputs. Built-ins include `talking-head-cleanup`, `polished-screen-demo`, `chaptered-demo`, `social-variants`, `creative-iteration`, `creative-selection` and `directed-scene`. Keep ordinary project edits complete before a V2 scene migration.
+
+```sh
+slopcamera workflows plan <id> --input input.json --json
+slopcamera workflows run <id> --input input.json --json
+```
+
+For custom local authoring, use `slopcamera code init workflow.ts`, inspect the starter and its input schema, then `code check`, `code plan` and `code run`. Use `slopcamera help code` for their required `--input` and exact `--plan` flags. Loading a custom module for check or plan runs its trusted Bun top-level code; withheld registered effects are not an OS sandbox.
+
+## Select the SDK boundary
+
+`@hraness/slopcamera/code` is the portable fixed four-operation diagram/image projection. Portable scene and studio schemas do not grant native executors. `@hraness/slopcamera/workflow` preserves the explicitly imported imperative API. `@hraness/slopcamera/local/code` adds the complete closed local media builder, including `.scene`, `.spatialProject`, `.studio`, `.gateway`, `.media`, `.project` and `.render`. Use `@hraness/slopcamera/local/code/workflows` for built-ins, never the nonexistent portable `code/workflows` or `code/testing` imports.
+
+Discover exact local inputs with `slopcamera operations list|show`. No host accepts arbitrary new operation registration or caller-selected shell/argv. The fixed `slopcamera.studio.run` is an explicit exception for previously retained native source: its bundle/job input remains typed, while executable paths and trusted-current-user authority belong to the host invocation. The checked `examples/studio/native-workflow.ts` uses `defineWorkflow` and `StudioRunInputSchema` from the local entrypoint.
+
+`media.ingest` needs an existing ordinary project. There is no public arbitrary-file project bootstrap or SDK project-create operation. Follow [video projects](video-projects.md) for the supported recording/native/directing entry paths; never synthesize their receipts or depend on private constructors.
+
+## Inspect, approve and resume exact work
+
+```sh
+slopcamera runs show <run-id> --json
+slopcamera runs resume <run-id> --json
+```
+
+If paused for approval, read the returned exact preparation or node plan and use `runs approve` with its `--preparation-plan` or `--node-plan` flag. Approval records a decision; a later resume performs work. Do not grant a broader plan than the task authorized.
+
+Native workflow execution also needs `--allow-trusted-code` and the selected `--studio-blender-bin` or `--studio-python` on the execution/resume invocation. A generic effect approval cannot confer native source authority. A completed exact receipt may replay without those execution settings. Private Gateway provider options must be supplied again with the same digest when required; do not store credentials in workflow JSON.
+
+Keep run IDs, errors and receipts after failure. A missing journal does not prove that an effect was never dispatched. Use `--replay-ambiguous-code <node>` only for an explicitly authorized new execution of uncertain trusted code, not as a routine retry. Cancellation does not undo a published output or provider charge.
+
+## Use the portable MCP surface narrowly
+
+When connected, use `check_diagram` and `render_diagram` for compatibility calls, or `search_slopcamera` and `execute_slopcamera` with one exact returned operation and typed JSON. No tool rewrites source.
+
+- Use root-relative paths. A diagram must end in `.diagram.json`.
+- Diagram render replaces the five documented exports, never its source.
+- MCP bounds diagrams to 64 shapes and 128 edges and reports at most 40 findings. Use the CLI for larger checked sources.
+- MCP uses built-in themes/icons and never executes workspace configuration; trusted custom config belongs to the CLI.
+- `slopcamera.image.vectorize` keeps raster bytes local and needs no login.
+- `slopcamera.image.generate` accepts a root-relative `.webp` output and the two exact registry model IDs; it has no automatic retry.
+- Never submit source code, shell text, dynamic imports, arbitrary remote URLs or unregistered names to semantic execution.
+
+The equivalent portable CLI is `slopcamera code search '<terms>' --limit 4` followed by `slopcamera code execute <exact-code> --input '<strict JSON>'`. This small semantic surface is distinct from loading an explicitly trusted local workflow module.

package/skills/slopcamera/scripts/compose-rubber-stamp-field-note.ts

@@ -0,0 +1,229 @@
+#!/usr/bin/env bun
+/**
+ * Compose one rubber-stamp travel field-note poster.
+ *
+ * Left ~58%: the source photograph (cover-cropped, never redrawn).
+ * Right ~42%: warm paper + a generated stamp vignette + typewriter text.
+ *
+ * Usage:
+ *   bun skills/slopcamera/scripts/compose-rubber-stamp-field-note.ts \
+ *     --photo /abs/photo.jpg \
+ *     --stamp /abs/stamp.png \
+ *     --output /abs/out.jpg \
+ *     --place "VENICE" \
+ *     --number "01" \
+ *     --keywords "brick / bell / lagoon" \
+ *     --year "2026"
+ */
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import sharp from "sharp";
+
+type Args = {
+  photo: string;
+  stamp: string;
+  output: string;
+  place: string;
+  number: string;
+  keywords: string;
+  year: string;
+  width: number;
+  height: number;
+  leftRatio: number;
+};
+
+function usage(): never {
+  console.error(`usage: compose-rubber-stamp-field-note.ts \\
+  --photo <path> --stamp <path> --output <path> \\
+  --place <NAME> --number <NN> --keywords "a / b / c" --year <YYYY> \\
+  [--width 1600] [--height 1200] [--left-ratio 0.58]`);
+  process.exit(64);
+}
+
+function readArgs(argv: string[]): Args {
+  const get = (name: string): string | undefined => {
+    const index = argv.indexOf(name);
+    if (index < 0) return undefined;
+    return argv[index + 1];
+  };
+  const photo = get("--photo");
+  const stamp = get("--stamp");
+  const output = get("--output");
+  const place = get("--place");
+  const number = get("--number");
+  const keywords = get("--keywords");
+  const year = get("--year");
+  if (!photo || !stamp || !output || !place || !number || !keywords || !year) usage();
+  return {
+    photo: resolve(photo),
+    stamp: resolve(stamp),
+    output: resolve(output),
+    place: place.trim().toUpperCase(),
+    number: number.trim().replace(/^No\.?\s*/i, ""),
+    keywords: keywords.trim().toLowerCase(),
+    year: year.trim(),
+    width: Number(get("--width") ?? "1600"),
+    height: Number(get("--height") ?? "1200"),
+    leftRatio: Number(get("--left-ratio") ?? "0.58"),
+  };
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+async function paperPanel(width: number, height: number): Promise<Buffer> {
+  // Warm off-white base with soft fiber noise.
+  const noise = await sharp({
+    create: {
+      width,
+      height,
+      channels: 3,
+      background: { r: 236, g: 228, b: 210 },
+    },
+  })
+    .png()
+    .toBuffer();
+
+  const grainSvg = Buffer.from(`<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+  <filter id="grain">
+    <feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/>
+    <feColorMatrix type="matrix" values="0 0 0 0 0.72  0 0 0 0 0.68  0 0 0 0 0.58  0 0 0 0.12 0"/>
+  </filter>
+  <rect width="100%" height="100%" fill="#ece4d2"/>
+  <rect width="100%" height="100%" filter="url(#grain)"/>
+</svg>`);
+
+  return sharp(noise)
+    .composite([{ input: grainSvg, blend: "multiply" }])
+    .jpeg({ quality: 95 })
+    .toBuffer()
+    .then((jpeg) => sharp(jpeg).png().toBuffer());
+}
+
+async function textPanel(
+  width: number,
+  height: number,
+  args: Args,
+): Promise<Buffer> {
+  const font = "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf";
+  const lines = [
+    args.place,
+    `No. ${args.number}`,
+    args.keywords,
+    args.year,
+  ];
+  const fontSize = Math.max(18, Math.round(width * 0.055));
+  const lineGap = Math.round(fontSize * 1.35);
+  const startY = Math.round(fontSize * 1.1);
+  const textSvg = Buffer.from(`<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+  <style>
+    .t {
+      font-family: "DejaVu Sans Mono", monospace;
+      font-size: ${fontSize}px;
+      fill: #1a1a1a;
+      letter-spacing: 0.5px;
+    }
+  </style>
+  ${lines
+    .map(
+      (line, index) =>
+        `<text class="t" x="0" y="${startY + index * lineGap}">${escapeXml(line)}</text>`,
+    )
+    .join("\n  ")}
+</svg>`);
+  return sharp(textSvg).png().toBuffer();
+}
+
+async function main(): Promise<void> {
+  const args = readArgs(process.argv.slice(2));
+  if (
+    !Number.isFinite(args.width)
+    || !Number.isFinite(args.height)
+    || args.width < 640
+    || args.height < 480
+    || args.leftRatio <= 0.4
+    || args.leftRatio >= 0.7
+  ) {
+    throw new Error("invalid canvas size or left ratio");
+  }
+
+  const leftWidth = Math.round(args.width * args.leftRatio);
+  const rightWidth = args.width - leftWidth;
+
+  const photo = await sharp(args.photo)
+    .rotate()
+    .resize(leftWidth, args.height, { fit: "cover", position: "centre" })
+    .modulate({ saturation: 0.92, brightness: 1.02 })
+    .jpeg({ quality: 92 })
+    .toBuffer();
+
+  const paper = await paperPanel(rightWidth, args.height);
+
+  const stampMaxWidth = Math.round(rightWidth * 0.78);
+  const stampMaxHeight = Math.round(args.height * 0.36);
+  const stamp = await sharp(args.stamp)
+    .ensureAlpha()
+    .resize(stampMaxWidth, stampMaxHeight, {
+      fit: "inside",
+      withoutEnlargement: false,
+    })
+    .png()
+    .toBuffer();
+  const stampMeta = await sharp(stamp).metadata();
+  const stampW = stampMeta.width ?? stampMaxWidth;
+  const stampH = stampMeta.height ?? stampMaxHeight;
+
+  const stampLeft = Math.round((rightWidth - stampW) / 2);
+  // Mid-lower placement with room for typewriter text under the stamp.
+  const stampTop = Math.round(args.height * 0.34);
+
+  const textWidth = Math.round(rightWidth * 0.78);
+  const textHeight = Math.round(args.height * 0.22);
+  const text = await textPanel(textWidth, textHeight, args);
+  const textLeft = Math.round((rightWidth - textWidth) / 2);
+  const textTop = stampTop + stampH + Math.round(args.height * 0.04);
+
+  const right = await sharp(paper)
+    .composite([
+      { input: stamp, left: stampLeft, top: stampTop },
+      { input: text, left: textLeft, top: textTop },
+    ])
+    .png()
+    .toBuffer();
+
+  await mkdir(dirname(args.output), { recursive: true });
+  await sharp({
+    create: {
+      width: args.width,
+      height: args.height,
+      channels: 3,
+      background: { r: 236, g: 228, b: 210 },
+    },
+  })
+    .composite([
+      { input: photo, left: 0, top: 0 },
+      { input: right, left: leftWidth, top: 0 },
+    ])
+    .jpeg({ quality: 94, mozjpeg: true })
+    .toFile(args.output);
+
+  console.log(JSON.stringify({
+    ok: true,
+    output: args.output,
+    width: args.width,
+    height: args.height,
+    leftWidth,
+    rightWidth,
+    place: args.place,
+    number: args.number,
+  }));
+}
+
+await main();

package/src/artifacts.ts

@@ -0,0 +1,106 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+import { basename, dirname, join, resolve } from "node:path"
+import { loadDiagramConfig } from "./config.js"
+import { lintDiagram } from "./lint.js"
+import { parseDiagramSpec } from "./parse.js"
+import { renderPng, renderSvg } from "./render.js"
+import { serializeTldr } from "./tldr.js"
+import type { LintFinding, RenderArtifacts } from "./types.js"
+
+async function atomicWrite(filePath: string, data: string | Uint8Array): Promise<void> {
+  const temporary = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`
+  try {
+    await writeFile(temporary, data)
+    await rename(temporary, filePath)
+  } catch (error) {
+    await rm(temporary, { force: true })
+    throw error
+  }
+}
+
+export async function readDiagramFile(filePath: string) {
+  const absolutePath = resolve(filePath)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(await readFile(absolutePath, "utf8"))
+  } catch (error) {
+    throw new Error(`Could not read diagram JSON at ${absolutePath}`, { cause: error })
+  }
+  return { absolutePath, spec: parseDiagramSpec(parsed) }
+}
+
+export async function checkDiagramFile(options: {
+  readonly filePath: string
+  readonly configPath?: string
+}): Promise<{ readonly findings: readonly LintFinding[]; readonly configPath: string | null }> {
+  const { absolutePath, spec } = await readDiagramFile(options.filePath)
+  const config = await loadDiagramConfig({
+    ...(options.configPath === undefined ? {} : { explicitPath: options.configPath }),
+    searchDirectory: dirname(absolutePath),
+  })
+  for (const shape of spec.shapes) {
+    if (
+      (shape.type === "rect" || shape.type === "ellipse") &&
+      shape.icon !== undefined &&
+      config.value.icons?.[shape.icon] === undefined
+    ) {
+      throw new Error(`Unknown icon "${shape.icon}" on shape ${shape.id}`)
+    }
+  }
+  return { findings: lintDiagram(spec), configPath: config.filePath }
+}
+
+export async function renderDiagramFile(options: {
+  readonly filePath: string
+  readonly outDirectory?: string
+  readonly configPath?: string
+  readonly scale?: number
+}): Promise<{
+  readonly artifacts: RenderArtifacts
+  readonly findings: readonly LintFinding[]
+  readonly configPath: string | null
+}> {
+  const { absolutePath, spec } = await readDiagramFile(options.filePath)
+  const outDirectory = resolve(options.outDirectory ?? dirname(absolutePath))
+  const config = await loadDiagramConfig({
+    ...(options.configPath === undefined ? {} : { explicitPath: options.configPath }),
+    searchDirectory: dirname(absolutePath),
+  })
+  const scale = options.scale ?? 2
+  if (!Number.isFinite(scale) || scale <= 0 || scale > 8) {
+    throw new Error("PNG scale must be greater than zero and no more than 8")
+  }
+  const [light, dark] = await Promise.all([
+    renderSvg(spec, "light", config.value),
+    renderSvg(spec, "dark", config.value),
+  ])
+  const [lightPng, darkPng] = [renderPng(light, config.value, scale), renderPng(dark, config.value, scale)]
+  const artifacts = {
+    spec: absolutePath,
+    tldr: join(outDirectory, `${spec.name}.tldr`),
+    lightSvg: join(outDirectory, `${spec.name}.light.svg`),
+    darkSvg: join(outDirectory, `${spec.name}.dark.svg`),
+    lightPng: join(outDirectory, `${spec.name}.light.png`),
+    darkPng: join(outDirectory, `${spec.name}.dark.png`),
+  } satisfies RenderArtifacts
+  await mkdir(outDirectory, { recursive: true })
+  await Promise.all([
+    atomicWrite(artifacts.tldr, serializeTldr(spec, config.value)),
+    atomicWrite(artifacts.lightSvg, light.svg),
+    atomicWrite(artifacts.darkSvg, dark.svg),
+    atomicWrite(artifacts.lightPng, lightPng),
+    atomicWrite(artifacts.darkPng, darkPng),
+  ])
+  return { artifacts, findings: lintDiagram(spec), configPath: config.filePath }
+}
+
+export function artifactSummary(artifacts: RenderArtifacts): string {
+  return [
+    `Rendered ${basename(artifacts.spec)}`,
+    `  ${artifacts.tldr}`,
+    `  ${artifacts.lightSvg}`,
+    `  ${artifacts.darkSvg}`,
+    `  ${artifacts.lightPng}`,
+    `  ${artifacts.darkPng}`,
+  ].join("\n")
+}

package/src/assets/fonts/nebula-sans/LICENSE.txt

@@ -0,0 +1,96 @@
+Copyright (c) 2024, Nebula Entertainment & Broadcasting LLC (https://nebula.tv),
+with Reserved Font Name 'Nebula'.
+
+Based on Source Sans, copyright 2010-2024 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/assets/fonts/nebula-sans/PROVENANCE.md

@@ -0,0 +1,21 @@
+# Nebula Sans provenance
+
+- Family: Nebula Sans
+- Version: 1.010
+- Use: default proportional browser text and heading face
+- Upstream: https://www.nebulasans.com/
+- Source archive: https://www.nebulasans.com/download/NebulaSans-1.010.zip
+- Retrieved: 2026-08-27
+- Archive SHA-256: `a9b56ef15e24b6e8195af7457cc75f714ecf5501fc3c20a69f546c8f589e7bdb`
+- License: SIL Open Font License 1.1, retained as `LICENSE.txt`
+
+The WOFF2 and OTF files are vendored unchanged from the official archive. Nebula
+Entertainment & Broadcasting LLC reserves the font name `Nebula`; this package
+distributes the unmodified original files under that name.
+
+Slopcamera carries the unchanged Book and Bold WOFF2 and OTF files from the canonical
+`@hraness/design-kit` v0.2.1 release. Resvg loads Bold OTF directly for caption
+sprites with system font discovery disabled. Diagram PNG rendering loads Book
+plus Bold OTF for the ordinary proportional default while retaining system font
+discovery for explicit mono and custom font roles. The WOFF2 files remain
+embedded in standalone diagram SVG output.

package/src/assets.d.ts

@@ -0,0 +1,9 @@
+declare module "*.woff2" {
+  const assetPath: string
+  export default assetPath
+}
+
+declare module "*.otf" {
+  const assetPath: string
+  export default assetPath
+}