@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/scripts/toolcraft-motion-reference-command-options.test.mjs

@@ -0,0 +1,224 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  parseToolcraftMotionReferenceArgs,
+  resolveToolcraftMotionReferenceOptions,
+  resolveToolcraftMotionReferenceSourceKind,
+} from "./toolcraft-motion-reference-command-options.mjs";
+import {
+  applyToolcraftMotionDeclaredImageTiming,
+} from "./toolcraft-motion-reference-image-timing.mjs";
+import {
+  formatToolcraftMotionReferenceError,
+  ToolcraftMotionReferenceInputError,
+} from "./toolcraft-motion-reference-stage.mjs";
+
+const source = path.resolve("/refs/reference.mkv");
+
+async function publicFailure(run) {
+  let error;
+  try {
+    await run();
+  } catch (caught) {
+    error = caught;
+  }
+  assert.ok(error instanceof ToolcraftMotionReferenceInputError);
+  const message = formatToolcraftMotionReferenceError(error);
+  assert.ok(message.length <= 180);
+  assert.equal(message.includes("/Users/private"), false);
+  assert.equal(message.includes("captured stderr"), false);
+  return message;
+}
+
+test("accepts the one leading package-manager argument separator", () => {
+  assert.deepEqual(parseToolcraftMotionReferenceArgs([
+    "--", "--source", source, "--kind", "video",
+  ]), { kind: "video", source });
+});
+
+test("parses the complete timed command surface without doing I/O", () => {
+  const parsed = parseToolcraftMotionReferenceArgs([
+    "--source", path.resolve("/refs/frames"), "--kind", "frame-sequence",
+    "--focus", "1:2.5",
+    "--focus", "3:4", "--segment", "0:5", "--fps", "30",
+  ]);
+  assert.deepEqual(parsed, {
+    focus: [{ endSeconds: 2.5, startSeconds: 1 },
+      { endSeconds: 4, startSeconds: 3 }],
+    framesPerSecond: 30,
+    kind: "frame-sequence",
+    segment: { endSeconds: 5, startSeconds: 0 },
+    source: path.resolve("/refs/frames"),
+  });
+});
+
+test("parses contact-sheet structure and an absolute timestamp authority", () => {
+  const timestampsFile = path.resolve("/refs/times.json");
+  assert.deepEqual(parseToolcraftMotionReferenceArgs([
+    "--source", path.resolve("/refs/sheet.png"), "--kind", "contact-sheet",
+    "--grid", "6x4", "--timestamps-file", timestampsFile,
+  ]), {
+    grid: { columns: 6, rows: 4 },
+    kind: "contact-sheet",
+    source: path.resolve("/refs/sheet.png"),
+    timestampsFile,
+  });
+});
+
+test("rejects missing values, unknown flags, repeated singletons, and relative paths", () => {
+  for (const [argv, expected] of [
+    [[], /source.*required/iu],
+    [["--source"], /requires a value/iu],
+    [["--source", source, "--wat", "x"], /use only|supported/iu],
+    [["--source", source, "--source", source], /single-value.*once/iu],
+    [["--source", "relative.mp4"], /absolute/iu],
+    [["--source", source, "--timestamps-file", "times.json"], /absolute/iu],
+  ]) assert.throws(() => parseToolcraftMotionReferenceArgs(argv), expected);
+});
+
+test("rejects malformed values and incompatible flag combinations", () => {
+  const sheet = path.resolve("/refs/sheet.png");
+  for (const [argv, expected] of [
+    [["--source", source, "--kind", "movie"], /kind/iu],
+    [["--source", source, "--focus", "2:1"], /focus.*range/iu],
+    [["--source", source, "--segment", "a:2"], /segment.*range/iu],
+    [["--source", source, "--fps", "0"], /fps.*positive/iu],
+    [["--source", source, "--fps", "30", "--timestamps-file", path.resolve("/t")],
+      /one timing authority/iu],
+    [["--source", source, "--kind", "video", "--grid", "2x2"],
+      /grid.*contact-sheet/iu],
+    [["--source", sheet, "--kind", "contact-sheet"], /grid.*required/iu],
+    [["--source", sheet, "--kind", "contact-sheet", "--grid", "0x2"],
+      /grid/iu],
+    [["--source", source, "--kind", "video", "--fps", "30"],
+      /timing.*image/iu],
+  ]) assert.throws(() => parseToolcraftMotionReferenceArgs(argv), expected);
+});
+
+test("infers only GIFs, supported timed containers, and directories", async () => {
+  assert.equal(await resolveToolcraftMotionReferenceSourceKind(
+    parseToolcraftMotionReferenceArgs(["--source", path.resolve("/refs/a.gif")]),
+    { stat: async () => ({ isDirectory: () => false }) },
+  ), "gif");
+  assert.equal(await resolveToolcraftMotionReferenceSourceKind(
+    parseToolcraftMotionReferenceArgs(["--source", source]),
+    { stat: async () => ({ isDirectory: () => false }) },
+  ), "video");
+  assert.equal(await resolveToolcraftMotionReferenceSourceKind(
+    parseToolcraftMotionReferenceArgs(["--source", path.resolve("/refs/frames")]),
+    { stat: async () => ({ isDirectory: () => true }) },
+  ), "frame-sequence");
+  await assert.rejects(() => resolveToolcraftMotionReferenceSourceKind(
+    parseToolcraftMotionReferenceArgs(["--source", path.resolve("/refs/a.png")]),
+    { stat: async () => ({ isDirectory: () => false }) },
+  ), /explicit.*kind/iu);
+});
+
+test("preserves explicit screen-recording semantics instead of guessing it", async () => {
+  const parsed = parseToolcraftMotionReferenceArgs([
+    "--source", source, "--kind", "screen-recording",
+  ]);
+  assert.equal(await resolveToolcraftMotionReferenceSourceKind(parsed),
+    "screen-recording");
+});
+
+test("resolves declared FPS timing and bounds segment and focus to inspection", async () => {
+  const parsed = parseToolcraftMotionReferenceArgs([
+    "--source", path.resolve("/refs/frames"), "--kind", "frame-sequence",
+    "--fps", "2", "--segment", "0:1.5", "--focus", "0.5:1",
+  ]);
+  const inspection = await applyToolcraftMotionDeclaredImageTiming({
+    decodedFrameCount: 4, sourceKind: "frame-sequence", timingMode: "ordinal",
+  }, parsed);
+  assert.deepEqual(await resolveToolcraftMotionReferenceOptions(parsed, inspection), {
+    ...parsed,
+    kind: "frame-sequence",
+    timing: {
+      authority: "declared-fps", frameTimes: [0, 0.5, 1, 1.5],
+      framesPerSecond: 2,
+    },
+  });
+  await assert.rejects(() => resolveToolcraftMotionReferenceOptions({
+    ...parsed, focus: [{ endSeconds: 2.1, startSeconds: 1 }],
+  }, inspection),
+  /focus.*duration/iu);
+});
+
+test("rejects ranges expressed in a shifted source's original PTS domain", async () => {
+  const parsed = parseToolcraftMotionReferenceArgs([
+    "--source", source, "--kind", "video", "--segment", "5:6",
+  ]);
+  await assert.rejects(() => resolveToolcraftMotionReferenceOptions(parsed, {
+    decodedFrameCount: 60,
+    durationSeconds: 2,
+    sourceKind: "video",
+    timingMode: "seconds",
+  }), /segment.*duration/iu);
+});
+
+test("derives the inspected duration when FPS turns an ordinal image source timed", async () => {
+  const parsed = parseToolcraftMotionReferenceArgs([
+    "--source", path.resolve("/refs/frames"), "--kind", "frame-sequence",
+    "--fps", "2", "--segment", "0:2", "--focus", "1:2",
+  ]);
+  const inspection = await applyToolcraftMotionDeclaredImageTiming({
+    decodedFrameCount: 4, sourceKind: "frame-sequence", timingMode: "ordinal",
+  }, parsed);
+  const resolved = await resolveToolcraftMotionReferenceOptions(parsed, inspection);
+  assert.deepEqual(resolved.timing.frameTimes, [0, 0.5, 1, 1.5]);
+});
+
+test("rejects timed-only ranges on ordinal image evidence", async () => {
+  const parsed = parseToolcraftMotionReferenceArgs([
+    "--source", path.resolve("/refs/frames"), "--kind", "frame-sequence",
+    "--focus", "0:1",
+  ]);
+  await assert.rejects(() => resolveToolcraftMotionReferenceOptions(parsed, {
+    decodedFrameCount: 3, sourceKind: "frame-sequence", timingMode: "ordinal",
+  }), /focus.*timing authority/iu);
+});
+
+test("rejects declared image timing when an omitted kind resolves to media", async () => {
+  const parsed = parseToolcraftMotionReferenceArgs([
+    "--source", source, "--fps", "30",
+  ]);
+  await assert.rejects(() => resolveToolcraftMotionReferenceOptions(parsed, {
+    decodedFrameCount: 3, durationSeconds: 0.1, sourceKind: "video",
+    timingMode: "seconds",
+  }), /timing.*image/iu);
+});
+
+test("checked public input errors expose bounded corrections without source details", async () => {
+  const secretSource = "/Users/private/reference.png";
+  assert.match(await publicFailure(() => parseToolcraftMotionReferenceArgs([])),
+    /--source.*absolute/iu);
+  assert.match(await publicFailure(() => parseToolcraftMotionReferenceArgs([
+    "--source", secretSource, "--kind", "contact-sheet", "--grid", "0x2",
+  ])), /--grid.*positive/iu);
+  assert.match(await publicFailure(() => parseToolcraftMotionReferenceArgs([
+    "--source", secretSource, "--focus", "2:1",
+  ])), /--focus.*start:end/iu);
+  assert.match(await publicFailure(() => parseToolcraftMotionReferenceArgs([
+    "--source", secretSource, "--kind", "private-kind",
+  ])), /--kind.*video.*frame-sequence/iu);
+  assert.match(await publicFailure(() => resolveToolcraftMotionReferenceSourceKind(
+    parseToolcraftMotionReferenceArgs(["--source", secretSource]),
+    { stat: async () => { throw new Error(`captured stderr ${secretSource}`); } },
+  )), /--source.*readable/iu);
+  assert.match(await publicFailure(() => applyToolcraftMotionDeclaredImageTiming({
+    decodedFrameCount: 2,
+    sourceKind: "frame-sequence",
+    timingMode: "ordinal",
+  }, { timestampsFile: secretSource }, {
+    readFile: async () => Buffer.from("captured stderr {"),
+  })), /timestamps.*JSON.*increasing/iu);
+  assert.match(await publicFailure(() => applyToolcraftMotionDeclaredImageTiming({
+    decodedFrameCount: 1,
+    sourceKind: "frame-sequence",
+    timingMode: "ordinal",
+  }, { timestampsFile: secretSource }, {
+    readFile: async () => Buffer.from("[10]\n"),
+  })), /at least two.*timestamps.*duration|timestamps.*at least two.*duration/iu);
+});

