@pixel-point/toolcraft 0.0.16 → 0.0.18

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/artifact-export-intent.ts

@@ -0,0 +1,130 @@
+import type { ToolcraftArtifactExportIntent } from "./types";
+
+export type ToolcraftArtifactExportDelivery = Readonly<{
+  imageEnabled: boolean;
+  videoEnabled: boolean;
+}>;
+
+export type ToolcraftArtifactExportSchemaFacts = Readonly<{
+  hasImageExportAction: boolean;
+  hasImageExportSection: boolean;
+  hasVideoExportAction: boolean;
+  hasVideoExportSection: boolean;
+}>;
+
+export type ToolcraftArtifactExportIntentValidation = Readonly<{
+  delivery: ToolcraftArtifactExportDelivery;
+  errors: readonly string[];
+}>;
+
+export function resolveToolcraftArtifactExportIntent(
+  intent: ToolcraftArtifactExportIntent,
+): ToolcraftArtifactExportDelivery {
+  return Object.freeze({
+    imageEnabled: intent.image.mode !== "user-removed",
+    videoEnabled: intent.video.mode === "user-requested",
+  });
+}
+
+export function getToolcraftArtifactExportIntentEvidenceErrors(
+  intent: ToolcraftArtifactExportIntent,
+): readonly string[] {
+  const errors: string[] = [];
+
+  if (
+    intent.image.mode !== "toolcraft-default" &&
+    intent.image.evidence.trim() === ""
+  ) {
+    errors.push(
+      `Image export ${intent.image.mode} intent requires non-empty evidence.`,
+    );
+  }
+
+  if (
+    intent.video.mode === "user-requested" &&
+    intent.video.evidence.trim() === ""
+  ) {
+    errors.push(
+      "Video export user-requested intent requires non-empty evidence.",
+    );
+  }
+
+  return errors;
+}
+
+function getToolcraftArtifactCorrespondenceErrors({
+  actionRole,
+  artifact,
+  enabled,
+  hasAction,
+  hasSection,
+  intentMode,
+  sectionArticle,
+  sectionTitle,
+}: Readonly<{
+  actionRole: "export-image" | "export-video";
+  artifact: "Image" | "Video";
+  enabled: boolean;
+  hasAction: boolean;
+  hasSection: boolean;
+  intentMode:
+    | ToolcraftArtifactExportIntent["image"]["mode"]
+    | ToolcraftArtifactExportIntent["video"]["mode"];
+  sectionArticle: "a" | "an";
+  sectionTitle: "Image Export" | "Video Export";
+}>): string[] {
+  const errors: string[] = [];
+  const requirement = enabled ? "requires" : "must not have";
+
+  if (hasAction !== enabled) {
+    errors.push(
+      `${artifact} export intent "${intentMode}" ${requirement} an ${actionRole} panel action.`,
+    );
+  }
+
+  if (hasSection !== enabled) {
+    errors.push(
+      `${artifact} export intent "${intentMode}" ${requirement} ${sectionArticle} "${sectionTitle}" section.`,
+    );
+  }
+
+  return errors;
+}
+
+export function validateToolcraftArtifactExportIntentCorrespondence({
+  hasImageExportAction,
+  hasImageExportSection,
+  hasVideoExportAction,
+  hasVideoExportSection,
+  intent,
+}: ToolcraftArtifactExportSchemaFacts &
+  Readonly<{
+    intent: ToolcraftArtifactExportIntent;
+  }>): ToolcraftArtifactExportIntentValidation {
+  const delivery = resolveToolcraftArtifactExportIntent(intent);
+  const errors = [
+    ...getToolcraftArtifactExportIntentEvidenceErrors(intent),
+    ...getToolcraftArtifactCorrespondenceErrors({
+      actionRole: "export-image",
+      artifact: "Image",
+      enabled: delivery.imageEnabled,
+      hasAction: hasImageExportAction,
+      hasSection: hasImageExportSection,
+      intentMode: intent.image.mode,
+      sectionArticle: "an",
+      sectionTitle: "Image Export",
+    }),
+    ...getToolcraftArtifactCorrespondenceErrors({
+      actionRole: "export-video",
+      artifact: "Video",
+      enabled: delivery.videoEnabled,
+      hasAction: hasVideoExportAction,
+      hasSection: hasVideoExportSection,
+      intentMode: intent.video.mode,
+      sectionArticle: "a",
+      sectionTitle: "Video Export",
+    }),
+  ];
+
+  return { delivery, errors };
+}

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

