@pixel-point/toolcraft 0.0.9 → 0.0.12

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

@@ -295,6 +295,15 @@ function browserTestsAssertNativePreviewResolution(): boolean {
   );
 }
 
+function browserPerfContractRequiresRenderScaleBackingPixels(): boolean {
+  const browserTestSources = readBrowserTestSources();
+
+  return (
+    /scenarioUsesRenderScaleFixture/.test(browserTestSources) &&
+    /expectToolcraftCanvasBackingPixelsForRenderScale/.test(browserTestSources)
+  );
+}
+
 function sourceUsesAnimationFrameWithoutCleanup(): boolean {
   const appSources = stripJsComments(readFiles(srcDir, /\.(ts|tsx)$/));
 
@@ -308,25 +317,54 @@ function sourceUsesDirectStorageApi(): boolean {
 }
 
 describe("Toolcraft template app performance coverage", () => {
-  it("publishes a sequential browser performance gate", () => {
+  it("publishes separate browser acceptance and performance fallback gates", () => {
     const packageJson = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")) as {
       scripts?: Record<string, string>;
     };
 
+    expect(
+      packageJson.scripts?.["test:browser"],
+      "Generated apps must keep full performance scenarios out of the default browser acceptance gate.",
+    ).toBe('playwright install chromium && playwright test --grep-invert "browser perf:"');
     expect(
       packageJson.scripts?.["test:browser:perf"],
-      "Generated apps must expose a sequential browser performance gate so perf budgets are measured without parallel e2e noise.",
+      "Generated apps must expose a sequential Playwright fallback so perf budgets can be measured when no agent browser is available.",
     ).toBe(
-      'playwright install chromium && playwright test e2e/app-performance.spec.ts --workers=1 && playwright test --grep "browser perf:" --workers=1 --pass-with-no-tests',
+      'playwright install chromium && playwright test --grep "browser perf:" --workers=1 --pass-with-no-tests',
     );
     expect(packageJson.scripts?.["verify:quick"]).toBe("pnpm ai:check && pnpm test");
     expect(packageJson.scripts?.["verify:ui"]).toBe("pnpm test:browser");
     expect(packageJson.scripts?.["verify:perf"]).toBe("pnpm test:browser:perf");
+    expect(packageJson.scripts?.["verify:perf:playwright"]).toBe(
+      "pnpm test:browser:perf",
+    );
     expect(packageJson.scripts?.["verify:final"]).toBe(
       "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
     );
   });
 
+  it("keeps the Playwright performance audit inside the browser perf tag", () => {
+    const source = readFileSync(join(e2eDir, "app-performance.spec.ts"), "utf8");
+    const testNames = [...source.matchAll(/test\(\s*(["'`])([^"'`]+)\1/g)].map(
+      (match) => match[2],
+    );
+
+    expect(source).not.toContain("TOOLCRAFT_PERF_CHECK");
+    expect(testNames.length).toBeGreaterThan(0);
+    expect(
+      testNames.every((name) => name.includes("browser perf:")),
+      `app-performance.spec.ts tests must all be tagged for the dedicated perf checkpoint: ${testNames.join(", ")}`,
+    ).toBe(true);
+  });
+
+  it("declares agent browser as the preferred performance runner", () => {
+    expect(starterPerformance.browserCheckPolicy).toEqual({
+      fallbackRunner: "playwright",
+      fallbackWhen: ["agent-browser-unavailable", "ci"],
+      preferredRunner: "agent-browser",
+    });
+  });
+
   it("requires valid performance coverage for declared workload scenarios", () => {
     expect(validateToolcraftPerformanceCoverage(starterSchema, starterPerformance)).toEqual([]);
   });
@@ -510,7 +548,7 @@ describe("Toolcraft template app performance coverage", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        '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.',
+        'rendererWorkload "pixel-output" should use rendererStrategy "webgl" or "webgpu", received "canvas-2d". Keeping a CPU renderer requires rendererTechnique.measuredAlternativeEvidence for WebGL/WebGPU stress comparison.',
       ]),
     );
   });
@@ -710,6 +748,13 @@ describe("Toolcraft template app performance coverage", () => {
     ).toBe(true);
   });
 
+  it("requires render scale scenarios to prove backing canvas pixels in browser performance tests", () => {
+    expect(
+      browserPerfContractRequiresRenderScaleBackingPixels(),
+      "Browser performance contract must require renderScale scenarios to assert backing canvas pixels, not only state or labels.",
+    ).toBe(true);
+  });
+
   it("requires procedural pixel-loop renderers to use a GPU strategy", () => {
     if (!sourceUsesCpuPixelLoop()) {
       return;
@@ -822,7 +867,7 @@ describe("Toolcraft template app performance coverage", () => {
     }
   });
 
-  it("requires each browser performance scenario to point at a Playwright test", () => {
+  it("requires each browser performance scenario to point at a fallback Playwright test", () => {
     const browserTestSources = readBrowserTestSources();
 
     for (const scenario of starterPerformance.scenarios) {
@@ -832,7 +877,7 @@ describe("Toolcraft template app performance coverage", () => {
 
       expect(
         browserTestSources,
-        `${scenario.id} must be backed by a Playwright test named "${scenario.browserTestName}".`,
+        `${scenario.id} must be backed by a fallback Playwright test named "${scenario.browserTestName}".`,
       ).toContain(scenario.browserTestName);
     }
   });
@@ -1262,8 +1307,6 @@ describe("Toolcraft template app performance coverage", () => {
       }),
     ).toEqual(
       expect.arrayContaining([
-        "canvas.size.width must have a performance scenario because every visible control can affect app responsiveness.",
-        "canvas.size.height must have a performance scenario because every visible control can affect app responsiveness.",
         "shader.gradient must have a performance scenario because every visible control can affect app responsiveness.",
         "shader.mode must have a performance scenario because every visible control can affect app responsiveness.",
       ]),
@@ -1418,6 +1461,85 @@ describe("Toolcraft template app performance coverage", () => {
     );
   });
 
+  it("does not let load-profile smooth targets bypass required interaction budgets", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                density: {
+                  defaultValue: 4,
+                  label: "Density",
+                  max: 12,
+                  min: 1,
+                  performanceReason: "Density changes rendered output size.",
+                  performanceRole: "workload",
+                  target: "render.density",
+                  type: "slider",
+                },
+              },
+              title: "Render",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(
+      validateToolcraftPerformanceCoverage(schema, {
+        rendererStrategy: "none",
+        rendererWorkload: "none",
+        scenarios: [
+          {
+            automated: true,
+            automatedTestName: "perf: density drag stays responsive",
+            browser: true,
+            browserTestName: "browser perf: density drag stays responsive",
+            budget: { maxFrameGapMs: 80 },
+            controlLabel: "Density",
+            expectedObservable: "Dragging Density updates product output without blocking the UI.",
+            fixture: "density smooth target fixture",
+            id: "density-drag",
+            interaction: "control-drag",
+            stressFixture: {
+              kind: "max-value",
+              loadProfile: {
+                degradationStepPercent: 10,
+                evidence: [
+                  {
+                    attemptedTarget: 12,
+                    decision: "Keep 12 as experimental and guarantee smoothness through 11.",
+                    measuredResult: "At density 12, maxFrameGapMs 148 exceeded the 80ms budget.",
+                    optimizationAttempted:
+                      "Cached expensive render inputs and coalesced preview work to requestAnimationFrame.",
+                    result: "failed",
+                    scenarioId: "density-drag",
+                  },
+                ],
+                hardLimit: 12,
+                metric: "numeric-max",
+                smoothTarget: 11,
+                smoothTargetRatio: 0.9,
+                target: "render.density",
+                userFacingRange: "experimental-above-smooth",
+              },
+              reason: "Density 11 is the measured smooth target after hard-limit testing.",
+              value: 11,
+            },
+            target: "render.density",
+            values: { default: 4, max: 12, min: 1 },
+            workload: true,
+          },
+        ],
+        usesCustomRenderer: false,
+        workloadTargets: ["render.density"],
+      }),
+    ).toContain("density-drag control-drag scenario must declare maxInteractionMs.");
+  });
+
   it("requires real browser interaction metadata for control performance scenarios", () => {
     expect(
       validateToolcraftPerformanceCoverage(starterSchema, {

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

@@ -4,6 +4,11 @@ import {
 } from "@repo/toolcraft-runtime";
 
 export const starterPerformance: ToolcraftPerformanceConfig = defineToolcraftPerformance({
+  browserCheckPolicy: {
+    fallbackRunner: "playwright",
+    fallbackWhen: ["agent-browser-unavailable", "ci"],
+    preferredRunner: "agent-browser",
+  },
   rendererStrategy: "none",
   rendererWorkload: "none",
   scenarios: [],

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

@@ -7,9 +7,25 @@ describe("starterSchema", () => {
   it("publishes the base Toolcraft template app contract for AI assembly", () => {
     expect(starterSchema.canvas.draggable).toBe(true);
     expect(starterSchema.canvas.enabled).toBe(true);
-    expect(starterSchema.canvas.sizing).toEqual({ mode: "intrinsic-media" });
+    expect(starterSchema.canvas.sizing).toEqual({ mode: "editable-output" });
     expect(starterSchema.canvas.upload).toBe(true);
-    expect(starterSchema.panels.controls).toBeUndefined();
+    expect(starterSchema.panels.controls?.sections[0]?.title).toBe("Setup");
+    expect(starterSchema.panels.controls?.sections[0]?.controls.settingsTransfer).toMatchObject({
+      target: "runtime.settingsTransfer",
+      type: "settingsTransfer",
+    });
+    expect(starterSchema.panels.controls?.sections[0]?.controls.canvasAspectRatio).toMatchObject({
+      target: "canvas.aspectRatio",
+      type: "aspectRatio",
+    });
+    expect(starterSchema.panels.controls?.sections[0]?.controls.canvasWidth).toMatchObject({
+      target: "canvas.size.width",
+      type: "text",
+    });
+    expect(starterSchema.panels.controls?.sections[0]?.controls.canvasHeight).toMatchObject({
+      target: "canvas.size.height",
+      type: "text",
+    });
     expect(starterSchema.panels.layers).toBeUndefined();
     expect(starterSchema.panels.timeline).toBeUndefined();
     expect(starterSchema.toolbar).toEqual({
@@ -20,38 +36,47 @@ describe("starterSchema", () => {
     });
     expect(starterSchema.assembly.components).toEqual([
       "canvas",
+      "controlsPanel",
       "toolbar",
     ]);
     expect(starterSchema.assembly.capabilities).toEqual(
       expect.arrayContaining([
         "canvas.draggable",
+        "canvas.editableSize",
         "canvas.upload",
+        "controls.defaults",
+        "controls.panel",
         "toolbar.history",
         "toolbar.radar",
         "toolbar.theme",
         "toolbar.zoom",
       ]),
     );
-    expect(starterSchema.assembly.capabilities).not.toContain("controls.defaults");
     expect(starterSchema.assembly.capabilities).not.toContain("timeline.playback");
     expect(starterSchema.assembly.capabilities).not.toContain("timeline.keyframes");
     expect(starterSchema.assembly.commands).toEqual(
       expect.arrayContaining([
         "canvas.center",
+        "canvas.setSize",
         "canvas.setViewport",
         "canvas.zoomIn",
+        "controls.reset",
+        "controls.setValue",
         "history.undo",
         "media.delete",
         "media.import",
       ]),
     );
-    expect(starterSchema.assembly.commands).not.toContain("controls.reset");
-    expect(starterSchema.assembly.commands).not.toContain("controls.setValue");
     expect(starterSchema.assembly.commands).not.toContain("timeline.setCurrentTime");
   });
 
-  it("starts without product-specific panels or controls", () => {
-    expect(starterSchema.panels.controls).toBeUndefined();
+  it("starts with runtime setup but without product-specific panels or controls", () => {
+    const productSections =
+      starterSchema.panels.controls?.sections.filter((section) => section.title !== "Setup") ??
+      [];
+
+    expect(starterSchema.panels.controls?.sections[0]?.title).toBe("Setup");
+    expect(productSections).toEqual([]);
     expect(starterSchema.panels.layers).toBeUndefined();
     expect(starterSchema.panels.timeline).toBeUndefined();
   });

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

@@ -3,10 +3,14 @@ import { defineToolcraft } from "@repo/toolcraft-runtime";
 export const starterSchema = defineToolcraft({
   canvas: {
     enabled: true,
-    sizing: { mode: "intrinsic-media" },
     upload: true,
   },
-  panels: {},
+  panels: {
+    controls: {
+      sections: [],
+      title: "Controls",
+    },
+  },
   toolbar: {
     history: true,
     radar: true,

package/templates/starter/vite.config.ts

@@ -1,10 +1,66 @@
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
+import fs from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { defineConfig } from "vite";
+import { defineConfig, type Plugin } from "vite";
+
+const rootDir = fileURLToPath(new URL(".", import.meta.url));
+const toolcraftServerIdentityPath = "/.toolcraft/server-identity.json";
+
+function readHtmlAppTitle(source: string): string | null {
+  const appTitleMeta = source
+    .match(/<meta\b[^>]*>/gi)
+    ?.find((tag) => tag.match(/\bname\s*=\s*["']toolcraft-app-title["']/i));
+
+  return appTitleMeta?.match(/\bcontent\s*=\s*["']([^"']*)["']/i)?.[1] ?? null;
+}
+
+async function createToolcraftServerIdentity() {
+  const indexSource = await fs.readFile(path.join(rootDir, "index.html"), "utf8");
+
+  return {
+    appTitle: readHtmlAppTitle(indexSource),
+    root: await fs.realpath(rootDir),
+  };
+}
+
+function toolcraftServerIdentityPlugin(): Plugin {
+  function handleIdentityRequest(
+    request: IncomingMessage,
+    response: ServerResponse,
+    next: (error?: unknown) => void,
+  ) {
+    const requestUrl = new URL(request.url ?? "/", "http://localhost");
+
+    if (requestUrl.pathname !== toolcraftServerIdentityPath) {
+      next();
+      return;
+    }
+
+    createToolcraftServerIdentity()
+      .then((identity) => {
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.setHeader("cache-control", "no-store");
+        response.end(JSON.stringify(identity));
+      })
+      .catch(next);
+  }
+
+  return {
+    name: "toolcraft-server-identity",
+    configurePreviewServer(server) {
+      server.middlewares.use(handleIdentityRequest);
+    },
+    configureServer(server) {
+      server.middlewares.use(handleIdentityRequest);
+    },
+  };
+}
 
 export default defineConfig({
-  plugins: [tailwindcss(), react()],
+  plugins: [toolcraftServerIdentityPlugin(), tailwindcss(), react()],
   resolve: {
     alias: {
       "@": fileURLToPath(new URL("./src", import.meta.url)),

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

@@ -2,14 +2,18 @@
 
 import type { ReactElement, ReactNode } from "react";
 import {
+  ArrowClockwiseIcon,
   ArrowCounterClockwiseIcon,
   CheckIcon,
   CopySimpleIcon,
   DownloadSimpleIcon,
   EraserIcon,
   ExportIcon,
+  FlipHorizontalIcon,
+  FlipVerticalIcon,
   MagicWandIcon,
   ShuffleIcon,
+  UploadSimpleIcon,
 } from "@phosphor-icons/react";
 
 import { Button, Field } from "../../primitives";
@@ -23,8 +27,12 @@ export type ActionControlIconName =
   | "download-simple"
   | "eraser"
   | "export"
+  | "flip-horizontal"
+  | "flip-vertical"
+  | "rotate-cw"
   | "rotate-ccw"
   | "shuffle"
+  | "upload-simple"
   | "wand-sparkles";
 
 const actionIconComponents = {
@@ -34,12 +42,17 @@ const actionIconComponents = {
   "download-simple": DownloadSimpleIcon,
   eraser: EraserIcon,
   export: ExportIcon,
+  "flip-horizontal": FlipHorizontalIcon,
+  "flip-vertical": FlipVerticalIcon,
+  "rotate-cw": ArrowClockwiseIcon,
   "rotate-ccw": ArrowCounterClockwiseIcon,
   shuffle: ShuffleIcon,
+  "upload-simple": UploadSimpleIcon,
   "wand-sparkles": MagicWandIcon,
 } as const;
 
 export type ActionControlObjectOption = {
+  ariaLabel?: string;
   children?: ReactNode;
   label?: string;
   value: string;
@@ -52,6 +65,12 @@ function getActionValue(action: ActionControlOption): string {
   return typeof action === "string" ? action : action.value;
 }
 
+function getActionLabel(action: ActionControlOption): string {
+  return typeof action === "string"
+    ? action
+    : (action.ariaLabel ?? action.label ?? action.value);
+}
+
 function getActionContent(action: ActionControlOption): ReactNode {
   if (typeof action === "string") {
     return action;
@@ -78,6 +97,10 @@ function getActionAriaLabel(
   action: ActionControlOption,
   content: ReactNode,
 ): string | undefined {
+  if (typeof action !== "string" && action.ariaLabel) {
+    return action.ariaLabel;
+  }
+
   if (typeof content === "string") {
     return undefined;
   }
@@ -87,18 +110,34 @@ function getActionAriaLabel(
 
 export type ActionsControlProps = {
   actions: readonly ActionControlOption[];
+  buttonColumns?: 1 | 2 | 3 | 4;
   name: string;
   onAction?: (value: string) => void;
+  showActionLabels?: boolean;
   showLabel?: boolean;
 };
 
 export function ActionsControl({
   actions,
+  buttonColumns,
   name,
   onAction,
+  showActionLabels = true,
   showLabel = true,
 }: ActionsControlProps): React.JSX.Element {
   const hasSingleAction = actions.length === 1;
+  const columnClass =
+    buttonColumns === 4
+      ? "w-full grid-cols-4"
+      : buttonColumns === 3
+        ? "w-full grid-cols-3"
+      : buttonColumns === 2
+        ? "w-full grid-cols-2"
+        : buttonColumns === 1
+          ? "w-full grid-cols-1"
+          : hasSingleAction
+            ? "w-1/2 grid-cols-1"
+            : "w-full grid-cols-2";
 
   return (
     <Field
@@ -115,18 +154,22 @@ export function ActionsControl({
       <div
         className={cn(
           "grid max-w-full gap-1.5",
-          hasSingleAction ? "w-1/2 grid-cols-1" : "w-full grid-cols-2",
+          columnClass,
         )}
         data-actions-count={actions.length}
+        data-actions-columns={buttonColumns ?? (hasSingleAction ? 1 : 2)}
         data-slot="actions-control-buttons"
       >
         {actions.map((action) => {
           const actionContent = getActionContent(action);
+          const actionLabel = getActionLabel(action);
           const actionValue = getActionValue(action);
 
           return (
             <Button
-              aria-label={getActionAriaLabel(action, actionContent)}
+              aria-label={
+                showActionLabels ? getActionAriaLabel(action, actionContent) : actionLabel
+              }
               key={actionValue}
               onClick={() => onAction?.(actionValue)}
               className="w-full"
@@ -135,7 +178,7 @@ export function ActionsControl({
               variant="outline"
             >
               {getActionIcon(action)}
-              {actionContent}
+              {showActionLabels ? actionContent : null}
             </Button>
           );
         })}

package/templates/ui/components/controls/color/palette-control.tsx

@@ -3,6 +3,10 @@
 import * as React from "react";
 
 import { cn } from "../../../lib/utils";
+import {
+  createControlHistoryGroupId,
+  type ControlChangeMeta,
+} from "../control-types";
 import {
   PALETTE_SHADE_STEPS,
   STYLE_GUIDE_PRIMARY_FAMILY_OPTIONS,
@@ -21,7 +25,7 @@ export {
 };
 export type { PaletteColorFamily, PaletteControlValue, PaletteShadeStep };
 
-export type PaletteControlChangeMeta = {
+export type PaletteControlChangeMeta = ControlChangeMeta & {
   stage: "live" | "commit";
   hex: string;
 };
@@ -91,6 +95,7 @@ export function PaletteControl({
   const pendingPersistRef = React.useRef<PaletteControlValue | null>(null);
   const clickCommitTimeoutRef = React.useRef<number | null>(null);
   const persistTimeoutRef = React.useRef<number | null>(null);
+  const liveHistoryGroupRef = React.useRef<string | null>(null);
   const isInteractingRef = React.useRef(false);
   const shadeTrackRef = React.useRef<HTMLDivElement | null>(null);
   const onValueChangeRef = React.useRef(onValueChange);
@@ -148,12 +153,34 @@ export function PaletteControl({
     persistTimeoutRef.current = null;
   }, []);
 
+  const getLiveHistoryMeta = React.useCallback((): ControlChangeMeta => {
+    liveHistoryGroupRef.current ??= createControlHistoryGroupId("palette");
+
+    return {
+      history: "merge",
+      historyGroup: liveHistoryGroupRef.current,
+    };
+  }, []);
+
+  const finishLiveHistoryGroup = React.useCallback(() => {
+    liveHistoryGroupRef.current = null;
+  }, []);
+
   const emitChange = React.useCallback(
     (nextValue: PaletteControlValue, stage: PaletteControlChangeMeta["stage"]) => {
       const hex = getPaletteHex(nextValue);
-      onValueChangeRef.current?.(nextValue, { stage, hex });
+      const historyMeta =
+        stage === "live" || liveHistoryGroupRef.current
+          ? getLiveHistoryMeta()
+          : undefined;
+
+      onValueChangeRef.current?.(nextValue, {
+        ...historyMeta,
+        stage,
+        hex,
+      });
     },
-    [],
+    [getLiveHistoryMeta],
   );
 
   const syncOptimisticValue = React.useCallback((nextValue: PaletteControlValue) => {
@@ -174,6 +201,7 @@ export function PaletteControl({
       if (options?.immediate) {
         pendingPersistRef.current = null;
         onCommitRef.current?.(pendingPersist, getPaletteHex(pendingPersist));
+        finishLiveHistoryGroup();
         setInteractionState(false);
         return true;
       }
@@ -184,17 +212,19 @@ export function PaletteControl({
         pendingPersistRef.current = null;
 
         if (!nextPersist) {
+          finishLiveHistoryGroup();
           setInteractionState(false);
           return;
         }
 
         onCommitRef.current?.(nextPersist, getPaletteHex(nextPersist));
+        finishLiveHistoryGroup();
         setInteractionState(false);
       }, PERSIST_SETTLE_MS);
 
       return true;
     },
-    [clearPersistTimeout, setInteractionState],
+    [clearPersistTimeout, finishLiveHistoryGroup, setInteractionState],
   );
 
   const flushPendingCommit = React.useCallback((options?: { persistImmediately?: boolean }) => {