@pixel-point/toolcraft 0.0.18 → 0.0.19

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

@@ -0,0 +1,151 @@
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftInteractionOwnershipEntry,
+  ToolcraftProductReadiness,
+} from "./types";
+
+type ToolcraftSelectionScopeValidationInput = {
+  acceptance: readonly ToolcraftComponentAcceptance[];
+  layersEnabled: boolean;
+  productReadiness: ToolcraftProductReadiness;
+};
+
+function isPropertyOwner(
+  entry: ToolcraftInteractionOwnershipEntry,
+): boolean {
+  return (
+    entry.capability === "precise-value-entry" ||
+    entry.capability === "property-edit"
+  );
+}
+
+function isSelectionOwner(
+  entry: ToolcraftInteractionOwnershipEntry | undefined,
+): boolean {
+  return (
+    entry?.capability === "spatial-selection" ||
+    entry?.capability === "structured-selection"
+  );
+}
+
+export function getToolcraftSelectionScopeErrors({
+  acceptance,
+  layersEnabled,
+  productReadiness,
+}: ToolcraftSelectionScopeValidationInput): string[] {
+  const errors: string[] = [];
+  const inventory =
+    productReadiness.mode === "product"
+      ? (productReadiness.interactionOwnership ?? [])
+      : [];
+
+  const ownershipById = new Map(
+    inventory.map((entry) => [entry.id, entry]),
+  );
+
+  for (const owner of inventory) {
+    const selectionScope = owner.selectionScope;
+
+    if (!isPropertyOwner(owner)) {
+      if (selectionScope !== undefined) {
+        errors.push(
+          `${owner.id} may not declare selectionScope because ${owner.capability} is not a property operation.`,
+        );
+      }
+      continue;
+    }
+
+    if (
+      !selectionScope ||
+      (selectionScope.mode !== "global" &&
+        selectionScope.mode !== "selected-entity")
+    ) {
+      errors.push(
+        `${owner.id} must declare selectionScope as global or selected-entity.`,
+      );
+      continue;
+    }
+
+    if (selectionScope.mode === "global") {
+      if ("selectionInteractionId" in selectionScope) {
+        errors.push(
+          `${owner.id} global selectionScope may not declare selectionInteractionId.`,
+        );
+      }
+      continue;
+    }
+
+    if (!selectionScope.selectionInteractionId.trim()) {
+      errors.push(
+        `${owner.id} selected-entity scope must reference a non-empty selectionInteractionId.`,
+      );
+      continue;
+    }
+
+    const selectionOwner = ownershipById.get(
+      selectionScope.selectionInteractionId,
+    );
+    if (!isSelectionOwner(selectionOwner)) {
+      errors.push(
+        `${owner.id} selectionInteractionId ${selectionScope.selectionInteractionId} must reference spatial-selection or structured-selection ownership.`,
+      );
+    }
+
+    const propertyAcceptance = acceptance.find(
+      (entry) =>
+        entry.interactionId === owner.id && entry.target === owner.target,
+    );
+    if (
+      propertyAcceptance?.selectionScopeCoverage !== "two-entity-isolation"
+    ) {
+      errors.push(
+        `${owner.id} selected-entity property must declare selectionScopeCoverage "two-entity-isolation" on its acceptance row.`,
+      );
+    }
+  }
+
+  for (const entry of acceptance) {
+    const owner = entry.interactionId
+      ? ownershipById.get(entry.interactionId)
+      : undefined;
+    const selectedProperty =
+      owner &&
+      isPropertyOwner(owner) &&
+      owner.selectionScope?.mode === "selected-entity";
+    const selectedLayerControl =
+      layersEnabled && entry.target?.startsWith("selectedLayer.");
+    const layerOwnedProperty =
+      layersEnabled && entry.layerCoverage === "selected-layer-controls";
+    const requiresIsolation =
+      selectedProperty || selectedLayerControl || layerOwnedProperty;
+
+    if (
+      requiresIsolation &&
+      entry.selectionScopeCoverage !== "two-entity-isolation"
+    ) {
+      errors.push(
+        `${entry.id} must declare selectionScopeCoverage "two-entity-isolation" proving edits stay on the selected entity.`,
+      );
+    }
+
+    if (
+      entry.selectionScopeCoverage === "two-entity-isolation" &&
+      !requiresIsolation
+    ) {
+      errors.push(
+        `${entry.id} declares two-entity isolation without selected-entity ownership or a selectedLayer.* target.`,
+      );
+    }
+
+    if (
+      selectedLayerControl &&
+      entry.layerCoverage !== "selected-layer-controls"
+    ) {
+      errors.push(
+        `${entry.id} targets selectedLayer.* and must declare layerCoverage "selected-layer-controls" together with two-entity isolation.`,
+      );
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/transfer-mode-types.ts

@@ -0,0 +1,114 @@
+import type {
+  ToolcraftReferenceFeatureInventoryItem,
+  ToolcraftReferenceInput,
+  ToolcraftReferenceStudyEvidence,
+} from "./reference-study-types";
+
+export type ToolcraftReferenceCoverage =
+  | "canvas-sizing"
+  | "control-mapping"
+  | "export-at-time"
+  | "export-copy"
+  | "media-lifecycle"
+  | "pause-resume"
+  | "renderer-loop"
+  | "renderer-state"
+  | "restart"
+  | "spawn-update-cadence"
+  | "time-progress";
+
+export type ToolcraftReferenceTimelineCoverage =
+  | "all-range"
+  | "duration"
+  | "export-at-time"
+  | "export-range"
+  | "jump-to-trim-start"
+  | "keyframes"
+  | "loop"
+  | "playback"
+  | "range-playback"
+  | "restart"
+  | "scrub"
+  | "state-jump"
+  | "time-progress"
+  | "trim-range";
+
+export type ToolcraftTimelinePlaybackCoverage =
+  | "duration"
+  | "loop"
+  | "pause-resume"
+  | "rendered-frame"
+  | "scrub";
+
+export type ToolcraftAutonomousAnimationCoverage =
+  | "no-duration-control"
+  | "no-export-at-time"
+  | "no-loop-control"
+  | "no-play-pause"
+  | "no-scrub"
+  | "no-user-facing-transport";
+
+export type ToolcraftTimelineLoopDurationSource =
+  | "product-derived"
+  | "reference"
+  | "user-request";
+
+export type ToolcraftTimelineLoopDurationIntent = {
+  evidence: string;
+  seconds: number;
+  source: ToolcraftTimelineLoopDurationSource;
+};
+
+export type ToolcraftTimelineLoopProof = {
+  direction: "forward-only";
+  durationChange: "reproved-after-edit";
+  reversePlayback: "forbidden";
+  seam: "first-last-match";
+};
+
+export type ToolcraftAnimationIntent =
+  | { mode: "none" }
+  | {
+      behaviorCoverage: readonly ToolcraftAutonomousAnimationCoverage[];
+      mode: "autonomous";
+      reason: string;
+    }
+  | {
+      loopDuration: ToolcraftTimelineLoopDurationIntent;
+      mode: "timeline-keyframes";
+    }
+  | {
+      loopDuration: ToolcraftTimelineLoopDurationIntent;
+      mode: "timeline-playback";
+    };
+
+export type ToolcraftReferenceTimelineMode =
+  | "custom-reference-timeline"
+  | "none"
+  | "toolcraft-keyframes"
+  | "toolcraft-playback";
+
+export type ToolcraftReferenceTimelineContract = {
+  behaviorCoverage: readonly ToolcraftReferenceTimelineCoverage[];
+  loopDuration?: ToolcraftTimelineLoopDurationIntent;
+  mode: ToolcraftReferenceTimelineMode;
+};
+
+type ToolcraftTransferModeBase = {
+  animationIntent?: ToolcraftAnimationIntent;
+  referenceInputs: readonly ToolcraftReferenceInput[];
+};
+
+export type ToolcraftTransferMode = ToolcraftTransferModeBase &
+  (
+    | { mode: "new-toolcraft-app" }
+    | {
+        behaviorCoverage: readonly ToolcraftReferenceCoverage[];
+        mode: "reference-runtime-clone";
+        referenceFeatureInventory?: readonly ToolcraftReferenceFeatureInventoryItem[];
+        referenceName: string;
+        referenceStudy?: ToolcraftReferenceStudyEvidence;
+        referenceTimeline: ToolcraftReferenceTimelineContract;
+        sourceOfTruth: "reference-runtime";
+      }
+  );

package/templates/starter/src/app/acceptance/types.ts

@@ -12,11 +12,13 @@ import type {
 } from "./canvas-coverage";
 import type { ToolcraftModelImportCoverage } from "./model-import-coverage";
 import type { ToolcraftInteractionOwnershipEntry } from "./interaction-ownership-intent";
+import type { ToolcraftMotionReferenceCoverage } from "./reference-study-types";
 import type {
-  ToolcraftReferenceFeatureInventoryItem,
-  ToolcraftReferenceStudyEvidence,
-  ToolcraftVideoReferenceStudyEvidence,
-} from "./reference-study-types";
+  ToolcraftReferenceCoverage,
+  ToolcraftReferenceTimelineCoverage,
+  ToolcraftTimelineLoopProof,
+  ToolcraftTimelinePlaybackCoverage,
+} from "./transfer-mode-types";
 import type { ToolcraftViewInteractionIntent } from "./view-interaction-intent";
 
 export { TOOLCRAFT_REQUIRED_MODEL_IMPORT_COVERAGE } from "./model-import-coverage";
@@ -38,15 +40,38 @@ export type {
   ToolcraftViewInteractionIntent,
 } from "./view-interaction-intent";
 export type {
+  ToolcraftMotionReferenceBehavior,
+  ToolcraftMotionReferenceCoverage,
+  ToolcraftMotionReferenceEvent,
+  ToolcraftMotionReferenceEvidence,
+  ToolcraftMotionReferenceEvidenceEvent,
+  ToolcraftMotionReferenceInput,
+  ToolcraftMotionReferenceOrdinalFrame,
+  ToolcraftMotionReferencePhase,
+  ToolcraftMotionReferenceSourceKind,
+  ToolcraftMotionReferenceStudy,
+  ToolcraftMotionReferenceTimedFrame,
+  ToolcraftMotionReferenceTimingClaim,
+  ToolcraftMotionReferenceTimingMode,
   ToolcraftReferenceFeatureInventoryItem,
   ToolcraftReferenceFeatureStatus,
+  ToolcraftReferenceInput,
   ToolcraftReferenceStudyEvidence,
   ToolcraftReferenceStudyStatus,
-  ToolcraftVideoReferenceAcceptanceMapping,
-  ToolcraftVideoReferenceStoryboardFrame,
-  ToolcraftVideoReferenceStudyEvidence,
-  ToolcraftVideoReferenceTransition,
 } from "./reference-study-types";
+export type {
+  ToolcraftAnimationIntent,
+  ToolcraftAutonomousAnimationCoverage,
+  ToolcraftReferenceCoverage,
+  ToolcraftReferenceTimelineContract,
+  ToolcraftReferenceTimelineCoverage,
+  ToolcraftReferenceTimelineMode,
+  ToolcraftTimelineLoopDurationIntent,
+  ToolcraftTimelineLoopDurationSource,
+  ToolcraftTimelineLoopProof,
+  ToolcraftTimelinePlaybackCoverage,
+  ToolcraftTransferMode,
+} from "./transfer-mode-types";
 
 export type ToolcraftAcceptanceEvidence =
   | "command-side-effect"
@@ -60,44 +85,9 @@ export type ToolcraftAcceptanceEvidence =
 
 export type ToolcraftExportArtifactCoverage =
   | "all-required-image-export-behavior"
+  | "all-required-svg-export-behavior"
   | "all-required-video-export-behavior";
 
-export type ToolcraftReferenceCoverage =
-  | "canvas-sizing"
-  | "control-mapping"
-  | "export-at-time"
-  | "export-copy"
-  | "media-lifecycle"
-  | "pause-resume"
-  | "renderer-loop"
-  | "renderer-state"
-  | "restart"
-  | "spawn-update-cadence"
-  | "time-progress";
-
-export type ToolcraftReferenceTimelineCoverage =
-  | "all-range"
-  | "duration"
-  | "export-at-time"
-  | "export-range"
-  | "jump-to-trim-start"
-  | "keyframes"
-  | "loop"
-  | "playback"
-  | "range-playback"
-  | "restart"
-  | "scrub"
-  | "state-jump"
-  | "time-progress"
-  | "trim-range";
-
-export type ToolcraftTimelinePlaybackCoverage =
-  | "duration"
-  | "loop"
-  | "pause-resume"
-  | "rendered-frame"
-  | "scrub";
-
 export type ToolcraftPersistenceCoverage = "reload";
 
 export type ToolcraftSettingsTransferCoverage = "opt-out";
@@ -129,62 +119,6 @@ export type ToolcraftMediaLifecycleCoverage =
   | "transform-output"
   | "upload";
 
-export type ToolcraftAutonomousAnimationCoverage =
-  | "no-duration-control"
-  | "no-export-at-time"
-  | "no-loop-control"
-  | "no-play-pause"
-  | "no-scrub"
-  | "no-user-facing-transport";
-
-export type ToolcraftTimelineLoopDurationSource =
-  | "product-derived"
-  | "reference"
-  | "user-request";
-
-export type ToolcraftTimelineLoopDurationIntent = {
-  evidence: string;
-  seconds: number;
-  source: ToolcraftTimelineLoopDurationSource;
-};
-
-export type ToolcraftTimelineLoopProof = {
-  direction: "forward-only";
-  durationChange: "reproved-after-edit";
-  reversePlayback: "forbidden";
-  seam: "first-last-match";
-};
-
-export type ToolcraftAnimationIntent =
-  | {
-      mode: "none";
-    }
-  | {
-      behaviorCoverage: readonly ToolcraftAutonomousAnimationCoverage[];
-      mode: "autonomous";
-      reason: string;
-    }
-  | {
-      loopDuration: ToolcraftTimelineLoopDurationIntent;
-      mode: "timeline-keyframes";
-    }
-  | {
-      loopDuration: ToolcraftTimelineLoopDurationIntent;
-      mode: "timeline-playback";
-    };
-
-export type ToolcraftReferenceTimelineMode =
-  | "custom-reference-timeline"
-  | "none"
-  | "toolcraft-keyframes"
-  | "toolcraft-playback";
-
-export type ToolcraftReferenceTimelineContract = {
-  behaviorCoverage: readonly ToolcraftReferenceTimelineCoverage[];
-  loopDuration?: ToolcraftTimelineLoopDurationIntent;
-  mode: ToolcraftReferenceTimelineMode;
-};
-
 export type ToolcraftLayerCoverage =
   | "grouping"
   | "media-lifecycle"
@@ -193,6 +127,8 @@ export type ToolcraftLayerCoverage =
   | "selection"
   | "visibility";
 
+export type ToolcraftSelectionScopeCoverage = "two-entity-isolation";
+
 export type ToolcraftControlPartCoverage =
   | "anchorGrid.position"
   | "channelMixer.activeChannel"
@@ -256,24 +192,6 @@ export type ToolcraftCustomControlCapability =
   | "reorder"
   | "selection";
 
-export type ToolcraftTransferMode =
-  | {
-      animationIntent?: ToolcraftAnimationIntent;
-      mode: "new-toolcraft-app";
-      videoReferenceStudy?: ToolcraftVideoReferenceStudyEvidence;
-    }
-  | {
-      animationIntent?: ToolcraftAnimationIntent;
-      behaviorCoverage: readonly ToolcraftReferenceCoverage[];
-      mode: "reference-runtime-clone";
-      referenceFeatureInventory?: readonly ToolcraftReferenceFeatureInventoryItem[];
-      referenceName: string;
-      referenceStudy?: ToolcraftReferenceStudyEvidence;
-      referenceTimeline: ToolcraftReferenceTimelineContract;
-      sourceOfTruth: "reference-runtime";
-      videoReferenceStudy?: ToolcraftVideoReferenceStudyEvidence;
-    };
-
 export type ToolcraftImageExportIntent =
   | Readonly<{ mode: "toolcraft-default" }>
   | Readonly<{ evidence: string; mode: "user-requested" }>
@@ -283,8 +201,13 @@ export type ToolcraftVideoExportIntent =
   | Readonly<{ mode: "not-requested" }>
   | Readonly<{ evidence: string; mode: "user-requested" }>;
 
+export type ToolcraftSvgExportIntent =
+  | Readonly<{ mode: "not-requested" }>
+  | Readonly<{ evidence: string; mode: "user-requested" }>;
+
 export type ToolcraftArtifactExportIntent = Readonly<{
   image: ToolcraftImageExportIntent;
+  svg: ToolcraftSvgExportIntent;
   video: ToolcraftVideoExportIntent;
 }>;
 
@@ -332,6 +255,7 @@ export type ToolcraftComponentAcceptance = {
   modelImportCoverage?:
     | "all-required-model-import-behavior"
     | readonly ToolcraftModelImportCoverage[];
+  motionReferenceCoverage?: readonly ToolcraftMotionReferenceCoverage[];
   optionCoverage?: "each-visible-item" | readonly string[];
   orientationGizmoCoverage?:
     | "all-required-orientation-gizmo-behavior"
@@ -342,6 +266,7 @@ export type ToolcraftComponentAcceptance = {
   referenceTimelineCoverage?: ToolcraftReferenceTimelineCoverage;
   renderScaleCoverage?: ToolcraftRenderScaleCoverage;
   settingsTransferCoverage?: ToolcraftSettingsTransferCoverage;
+  selectionScopeCoverage?: ToolcraftSelectionScopeCoverage;
   target?: string;
   timelineCoverage?: "keyframes" | "playback";
   timelinePlaybackCoverage?:

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

@@ -21,8 +21,10 @@ import {
   schemaHasVideoExportPanelAction,
 } from "./output-export";
 import { getToolcraftOrientationGizmoErrors } from "./orientation-gizmo";
+import { getToolcraftMotionReferenceStudyErrors } from "./motion-reference-study";
 import { getToolcraftReferenceRuntimeCloneErrors } from "./reference-runtime";
 import { getToolcraftRenderScaleCoverageErrors } from "./render-scale";
+import { getToolcraftSelectionScopeErrors } from "./selection-scope";
 import {
   getToolcraftCanvasSizingCoverageErrors,
   getToolcraftLayerCoverageErrors,
@@ -46,7 +48,6 @@ import {
   type ToolcraftAcceptanceValidationContext,
   type ToolcraftAcceptanceValidator,
 } from "./validation-pipeline";
-import { getToolcraftVideoReferenceStudyErrors } from "./video-reference-study";
 import { getToolcraftViewInteractionErrors } from "./view-interaction";
 
 export type ToolcraftAcceptanceValidationInput = {
@@ -112,6 +113,16 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
         productReadiness,
       }),
   },
+  {
+    path: "starterProductReadiness.interactionOwnership[].selectionScope",
+    ruleId: "interaction-surface-ownership",
+    validate: ({ acceptance, layersEnabled, productReadiness }) =>
+      getToolcraftSelectionScopeErrors({
+        acceptance,
+        layersEnabled,
+        productReadiness,
+      }),
+  },
   {
     path: "starterProductReadiness.viewInteraction",
     ruleId: "renderer-view-interaction",
@@ -186,9 +197,9 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
       }),
   },
   {
-    path: "starterTransferMode.videoReferenceStudy",
+    path: "starterTransferMode.referenceInputs",
     ruleId: "video-reference-analysis",
-    validate: getToolcraftVideoReferenceStudyErrors,
+    validate: getToolcraftMotionReferenceStudyErrors,
   },
   {
     path: "starterTransferMode.animationIntent",

package/templates/starter/src/app/starter-acceptance-data.ts

@@ -14,6 +14,7 @@ const starterPersistenceSlices =
 export const starterTransferMode: ToolcraftTransferMode = {
   animationIntent: { mode: "none" },
   mode: "new-toolcraft-app",
+  referenceInputs: [],
 };
 
 export const starterProductReadiness: ToolcraftProductReadiness = {

package/templates/starter/src/app/starter-acceptance.animation-intent.test.ts

@@ -253,6 +253,7 @@ describe("starter acceptance animation intent contract", () => {
             reason: "The shimmer is decorative self-running output and does not expose product time transport.",
           },
           mode: "new-toolcraft-app",
+          referenceInputs: [],
         },
       }),
     ).toEqual([]);
@@ -351,6 +352,7 @@ describe("starter acceptance animation intent contract", () => {
             reason: "The shader is decorative self-running output with no transport controls.",
           },
           mode: "new-toolcraft-app",
+          referenceInputs: [],
         },
       }),
     ).toContain(
@@ -377,6 +379,7 @@ describe("starter acceptance animation intent contract", () => {
             mode: "timeline-keyframes",
           },
           mode: "new-toolcraft-app",
+          referenceInputs: [],
         },
       }),
     ).toContain(