@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/e2e/performance-budget-helpers.ts

@@ -0,0 +1,159 @@
+import { expect } from "@playwright/test";
+
+import type {
+  ToolcraftPerformanceBudget,
+  ToolcraftPerformanceConfig,
+} from "@repo/toolcraft-runtime";
+
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import {
+  getToolcraftMeasurementProvenance,
+  type ToolcraftInteractionResult,
+} from "./performance-probe-helpers";
+
+type ToolcraftPerformanceBudgetResult = Partial<ToolcraftInteractionResult> & {
+  durationMs?: number;
+  exportMs?: number;
+  frameGapMs?: number;
+  previewMs?: number;
+  renderMs?: number;
+};
+
+export function getToolcraftPerformanceScenarioBudget(
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+): ToolcraftPerformanceBudget {
+  const scenario = config.scenarios.find((item) => item.id === scenarioId);
+
+  if (!scenario) {
+    throw new Error(`Toolcraft performance scenario "${scenarioId}" was not found.`);
+  }
+
+  return scenario.budget;
+}
+
+export function getToolcraftPerformanceStressValue<TValue = unknown>(
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+): TValue {
+  const scenario = config.scenarios.find((item) => item.id === scenarioId);
+
+  if (!scenario) {
+    throw new Error(`Toolcraft performance scenario "${scenarioId}" was not found.`);
+  }
+
+  if (
+    !scenario.stressFixture ||
+    !Object.prototype.hasOwnProperty.call(scenario.stressFixture, "value")
+  ) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" does not declare stressFixture.value.`,
+    );
+  }
+
+  return scenario.stressFixture.value as TValue;
+}
+
+export function getToolcraftPerformanceWorkloadValue<TValue = unknown>(
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+): TValue {
+  const scenario = config.scenarios.find((item) => item.id === scenarioId);
+
+  if (!scenario) {
+    throw new Error(`Toolcraft performance scenario "${scenarioId}" was not found.`);
+  }
+
+  if (
+    !scenario.workloadFixture ||
+    !Object.prototype.hasOwnProperty.call(scenario.workloadFixture, "value")
+  ) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" does not declare workloadFixture.value.`,
+    );
+  }
+
+  return scenario.workloadFixture.value as TValue;
+}
+
+export async function expectToolcraftScenarioPerformanceBudget(
+  result: ToolcraftPerformanceBudgetResult,
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+): Promise<void> {
+  const scenario = config.scenarios.find((item) => item.id === scenarioId);
+  if (!scenario) {
+    throw new Error(`Toolcraft performance scenario "${scenarioId}" was not found.`);
+  }
+  const provenance = getToolcraftMeasurementProvenance(
+    result,
+  );
+  if (
+    provenance?.scenarioId !== scenarioId ||
+    provenance.target !== scenario.target
+  ) {
+    throw new Error(
+      `Toolcraft performance budget "${scenarioId}" requires a result created by a protected measurement helper for the same scenario and schema target.`,
+    );
+  }
+  expectToolcraftPerformanceBudget(
+    result,
+    getToolcraftPerformanceScenarioBudget(config, scenarioId),
+  );
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType: "performance-budget",
+    requirementId: scenarioId,
+    target: scenario.target,
+  });
+}
+
+export function expectToolcraftPerformanceBudget(
+  result: ToolcraftPerformanceBudgetResult,
+  budget: ToolcraftPerformanceBudget,
+): void {
+  if (typeof budget.maxInteractionMs === "number") {
+    expect(
+      result.durationMs,
+      `Expected interaction duration to stay within ${budget.maxInteractionMs}ms.`,
+    ).toBeLessThanOrEqual(budget.maxInteractionMs);
+  }
+
+  if (typeof budget.maxFrameGapMs === "number") {
+    expect(
+      result.sampleCount,
+      "Frame-gap budgets require at least one observed animation frame.",
+    ).toBeGreaterThan(0);
+    expect(
+      result.maxFrameGapMs ?? result.frameGapMs,
+      `Expected frame gaps to stay within ${budget.maxFrameGapMs}ms.`,
+    ).toBeLessThanOrEqual(budget.maxFrameGapMs);
+  }
+
+  if (typeof budget.maxLongTaskMs === "number") {
+    expect(
+      result.longTaskMaxMs,
+      `Expected long tasks to stay within ${budget.maxLongTaskMs}ms.`,
+    ).toBeLessThanOrEqual(budget.maxLongTaskMs);
+  }
+
+  if (typeof budget.maxExportMs === "number") {
+    expect(
+      result.exportMs ?? result.durationMs,
+      `Expected export/copy duration to stay within ${budget.maxExportMs}ms.`,
+    ).toBeLessThanOrEqual(budget.maxExportMs);
+  }
+
+  if (typeof budget.maxPreviewMs === "number") {
+    expect(
+      result.previewMs ?? result.durationMs,
+      `Expected preview duration to stay within ${budget.maxPreviewMs}ms.`,
+    ).toBeLessThanOrEqual(budget.maxPreviewMs);
+  }
+
+  if (typeof budget.maxRenderMs === "number") {
+    expect(
+      result.renderMs ?? result.durationMs,
+      `Expected render duration to stay within ${budget.maxRenderMs}ms.`,
+    ).toBeLessThanOrEqual(budget.maxRenderMs);
+  }
+}

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