package/templates/starter/scripts/toolcraft-motion-reference-contact-sheet.mjs

@@ -0,0 +1,122 @@
+import { runToolcraftMotionStage } from "./toolcraft-motion-reference-stage.mjs";
+import {
+  TOOLCRAFT_MOTION_REFERENCE_STAGES,
+} from "./toolcraft-motion-reference-stage-registry.mjs";
+
+function fail(message) {
+  throw new TypeError(`Invalid Toolcraft motion reference contact sheet: ${message}`);
+}
+
+function validateInput({ execute, frames, outputPath, sourceHeight, sourceWidth }) {
+  if (typeof execute !== "function") fail("an executor is required");
+  if (!Array.isArray(frames) || frames.length === 0) fail("at least one frame is required");
+  if (!Number.isInteger(sourceWidth) || sourceWidth <= 0 ||
+      !Number.isInteger(sourceHeight) || sourceHeight <= 0) {
+    fail("positive integer source dimensions are required");
+  }
+  if (typeof outputPath !== "string" || outputPath.length === 0) {
+    fail("an output PNG path is required");
+  }
+  const seen = new Set();
+  frames.forEach((frame) => {
+    if (!Number.isInteger(frame?.sourceFrameIndex) || frame.sourceFrameIndex < 0) {
+      fail("every sourceFrameIndex must be a nonnegative integer");
+    }
+    if (seen.has(frame.sourceFrameIndex)) fail("sourceFrameIndex values must be unique");
+    seen.add(frame.sourceFrameIndex);
+    if (typeof frame.path !== "string" || frame.path.length === 0) {
+      fail("every normalized PNG record must have a path");
+    }
+    if (typeof frame.sourceLocator !== "string" || frame.sourceLocator.length === 0) {
+      fail("every normalized PNG record must have a source locator");
+    }
+  });
+}
+
+function createLayout(frameCount, sourceWidth, sourceHeight) {
+  const sourceAspectRatio = sourceWidth / sourceHeight;
+  const columns = Math.ceil(Math.sqrt(frameCount * sourceAspectRatio));
+  const rows = Math.ceil(frameCount / columns);
+  const initialCellWidth = Math.min(480, sourceWidth);
+  const initialCellHeight = Math.max(1,
+    Math.round(initialCellWidth / sourceAspectRatio));
+  const initialWidth = columns * initialCellWidth;
+  const initialHeight = rows * initialCellHeight;
+  const scale = Math.min(1, 6000 / initialWidth, 6000 / initialHeight);
+  const cellWidth = Math.max(1, Math.floor(initialCellWidth * scale));
+  const cellHeight = Math.max(1, Math.floor(initialCellHeight * scale));
+  return {
+    cellHeight,
+    cellWidth,
+    columns,
+    height: rows * cellHeight,
+    rows,
+    width: columns * cellWidth,
+  };
+}
+
+function createCells(frames, layout) {
+  return frames.map(({ sourceFrameIndex }, ordinal) => {
+    const column = ordinal % layout.columns;
+    const row = Math.floor(ordinal / layout.columns);
+    return {
+      column,
+      frameId: `source-frame:${sourceFrameIndex}`,
+      height: layout.cellHeight,
+      row,
+      sourceFrameIndex,
+      width: layout.cellWidth,
+      x: column * layout.cellWidth,
+      y: row * layout.cellHeight,
+    };
+  });
+}
+
+function filterGraph(frames, cells, layout) {
+  const barHeight = Math.min(28, layout.cellHeight);
+  const barY = layout.cellHeight - barHeight;
+  const labelX = Math.min(8, layout.cellWidth - 1);
+  const prepared = frames.map((frame, index) => {
+    const label = `source-frame\\:${frame.sourceFrameIndex}`;
+    return `[${index}:v]scale=${layout.cellWidth}:${layout.cellHeight}:` +
+      "force_original_aspect_ratio=decrease," +
+      `pad=${layout.cellWidth}:${layout.cellHeight}:(ow-iw)/2:(oh-ih)/2:black,` +
+      `drawbox=x=0:y=${barY}:w=${layout.cellWidth}:h=${barHeight}:` +
+      "color=black@0.65:t=fill," +
+      `drawtext=text='${label}':x=${labelX}:y=${barY}:` +
+      "fontcolor=white:fontsize=16" +
+      `[frame${index}]`;
+  });
+  if (frames.length === 1) return `${prepared[0]};[frame0]null[sheet]`;
+  const inputs = frames.map((_, index) => `[frame${index}]`).join("");
+  const positions = cells.map(({ x, y }) => `${x}_${y}`).join("|");
+  return `${prepared.join(";")};${inputs}xstack=inputs=${frames.length}:` +
+    `layout=${positions}:fill=black[sheet]`;
+}
+
+export async function createToolcraftMotionReferenceContactSheet(input) {
+  validateInput(input);
+  const layout = createLayout(
+    input.frames.length, input.sourceWidth, input.sourceHeight,
+  );
+  const cells = createCells(input.frames, layout);
+  const args = [
+    "-loglevel", "error",
+    ...input.frames.flatMap(({ path }) => ["-i", path]),
+    "-filter_complex", filterGraph(input.frames, cells, layout),
+    "-map", "[sheet]", "-frames:v", "1", "-y", input.outputPath,
+  ];
+  await runToolcraftMotionStage(input.execute, {
+    args,
+    binary: "ffmpeg",
+    stage: TOOLCRAFT_MOTION_REFERENCE_STAGES.contactSheet,
+  });
+  return {
+    cells,
+    columns: layout.columns,
+    height: layout.height,
+    outputPath: input.outputPath,
+    rows: layout.rows,
+    width: layout.width,
+  };
+}

