@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/src/app/starter-acceptance.video-reference-study.test.ts

@@ -1,262 +1,60 @@
 import { describe, expect, it } from "vitest";
 
-import type {
-  ToolcraftComponentAcceptance,
-  ToolcraftVideoReferenceStudyEvidence,
-} from "./acceptance/types";
 import {
+  contractAcceptanceFixture,
   contractSchemaFixture,
-  defineContractSchemaFixture,
+  contractTransferModeFixture,
   validateContractAcceptance,
 } from "./starter-acceptance.contract-fixtures";
-import {
-  playbackTimelineAcceptance,
-} from "./starter-acceptance.timeline-test-utils";
-
-const videoReferenceMotionAcceptance: ToolcraftComponentAcceptance = {
-  automated: true,
-  automatedTestName: "video reference motion matches frame delta study",
-  browser: true,
-  browserTestName: "browser: video reference motion matches frame delta study",
-  componentType: "custom-renderer",
-  evidence: "product-output",
-  expectedObservable:
-    "The renderer preserves the video reference behavior observed across the storyboard transitions.",
-  fixture: "video reference storyboard fixture",
-  id: "reference.video.motion",
-  kind: "runtime",
-  target: "reference.video.motion",
-  userAction:
-    "Compare the implemented renderer against the storyboard frames and frame-to-frame behavior deltas.",
-};
-
-const videoReferenceStudyEvidence = {
-  acceptanceMapping: [
-    {
-      acceptanceId: "reference.video.motion",
-      behavior: "Planted contact points stretch across adjacent frames before retargeting.",
-      frameIds: ["f000", "f012", "f024"],
-    },
-  ],
-  behaviorDecomposition:
-    "The video reference is decomposed into body movement, persistent contact points, delayed release, and retargeted anchors. The implementation copies those behaviors rather than a single static frame.",
-  extractionEvidence:
-    "Extracted frames with ffmpeg and reviewed contact sheets before implementation.",
-  referenceLocation: "/fixtures/reference-motion/ref.mp4",
-  storyboard: [
-    {
-      behaviorObservation:
-        "Body starts moving while several endpoints remain planted in canvas space.",
-      frameId: "f000",
-      frameSource: "frames/frame_000.png",
-      timeSeconds: 0,
-      visualObservation: "The body is near the left side with legs extended outward.",
-    },
-    {
-      behaviorObservation:
-        "Body advances and planted endpoints stretch instead of following immediately.",
-      frameId: "f012",
-      frameSource: "frames/frame_012.png",
-      timeSeconds: 0.2,
-      visualObservation: "Several endpoints stay near the earlier canvas positions.",
-    },
-    {
-      behaviorObservation:
-        "Over-extended legs begin to release and choose new anchors.",
-      frameId: "f024",
-      frameSource: "frames/frame_024.png",
-      timeSeconds: 0.4,
-      visualObservation: "One side shows a retargeted leg group closer to the body.",
-    },
-    {
-      behaviorObservation:
-        "The new anchor pattern stabilizes before the next release.",
-      frameId: "f036",
-      frameSource: "frames/frame_036.png",
-      timeSeconds: 0.6,
-      visualObservation: "Legs settle into a new spread with the body further right.",
-    },
-  ],
-  transitionAnalysis: [
-    {
-      behaviorDelta:
-        "Between f000 and f012, body position changes faster than several leg endpoints, proving contact memory.",
-      fromFrameId: "f000",
-      id: "f000-f012",
-      toFrameId: "f012",
-    },
-    {
-      behaviorDelta:
-        "Between f012 and f024, over-extension triggers release and retargeting instead of continuous sine motion.",
-      fromFrameId: "f012",
-      id: "f012-f024",
-      toFrameId: "f024",
-    },
-    {
-      behaviorDelta:
-        "Between f024 and f036, newly planted anchors remain stable while the body keeps moving.",
-      fromFrameId: "f024",
-      id: "f024-f036",
-      toFrameId: "f036",
-    },
-  ],
-} satisfies ToolcraftVideoReferenceStudyEvidence;
-
-function createPlaybackTimelineSchema(durationSeconds = 5.8) {
-  return {
-    ...contractSchemaFixture,
-    panels: {
-      ...contractSchemaFixture.panels,
-      timeline: {
-        defaultDurationSeconds: durationSeconds,
-        enabled: true,
-        mode: "playback" as const,
-      },
-    },
-  };
-}
-
-describe("starter acceptance video reference study contract", () => {
-  it("requires video reference study when a new app cites video reference evidence", () => {
-    expect(
-      validateContractAcceptance({
-        schema: createPlaybackTimelineSchema(),
-        acceptance: [playbackTimelineAcceptance],
-        transferMode: {
-          animationIntent: {
-            loopDuration: {
-              evidence: "The source reference video /fixtures/reference-motion/ref.mp4 was inspected for motion behavior.",
-              seconds: 5.8,
-              source: "reference",
-            },
-            mode: "timeline-playback",
-          },
-          mode: "new-toolcraft-app",
-        },
-      }),
-    ).toContain(
-      "starterTransferMode cites a video reference, screen recording, GIF, extracted frames, or contact sheet; declare videoReferenceStudy with storyboard frames, frame-to-frame transition analysis, behavior decomposition, and acceptance mapping before implementation.",
-    );
-  });
-
-  it("does not require video reference study for ordinary video export intent", () => {
-    const schemaWithPlaybackTimeline = defineContractSchemaFixture({
-      canvas: {
-        enabled: true,
-        upload: true,
-      },
-      panels: {
-        controls: {
-          sections: [],
-          title: "Controls",
-        },
-        timeline: { defaultDurationSeconds: 6, enabled: true, mode: "playback" as const },
-      },
-      toolbar: {
-        history: true,
-        radar: true,
-        zoom: true,
-      },
-    });
-
-    expect(
-      validateContractAcceptance({
-        schema: schemaWithPlaybackTimeline,
-        acceptance: [playbackTimelineAcceptance],
-        transferMode: {
-          animationIntent: {
-            loopDuration: {
-              evidence: "The product timing model derives a six second cycle for exported video output.",
-              seconds: 6,
-              source: "product-derived",
-            },
-            mode: "timeline-playback",
-          },
-          mode: "new-toolcraft-app",
-        },
-      }),
-    ).toEqual([]);
-  });
-
-  it("accepts a new app video reference only with storyboard and transition acceptance mapping", () => {
-    const schemaWithPlaybackTimeline = defineContractSchemaFixture({
-      canvas: {
-        enabled: true,
-        upload: true,
-      },
-      panels: {
-        controls: {
-          sections: [],
-          title: "Controls",
-        },
-        timeline: { defaultDurationSeconds: 5.8, enabled: true, mode: "playback" as const },
-      },
-      toolbar: {
-        history: true,
-        radar: true,
-        zoom: true,
-      },
-    });
 
+describe("starter acceptance motion reference pipeline", () => {
+  it("does not infer reference authority from prose when referenceInputs is explicitly empty", () => {
     expect(
       validateContractAcceptance({
-        schema: schemaWithPlaybackTimeline,
-        acceptance: [playbackTimelineAcceptance, videoReferenceMotionAcceptance],
+        acceptance: contractAcceptanceFixture,
+        schema: contractSchemaFixture,
         transferMode: {
+          ...contractTransferModeFixture,
           animationIntent: {
-            loopDuration: {
-              evidence: "The source reference timing comes from the inspected motion reference asset.",
-              seconds: 5.8,
-              source: "reference",
-            },
-            mode: "timeline-playback",
+            mode: "autonomous",
+            behaviorCoverage: [
+              "no-duration-control",
+              "no-export-at-time",
+              "no-loop-control",
+              "no-play-pause",
+              "no-scrub",
+              "no-user-facing-transport",
+            ],
+            reason:
+              "A decorative loop happens to mention an inspected video but owns no product time transport.",
           },
-          mode: "new-toolcraft-app",
-          videoReferenceStudy: videoReferenceStudyEvidence,
+          referenceInputs: [],
         },
       }),
     ).toEqual([]);
   });
 
-  it("rejects incomplete video reference studies", () => {
+  it("routes explicit normalized reference inputs through the semantic validator", () => {
     expect(
       validateContractAcceptance({
+        acceptance: contractAcceptanceFixture,
         schema: contractSchemaFixture,
-        acceptance: [],
         transferMode: {
-          mode: "new-toolcraft-app",
-          videoReferenceStudy: {
-            acceptanceMapping: [
-              {
-                acceptanceId: "missing.acceptance",
-                behavior: "Motion behavior",
-                frameIds: ["f001"],
-              },
-            ],
-            behaviorDecomposition: "",
-            extractionEvidence: "",
-            referenceLocation: "/fixtures/reference-motion/ref.mp4",
-            storyboard: [
-              {
-                behaviorObservation: "Only one frame was inspected.",
-                frameId: "f001",
-                frameSource: "frames/frame_001.png",
-                timeSeconds: 0,
-                visualObservation: "A single static state.",
-              },
-            ],
-            transitionAnalysis: [],
-          },
+          ...contractTransferModeFixture,
+          referenceInputs: [
+            {
+              behaviors: [],
+              kind: "motion-reference",
+              referenceId:
+                "motion-reference-v1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+              studies: [],
+            },
+          ],
         },
       }),
-    ).toEqual(
-      expect.arrayContaining([
-        "videoReferenceStudy.extractionEvidence must explain how frames were inspected or extracted before implementation.",
-        "videoReferenceStudy.behaviorDecomposition must decompose the observed frame-to-frame changes into product behavior to preserve.",
-        "videoReferenceStudy.storyboard must include at least four timecoded frames so the reference is studied as motion, not a single screenshot.",
-        "videoReferenceStudy.transitionAnalysis must include at least three frame-to-frame deltas proving how behavior changes between sampled frames.",
-        'videoReferenceStudy.acceptanceMapping "Motion behavior" points to missing acceptanceId "missing.acceptance".',
-      ]),
+    ).toContain(
+      'motion reference "motion-reference-v1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" must declare at least one study.',
     );
   });
+
 });

package/templates/starter/src/app/starter-acceptance.view-interaction.test.ts

@@ -20,6 +20,7 @@ const defaultPose = {
 const noAnimation: ToolcraftTransferMode = {
   animationIntent: { mode: "none" },
   mode: "new-toolcraft-app",
+  referenceInputs: [],
 };
 
 const timelineAnimation: ToolcraftTransferMode = {
@@ -32,12 +33,18 @@ const timelineAnimation: ToolcraftTransferMode = {
     mode: "timeline-playback",
   },
   mode: "new-toolcraft-app",
+  referenceInputs: [],
 };
 
 function createProductReadiness(
   viewInteraction: ToolcraftViewInteractionIntent,
 ): ToolcraftProductReadiness {
   return {
+    exportIntent: {
+      image: { mode: "toolcraft-default" },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
     interactionOwnership: [],
     mode: "product",
     productName: "Spatial fixture",
@@ -111,6 +118,11 @@ function createSchema({
 describe("Toolcraft spatial view interaction intent", () => {
   it("rejects stale product readiness that omits the typed intent", () => {
     const productReadiness = {
+      exportIntent: {
+        image: { mode: "toolcraft-default" },
+        svg: { mode: "not-requested" },
+        video: { mode: "not-requested" },
+      },
       mode: "product",
       productName: "Legacy fixture",
       productSummary: "An old product declaration.",

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

@@ -13,6 +13,9 @@ import {
 import {
   TOOLCRAFT_DELIVERY_VERIFICATION_COMMAND,
 } from "../../scripts/toolcraft-performance-authority-policy.mjs";
+import type {
+  ToolcraftMotionReferenceTimingMode,
+} from "./acceptance/types";
 
 const appDir = dirname(fileURLToPath(import.meta.url));
 const projectDir = join(appDir, "../..");
@@ -92,10 +95,21 @@ export type AgentWorklogFixtureOptions = {
   trailHeading?: string;
   verificationLines?: readonly string[];
 };
+export type WorklogMotionReference = Readonly<{
+  contactSheetPath: string;
+  referenceId: string;
+  requiresRealTimeReview: boolean;
+  requiresSlowedReview: boolean;
+  sourceSha256: string;
+  studyId: string;
+  timingMode: ToolcraftMotionReferenceTimingMode;
+}>;
 const worklogVideoReferencePattern =
   /\b(?:source\/reference checked|source reviewed|reference inputs):[^\n]*(?:reference\s+(?:video|gif)|screen\s*recording|contact[-\s]*sheet|storyboard|frame[-\s]*by[-\s]*frame|extracted[-\s]*frames?|cleanshot|ffprobe|[^\s]+\.(?:mp4|mov|webm|gif))\b/i;
-const worklogVideoReferenceStudyPattern =
-  /\b(video reference study|storyboard|frame[-\s]*by[-\s]*frame|transition analysis|frame[-\s]*to[-\s]*frame|contact[-\s]*sheet|extracted frames?)\b/i;
+const motionReferenceRecordPattern =
+  /^\s*[-*]\s+Motion reference study:\s*(?<fields>\S.*)$/iu;
+const motionReferenceFieldPattern =
+  /\b(?<name>referenceId|studyId|sourceSha256|timingMode|contactSheetPath|review)=(?<value>[^;]+?)(?=;\s*|$)/giu;
 export function readToolcraftDoc(relativePath: string): string {
   return readFileSync(join(projectDir, "docs/toolcraft", relativePath), "utf8");
 }
@@ -252,8 +266,96 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-export function getAgentWorklogValidationErrors(source: string): string[] {
+type MotionReferenceRecord = Readonly<{
+  contactSheetPath?: string;
+  referenceId?: string;
+  review?: string;
+  sourceSha256?: string;
+  studyId?: string;
+  timingMode?: string;
+}>;
+
+function getAuthoritativeWorklogSource(source: string): string {
+  return requiredAgentWorklogSections
+    .map((section) => getMarkdownSectionBody(source, section))
+    .join("\n");
+}
+
+function getMotionReferenceRecords(
+  authoritativeSource: string,
+): readonly MotionReferenceRecord[] {
+  return authoritativeSource.split(/\r?\n/u).flatMap((line) => {
+    const recordMatch = motionReferenceRecordPattern.exec(line);
+    if (!recordMatch?.groups?.fields) return [];
+
+    const fields: Record<string, string> = {};
+    for (const match of recordMatch.groups.fields.matchAll(
+      motionReferenceFieldPattern,
+    )) {
+      if (!match.groups) continue;
+      fields[match.groups.name] = match.groups.value
+        .trim()
+        .replace(/[.]$/u, "");
+    }
+    return [fields];
+  });
+}
+
+function recordMatchesMotionReference(
+  record: MotionReferenceRecord,
+  motionReference: WorklogMotionReference,
+): boolean {
+  if (
+    record.contactSheetPath !== motionReference.contactSheetPath ||
+    record.referenceId !== motionReference.referenceId ||
+    record.sourceSha256 !== motionReference.sourceSha256 ||
+    record.studyId !== motionReference.studyId ||
+    record.timingMode !== motionReference.timingMode
+  ) {
+    return false;
+  }
+
+  const reviewModes = new Set(
+    (record.review ?? "")
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+  if (motionReference.timingMode === "ordinal") {
+    return (
+      reviewModes.has("ordered-frames") &&
+      !reviewModes.has("real-time") &&
+      !reviewModes.has("slowed")
+    );
+  }
+  if (
+    (motionReference.timingMode === "seconds" ||
+      motionReference.requiresRealTimeReview) &&
+    !reviewModes.has("real-time")
+  ) {
+    return false;
+  }
+  return (
+    !motionReference.requiresSlowedReview || reviewModes.has("slowed")
+  );
+}
+
+function describeRequiredReview(motionReference: WorklogMotionReference): string {
+  if (motionReference.timingMode === "ordinal") return "ordered-frames";
+  return motionReference.requiresSlowedReview
+    ? "real-time,slowed"
+    : "real-time";
+}
+
+export function getAgentWorklogValidationErrors(
+  source: string,
+  options: Readonly<{
+    motionReferences?: readonly WorklogMotionReference[];
+  }> = {},
+): string[] {
   const errors: string[] = [];
+  const motionReferences = options.motionReferences ?? [];
+  const authoritativeSource = getAuthoritativeWorklogSource(source);
 
   for (const section of requiredAgentWorklogSections) {
     if (!getMarkdownSectionBody(source, section)) {
@@ -315,11 +417,25 @@ export function getAgentWorklogValidationErrors(source: string): string[] {
   }
 
   if (
-    worklogVideoReferencePattern.test(source) &&
-    !worklogVideoReferenceStudyPattern.test(source)
+    worklogVideoReferencePattern.test(authoritativeSource) &&
+    motionReferences.length === 0
   ) {
     errors.push(
-      "agent-worklog.md cites a video reference, screen recording, GIF, extracted frames, or contact sheet; record a Video Reference Study with storyboard frames and frame-to-frame transition analysis.",
+      "agent-worklog.md cites a video reference, screen recording, GIF, extracted frames, or contact sheet, but starterTransferMode.referenceInputs registers no motion reference input.",
+    );
+  }
+
+  const motionReferenceRecords = getMotionReferenceRecords(authoritativeSource);
+  for (const motionReference of motionReferences) {
+    if (
+      motionReferenceRecords.some((record) =>
+        recordMatchesMotionReference(record, motionReference),
+      )
+    ) {
+      continue;
+    }
+    errors.push(
+      `agent-worklog.md motion reference study "${motionReference.studyId}" for reference "${motionReference.referenceId}" must include one exact "Motion reference study:" record with referenceId=${motionReference.referenceId}; studyId=${motionReference.studyId}; sourceSha256=${motionReference.sourceSha256}; timingMode=${motionReference.timingMode}; contactSheetPath=${motionReference.contactSheetPath}; review=${describeRequiredReview(motionReference)}.`,
     );
   }