@pixel-point/toolcraft 0.0.17 → 0.0.18

package/templates/starter/scripts/toolcraft-product-export-boundary.test.mjs

@@ -0,0 +1,196 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { evaluateToolcraftProductBoundary } from "./toolcraft-product-boundary.mjs";
+import { createToolcraftProductBoundaryFixture as createFixture } from "./toolcraft-product-boundary-test-fixtures.mjs";
+
+test("keeps artifact encoding and download mechanics runtime-owned", async (context) => {
+  const workspaceRuntimeExportSpecifier = [
+    "@repo",
+    "toolcraft-runtime",
+    "export",
+    "image-artifact-export",
+  ].join("/");
+  const rootDir = await createFixture(context, {
+    "src/features/export-mechanics.ts": `
+      import { createToolcraftVideoEncoderBackend as createAliasBackend } from "@/toolcraft/runtime/export/video-encoding-backend";
+      import { exportToolcraftImageArtifact } from "${workspaceRuntimeExportSpecifier}";
+      import { downloadToolcraftArtifact } from "../toolcraft/runtime/export/artifact-download";
+      import { Output } from "mediabunny";
+      export function exportArtifact(canvas: HTMLCanvasElement) {
+        const recorder = new MediaRecorder(canvas.captureStream());
+        const encoder = new VideoEncoder({ error() {}, output() {} });
+        canvas.toBlob(() => undefined);
+        canvas.toDataURL();
+        URL.createObjectURL(new Blob());
+        void createAliasBackend;
+        void exportToolcraftImageArtifact;
+        void downloadToolcraftArtifact;
+        void Output;
+        void recorder;
+        void encoder;
+      }
+    `,
+    "src/features/safe-renderer.ts": `
+      import * as Runtime from "@/toolcraft/runtime";
+      import {
+        getToolcraftImageExportSize,
+        shouldIncludeToolcraftPreviewBackground,
+        validateToolcraftArtifactSize,
+      } from "@/toolcraft/runtime";
+      import type {
+        ToolcraftExportFrame,
+        ToolcraftProductExportRenderer,
+      } from "@/toolcraft/runtime";
+      export const renderFrame = ({ context }) => context.fillRect(0, 0, 1, 1);
+      void Runtime;
+      void getToolcraftImageExportSize;
+      void shouldIncludeToolcraftPreviewBackground;
+      void validateToolcraftArtifactSize;
+      void (null as unknown as ToolcraftExportFrame);
+      void (null as unknown as ToolcraftProductExportRenderer);
+    `,
+    "src/features/shadowed-globals.ts": `
+      export function localNames(MediaRecorder, VideoEncoder, URL) {
+        void new MediaRecorder();
+        void new VideoEncoder();
+        URL.createObjectURL();
+      }
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.equal(result.violations.length, 10);
+  assert.equal(
+    result.violations.every(
+      (violation) => violation.kind === "runtime-export-ownership",
+    ),
+    true,
+  );
+  assert.equal(
+    result.violations.some((violation) =>
+      violation.repoPath.endsWith("shadowed-globals.ts"),
+    ),
+    false,
+  );
+  assert.equal(
+    result.violations.some((violation) =>
+      violation.repoPath.endsWith("safe-renderer.ts"),
+    ),
+    false,
+  );
+});
+
+test("classifies every runtime export mechanics module reference once", async (context) => {
+  const workspaceRuntimeExportRoot = [
+    "@repo",
+    "toolcraft-runtime",
+    "export",
+  ].join("/");
+  const rootDir = await createFixture(context, {
+    "src/features/dynamic-import.ts": `
+      export async function loadMedia() {
+        return import("mediabunny");
+      }
+    `,
+    "src/features/import-equals.ts": `
+      import Backend = require("@/toolcraft/runtime/export/video-encoding-backend");
+      void Backend;
+    `,
+    "src/features/import-type.ts": `
+      type Backend = import("@/toolcraft/runtime/export/video-encoding-backend").ToolcraftVideoEncoderBackend;
+      void (null as unknown as Backend);
+    `,
+    "src/features/regular-export.ts": `
+      export {
+        createToolcraftVideoEncoderBackend as createFirstBackend,
+        createToolcraftVideoEncoderBackend as createSecondBackend,
+      } from "@/toolcraft/runtime/export/video-encoding-backend";
+    `,
+    "src/features/regular-import.ts": `
+      import {
+        createToolcraftVideoEncoderBackend as createFirstBackend,
+        createToolcraftVideoEncoderBackend as createSecondBackend,
+      } from "@/toolcraft/runtime/export/video-encoding-backend";
+      void createFirstBackend;
+      void createSecondBackend;
+    `,
+    "src/features/require.ts": `
+      export const backend = require("${workspaceRuntimeExportRoot}/video-encoding-backend");
+    `,
+    "src/features/safe-root-type-import.ts": `
+      import type { ToolcraftExportFrame } from "@/toolcraft/runtime";
+      void (null as unknown as ToolcraftExportFrame);
+    `,
+    "src/features/side-effect-import.ts": `import "mediabunny";`,
+    "src/features/type-only-export.ts": `
+      export type {
+        ToolcraftImageArtifactExportRequest,
+        ToolcraftImageArtifactExportResult,
+      } from "${workspaceRuntimeExportRoot}/image-artifact-export";
+    `,
+    "src/features/type-only-import-equals.ts": `
+      import type Backend = require("@/toolcraft/runtime/export/video-encoding-backend");
+      void (null as unknown as Backend);
+    `,
+    "src/features/type-only-import.ts": `
+      import type {
+        ToolcraftVideoArtifactExportRequest,
+        ToolcraftVideoArtifactExportResult,
+      } from "${workspaceRuntimeExportRoot}/video-artifact-export";
+      void (null as unknown as ToolcraftVideoArtifactExportRequest);
+      void (null as unknown as ToolcraftVideoArtifactExportResult);
+    `,
+    "src/features/typeof-import-type.ts": `
+      type MediaBunny = typeof import("mediabunny");
+      void (null as unknown as MediaBunny);
+    `,
+    "src/features/export-boundary.test.ts": `
+      import type { ToolcraftVideoEncoderBackend } from "@/toolcraft/runtime/export/video-encoding-backend";
+      void (null as unknown as ToolcraftVideoEncoderBackend);
+    `,
+    "e2e/test-support/export-fixture.ts": `
+      export type { ToolcraftVideoEncoderBackend } from "@/toolcraft/runtime/export/video-encoding-backend";
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(
+    result.violations.map(({ repoPath }) => repoPath).sort(),
+    [
+      "src/features/dynamic-import.ts",
+      "src/features/import-equals.ts",
+      "src/features/import-type.ts",
+      "src/features/regular-export.ts",
+      "src/features/regular-import.ts",
+      "src/features/require.ts",
+      "src/features/side-effect-import.ts",
+      "src/features/type-only-export.ts",
+      "src/features/type-only-import-equals.ts",
+      "src/features/type-only-import.ts",
+      "src/features/typeof-import-type.ts",
+    ],
+  );
+  assert.equal(
+    new Set(result.violations.map(({ repoPath }) => repoPath)).size,
+    result.violations.length,
+  );
+  assert.equal(
+    result.violations.every(
+      (violation) => violation.kind === "runtime-export-ownership",
+    ),
+    true,
+  );
+  assert.equal(
+    result.violations.some(({ repoPath }) =>
+      [
+        "src/features/export-boundary.test.ts",
+        "src/features/safe-root-type-import.ts",
+        "e2e/test-support/export-fixture.ts",
+      ].includes(repoPath),
+    ),
+    false,
+  );
+});

package/templates/starter/scripts/toolcraft-typescript-source-evidence-structure.test.mjs

@@ -41,4 +41,24 @@ test("keeps TypeScript parsing and boundary facts on one canonical path", async
   assert.deepEqual(checkerOwners, [
     "toolcraft-typescript-analysis.mjs",
   ]);
+
+  const productBoundarySource = await fs.readFile(
+    path.join(scriptsDir, "toolcraft-product-boundary-ast.mjs"),
+    "utf8",
+  );
+  const controlBoundarySource = await fs.readFile(
+    path.join(scriptsDir, "toolcraft-product-control-boundary.mjs"),
+    "utf8",
+  );
+  const modulePolicySource = await fs.readFile(
+    path.join(scriptsDir, "toolcraft-product-boundary-module-policy.mjs"),
+    "utf8",
+  );
+
+  assert.match(productBoundarySource, /createToolcraftProductControlInspector/u);
+  assert.match(
+    modulePolicySource,
+    /isToolcraftPrivateControlImplementationModule/u,
+  );
+  assert.doesNotMatch(controlBoundarySource, /(?:ts\.)?createSourceFile\(/u);
 });

package/templates/starter/scripts/toolcraft-typescript-source-evidence.mjs

@@ -300,6 +300,7 @@ export async function createToolcraftTypeScriptSourceRecord({
     inspectors.createToolcraftStaticStringResolver(sourceFile, checker);
   const inspectorInput = {
     absolutePath,
+    checker,
     getNodeLocation,
     repoPath,
     resolveStaticString,

package/templates/starter/scripts/toolcraft-unavailable-resource-evidence-facade.test.mjs

@@ -29,6 +29,7 @@ function createFiniteObservation(width, height) {
     finiteControlSize: { height, width },
     finiteControlsPresent: true,
     overflow: "hidden",
+    productSceneStatus: null,
     sceneRect: null,
     viewportOffset: { x: 0, y: 0 },
   };
@@ -42,6 +43,7 @@ function createInfiniteObservation() {
     finiteControlSize: null,
     finiteControlsPresent: false,
     overflow: "visible",
+    productSceneStatus: "ready",
     sceneRect: { height: 400, width: 640, x: -320, y: -200 },
     viewportOffset: { x: 0, y: 0 },
   };

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.`,
     );
   }