@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -0,0 +1,349 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import { validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
+import {
+  makeBackgroundSection,
+  makeImageExportSection,
+} from "./starter-acceptance.export-test-utils";
+import { makeControlAcceptance } from "./starter-acceptance.test-utils";
+
+describe("Toolcraft background export acceptance contract", () => {
+  it("requires png export apps to expose background color and png background toggle controls", () => {
+    const schemaWithoutBackgroundControls = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      icon: "upload-simple",
+                      label: "Export PNG",
+                      role: "export-image",
+                      value: "export.png",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+              title: "Output",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithoutBackgroundControls,
+        acceptance: [
+          {
+            actionCoverage: ["export.png"],
+            automated: true,
+            automatedTestName: "exports png output",
+            browser: true,
+            browserTestName: "browser: exports png output",
+            componentType: "panelActions",
+            evidence: "exported-bytes",
+            expectedObservable: "Export PNG creates output bytes.",
+            fixture: "export fixture",
+            id: "actions.output",
+            kind: "control",
+            target: "actions.output",
+            userAction: "Click Export PNG.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("must expose a user-facing background color control"),
+        expect.stringContaining('must expose export.includeBackground inside the required "Background" section'),
+      ]),
+    );
+  });
+
+  it("rejects legacy output sections that mix background controls with export actions", () => {
+    const schemaWithLegacyBackgroundControls = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                background: {
+                  defaultValue: "#ffffff",
+                  label: "Background",
+                  target: "appearance.background",
+                  type: "color",
+                },
+                includeBackground: {
+                  defaultValue: true,
+                  label: "Include background",
+                  target: "export.includeBackground",
+                  type: "switch",
+                },
+                outputActions: {
+                  actions: [
+                    {
+                      icon: "upload-simple",
+                      label: "Export PNG",
+                      role: "export-image",
+                      value: "export.png",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+              title: "Output",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithLegacyBackgroundControls,
+        acceptance: [
+          makeControlAcceptance("appearance.background", "color"),
+          makeControlAcceptance("export.includeBackground", "switch"),
+          {
+            actionCoverage: ["export.png"],
+            automated: true,
+            automatedTestName: "exports png output",
+            browser: true,
+            browserTestName: "browser: exports png output",
+            componentType: "panelActions",
+            evidence: "exported-bytes",
+            expectedObservable: "Export PNG creates output bytes.",
+            fixture: "export fixture",
+            id: "actions.output",
+            kind: "control",
+            target: "actions.output",
+            userAction: "Click Export PNG.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('separate controls section titled "Background"'),
+        expect.stringContaining(
+          'The "Background" section must contain export.includeBackground as the Include switch.',
+        ),
+        expect.stringContaining(
+          'The "Background" section must contain the renderer-owned background color control',
+        ),
+      ]),
+    );
+  });
+
+  it("accepts png export apps that wire background controls into the schema", () => {
+    const schemaWithBackgroundControls = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            makeBackgroundSection(),
+            makeImageExportSection(),
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      icon: "upload-simple",
+                      label: "Export PNG",
+                      role: "export-image",
+                      value: "export.png",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+              title: "Output",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const errors = validateContractAcceptance({
+      schema: schemaWithBackgroundControls,
+      acceptance: [
+        makeControlAcceptance("appearance.background", "color"),
+        {
+          ...makeControlAcceptance("export.includeBackground", "switch"),
+          backgroundOutputCoverage: [
+            "preview-hidden-when-excluded",
+            "image-transparent-when-excluded",
+          ],
+          expectedObservable: "Переключатель изменяет фон предпросмотра и растрового результата.",
+          userAction: "Отключить фон и проверить оба результата.",
+        },
+        {
+          actionCoverage: ["export.png"],
+          automated: true,
+          automatedTestName: "exports png output with current background settings",
+          browser: true,
+          browserTestName: "browser: exports png output with current background settings",
+          componentType: "panelActions",
+          evidence: "exported-bytes",
+          expectedObservable: "Export PNG creates output bytes and reads background color plus include-background state.",
+          fixture: "export fixture",
+          id: "actions.output",
+          kind: "control",
+          target: "actions.output",
+          userAction: "Toggle Include background, change Background, then click Export PNG.",
+        },
+      ],
+    });
+
+    expect(errors).not.toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("must expose a user-facing background color control"),
+        expect.stringContaining('must expose export.includeBackground inside the required "Background" section'),
+      ]),
+    );
+  });
+
+  it("requires include-background acceptance to hide preview background and keep video background", () => {
+    const schemaWithBackgroundControls = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            makeBackgroundSection(),
+            makeImageExportSection(),
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      icon: "upload-simple",
+                      label: "Export PNG",
+                      role: "export-image",
+                      value: "export.png",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+              title: "Output",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithBackgroundControls,
+        acceptance: [
+          makeControlAcceptance("appearance.background", "color"),
+          makeControlAcceptance("export.includeBackground", "switch"),
+          {
+            actionCoverage: ["export.png"],
+            automated: true,
+            automatedTestName: "exports png output with current background settings",
+            browser: true,
+            browserTestName: "browser: exports png output with current background settings",
+            componentType: "panelActions",
+            evidence: "exported-bytes",
+            expectedObservable: "Export PNG creates output bytes and reads background color plus include-background state.",
+            fixture: "export fixture",
+            id: "actions.output",
+            kind: "control",
+            target: "actions.output",
+            userAction: "Toggle Include background, change Background, then click Export PNG.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining(
+          "controls background inclusion and must declare backgroundOutputCoverage",
+        ),
+      ]),
+    );
+  });
+
+  it("requires video background coverage only when video export is present", () => {
+    const schemaWithVideoExport = defineToolcraft({
+      canvas: {
+        enabled: true,
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            makeBackgroundSection(),
+            makeImageExportSection(),
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      label: "Export PNG",
+                      role: "export-image",
+                      value: "export.png",
+                    },
+                    {
+                      label: "Export Video",
+                      role: "export-video",
+                      value: "export.video",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+              title: "Output",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: schemaWithVideoExport,
+        acceptance: [
+          makeControlAcceptance("appearance.background", "color"),
+          {
+            ...makeControlAcceptance("export.includeBackground", "switch"),
+            backgroundOutputCoverage: [
+              "preview-hidden-when-excluded",
+              "image-transparent-when-excluded",
+            ],
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("video-background-preserved"),
+      ]),
+    );
+  });
+});

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

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  starterAcceptance,
+  starterControlSectionInventory,
+  starterTransferMode,
+  validateProductAcceptanceCoverage,
+  validateToolcraftAcceptanceCoverage,
+} from "./starter-acceptance";
+import { starterSchema } from "./starter-schema";
+import { schemaHasProductSurface } from "./starter-acceptance.schema-test-utils";
+
+describe("Toolcraft starter base acceptance coverage", () => {
+  it("requires acceptance coverage for every visible schema control", () => {
+    expect(validateProductAcceptanceCoverage()).toEqual([]);
+  });
+
+  it("validates equivalent product data independently from object identity", () => {
+    const clonedSchema = structuredClone(starterSchema);
+    const clonedAcceptance = structuredClone(starterAcceptance);
+    const clonedTransferMode = structuredClone(starterTransferMode);
+    const clonedSectionInventory = structuredClone(starterControlSectionInventory);
+
+    expect(
+      validateToolcraftAcceptanceCoverage({
+        acceptance: clonedAcceptance,
+        schema: clonedSchema,
+        sectionInventory: clonedSectionInventory,
+        transferMode: clonedTransferMode,
+      }),
+    ).toEqual(validateProductAcceptanceCoverage());
+  });
+
+  it("requires generated product apps to publish a control section inventory", () => {
+    if (!schemaHasProductSurface()) {
+      expect(starterControlSectionInventory).toEqual([]);
+      return;
+    }
+
+    expect(
+      starterControlSectionInventory.length,
+      "Product apps must export starterControlSectionInventory so section grouping decisions are machine-checkable.",
+    ).toBeGreaterThan(0);
+    expect(validateProductAcceptanceCoverage()).toEqual([]);
+  });
+
+});

