@pixel-point/toolcraft 0.0.18 → 0.0.19

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

@@ -0,0 +1,90 @@
+import { validateBehaviorCoverage } from "./motion-reference-study-behaviors";
+import { validateStudyCoverage } from "./motion-reference-study-coverage";
+import {
+  getMotionReferenceSourceSha256,
+  validateStudyIdentity,
+} from "./motion-reference-study-identity";
+import { validatePartitionCoverage } from "./motion-reference-study-partitions";
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftTransferMode,
+} from "./types";
+
+export function getToolcraftMotionReferenceStudyErrors({
+  acceptance,
+  transferMode,
+}: {
+  acceptance: readonly ToolcraftComponentAcceptance[];
+  transferMode: ToolcraftTransferMode;
+}): string[] {
+  const errors: string[] = [];
+  const acceptanceRowsById = new Map<string, ToolcraftComponentAcceptance[]>();
+  for (const entry of acceptance) {
+    acceptanceRowsById.set(entry.id, [
+      ...(acceptanceRowsById.get(entry.id) ?? []),
+      entry,
+    ]);
+  }
+  const referenceIds = new Set<string>();
+  const sourceOwners = new Map<string, string>();
+  const behaviorCountsByReferenceId = new Map<string, Map<string, number>>();
+
+  for (const input of transferMode.referenceInputs) {
+    if (referenceIds.has(input.referenceId)) {
+      errors.push(`motion reference id "${input.referenceId}" is duplicated.`);
+    }
+    referenceIds.add(input.referenceId);
+
+    errors.push(
+      ...validateStudyIdentity(input),
+      ...validateStudyCoverage(input),
+      ...validatePartitionCoverage(input),
+      ...validateBehaviorCoverage(input, acceptanceRowsById),
+    );
+
+    const sourceSha256 = getMotionReferenceSourceSha256(input);
+    if (sourceSha256) {
+      const existingOwner = sourceOwners.get(sourceSha256);
+      if (existingOwner) {
+        errors.push(
+          `motion reference sourceSha256 "${sourceSha256}" is declared by multiple reference inputs; merge their studies under one input.`,
+        );
+      } else {
+        sourceOwners.set(sourceSha256, input.referenceId);
+      }
+    }
+
+    const behaviorCounts =
+      behaviorCountsByReferenceId.get(input.referenceId) ??
+      new Map<string, number>();
+    for (const behavior of input.behaviors) {
+      behaviorCounts.set(
+        behavior.id,
+        (behaviorCounts.get(behavior.id) ?? 0) + 1,
+      );
+    }
+    behaviorCountsByReferenceId.set(input.referenceId, behaviorCounts);
+  }
+
+  for (const acceptanceEntry of acceptance) {
+    for (const coverage of acceptanceEntry.motionReferenceCoverage ?? []) {
+      const behaviorCount =
+        behaviorCountsByReferenceId
+          .get(coverage.referenceId)
+          ?.get(coverage.behaviorId) ?? 0;
+      if (behaviorCount === 0) {
+        errors.push(
+          `acceptance "${acceptanceEntry.id}" has dangling motion reference coverage for "${coverage.referenceId}" behavior "${coverage.behaviorId}".`,
+        );
+      } else if (behaviorCount > 1) {
+        errors.push(
+          `acceptance "${acceptanceEntry.id}" motion reference coverage for "${coverage.referenceId}" behavior "${coverage.behaviorId}" resolves to ${behaviorCount} behavior definitions; expected exactly one.`,
+        );
+      }
+    }
+  }
+
+  return [...new Set(errors)].sort((left, right) =>
+    left.localeCompare(right, "en"),
+  );
+}

package/templates/starter/src/app/acceptance/output-export-actions.test.ts

@@ -3,6 +3,7 @@ import { defineToolcraft } from "@repo/toolcraft-runtime";
 
 import {
   schemaHasPngExportPanelAction,
+  schemaHasSvgExportPanelAction,
   schemaHasVideoExportPanelAction,
 } from "./output-export-actions";
 
