@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/src/app/starter-acceptance.layers.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  contractAcceptanceFixture,
+  contractSchemaFixture,
+  validateContractAcceptance,
+} from "./starter-acceptance.contract-fixtures";
+import { playbackTimelineAcceptance } from "./starter-acceptance.timeline-test-utils";
+
+describe("starter acceptance layers contract", () => {
+  it("requires layer behavior coverage when a layers panel is enabled", () => {
+    const layersSchema = {
+      ...contractSchemaFixture,
+      panels: {
+        ...contractSchemaFixture.panels,
+        layers: true,
+      },
+    };
+
+    expect(
+      validateContractAcceptance({
+        schema: layersSchema,
+        acceptance: contractAcceptanceFixture,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'panels.layers requires a runtime acceptance entry with layerCoverage "selection" proving layer selection behavior.',
+        'panels.layers requires a runtime acceptance entry with layerCoverage "visibility" proving layer visibility behavior.',
+        'panels.layers requires a runtime acceptance entry with layerCoverage "reorder" proving layer reorder behavior.',
+        'panels.layers requires a runtime acceptance entry with layerCoverage "grouping" proving layer grouping behavior.',
+      ]),
+    );
+  });
+
+  it("rejects selectedLayer targets when the layers panel is disabled", () => {
+    const schemaWithSelectedLayerControl = {
+      ...contractSchemaFixture,
+      panels: {
+        ...contractSchemaFixture.panels,
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 75,
+                  label: "Opacity",
+                  max: 100,
+                  min: 0,
+                  target: "selectedLayer.opacity",
+                  type: "slider",
+                  variant: "continuous",
+                },
+              },
+              title: "Layer",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    };
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithSelectedLayerControl,
+        acceptance: [
+          playbackTimelineAcceptance,
+          {
+            automated: true,
+            automatedTestName: "opacity changes rendered output",
+            browser: true,
+            browserTestName: "browser: opacity slider changes rendered output",
+            componentType: "slider",
+            evidence: "rendered-pixels",
+            expectedObservable: "Changing Opacity changes layer transparency.",
+            fixture: "opacity fixture",
+            id: "selectedLayer.opacity",
+            kind: "control",
+            target: "selectedLayer.opacity",
+            userAction: "Drag the Opacity slider.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        "Layer / opacity (selectedLayer.opacity) uses reserved selectedLayer.* target without panels.layers enabled. Use an app-specific target for single-layer apps or enable layers with layerCoverage.",
+      ]),
+    );
+  });
+
+  it("requires selectedLayer controls to prove currently selected layer behavior", () => {
+    const layeredSchema = {
+      ...contractSchemaFixture,
+      panels: {
+        ...contractSchemaFixture.panels,
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 75,
+                  label: "Opacity",
+                  max: 100,
+                  min: 0,
+                  target: "selectedLayer.opacity",
+                  type: "slider",
+                  variant: "continuous",
+                },
+              },
+              title: "Layer",
+            },
+          ],
+          title: "Controls",
+        },
+        layers: true,
+      },
+    };
+
+    expect(
+      validateContractAcceptance({
+        schema: layeredSchema,
+        acceptance: [
+          playbackTimelineAcceptance,
+          {
+            automated: true,
+            automatedTestName: "layer selection changes selected runtime layer",
+            browser: true,
+            browserTestName: "browser: layers selection changes selected runtime layer",
+            componentType: "layers",
+            evidence: "product-output",
+            expectedObservable: "Selecting another layer changes which output layer is edited.",
+            fixture: "layered output fixture",
+            id: "layers.selection",
+            kind: "runtime",
+            layerCoverage: "selection",
+            userAction: "Select another layer.",
+          },
+          {
+            automated: true,
+            automatedTestName: "layer visibility hides nested layer output",
+            browser: true,
+            browserTestName: "browser: layers visibility hides nested layer output",
+            componentType: "layers",
+            evidence: "product-output",
+            expectedObservable: "Toggling layer visibility removes that layer from output.",
+            fixture: "layered output fixture",
+            id: "layers.visibility",
+            kind: "runtime",
+            layerCoverage: "visibility",
+            userAction: "Toggle a layer visibility button.",
+          },
+          {
+            automated: true,
+            automatedTestName: "layer reorder changes render order",
+            browser: true,
+            browserTestName: "browser: layers reorder changes render order",
+            componentType: "layers",
+            evidence: "product-output",
+            expectedObservable: "Dragging a layer changes composited render order.",
+            fixture: "overlapping layers fixture",
+            id: "layers.reorder",
+            kind: "runtime",
+            layerCoverage: "reorder",
+            userAction: "Drag a layer before another layer.",
+          },
+          {
+            automated: true,
+            automatedTestName: "layer grouping nests layer output",
+            browser: true,
+            browserTestName: "browser: layers grouping nests layer output",
+            componentType: "layers",
+            evidence: "product-output",
+            expectedObservable: "Dragging a layer into a group nests it and group visibility affects the nested output.",
+            fixture: "grouped layers fixture",
+            id: "layers.grouping",
+            kind: "runtime",
+            layerCoverage: "grouping",
+            userAction: "Drag a layer into a group.",
+          },
+          {
+            automated: true,
+            automatedTestName: "opacity changes rendered output",
+            browser: true,
+            browserTestName: "browser: opacity slider changes rendered output",
+            componentType: "slider",
+            evidence: "rendered-pixels",
+            expectedObservable: "Changing Opacity changes layer transparency.",
+            fixture: "opacity fixture",
+            id: "selectedLayer.opacity",
+            kind: "control",
+            target: "selectedLayer.opacity",
+            userAction: "Drag the Opacity slider.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'Layer / opacity (selectedLayer.opacity) targets selectedLayer.* and must have acceptance layerCoverage "selected-layer-controls" proving the control edits the currently selected layer output.',
+      ]),
+    );
+  });
+
+
+});

