@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/src/app/starter-acceptance.motion-reference-ownership.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createMotionReferenceAcceptance,
+  createMotionReferenceBehavior,
+  createMotionReferenceInput,
+  createTimedMotionReferenceStudy,
+  getMotionReferenceErrors,
+  motionReferenceAcceptance,
+  motionReferenceId,
+} from "./starter-acceptance.motion-reference-test-utils";
+
+describe("Toolcraft motion reference acceptance ownership", () => {
+  it("requires one exact reverse acceptance coverage record", () => {
+    const input = createMotionReferenceInput();
+
+    expect(
+      getMotionReferenceErrors([input], [
+        createMotionReferenceAcceptance({ motionReferenceCoverage: [] }),
+      ]),
+    ).toContain(
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must own exactly one reverse coverage pair; found 0.',
+    );
+
+    const duplicateOwner = createMotionReferenceAcceptance({
+      id: "reference.anchor-retarget-duplicate",
+    });
+    expect(
+      getMotionReferenceErrors(
+        [input],
+        [motionReferenceAcceptance, duplicateOwner],
+      ),
+    ).toContain(
+      'motion reference behavior "delayed-retarget" coverage pair has 2 acceptance owners; expected exactly one.',
+    );
+  });
+
+  it("rejects dangling reverse acceptance coverage", () => {
+    const danglingAcceptance = createMotionReferenceAcceptance({
+      id: "reference.dangling-motion",
+      motionReferenceCoverage: [
+        { behaviorId: "missing-behavior", referenceId: motionReferenceId },
+      ],
+    });
+
+    expect(
+      getMotionReferenceErrors(
+        [createMotionReferenceInput()],
+        [motionReferenceAcceptance, danglingAcceptance],
+      ),
+    ).toContain(
+      `acceptance "reference.dangling-motion" has dangling motion reference coverage for "${motionReferenceId}" behavior "missing-behavior".`,
+    );
+  });
+
+  it("never selects a representative from ambiguous acceptance ids", () => {
+    const valid = createMotionReferenceAcceptance();
+    const malformed = createMotionReferenceAcceptance({
+      automated: false,
+      automatedTestName: "",
+      browser: false,
+      browserTestName: "",
+      expectedObservable: "",
+      motionReferenceCoverage: [],
+    });
+    const expected = [
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must describe its observable result.',
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must have automated coverage.',
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must have browser coverage.',
+      'motion reference behavior "delayed-retarget" acceptanceId "reference.anchor-retarget" resolves to 2 acceptance rows; expected exactly one.',
+    ];
+
+    expect(
+      getMotionReferenceErrors(
+        [createMotionReferenceInput()],
+        [valid, malformed],
+      ),
+    ).toEqual(expected);
+    expect(
+      getMotionReferenceErrors(
+        [createMotionReferenceInput()],
+        [malformed, valid],
+      ),
+    ).toEqual(expected);
+  });
+
+  it("does not let delimiter-shaped coverage pairs hide dangling ownership", () => {
+    const ownedReferenceId = "motion-reference-v1-control\u0000suffix" as const;
+    const danglingReferenceId = "motion-reference-v1-control" as const;
+    const ownedBehaviorId = "tail";
+    const danglingBehaviorId = "suffix\u0000tail";
+    const ownedAcceptance = createMotionReferenceAcceptance({
+      id: "reference.control-owner",
+      motionReferenceCoverage: [
+        { behaviorId: ownedBehaviorId, referenceId: ownedReferenceId },
+      ],
+    });
+    const danglingAcceptance = createMotionReferenceAcceptance({
+      id: "reference.control-dangling",
+      motionReferenceCoverage: [
+        { behaviorId: danglingBehaviorId, referenceId: danglingReferenceId },
+      ],
+    });
+    const behavior = createMotionReferenceBehavior({
+      acceptanceId: ownedAcceptance.id,
+      id: ownedBehaviorId,
+    });
+    const study = createTimedMotionReferenceStudy({ behaviorId: ownedBehaviorId });
+    const input = createMotionReferenceInput({
+      behaviors: [behavior],
+      referenceId: ownedReferenceId,
+      studies: [study],
+    });
+
+    expect(
+      getMotionReferenceErrors([input], [ownedAcceptance, danglingAcceptance]),
+    ).toContain(
+      `acceptance "reference.control-dangling" has dangling motion reference coverage for "${danglingReferenceId}" behavior "${danglingBehaviorId}".`,
+    );
+  });
+});

