@pixel-point/toolcraft 0.0.2

package/templates/starter/e2e/app-controls.spec.ts

@@ -0,0 +1,41 @@
+import { expect, test } from "@playwright/test";
+
+test("browser: starter opens as a neutral Toolcraft shell", async ({ page }) => {
+  await page.goto("/");
+
+  await expect(page.locator('[data-slot="toolcraft-runtime-app"]')).toBeVisible();
+  await expect(page.getByRole("application", { name: "Canvas viewport" })).toBeVisible();
+
+  await expect(page.getByText("Toolcraft App Template Controls")).toHaveCount(0);
+  await expect(page.getByText("Generation")).toHaveCount(0);
+  await expect(page.getByText("Prompt")).toHaveCount(0);
+  await expect(page.getByText("Dur:")).toHaveCount(0);
+  await expect(page.getByRole("button", { name: /Play playback|Pause playback/ })).toHaveCount(0);
+});
+
+test("browser: starter canvas accepts media upload without product controls", async ({
+  page,
+}) => {
+  await page.goto("/");
+
+  const upload = await page.evaluateHandle(() => {
+    const dataTransfer = new DataTransfer();
+    const file = new File(
+      [
+        '<svg xmlns="http://www.w3.org/2000/svg" width="128" height="96"><rect width="128" height="96" fill="#888"/></svg>',
+      ],
+      "starter-fixture.svg",
+      { type: "image/svg+xml" },
+    );
+
+    dataTransfer.items.add(file);
+    return dataTransfer;
+  });
+
+  await page
+    .getByRole("application", { name: "Canvas viewport" })
+    .dispatchEvent("drop", { dataTransfer: upload });
+
+  await expect(page.getByRole("img", { name: "starter-fixture.svg" })).toBeVisible();
+  await expect(page.getByText("Prompt")).toHaveCount(0);
+});

package/templates/starter/e2e/app-performance.spec.ts