@@ -0,0 +1,123 @@
+import { expect, type Page } from "@playwright/test";
+
+import {
+  measureToolcraftInteraction,
+  waitForToolcraftAnimationFrames,
+  type ToolcraftInteractionOptions,
+  type ToolcraftInteractionResult,
+} from "./performance-probe-helpers";
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+
+export async function dragToolcraftCanvasViewport(
+  page: Page,
+  delta: { x: number; y: number } = { x: 96, y: -64 },
+  options: { scenarioId?: string } = {},
+): Promise<void> {
+  const viewport = page.getByRole("application", { name: "Canvas viewport" });
+  await expect(viewport, "Toolcraft canvas viewport should be visible").toBeVisible();
+
+  const box = await viewport.boundingBox();
+  if (!box) {
+    throw new Error("Could not measure Toolcraft canvas viewport.");
+  }
+
+  const startX = box.x + box.width * 0.5;
+  const startY = box.y + box.height * 0.5;
+
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  await page.mouse.move(startX + delta.x, startY + delta.y, { steps: 16 });
+  await page.mouse.up();
+  if (options.scenarioId) {
+    await attachToolcraftBrowserRuntimeEvidence({
+      evidenceType: "performance-viewport",
+      requirementId: options.scenarioId,
+    });
+  }
+}
+
+export async function zoomToolcraftCanvasViewport(
+  page: Page,
+  repetitions = 2,
+  options: { scenarioId?: string } = {},
+): Promise<void> {
+  const zoomIn = page.getByRole("button", { name: "Zoom in" });
+  const zoomOut = page.getByRole("button", { name: "Zoom out" });
+
+  await expect(zoomIn, "Toolcraft zoom-in control should be visible").toBeVisible();
+  await expect(zoomOut, "Toolcraft zoom-out control should be visible").toBeVisible();
+
+  for (let index = 0; index < repetitions; index += 1) {
+    await zoomIn.click();
+    await waitForToolcraftAnimationFrames(page, 2);
+  }
+
+  for (let index = 0; index < repetitions; index += 1) {
+    await zoomOut.click();
+    await waitForToolcraftAnimationFrames(page, 2);
+  }
+  if (options.scenarioId) {
+    await attachToolcraftBrowserRuntimeEvidence({
+      evidenceType: "performance-viewport",
+      requirementId: options.scenarioId,
+    });
+  }
+}
+
+export async function readToolcraftCanvasViewport(page: Page): Promise<{
+  offsetX: number;
+  offsetY: number;
+  zoom: number;
+}> {
+  return page.evaluate(() => {
+    const canvas = document.querySelector("[data-toolcraft-editable-canvas]");
+    const style = canvas ? window.getComputedStyle(canvas) : null;
+    const zoomText =
+      canvas?.getAttribute("data-canvas-zoom") ??
+      style?.getPropertyValue("--canvas-zoom") ??
+      "1";
+
+    return {
+      offsetX: Number(canvas?.getAttribute("data-canvas-offset-x") ?? 0),
+      offsetY: Number(canvas?.getAttribute("data-canvas-offset-y") ?? 0),
+      zoom: Number.parseFloat(zoomText) || 1,
+    };
+  });
+}
+
+export async function expectToolcraftCanvasViewportStable(
+  page: Page,
+  action: () => Promise<void>,
+  options: ToolcraftInteractionOptions & {
+    maxOffsetDelta?: number;
+    maxZoomDelta?: number;
+  } = {},
+): Promise<ToolcraftInteractionResult> {
+  const before = await readToolcraftCanvasViewport(page);
+  const result = await measureToolcraftInteraction(page, action, options);
+  const after = await readToolcraftCanvasViewport(page);
+  const maxOffsetDelta = options.maxOffsetDelta ?? 0.5;
+  const maxZoomDelta = options.maxZoomDelta ?? 0.001;
+
+  expect(
+    Math.abs(after.offsetX - before.offsetX),
+    `Expected canvas offsetX to stay stable within ${maxOffsetDelta}px.`,
+  ).toBeLessThanOrEqual(maxOffsetDelta);
+  expect(
+    Math.abs(after.offsetY - before.offsetY),
+    `Expected canvas offsetY to stay stable within ${maxOffsetDelta}px.`,
+  ).toBeLessThanOrEqual(maxOffsetDelta);
+  expect(
+    Math.abs(after.zoom - before.zoom),
+    `Expected canvas zoom to stay stable within ${maxZoomDelta}.`,
+  ).toBeLessThanOrEqual(maxZoomDelta);
+
+  if (options.scenarioId) {
+    await attachToolcraftBrowserRuntimeEvidence({
+      evidenceType: "performance-viewport",
+      requirementId: options.scenarioId,
+    });
+  }
+
+  return result;
+}

