@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -0,0 +1,304 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import {
+  contractAcceptanceFixture,
+  contractSchemaFixture,
+  validateContractAcceptance,
+} from "./starter-acceptance.contract-fixtures";
+import { makeControlAcceptance } from "./starter-acceptance.test-utils";
+import {
+  makeReferenceCoverageAcceptance,
+  makeReferenceFeatureInventory,
+  referenceStudyEvidence,
+} from "./starter-acceptance.reference-test-utils";
+
+describe("starter acceptance reference-runtime foundation", () => {
+  it("requires explicit reference behavior coverage in reference-runtime-clone mode", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: contractAcceptanceFixture,
+        transferMode: {
+          behaviorCoverage: [
+            "canvas-sizing",
+            "control-mapping",
+            "renderer-state",
+            "renderer-loop",
+          ],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy badge wall",
+          sourceOfTruth: "reference-runtime",
+        } as never,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'reference-runtime-clone behaviorCoverage "canvas-sizing" is missing an acceptance entry with referenceCoverage "canvas-sizing".',
+        'reference-runtime-clone behaviorCoverage "control-mapping" is missing an acceptance entry with referenceCoverage "control-mapping".',
+        'reference-runtime-clone behaviorCoverage "renderer-state" is missing an acceptance entry with referenceCoverage "renderer-state".',
+        'reference-runtime-clone behaviorCoverage "renderer-loop" is missing an acceptance entry with referenceCoverage "renderer-loop".',
+        'reference-runtime-clone transferMode must declare referenceTimeline with mode "none", "toolcraft-playback", "toolcraft-keyframes", or "custom-reference-timeline".',
+      ]),
+    );
+  });
+
+  it("requires a reference feature inventory before accepting a reference-runtime-clone", () => {
+    const referenceAcceptance = [
+      ...contractAcceptanceFixture,
+      makeReferenceCoverageAcceptance("reference.canvasSizing", "canvas-sizing"),
+      makeReferenceCoverageAcceptance("reference.controlMapping", "control-mapping"),
+      makeReferenceCoverageAcceptance("reference.rendererState", "renderer-state"),
+    ];
+
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: referenceAcceptance,
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy badge wall",
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        "reference-runtime-clone transferMode must declare referenceFeatureInventory with every user-visible and output-affecting behavior from the inspected reference, mapped to Toolcraft implementation and acceptance coverage.",
+        'reference-runtime-clone behaviorCoverage "canvas-sizing" must be represented in referenceFeatureInventory by an item whose acceptanceId points to that referenceCoverage.',
+        'reference-runtime-clone behaviorCoverage "control-mapping" must be represented in referenceFeatureInventory by an item whose acceptanceId points to that referenceCoverage.',
+        'reference-runtime-clone behaviorCoverage "renderer-state" must be represented in referenceFeatureInventory by an item whose acceptanceId points to that referenceCoverage.',
+        "reference.canvasSizing declares reference coverage but is not mapped from referenceFeatureInventory. Every reference acceptance row must correspond to an inventoried reference feature.",
+      ]),
+    );
+  });
+
+  it("requires reference study evidence before accepting a reference-runtime-clone", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          makeReferenceCoverageAcceptance("reference.canvasSizing", "canvas-sizing"),
+          makeReferenceCoverageAcceptance("reference.controlMapping", "control-mapping"),
+          makeReferenceCoverageAcceptance("reference.rendererState", "renderer-state"),
+        ],
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceFeatureInventory: makeReferenceFeatureInventory(),
+          referenceName: "legacy badge wall",
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      "reference-runtime-clone transferMode must declare referenceStudy proving the reference was inspected and, when runnable or reconstructable, run or restored locally before implementation.",
+    );
+  });
+
+  it("requires a concrete blocker for source-only reference study", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          makeReferenceCoverageAcceptance("reference.canvasSizing", "canvas-sizing"),
+          makeReferenceCoverageAcceptance("reference.controlMapping", "control-mapping"),
+          makeReferenceCoverageAcceptance("reference.rendererState", "renderer-state"),
+        ],
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceFeatureInventory: makeReferenceFeatureInventory(),
+          referenceName: "legacy badge wall",
+          referenceStudy: {
+            ...referenceStudyEvidence,
+            sourceOnlyReason: "Source review was enough.",
+            status: "source-inspection-only",
+          },
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      "referenceStudy.sourceOnlyReason must state the concrete blocker that made running or restoring the reference unavailable.",
+    );
+  });
+
+  it("rejects reference feature inventory items that are not backed by reference acceptance coverage", () => {
+    const ordinaryControlAcceptance = makeControlAcceptance("appearance.opacity", "slider");
+
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          ordinaryControlAcceptance,
+          makeReferenceCoverageAcceptance("reference.controlMapping", "control-mapping"),
+          makeReferenceCoverageAcceptance("reference.rendererState", "renderer-state"),
+        ],
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceFeatureInventory: [
+            {
+              acceptanceId: "appearance.opacity",
+              behaviorEvidence: "Observed the reference browser output preserve its canvas dimensions.",
+              featureName: "Canvas sizing",
+              id: "canvas-sizing",
+              referenceBehavior: "The reference renderer owns output sizing and canvas dimensions.",
+              sourceEvidence: "Inspected reference renderer sizing source.",
+              status: "ported",
+              toolcraftMapping: "Toolcraft editable-output sizing preserves the reference dimensions.",
+            },
+            ...makeReferenceFeatureInventory().slice(1),
+          ],
+          referenceName: "legacy badge wall",
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'referenceFeatureInventory "canvas-sizing" acceptanceId "appearance.opacity" must point to an acceptance entry with referenceCoverage or referenceTimelineCoverage.',
+        'reference-runtime-clone behaviorCoverage "canvas-sizing" must be represented in referenceFeatureInventory by an item whose acceptanceId points to that referenceCoverage.',
+      ]),
+    );
+  });
+
+  it("requires feature-level behavior evidence for reference inventory items", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          makeReferenceCoverageAcceptance("reference.canvasSizing", "canvas-sizing"),
+          makeReferenceCoverageAcceptance("reference.controlMapping", "control-mapping"),
+          makeReferenceCoverageAcceptance("reference.rendererState", "renderer-state"),
+        ],
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceFeatureInventory: [
+            { ...makeReferenceFeatureInventory()[0], behaviorEvidence: "" },
+            ...makeReferenceFeatureInventory().slice(1),
+          ],
+          referenceName: "legacy badge wall",
+          referenceStudy: referenceStudyEvidence,
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      'referenceFeatureInventory "canvas-sizing" must include behaviorEvidence from the original, restored, or source-only reference study proving this feature was observed before Toolcraft mapping.',
+    );
+  });
+
+  it("requires explicit user evidence before marking reference behavior intentionally changed", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          makeReferenceCoverageAcceptance("reference.canvasSizing", "canvas-sizing"),
+          makeReferenceCoverageAcceptance("reference.controlMapping", "control-mapping"),
+          makeReferenceCoverageAcceptance("reference.rendererState", "renderer-state"),
+        ],
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceFeatureInventory: [
+            {
+              ...makeReferenceFeatureInventory()[0],
+              status: "intentionally-changed",
+              userApprovedChangeReason: "Cleaner implementation.",
+            },
+            ...makeReferenceFeatureInventory().slice(1),
+          ],
+          referenceName: "legacy badge wall",
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      'referenceFeatureInventory "canvas-sizing" userApprovedChangeReason must cite explicit user approval or redesign/change-request evidence.',
+    );
+  });
+
+  it("rejects reference-runtime-clone apps that disable the Toolcraft canvas shell", () => {
+    const schemaWithoutCanvas = defineToolcraft({
+      canvas: {
+        enabled: false,
+        size: { height: 720, unit: "px", width: 1280 },
+      },
+      panels: {},
+      toolbar: {
+        history: false,
+        radar: false,
+        theme: false,
+        zoom: false,
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithoutCanvas,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            automated: true,
+            automatedTestName: "reference canvas size matches legacy renderer",
+            browser: true,
+            browserTestName: "browser: reference canvas size matches legacy renderer",
+            componentType: "custom-renderer",
+            evidence: "rendered-pixels",
+            expectedObservable: "The Toolcraft renderer uses the same output dimensions as the reference runtime.",
+            fixture: "legacy renderer fixture",
+            id: "reference.canvasSizing",
+            kind: "runtime",
+            referenceCoverage: "canvas-sizing",
+            userAction: "Render the reference-sized output.",
+          },
+          {
+            automated: true,
+            automatedTestName: "reference control mapping preserves legacy output",
+            browser: true,
+            browserTestName: "browser: reference control mapping preserves legacy output",
+            componentType: "custom-renderer",
+            evidence: "product-output",
+            expectedObservable: "Changing each mapped control updates the same renderer parameter as the reference app.",
+            fixture: "legacy controls fixture",
+            id: "reference.controlMapping",
+            kind: "runtime",
+            referenceCoverage: "control-mapping",
+            userAction: "Change mapped controls and compare reference output behavior.",
+          },
+          {
+            automated: true,
+            automatedTestName: "reference renderer state preserves legacy lifecycle",
+            browser: true,
+            browserTestName: "browser: reference renderer state preserves legacy lifecycle",
+            componentType: "custom-renderer",
+            evidence: "product-output",
+            expectedObservable: "The renderer preserves the reference runtime mutable state lifecycle across frames.",
+            fixture: "legacy renderer state fixture",
+            id: "reference.rendererState",
+            kind: "runtime",
+            referenceCoverage: "renderer-state",
+            userAction: "Run the renderer across frames and compare stateful output.",
+          },
+        ],
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy iframe shell",
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      "reference-runtime-clone must keep the Toolcraft canvas shell enabled; preserve the reference renderer inside ToolcraftApp canvasContent instead of replacing the app with the original UI.",
+    );
+  });
+});

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