@@ -0,0 +1,326 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { expect, test } from "@playwright/test";
+
+import { starterPerformance } from "../src/app/starter-performance";
+import { starterSchema } from "../src/app/starter-schema";
+
+const currentFileName = basename(fileURLToPath(import.meta.url));
+const e2eDir = dirname(fileURLToPath(import.meta.url));
+
+type BrowserTestSource = {
+  fileName: string;
+  source: string;
+};
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripJsComments(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+function hasRealLayerRowInteraction(source: string): boolean {
+  return /data-layer-id|data-template-layer-name|selectLayerByName\s*\(|layerRowByName\s*\(|getByRole\s*\(\s*(["'`])option\1/i.test(
+    source,
+  );
+}
+
+function hasRealLayerVisibilityInteraction(source: string): boolean {
+  return /toggleLayerVisibilityByName\s*\(|getByRole\s*\([\s\S]*?(Hide|Show|Disable|Enable).*layer|aria-label[\s\S]*?(Hide|Show|Disable|Enable)/i.test(
+    source,
+  );
+}
+
+function hasRealLayerDragInteraction(source: string): boolean {
+  return /\.dragTo\s*\(|page\.mouse\.(?:down|move|up)\s*\(|dragLayer(?:Before|After|ToGroup|ByName)?\s*\(/i.test(
+    source,
+  );
+}
+
+function readSiblingBrowserTestSources(): BrowserTestSource[] {
+  return readdirSync(e2eDir)
+    .filter((fileName) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(fileName))
+    .filter((fileName) => fileName !== currentFileName)
+    .map((fileName) => ({
+      fileName,
+      source: readFileSync(join(e2eDir, fileName), "utf8"),
+    }));
+}
+
+function findNamedBrowserTestSource(
+  sources: readonly BrowserTestSource[],
+  testName: string,
+): string | undefined {
+  const testStartPattern = new RegExp(
+    `(?:test|it)(?:\\.[\\w]+)?\\(\\s*(["'\`])${escapeRegExp(testName)}\\1`,
+  );
+  const nextTestPattern = /\n\s*(?:test|it)(?:\.[\w]+)?\(\s*["'`]/;
+
+  for (const { source } of sources) {
+    const cleanSource = stripJsComments(source);
+    const match = testStartPattern.exec(cleanSource);
+    if (!match) {
+      continue;
+    }
+
+    const startIndex = match.index;
+    const afterStart = cleanSource.slice(startIndex + 1);
+    const nextMatchIndex = afterStart.search(nextTestPattern);
+
+    return cleanSource.slice(
+      startIndex,
+      nextMatchIndex === -1 ? undefined : startIndex + 1 + nextMatchIndex,
+    );
+  }
+
+  return undefined;
+}
+
+function getDiscreteControlLabels(): Set<string> {
+  const labels = new Set<string>();
+
+  for (const section of starterSchema.panels.controls?.sections ?? []) {
+    for (const control of Object.values(section.controls)) {
+      if (
+        (control.type === "slider" || control.type === "rangeSlider") &&
+        control.variant === "discrete" &&
+        typeof control.label === "string"
+      ) {
+        labels.add(control.label);
+      }
+    }
+  }
+
+  return labels;
+}
+
+function getScenarioBudgetAssertionPattern(scenarioId: string): RegExp {
+  return new RegExp(
+    `expectToolcraftScenarioPerformanceBudget\\s*\\([\\s\\S]*?,\\s*(?:starterPerformance|appPerformance)\\s*,\\s*(["'\`])${escapeRegExp(
+      scenarioId,
+    )}\\1`,
+  );
+}
+
+function getScenarioStressFixturePattern(scenarioId: string): RegExp {
+  return new RegExp(
+    `getToolcraftPerformanceStressValue(?:\\s*<[^>]+>)?\\s*\\(\\s*(?:starterPerformance|appPerformance)\\s*,\\s*(["'\`])${escapeRegExp(
+      scenarioId,
+    )}\\1`,
+  );
+}
+
+test("browser performance matrix points at real Playwright tests", () => {
+  const browserTestSources = readSiblingBrowserTestSources();
+
+  for (const scenario of starterPerformance.scenarios) {
+    if (!scenario.browser) {
+      continue;
+    }
+
+    expect(
+      Boolean(findNamedBrowserTestSource(browserTestSources, scenario.browserTestName)),
+      `${scenario.id} must be backed by a browser performance test named "${scenario.browserTestName}".`,
+    ).toBe(true);
+  }
+});
+
+test("browser performance tests use real Toolcraft interactions", () => {
+  if (starterPerformance.scenarios.length === 0) {
+    return;
+  }
+
+  const browserTestSources = readSiblingBrowserTestSources();
+  const discreteControlLabels = getDiscreteControlLabels();
+
+  for (const scenario of starterPerformance.scenarios) {
+    const browserTestSource = findNamedBrowserTestSource(
+      browserTestSources,
+      scenario.browserTestName,
+    );
+
+    expect(
+      browserTestSource,
+      `${scenario.id} must be backed by a browser performance test named "${scenario.browserTestName}".`,
+    ).toBeDefined();
+
+    if (!browserTestSource) {
+      continue;
+    }
+
+    if (scenario.workload) {
+      expect(
+        scenario.stressFixture,
+        `${scenario.id} workload scenario must declare stressFixture so browser tests cannot use toy inputs.`,
+      ).toBeDefined();
+      expect(
+        browserTestSource,
+        `${scenario.id} must read the declared stress fixture with getToolcraftPerformanceStressValue(appPerformance, "${scenario.id}") before measuring performance.`,
+      ).toMatch(getScenarioStressFixturePattern(scenario.id));
+    }
+
+    if (scenario.interaction === "control-drag") {
+      expect(
+        browserTestSource,
+        `${scenario.id} must measure a real Toolcraft pointer drag instead of filling a hidden/numeric editor.`,
+      ).toMatch(/dragToolcraftSliderByLabel\s*\(/);
+
+      if (scenario.controlLabel) {
+        expect(
+          browserTestSource,
+          `${scenario.id} must drag the declared control label "${scenario.controlLabel}".`,
+        ).toMatch(
+          new RegExp(
+            `dragToolcraftSliderByLabel\\s*\\([\\s\\S]*?(["'\`])${escapeRegExp(
+              scenario.controlLabel,
+            )}\\1`,
+          ),
+        );
+      }
+
+      if (scenario.controlLabel && discreteControlLabels.has(scenario.controlLabel)) {
+        expect(
+          browserTestSource,
+          `${scenario.id} drags discrete slider "${scenario.controlLabel}" and must verify Toolcraft marker-budget behavior plus smooth drag.`,
+        ).toMatch(/expectToolcraftDiscreteSliderDragSmoothness\s*\(/);
+      }
+    }
+
+    if (scenario.interaction === "control-change") {
+      expect(
+        browserTestSource,
+        `${scenario.id} must change the declared control through the browser UI.`,
+      ).toMatch(/\.fill\s*\(|\.pressSequentially\s*\(|\.selectOption\s*\(|getByRole\s*\([\s\S]*?\.click\s*\(/);
+    }
+
+    if (scenario.uiSelector) {
+      expect(
+        browserTestSource,
+        `${scenario.id} must interact with the declared UI selector "${scenario.uiSelector}".`,
+      ).toContain(scenario.uiSelector);
+    }
+
+    expect(
+      browserTestSource,
+      `${scenario.id} must measure browser responsiveness with measureToolcraftInteraction.`,
+    ).toMatch(
+      /measureToolcraftInteraction\s*\(|measureToolcraftAnimationFrames\s*\(|expectToolcraftCanvasViewportStable\s*\(/,
+    );
+
+    if (scenario.interaction === "viewport-stability") {
+      expect(
+        browserTestSource,
+        `${scenario.id} must use expectToolcraftCanvasViewportStable to catch canvas zoom/offset jumps.`,
+      ).toMatch(/expectToolcraftCanvasViewportStable\s*\(/);
+
+      if (scenario.target === "timeline.keyframes") {
+        expect(
+          browserTestSource,
+          `${scenario.id} must exercise toolbar zoom or radar before checking keyframe viewport stability.`,
+        ).toMatch(/Zoom in|Zoom out|Center canvas|canvas\.zoom|canvas\.center/);
+        expect(
+          browserTestSource,
+          `${scenario.id} must open the expanded keyframe editor while checking viewport stability.`,
+        ).toMatch(/Expand timeline panel|timeline\.setExpanded|timeline-expanded/);
+        expect(
+          browserTestSource,
+          `${scenario.id} must create or update at least one keyframe while checking viewport stability.`,
+        ).toMatch(/Add .* keyframe|Disable .* keyframes|timeline-keyframe-row/);
+        expect(
+          browserTestSource,
+          `${scenario.id} must scrub or play the timeline while checking viewport stability.`,
+        ).toMatch(/Playback position|Play playback|Pause playback|timeline\.setCurrentTime/);
+      }
+
+      if (scenario.target === "layers.interactions") {
+        expect(
+          browserTestSource,
+          `${scenario.id} must exercise toolbar zoom or radar before checking layer viewport stability.`,
+        ).toMatch(/Zoom in|Zoom out|Center canvas|canvas\.zoom|canvas\.center/);
+        expect(
+          hasRealLayerRowInteraction(browserTestSource),
+          `${scenario.id} must select real LayersPanel rows while checking viewport stability.`,
+        ).toBe(true);
+        expect(
+          hasRealLayerVisibilityInteraction(browserTestSource),
+          `${scenario.id} must toggle real layer visibility while checking viewport stability.`,
+        ).toBe(true);
+        expect(
+          hasRealLayerDragInteraction(browserTestSource),
+          `${scenario.id} must drag real layer rows for reorder or grouping while checking viewport stability.`,
+        ).toBe(true);
+        expect(
+          browserTestSource,
+          `${scenario.id} must assert selected-layer or product output after layer interactions.`,
+        ).toMatch(/selected layer|selectedLayer|product-output|rendered-pixels|canvas|export|output/i);
+      }
+    }
+
+    if (scenario.interaction === "animation-frame") {
+      expect(
+        browserTestSource,
+        `${scenario.id} must use measureToolcraftAnimationFrames so animated renderers are sampled for at least 120 frames.`,
+      ).toMatch(/measureToolcraftAnimationFrames\s*\(/);
+      expect(
+        browserTestSource,
+        `${scenario.id} must not satisfy animation coverage with a short waitForToolcraftAnimationFrames probe.`,
+      ).not.toMatch(/waitForToolcraftAnimationFrames\s*\(\s*page\s*,\s*(?:[1-9]|[1-9]\d|1[01]\d)\s*\)/);
+    }
+
+    if (scenario.interaction === "animation-viewport-drag") {
+      expect(
+        browserTestSource,
+        `${scenario.id} must measure a real canvas viewport drag while the renderer is animated.`,
+      ).toMatch(/measureToolcraftInteraction\s*\([\s\S]*dragToolcraftCanvasViewport\s*\(/);
+      expect(
+        browserTestSource,
+        `${scenario.id} must not fake animated viewport coverage with toolbar zoom or direct canvas commands.`,
+      ).not.toMatch(/canvas\.setOffset|canvas\.panBy|canvas\.zoom|Zoom in|Zoom out|Center canvas/);
+    }
+
+    if (scenario.interaction === "viewport-zoom-stress") {
+      expect(
+        browserTestSource,
+        `${scenario.id} must measure real toolbar zoom while sampling frame gaps.`,
+      ).toMatch(/measureToolcraftInteraction\s*\([\s\S]*zoomToolcraftCanvasViewport\s*\(/);
+      expect(
+        browserTestSource,
+        `${scenario.id} must not fake zoom stress with direct runtime canvas commands.`,
+      ).not.toMatch(/canvas\.setZoom|canvas\.zoom|canvas\.setScale|canvas\.setOffset|canvas\.panBy/);
+    }
+
+    expect(
+      browserTestSource,
+      `${scenario.id} must assert product or UI output after the measured interaction so a no-op control cannot pass.`,
+    ).toMatch(/await\s+expect\s*\(|expect\s*\(/);
+
+    expect(
+      browserTestSource,
+      `${scenario.id} must assert its typed budget through expectToolcraftScenarioPerformanceBudget(..., appPerformance, "${scenario.id}") so browser thresholds cannot drift from app-performance.ts.`,
+    ).toMatch(getScenarioBudgetAssertionPattern(scenario.id));
+  }
+});
+
+test("declared renderer layer selectors are present", async ({ page }) => {
+  if (!starterPerformance.usesCustomRenderer) {
+    return;
+  }
+
+  const visibleLayers =
+    starterPerformance.rendererTechnique?.layers?.filter((layer) => layer.uiSelector) ?? [];
+
+  await page.goto("/");
+
+  for (const layer of visibleLayers) {
+    await expect(
+      page.locator(layer.uiSelector!).first(),
+      `renderer layer "${layer.id}" should exist at ${layer.uiSelector}`,
+    ).toBeVisible();
+  }
+});

package/templates/starter/e2e/canvas-handle-helpers.ts

@@ -0,0 +1,244 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+export function getCanvasHandle(page: Page, testId: string): Locator {
+  return page.locator(`[data-toolcraft-canvas-handle][data-testid="${testId}"]`);
+}
+
+export async function dragCanvasHandle(
+  page: Page,
+  testId: string,
+  delta: { x: number; y: number },
+): Promise<void> {
+  const handle = getCanvasHandle(page, testId);
+  await expect(handle, `Canvas handle "${testId}" should be visible`).toBeVisible();
+
+  const box = await handle.boundingBox();
+  if (!box) {
+    throw new Error(`Could not measure canvas handle "${testId}".`);
+  }
+
+  const startX = box.x + box.width / 2;
+  const startY = box.y + box.height / 2;
+
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  await page.mouse.move(startX + delta.x, startY + delta.y, { steps: 8 });
+  await page.mouse.up();
+}
+
+const defaultForbiddenCanvasCopyPatterns = [
+  /apply/i,
+  /choose file/i,
+  /click to upload/i,
+  /copy png/i,
+  /drag it onto the canvas/i,
+  /export png/i,
+  /generate/i,
+  /reset/i,
+  /settings/i,
+  /upload an image/i,
+] as const;
+
+const productCanvasTextSelector =
+  "[data-toolcraft-product-output], [data-toolcraft-product-text]";
+
+export type ToolcraftCanvasUiCheckOptions = {
+  allowedProductText?: readonly RegExp[];
+};
+
+export async function expectNoForbiddenCanvasUi(
+  page: Page,
+  options: ToolcraftCanvasUiCheckOptions = {},
+): Promise<void> {
+  const canvasWorld = page.locator(
+    '[data-toolcraft-canvas-world], [data-toolcraft-editable-canvas]',
+  );
+
+  await expect(
+    canvasWorld.locator(
+      [
+        'button:not([data-toolcraft-canvas-handle])',
+        "input",
+        "textarea",
+        "select",
+        '[role="button"]:not([data-toolcraft-canvas-handle])',
+        '[role="menu"]',
+        '[role="dialog"]',
+        '[data-slot="button"]',
+        '[data-slot="input"]',
+      ].join(", "),
+    ),
+    "Canvas must not contain app UI controls; only product output and data-toolcraft-canvas-handle overlays are allowed.",
+  ).toHaveCount(0);
+
+  const canvasTextMatches = await canvasWorld.evaluateAll(
+    (roots, { allowedSources, forbiddenSources, productTextSelector }) => {
+      const allowedPatterns = allowedSources.map((source) => new RegExp(source, "i"));
+      const forbiddenPatterns = forbiddenSources.map((source) => new RegExp(source, "i"));
+      const matches: { kind: "forbidden-copy" | "unclassified-text"; text: string }[] = [];
+
+      const getDirectText = (element: Element) =>
+        Array.from(element.childNodes)
+          .filter((node) => node.nodeType === Node.TEXT_NODE)
+          .map((node) => node.textContent?.trim() ?? "")
+          .filter(Boolean)
+          .join(" ")
+          .trim();
+
+      for (const root of roots) {
+        const elements = [root, ...Array.from(root.querySelectorAll("*"))];
+
+        for (const element of elements) {
+          if (element.closest("[data-toolcraft-canvas-handle]")) {
+            continue;
+          }
+
+          const text = getDirectText(element);
+
+          if (!text) {
+            continue;
+          }
+
+          if (allowedPatterns.some((pattern) => pattern.test(text))) {
+            continue;
+          }
+
+          if (forbiddenPatterns.some((pattern) => pattern.test(text))) {
+            matches.push({ kind: "forbidden-copy", text });
+            continue;
+          }
+
+          if (!element.closest(productTextSelector)) {
+            matches.push({ kind: "unclassified-text", text });
+          }
+        }
+      }
+
+      return matches;
+    },
+    {
+      allowedSources: (options.allowedProductText ?? []).map((pattern) => pattern.source),
+      forbiddenSources: defaultForbiddenCanvasCopyPatterns.map((pattern) => pattern.source),
+      productTextSelector: productCanvasTextSelector,
+    },
+  );
+
+  expect(
+    canvasTextMatches,
+    "Canvas text must be product output marked with data-toolcraft-product-output/data-toolcraft-product-text; app UI copy, CTAs, helper text, upload prompts, export/copy/reset text, and settings labels are forbidden.",
+  ).toEqual([]);
+}
+
+export async function expectExportExcludesCanvasHandles(
+  page: Page,
+  exportAction: () => Promise<unknown>,
+): Promise<void> {
+  await exportAction();
+
+  const handles = page.locator("[data-toolcraft-canvas-handle]");
+  const count = await handles.count();
+
+  for (let index = 0; index < count; index += 1) {
+    const handle = handles.nth(index);
+    await expect(
+      handle,
+      "Canvas handles should remain editor overlays after export/copy and must not be duplicated into product output.",
+    ).toHaveAttribute("data-toolcraft-canvas-handle");
+  }
+}
+
+export async function expectCanvasHandlesUseToolcraftVisualLanguage(page: Page): Promise<void> {
+  const handles = page.locator("[data-toolcraft-canvas-handle]");
+  const count = await handles.count();
+
+  for (let index = 0; index < count; index += 1) {
+    const handle = handles.nth(index);
+
+    await expect(handle, `Canvas handle ${index + 1} should be visible`).toBeVisible();
+    await expect(
+      handle.locator(
+        [
+          "button",
+          "input",
+          "textarea",
+          "select",
+          '[role="button"]',
+          '[role="menu"]',
+          '[role="dialog"]',
+          '[data-slot="button"]',
+          '[data-slot="input"]',
+        ].join(", "),
+      ),
+      "Canvas handles must not contain nested app UI controls.",
+    ).toHaveCount(0);
+
+    const style = await handle.evaluate((node) => {
+      const element = node as HTMLElement;
+      const elements = [element, ...Array.from(element.querySelectorAll<HTMLElement>("*"))];
+      const toNumber = (value: string) => Number.parseFloat(value) || 0;
+      const svgStrokeWidths = Array.from(
+        element.querySelectorAll<SVGElement>(
+          "svg [stroke-width], svg line, svg path, svg circle, svg rect, svg polyline, svg polygon",
+        ),
+      ).map((svgElement) => {
+        const attributeValue = svgElement.getAttribute("stroke-width");
+        const computedValue = window.getComputedStyle(svgElement).strokeWidth;
+        return toNumber(attributeValue ?? computedValue);
+      });
+      const getMaxStrokeWidth = (property: "border" | "outline") =>
+        Math.max(
+          ...elements.map((currentElement) => {
+            const computed = window.getComputedStyle(currentElement);
+            if (property === "outline") {
+              return toNumber(computed.outlineWidth);
+            }
+
+            return Math.max(
+              toNumber(computed.borderTopWidth),
+              toNumber(computed.borderRightWidth),
+              toNumber(computed.borderBottomWidth),
+              toNumber(computed.borderLeftWidth),
+            );
+          }),
+        );
+      const rect = element.getBoundingClientRect();
+
+      return {
+        borderWidth: getMaxStrokeWidth("border"),
+        height: rect.height,
+        outlineWidth: getMaxStrokeWidth("outline"),
+        role: element.getAttribute("role") ?? "",
+        svgStrokeWidth: Math.max(0, ...svgStrokeWidths),
+        tagName: element.tagName.toLowerCase(),
+        text: element.textContent?.trim() ?? "",
+        width: rect.width,
+      };
+    });
+
+    expect(
+      ["button", "input", "select", "textarea"],
+      "Canvas handle roots must be visual elements, not native app controls.",
+    ).not.toContain(style.tagName);
+    expect(
+      ["button", "menu", "dialog", "textbox", "slider", "spinbutton", "combobox", "listbox"],
+      "Canvas handle roots must not expose app-control roles.",
+    ).not.toContain(style.role);
+    expect(style.text, "Canvas handles should be visual pins/lines, not text labels.").toBe("");
+    expect(
+      style.borderWidth,
+      "Canvas handle borders, including child elements, should stay close to Toolcraft control stroke weights.",
+    ).toBeLessThanOrEqual(2);
+    expect(
+      style.outlineWidth,
+      "Canvas handle outlines, including child elements, should stay close to Toolcraft focus ring weights.",
+    ).toBeLessThanOrEqual(2);
+    expect(
+      style.svgStrokeWidth,
+      "Canvas handle SVG strokes should stay close to Toolcraft control stroke weights.",
+    ).toBeLessThanOrEqual(2);
+    expect(
+      style.width <= 96 || style.height <= 96,
+      "Canvas handles should be pins, lines, corners, or light geometry, not panel-sized controls.",
+    ).toBe(true);
+  }
+}