@pixel-point/toolcraft 0.0.6 → 0.0.8

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

@@ -150,6 +150,7 @@ const builtInToolcraftControlTypeValues = [
   "channelMixer",
   "checkbox",
   "code",
+  "collectionActions",
   "color",
   "colorOpacity",
   "curves",
@@ -385,6 +386,34 @@ function getAcceptanceEvidenceText(entry: ToolcraftComponentAcceptance): string
   ].join(" ");
 }
 
+function getFileDropLifecycleCoverageErrors(
+  label: string,
+  entry: ToolcraftComponentAcceptance,
+): string[] {
+  const errors: string[] = [];
+  const evidenceText = getAcceptanceEvidenceText(entry);
+
+  if (entry.evidence !== "media-lifecycle") {
+    errors.push(
+      `${label} fileDrop acceptance evidence must be "media-lifecycle" so upload, clear, and reset behavior cannot be replaced by generic product-output coverage.`,
+    );
+  }
+
+  if (
+    !/\b(upload|import|drop|drag|browse|choose|select file|source image)\b/i.test(
+      evidenceText,
+    ) ||
+    !/\b(clear|remove|delete|trash)\b/i.test(evidenceText) ||
+    !/\b(reset|reset controls|section reset|global reset)\b/i.test(evidenceText)
+  ) {
+    errors.push(
+      `${label} fileDrop acceptance must prove upload/import, clear/remove, and section or global reset remove source media.`,
+    );
+  }
+
+  return errors;
+}
+
 const conditionOperatorLabels = [
   "equals",
   "notEquals",
@@ -520,9 +549,109 @@ function isCustomToolcraftControl(control: ToolcraftControlSchema): boolean {
   return !builtInToolcraftControlTypes.has(control.type);
 }
 
+const collectionEntityCustomControlRe =
+  /\b(collection|repeatable|list|lists|item|items|entry|entries|row|rows|asset|assets|object|objects|color|colors|swatch|swatches|glyph|glyphs|symbol|symbols|point|points|stop|stops|variant|variants|rule|rules|mask|masks|shape|shapes|layer|layers|media|image|images|file|files)\b/i;
+const collectionOperationCustomControlRe =
+  /\b(add|adding|delete|deleting|remove|removing|reorder|reordering|order|ordering|sort|sorting|select|selecting|selected|selection|duplicate|duplicating|upload|import|clear|clearing)\b/i;
+
+const actionLikeCustomControlRe =
+  /\b(add|adding|delete|deleting|remove|removing|duplicate|duplicating|sort|sorting|normalize|normalizing|clear|clearing|reset|shuffle|randomize|randomizing)\b/i;
+
+const chromeOnlyCustomControlReasonRe =
+  /\b(icon|icons|visual|style|styling|layout|spacing|chrome|button|buttons|compact|custom look|custom ui)\b/i;
+const productInteractionCustomControlReasonRe =
+  /\b(runtime|state|canvas|output|export|upload|import|preview|reorder|ordering|sort|drag|resize|handle|threshold|density|mapping|geometry|nested|multi|multiple|per-item|metadata|hit target|validation|selection)\b/i;
+const collectionValueKeyRe =
+  /^(items?|entries|rows|assets|objects|colors?|glyphs?|symbols?|points?|stops?|variants?|rules?|masks?|shapes?|layers?|media|images?|files?)$/i;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringifyUnknownForFitCheck(value: unknown): string {
+  if (value == null) {
+    return "";
+  }
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(stringifyUnknownForFitCheck).join(" ");
+  }
+
+  if (isRecord(value)) {
+    return Object.entries(value)
+      .flatMap(([key, entryValue]) => [key, stringifyUnknownForFitCheck(entryValue)])
+      .join(" ");
+  }
+
+  return "";
+}
+
+function arrayLooksLikeCollectionValue(value: readonly unknown[]): boolean {
+  return (
+    value.length === 0 ||
+    value.some((item) => isRecord(item) || Array.isArray(item) || typeof item === "string")
+  );
+}
+
+function hasCollectionValueShape(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return Array.isArray(value) && arrayLooksLikeCollectionValue(value);
+  }
+
+  return Object.entries(value).some(([key, entryValue]) => {
+    if (Array.isArray(entryValue)) {
+      return collectionValueKeyRe.test(key) || arrayLooksLikeCollectionValue(entryValue);
+    }
+
+    return collectionValueKeyRe.test(key) && isRecord(entryValue);
+  });
+}
+
+function getCustomFitCheckSearchText(
+  entry: ToolcraftComponentAcceptance,
+  control?: ToolcraftControlSchema,
+): string {
+  return [
+    control?.type,
+    control?.target,
+    typeof control?.label === "string" ? control.label : undefined,
+    stringifyUnknownForFitCheck(control?.defaultValue),
+    entry.id,
+    entry.target,
+    entry.componentType,
+    entry.expectedObservable,
+    entry.userAction,
+    entry.builtInFitCheck?.whyInsufficient,
+    entry.builtInFitCheck?.productObservable,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+function isCollectionLikeCustomControl(
+  entry: ToolcraftComponentAcceptance,
+  control: ToolcraftControlSchema,
+): boolean {
+  if (hasCollectionValueShape(control.defaultValue)) {
+    return true;
+  }
+
+  const searchText = getCustomFitCheckSearchText(entry, control);
+
+  return (
+    collectionEntityCustomControlRe.test(searchText) &&
+    collectionOperationCustomControlRe.test(searchText)
+  );
+}
+
 function getBuiltInFitCheckErrors(
   label: string,
   entry: ToolcraftComponentAcceptance,
+  control: ToolcraftControlSchema,
 ): string[] {
   const fitCheck = entry.builtInFitCheck;
 
@@ -574,6 +703,32 @@ function getBuiltInFitCheckErrors(
     );
   }
 
+  const searchText = getCustomFitCheckSearchText(entry, control);
+
+  if (
+    isCollectionLikeCustomControl(entry, control) &&
+    !checkedBuiltIns.includes("collectionActions")
+  ) {
+    errors.push(
+      `${label} builtInFitCheck.checkedBuiltIns must include collectionActions when the custom control owns a growable, removable, selectable, or reorderable runtime item set.`,
+    );
+  }
+
+  if (actionLikeCustomControlRe.test(searchText) && !checkedBuiltIns.includes("actions")) {
+    errors.push(
+      `${label} builtInFitCheck.checkedBuiltIns must include actions when the custom control exposes local command buttons such as add, remove, delete, duplicate, sort, normalize, or clear.`,
+    );
+  }
+
+  if (
+    chromeOnlyCustomControlReasonRe.test(fitCheck.whyInsufficient) &&
+    !productInteractionCustomControlReasonRe.test(fitCheck.whyInsufficient)
+  ) {
+    errors.push(
+      `${label} builtInFitCheck.whyInsufficient cannot justify a custom control only with icons, layout, styling, or custom buttons; name the product interaction or value model that built-ins cannot express.`,
+    );
+  }
+
   return errors;
 }
 
@@ -714,6 +869,10 @@ function getControlLabelText(control: ToolcraftControlSchema): string {
   return typeof control.label === "string" ? control.label : "";
 }
 
+function hasVisibleControlLabel(control: ToolcraftControlSchema): boolean {
+  return typeof control.label === "string" && control.label.trim().length > 0;
+}
+
 const singleCurveSemanticPattern =
   /\b(acceleration|accel|bend|easing|ease|response|depth|mask|opacity|alpha|motion|velocity|threshold|falloff|remap|remapping)\b|speed\s+profile|mapping\s+curve|curve\s+mapping/i;
 const rgbCurveSemanticPattern =
@@ -1603,13 +1762,23 @@ function getToolcraftControlDescriptionError({
 }
 
 function isToolcraftColorSectionTitle(sectionTitle: string | undefined): boolean {
-  return /\b(colou?rs?|palette|palettes)\b/i.test(sectionTitle ?? "");
+  return /\b(colou?rs?|palette|palettes|shades?|accents?)\b/i.test(
+    sectionTitle ?? "",
+  );
 }
 
 function isToolcraftSequentialColorLabel(label: string): boolean {
   return /^colou?r\s+\d+$/i.test(label.trim());
 }
 
+function isToolcraftPaletteVariationTarget(target: string): boolean {
+  return (
+    /(?:^|\.)(?:palette|palettes|colou?rs?|shades?|accents?)\b/i.test(
+      target,
+    ) || /(?:^|\.)(?:accent|shade|colou?r)\d+\b/i.test(target)
+  );
+}
+
 function isToolcraftSimplePaletteDistributionLabel(label: string): boolean {
   return /^(spread|mix|distribution)$/i.test(label.trim());
 }
@@ -1648,6 +1817,76 @@ function isToolcraftObviousColorSectionControlDescription({
   );
 }
 
+function getToolcraftColorBankLabelErrors({
+  controls,
+  sectionLabel,
+  sectionTitle,
+}: {
+  controls: readonly [string, ToolcraftControlSchema][];
+  sectionLabel: string;
+  sectionTitle: string | undefined;
+}): string[] {
+  const colorControls = controls.filter(([, control]) => {
+    if (control.type !== "color" && control.type !== "colorOpacity") {
+      return false;
+    }
+
+    return true;
+  });
+
+  if (colorControls.length < 2) {
+    return [];
+  }
+
+  const loosePrefixes = new Set(
+    colorControls
+      .map(([, control]) => getToolcraftLooseTargetPrefix(control.target))
+      .filter((prefix): prefix is string => Boolean(prefix)),
+  );
+
+  if (loosePrefixes.size !== 1) {
+    return [];
+  }
+
+  const sequentialColorControls = colorControls.filter(([, control]) =>
+    isToolcraftSequentialColorLabel(getControlLabelText(control)),
+  );
+  const isPaletteVariationBank =
+    colorControls.every(([, control]) =>
+      isToolcraftPaletteVariationTarget(control.target),
+    ) ||
+    (isToolcraftColorSectionTitle(sectionTitle) &&
+      sequentialColorControls.length > 0);
+
+  if (!isPaletteVariationBank) {
+    return [];
+  }
+
+  const visibleColorControls = colorControls.filter(([, control]) =>
+    hasVisibleControlLabel(control),
+  );
+  const errors: string[] = [];
+
+  if (
+    visibleColorControls.length > 0 &&
+    visibleColorControls.length < colorControls.length
+  ) {
+    errors.push(
+      `${sectionLabel} mixes labeled and unlabeled color items in one palette variation group. Decide label visibility for the whole group: omit all per-item labels when colors only add variety, or label every item only when each color has a distinct user-facing role.`,
+    );
+  }
+
+  for (const [controlId, control] of sequentialColorControls) {
+    const label = getControlLabelText(control).trim();
+
+    errors.push(
+      `${sectionLabel} / ${controlId} uses visible label "${label}" for a palette variation color. When colors only add variety to one shared palette, set label: false or use collectionActions with unlabeled items. Keep visible labels only when each color edits a distinct user-facing entity such as Fill, Stroke, Background, Connector, or Object color.`,
+    );
+  }
+
+  return errors;
+}
+
 function getToolcraftControlSectionGroupingErrors(
   schema: ResolvedToolcraftAppSchema,
 ): string[] {
@@ -1737,6 +1976,14 @@ function getToolcraftControlSectionGroupingErrors(
       );
     }
 
+    errors.push(
+      ...getToolcraftColorBankLabelErrors({
+        controls,
+        sectionLabel,
+        sectionTitle,
+      }),
+    );
+
     for (const [controlId, control] of controls) {
       const strictPrefix = getToolcraftStrictTargetPrefix(control.target);
       const loosePrefix = getToolcraftLooseTargetPrefix(control.target);
@@ -2121,7 +2368,7 @@ export function validateToolcraftAcceptanceCoverage(
 
     if (!schemaHasOutputBackgroundToggleControl(controls)) {
       errors.push(
-        'Product apps with Export PNG must expose export.includeBackground inside the required "Background" section as a Switch labeled "Include". PNG export must pass that runtime value to createToolcraftPngExportCanvas includeBackground; video export keeps the background.',
+        'Product apps with Export PNG must expose export.includeBackground inside the required "Background" section as a Switch labeled "Include". PNG export must pass that runtime value to createToolcraftPngExportCanvas includeBackground; live preview must use shouldIncludeToolcraftPreviewBackground(state); video export keeps the background.',
       );
     }
 
@@ -2798,6 +3045,10 @@ export function validateToolcraftAcceptanceCoverage(
       );
     }
 
+    if (control.type === "fileDrop") {
+      errors.push(...getFileDropLifecycleCoverageErrors(label, entry));
+    }
+
     if (
       isCustomControl &&
       !hasCustomControlCoverage(
@@ -2811,7 +3062,7 @@ export function validateToolcraftAcceptanceCoverage(
     }
 
     if (isCustomControl) {
-      errors.push(...getBuiltInFitCheckErrors(label, entry));
+      errors.push(...getBuiltInFitCheckErrors(label, entry, control));
     }
 
     if (
@@ -2841,17 +3092,23 @@ export function validateToolcraftAcceptanceCoverage(
       isOutputBackgroundToggleControl({ control, controlId, sectionTitle })
     ) {
       const evidenceText = getAcceptanceEvidenceText(entry);
-
-      if (
-        !/\b(png|image)\b/i.test(evidenceText) ||
-        !/\b(transparent|transparency|alpha)\b/i.test(evidenceText) ||
-        !/\b(preview|canvas|workspace|backing|video)\b/i.test(evidenceText) ||
-        !/\b(keep|keeps|preserve|preserves|stay|stays|remain|remains|still|not transparent|non-transparent)\b/i.test(
+      const provesPngTransparency =
+        /\b(png|image)\b/i.test(evidenceText) &&
+        /\b(transparent|transparency|alpha)\b/i.test(evidenceText);
+      const provesPreviewTransparency =
+        /\b(preview|canvas)\b/i.test(evidenceText) &&
+        /\b(transparent|transparency|alpha|hide|hides|hidden|without background|no background|background off)\b/i.test(
           evidenceText,
-        )
-      ) {
+        );
+      const provesVideoBackground =
+        /\bvideo\b/i.test(evidenceText) &&
+        /\b(keep|keeps|preserve|preserves|stay|stays|remain|remains|still|background)\b/i.test(
+          evidenceText,
+        );
+
+      if (!provesPngTransparency || !provesPreviewTransparency || !provesVideoBackground) {
         errors.push(
-          `${label} controls PNG background inclusion and acceptance must prove disabling it makes PNG output transparent while live preview, workspace canvas backing, and video output keep the product background.`,
+          `${label} controls background inclusion and acceptance must prove disabling it makes PNG output transparent, hides the live preview product background, and keeps video output with the product background.`,
         );
       }
     }

package/templates/starter/src/app/starter-performance.test.ts

@@ -138,6 +138,18 @@ function projectDocsIncludeRendererLayerInventory(): boolean {
   );
 }
 
+function projectDocsIncludeRendererPipelineInventory(): boolean {
+  const decisionSources = readProjectDecisionSources();
+
+  return (
+    /Render Pipeline Inventory|rendererPipeline|render pipeline/i.test(decisionSources) &&
+    /pass|passes|cacheKey|cache key|invalidat/i.test(decisionSources) &&
+    /control-drag|viewport-zoom|viewport-drag|media-import|animation-frame|timeline-playback|interaction/i.test(
+      decisionSources,
+    )
+  );
+}
+
 function projectDocsExplainRendererAlternatives(): boolean {
   const decisionSources = readProjectDecisionSources();
 
@@ -198,12 +210,24 @@ function projectDocsIncludeFixedBackgroundDecision(): boolean {
 
 function sourceUsesCpuPixelLoop(): boolean {
   const appSources = stripJsComments(readFiles(srcDir, /\.(ts|tsx)$/));
+  const cpuPixelMethodCallPattern =
+    /(?:\.(?:createImageData|getImageData|putImageData)|\[\s*["'](?:createImageData|getImageData|putImageData)["']\s*\])\s*\(/;
 
   return (
     /new\s+ImageData\s*\(/.test(appSources) ||
-    /\.createImageData\s*\(/.test(appSources) ||
-    /\.getImageData\s*\(/.test(appSources) ||
-    /\.putImageData\s*\(/.test(appSources)
+    cpuPixelMethodCallPattern.test(appSources)
+  );
+}
+
+function appPerformanceHasRenderPipelinePass(kind: string): boolean {
+  return (starterPerformance.rendererPipeline?.passes ?? []).some(
+    (pass) => pass.kind === kind,
+  );
+}
+
+function appPerformanceHasInteractionInvalidation(interaction: string): boolean {
+  return (starterPerformance.rendererPipeline?.interactionInvalidation ?? []).some(
+    (entry) => entry.interaction === interaction,
   );
 }
 
@@ -299,7 +323,7 @@ describe("Toolcraft template app performance coverage", () => {
     expect(packageJson.scripts?.["verify:ui"]).toBe("pnpm test:browser");
     expect(packageJson.scripts?.["verify:perf"]).toBe("pnpm test:browser:perf");
     expect(packageJson.scripts?.["verify:final"]).toBe(
-      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser && pnpm test:browser:perf",
+      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
     );
   });
 
@@ -345,6 +369,17 @@ describe("Toolcraft template app performance coverage", () => {
     ).toBe(true);
   });
 
+  it("requires custom renderer apps to document the render pipeline inventory", () => {
+    if (!starterPerformance.usesCustomRenderer) {
+      return;
+    }
+
+    expect(
+      projectDocsIncludeRendererPipelineInventory(),
+      "Custom renderer apps must write a Render Pipeline Inventory in their app spec/plan docs before implementation so expensive passes, cache keys, and invalidation rules are deliberate.",
+    ).toBe(true);
+  });
+
   it("requires custom renderer apps to mirror the renderer decision in typed performance config", () => {
     if (!starterPerformance.usesCustomRenderer) {
       return;
@@ -356,6 +391,17 @@ describe("Toolcraft template app performance coverage", () => {
     ).toBeDefined();
   });
 
+  it("requires custom renderer apps to mirror the render pipeline in typed performance config", () => {
+    if (!starterPerformance.usesCustomRenderer) {
+      return;
+    }
+
+    expect(
+      starterPerformance.rendererPipeline,
+      "Custom renderer apps must declare rendererPipeline in app-performance.ts; prose specs and plans are not enough.",
+    ).toBeDefined();
+  });
+
   it("requires custom renderer apps to mirror layer inventory in typed performance config", () => {
     if (!starterPerformance.usesCustomRenderer) {
       return;
@@ -453,7 +499,7 @@ describe("Toolcraft template app performance coverage", () => {
     );
   });
 
-  it("requires pixel-output renderers to use WebGL or WebGPU", () => {
+  it("requires pixel-output renderers to use GPU or measured CPU evidence", () => {
     expect(
       validateToolcraftPerformanceCoverage(starterSchema, {
         rendererStrategy: "canvas-2d",
@@ -464,7 +510,7 @@ describe("Toolcraft template app performance coverage", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        'rendererWorkload "pixel-output" must use rendererStrategy "webgl" or "webgpu", received "canvas-2d".',
+        'rendererWorkload "pixel-output" should use rendererStrategy "webgl" or "webgpu", received "canvas-2d". Keeping a CPU renderer requires measured WebGL/WebGPU evidence in rendererTechnique.whyNotAlternativeStrategies or performanceRisks.',
       ]),
     );
   });
@@ -681,6 +727,21 @@ describe("Toolcraft template app performance coverage", () => {
       sourceUsesGpuRenderer(),
       "Procedural pixel renderers must contain an actual WebGL/WebGPU code path, not only declare a GPU strategy.",
     ).toBe(true);
+    expect(
+      appPerformanceHasRenderPipelinePass("pixel-transform"),
+      "Procedural pixel renderers must declare a rendererPipeline pixel-transform pass so caching and invalidation are machine-checkable.",
+    ).toBe(true);
+  });
+
+  it("requires custom renderers to declare high-frequency viewport invalidation", () => {
+    if (!starterPerformance.usesCustomRenderer) {
+      return;
+    }
+
+    expect(
+      appPerformanceHasInteractionInvalidation("viewport-zoom"),
+      "Custom renderer apps must declare rendererPipeline interactionInvalidation for viewport-zoom so zoom can stay responsive without recomputing expensive passes.",
+    ).toBe(true);
   });
 
   it("requires WebGL/WebGPU renderers to keep their pipeline lifecycle outside React render", () => {

package/templates/ui/components/controls/actions/actions-control.tsx

@@ -14,7 +14,6 @@ import {
 
 import { Button, Field } from "../../primitives";
 import { ControlFieldLabel } from "../../control-layout";
-import { cn } from "../../../lib/utils";
 
 export type ActionControlIconName =
   | "check"
@@ -102,6 +101,7 @@ export function ActionsControl({
     <Field
       aria-label={showLabel ? undefined : name}
       className="h-fit min-w-0 flex-wrap items-center justify-between gap-y-2!"
+      data-slot="actions-control"
       orientation="horizontal"
     >
       {showLabel ? (
@@ -110,10 +110,8 @@ export function ActionsControl({
         </ControlFieldLabel>
       ) : null}
       <div
-        className={cn(
-          "flex max-w-full shrink-0 flex-wrap items-center justify-start gap-1.5",
-          showLabel && "ml-auto",
-        )}
+        className="flex max-w-full shrink-0 flex-wrap items-center justify-start gap-1.5"
+        data-slot="actions-control-buttons"
       >
         {actions.map((action) => {
           const actionContent = getActionContent(action);

package/templates/ui/components/controls/collection-actions/collection-actions-control.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { MinusIcon, PlusIcon } from "@phosphor-icons/react";
+import type * as React from "react";
+
+import { ControlFieldLabel } from "../../control-layout";
+import { Button, Field } from "../../primitives";
+
+export type CollectionActionsControlProps = {
+  addLabel?: string;
+  canAdd?: boolean;
+  canRemove?: boolean;
+  name: string;
+  onAdd?: () => void;
+  onRemove?: () => void;
+  removeLabel?: string;
+};
+
+export function CollectionActionsControl({
+  addLabel = "Add item",
+  canAdd = true,
+  canRemove = true,
+  name,
+  onAdd,
+  onRemove,
+  removeLabel = "Remove item",
+}: CollectionActionsControlProps): React.JSX.Element {
+  return (
+    <Field
+      aria-label={name}
+      className="min-w-0 items-center justify-between gap-2"
+      data-slot="collection-actions-control-header"
+      orientation="horizontal"
+    >
+      <ControlFieldLabel className="flex-1">{name}</ControlFieldLabel>
+      <div className="inline-flex shrink-0 items-center gap-1">
+        <Button
+          aria-label={removeLabel}
+          disabled={!canRemove}
+          onClick={onRemove}
+          size="icon-sm"
+          type="button"
+          variant="outline"
+        >
+          <MinusIcon />
+        </Button>
+        <Button
+          aria-label={addLabel}
+          disabled={!canAdd}
+          onClick={onAdd}
+          size="icon-sm"
+          type="button"
+          variant="outline"
+        >
+          <PlusIcon />
+        </Button>
+      </div>
+    </Field>
+  );
+}

package/templates/ui/components/controls/collection-actions/index.ts

@@ -0,0 +1,4 @@
+"use client";
+
+export { CollectionActionsControl } from "./collection-actions-control";
+export type { CollectionActionsControlProps } from "./collection-actions-control";