package/templates/starter/src/app/starter-acceptance.canvas-handles.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  contractAcceptanceFixture,
+  contractSchemaFixture,
+  validateContractAcceptance,
+} from "./starter-acceptance.contract-fixtures";
+
+describe("Toolcraft starter canvas handle acceptance coverage", () => {
+  it("requires canvas handles to declare runtime, browser, and export-clean coverage", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            automated: true,
+            automatedTestName: "gradient focus handle changes rendered output",
+            browser: true,
+            browserTestName: "browser: gradient focus handle drags on canvas",
+            componentType: "canvas-handle",
+            evidence: "product-output",
+            expectedObservable: "Dragging the focus handle moves the gradient hotspot.",
+            fixture: "radial gradient fixture",
+            id: "shader.focus.handle",
+            kind: "canvas-handle",
+            userAction: "Drag the focus handle on the canvas.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        "shader.focus.handle canvas handle is missing canvasHandle metadata.",
+      ]),
+    );
+  });
+
+  it("requires canvas handle write targets to exist in schema or editor commands", () => {
+    expect(
+      validateContractAcceptance({
+        schema: contractSchemaFixture,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            automated: true,
+            automatedTestName: "gradient focus handle changes rendered output",
+            browser: true,
+            browserTestName: "browser: gradient focus handle drags on canvas",
+            canvasHandle: {
+              exportCleanTestName: "export excludes gradient focus handle",
+              outputObservable: "The gradient hotspot moves after dragging the handle.",
+              testId: "gradient-focus-handle",
+              writesTarget: "missing.target",
+            },
+            componentType: "canvas-handle",
+            evidence: "product-output",
+            expectedObservable: "Dragging the focus handle moves the gradient hotspot.",
+            fixture: "radial gradient fixture",
+            id: "shader.focus.handle",
+            kind: "canvas-handle",
+            userAction: "Drag the focus handle on the canvas.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        "shader.focus.handle canvas handle writesTarget missing.target does not match a schema target or supported editor command.",
+      ]),
+    );
+  });
+});