package/templates/starter/e2e/performance-control-helpers.ts

@@ -0,0 +1,3 @@
+export * from "./performance-control-layout-helpers";
+export * from "./performance-render-scale-helpers";
+export * from "./performance-slider-helpers";

package/templates/starter/e2e/performance-control-layout-helpers.ts

@@ -0,0 +1,161 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+import { getToolcraftControlFieldByTarget } from "./browser-control-target-helpers";
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+export async function getToolcraftFieldByLabel(page: Page, label: string): Promise<Locator> {
+  const field = page
+    .locator('[data-slot="field"]')
+    .filter({ hasText: new RegExp(`^${escapeRegExp(label)}`) });
+  await expect(field, `Toolcraft field "${label}" should be visible`).toBeVisible();
+  return field;
+}
+
+export async function expectToolcraftSegmentedControlCellsPreservePadding(
+  page: Page,
+  label: string,
+  options: {
+    minHorizontalPaddingPx?: number;
+    requirementId?: string;
+    target?: string;
+  } = {},
+): Promise<void> {
+  const minHorizontalPaddingPx = options.minHorizontalPaddingPx ?? 6;
+  const field = options.target
+    ? await getToolcraftControlFieldByTarget(page, options.target)
+    : await getToolcraftFieldByLabel(page, label);
+  const segmentedGroup = field.locator('[data-slot="toggle-group"]').first();
+
+  await expect(
+    segmentedGroup,
+    `Toolcraft segmented control "${label}" should render a toggle group.`,
+  ).toBeVisible();
+
+  const issues = await segmentedGroup.evaluate(
+    (group, minPadding) => {
+      type LayoutIssue = {
+        label: string;
+        reason: string;
+      };
+
+      function getTextRect(element: Element): DOMRect | null {
+        const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, {
+          acceptNode(node) {
+            return node.textContent?.trim()
+              ? NodeFilter.FILTER_ACCEPT
+              : NodeFilter.FILTER_REJECT;
+          },
+        });
+        const textNodes: Text[] = [];
+        let currentNode = walker.nextNode();
+
+        while (currentNode) {
+          textNodes.push(currentNode as Text);
+          currentNode = walker.nextNode();
+        }
+
+        if (textNodes.length === 0) {
+          return null;
+        }
+
+        const range = document.createRange();
+        range.setStartBefore(textNodes[0]!);
+        range.setEndAfter(textNodes[textNodes.length - 1]!);
+
+        return range.getBoundingClientRect();
+      }
+
+      const items = Array.from(
+        group.querySelectorAll<HTMLElement>('[data-slot="toggle-group-item"]'),
+      );
+      const issues: LayoutIssue[] = [];
+      const canvas = document.createElement("canvas");
+      const context = canvas.getContext("2d");
+
+      for (let index = 0; index < items.length; index += 1) {
+        const item = items[index]!;
+        const itemRect = item.getBoundingClientRect();
+        const textRect = getTextRect(item);
+        const label = item.textContent?.trim() || item.getAttribute("aria-label") || `#${index + 1}`;
+        const nextItem = items[index + 1];
+        const computedStyle = window.getComputedStyle(item);
+
+        if (context && label.trim()) {
+          context.font = computedStyle.font;
+          const measuredTextWidth = context.measureText(label).width;
+          const requiredWidth = measuredTextWidth + minPadding * 2;
+
+          if (requiredWidth > itemRect.width + 0.5) {
+            issues.push({
+              label,
+              reason: `label requires ${requiredWidth.toFixed(2)}px including padding but cell width is ${itemRect.width.toFixed(2)}px`,
+            });
+          }
+        }
+
+        if (nextItem) {
+          const nextRect = nextItem.getBoundingClientRect();
+
+          if (itemRect.right > nextRect.left + 0.5) {
+            issues.push({
+              label,
+              reason: `cell overlaps next cell by ${(itemRect.right - nextRect.left).toFixed(2)}px`,
+            });
+          }
+        }
+
+        if (item.scrollWidth > item.clientWidth + 1) {
+          issues.push({
+            label,
+            reason: `cell scrollWidth ${item.scrollWidth}px exceeds clientWidth ${item.clientWidth}px`,
+          });
+        }
+
+        if (!textRect) {
+          continue;
+        }
+
+        const leftPadding = textRect.left - itemRect.left;
+        const rightPadding = itemRect.right - textRect.right;
+
+        if (leftPadding < minPadding) {
+          issues.push({
+            label,
+            reason: `left text padding ${leftPadding.toFixed(2)}px is below ${minPadding}px`,
+          });
+        }
+
+        if (rightPadding < minPadding) {
+          issues.push({
+            label,
+            reason: `right text padding ${rightPadding.toFixed(2)}px is below ${minPadding}px`,
+          });
+        }
+      }
+
+      return issues;
+    },
+    minHorizontalPaddingPx,
+  );
+
+  expect(
+    issues,
+    `Toolcraft segmented control "${label}" must preserve cell padding and avoid label collisions.`,
+  ).toEqual([]);
+  if (options.requirementId) {
+    if (!options.target) {
+      throw new Error(
+        "Segmented-control runtime evidence requires a schema target.",
+      );
+    }
+    await attachToolcraftBrowserRuntimeEvidence({
+      evidenceType: "segmented-control-layout",
+      requirementId: options.requirementId,
+      target: options.target,
+    });
+  }
+}

