@hraness/slopcamera 3.3.6 → 3.4.0

package/examples/style-portfolio/market-street/source.json

@@ -0,0 +1 @@
+{"engine":"blender","entrypoint":{"kind":"python","path":"scene.py"},"files":["mesh.py","scene.py","street_data.py"]}

package/examples/style-portfolio/market-street/street_data.py

@@ -0,0 +1,72 @@
+"""Evidence for the historical interpretation, separate from art direction.
+
+The scene is a compressed invented block inspired by the 1906 film. Dimensions,
+shop occupants, figure performances, and most facades are authored estimates.
+No building footprint is claimed to have been digitized from a Sanborn plate.
+"""
+
+SOURCES = [
+    {
+        'id': 'loc-film',
+        'url': 'https://www.loc.gov/item/00694408/',
+        'title': 'A trip down Market Street before the fire',
+        'institution': 'Library of Congress',
+        'supports': ['1906 setting', 'cable-car viewpoint toward Ferry Building',
+                     'black-and-white 35 mm source', 'mixed street traffic',
+                     'damp roadway visible in the film'],
+    },
+    {
+        'id': 'sfmta-conversion',
+        'url': 'https://www.sfmta.com/blog/how-1906-earthquake-transformed-our-public-transit-system',
+        'title': 'How the 1906 Earthquake Transformed Our Public Transit System',
+        'institution': 'San Francisco Municipal Transportation Agency',
+        'supports': ['electric conversion of Market Street followed the earthquake'],
+    },
+    {
+        'id': 'sfplanning-lamps',
+        'url': 'https://commissions.sfplanning.org/hpcpackets/2014.794A.pdf',
+        'title': 'Path of Gold Light Standards landmark case report',
+        'institution': 'San Francisco Planning Department',
+        'supports': ['Path of Gold bases date to 1908, globe tops to 1916'],
+    },
+]
+
+INTERPRETATION = {
+    'depictedPeriod': 'San Francisco, before the April 1906 earthquake',
+    'kind': 'procedural historical interpretation',
+    'historicalReconstruction': False,
+    'authoredEstimates': [
+        'All metric geometry, street compression, camera lens and height',
+        'Facades, shop names, costumes, individual vehicles and performances',
+        'Monochrome material response, weather, lighting and capture cadence',
+    ],
+    'excludedAnachronisms': ['Path of Gold globes', 'Market Street traction catenary'],
+}
+
+# +Y runs inland. The camera travels toward -Y. The shot faces the Ferry,
+# where screen-left is +X and screen-right is -X. Parcel coordinates are
+# composition coordinates, not surveyed geographic coordinates.
+ROAD_WIDTH = 26.0
+SIDEWALK_WIDTH = 5.3
+FERRY_Y = -12.0
+CAPTURE_FPS = 16
+DURATION_SECONDS = 6.0
+
+# Art-directed frontage parcels with separate setbacks at side-street cuts.
+# Values are (center Y, frontage, height, bays, material, roof treatment).
+PARCELS = {
+    -1: [(12, 22, 18, 6, 'stone', 'flat'),
+         (40, 23, 25, 6, 'brick', 'pediment'),
+         (70, 25, 20, 7, 'plaster', 'flat'),
+         (105, 30, 31, 8, 'brick_light', 'mansard'),
+         (146, 35, 24, 9, 'stone', 'pediment'),
+         (187, 31, 36, 8, 'brick', 'flat'),
+         (224, 30, 23, 8, 'plaster', 'flat')],
+    1: [(14, 24, 21, 7, 'brick_light', 'flat'),
+        (46, 25, 18, 7, 'stone', 'flat'),
+        (77, 27, 30, 8, 'brick', 'pediment'),
+        (111, 24, 22, 6, 'stone', 'flat'),
+        (148, 35, 33, 9, 'brick_light', 'mansard'),
+        (190, 34, 25, 9, 'plaster', 'pediment'),
+        (230, 33, 31, 9, 'brick', 'flat')],
+}

package/examples/style-portfolio/render-film-plate.ts