package/templates/starter/src/app/starter-acceptance.canvas-sizing.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vitest";
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+
+import {
+  contractAcceptanceFixture,
+  validateContractAcceptance,
+} from "./starter-acceptance.contract-fixtures";
+import { makeControlAcceptance } from "./starter-acceptance.test-utils";
+
+function createFixedOutputSchema({
+  height = 1080,
+  width = 1920,
+}: {
+  height?: number;
+  width?: number;
+} = {}) {
+  return defineToolcraft({
+    canvas: {
+      enabled: true,
+      size: { height, unit: "px", width },
+      sizing: { mode: "fixed-output" },
+    },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              prompt: {
+                defaultValue: "Describe the effect",
+                label: "Prompt",
+                orderRole: "input",
+                target: "generation.prompt",
+                textValueKind: "single-line",
+                type: "text",
+              },
+            },
+            title: "Generation",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+function createIntrinsicMediaUploadSchema() {
+  return defineToolcraft({
+    canvas: {
+      enabled: true,
+      sizing: { mode: "intrinsic-media" },
+      upload: true,
+    },
+    panels: {
+      controls: {
+        sections: [],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+describe("Toolcraft canvas sizing acceptance coverage", () => {
+  it("requires explicit runtime acceptance before locking canvas output size", () => {
+    expect(
+      validateContractAcceptance({
+        schema: createFixedOutputSchema(),
+        acceptance: contractAcceptanceFixture,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'canvas.sizing mode "fixed-output" requires a runtime acceptance entry with canvasSizingCoverage "fixed-output-size" explaining why width and height are intentionally non-editable. Product/output apps must use "editable-output"; user-provided, reference, fixed-format, or base/default sizes belong in canvas.size as editable initial values.',
+      ]),
+    );
+  });
+
+  it("accepts typed fixed-output coverage without parsing explanatory prose", () => {
+    expect(
+      validateContractAcceptance({
+        schema: createFixedOutputSchema(),
+        acceptance: [
+          ...contractAcceptanceFixture,
+          makeControlAcceptance("generation.prompt", "text"),
+          {
+            automated: true,
+            automatedTestName: "fixed canvas dimensions remain stable",
+            browser: true,
+            browserTestName: "browser: canvas starts at 1920 by 1080",
+            canvasSizingCoverage: "fixed-output-size",
+            componentType: "canvas",
+            evidence: "product-output",
+            expectedObservable: "Las dimensiones permanecen estables.",
+            fixture: "canvas default size fixture",
+            id: "canvas.sizing",
+            kind: "runtime",
+            userAction: "Abrir la herramienta interna.",
+          },
+        ],
+      }),
+    ).toEqual([]);
+  });
+
+  it("rejects fixed canvas sizing for exportable product apps even when reference dimensions are fixed", () => {
+    const fixedExportSchema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 900, unit: "px", width: 1440 },
+        sizing: { mode: "fixed-output" },
+      },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      icon: "upload-simple",
+                      label: "Export PNG",
+                      role: "export-image",
+                      value: "export.png",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateContractAcceptance({
+        schema: fixedExportSchema,
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            automated: true,
+            automatedTestName: "fixed reference size is preserved",
+            browser: true,
+            browserTestName: "browser: fixed reference size is preserved",
+            canvasSizingCoverage: "fixed-output-size",
+            componentType: "fixed-output canvas",
+            evidence: "product-output",
+            expectedObservable: "The exported shader canvas remains reference-defined and fixed at 1440x900.",
+            fixture: "shader reference fixture",
+            id: "canvas.sizing",
+            kind: "runtime",
+            userAction: "Open the app.",
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        '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".',
+      ]),
+    );
+  });
+
+  it("requires intrinsic media sizing acceptance for upload apps that let media own canvas size", () => {
+    expect(
+      validateContractAcceptance({
+        schema: createIntrinsicMediaUploadSchema(),
+        acceptance: contractAcceptanceFixture,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'canvas.sizing mode "intrinsic-media" with upload requires a runtime acceptance entry with canvasSizingCoverage "intrinsic-media-size" proving the app is a true media-viewer/source-native product where imported media natural dimensions intentionally own canvas.size. Uploaded background/source images inside product canvases must use "editable-output" and keep the current canvas size.',
+      ]),
+    );
+  });
+
+  it("accepts explicit intrinsic media sizing when browser coverage proves source-native canvas sizing", () => {
+    expect(
+      validateContractAcceptance({
+        schema: createIntrinsicMediaUploadSchema(),
+        acceptance: [
+          ...contractAcceptanceFixture,
+          {
+            automated: true,
+            automatedTestName: "media viewer uses uploaded natural dimensions",
+            browser: true,
+            browserTestName: "browser: upload source-native image updates canvas.size",
+            canvasSizingCoverage: "intrinsic-media-size",
+            componentType: "canvas",
+            evidence: "media-lifecycle",
+            expectedObservable: "Uploading a 1400x900 image intentionally changes canvas.size to the image natural dimensions.",
+            fixture: "source-native media viewer fixture",
+            id: "canvas.intrinsicSizing",
+            kind: "runtime",
+            userAction: "Upload an image with known natural dimensions.",
+          },
+        ],
+      }),
+    ).toEqual([]);
+  });
+});