@@ -0,0 +1,102 @@
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftReferenceCoverage,
+  ToolcraftReferenceFeatureInventoryItem,
+  ToolcraftReferenceStudyEvidence,
+  ToolcraftReferenceTimelineCoverage,
+} from "./acceptance/types";
+
+export const referenceStudyEvidence = {
+  behaviorEvidence:
+    "Ran the original app in a local browser and checked canvas sizing, controls, and renderer state changes.",
+  referenceLocation: "/fixtures/legacy-badge-wall",
+  reproductionSteps:
+    "Installed dependencies, started the reference app, opened it in the browser, and compared behavior against the port.",
+  sourceEvidence:
+    "Inspected reference routes, renderer, control state, export handlers, and media lifecycle source files.",
+  status: "ran-original",
+} satisfies ToolcraftReferenceStudyEvidence;
+
+export function makeReferenceFeatureInventory(
+  extra: readonly ToolcraftReferenceFeatureInventoryItem[] = [],
+): readonly ToolcraftReferenceFeatureInventoryItem[] {
+  return [
+    {
+      acceptanceId: "reference.canvasSizing",
+      behaviorEvidence:
+        "Observed the reference output keep its authored dimensions in the browser.",
+      featureName: "Canvas sizing",
+      id: "canvas-sizing",
+      referenceBehavior: "The reference renderer owns the output dimensions.",
+      sourceEvidence: "Inspected reference renderer sizing and browser output.",
+      status: "ported",
+      toolcraftMapping:
+        "Toolcraft editable-output canvas starts from the reference dimensions and keeps runtime sizing visible.",
+    },
+    {
+      acceptanceId: "reference.controlMapping",
+      behaviorEvidence:
+        "Changed reference controls in the browser and observed renderer parameters update.",
+      featureName: "Control mapping",
+      id: "control-mapping",
+      referenceBehavior: "Reference controls update renderer parameters directly.",
+      sourceEvidence: "Inspected reference control state and parameter wiring.",
+      status: "ported",
+      toolcraftMapping:
+        "Toolcraft schema controls write runtime values consumed by the renderer.",
+    },
+    {
+      acceptanceId: "reference.rendererState",
+      behaviorEvidence:
+        "Observed reference renderer state persist across multiple animation frames.",
+      featureName: "Renderer state",
+      id: "renderer-state",
+      referenceBehavior: "Reference renderer mutable state persists across frames.",
+      sourceEvidence: "Inspected reference renderer lifecycle and frame updates.",
+      status: "ported",
+      toolcraftMapping:
+        "Toolcraft renderer keeps equivalent mutable state and invalidation lifecycle.",
+    },
+    ...extra,
+  ];
+}
+
+export function makeReferenceCoverageAcceptance(
+  id: string,
+  referenceCoverage: ToolcraftReferenceCoverage,
+): ToolcraftComponentAcceptance {
+  return {
+    automated: true,
+    automatedTestName: `${id} preserves reference behavior`,
+    browser: true,
+    browserTestName: `browser: ${id} preserves reference behavior`,
+    componentType: "custom-renderer",
+    evidence: "product-output",
+    expectedObservable: `${id} preserves the reference behavior in Toolcraft output.`,
+    fixture: `${id} fixture`,
+    id,
+    kind: "runtime",
+    referenceCoverage,
+    userAction: `Exercise ${id}.`,
+  };
+}
+
+export function makeReferenceTimelineCoverageAcceptance(
+  id: string,
+  referenceTimelineCoverage: ToolcraftReferenceTimelineCoverage,
+): ToolcraftComponentAcceptance {
+  return {
+    automated: true,
+    automatedTestName: `${id} preserves reference timeline behavior`,
+    browser: true,
+    browserTestName: `browser: ${id} preserves reference timeline behavior`,
+    componentType: "custom-timeline",
+    evidence: "timeline-output",
+    expectedObservable: `${id} preserves the reference timeline behavior.`,
+    fixture: `${id} fixture`,
+    id,
+    kind: "runtime",
+    referenceTimelineCoverage,
+    userAction: `Exercise ${id}.`,
+  };
+}

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