package/templates/starter/src/app/starter-acceptance.motion-reference-partitions.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+
+import type { ToolcraftMotionReferenceStudy } from "./acceptance/types";
+import {
+  createMotionReferenceInput,
+  createTimedMotionReferenceStudy,
+  getMotionReferenceErrors,
+  type MotionReviewPartition,
+  type MotionSegment,
+} from "./starter-acceptance.motion-reference-test-utils";
+
+const partitionBase = {
+  count: 2,
+  groupId: "motion-group-v1-partitioned-reference",
+  planSha256:
+    "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+  scope: { endSeconds: 4, startSeconds: 0 },
+} satisfies Omit<MotionReviewPartition, "index">;
+
+function createPartitionStudy({
+  count = partitionBase.count,
+  detectedLoopSeam = false,
+  index,
+  planSha256 = partitionBase.planSha256,
+  reviewPartition = true,
+  scope = partitionBase.scope,
+  segment,
+}: {
+  count?: number;
+  detectedLoopSeam?: boolean;
+  index: number;
+  planSha256?: string;
+  reviewPartition?: boolean;
+  scope?: MotionReviewPartition["scope"];
+  segment: MotionSegment;
+}): ToolcraftMotionReferenceStudy {
+  const studyId = `study-partition-${index}`;
+  return createTimedMotionReferenceStudy({
+    behaviorId: null,
+    detectedLoopSeam,
+    framePrefix: `p${index}-`,
+    pathId: studyId,
+    reviewPartition: reviewPartition
+      ? { count, groupId: partitionBase.groupId, index, planSha256, scope }
+      : undefined,
+    segment,
+    studyId,
+    withEvent: detectedLoopSeam,
+  });
+}
+
+function getPartitionErrors(
+  studies: readonly ToolcraftMotionReferenceStudy[],
+): string[] {
+  return getMotionReferenceErrors(
+    [createMotionReferenceInput({ behaviors: [], studies })],
+    [],
+  );
+}
+
+function createCompletePartition(): readonly ToolcraftMotionReferenceStudy[] {
+  return [
+    createPartitionStudy({
+      index: 0,
+      segment: { endSeconds: 2, startSeconds: 0 },
+    }),
+    createPartitionStudy({
+      index: 1,
+      segment: { endSeconds: 4, startSeconds: 2 },
+    }),
+  ];
+}
+
+describe("Toolcraft motion reference partitions", () => {
+  it("accepts an exact contiguous partition group in every input order", () => {
+    const studies = createCompletePartition();
+
+    expect(getPartitionErrors(studies)).toEqual([]);
+    expect(getPartitionErrors([...studies].reverse())).toEqual([]);
+  });
+
+  it("rejects an incomplete partition group", () => {
+    expect(getPartitionErrors([createCompletePartition()[0]])).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" count 2 cannot exceed group cardinality 1.',
+    );
+  });
+
+  it("rejects overlapping partition segments", () => {
+    expect(
+      getPartitionErrors([
+        createPartitionStudy({
+          index: 0,
+          segment: { endSeconds: 2, startSeconds: 0 },
+        }),
+        createPartitionStudy({
+          index: 1,
+          segment: { endSeconds: 4, startSeconds: 1.5 },
+        }),
+      ]),
+    ).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" segments must be contiguous and non-overlapping; index 1 starts at 1.5 after 2.',
+    );
+  });
+
+  it("validates count before deriving an index range or allocating by it", () => {
+    const invalidCounts = [0, 1.5, Number.POSITIVE_INFINITY];
+    for (const count of invalidCounts) {
+      expect(
+        getPartitionErrors([
+          createPartitionStudy({
+            count,
+            index: 0,
+            segment: { endSeconds: 4, startSeconds: 0 },
+          }),
+        ]),
+      ).toContain(
+        `motion reference partition "motion-group-v1-partitioned-reference" count must be a finite safe positive integer; received ${String(count)}.`,
+      );
+    }
+
+    expect(
+      getPartitionErrors([
+        createPartitionStudy({
+          count: Number.MAX_SAFE_INTEGER,
+          index: 0,
+          segment: { endSeconds: 4, startSeconds: 0 },
+        }),
+      ]),
+    ).toContain(
+      `motion reference partition "motion-group-v1-partitioned-reference" count ${Number.MAX_SAFE_INTEGER} cannot exceed group cardinality 1.`,
+    );
+  });
+
+  it("reports conflicting metadata canonically and skips dependent range checks", () => {
+    const studies = [
+      createPartitionStudy({
+        count: 2,
+        index: 0,
+        segment: { endSeconds: 3, startSeconds: 0 },
+      }),
+      createPartitionStudy({
+        count: 3,
+        index: 1,
+        planSha256:
+          "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        scope: { endSeconds: 5, startSeconds: 0 },
+        segment: { endSeconds: 4, startSeconds: 1 },
+      }),
+      createPartitionStudy({
+        count: 2,
+        index: 2,
+        segment: { endSeconds: 4, startSeconds: 3 },
+      }),
+    ];
+    const forward = getPartitionErrors(studies);
+    const reverse = getPartitionErrors([...studies].reverse());
+
+    expect(forward).toEqual(reverse);
+    expect(forward).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" studies must declare one shared count.',
+    );
+    expect(forward).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" studies must declare one shared planSha256.',
+    );
+    expect(forward).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" studies must declare one shared scope.',
+    );
+    expect(forward.some((error) => error.includes("segments must"))).toBe(false);
+  });
+
+  it("accepts semantically equal scopes regardless of key insertion order", () => {
+    expect(
+      getPartitionErrors([
+        createCompletePartition()[0],
+        createPartitionStudy({
+          index: 1,
+          scope: { startSeconds: 0, endSeconds: 4 },
+          segment: { endSeconds: 4, startSeconds: 2 },
+        }),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("allows the original full-source loop seam only in partition index zero", () => {
+    expect(
+      getPartitionErrors([
+        createCompletePartition()[0],
+        createPartitionStudy({
+          detectedLoopSeam: true,
+          index: 1,
+          segment: { endSeconds: 4, startSeconds: 2 },
+        }),
+      ]),
+    ).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" original loop-seam evidence must appear only in index 0.',
+    );
+  });
+
+  it("accepts one explicit unpartitioned segment as an intentional excerpt", () => {
+    expect(
+      getPartitionErrors([
+        createPartitionStudy({
+          index: 0,
+          reviewPartition: false,
+          segment: { endSeconds: 2, startSeconds: 1 },
+        }),
+      ]),
+    ).toEqual([]);
+  });
+});

package/templates/starter/src/app/starter-acceptance.motion-reference-test-utils.ts

@@ -0,0 +1,313 @@
+import { getToolcraftMotionReferenceStudyErrors } from "./acceptance/motion-reference-study";
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftMotionReferenceBehavior,
+  ToolcraftMotionReferenceEvidence,
+  ToolcraftMotionReferenceInput,
+  ToolcraftMotionReferenceOrdinalFrame,
+  ToolcraftMotionReferenceStudy,
+  ToolcraftMotionReferenceTimedFrame,
+  ToolcraftTransferMode,
+} from "./acceptance/types";
+
+export const motionReferenceId =
+  "motion-reference-v1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" as const;
+export const alternateMotionReferenceId =
+  "motion-reference-v1-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" as const;
+export const motionSourceSha256 =
+  "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+export const alternateMotionSourceSha256 =
+  "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+type TimedEvidence = Extract<
+  ToolcraftMotionReferenceEvidence,
+  { timingMode: "seconds" }
+>;
+export type MotionReviewPartition = NonNullable<
+  TimedEvidence["reviewPartition"]
+>;
+export type MotionSegment = NonNullable<TimedEvidence["segment"]>;
+
+export function createMotionReferenceAcceptance(
+  overrides: Partial<ToolcraftComponentAcceptance> = {},
+): ToolcraftComponentAcceptance {
+  return {
+    automated: true,
+    automatedTestName: "preserves planted-anchor retarget behavior",
+    browser: true,
+    browserTestName: "browser: preserves planted-anchor retarget behavior",
+    componentType: "custom-renderer",
+    evidence: "product-output",
+    expectedObservable: "Anchors remain planted before a delayed retarget.",
+    fixture: "motion reference evidence fixture",
+    id: "reference.anchor-retarget",
+    kind: "runtime",
+    motionReferenceCoverage: [
+      { behaviorId: "delayed-retarget", referenceId: motionReferenceId },
+    ],
+    target: "renderer.anchor-state",
+    userAction: "Compare the reference event with the running renderer.",
+    ...overrides,
+  };
+}
+
+export const motionReferenceAcceptance = createMotionReferenceAcceptance();
+
+export function createMotionReferenceBehavior(
+  overrides: Partial<ToolcraftMotionReferenceBehavior> = {},
+): ToolcraftMotionReferenceBehavior {
+  return {
+    acceptanceId: motionReferenceAcceptance.id,
+    description: "Anchors stay planted until stretch triggers a retarget.",
+    id: "delayed-retarget",
+    implementationIntent:
+      "Preserve contact memory and release anchors only after the observed stretch threshold.",
+    timingClaims: [{ claim: "duration", studyId: "study-main" }],
+    ...overrides,
+  };
+}
+
+export function createTimedMotionReferenceStudy({
+  behaviorId = "delayed-retarget",
+  detectedLoopSeam = false,
+  framePrefix = "",
+  pathId,
+  reviewPartition,
+  segment,
+  sourceBasename = "reference.mp4",
+  sourceSha256 = motionSourceSha256,
+  studyId = "study-main",
+  withEvent = true,
+}: {
+  behaviorId?: string | null;
+  detectedLoopSeam?: boolean;
+  framePrefix?: string;
+  pathId?: string;
+  reviewPartition?: MotionReviewPartition;
+  segment?: MotionSegment;
+  sourceBasename?: string;
+  sourceSha256?: string;
+  studyId?: string;
+  withEvent?: boolean;
+} = {}): ToolcraftMotionReferenceStudy {
+  const frameIds = [0, 1, 2, 3].map((index) => `${framePrefix}f${index}`);
+  const reviewedFrames: readonly ToolcraftMotionReferenceTimedFrame[] =
+    frameIds.map((frameId, index) => ({
+      cell: { column: index, row: 0 },
+      frameId,
+      sourceFrameIndex: index,
+      sourceLocator: `${sourceBasename}#frame=${index}`,
+      sourceSha256,
+      timeSeconds: index,
+    }));
+  const detectedEvents = !withEvent
+    ? []
+    : [
+        {
+          afterFrameId: frameIds[2],
+          beforeFrameId: frameIds[0],
+          eventId: `${framePrefix}machine-retarget`,
+          kind: detectedLoopSeam ? ("loop-seam" as const) : ("change" as const),
+          peakFrameId: frameIds[1],
+          score: 0.8,
+          windowFrameIds: frameIds.slice(0, 3),
+        },
+      ];
+  const evidence: TimedEvidence = {
+    changeMetric: "max-yuva-diff-v1",
+    contactSheet: {
+      columns: 4,
+      height: 180,
+      path: `src/app/reference-studies/${pathId ?? studyId}/contact-sheet.png`,
+      rows: 1,
+      sha256:
+        "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+      width: 320,
+    },
+    decodedFrameCount: 4,
+    detectedEvents,
+    durationSeconds: 4,
+    evidenceVersion: 1,
+    ffmpegVersion: "ffmpeg 8.0",
+    ffprobeVersion: "ffprobe 8.0",
+    focusWindows: [],
+    height: 180,
+    maximumSourceFrameGapSeconds: 1,
+    nominalFrameRate: 1,
+    overviewFrameIds: frameIds,
+    overviewTargetFps: 1,
+    reviewPartition,
+    reviewedFrames,
+    scannedFrameCount: 4,
+    segment,
+    sourceBasename,
+    sourceKind: "video",
+    sourceSha256,
+    studyId,
+    timing: { authority: "decoded-timestamps" },
+    timingMode: "seconds",
+    width: 320,
+  };
+  const events: ToolcraftMotionReferenceStudy["events"] = !withEvent
+    ? []
+    : behaviorId
+      ? [
+          {
+            behaviorIds: [behaviorId],
+            classification: "product-behavior",
+            evidenceEventId: `${framePrefix}machine-retarget`,
+            id: `${framePrefix}event-retarget`,
+          },
+        ]
+      : [
+          {
+            behaviorIds: [],
+            classification: "irrelevant-change",
+            evidenceEventId: `${framePrefix}machine-retarget`,
+            id: `${framePrefix}event-retarget`,
+            reason: "The event is outside product scope.",
+          },
+        ];
+
+  return {
+    evidence,
+    evidencePath: `src/app/reference-studies/${pathId ?? studyId}/evidence.json`,
+    events,
+    phases: [
+      {
+        behaviorIds: behaviorId ? [behaviorId] : [],
+        fromFrameId: frameIds[0],
+        id: `${framePrefix}phase-before`,
+        toFrameId: frameIds[1],
+        visualState: "Anchors remain planted while the body advances.",
+      },
+      {
+        behaviorIds: behaviorId ? [behaviorId] : [],
+        fromFrameId: frameIds[2],
+        id: `${framePrefix}phase-after`,
+        toFrameId: frameIds[3],
+        visualState: "Released anchors settle into their new positions.",
+      },
+    ],
+    studyId,
+  };
+}
+
+export function createOrdinalMotionReferenceStudy({
+  behaviorId = "delayed-retarget",
+  framePrefix = "o",
+  pathId,
+  sourceSha256 = motionSourceSha256,
+  studyId = "study-main",
+}: {
+  behaviorId?: string | null;
+  framePrefix?: string;
+  pathId?: string;
+  sourceSha256?: string;
+  studyId?: string;
+} = {}): ToolcraftMotionReferenceStudy {
+  const frameIds = [0, 1, 2, 3].map((index) => `${framePrefix}${index}`);
+  const reviewedFrames: readonly ToolcraftMotionReferenceOrdinalFrame[] =
+    frameIds.map((frameId, index) => ({
+      cell: { column: index, row: 0 },
+      frameId,
+      sourceFrameIndex: index,
+      sourceLocator: `reference-contact-sheet.png#cell=${index},0`,
+      sourceSha256,
+    }));
+  const directory = pathId ?? studyId;
+
+  return {
+    evidence: {
+      changeMetric: "max-yuva-diff-v1",
+      contactSheet: {
+        columns: 4,
+        height: 180,
+        path: `src/app/reference-studies/${directory}/contact-sheet.png`,
+        rows: 1,
+        sha256:
+          "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+        width: 320,
+      },
+      decodedFrameCount: 4,
+      detectedEvents: [],
+      evidenceVersion: 1,
+      ffmpegVersion: "ffmpeg 8.0",
+      ffprobeVersion: "ffprobe 8.0",
+      focusWindows: [],
+      height: 180,
+      overviewFrameIds: frameIds,
+      reviewedFrames,
+      scannedFrameCount: 4,
+      sourceBasename: "reference-contact-sheet.png",
+      sourceGrid: { columns: 4, rows: 1 },
+      sourceKind: "contact-sheet",
+      sourceSha256,
+      studyId,
+      timingMode: "ordinal",
+      width: 320,
+    },
+    evidencePath: `src/app/reference-studies/${directory}/evidence.json`,
+    events: [],
+    phases: [
+      {
+        behaviorIds: behaviorId ? [behaviorId] : [],
+        fromFrameId: frameIds[0],
+        id: `${framePrefix}-phase`,
+        toFrameId: frameIds[3],
+        visualState: "The referenced state remains visible.",
+      },
+    ],
+    studyId,
+  };
+}
+
+export function createMotionReferenceInput({
+  behaviors = [createMotionReferenceBehavior()],
+  referenceId = motionReferenceId,
+  studies = [createTimedMotionReferenceStudy()],
+}: {
+  behaviors?: readonly ToolcraftMotionReferenceBehavior[];
+  referenceId?: ToolcraftMotionReferenceInput["referenceId"];
+  studies?: readonly ToolcraftMotionReferenceStudy[];
+} = {}): ToolcraftMotionReferenceInput {
+  return { behaviors, kind: "motion-reference", referenceId, studies };
+}
+
+export function getMotionReferenceErrors(
+  referenceInputs: readonly ToolcraftMotionReferenceInput[],
+  acceptance: readonly ToolcraftComponentAcceptance[] = [
+    motionReferenceAcceptance,
+  ],
+): string[] {
+  const transferMode: ToolcraftTransferMode = {
+    animationIntent: { mode: "none" },
+    mode: "new-toolcraft-app",
+    referenceInputs,
+  };
+
+  return getToolcraftMotionReferenceStudyErrors({ acceptance, transferMode });
+}
+
+export function createPassiveMotionReferenceInput({
+  referenceId = alternateMotionReferenceId,
+  sourceSha256 = motionSourceSha256,
+}: {
+  referenceId?: ToolcraftMotionReferenceInput["referenceId"];
+  sourceSha256?: string;
+} = {}): ToolcraftMotionReferenceInput {
+  return createMotionReferenceInput({
+    behaviors: [],
+    referenceId,
+    studies: [
+      createTimedMotionReferenceStudy({
+        behaviorId: null,
+        framePrefix: "passive-",
+        pathId: "study-passive",
+        sourceSha256,
+        studyId: "study-passive",
+        withEvent: false,
+      }),
+    ],
+  });
+}