@@ -16,6 +17,11 @@ function createOutputSchema() {
             controls: {
               output: {
                 actions: [
+                  {
+                    label: "Guardar vector",
+                    role: "export-svg",
+                    value: "salida.vector",
+                  },
                   {
                     label: "Guardar imagen",
                     role: "export-image",
@@ -41,10 +47,11 @@ function createOutputSchema() {
 }
 
 describe("Toolcraft typed output action roles", () => {
-  it("detects image and video export without parsing labels or values", () => {
+  it("detects image, SVG, and video export without parsing labels or values", () => {
     const schema = createOutputSchema();
 
     expect(schemaHasPngExportPanelAction(schema)).toBe(true);
+    expect(schemaHasSvgExportPanelAction(schema)).toBe(true);
     expect(schemaHasVideoExportPanelAction(schema)).toBe(true);
   });
 
@@ -71,6 +78,7 @@ describe("Toolcraft typed output action roles", () => {
     });
 
     expect(schemaHasPngExportPanelAction(schema)).toBe(false);
+    expect(schemaHasSvgExportPanelAction(schema)).toBe(false);
     expect(schemaHasVideoExportPanelAction(schema)).toBe(false);
   });
 });

package/templates/starter/src/app/acceptance/output-export-actions.ts

@@ -1,34 +1,26 @@
 import type {
   ResolvedToolcraftAppSchema,
-  ToolcraftActionSchema,
+  ToolcraftArtifactExportActionRole,
 } from "@repo/toolcraft-runtime";
+import { getToolcraftArtifactExportActions } from "@repo/toolcraft-runtime";
 
-import { getControlActions } from "./actions";
-
-function actionLooksLikePngExport(action: ToolcraftActionSchema | string): boolean {
-  return typeof action !== "string" && action.role === "export-image";
+function schemaHasExportPanelAction(
+  schema: ResolvedToolcraftAppSchema,
+  role: ToolcraftArtifactExportActionRole,
+): boolean {
+  return getToolcraftArtifactExportActions(schema).some(
+    (action) => action.role === role,
+  );
 }
 
-function actionLooksLikeVideoExport(action: ToolcraftActionSchema | string): boolean {
-  return typeof action !== "string" && action.role === "export-video";
+export function schemaHasPngExportPanelAction(schema: ResolvedToolcraftAppSchema): boolean {
+  return schemaHasExportPanelAction(schema, "export-image");
 }
 
-export function schemaHasPngExportPanelAction(schema: ResolvedToolcraftAppSchema): boolean {
-  return (schema.panels.controls?.sections ?? []).some((section) =>
-    Object.values(section.controls).some(
-      (control) =>
-        control.type === "panelActions" &&
-        getControlActions(control).some(actionLooksLikePngExport),
-    ),
-  );
+export function schemaHasSvgExportPanelAction(schema: ResolvedToolcraftAppSchema): boolean {
+  return schemaHasExportPanelAction(schema, "export-svg");
 }
 
 export function schemaHasVideoExportPanelAction(schema: ResolvedToolcraftAppSchema): boolean {
-  return (schema.panels.controls?.sections ?? []).some((section) =>
-    Object.values(section.controls).some(
-      (control) =>
-        control.type === "panelActions" &&
-        getControlActions(control).some(actionLooksLikeVideoExport),
-    ),
-  );
+  return schemaHasExportPanelAction(schema, "export-video");
 }

package/templates/starter/src/app/acceptance/output-export-layout-rules.ts

@@ -8,7 +8,11 @@ export function getToolcraftOutputExportLayoutErrors({
   delivery: ToolcraftArtifactExportDelivery;
   facts: ToolcraftOutputExportFacts;
 }): string[] {
-  if (!delivery.imageEnabled && !delivery.videoEnabled) {
+  if (
+    !delivery.imageEnabled &&
+    !delivery.svgEnabled &&
+    !delivery.videoEnabled
+  ) {
     return [];
   }
 

package/templates/starter/src/app/acceptance/output-export-model.ts

@@ -6,6 +6,7 @@ import type {
 import { getControlLabelText } from "./controls";
 import {
   schemaHasPngExportPanelAction,
+  schemaHasSvgExportPanelAction,
   schemaHasVideoExportPanelAction,
 } from "./output-export-actions";
 import { normalizeToolcraftSemanticText } from "./semantic";
@@ -19,6 +20,7 @@ export type ToolcraftOutputExportFacts = {
   backgroundSection: ToolcraftControlsSection | undefined;
   finalExportSettingsIndex: number;
   hasImageExportAction: boolean;
+  hasSvgExportAction: boolean;
   hasVideoExportAction: boolean;
   imageExportSection: ToolcraftControlsSection | undefined;
   imageExportSectionIndex: number;
@@ -148,6 +150,7 @@ export function buildToolcraftOutputExportFacts({
     "Video Export",
   );
   const hasImageExportAction = schemaHasPngExportPanelAction(schema);
+  const hasSvgExportAction = schemaHasSvgExportPanelAction(schema);
   const hasVideoExportAction = schemaHasVideoExportPanelAction(schema);
 
   return {
@@ -159,6 +162,7 @@ export function buildToolcraftOutputExportFacts({
         ? imageExportSectionIndex
         : -1,
     hasImageExportAction,
+    hasSvgExportAction,
     hasVideoExportAction,
     imageExportSection,
     imageExportSectionIndex,

package/templates/starter/src/app/acceptance/output-export.ts

@@ -7,6 +7,7 @@ import {
 } from "./output-background-rules";
 import {
   schemaHasPngExportPanelAction,
+  schemaHasSvgExportPanelAction,
   schemaHasVideoExportPanelAction,
 } from "./output-export-actions";
 import { getToolcraftOutputExportLayoutErrors } from "./output-export-layout-rules";
@@ -23,6 +24,7 @@ import type {
 export {
   isOutputBackgroundToggleControl,
   schemaHasPngExportPanelAction,
+  schemaHasSvgExportPanelAction,
   schemaHasVideoExportPanelAction,
 };
 
@@ -50,6 +52,7 @@ export function getToolcraftOutputExportErrors({
     validateToolcraftArtifactExportIntentCorrespondence({
       hasImageExportAction: facts.hasImageExportAction,
       hasImageExportSection: facts.imageExportSection !== undefined,
+      hasSvgExportAction: facts.hasSvgExportAction,
       hasVideoExportAction: facts.hasVideoExportAction,
       hasVideoExportSection: facts.videoExportSection !== undefined,
       intent: productReadiness.exportIntent,
@@ -59,7 +62,7 @@ export function getToolcraftOutputExportErrors({
     ...intentErrors,
     ...(delivery.imageEnabled ? getToolcraftImageExportErrors(facts) : []),
     ...(delivery.videoEnabled ? getToolcraftVideoExportErrors(facts) : []),
-    ...(delivery.imageEnabled || delivery.videoEnabled
+    ...(delivery.imageEnabled || delivery.svgEnabled || delivery.videoEnabled
       ? getToolcraftOutputBackgroundErrors({ controls, facts })
       : []),
     ...getToolcraftOutputExportLayoutErrors({ delivery, facts }),

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

@@ -12,36 +12,186 @@ export type ToolcraftReferenceStudyEvidence = {
   status: ToolcraftReferenceStudyStatus;
 };
 
-export type ToolcraftVideoReferenceStoryboardFrame = {
-  behaviorObservation: string;
+export type ToolcraftMotionReferenceTimingMode = "ordinal" | "seconds";
+
+export type ToolcraftMotionReferenceSourceKind =
+  | "contact-sheet"
+  | "frame-sequence"
+  | "gif"
+  | "screen-recording"
+  | "video";
+
+type ToolcraftMotionReferenceFrameBase = {
+  cell: Readonly<{ column: number; row: number }>;
   frameId: string;
-  frameSource: string;
-  timeSeconds: number;
-  visualObservation: string;
+  sourceFrameIndex: number;
+  sourceLocator: string;
+  sourceSha256: string;
 };
 
-export type ToolcraftVideoReferenceTransition = {
-  behaviorDelta: string;
+export type ToolcraftMotionReferenceOrdinalFrame =
+  ToolcraftMotionReferenceFrameBase & { timeSeconds?: never };
+
+export type ToolcraftMotionReferenceTimedFrame =
+  ToolcraftMotionReferenceFrameBase & { timeSeconds: number };
+
+export type ToolcraftMotionReferenceEvidenceEvent = {
+  afterFrameId: string;
+  beforeFrameId: string;
+  eventId: string;
+  kind: "change" | "loop-seam";
+  peakFrameId: string;
+  score: number;
+  windowFrameIds: readonly string[];
+};
+
+type ToolcraftMotionReferenceEvidenceBase = {
+  changeMetric: "max-yuva-diff-v1";
+  contactSheet: Readonly<{
+    columns: number;
+    height: number;
+    path: `src/app/reference-studies/${string}/contact-sheet.png`;
+    rows: number;
+    sha256: string;
+    width: number;
+  }>;
+  decodedFrameCount: number;
+  detectedEvents: readonly ToolcraftMotionReferenceEvidenceEvent[];
+  evidenceVersion: 1;
+  ffmpegVersion: string;
+  ffprobeVersion: string;
+  height: number;
+  scannedFrameCount: number;
+  sourceBasename: string;
+  sourceSha256: string;
+  studyId: string;
+  width: number;
+};
+
+export type ToolcraftMotionReferenceEvidence =
+  ToolcraftMotionReferenceEvidenceBase &
+    (
+      | {
+          sourceGrid: Readonly<{ columns: number; rows: number }>;
+          sourceKind: "contact-sheet";
+        }
+      | {
+          sourceGrid?: never;
+          sourceKind: Exclude<
+            ToolcraftMotionReferenceSourceKind,
+            "contact-sheet"
+          >;
+        }
+    ) &
+    (
+      | {
+          focusWindows: readonly [];
+          overviewFrameIds: readonly string[];
+          reviewedFrames: readonly ToolcraftMotionReferenceOrdinalFrame[];
+          timingMode: "ordinal";
+        }
+      | {
+          durationSeconds: number;
+          focusWindows: readonly Readonly<{
+            endSeconds: number;
+            frameIds: readonly string[];
+            sourceFrameEndIndex: number;
+            sourceFrameStartIndex: number;
+            startSeconds: number;
+          }>[];
+          maximumSourceFrameGapSeconds: number;
+          nominalFrameRate?: number;
+          overviewFrameIds: readonly string[];
+          overviewTargetFps: number;
+          reviewPartition?: Readonly<{
+            count: number;
+            groupId: `motion-group-v1-${string}`;
+            index: number;
+            planSha256: string;
+            scope: Readonly<{ endSeconds: number; startSeconds: number }>;
+          }>;
+          reviewedFrames: readonly ToolcraftMotionReferenceTimedFrame[];
+          segment?: Readonly<{ endSeconds: number; startSeconds: number }>;
+          timing: Readonly<
+            | { authority: "decoded-timestamps" }
+            | { authority: "declared-fps"; framesPerSecond: number }
+            | {
+                authority: "declared-timestamps";
+                timestampsSha256: string;
+              }
+          >;
+          timingMode: "seconds";
+        }
+    );
+
+export type ToolcraftMotionReferencePhase = {
+  behaviorIds: readonly string[];
   fromFrameId: string;
   id: string;
   toFrameId: string;
+  visualState: string;
 };
 
-export type ToolcraftVideoReferenceAcceptanceMapping = {
+export type ToolcraftMotionReferenceEvent = {
+  evidenceEventId: string;
+  id: string;
+} &
+  (
+    | {
+        behaviorIds: readonly string[];
+        classification: "product-behavior";
+        reason?: never;
+      }
+    | {
+        behaviorIds: readonly [];
+        classification:
+          | "edit-boundary"
+          | "encoding-artifact"
+          | "irrelevant-change";
+        reason: string;
+      }
+  );
+
+export type ToolcraftMotionReferenceTimingClaim =
+  | "cadence"
+  | "duration"
+  | "easing"
+  | "loop-seam"
+  | "speed";
+
+export type ToolcraftMotionReferenceBehavior = {
   acceptanceId: string;
-  behavior: string;
-  frameIds: readonly string[];
+  description: string;
+  id: string;
+  implementationIntent: string;
+  timingClaims: readonly Readonly<{
+    claim: ToolcraftMotionReferenceTimingClaim;
+    studyId: string;
+  }>[];
 };
 
-export type ToolcraftVideoReferenceStudyEvidence = {
-  acceptanceMapping: readonly ToolcraftVideoReferenceAcceptanceMapping[];
-  behaviorDecomposition: string;
-  extractionEvidence: string;
-  referenceLocation: string;
-  storyboard: readonly ToolcraftVideoReferenceStoryboardFrame[];
-  transitionAnalysis: readonly ToolcraftVideoReferenceTransition[];
+export type ToolcraftMotionReferenceStudy = {
+  evidence: ToolcraftMotionReferenceEvidence;
+  evidencePath: `src/app/reference-studies/${string}/evidence.json`;
+  events: readonly ToolcraftMotionReferenceEvent[];
+  phases: readonly ToolcraftMotionReferencePhase[];
+  studyId: string;
 };
 
+export type ToolcraftMotionReferenceInput = {
+  behaviors: readonly ToolcraftMotionReferenceBehavior[];
+  kind: "motion-reference";
+  referenceId: `motion-reference-v1-${string}`;
+  studies: readonly ToolcraftMotionReferenceStudy[];
+};
+
+export type ToolcraftReferenceInput = ToolcraftMotionReferenceInput;
+
+export type ToolcraftMotionReferenceCoverage = Readonly<{
+  behaviorId: string;
+  referenceId: ToolcraftMotionReferenceInput["referenceId"];
+}>;
+
 export type ToolcraftReferenceFeatureStatus =
   | "intentionally-changed"
   | "ported"

package/templates/starter/src/app/acceptance/runtime-coverage.ts

@@ -9,6 +9,7 @@ import {
 } from "./coverage";
 import {
   schemaHasPngExportPanelAction,
+  schemaHasSvgExportPanelAction,
   schemaHasVideoExportPanelAction,
 } from "./output-export";
 import type {
@@ -178,7 +179,11 @@ export function getToolcraftCanvasSizingCoverageErrors({
   const errors: string[] = [];
 
   if (schema.canvas.sizing.mode === "fixed-output") {
-    if (schemaHasPngExportPanelAction(schema) || schemaHasVideoExportPanelAction(schema)) {
+    if (
+      schemaHasPngExportPanelAction(schema) ||
+      schemaHasSvgExportPanelAction(schema) ||
+      schemaHasVideoExportPanelAction(schema)
+    ) {
       errors.push(
         'Product/output apps with export actions must use canvas.sizing mode "editable-output" so Aspect ratio, Canvas width, and Canvas height are always available. Put reference, fixed-format, or user-requested dimensions in canvas.size as the initial value instead of hiding size controls with "fixed-output".',
       );

package/templates/starter/src/app/acceptance/selection-scope.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest";
+
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftInteractionOwnershipEntry,
+  ToolcraftProductReadiness,
+} from "./types";
+import { getToolcraftSelectionScopeErrors } from "./selection-scope";
+
+const selectionAcceptance: ToolcraftComponentAcceptance = {
+  automated: true,
+  automatedTestName: "selection updates the active shape",
+  browser: true,
+  browserTestName: "browser: selection updates the active shape",
+  componentType: "canvas selection",
+  evidence: "command-side-effect",
+  expectedObservable: "Selecting either shape updates the active shape.",
+  fixture: "two separated visible shapes",
+  id: "shape.selection",
+  interactionId: "shape-selection",
+  kind: "runtime",
+  target: "selection.activeShape",
+  userAction: "Select each shape.",
+};
+
+const fillAcceptance: ToolcraftComponentAcceptance = {
+  automated: true,
+  automatedTestName: "selected fill changes only the active shape",
+  browser: true,
+  browserTestName: "browser: selected fill changes only the active shape",
+  componentType: "color",
+  evidence: "product-output",
+  expectedObservable: "Only the selected shape changes fill.",
+  fixture: "two separated visible shapes",
+  id: "shape.selected-fill",
+  interactionId: "shape-fill",
+  kind: "control",
+  selectionScopeCoverage: "two-entity-isolation",
+  target: "selectedShape.fill",
+  userAction: "Select each shape and edit Fill.",
+};
+
+function readiness(
+  interactionOwnership: readonly ToolcraftInteractionOwnershipEntry[],
+): ToolcraftProductReadiness {
+  return {
+    exportIntent: {
+      image: { mode: "toolcraft-default" },
+      svg: { mode: "not-requested" },
+      video: { mode: "not-requested" },
+    },
+    interactionOwnership,
+    mode: "product",
+    productName: "Selection fixture",
+    productSummary: "Two shapes with selected-entity property editing.",
+    requestedBehavior: "Select either shape and edit only that shape.",
+    viewInteraction: {
+      mode: "non-spatial",
+      reason: "The fixture uses a fixed two-dimensional editing view.",
+    },
+  };
+}
+
+const validOwnership = [
+  {
+    alternative: {
+      reason: "A panel selector would separate selection from visible shapes.",
+      surface: "panel",
+    },
+    capability: "spatial-selection",
+    evidence: {
+      detail: "The user requested direct selection on the visible canvas.",
+      source: "user-request",
+    },
+    id: "shape-selection",
+    reason: "Canvas selection provides immediate spatial target feedback.",
+    surface: "canvas",
+    target: "selection.activeShape",
+  },
+  {
+    alternative: {
+      reason: "A canvas color editor would duplicate panel property editing.",
+      surface: "canvas",
+    },
+    capability: "property-edit",
+    evidence: {
+      detail: "The user requested built-in panel controls for shape properties.",
+      source: "user-request",
+    },
+    id: "shape-fill",
+    reason: "The panel keeps exact color entry accessible and discoverable.",
+    selectionScope: {
+      mode: "selected-entity",
+      selectionInteractionId: "shape-selection",
+    },
+    surface: "panel",
+    target: "selectedShape.fill",
+  },
+] as const;
+
+describe("Toolcraft selection scope", () => {
+  it("accepts a linked two-entity selected-property proof", () => {
+    expect(
+      getToolcraftSelectionScopeErrors({
+        acceptance: [selectionAcceptance, fillAcceptance],
+        layersEnabled: false,
+        productReadiness: readiness(validOwnership),
+      }),
+    ).toEqual([]);
+  });
+
+  it("allows an explicitly global property without isolation coverage", () => {
+    const globalOwnership = [
+      {
+        ...validOwnership[1],
+        id: "scene-background",
+        selectionScope: { mode: "global" },
+        target: "scene.background",
+      },
+    ] as const;
+    const globalAcceptance = {
+      ...fillAcceptance,
+      id: "scene.background",
+      interactionId: "scene-background",
+      selectionScopeCoverage: undefined,
+      target: "scene.background",
+    };
+
+    expect(
+      getToolcraftSelectionScopeErrors({
+        acceptance: [globalAcceptance],
+        layersEnabled: false,
+        productReadiness: readiness(globalOwnership),
+      }),
+    ).toEqual([]);
+  });
+
+  it("rejects omitted scope, invalid selection links, and missing isolation", () => {
+    const malformed = [
+      {
+        ...validOwnership[1],
+        selectionScope: undefined,
+      },
+      {
+        ...validOwnership[1],
+        id: "wrong-link",
+        selectionScope: {
+          mode: "selected-entity",
+          selectionInteractionId: "shape-fill",
+        },
+      },
+    ] as never;
+
+    expect(
+      getToolcraftSelectionScopeErrors({
+        acceptance: [
+          selectionAcceptance,
+          { ...fillAcceptance, selectionScopeCoverage: undefined },
+        ],
+        layersEnabled: false,
+        productReadiness: readiness(malformed),
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("must declare selectionScope"),
+        expect.stringContaining(
+          "must reference spatial-selection or structured-selection",
+        ),
+        expect.stringContaining("two-entity-isolation"),
+      ]),
+    );
+  });
+
+  it("rejects meaningless isolation metadata", () => {
+    expect(
+      getToolcraftSelectionScopeErrors({
+        acceptance: [
+          {
+            ...fillAcceptance,
+            interactionId: "scene-background",
+            target: "scene.background",
+          },
+        ],
+        layersEnabled: false,
+        productReadiness: readiness([
+          {
+            ...validOwnership[1],
+            id: "scene-background",
+            selectionScope: { mode: "global" },
+            target: "scene.background",
+          },
+        ]),
+      }),
+    ).toEqual([
+      expect.stringContaining(
+        "without selected-entity ownership or a selectedLayer.* target",
+      ),
+    ]);
+  });
+});