@pixel-point/toolcraft 0.0.16 → 0.0.17

package/templates/starter/scripts/toolcraft-vite-env-activation.test.mjs

@@ -6,34 +6,35 @@ import test from "node:test";
 import { createServer } from "vite";
 
 const starterRoot = path.resolve(import.meta.dirname, "..");
-const generatedRuntimePath = path.join(
+const generatedProofControllerPath = path.join(
   starterRoot,
-  "src/toolcraft/runtime/react/app-shell/toolcraft-source-asset-context.tsx",
+  "src/toolcraft/runtime/react/app-shell/toolcraft-unavailable-resource-proof.ts",
 );
-const monorepoRuntimePath = path.resolve(
+const monorepoProofControllerPath = path.resolve(
   starterRoot,
-  "../packages/toolcraft-runtime/src/react/app-shell/toolcraft-source-asset-context.tsx",
+  "../packages/toolcraft-runtime/src/react/app-shell/toolcraft-unavailable-resource-proof.ts",
 );
+let transformedProofControllerSequence = 0;
 
-async function resolveRuntimeSource() {
+async function resolveProofControllerSource() {
   try {
     return {
-      filePath: generatedRuntimePath,
+      filePath: generatedProofControllerPath,
       requestPath:
-        "/src/toolcraft/runtime/react/app-shell/toolcraft-source-asset-context.tsx",
+        "/src/toolcraft/runtime/react/app-shell/toolcraft-unavailable-resource-proof.ts",
       root: starterRoot,
-      source: await fs.readFile(generatedRuntimePath, "utf8"),
+      source: await fs.readFile(generatedProofControllerPath, "utf8"),
     };
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
   }
 
   return {
-    filePath: monorepoRuntimePath,
+    filePath: monorepoProofControllerPath,
     requestPath:
-      "/packages/toolcraft-runtime/src/react/app-shell/toolcraft-source-asset-context.tsx",
+      "/packages/toolcraft-runtime/src/react/app-shell/toolcraft-unavailable-resource-proof.ts",
     root: path.resolve(starterRoot, ".."),
-    source: await fs.readFile(monorepoRuntimePath, "utf8"),
+    source: await fs.readFile(monorepoProofControllerPath, "utf8"),
   };
 }
 
@@ -46,7 +47,7 @@ function readInjectedViteEnv(code, mode) {
   return JSON.parse(match[1]);
 }
 
-async function transformRuntime({ mode, requestPath, root }) {
+async function transformProofController({ mode, requestPath, root }) {
   const server = await createServer({
     configFile: false,
     envDir: false,
@@ -65,67 +66,135 @@ async function transformRuntime({ mode, requestPath, root }) {
   }
 }
 
+async function loadTransformedProofController({
+  fixtureFlag,
+  mode,
+  requestPath,
+  root,
+}) {
+  const previousFixtureValue =
+    process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES;
+  try {
+    if (fixtureFlag === undefined) {
+      delete process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES;
+    } else {
+      process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES = fixtureFlag;
+    }
+    const code = await transformProofController({ mode, requestPath, root });
+    const moduleUrl =
+      `data:text/javascript;base64,${Buffer.from(code).toString("base64")}` +
+      `#toolcraft-proof-${++transformedProofControllerSequence}`;
+    const transformedModule = await import(moduleUrl);
+    assert.equal(
+      typeof transformedModule.decorateToolcraftUnavailableResourceProofCoordinator,
+      "function",
+    );
+    return {
+      code,
+      decorateCoordinator:
+        transformedModule.decorateToolcraftUnavailableResourceProofCoordinator,
+    };
+  } finally {
+    if (previousFixtureValue === undefined) {
+      delete process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES;
+    } else {
+      process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES = previousFixtureValue;
+    }
+  }
+}
+
+async function observeProofControllerDecoration(decorateCoordinator) {
+  const addedEvents = [];
+  const removedEvents = [];
+  const previousDocument = globalThis.document;
+  globalThis.document = {
+    addEventListener(eventName) {
+      addedEvents.push(eventName);
+    },
+    removeEventListener(eventName) {
+      removedEvents.push(eventName);
+    },
+  };
+  const originalDispose = async () => {};
+  const originalResolveResource = async () => new Uint8Array([1]);
+  const coordinator = {
+    dispose: originalDispose,
+    resolveResource: originalResolveResource,
+  };
+  try {
+    const returned = decorateCoordinator(coordinator, {});
+    const decorationApplied =
+      coordinator.dispose !== originalDispose &&
+      coordinator.resolveResource !== originalResolveResource;
+    await coordinator.dispose();
+    return {
+      addedEvents,
+      decorationApplied,
+      removedEvents,
+      returnedOriginal: returned === coordinator,
+    };
+  } finally {
+    if (previousDocument === undefined) delete globalThis.document;
+    else globalThis.document = previousDocument;
+  }
+}
+
 test("unavailable-resource proof activation uses Vite-static env access and stays production-disabled", async () => {
-  const runtime = await resolveRuntimeSource();
+  const proofController = await resolveProofControllerSource();
   assert.match(
-    runtime.source,
+    proofController.source,
     /import\.meta\.env\?\.MODE/u,
-    `${runtime.filePath} must read MODE through direct, Node-safe Vite-static access.`,
+    `${proofController.filePath} must read MODE through direct, Node-safe Vite-static access.`,
   );
   assert.match(
-    runtime.source,
+    proofController.source,
     /import\.meta\.env\?\.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES/u,
-    `${runtime.filePath} must read the protected fixture flag through direct, Node-safe Vite-static access.`,
+    `${proofController.filePath} must read the protected fixture flag through direct, Node-safe Vite-static access.`,
   );
   assert.doesNotMatch(
-    runtime.source,
+    proofController.source,
     /\bconst\s+\w+\s*=\s*import\.meta\s*(?:;|\n)/u,
-    `${runtime.filePath} must not alias import.meta before reading env.`,
+    `${proofController.filePath} must not alias import.meta before reading env.`,
   );
 
-  const previousFixtureValue =
-    process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES;
-  try {
-    process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES =
-      "unavailable-resource";
-    const testEnv = readInjectedViteEnv(
-      await transformRuntime({ ...runtime, mode: "test" }),
-      "test",
+  for (const scenario of [
+    { enabled: false, fixtureFlag: undefined, mode: "production" },
+    { enabled: false, fixtureFlag: undefined, mode: "development" },
+    { enabled: true, fixtureFlag: undefined, mode: "test" },
+    {
+      enabled: true,
+      fixtureFlag: "unavailable-resource",
+      mode: "production",
+    },
+  ]) {
+    const transformed = await loadTransformedProofController({
+      ...proofController,
+      fixtureFlag: scenario.fixtureFlag,
+      mode: scenario.mode,
+    });
+    const injectedEnv = readInjectedViteEnv(
+      transformed.code,
+      scenario.mode,
     );
-    assert.equal(testEnv.MODE, "test");
+    assert.equal(injectedEnv.MODE, scenario.mode);
     assert.equal(
-      testEnv.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES,
-      "unavailable-resource",
+      injectedEnv.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES,
+      scenario.fixtureFlag,
     );
-    assert.equal(
-      testEnv.MODE === "test" ||
-        testEnv.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES ===
-          "unavailable-resource",
-      true,
+    assert.deepEqual(
+      await observeProofControllerDecoration(
+        transformed.decorateCoordinator,
+      ),
+      {
+        addedEvents: scenario.enabled
+          ? ["toolcraft.browser-proof.unavailable-resource-request"]
+          : [],
+        decorationApplied: scenario.enabled,
+        removedEvents: scenario.enabled
+          ? ["toolcraft.browser-proof.unavailable-resource-request"]
+          : [],
+        returnedOriginal: true,
+      },
     );
-
-    delete process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES;
-    const productionEnv = readInjectedViteEnv(
-      await transformRuntime({ ...runtime, mode: "production" }),
-      "production",
-    );
-    assert.equal(productionEnv.MODE, "production");
-    assert.equal(
-      productionEnv.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES,
-      undefined,
-    );
-    assert.equal(
-      productionEnv.MODE === "test" ||
-        productionEnv.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES ===
-          "unavailable-resource",
-      false,
-    );
-  } finally {
-    if (previousFixtureValue === undefined) {
-      delete process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES;
-    } else {
-      process.env.VITE_TOOLCRAFT_BROWSER_PROOF_FIXTURES =
-        previousFixtureValue;
-    }
   }
 });

package/templates/starter/src/app/acceptance/export-artifact-coverage.ts

@@ -0,0 +1,113 @@
+import type {
+  ResolvedToolcraftAppSchema,
+  ToolcraftActionSchema,
+} from "@repo/toolcraft-runtime";
+
+import { getControlActions } from "./actions";
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftExportArtifactCoverage,
+} from "./types";
+
+const requiredCoverageByRole = {
+  "export-image": "all-required-image-export-behavior",
+  "export-video": "all-required-video-export-behavior",
+} as const satisfies Record<
+  "export-image" | "export-video",
+  ToolcraftExportArtifactCoverage
+>;
+
+function getCoverageValues(
+  entry: ToolcraftComponentAcceptance,
+): readonly ToolcraftExportArtifactCoverage[] {
+  if (!entry.exportArtifactCoverage) return [];
+  return typeof entry.exportArtifactCoverage === "string"
+    ? [entry.exportArtifactCoverage]
+    : entry.exportArtifactCoverage;
+}
+
+function isMediaExportAction(
+  action: ToolcraftActionSchema | string,
+): action is ToolcraftActionSchema & {
+  role: "export-image" | "export-video";
+} {
+  return (
+    typeof action !== "string" &&
+    (action.role === "export-image" || action.role === "export-video")
+  );
+}
+
+function collectMediaExportActions(schema: ResolvedToolcraftAppSchema) {
+  return (schema.panels.controls?.sections ?? []).flatMap((section) =>
+    Object.values(section.controls).flatMap((control) =>
+      control.type !== "panelActions" || !control.target
+        ? []
+        : getControlActions(control)
+            .filter(isMediaExportAction)
+            .map((action) => ({
+              requiredCoverage: requiredCoverageByRole[action.role],
+              role: action.role,
+              target: control.target,
+              value: action.value,
+            })),
+    ),
+  );
+}
+
+export function getToolcraftExportArtifactCoverageErrors({
+  acceptance,
+  schema,
+}: Readonly<{
+  acceptance: readonly ToolcraftComponentAcceptance[];
+  schema: ResolvedToolcraftAppSchema;
+}>): string[] {
+  const errors: string[] = [];
+  const exportActions = collectMediaExportActions(schema);
+
+  for (const entry of acceptance) {
+    const coverage = getCoverageValues(entry);
+    if (coverage.length === 0) continue;
+    if (entry.evidence !== "exported-bytes") {
+      errors.push(
+        `Acceptance "${entry.id}" declares exportArtifactCoverage but evidence is not "exported-bytes".`,
+      );
+    }
+    if (!entry.automated || !entry.browser) {
+      errors.push(
+        `Acceptance "${entry.id}" exportArtifactCoverage requires automated and browser proof.`,
+      );
+    }
+    for (const value of coverage) {
+      const hasMatchingAction = exportActions.some(
+        (action) =>
+          action.target === entry.target &&
+          action.requiredCoverage === value &&
+          (entry.actionCoverage ?? []).includes(action.value),
+      );
+      if (!hasMatchingAction) {
+        errors.push(
+          `Acceptance "${entry.id}" declares ${value} without a matching typed export action in target/actionCoverage.`,
+        );
+      }
+    }
+  }
+
+  for (const action of exportActions) {
+    const hasCoverage = acceptance.some(
+      (entry) =>
+        entry.target === action.target &&
+        entry.evidence === "exported-bytes" &&
+        entry.automated &&
+        entry.browser &&
+        (entry.actionCoverage ?? []).includes(action.value) &&
+        getCoverageValues(entry).includes(action.requiredCoverage),
+    );
+    if (!hasCoverage) {
+      errors.push(
+        `Typed ${action.role} action "${action.value}" on "${action.target}" requires ${action.requiredCoverage} acceptance coverage.`,
+      );
+    }
+  }
+
+  return errors;
+}

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

@@ -103,7 +103,7 @@ export function getToolcraftOutputBackgroundErrors({
 
   if (!schemaHasOutputBackgroundToggleControl(controls)) {
     errors.push(
-      'Product apps with Export PNG must expose export.includeBackground in runtime Setup as a Switch labeled "Background". PNG export must pass that runtime value to createToolcraftPngExportCanvas includeBackground; live preview must use shouldIncludeToolcraftPreviewBackground(state); video export keeps the background.',
+      'Product apps with Export PNG must expose export.includeBackground in runtime Setup as a Switch labeled "Background". Runtime artifact export owns PNG alpha and preserves the background for JPEG and video; bounded live preview must use shouldIncludeToolcraftPreviewBackground(state).',
     );
   }
 

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

@@ -11,7 +11,11 @@ import {
 import { getToolcraftOutputExportLayoutErrors } from "./output-export-layout-rules";
 import { buildToolcraftOutputExportFacts } from "./output-export-model";
 import { getToolcraftImageExportErrors } from "./output-image-export-rules";
-import type { ToolcraftVisibleControl } from "./types";
+import { getToolcraftExportArtifactCoverageErrors } from "./export-artifact-coverage";
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftVisibleControl,
+} from "./types";
 
 export {
   isOutputBackgroundToggleControl,
@@ -20,16 +24,22 @@ export {
 };
 
 export function getToolcraftOutputExportErrors({
+  acceptance,
   controls,
   schema,
   hasVideoExportAction = schemaHasVideoExportPanelAction(schema),
 }: {
+  acceptance: readonly ToolcraftComponentAcceptance[];
   controls: readonly ToolcraftVisibleControl[];
   hasVideoExportAction?: boolean;
   schema: ResolvedToolcraftAppSchema;
 }): string[] {
+  const exportArtifactCoverageErrors = getToolcraftExportArtifactCoverageErrors({
+    acceptance,
+    schema,
+  });
   if (!schemaHasPngExportPanelAction(schema)) {
-    return [];
+    return exportArtifactCoverageErrors;
   }
 
   const facts = buildToolcraftOutputExportFacts({
@@ -41,5 +51,6 @@ export function getToolcraftOutputExportErrors({
     ...getToolcraftOutputExportLayoutErrors(facts),
     ...getToolcraftOutputBackgroundErrors({ controls, facts }),
     ...getToolcraftImageExportErrors(facts),
+    ...exportArtifactCoverageErrors,
   ];
 }

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

@@ -58,6 +58,10 @@ export type ToolcraftAcceptanceEvidence =
   | "timeline-output"
   | "viewport-side-effect";
 
+export type ToolcraftExportArtifactCoverage =
+  | "all-required-image-export-behavior"
+  | "all-required-video-export-behavior";
+
 export type ToolcraftReferenceCoverage =
   | "canvas-sizing"
   | "control-mapping"
@@ -290,6 +294,9 @@ export type ToolcraftComponentAcceptance = {
   browserTestName: string;
   componentType: string;
   evidence: ToolcraftAcceptanceEvidence;
+  exportArtifactCoverage?:
+    | ToolcraftExportArtifactCoverage
+    | readonly ToolcraftExportArtifactCoverage[];
   expectedObservable: string;
   fixture: string;
   id: string;

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

@@ -160,8 +160,9 @@ const toolcraftAcceptanceValidators: readonly ToolcraftAcceptanceValidator[] = [
   {
     path: "schema.export",
     ruleId: "output-export-required",
-    validate: ({ controls, hasVideoExportAction, schema }) =>
+    validate: ({ acceptance, controls, hasVideoExportAction, schema }) =>
       getToolcraftOutputExportErrors({
+        acceptance,
         controls,
         hasVideoExportAction,
         schema,

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

@@ -0,0 +1,131 @@
+import { defineToolcraft } from "@repo/toolcraft-runtime";
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftExportArtifactCoverageErrors } from "./acceptance/export-artifact-coverage";
+import type { ToolcraftComponentAcceptance } from "./acceptance/types";
+
+function createSchema(roles: readonly ("export-image" | "export-video")[]) {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              output: {
+                actions: roles.map((role) => ({
+                  label: role === "export-image" ? "Export Image" : "Export Video",
+                  role,
+                  value: role === "export-image" ? "export.image" : "export.video",
+                })),
+                target: "actions.output",
+                type: "panelActions",
+              },
+            },
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  });
+}
+
+function createAcceptance(
+  overrides: Partial<ToolcraftComponentAcceptance> = {},
+): ToolcraftComponentAcceptance {
+  return {
+    actionCoverage: ["export.image"],
+    automated: true,
+    automatedTestName: "exports image",
+    browser: true,
+    browserTestName: "browser: exports image",
+    componentType: "panelActions",
+    evidence: "exported-bytes",
+    expectedObservable: "Downloads decoded image output.",
+    fixture: "image export fixture",
+    id: "actions.output",
+    kind: "control",
+    target: "actions.output",
+    userAction: "Click Export Image.",
+    ...overrides,
+  };
+}
+
+describe("Toolcraft export artifact acceptance", () => {
+  it("requires exact image coverage for an image action", () => {
+    const schema = createSchema(["export-image"]);
+
+    expect(
+      getToolcraftExportArtifactCoverageErrors({
+        acceptance: [createAcceptance()],
+        schema,
+      }),
+    ).toContainEqual(
+      expect.stringContaining("all-required-image-export-behavior"),
+    );
+    expect(
+      getToolcraftExportArtifactCoverageErrors({
+        acceptance: [
+          createAcceptance({
+            exportArtifactCoverage: "all-required-image-export-behavior",
+          }),
+        ],
+        schema,
+      }),
+    ).toEqual([]);
+  });
+
+  it("does not allow image coverage to satisfy video", () => {
+    const errors = getToolcraftExportArtifactCoverageErrors({
+      acceptance: [
+        createAcceptance({
+          actionCoverage: ["export.video"],
+          exportArtifactCoverage: "all-required-image-export-behavior",
+        }),
+      ],
+      schema: createSchema(["export-video"]),
+    });
+
+    expect(errors).toEqual([
+      expect.stringContaining("without a matching typed export action"),
+      expect.stringContaining("all-required-video-export-behavior"),
+    ]);
+  });
+
+  it("requires exported bytes plus automated browser proof", () => {
+    const errors = getToolcraftExportArtifactCoverageErrors({
+      acceptance: [
+        createAcceptance({
+          automated: false,
+          browser: false,
+          evidence: "command-side-effect",
+          exportArtifactCoverage: "all-required-image-export-behavior",
+        }),
+      ],
+      schema: createSchema(["export-image"]),
+    });
+
+    expect(errors).toEqual([
+      expect.stringContaining('evidence is not "exported-bytes"'),
+      expect.stringContaining("requires automated and browser proof"),
+      expect.stringContaining("all-required-image-export-behavior"),
+    ]);
+  });
+
+  it("allows one row to cover both typed actions explicitly", () => {
+    expect(
+      getToolcraftExportArtifactCoverageErrors({
+        acceptance: [
+          createAcceptance({
+            actionCoverage: ["export.image", "export.video"],
+            exportArtifactCoverage: [
+              "all-required-image-export-behavior",
+              "all-required-video-export-behavior",
+            ],
+          }),
+        ],
+        schema: createSchema(["export-image", "export-video"]),
+      }),
+    ).toEqual([]);
+  });
+});

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

@@ -4,7 +4,6 @@ import type { ToolcraftControlSchema } from "@repo/toolcraft-runtime";
 import type { ToolcraftComponentAcceptance } from "./acceptance/types";
 import {
   defineContractSchemaFixture,
-  contractSchemaFixture,
   validateContractAcceptance,
 } from "./starter-acceptance.contract-fixtures";
 
@@ -63,9 +62,11 @@ function createKeyframesSchema(
   title = "Style",
 ) {
   return defineContractSchemaFixture({
-    ...contractSchemaFixture,
+    canvas: {
+      enabled: true,
+      upload: true,
+    },
     panels: {
-      ...contractSchemaFixture.panels,
       controls: {
         sections: [
           {
@@ -75,7 +76,16 @@ function createKeyframesSchema(
         ],
         title: "Controls",
       },
-      timeline: { defaultDurationSeconds: 8, enabled: true, mode: "keyframes" as const },
+      timeline: {
+        defaultDurationSeconds: 8,
+        enabled: true,
+        mode: "keyframes",
+      },
+    },
+    toolbar: {
+      history: true,
+      radar: true,
+      zoom: true,
     },
   });
 }

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

@@ -1,6 +1,9 @@
 import { describe, expect, it } from "vitest";
 
-import { schemaHasVideoExportPanelAction } from "./acceptance/output-export";
+import {
+  getToolcraftOutputExportErrors,
+  schemaHasVideoExportPanelAction,
+} from "./acceptance/output-export";
 import { defineContractSchemaFixture, validateContractAcceptance } from "./starter-acceptance.contract-fixtures";
 
 describe("Toolcraft output export synthetic rules", () => {
@@ -20,6 +23,44 @@ describe("Toolcraft output export synthetic rules", () => {
     expect(schemaHasVideoExportPanelAction(playbackSchema)).toBe(false);
   });
 
+  it("does not let a video-only schema bypass artifact coverage", () => {
+    const videoOnlySchema = defineContractSchemaFixture({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                outputActions: {
+                  actions: [
+                    {
+                      label: "Export Video",
+                      role: "export-video",
+                      value: "export.video",
+                    },
+                  ],
+                  target: "actions.output",
+                  type: "panelActions",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      getToolcraftOutputExportErrors({
+        acceptance: [],
+        controls: [],
+        schema: videoOnlySchema,
+      }),
+    ).toEqual([
+      expect.stringContaining("all-required-video-export-behavior"),
+    ]);
+  });
+
   it("rejects reset actions in sticky footer panelActions", () => {
     const schemaWithFooterReset = defineContractSchemaFixture({
       canvas: {

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

@@ -23,6 +23,7 @@ import type {
   ToolcraftControlPartCoverage,
   ToolcraftControlSectionInventoryEntry,
   ToolcraftCustomControlCoverage,
+  ToolcraftExportArtifactCoverage,
   ToolcraftLayerCoverage,
   ToolcraftInteractionCapability,
   ToolcraftInteractionEvidenceSource,
@@ -96,6 +97,7 @@ export type {
   ToolcraftControlPartCoverage,
   ToolcraftControlSectionInventoryEntry,
   ToolcraftCustomControlCoverage,
+  ToolcraftExportArtifactCoverage,
   ToolcraftLayerCoverage,
   ToolcraftInteractionCapability,
   ToolcraftInteractionEvidenceSource,