@pixel-point/toolcraft 0.0.8 → 0.0.11

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,36 @@ function sourceUsesDirectStorageApi(): boolean {
 }
 
 describe("Toolcraft template app performance coverage", () => {
-  it("publishes a sequential browser performance gate", () => {
+  it("publishes a sequential Playwright browser performance fallback", () => {
     const packageJson = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")) as {
       scripts?: Record<string, string>;
     };
 
     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',
     );
     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("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 +530,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 +730,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 +849,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 +859,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 +1289,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 +1443,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/control-layout/index.tsx

@@ -90,7 +90,7 @@ export function ControlInlineGroup({
       {...props}
       className={cn(
         "grid min-w-0",
-        kind === "slider" ? "gap-4" : "gap-2",
+        kind === "slider" ? "gap-4" : "gap-x-2.5 gap-y-2",
         kind === "toggleParameter" && "items-end",
         className,
       )}
@@ -229,10 +229,13 @@ export function ControlItem({
 }: {
   allowCompoundDividers?: boolean;
   children: React.ReactNode;
-  compoundDividerPlacement?: "both" | "bottom";
+  compoundDividerPlacement?: "both" | "bottom" | "top";
   flush?: boolean;
 }): React.JSX.Element {
-  const showCompoundTopDivider = compoundDividerPlacement === "both";
+  const showCompoundTopDivider =
+    compoundDividerPlacement === "both" || compoundDividerPlacement === "top";
+  const showCompoundBottomDivider =
+    compoundDividerPlacement === "both" || compoundDividerPlacement === "bottom";
 
   return (
     <div
@@ -240,11 +243,13 @@ export function ControlItem({
         "min-w-0",
         !flush && "px-3",
         allowCompoundDividers &&
+          showCompoundBottomDivider &&
           "has-data-[control-section-divider=compound]:relative has-data-[control-section-divider=compound]:pb-[18px] has-data-[control-section-divider=compound]:after:absolute has-data-[control-section-divider=compound]:after:bottom-0 has-data-[control-section-divider=compound]:after:h-px has-data-[control-section-divider=compound]:after:bg-[color:color-mix(in_oklab,var(--border)_8%,transparent)]",
         allowCompoundDividers &&
           showCompoundTopDivider &&
           "has-data-[control-section-divider=compound]:pt-[18px] has-data-[control-section-divider=compound]:before:absolute has-data-[control-section-divider=compound]:before:top-0 has-data-[control-section-divider=compound]:before:h-px has-data-[control-section-divider=compound]:before:bg-[color:color-mix(in_oklab,var(--border)_8%,transparent)]",
         allowCompoundDividers &&
+          showCompoundBottomDivider &&
           (flush
             ? "has-data-[control-section-divider=compound]:after:inset-x-0"
             : "has-data-[control-section-divider=compound]:after:inset-x-3"),

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

@@ -2,18 +2,23 @@
 
 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";
 import { ControlFieldLabel } from "../../control-layout";
+import { cn } from "../../../lib/utils";
 
 export type ActionControlIconName =
   | "check"
@@ -22,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 = {
@@ -33,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;
@@ -51,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;
@@ -77,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;
   }
@@ -86,23 +110,41 @@ 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
       aria-label={showLabel ? undefined : name}
-      className="h-fit min-w-0 flex-wrap items-center justify-between gap-y-2!"
+      className="h-fit min-w-0 gap-2"
       data-slot="actions-control"
-      orientation="horizontal"
+      orientation="vertical"
     >
       {showLabel ? (
         <ControlFieldLabel className="min-w-0" textClassName="min-w-0 truncate">
@@ -110,24 +152,33 @@ export function ActionsControl({
         </ControlFieldLabel>
       ) : null}
       <div
-        className="flex max-w-full shrink-0 flex-wrap items-center justify-start gap-1.5"
+        className={cn(
+          "grid max-w-full gap-1.5",
+          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"
               size="sm"
               type="button"
               variant="outline"
             >
               {getActionIcon(action)}
-              {actionContent}
+              {showActionLabels ? actionContent : null}
             </Button>
           );
         })}

package/templates/ui/components/controls/code-textarea/code-textarea-control.tsx

@@ -14,12 +14,14 @@ export type CodeTextareaControlProps = {
   defaultValue?: string;
   name: string;
   onValueChange?: ControlValueChangeHandler<string>;
+  showLabel?: boolean;
   value: string;
 };
 
 export function CodeTextareaControl({
   name,
   onValueChange,
+  showLabel = true,
   value,
 }: CodeTextareaControlProps): React.JSX.Element {
   const [currentValue, setCurrentValue] = React.useState(value);
@@ -61,9 +63,11 @@ export function CodeTextareaControl({
 
   return (
     <Field className="min-w-0 gap-2">
-      <div className="flex items-center">
-        <ControlFieldLabel>{name}</ControlFieldLabel>
-      </div>
+      {showLabel ? (
+        <div className="flex items-center">
+          <ControlFieldLabel>{name}</ControlFieldLabel>
+        </div>
+      ) : null}
       <Textarea
         aria-label={name}
         className="max-h-[calc(12lh+12px)] min-h-[84px] overflow-y-auto font-mono"

package/templates/ui/components/controls/color/index.ts

@@ -18,7 +18,10 @@ export {
   type ColorFormatMode,
   type ColorSurfaceModel,
 } from "./style-guide-color-picker-channel-utils";
-export { DEFAULT_COLOR_FORMAT_MODE } from "./style-guide-color-picker";
+export {
+  DEFAULT_COLOR_FORMAT_MODE,
+  StyleGuideColorPicker,
+} from "./style-guide-color-picker";
 export {
   getColorSurfaceSliderConfig,
   getColorSurfaceStyle,