package/templates/starter/e2e/performance-fixture-helpers.ts

@@ -0,0 +1,217 @@
+import { expect, type Page } from "@playwright/test";
+
+import type { ToolcraftPerformanceConfig } from "@repo/toolcraft-runtime";
+
+import {
+  getToolcraftPerformanceStressValue,
+  getToolcraftPerformanceWorkloadValue,
+} from "./performance-budget-helpers";
+import { attachToolcraftBrowserRuntimeEvidence } from "./browser-runtime-evidence";
+
+export type ToolcraftStressFixtureApplyContext = {
+  config: ToolcraftPerformanceConfig;
+  fixture: Record<string, unknown>;
+  key: string;
+  page: Page;
+  scenarioId: string;
+};
+
+export type ToolcraftStressFixtureAppliers = Record<
+  string,
+  {
+    applyValue: (
+      value: unknown,
+      context: ToolcraftStressFixtureApplyContext,
+    ) => Promise<void> | void;
+    observeValue: (
+      context: ToolcraftStressFixtureApplyContext,
+    ) => Promise<unknown> | unknown;
+  }
+>;
+
+export type ToolcraftScalarFixtureApplication<TValue> = {
+  applyValue: (value: TValue) => Promise<void> | void;
+  observeValue: () => Promise<TValue> | TValue;
+};
+
+function isToolcraftStressFixtureObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function assertFixtureAppliersCoverKeys(
+  scenarioId: string,
+  fixtureKind: "stressFixture" | "workloadFixture",
+  fixtureKeys: readonly string[],
+  appliers: ToolcraftStressFixtureAppliers,
+): void {
+  const applierLabel = fixtureKind === "stressFixture" ? "fixture" : "workload fixture";
+  const missingKeys = fixtureKeys.filter((key) => !appliers[key]);
+  if (missingKeys.length > 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" is missing ${applierLabel} appliers for: ${missingKeys.join(
+        ", ",
+      )}.`,
+    );
+  }
+
+  const extraKeys = Object.keys(appliers).filter((key) => !fixtureKeys.includes(key));
+  if (extraKeys.length > 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" declares ${applierLabel} appliers not present in ${fixtureKind}.value: ${extraKeys.join(
+        ", ",
+      )}.`,
+    );
+  }
+}
+
+async function applyToolcraftPerformanceFixture(
+  page: Page,
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  fixtureKind: "stressFixture" | "workloadFixture",
+  fixture: unknown,
+  appliers: ToolcraftStressFixtureAppliers,
+): Promise<Record<string, unknown>> {
+  const scenario = config.scenarios.find((item) => item.id === scenarioId);
+  if (!scenario) {
+    throw new Error(`Toolcraft performance scenario "${scenarioId}" was not found.`);
+  }
+  if (!isToolcraftStressFixtureObject(fixture)) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" must provide an object ${fixtureKind}.value for ${fixtureKind === "stressFixture" ? "combined fixture" : "baseline fixture"} application.`,
+    );
+  }
+
+  const fixtureKeys = Object.keys(fixture);
+  if (fixtureKeys.length === 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" ${fixtureKind}.value must contain at least one key.`,
+    );
+  }
+
+  assertFixtureAppliersCoverKeys(scenarioId, fixtureKind, fixtureKeys, appliers);
+
+  for (const key of fixtureKeys) {
+    await appliers[key]!.applyValue(fixture[key], {
+      config,
+      fixture,
+      key,
+      page,
+      scenarioId,
+    });
+  }
+
+  for (const key of fixtureKeys) {
+    const observedValue = await appliers[key]!.observeValue({
+      config,
+      fixture,
+      key,
+      page,
+      scenarioId,
+    });
+    expect(
+      observedValue,
+      `Toolcraft performance scenario "${scenarioId}" must preserve the observed fixture value for "${key}" after applying the complete ${fixtureKind}.`,
+    ).toEqual(fixture[key]);
+  }
+
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType:
+      fixtureKind === "stressFixture"
+        ? "performance-stress-fixture"
+        : "performance-workload-fixture",
+    requirementId: scenarioId,
+    target: scenario.target,
+  });
+
+  return fixture;
+}
+
+async function applyToolcraftPerformanceScalarFixture<TValue>(
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  fixtureKind: "stressFixture" | "workloadFixture",
+  application: ToolcraftScalarFixtureApplication<TValue>,
+): Promise<TValue> {
+  const scenario = config.scenarios.find((item) => item.id === scenarioId);
+  if (!scenario) {
+    throw new Error(`Toolcraft performance scenario "${scenarioId}" was not found.`);
+  }
+  const value =
+    fixtureKind === "stressFixture"
+      ? getToolcraftPerformanceStressValue<TValue>(config, scenarioId)
+      : getToolcraftPerformanceWorkloadValue<TValue>(config, scenarioId);
+  await application.applyValue(value);
+  const observedValue = await application.observeValue();
+  expect(
+    observedValue,
+    `Toolcraft performance scenario "${scenarioId}" must expose the observed fixture value after applying ${fixtureKind}.value.`,
+  ).toEqual(value);
+  await attachToolcraftBrowserRuntimeEvidence({
+    evidenceType:
+      fixtureKind === "stressFixture"
+        ? "performance-stress-fixture"
+        : "performance-workload-fixture",
+    requirementId: scenarioId,
+    target: scenario.target,
+  });
+  return value;
+}
+
+export async function applyToolcraftPerformanceStressValue<TValue>(
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  application: ToolcraftScalarFixtureApplication<TValue>,
+): Promise<TValue> {
+  return applyToolcraftPerformanceScalarFixture(
+    config,
+    scenarioId,
+    "stressFixture",
+    application,
+  );
+}
+
+export async function applyToolcraftPerformanceWorkloadValue<TValue>(
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  application: ToolcraftScalarFixtureApplication<TValue>,
+): Promise<TValue> {
+  return applyToolcraftPerformanceScalarFixture(
+    config,
+    scenarioId,
+    "workloadFixture",
+    application,
+  );
+}
+
+export async function applyToolcraftPerformanceStressFixture(
+  page: Page,
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  appliers: ToolcraftStressFixtureAppliers,
+): Promise<Record<string, unknown>> {
+  return applyToolcraftPerformanceFixture(
+    page,
+    config,
+    scenarioId,
+    "stressFixture",
+    getToolcraftPerformanceStressValue(config, scenarioId),
+    appliers,
+  );
+}
+
+export async function applyToolcraftPerformanceWorkloadFixture(
+  page: Page,
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  appliers: ToolcraftStressFixtureAppliers,
+): Promise<Record<string, unknown>> {
+  return applyToolcraftPerformanceFixture(
+    page,
+    config,
+    scenarioId,
+    "workloadFixture",
+    getToolcraftPerformanceWorkloadValue(config, scenarioId),
+    appliers,
+  );
+}