@@ -0,0 +1,128 @@
+/** Retain one local photographic plate and render a bounded single-image transfer study. */
+import { createHash } from "node:crypto";
+import { mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import sharp from "sharp";
+import { z } from "zod";
+import { HtmlSceneInputSchema } from "../../apps/desktop/html-overlay/scene";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const maxBytes = 32 * 1024 * 1024;
+const maxPixels = 33_000_000;
+const args = process.argv.slice(2);
+const options = new Map<string, string>();
+let dryRun = false;
+for (let index = 0; index < args.length; index++) {
+  const arg = args[index]!;
+  if (arg === "--dry-run" && !dryRun) dryRun = true;
+  else if (["--image", "--run", "--width", "--height"].includes(arg) && args[index + 1] !== undefined) {
+    if (options.has(arg)) throw new Error(`Duplicate option ${arg}.`);
+    options.set(arg, args[++index]!);
+  } else throw new Error(`Unknown, duplicate, or incomplete option ${arg}.`);
+}
+const imageArg = options.get("--image");
+const run = options.get("--run");
+if (!imageArg || !run) throw new Error("Usage: bun examples/style-portfolio/render-film-plate.ts --image <local.png|local.jpg> --run <new-id> [--width <maximum>] [--height <maximum>] [--dry-run]");
+if (imageArg.length > 4096 || /[\0\r\n]/u.test(imageArg) || /^[a-z][a-z0-9+.-]*:\/\//iu.test(imageArg)) throw new Error("--image must be an explicit bounded local path, not a URL.");
+if (!/^[a-z0-9][a-z0-9-]{0,63}$/u.test(run)) throw new Error("--run must be a new short lowercase filename token.");
+function bound(name: string, fallback: number) {
+  const value = options.get(name);
+  if (value === undefined) return fallback;
+  if (!/^[0-9]{1,4}$/u.test(value)) throw new Error(`${name} must be an integer in [16,8192].`);
+  const parsed = Number(value);
+  if (parsed < 16 || parsed > 8192) throw new Error(`${name} must be an integer in [16,8192].`);
+  return parsed;
+}
+const hasSize = options.has("--width") || options.has("--height");
+const maxWidth = bound("--width", hasSize ? 8192 : 1440);
+const maxHeight = bound("--height", hasSize ? 8192 : 1080);
+const input = await realpath(resolve(root, imageArg));
+// Read from one handle with a fixed byte ceiling, then bind the retained copy.
+const handle = await open(input, "r");
+let bytes: Buffer;
+try {
+  const before = await handle.stat();
+  if (!before.isFile() || !Number.isSafeInteger(before.size) || before.size < 1 || before.size > maxBytes) throw new Error("Use a regular PNG/JPEG file no larger than 32 MiB.");
+  bytes = Buffer.alloc(before.size);
+  let position = 0;
+  while (position < bytes.length) {
+    const result = await handle.read(bytes, position, bytes.length - position, position);
+    if (result.bytesRead === 0) throw new Error("The plate changed while it was read.");
+    position += result.bytesRead;
+  }
+  const extra = await handle.read(Buffer.alloc(1), 0, 1, position);
+  const after = await handle.stat();
+  if (extra.bytesRead !== 0 || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ino !== before.ino || after.dev !== before.dev) throw new Error("The plate changed while it was read.");
+} finally { await handle.close(); }
+const metadata = await sharp(bytes, { limitInputPixels: maxPixels, failOn: "error", animated: true }).metadata();
+if (!["png", "jpeg"].includes(metadata.format ?? "") || (metadata.pages ?? 1) !== 1) throw new Error("Use one static PNG or JPEG photograph.");
+const sourceWidth = metadata.autoOrient.width;
+const sourceHeight = metadata.autoOrient.height;
+if (!Number.isInteger(sourceWidth) || !Number.isInteger(sourceHeight) || sourceWidth < 16 || sourceHeight < 16 || sourceWidth * sourceHeight > maxPixels) throw new Error("The decoded plate must be at least 16 pixels per side and at most 33 megapixels.");
+const scale = Math.min(1, maxWidth / sourceWidth, maxHeight / sourceHeight);
+const width = Math.floor(sourceWidth * scale / 2) * 2;
+const height = Math.floor(sourceHeight * scale / 2) * 2;
+if (width < 2 || height < 2 || width * height > maxPixels) throw new Error("The requested aspect ratio does not fit a bounded even raster.");
+const sourceSha256 = createHash("sha256").update(bytes).digest("hex");
+const extension = metadata.format === "png" ? "png" : "jpg";
+const outputRoot = join(root, "artifacts/style-portfolio/film-plate");
+await mkdir(outputRoot, { recursive: true });
+if (await realpath(outputRoot) !== outputRoot) throw new Error("The output directory and its parents must not be symlinks.");
+const output = join(outputRoot, run);
+// The run directory is the exclusive claim. A previous or ambiguous run is
+// never overwritten or automatically resumed, even when only planning failed.
+try { await mkdir(output); }
+catch (error) {
+  if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Run ${run} already exists. Inspect its intent, log, and host receipts; no overwrite or retry was made.`);
+  throw error;
+}
+const retainedPlate = join(output, `plate.${extension}`);
+await writeFile(retainedPlate, bytes, { flag: "wx", mode: 0o600 });
+const retainedRelative = relative(root, retainedPlate).split(sep).join("/");
+if (isAbsolute(retainedRelative) || retainedRelative.startsWith("../")) throw new Error("The retained plate must stay inside the repository artifacts directory.");
+const source = HtmlSceneInputSchema.parse({
+  kind: "slopcamera.html-scene", schemaVersion: 1,
+  name: "Single-image film-transfer study",
+  document: { path: "examples/style-portfolio/film-plate.html" },
+  canvas: { width, height, deviceScaleFactor: 1 },
+  timing: { durationUs: 6_000_000, fps: 16 },
+  seed: 19060414, background: "#000000", libraries: [],
+  parameters: { kind: "single-image-film-transfer", sourceWidth, sourceHeight, sourceSha256 },
+  resources: [{ name: "plate", path: retainedRelative, urlPath: `assets/plate.${extension}`, mediaType: metadata.format === "png" ? "image/png" : "image/jpeg" }],
+});
+const requestPath = join(output, "scene.json");
+const intentPath = join(output, "intent.json");
+await writeFile(requestPath, JSON.stringify(source, null, 2) + "\n", { flag: "wx" });
+const intent = {
+  kind: "slopcamera.single-image-film-transfer-intent", schemaVersion: 1,
+  mode: dryRun ? "plan" : "render", input, sourceSha256, sourceBytes: bytes.length,
+  sourceDimensions: { width: sourceWidth, height: sourceHeight }, outputDimensions: { width, height },
+  requestedMaximum: { width: maxWidth, height: maxHeight }, retainedPlate: retainedRelative,
+  requestPath, timing: source.timing,
+  limitations: ["One photographic image with optical movement; no subject animation.", "Delivery never exceeds input dimensions. A small optical crop is resampled within that raster.", "Grain and diffusion are a separate explicit finishing operation."],
+};
+await writeFile(intentPath, JSON.stringify(intent, null, 2) + "\n", { flag: "wx" });
+const argv = [process.execPath, join(root, "apps/desktop/dist/cli/main.js"), "html", "render", "--input", requestPath, "--json"];
+if (dryRun) argv.push("--dry-run");
+const logPath = join(output, "render.log");
+const log = await open(logPath, "wx", 0o600);
+let code: number;
+let stdout: string;
+try {
+  const child = Bun.spawn(argv, { cwd: root, env: process.env, stdout: "pipe", stderr: log.fd });
+  const result = await Promise.all([child.exited, new Response(child.stdout).text()]);
+  [code, stdout] = result;
+} finally { await log.close(); }
+if (code !== 0) {
+  await writeFile(join(output, "failed.json"), JSON.stringify({ code, stdout }, null, 2) + "\n", { flag: "wx" });
+  throw new Error(`Slopcamera ${dryRun ? "plan" : "render"} failed (${code}); inspect ${logPath} and retained host receipts. No retry was made.`);
+}
+const result: unknown = JSON.parse(stdout);
+const resultPath = join(output, dryRun ? "plan.json" : "result.json");
+await writeFile(resultPath, JSON.stringify(result, null, 2) + "\n", { flag: "wx" });
+if (!dryRun) {
+  const completion = z.object({ kind: z.literal("slopcamera.html-scene-export"), verification: z.object({ width: z.number(), height: z.number(), frameCount: z.number(), durationUs: z.number() }) }).parse(result);
+  if (completion.verification.width !== width || completion.verification.height !== height || completion.verification.frameCount !== 96 || completion.verification.durationUs !== 6_000_000) throw new Error("Rendered dimensions or timing differ from the admitted request; retain this result for review.");
+}
+console.log(JSON.stringify({ state: dryRun ? "planned" : "rendered", interpretation: "single-image-film-transfer", sourceDimensions: intent.sourceDimensions, dimensions: { width, height }, fps: 16, durationSeconds: 6, sourceSha256, resultPath, intentPath }));

package/examples/style-portfolio/render.ts

@@ -0,0 +1,89 @@
+/** Render original style studies through the canonical Slopcamera host. */
+import { mkdir, open, realpath, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getVisualStyleProfile } from "../../src/visual-style";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const studies = ["theatrical-cel", "watercolor-storybook", "pixel-art", "math-explainer",
+  "midcentury-limited", "rubber-hose", "cut-paper", "stopmotion-clay", "engraving",
+  "ink-sketch", "rotoscope", "clean-motion"] as const;
+export async function renderStudies(args: readonly string[], workspaceRoot = root, log: (message: string) => void = console.log): Promise<void> {
+  const flagNames = new Set(["--style", "--width", "--offset", "--run"]);
+  const options = new Map<string, string>();
+  const flags = new Set<string>();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--all" || arg === "--still" || arg === "--dry-run") {
+      if (flags.has(arg)) throw new Error(`Duplicate flag ${arg}`);
+      flags.add(arg);
+    } else if (flagNames.has(arg) && args[i + 1] !== undefined) {
+      if (options.has(arg)) throw new Error(`Duplicate option ${arg}`);
+      options.set(arg, args[++i]!);
+    } else throw new Error(`Unknown or incomplete option ${arg}`);
+  }
+  const still = flags.has("--still");
+  const width = Number(options.get("--width") ?? 3840);
+  const offset = Number(options.get("--offset") ?? (still ? 3 : 0));
+  const run = options.get("--run") ?? (still ? "stills" : "films");
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/u.test(run)) throw new Error("--run must be a short lowercase filename token.");
+  if (![1280, 1920, 2560, 3840].includes(width)) throw new Error("--width must be 1280, 1920, 2560, or 3840.");
+  if (!Number.isFinite(offset) || offset < 0 || offset >= 6 || (!still && offset !== 0)) throw new Error("--offset must be in [0,6), and requires --still.");
+  const requested = options.get("--style");
+  if ((requested === undefined) === !flags.has("--all")) throw new Error("Choose exactly one of --style <id> or --all.");
+  const selected = requested === undefined ? studies : studies.filter(id => id === requested);
+  if (selected.length === 0) throw new Error(`Study not found. Choose: ${studies.join(", ")}`);
+  const canonicalRoot = await realpath(workspaceRoot);
+  const output = join(canonicalRoot, "artifacts", "style-portfolio", run);
+  await mkdir(output, { recursive: true });
+  if (await realpath(output) !== output) throw new Error("Output directories must not be symlinks.");
+  for (const style of selected) {
+    // Plans have their own immutable attempt, so inspecting a new width never
+    // replaces an execution's scene, log, result, or native receipt references.
+    const prefix = `${style}${flags.has("--dry-run") ? ".plan" : ""}`;
+    const resultPath = join(output, `${prefix}.result.json`);
+    const requestPath = join(output, `${prefix}.scene.json`);
+    const intentPath = join(output, `${prefix}.intent.json`);
+    // A retained intent without a result is ambiguous. Inspect its log and host
+    // receipts before selecting an explicitly new --run, never auto-resubmit.
+    try {
+      await writeFile(intentPath, JSON.stringify({ kind: "slopcamera.style-study-intent", style, requestPath, width, still,
+        mode: flags.has("--dry-run") ? "plan" : "render" }) + "\n", { flag: "wx", mode: 0o600 });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      log(JSON.stringify({ style, state: "already-attempted", intentPath, resultPath }));
+      continue;
+    }
+    const profile = getVisualStyleProfile(style);
+    const scene = {
+      kind: "slopcamera.html-scene", schemaVersion: 1,
+      name: `${profile.name} / ${still ? "master still" : "motion study"}`,
+      document: { path: "examples/style-portfolio/animation-studies.html" },
+      canvas: { width, height: width * 9 / 16, deviceScaleFactor: 1 },
+      timing: { durationUs: still ? 1 : 6_000_000, fps: 24 },
+      seed: 20260923, libraries: [], resources: [],
+      parameters: { style, direction: profile, timeOffsetSeconds: offset },
+      background: profile.palette.background,
+    };
+    await writeFile(requestPath, JSON.stringify(scene, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+    const childArgs = [process.execPath, join(canonicalRoot, "apps/desktop/dist/cli/main.js"), "html", "render", "--input", requestPath, "--json"];
+    if (flags.has("--dry-run")) childArgs.push("--dry-run");
+    const logPath = join(output, `${prefix}.log`);
+    const logFile = await open(logPath, "wx", 0o600);
+    let code: number;
+    let stdout: string;
+    try {
+      const child = Bun.spawn(childArgs, { cwd: canonicalRoot, env: process.env, stdout: "pipe", stderr: logFile.fd });
+      [code, stdout] = await Promise.all([child.exited, new Response(child.stdout).text()]);
+    } finally { await logFile.close(); }
+    if (code !== 0) {
+      await writeFile(join(output, `${prefix}.failed.json`), JSON.stringify({ code, stdout }) + "\n", { flag: "wx" });
+      throw new Error(`${style} render failed (${code}); inspect ${logPath}. No automatic retry was made.`);
+    }
+    const result: unknown = JSON.parse(stdout);
+    await writeFile(resultPath, JSON.stringify(result, null, 2) + "\n", { flag: "wx" });
+    log(JSON.stringify({ style, state: flags.has("--dry-run") ? "planned" : "rendered", resultPath }));
+  }
+}
+
+if (import.meta.main) await renderStudies(process.argv.slice(2));

package/examples/style-portfolio/verify-animation-source.mjs

@@ -0,0 +1,94 @@
+/** Source checks only. This does not replace rendered-frame and motion review. */
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { runInNewContext } from "node:vm";
+import { getVisualStyleProfile } from "../../src/visual-style.ts";
+
+const html = await readFile(new URL("./animation-studies.html", import.meta.url), "utf8");
+const scripts = [...html.matchAll(/<script\s*>([\s\S]*?)<\/script\s*>/giu)];
+assert.equal((html.match(/<script\b/giu) ?? []).length, 1, "The self-contained scene has one script element.");
+assert.equal(scripts.length, 1, "The scene script is inline and has no attributes.");
+const script = scripts[0]?.[1];
+assert.ok(script, "The inline scene script is nonempty.");
+new Function(script);
+let digest = createHash("sha256");
+const contexts = [];
+const record = (name, values) => digest.update(JSON.stringify([name, values]));
+function context(name) {
+  let depth = 0;
+  const methods = {
+    save() { depth++; record(`${name}.save`, []); },
+    restore() { assert.ok(depth > 0, "Canvas restore has an owned save."); depth--; record(`${name}.restore`, []); },
+    createLinearGradient(...args) { return gradient("linear", args); },
+    createRadialGradient(...args) { return gradient("radial", args); },
+  };
+  const gradient = (kind, args) => {
+    args.forEach(value => assert.ok(Number.isFinite(value), "Gradient coordinates are finite."));
+    const result = { kind, args, stops: [], addColorStop(position, color) {
+      assert.ok(position >= 0 && position <= 1, "Gradient stop lies in [0, 1].");
+      result.stops.push([position, color]);
+    } };
+    return result;
+  };
+  const proxy = new Proxy(methods, {
+    get(target, property) {
+      if (property in target) return target[property];
+      return (...args) => {
+        for (const value of args) if (typeof value === "number") assert.ok(Number.isFinite(value), `${String(property)} receives finite coordinates.`);
+        if (property === "arc") assert.ok(args[2] >= 0, "Arc radius is nonnegative.");
+        if (property === "ellipse") assert.ok(args[2] >= 0 && args[3] >= 0, "Ellipse radii are nonnegative.");
+        record(`${name}.${String(property)}`, args);
+      };
+    },
+    set(target, property, value) { target[property] = value; record(`${name}.${String(property)}=`, [value]); return true; },
+  });
+  contexts.push(() => assert.equal(depth, 0, "Scene leaves a balanced Canvas save stack."));
+  return proxy;
+}
+const main = { width: 1920, height: 1080, getContext: () => context("main") };
+const pixel = { width: 320, height: 180, getContext: () => context("pixel") };
+let frame;
+const host = { parameters: { style: "theatrical-cel" }, onFrame(callback) { frame = callback; } };
+const window = { innerWidth: 1920, innerHeight: 1080, devicePixelRatio: 1, SlopcameraOverlay: host };
+runInNewContext(script, {
+  window, SlopcameraOverlay: host,
+  document: { getElementById: () => main, createElement: tag => { assert.equal(tag, "canvas"); return pixel; } },
+  Path2D: class { constructor(data) { assert.equal(typeof data, "string"); assert.ok(!/NaN|Infinity/u.test(data), "Path coordinates are finite."); this.data = data; } },
+}, { timeout: 10_000 });
+const drawing = window.PortfolioDrawing;
+assert.equal(drawing.styles.length, 12);
+const fingerprint = (time, style, direction) => {
+  digest = createHash("sha256");
+  drawing.render(time, style, direction);
+  contexts.forEach(check => check());
+  return digest.digest("hex");
+};
+let samples = 0;
+for (const style of drawing.styles) {
+  const profile = getVisualStyleProfile(style);
+  drawing.validateDirection(profile, style);
+  for (const time of [0, .25, .84, 1.68, 2.65, 3, 5.999, 6]) {
+    const first = fingerprint(time, style, profile);
+    fingerprint((time + 1.3) % 6, "clean-motion", getVisualStyleProfile("clean-motion"));
+    assert.equal(fingerprint(time, style, profile), first, `${style} at ${time}s is independent of seek order.`);
+    samples++;
+  }
+}
+assert.throws(() => drawing.render(1, "unknown"), /Unsupported style/u);
+assert.throws(() => drawing.render(NaN, "theatrical-cel"), /finite number/u);
+assert.throws(() => drawing.render(-1, "theatrical-cel"), /finite number/u);
+assert.throws(() => drawing.render(6.1, "theatrical-cel"), /finite number/u);
+assert.throws(() => drawing.validateDirection({}, "theatrical-cel"), /required/u);
+assert.throws(() => drawing.validateDirection({ ...getVisualStyleProfile("theatrical-cel"), id: "pixel-art" }, "theatrical-cel"), /must match/u);
+assert.throws(() => drawing.validateDirection({ ...getVisualStyleProfile("theatrical-cel"), unsupported: 1 }, "theatrical-cel"), /unsupported/u);
+assert.throws(() => drawing.validateDirection({ ...getVisualStyleProfile("theatrical-cel"), cadence: { ...getVisualStyleProfile("theatrical-cel").cadence, fps: 0 } }, "theatrical-cel"), /integer/u);
+window.innerWidth = Infinity;
+assert.throws(() => drawing.render(0, "theatrical-cel"), /canvas CSS width/u);
+window.innerWidth = 1920;
+window.devicePixelRatio = 9;
+assert.throws(() => drawing.render(0, "theatrical-cel"), /devicePixelRatio/u);
+window.devicePixelRatio = 1;
+assert.throws(() => frame({ timeMs: -1 }), /timeMs/u);
+assert.throws(() => frame({ timeMs: 6001 }), /timeMs/u);
+console.log(`Passed: 12 canonical profiles, ${samples} deterministic drawing-command samples, balanced Canvas stacks, finite geometry, and invalid-input checks. Pixel and motion quality still require real renders.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/slopcamera",
-  "version": "3.3.6",
+  "version": "3.4.0",
   "description": "A local visual studio for coding agents: author scenes, combine generated and recorded media, and export images, diagrams, animation, and video from retained sources.",
   "license": "MIT",
   "type": "module",
@@ -162,6 +162,15 @@
     "examples/studio/hybrid-scene.ts",
     "examples/html/*.html",
     "examples/html/*.json",
+    "examples/style-portfolio/**/*.html",
+    "examples/style-portfolio/**/*.ts",
+    "examples/style-portfolio/**/*.mjs",
+    "!examples/style-portfolio/**/*.test.ts",
+    "examples/style-portfolio/**/*.py",
+    "examples/style-portfolio/**/*.json",
+    "examples/style-portfolio/**/*.md",
+    "examples/style-portfolio/**/*.woff2",
+    "examples/style-portfolio/**/*.txt",
     "examples/studio/vgpu/heat-field.mjs",
     "apps/desktop/studio/assets/README.md",
     "!apps/desktop/cli/**/*.test.ts",
@@ -227,7 +236,7 @@
     "benchmark:code-concurrency": "bun run ./apps/desktop/code/concurrency-benchmark.ts",
     "check:release-workflows": "bun test ./scripts/release-workflow.test.ts ./scripts/github-release.test.ts",
     "check:schema": "bun run ./scripts/validate-schema.ts",
-    "check:skill": "bun run ./scripts/validate-skill.ts && bun test ./scripts/social-collage-compositor.test.ts",
+    "check:skill": "bun run ./scripts/validate-skill.ts && bun test ./scripts/social-collage-compositor.test.ts && bun examples/style-portfolio/verify-animation-source.mjs",
     "check:standalone": "bun test ./scripts/standalone-support-fixture.test.ts && bun run ./scripts/check-standalone.ts",
     "test:vectorize:official": "bun run ./scripts/official-vectorizer-smoke.ts",
     "test:package": "bun run ./scripts/package-smoke.ts",

package/skills/slopcamera/SKILL.md

@@ -7,6 +7,14 @@ description: Create, inspect, edit and render visual media with the Slopcamera C
 
 Start from the requested result and existing source. Use the installed `slopcamera` CLI, inspect its real capabilities and retain the authored source beside its derived media. Read only the references needed by the task.
 
+For creative film and animation, choose coherent art direction before rendering.
+Use [visual style direction](references/visual-style-direction.md) for historical
+footage, animation families, resolution, and visual review. Default to native 4K
+for an unspecified creative master when the renderer and source support it;
+preserve deliberate pixel grids, period aspect ratios, source limits, and the
+user's explicit settings. Treat quality as staging,
+materials, movement, and finishing together.
+
 ## Establish the host
 
 Run `slopcamera --help` and use `slopcamera doctor --json` for the selected local tools. If installation or a version mismatch blocks the task, read [installation and readiness](references/install.md). A skill installation does not install the CLI or native engines.
@@ -17,6 +25,7 @@ Slopcamera installs from its verified release archive or from source. Historical
 
 | Requested result | Read |
 | --- | --- |
+| Historical film, cel animation, pixel art, classic animation styles, or a demo portfolio | [Visual style direction](references/visual-style-direction.md) |
 | Editable diagram, flowchart or visual explanation | [Diagrams](references/diagrams.md) and [visual communication](references/visual-communication.md) |
 | Patent-style drawing sheets, physical margins, monochrome SVGs or a drawing PDF | [Drawing sheets](references/patent-drawings.md); requires current source |
 | Custom diagram themes, fonts or icon packages | [Customization](references/customization.md) |

package/skills/slopcamera/references/gateway-media.md

@@ -6,6 +6,11 @@ credential. It has no Slopcamera account, credential store, or hosted project.
 
 ## Start with the intended role
 
+For a creative film or animation brief, use
+[visual style direction](visual-style-direction.md) to translate the intended
+look into concrete source, camera, movement, and finishing decisions. Keep a
+literal prompt literal when that is what the user requested.
+
 Clarify what the generated media needs to do in the final project:
 
 - the subject or message;

package/skills/slopcamera/references/install.md

@@ -14,7 +14,7 @@ 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.3.5/hraness-slopcamera-3.3.5.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.3.6/hraness-slopcamera-3.3.6.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.
 
 Use an existing compatible source build when available. Otherwise follow the [complete source-install guide](https://github.com/hraness/slopcamera/blob/main/docs/how-to/use-current-source.md): clone into a new directory, record its exact commit, install locked dependencies without lifecycle scripts, build the SDK and source CLI, then define the shell command against that checkout. A clone or skill installation alone does not install the executable. Do not alter an existing active checkout to satisfy this path.
 

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

@@ -1,5 +1,10 @@
 # Render a music video from an authored scene
 
+Choose the intended film or animation language with
+[visual style direction](visual-style-direction.md) before authoring the scene.
+The example dimensions below are an iteration setting; select native delivery
+dimensions explicitly for the finished movie.
+
 Use this workflow for a complete HTML or Three.js music video with a local track,
 including dancing characters, changing landscapes, and musical light accents.
 The export retains the source and creates an ordinary editable project with

package/skills/slopcamera/references/native-studio.md

@@ -1,5 +1,9 @@
 # Direct a native film studio
 
+For historical footage, physical materials, or a distinctive animation family,
+establish [visual style direction](visual-style-direction.md) before choosing
+lighting, camera, frame cadence, and finishing.
+
 These commands require current source; check [installation](install.md) and `slopcamera help studio`.
 
 Use `slopcamera studio` when the deliverable needs native Blender, CadQuery or Manim authoring. Keep the native source, caches and exact settings alongside review frames and final clips. This complements the existing Three/Spark scene and ordinary video-project workflows.

package/skills/slopcamera/references/visual-style-direction.md

@@ -0,0 +1,143 @@
+# Direct a visual style
+
+Use this reference when a scene needs a recognizable film or animation language,
+or when producing a portfolio of distinct styles. The current-source `style`
+catalog records reusable production decisions:
+
+```sh
+slopcamera style list --json
+slopcamera style show silent-actuality --json
+slopcamera style show theatrical-cel --json
+```
+
+These profiles are art direction. They do not automatically transform an image,
+replace a scene's materials, synthesize character animation, or certify historical
+accuracy. Apply them through an appropriate renderer. The seven `html catalog`
+profiles describe rendering tools; visual styles are a separate choice.
+
+## Establish the picture before the finish
+
+Write a short direction for the specific subject: setting and period, dominant
+silhouette, foreground and distance planes, light source, camera position, one
+readable action, and intended emotional rhythm. Keep the user's literal facts and
+selected identity. Where invention is authorized, give the subject a concrete
+setting and action instead of filling the prompt with quality adjectives.
+
+Select the renderer that can produce the needed evidence:
+
+| Picture requirement | Useful route |
+| --- | --- |
+| Volumetric light, physical material, contact, perspective, architecture | Blender studio or Three scene |
+| Drawn contours, held drawings, flat shadow shapes, graphic composition | Canvas/p5/Two HTML scene |
+| Correct mathematical construction with deliberate teaching beats | Manim or checked deterministic Canvas geometry |
+| Photographic or painted source assets that procedural geometry cannot supply | Authorized Gateway image generation, then reviewed composition |
+| Photochemical finishing of an already convincing source | Existing ordered video-look effects, with restrained diffusion, grain, and vignette |
+
+A photo-textured background does not make moving geometry photorealistic. A
+Canvas material study does not demonstrate a physical clay simulation. Name the
+actual method in a portfolio caption.
+
+For creative delivery without specified dimensions, default to a native
+3840×2160 master or an equivalent frame in the intended aspect ratio when the
+renderer and source support it. Use explicit 1920×1080 previews for iteration.
+Respect source-image dimensions and a provider's actual output limits; state a
+lower native delivery clearly. Do not upscale a draft and call it native
+high-resolution detail. A 4:3 silent-film composition and a low-resolution pixel
+grid are deliberate exceptions to widescreen layout, not lower quality targets.
+
+## Historical film
+
+Choose a period and acquisition process before choosing damage. Early silent
+actuality, a 1940s studio negative, postwar 16mm documentary, and a 1970s home movie
+have different framing, motion, lighting, tonal latitude, and surface texture.
+Use a dated primary reference for specific history and label uncertain geometry
+or staging as interpretation. A source link beside an invented measurement does
+not verify that measurement.
+
+For an early street actuality:
+
+- Research street furniture, transport, overhead utilities, paving, clothing,
+  signage, and the sightline. Keep source-supported facts separate from estimated
+  dimensions and compressed geography. Inspect generated images for contradictions
+  even when the prompt explicitly forbids them. Do not add a familiar landmark or lamp
+  merely because it exists there today.
+- Stage a useful street depth: irregular storefront bays, window recesses,
+  cornices, varied reflectance, believable kerbs, contact shadows, and atmospheric
+  distance. Keep buildings from reading as identical extruded blocks.
+- Put the camera on the actual support, such as a cable car at a plausible human
+  height and speed. Keep distant geography coherent as it moves. Avoid a drone
+  orbit, wide modern lens, skyline reveal, or floating gimbal unless the reference
+  supports it.
+- Set capture cadence and playback cadence separately. A selected 16 fps
+  reconstruction is an artistic timing choice, not proof of the source camera's
+  exact crank speed. Hold drawings or photographed exposures deliberately; do
+  not interpolate every style to 60 fps.
+- Plan the monochrome values in the source. Early film spectral response cannot
+  be recovered by desaturating arbitrary modern colors. Make roofs, skin,
+  clothing, sky, and street separate in luminance; tune this against the reference.
+- Apply gentle highlight compression, optical softness, and restrained vignette
+  after the source works. Keep frame-varying grain fine enough to preserve facade
+  detail. Inspect wet surfaces, grain and stroke widths at final pixel size. Separate
+  visible sky brightness from ambient fill when a bright sky washes out contact
+  shadows; inspect material mapping on every visible face orientation.
+  Gate weave belongs to the entire image, not separate jittering objects.
+  Dirt and scratches are optional print wear, not the definition of old film.
+
+Distinguish capture, print, restoration, and scan. A clean high-resolution scan
+can retain fine texture and stable framing. Do not add heavy dust, crushed blacks,
+sepia, random flicker, letterbox bars, or a fake timecode by habit. Keep invented
+archival-looking footage labeled as an authored interpretation. A photographic
+plate with optical movement is a still-image study, not evidence of independently
+animated people, vehicles, or a historical event.
+
+The Market Street example includes a source manifest and an explicitly compressed
+street plan. Consult the Library of Congress film and SFMTA history linked in the
+example before changing its dates or street equipment.
+
+## Animation families
+
+An influence such as *Akira* or 3Blue1Brown is useful reference language. Translate
+it into mechanisms and create original subjects and compositions. The catalog
+uses generic technique names so the direction is reusable beyond one reference.
+
+| Family | Construct the image and movement | Reject at review |
+| --- | --- | --- |
+| Theatrical cel | Painted depth planes; precise perspective; selective contour weight; solid shadow shapes; articulated motion; held poses and short accents; camera motion sampled independently | Glossy toy materials, uniform outline filters, idle motion everywhere |
+| Watercolor storybook | Broad pigment washes, warm paper, lost edges, a focal patch of crisp ink, gentle overlapping action | A blur over vector art, evenly noisy outlines, identical texture on every object |
+| Ink sketch | Confident primary contours, sparse searching lines, directional hatching, selected line boil tied to held drawings | Unstable silhouettes, crosshatching through highlights, whole-scene wobble |
+| Rubber hose | Strong readable silhouette, curved limbs, arcs, anticipation, squash and stretch with volume awareness, clear contact | Random sine waves on every joint, sliding feet, impossible eye direction |
+| Midcentury limited | Asymmetric geometry, restrained spot palette, texture fields, selective held animation, strong negative space | Full constant motion, muddy colors, ornamental texture obscuring the subject |
+| Cut paper | Distinct cut contours, shallow layer separation, directional edge shadows, articulated pivots and reveal order | Universal blur, deep plastic bevels, disconnected shadows |
+| Stop-motion clay | Fingerprint-scale surface, soft contact, slightly imperfect construction, intentionally stepped poses and weighted settling | A smooth wobbling sphere described as physical stop motion, glossy uniform skin |
+| Pixel art | Explicit logical grid, limited palette, clustered shading, authored sprite poses, integer-aligned travel, nearest-neighbor integer scale | Blurred scaling, subpixel edges, unrestricted gradients, every object at a different pixel size |
+| Rotoscope | Gesture and weight from coherent anatomy, restrained contour drift, distinct held silhouettes, consistent volume | Unmotivated jitter, bendy joints, inconsistent limb lengths |
+| Engraving | Hatching follows form; line density describes value; leave highlights open; compose large black and white masses | Uniform screen-space stripe overlays or crushed unreadable detail |
+| Mathematical explanation | State one claim, assign stable colors, construct the relation, pause at its implication, keep notation readable | Decorative formulas, mismatched axes, moving labels, false equality, a waveform inconsistent with its generators |
+| Isometric design | Stable projection, consistent edge families, hierarchy through material and spacing, staged exploded movement | Conflicting vanishing points, changing scale, unrelated decorative labels |
+| Clean motion | A small set of shapes, optical alignment, purposeful easing, pauses, consistent transformation rules | Continuous bouncing, gratuitous overshoot, generic orbiting particles |
+
+Build the action from anticipation, main movement, follow-through, and a readable
+hold when those suit the style. Offset secondary action; avoid identical phase on
+every leaf or limb. Derive state from absolute frame time, with seeded variation
+keyed to the object and exposure index. Keep stable construction randomness
+separate from intentionally changing drawing or grain randomness. Seeking frames
+in a different order must reproduce the same image.
+
+## Review and retain
+
+Review representative frames before a full render: establishing view, strongest
+action, transition, and ending. Then inspect the encoded movie for timing,
+flicker, texture shimmer, crop, strobing, text, and compression. Pixel-level
+sharpness does not establish coherent art direction. A large output dimension
+does not establish source detail.
+
+For a portfolio, select different subjects and compositions that reveal each
+technique. Include the editable sources, profile IDs, actual output dimensions,
+render receipts, and honest renderer labels. Separate reusable direction from
+scene-specific drawing code. A contact sheet supports visual comparison; it does
+not replace checking motion. Preserve an old result when it explains a change.
+
+Keep bounded render jobs and their original sources. Dense grain can make a
+lossless intermediate exceed the existing media bound, especially at 4K. Shorten
+the shot or split it into retained takes without weakening that boundary. Do not
+retry an ambiguous native or paid generation before inspecting its retained state.