package/templates/starter/src/app/starter-acceptance.media-upload.fixtures.ts

@@ -0,0 +1,110 @@
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftMediaLifecycleCoverage,
+} from "./acceptance/types";
+
+type FileDropSchemaOptions = {
+  withDefaultAsset?: boolean;
+};
+
+type FileDropAcceptanceOptions = {
+  automatedTestName: string;
+  browserTestName: string;
+  expectedObservable: string;
+  fixture: string;
+  id?: string;
+  mediaLifecycleCoverage?: readonly ToolcraftMediaLifecycleCoverage[];
+  target?: string;
+  userAction: string;
+};
+
+export function createSingleFileDropSchema({
+  withDefaultAsset = false,
+}: FileDropSchemaOptions = {}) {
+  return defineToolcraft({
+    canvas: { enabled: true, upload: withDefaultAsset },
+    media: withDefaultAsset
+      ? {
+          defaultAssets: [
+            {
+              dataUrl: "data:image/png;base64,AAAA",
+              fileName: "default-source.png",
+              sourceTarget: "media.source",
+            },
+          ],
+        }
+      : undefined,
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              source: {
+                defaultValue: null,
+                label: "Source image",
+                target: "media.source",
+                type: "fileDrop",
+              },
+            },
+            title: "Source",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+export function createMultipleFileDropSchema() {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              sources: {
+                defaultValue: [],
+                label: "Source images",
+                multiple: true,
+                target: "media.sources",
+                type: "fileDrop",
+              },
+            },
+            title: "Source",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+export function createFileDropAcceptance({
+  automatedTestName,
+  browserTestName,
+  expectedObservable,
+  fixture,
+  id = "media.source",
+  mediaLifecycleCoverage,
+  target = id,
+  userAction,
+}: FileDropAcceptanceOptions): ToolcraftComponentAcceptance {
+  return {
+    automated: true,
+    automatedTestName,
+    browser: true,
+    browserTestName,
+    componentType: "fileDrop",
+    evidence: "media-lifecycle",
+    expectedObservable,
+    fixture,
+    id,
+    kind: "control",
+    mediaLifecycleCoverage,
+    target,
+    userAction,
+  };
+}

package/templates/starter/src/app/starter-acceptance.media-upload.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+import {
+  createFileDropAcceptance,
+  createMultipleFileDropSchema,
+  createSingleFileDropSchema,
+} from "./starter-acceptance.media-upload.fixtures";
+
+describe("Toolcraft media upload acceptance coverage", () => {
+  it("requires fileDrop acceptance to prove upload, clear, reset, and image transforms", () => {
+    const fileDropSchema = createSingleFileDropSchema();
+
+    expect(
+      validateContractAcceptance({
+        schema: fileDropSchema,
+        acceptance: [
+          createFileDropAcceptance({
+            automatedTestName: "source image upload and clear update media",
+            browserTestName: "browser: source image upload and clear update media",
+            expectedObservable: "Uploading a source image changes the media preview and Clear removes it.",
+            fixture: "source image fixture",
+            mediaLifecycleCoverage: ["upload", "remove"],
+            userAction: "Upload a source image, then clear the preview.",
+          }),
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        "Source / source (media.source) fileDrop acceptance must prove upload/import, clear/remove, and section or global reset restore default source media or remove uploaded source media when no default exists.",
+        "Source / source (media.source) image fileDrop acceptance must prove rotate and flip actions update runtime media transform metadata and that preview, renderer, or export consumes the transform.",
+      ]),
+    );
+  });
+
+  it("requires predefined fileDrop media acceptance to prove attached default restore", () => {
+    const fileDropSchema = createSingleFileDropSchema({ withDefaultAsset: true });
+
+    expect(
+      validateContractAcceptance({
+        schema: fileDropSchema,
+        acceptance: [
+          createFileDropAcceptance({
+            automatedTestName: "source image upload reset lifecycle",
+            browserTestName: "browser: source image upload reset lifecycle",
+            expectedObservable: "Upload, clear, reset, rotate, and flip update the source preview and renderer.",
+            fixture: "source image fixture",
+            mediaLifecycleCoverage: [
+              "upload",
+              "remove",
+              "reset",
+              "rotate",
+              "flip",
+              "transform-output",
+            ],
+            userAction: "Upload a source image, clear it, use Reset controls, rotate 90°, flip horizontal, and verify runtime media transform metadata is consumed by preview.",
+          }),
+        ],
+      }),
+    ).toContain(
+      "Source / source (media.source) fileDrop acceptance must prove predefined media.defaultAssets render as attached files, can be removed to an empty source/canvas state, and are restored by section or global Reset.",
+    );
+  });
+
+  it("accepts fileDrop lifecycle coverage that includes reset and image transforms", () => {
+    const fileDropSchema = createSingleFileDropSchema();
+
+    const errors = validateContractAcceptance({
+      schema: fileDropSchema,
+      acceptance: [
+        createFileDropAcceptance({
+          automatedTestName: "source image upload clear and reset update media",
+          browserTestName: "browser: source image upload clear and reset update media",
+          expectedObservable: "El resultado visual refleja el ciclo de medios completo.",
+          fixture: "source image fixture",
+          mediaLifecycleCoverage: [
+            "upload",
+            "remove",
+            "reset",
+            "rotate",
+            "flip",
+            "transform-output",
+          ],
+          userAction: "Ejecutar el flujo completo del medio.",
+        }),
+      ],
+    });
+
+    expect(
+      errors.filter((error) => error.includes("fileDrop acceptance")),
+    ).toEqual([]);
+  });
+
+  it("requires multiple fileDrop acceptance to prove runtime media reorder", () => {
+    const fileDropSchema = createMultipleFileDropSchema();
+
+    expect(
+      validateContractAcceptance({
+        schema: fileDropSchema,
+        acceptance: [
+          createFileDropAcceptance({
+            automatedTestName: "source images upload clear reset and transform",
+            browserTestName: "browser: source images upload clear reset and transform",
+            expectedObservable: "Uploading source images changes the media preview; rotate and flip actions update runtime media transform metadata and rendered output; Clear and Reset controls remove media.",
+            fixture: "source images fixture",
+            id: "media.sources",
+            mediaLifecycleCoverage: [
+              "upload",
+              "remove",
+              "reset",
+              "rotate",
+              "flip",
+              "transform-output",
+            ],
+            target: "media.sources",
+            userAction: "Upload two source images, rotate one, flip it, clear the images, and use Reset controls.",
+          }),
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        "Source / sources (media.sources) multiple fileDrop acceptance must prove thumbnail/file reorder updates runtime media order and that preview, renderer, or export consumes that order.",
+      ]),
+    );
+
+    expect(
+      validateContractAcceptance({
+        schema: fileDropSchema,
+        acceptance: [
+          createFileDropAcceptance({
+            automatedTestName: "source images upload reorder transform and reset",
+            browserTestName: "browser: source images upload reorder transform and reset",
+            expectedObservable: "Uploading source images changes the preview; drag reorder updates runtime media order used by rendered output; rotate and flip update runtime media transform metadata used by export; Clear, section reset, and global Reset controls remove media.",
+            fixture: "source images fixture",
+            id: "media.sources",
+            mediaLifecycleCoverage: [
+              "upload",
+              "remove",
+              "reset",
+              "rotate",
+              "flip",
+              "transform-output",
+              "reorder",
+              "order-output",
+            ],
+            target: "media.sources",
+            userAction: "Upload two source images, drag to reorder thumbnails, rotate and flip the selected image, clear them, then use section reset and Reset controls.",
+          }),
+        ],
+      }),
+    ).toEqual([]);
+  });
+});

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

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+import { schemaRequiresVideoExport } from "./starter-acceptance.video-export-test-utils";
+
+describe("Toolcraft output export synthetic rules", () => {
+  it("does not force decorative autonomous animation into video export", () => {
+    const autonomousSchema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: { controls: { sections: [], title: "Controls" } },
+    });
+
+    expect(
+      schemaRequiresVideoExport(autonomousSchema, {
+        animationIntent: {
+          behaviorCoverage: [
+            "no-duration-control",
+            "no-export-at-time",
+            "no-loop-control",
+            "no-play-pause",
+            "no-scrub",
+            "no-user-facing-transport",
+          ],
+          mode: "autonomous",
+          reason: "Decorative ambient motion has no user-facing product time.",
+        },
+        mode: "new-toolcraft-app",
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects reset actions in sticky footer panelActions", () => {
+    const schemaWithFooterReset = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      command: "controls.reset",
+                      icon: "rotate-ccw",
+                      label: "Reset",
+                      value: "reset",
+                    },
+                    {
+                      icon: "upload-simple",
+                      label: "Export PNG",
+                      role: "export-image",
+                      value: "export.png",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        acceptance: [
+          {
+            actionCoverage: ["reset", "export.png"],
+            automated: true,
+            automatedTestName: "footer actions reset and export output",
+            browser: true,
+            browserTestName: "browser: footer actions reset and export output",
+            componentType: "panelActions",
+            evidence: "exported-bytes",
+            expectedObservable: "Footer actions reset controls and export output.",
+            fixture: "footer actions fixture",
+            id: "actions.output",
+            kind: "control",
+            target: "actions.output",
+            userAction: "Click Reset and Export PNG.",
+          },
+        ],
+        schema: schemaWithFooterReset,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("must not include Reset footer actions (reset)"),
+      ]),
+    );
+  });
+});

package/templates/starter/src/app/starter-acceptance.persistence-coverage.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+import { makeControlAcceptance } from "./starter-acceptance.test-utils";
+
+describe("Toolcraft starter persistence acceptance coverage", () => {
+  it("requires browser reload acceptance when localStorage persistence is enabled", () => {
+    const persistentSchema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 0.75,
+                  label: "Opacity",
+                  target: "appearance.opacity",
+                  type: "slider",
+                },
+              },
+              title: "Appearance",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+      persistence: {
+        include: ["values", "panels"],
+        key: "toolcraft:persistence-acceptance-test:state:v1",
+        storage: "localStorage",
+        version: 1,
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: persistentSchema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "opacity changes product output",
+            browser: true,
+            browserTestName: "browser: opacity changes product output",
+            componentType: "slider",
+            evidence: "product-output",
+            expectedObservable: "Changing Opacity changes rendered product opacity.",
+            fixture: "opacity fixture",
+            id: "appearance.opacity",
+            kind: "control",
+            target: "appearance.opacity",
+            userAction: "Drag the Opacity slider.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'persistence.storage "localStorage" requires a runtime acceptance entry with persistenceCoverage "reload" proving user-edited persisted state restores after a real browser reload. Settings import/export is not a substitute for persistence.',
+      ]),
+    );
+  });
+
+  it("accepts typed reload coverage without relying on English prose", () => {
+    const persistentSchema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 0.75,
+                  label: "Opacity",
+                  target: "appearance.opacity",
+                  type: "slider",
+                },
+              },
+              title: "Appearance",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+      persistence: {
+        include: ["values", "panels"],
+        key: "toolcraft:persistence-acceptance-test:state:v1",
+        storage: "localStorage",
+        version: 1,
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: persistentSchema,
+        acceptance: [
+          {
+            automated: true,
+            automatedTestName: "opacity changes product output",
+            browser: true,
+            browserTestName: "browser: opacity changes product output",
+            componentType: "slider",
+            evidence: "product-output",
+            expectedObservable: "Changing Opacity changes rendered product opacity.",
+            fixture: "opacity fixture",
+            id: "appearance.opacity",
+            kind: "control",
+            target: "appearance.opacity",
+            userAction: "Drag the Opacity slider.",
+          },
+          {
+            automated: true,
+            automatedTestName: "exports and imports settings",
+            browser: true,
+            browserTestName: "browser: exports and imports settings",
+            componentType: "persistence",
+            evidence: "persistence-state",
+            expectedObservable: "El valor editado reaparece después de recargar.",
+            fixture: "settings transfer fixture",
+            id: "persistence.reload",
+            kind: "runtime",
+            persistenceCoverage: "reload",
+            target: "persistence.reload",
+            userAction: "Cambiar el valor, recargar la página y observar el estado.",
+          },
+        ],
+      }),
+    ).not.toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("must describe changing a user-facing setting"),
+      ]),
+    );
+  });
+});