@pixel-point/toolcraft 0.0.17 → 0.0.19

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",
+      ),
+    ]);
+  });
+});

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";
+      }
+  );