@@ -0,0 +1,267 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  contractAcceptanceFixture,
+  contractSchemaFixture,
+  validateContractAcceptance,
+} from "./starter-acceptance.contract-fixtures";
+import {
+  keyframesTimelineAcceptance,
+  playbackTimelineAcceptance,
+} from "./starter-acceptance.timeline-test-utils";
+import {
+  makeReferenceFeatureInventory,
+  referenceStudyEvidence,
+} from "./starter-acceptance.reference-test-utils";
+
+describe("starter acceptance reference timeline contract", () => {
+  it("accepts reference-runtime-clone mode only when required reference behavior is test-backed", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            automated: true,
+            automatedTestName: "reference canvas size matches legacy renderer",
+            browser: true,
+            browserTestName: "browser: reference canvas size matches legacy renderer",
+            componentType: "custom-renderer",
+            evidence: "rendered-pixels",
+            expectedObservable: "The Toolcraft renderer uses the same output dimensions as the reference runtime.",
+            fixture: "legacy renderer fixture",
+            id: "reference.canvasSizing",
+            kind: "runtime",
+            referenceCoverage: "canvas-sizing",
+            userAction: "Render the reference-sized output.",
+          },
+          {
+            automated: true,
+            automatedTestName: "reference control mapping preserves legacy output",
+            browser: true,
+            browserTestName: "browser: reference control mapping preserves legacy output",
+            componentType: "custom-renderer",
+            evidence: "product-output",
+            expectedObservable: "Changing each mapped control updates the same renderer parameter as the reference app.",
+            fixture: "legacy controls fixture",
+            id: "reference.controlMapping",
+            kind: "runtime",
+            referenceCoverage: "control-mapping",
+            userAction: "Change mapped controls and compare reference output behavior.",
+          },
+          {
+            automated: true,
+            automatedTestName: "reference renderer state preserves legacy lifecycle",
+            browser: true,
+            browserTestName: "browser: reference renderer state preserves legacy lifecycle",
+            componentType: "custom-renderer",
+            evidence: "product-output",
+            expectedObservable: "The renderer preserves the reference runtime mutable state lifecycle across frames.",
+            fixture: "legacy renderer state fixture",
+            id: "reference.rendererState",
+            kind: "runtime",
+            referenceCoverage: "renderer-state",
+            userAction: "Run the renderer across frames and compare stateful output.",
+          },
+        ],
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceFeatureInventory: makeReferenceFeatureInventory(),
+          referenceName: "legacy badge wall",
+          referenceStudy: referenceStudyEvidence,
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it("requires reference clones with pause resume behavior to choose a non-none timeline mode", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: contractAcceptanceFixture,
+        transferMode: {
+          behaviorCoverage: [
+            "canvas-sizing",
+            "control-mapping",
+            "renderer-state",
+            "pause-resume",
+          ],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy pause animation",
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      'reference-runtime-clone transport behaviorCoverage "pause-resume" requires referenceTimeline mode "toolcraft-playback", "toolcraft-keyframes", or "custom-reference-timeline"; mode "none" is only for references with no user-facing transport behavior.',
+    );
+  });
+
+  it("rejects reference clones that hide restart transport behind timeline none", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: contractAcceptanceFixture,
+        transferMode: {
+          behaviorCoverage: [
+            "canvas-sizing",
+            "control-mapping",
+            "renderer-state",
+            "restart",
+            "time-progress",
+          ],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy restart animation",
+          referenceTimeline: { behaviorCoverage: [], mode: "none" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      'reference-runtime-clone transport behaviorCoverage "restart", "time-progress" requires referenceTimeline mode "toolcraft-playback", "toolcraft-keyframes", or "custom-reference-timeline"; mode "none" is only for references with no user-facing transport behavior.',
+    );
+  });
+
+  it("requires playback reference timelines to declare concrete behavior coverage", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: contractAcceptanceFixture,
+        transferMode: {
+          behaviorCoverage: ["canvas-sizing", "control-mapping", "renderer-state"],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy playback animation",
+          referenceTimeline: { behaviorCoverage: [], mode: "toolcraft-playback" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      'referenceTimeline mode "toolcraft-playback" must list the concrete timeline transport behaviors in behaviorCoverage.',
+    );
+  });
+
+  it("requires Toolcraft reference playback timelines to declare loop duration provenance", () => {
+    const schemaWithPlaybackTimeline = {
+      ...contractSchemaFixture,
+      panels: {
+        ...contractSchemaFixture.panels,
+        timeline: { defaultDurationSeconds: 8, enabled: true, mode: "playback" as const },
+      },
+    };
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithPlaybackTimeline,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            ...playbackTimelineAcceptance,
+            id: "reference.timeline.playback",
+            referenceTimelineCoverage: "playback",
+          },
+        ],
+        transferMode: {
+          behaviorCoverage: [
+            "canvas-sizing",
+            "control-mapping",
+            "renderer-state",
+            "pause-resume",
+          ],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy playback animation",
+          referenceTimeline: { behaviorCoverage: ["playback"], mode: "toolcraft-playback" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      'referenceTimeline mode "toolcraft-playback" must declare loopDuration with source, seconds, and evidence. Do not let runtime/template fallback duration such as 8s stand in for reference loop intent.',
+    );
+  });
+
+  it("requires Toolcraft reference timeline loop duration to match the timeline default", () => {
+    const schemaWithPlaybackTimeline = {
+      ...contractSchemaFixture,
+      panels: {
+        ...contractSchemaFixture.panels,
+        timeline: { defaultDurationSeconds: 8, enabled: true, mode: "playback" as const },
+      },
+    };
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithPlaybackTimeline,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            ...playbackTimelineAcceptance,
+            id: "reference.timeline.playback",
+            referenceTimelineCoverage: "playback",
+          },
+        ],
+        transferMode: {
+          behaviorCoverage: [
+            "canvas-sizing",
+            "control-mapping",
+            "renderer-state",
+            "pause-resume",
+          ],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy playback animation",
+          referenceTimeline: {
+            behaviorCoverage: ["playback"],
+            loopDuration: {
+              evidence: "The reference app completes one seamless forward playback cycle over 6s.",
+              seconds: 6,
+              source: "reference",
+            },
+            mode: "toolcraft-playback",
+          },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      "panels.timeline.defaultDurationSeconds (8) must match referenceTimeline.loopDuration.seconds (6).",
+    );
+  });
+
+  it("requires Toolcraft reference keyframe timelines to declare loop duration provenance", () => {
+    const schemaWithKeyframesTimeline = {
+      ...contractSchemaFixture,
+      panels: {
+        ...contractSchemaFixture.panels,
+        timeline: { defaultDurationSeconds: 8, enabled: true, mode: "keyframes" as const },
+      },
+    };
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithKeyframesTimeline,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          playbackTimelineAcceptance,
+          {
+            ...keyframesTimelineAcceptance,
+            id: "reference.timeline.keyframes",
+            referenceTimelineCoverage: "keyframes",
+          },
+        ],
+        transferMode: {
+          behaviorCoverage: [
+            "canvas-sizing",
+            "control-mapping",
+            "renderer-state",
+            "time-progress",
+          ],
+          mode: "reference-runtime-clone",
+          referenceName: "legacy keyframe animation",
+          referenceTimeline: { behaviorCoverage: ["keyframes"], mode: "toolcraft-keyframes" },
+          sourceOfTruth: "reference-runtime",
+        },
+      }),
+    ).toContain(
+      'referenceTimeline mode "toolcraft-keyframes" must declare loopDuration with source, seconds, and evidence. Do not let runtime/template fallback duration such as 8s stand in for reference loop intent.',
+    );
+  });
+});