@@ -26,7 +26,7 @@ export function getConditionValidationErrors({
   label,
 }: {
   condition: ToolcraftControlConditionSchema;
-  conditionName: "disabledWhen" | "visibleWhen";
+  conditionName: "disabledWhen";
   controlTargets: ReadonlySet<string>;
   label: string;
 }): string[] {

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

@@ -1,6 +1,6 @@
 import type {
   ResolvedToolcraftAppSchema,
-  ToolcraftControlSchema,
+  ResolvedToolcraftControlSchema,
   ToolcraftTimelineMode,
 } from "@repo/toolcraft-runtime";
 
@@ -21,7 +21,7 @@ export type ToolcraftControlAcceptanceContext = {
 };
 
 export type ToolcraftControlRuleContext = {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   controlId: string;
   controlTargets: ReadonlySet<string>;
   label: string;

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

@@ -1,7 +1,7 @@
 import {
   getToolcraftControlKeyframeCapability,
   type ResolvedToolcraftAppSchema,
-  type ToolcraftControlSchema,
+  type ResolvedToolcraftControlSchema,
   type ToolcraftTimelineMode,
 } from "@repo/toolcraft-runtime";
 
@@ -21,7 +21,6 @@ import {
 import type {
   ToolcraftBackgroundOutputCoverage,
   ToolcraftComponentAcceptance,
-  ToolcraftConditionalVisibilityCoverage,
   ToolcraftOrientationGizmoCoverage,
   ToolcraftProductReadiness,
 } from "./types";
@@ -53,7 +52,7 @@ function getControlAcceptanceEntryErrors({
   entry,
   label,
 }: {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   entry: ToolcraftComponentAcceptance;
   label: string;
 }): string[] {
@@ -98,7 +97,7 @@ function getControlLifecycleAndCustomErrors({
   schema,
 }: {
   acceptance: readonly ToolcraftComponentAcceptance[];
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   entry: ToolcraftComponentAcceptance;
   label: string;
   layersEnabled: boolean;
@@ -155,7 +154,7 @@ function getControlEvidenceErrors({
   schema,
   sectionTitle,
 }: {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   controlId: string;
   entry: ToolcraftComponentAcceptance;
   label: string;
@@ -177,19 +176,6 @@ function getControlEvidenceErrors({
     );
   }
 
-  if (
-    control.visibleWhen &&
-    !hasTypedCoverage<ToolcraftConditionalVisibilityCoverage>(
-      entry.visibilityCoverage,
-      "all-conditional-visibility",
-      ["hidden", "visible"],
-    )
-  ) {
-    errors.push(
-      `${label} uses visibleWhen and must declare visibilityCoverage for both "hidden" and "visible" states reached through ${control.visibleWhen.target}.`,
-    );
-  }
-
   if (
     schemaHasPngExportPanelAction(schema) &&
     isOutputBackgroundToggleControl({ control, controlId, sectionTitle })
@@ -228,7 +214,7 @@ function getControlPartAndRuntimeCoverageErrors({
   layersEnabled,
   timelineMode,
 }: {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   entry: ToolcraftComponentAcceptance;
   label: string;
   layersEnabled: boolean;
@@ -281,7 +267,7 @@ export function getControlAcceptanceCoverageErrors({
   timelineMode,
 }: {
   acceptance: readonly ToolcraftComponentAcceptance[];
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   controlId: string;
   entry: ToolcraftComponentAcceptance;
   label: string;

package/templates/starter/src/app/acceptance/control-acceptance-kind-rules.ts

@@ -1,5 +1,8 @@
 import { getToolcraftSegmentedStaticFitError } from "@repo/toolcraft-runtime";
-import type { ToolcraftControlSchema } from "@repo/toolcraft-runtime";
+import type {
+  ToolcraftCollectionItemControlSchema,
+  ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
 
 import { getActionValue, isResetPanelAction } from "./actions";
 import {
@@ -103,13 +106,29 @@ function getOptionControlAcceptanceErrors({
     }
   }
 
-  if (control.type === "collectionActions" && control.itemControl) {
-    const segmentedLayoutError = getToolcraftSegmentedStaticFitError(
-      control.itemControl,
+  const nestedItemControls: Array<
+    [string, ToolcraftCollectionItemControlSchema]
+  > = [];
+
+  if (control.itemControl) {
+    nestedItemControls.push(["itemControl", control.itemControl]);
+  }
+
+  if (control.itemControls) {
+    nestedItemControls.push(
+      ...Object.entries(control.itemControls).map(
+        ([itemId, itemControl]): [string, ToolcraftCollectionItemControlSchema] =>
+          [`itemControls.${itemId}`, itemControl],
+      ),
     );
+  }
+
+  for (const [itemId, itemControl] of nestedItemControls) {
+    const segmentedLayoutError =
+      getToolcraftSegmentedStaticFitError(itemControl);
 
     if (segmentedLayoutError) {
-      errors.push(`${label} itemControl ${segmentedLayoutError}`);
+      errors.push(`${label} ${itemId} ${segmentedLayoutError}`);
     }
   }
 

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

@@ -140,17 +140,6 @@ function getControlStatePolicyErrors({
 >): string[] {
   const errors: string[] = [];
 
-  if (control.visibleWhen) {
-    errors.push(
-      ...getConditionValidationErrors({
-        condition: control.visibleWhen,
-        conditionName: "visibleWhen",
-        controlTargets,
-        label,
-      }),
-    );
-  }
-
   if (control.disabledWhen) {
     errors.push(
       ...getConditionValidationErrors({
@@ -164,13 +153,13 @@ function getControlStatePolicyErrors({
 
   if (control.disabled === true) {
     errors.push(
-      `${label} sets disabled: true. Generated product panels should show only controls usable in the current state; hide unavailable product controls with visibleWhen instead of rendering disabled controls.`,
+      `${label} sets disabled: true. Generated product panels should show only controls usable in the current state; declare conditional applicability instead of rendering disabled controls.`,
     );
   }
 
   if (control.disabledWhen) {
     errors.push(
-      `${label} uses disabledWhen. Generated product panels should show only controls usable in the current state; hide unavailable product controls with visibleWhen instead of rendering disabled controls.`,
+      `${label} uses disabledWhen. Generated product panels should show only controls usable in the current state; declare conditional applicability instead of rendering disabled controls.`,
     );
   }