package/templates/starter/scripts/toolcraft-motion-reference-contact-sheet.test.mjs

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createToolcraftMotionReferenceContactSheet,
+} from "./toolcraft-motion-reference-contact-sheet.mjs";
+
+function frames(count) {
+  return Array.from({ length: count }, (_, sourceFrameIndex) => ({
+    path: `/tmp/review/review-${String(sourceFrameIndex).padStart(6, "0")}.png`,
+    sourceFrameIndex,
+    sourceLocator: `reference.mov#frame=${sourceFrameIndex}`,
+    timeSeconds: sourceFrameIndex / 30,
+  }));
+}
+function fakeExecutor(result = { stdout: "" }) {
+  const calls = [];
+  return {
+    calls,
+    execute: async (request) => {
+      calls.push(request);
+      return result;
+    },
+  };
+}
+
+test("lays out normalized PNG frames row-major with stable labels", async () => {
+  const executor = fakeExecutor();
+  const result = await createToolcraftMotionReferenceContactSheet({
+    execute: executor.execute,
+    frames: frames(4),
+    outputPath: "/tmp/contact-sheet.png",
+    sourceHeight: 900,
+    sourceWidth: 1600,
+  });
+
+  assert.deepEqual({
+    columns: result.columns,
+    height: result.height,
+    rows: result.rows,
+    width: result.width,
+  }, { columns: 3, height: 540, rows: 2, width: 1440 });
+  assert.deepEqual(result.cells, [
+    { column: 0, frameId: "source-frame:0", height: 270, row: 0,
+      sourceFrameIndex: 0, width: 480, x: 0, y: 0 },
+    { column: 1, frameId: "source-frame:1", height: 270, row: 0,
+      sourceFrameIndex: 1, width: 480, x: 480, y: 0 },
+    { column: 2, frameId: "source-frame:2", height: 270, row: 0,
+      sourceFrameIndex: 2, width: 480, x: 960, y: 0 },
+    { column: 0, frameId: "source-frame:3", height: 270, row: 1,
+      sourceFrameIndex: 3, width: 480, x: 0, y: 270 },
+  ]);
+  assert.equal(result.outputPath, "/tmp/contact-sheet.png");
+  assert.equal(executor.calls.length, 1);
+  assert.equal(executor.calls[0].binary, "ffmpeg");
+  assert.equal(executor.calls[0].stage, "contact-sheet");
+  assert.match(executor.calls[0].args.join(" "), /source-frame\\:0/u);
+});
+
+test("caps the starting cell width at the source width", async () => {
+  const executor = fakeExecutor();
+  const result = await createToolcraftMotionReferenceContactSheet({
+    execute: executor.execute,
+    frames: frames(2),
+    outputPath: "/tmp/contact-sheet.png",
+    sourceHeight: 200,
+    sourceWidth: 320,
+  });
+
+  assert.deepEqual({
+    cellHeight: result.cells[0].height,
+    cellWidth: result.cells[0].width,
+    height: result.height,
+    width: result.width,
+  }, { cellHeight: 200, cellWidth: 320, height: 200, width: 640 });
+  assert.match(executor.calls[0].args[executor.calls[0].args.indexOf("-filter_complex") + 1],
+    /drawbox=x=0:y=172:w=320:h=28/iu);
+});
+
+test("uses numeric drawbox geometry and clamps its bar for tiny cells", async () => {
+  const executor = fakeExecutor();
+  await createToolcraftMotionReferenceContactSheet({
+    execute: executor.execute,
+    frames: frames(1),
+    outputPath: "/tmp/tiny.png",
+    sourceHeight: 10,
+    sourceWidth: 320,
+  });
+  const graph = executor.calls[0].args[
+    executor.calls[0].args.indexOf("-filter_complex") + 1
+  ];
+
+  assert.equal(graph,
+    "[0:v]scale=320:10:force_original_aspect_ratio=decrease," +
+    "pad=320:10:(ow-iw)/2:(oh-ih)/2:black," +
+    "drawbox=x=0:y=0:w=320:h=10:color=black@0.65:t=fill," +
+    "drawtext=text='source-frame\\:0':x=8:y=0:fontcolor=white:fontsize=16" +
+    "[frame0];[frame0]null[sheet]");
+});
+
+test("uniformly scales cells down so neither final dimension exceeds 6000", async () => {
+  const result = await createToolcraftMotionReferenceContactSheet({
+    execute: fakeExecutor().execute,
+    frames: frames(225),
+    outputPath: "/tmp/contact-sheet.png",
+    sourceHeight: 120,
+    sourceWidth: 480,
+  });
+
+  assert.ok(result.width <= 6000);
+  assert.ok(result.height <= 6000);
+  assert.equal(result.columns, 30);
+  assert.equal(result.rows, 8);
+  assert.ok(result.cells[0].width < 480);
+  assert.equal(result.cells[0].width / result.cells[0].height, 4);
+});
+
+test("rejects invalid counts, dimensions, indices, and empty PNG records", async () => {
+  const valid = {
+    execute: fakeExecutor().execute,
+    frames: frames(1),
+    outputPath: "/tmp/contact-sheet.png",
+    sourceHeight: 100,
+    sourceWidth: 100,
+  };
+  await assert.rejects(() => createToolcraftMotionReferenceContactSheet({
+    ...valid, frames: [],
+  }), /frame/iu);
+  await assert.rejects(() => createToolcraftMotionReferenceContactSheet({
+    ...valid, sourceWidth: 0,
+  }), /dimensions/iu);
+  await assert.rejects(() => createToolcraftMotionReferenceContactSheet({
+    ...valid, frames: [{ ...frames(1)[0], sourceFrameIndex: -1 }],
+  }), /sourceFrameIndex/iu);
+  await assert.rejects(() => createToolcraftMotionReferenceContactSheet({
+    ...valid, frames: [{ ...frames(1)[0], path: "" }],
+  }), /PNG/iu);
+});
+
+test("normalizes executor failure at the contact-sheet stage", async () => {
+  const cause = new Error("opaque process failure");
+  await assert.rejects(
+    () => createToolcraftMotionReferenceContactSheet({
+      execute: fakeExecutor({ exitCode: 7, error: cause }).execute,
+      frames: frames(1),
+      outputPath: "/tmp/contact-sheet.png",
+      sourceHeight: 100,
+      sourceWidth: 100,
+    }),
+    (error) => error.name === "ToolcraftMotionReferenceStageError" &&
+      error.stage === "contact-sheet" && error.cause === cause,
+  );
+});