@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/runtime/testing/performance-schema-queries.ts

@@ -0,0 +1,181 @@
+import type {
+  ResolvedToolcraftAppSchema,
+  ToolcraftControlSchema,
+} from "../schema/types";
+import type { ToolcraftPerformanceValueSet } from "./performance-types";
+
+export function getAllSchemaControls(
+  schema: ResolvedToolcraftAppSchema,
+): ToolcraftControlSchema[] {
+  return (schema.panels.controls?.sections ?? []).flatMap((section) =>
+    Object.values(section.controls),
+  );
+}
+
+export function getVisiblePerformanceControlTargets(schema: ResolvedToolcraftAppSchema): string[] {
+  return getAllSchemaControls(schema)
+    .filter((control) => control.type !== "panelActions")
+    .map((control) => control.target);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+export function getToolcraftControlPerformanceValues(
+  control: ToolcraftControlSchema | undefined,
+): ToolcraftPerformanceValueSet | null {
+  if (!control) {
+    return null;
+  }
+
+  if (
+    control.type === "slider" &&
+    isFiniteNumber(control.defaultValue) &&
+    isFiniteNumber(control.max) &&
+    isFiniteNumber(control.min)
+  ) {
+    return {
+      default: control.defaultValue,
+      max: control.max,
+      min: control.min,
+    };
+  }
+
+  if (
+    control.type === "rangeSlider" &&
+    Array.isArray(control.defaultValue) &&
+    control.defaultValue.length === 2 &&
+    control.defaultValue.every(isFiniteNumber) &&
+    isFiniteNumber(control.max) &&
+    isFiniteNumber(control.min)
+  ) {
+    return {
+      default: [...control.defaultValue],
+      max: [control.max, control.max],
+      min: [control.min, control.min],
+    };
+  }
+
+  if (
+    (control.type === "select" || control.type === "segmented") &&
+    control.options &&
+    control.options.length > 0
+  ) {
+    return {
+      default: control.defaultValue ?? control.options[0]?.value,
+      max: control.options.at(-1)?.value,
+      min: control.options[0]?.value,
+    };
+  }
+
+  return null;
+}
+
+export function getToolcraftSchemaPerformanceValues(
+  schema: ResolvedToolcraftAppSchema,
+  target: string,
+): ToolcraftPerformanceValueSet | null {
+  return getToolcraftControlPerformanceValues(
+    getAllSchemaControls(schema).find((control) => control.target === target),
+  );
+}
+
+export function requireToolcraftSchemaPerformanceValues(
+  schema: ResolvedToolcraftAppSchema,
+  target: string,
+): ToolcraftPerformanceValueSet {
+  const values = getToolcraftSchemaPerformanceValues(schema, target);
+
+  if (!values) {
+    throw new Error(
+      `Toolcraft schema target "${target}" does not expose a derivable performance range.`,
+    );
+  }
+
+  return values;
+}
+
+function getActionValue(
+  action: NonNullable<ToolcraftControlSchema["actions"]>[number],
+): string {
+  return typeof action === "string" ? action : action.value;
+}
+
+function getActionLabel(
+  action: NonNullable<ToolcraftControlSchema["actions"]>[number],
+): string | undefined {
+  return typeof action === "string" ? undefined : action.label;
+}
+
+function normalizeActionReference(value: string | undefined): string {
+  return String(value ?? "")
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+const outputDeliveryActionRoles = new Set([
+  "copy-output",
+  "download-output",
+  "export-image",
+  "export-video",
+]);
+
+function isOutputDeliveryAction(
+  action: NonNullable<ToolcraftControlSchema["actions"]>[number],
+): boolean {
+  return typeof action !== "string" && outputDeliveryActionRoles.has(action.role ?? "");
+}
+
+function getOutputDeliveryActions(
+  schema: ResolvedToolcraftAppSchema,
+): NonNullable<ToolcraftControlSchema["actions"]>[number][] {
+  return getAllSchemaControls(schema).flatMap((control) => {
+    if (control.type !== "panelActions") {
+      return [];
+    }
+
+    return (control.actions ?? []).filter(isOutputDeliveryAction);
+  });
+}
+
+export function hasOutputDeliveryAction(schema: ResolvedToolcraftAppSchema): boolean {
+  return getOutputDeliveryActions(schema).length > 0;
+}
+
+export function hasOutputDeliveryActionReference(
+  schema: ResolvedToolcraftAppSchema,
+  reference: { actionValue?: string; controlLabel?: string },
+): boolean {
+  const outputActions = getOutputDeliveryActions(schema);
+  const expectedActionValue = reference.actionValue?.trim();
+  if (!expectedActionValue) {
+    return false;
+  }
+
+  const matchingAction = outputActions.find(
+    (action) => getActionValue(action).trim() === expectedActionValue,
+  );
+  if (!matchingAction) {
+    return false;
+  }
+
+  const expectedLabel = normalizeActionReference(reference.controlLabel);
+  return (
+    !expectedLabel ||
+    normalizeActionReference(
+      getActionLabel(matchingAction) ?? getActionValue(matchingAction),
+    ) === expectedLabel
+  );
+}
+
+export function hasKeyframeTimeline(schema: ResolvedToolcraftAppSchema): boolean {
+  return schema.panels.timeline?.enabled === true && schema.panels.timeline.mode === "keyframes";
+}
+
+export function hasLayersPanel(schema: ResolvedToolcraftAppSchema): boolean {
+  return schema.panels.layers === true;
+}

package/templates/runtime/testing/performance-test-fixtures/index.ts

@@ -0,0 +1,4 @@
+export * from "./schemas";
+export * from "./stress-fixtures";
+export * from "./renderer-pipelines";
+export * from "./scenarios";

package/templates/runtime/testing/performance-test-fixtures/renderer-pipelines.ts

@@ -0,0 +1,322 @@
+export function createMeasuredWebglEvidence(scenarioId = "text-preview-render") {
+  return [
+    {
+      alternativeStrategy: "webgl" as const,
+      decision:
+        "Canvas 2D remains selected because cached CPU rendering stayed within budget for this product fixture while preserving export parity.",
+      fixture: "large product stress fixture at render scale 2",
+      measuredResult:
+        "WebGL comparison: maxFrameGapMs 72, maxLongTaskMs 64; Canvas 2D comparison: maxFrameGapMs 68, maxLongTaskMs 58.",
+      scenarioId,
+    },
+  ];
+}
+
+export function createTextRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["text-layout"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["text-layout"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["text-layout"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["product.content", "render.density", "render.mode"],
+        id: "text-layout",
+        inputs: ["product.content", "render.density", "render.mode"],
+        invalidatedBy: ["product.content", "render.density", "render.mode"],
+        kind: "text-layout",
+        output: "preview",
+        quality: "full",
+        runsOn: "main",
+      },
+    ],
+  } as const;
+}
+
+export function createAnimatedVectorRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["vector-build"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["vector-build"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "animation-frame",
+        invalidates: ["animation-composite"],
+        mustNotInvalidate: ["vector-build"],
+        targets: ["animation.time"],
+      },
+      {
+        interaction: "timeline-playback",
+        invalidates: ["animation-composite"],
+        mustNotInvalidate: ["vector-build"],
+        targets: ["timeline.currentTime"],
+      },
+      {
+        interaction: "timeline-scrub",
+        invalidates: ["animation-composite"],
+        mustNotInvalidate: ["vector-build"],
+        targets: ["timeline.currentTime"],
+      },
+      {
+        interaction: "viewport-drag",
+        invalidates: [],
+        mustNotInvalidate: ["vector-build", "animation-composite"],
+        targets: ["canvas.viewport"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["vector-build", "animation-composite"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        id: "vector-build",
+        inputs: ["render.density", "render.mode"],
+        invalidatedBy: ["render.density", "render.mode"],
+        kind: "vector-build",
+        output: "preview",
+        quality: "full",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["vector-build", "animation.time", "timeline.currentTime"],
+        id: "animation-composite",
+        inputs: ["vector-build", "animation.time", "timeline.currentTime"],
+        invalidatedBy: ["animation.time", "timeline.currentTime"],
+        kind: "composite",
+        output: "preview",
+        quality: "preview",
+        runsOn: "main",
+      },
+    ],
+  } as const;
+}
+
+export function createDenseCanvasPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["dense-background", "export-composite"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["export-composite"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["dense-background", "export-composite"],
+        targets: ["canvas.viewport"],
+      },
+      {
+        interaction: "export",
+        invalidates: ["export-composite"],
+        mustNotInvalidate: ["dense-background"],
+        targets: ["export.image.resolution"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["render.density", "canvas.size", "canvas.renderScale"],
+        id: "dense-background",
+        inputs: ["render.density", "canvas.size", "canvas.renderScale"],
+        invalidatedBy: ["render.density", "canvas.size", "canvas.renderScale"],
+        kind: "rasterize",
+        output: "preview",
+        quality: "retina",
+        runsOn: "worker",
+      },
+      {
+        id: "semantic-foreground",
+        inputs: ["product.geometry"],
+        invalidatedBy: ["product.geometry"],
+        kind: "vector-build",
+        output: "preview",
+        quality: "full",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["dense-background", "semantic-foreground", "export.image.resolution"],
+        id: "export-composite",
+        inputs: ["dense-background", "semantic-foreground", "export.image.resolution"],
+        invalidatedBy: ["dense-background", "semantic-foreground", "export.image.resolution"],
+        kind: "composite",
+        output: "export",
+        quality: "export",
+        runsOn: "export-only",
+      },
+    ],
+  } as const;
+}
+
+export function createMainThreadCanvasCompositePipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["text-texture", "warp-composite", "optical-composite"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["text-texture", "warp-composite", "optical-composite"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["text-texture", "warp-composite", "optical-composite"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["product.content", "render.density", "canvas.size", "canvas.renderScale"],
+        id: "text-texture",
+        inputs: ["product.content", "render.density", "canvas.size", "canvas.renderScale"],
+        invalidatedBy: ["product.content", "render.density", "canvas.size", "canvas.renderScale"],
+        kind: "rasterize",
+        output: "intermediate",
+        quality: "retina",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["text-texture", "render.density", "canvas.size"],
+        id: "warp-composite",
+        inputs: ["text-texture", "render.density", "canvas.size"],
+        invalidatedBy: ["text-texture", "render.density", "canvas.size"],
+        kind: "composite",
+        output: "preview",
+        quality: "retina",
+        runsOn: "main",
+      },
+      {
+        cacheKey: ["warp-composite", "render.mode", "canvas.renderScale"],
+        id: "optical-composite",
+        inputs: ["warp-composite", "render.mode", "canvas.renderScale"],
+        invalidatedBy: ["warp-composite", "render.mode", "canvas.renderScale"],
+        kind: "composite",
+        output: "preview",
+        quality: "retina",
+        runsOn: "main",
+      },
+    ],
+  } as const;
+}
+
+export function createPixelRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "control-drag",
+        invalidates: ["pixel-transform"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "control-change",
+        invalidates: ["pixel-transform"],
+        targets: ["render.mode"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["pixel-transform"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["render.density", "render.mode", "canvas.size", "canvas.renderScale"],
+        id: "pixel-transform",
+        inputs: ["render.density", "render.mode", "canvas.size", "canvas.renderScale"],
+        invalidatedBy: ["render.density", "render.mode", "canvas.size", "canvas.renderScale"],
+        kind: "pixel-transform",
+        output: "preview",
+        quality: "retina",
+        runsOn: "worker",
+      },
+    ],
+  } as const;
+}
+
+export function createMediaRendererPipeline() {
+  return {
+    interactionInvalidation: [
+      {
+        interaction: "media-import",
+        invalidates: ["source-decode", "media-preprocess"],
+        targets: ["source.image"],
+      },
+      {
+        interaction: "control-drag",
+        invalidates: ["effect-composite"],
+        mustNotInvalidate: ["source-decode", "media-preprocess"],
+        targets: ["render.density"],
+      },
+      {
+        interaction: "viewport-zoom",
+        invalidates: [],
+        mustNotInvalidate: ["source-decode", "media-preprocess", "effect-composite"],
+        targets: ["canvas.viewport"],
+      },
+    ],
+    passes: [
+      {
+        cacheKey: ["source.image.id", "source.image.width", "source.image.height"],
+        id: "source-decode",
+        inputs: ["source.image"],
+        invalidatedBy: ["source.image"],
+        kind: "decode",
+        output: "source",
+        quality: "full",
+        runsOn: "worker",
+      },
+      {
+        cacheKey: ["source-decode", "source.image.id"],
+        id: "media-preprocess",
+        inputs: ["source-decode"],
+        invalidatedBy: ["source-decode"],
+        kind: "preprocess",
+        output: "intermediate",
+        quality: "full",
+        runsOn: "worker-or-gpu",
+      },
+      {
+        cacheKey: ["media-preprocess", "render.density"],
+        id: "effect-composite",
+        inputs: ["media-preprocess", "render.density"],
+        invalidatedBy: ["media-preprocess", "render.density"],
+        kind: "composite",
+        output: "preview",
+        quality: "retina",
+        runsOn: "gpu",
+      },
+    ],
+  } as const;
+}

package/templates/runtime/testing/performance-test-fixtures/scenarios.ts

@@ -0,0 +1,172 @@
+import { defineToolcraftPerformance } from "../performance";
+import {
+  createAnimatedVectorRendererPipeline,
+  createTextRendererPipeline,
+} from "./renderer-pipelines";
+import {
+  createCombinedRendererStressFixture,
+  createCustomStressFixture,
+  createLargeTextStressFixture,
+  createSchemaMaxValueStressFixture,
+} from "./stress-fixtures";
+import { testSchema } from "./schemas";
+
+export function createViewportZoomStressScenario() {
+  return {
+    automated: true,
+    automatedTestName: "perf: detailed canvas zoom stays smooth",
+    browser: true,
+    browserTestName: "browser perf: detailed canvas zoom stays smooth",
+    budget: { maxFrameGapMs: 80, maxInteractionMs: 500, maxLongTaskMs: 80 },
+    expectedObservable:
+      "Zooming detailed product output does not shake the canvas or block frames.",
+    fixture: "detailed renderer zoom fixture",
+    id: "viewport-zoom-stress",
+    interaction: "viewport-zoom-stress" as const,
+    stress: true,
+    stressFixture: createCombinedRendererStressFixture(),
+    target: "canvas.viewport",
+    workload: false,
+  };
+}
+
+export function createTextRendererScenarios(
+  options: { includeStressPreview?: boolean; includeViewportZoomStress?: boolean } = {},
+) {
+  const includeStressPreview = options.includeStressPreview ?? true;
+  const includeViewportZoomStress = options.includeViewportZoomStress ?? true;
+
+  return [
+    {
+      automated: true,
+      automatedTestName: "perf: text preview render stays under budget",
+      browser: true,
+      browserTestName: "browser perf: text preview render stays under budget",
+      budget: { maxLongTaskMs: 80, maxPreviewMs: 1000 },
+      expectedObservable: "Text preview renders crisply without freezing.",
+      fixture: "native-resolution glyph output fixture",
+      id: "text-preview-render",
+      interaction: "preview-render" as const,
+      stress: includeStressPreview,
+      ...(includeStressPreview
+        ? { stressFixture: createCombinedRendererStressFixture() }
+        : {}),
+      workload: false,
+    },
+    {
+      automated: true,
+      automatedTestName: "perf: density drag stays responsive",
+      browser: true,
+      browserTestName: "browser perf: density drag stays responsive",
+      budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+      controlLabel: "Density",
+      expectedObservable: "Dragging Density updates text output without blocking the UI.",
+      fixture: "runtime density fixture",
+      id: "density-drag",
+      interaction: "control-drag" as const,
+      stressFixture: createSchemaMaxValueStressFixture(
+        testSchema,
+        "render.density",
+        "Density max is the heaviest glyph output fixture.",
+      ),
+      target: "render.density",
+      workloadFixture: createLargeTextStressFixture(),
+      workload: true,
+    },
+    {
+      automated: true,
+      automatedTestName: "perf: mode change stays responsive",
+      browser: true,
+      browserTestName: "browser perf: mode change stays responsive",
+      budget: { maxFrameGapMs: 80, maxInteractionMs: 500 },
+      controlLabel: "Mode",
+      expectedObservable: "Changing Mode updates text output without blocking the UI.",
+      fixture: "runtime mode fixture",
+      id: "mode-change",
+      interaction: "control-change" as const,
+      target: "render.mode",
+      values: { default: "soft", max: "sharp", min: "soft" },
+      workload: false,
+    },
+    {
+      automated: true,
+      automatedTestName: "perf: viewport stays stable",
+      browser: true,
+      browserTestName: "browser perf: viewport stays stable",
+      budget: { maxFrameGapMs: 80 },
+      expectedObservable: "Viewport remains stable.",
+      fixture: "native-resolution glyph output fixture",
+      id: "viewport-stability",
+      interaction: "viewport-stability" as const,
+      workload: false,
+    },
+    ...(includeViewportZoomStress ? [createViewportZoomStressScenario()] : []),
+  ];
+}
+
+export function createAnimationFrameScenario() {
+  return {
+    automated: true,
+    automatedTestName: "perf: animation frame loop stays smooth",
+    browser: true,
+    browserTestName: "browser perf: animation frame loop stays smooth",
+    budget: { maxFrameGapMs: 80, maxLongTaskMs: 80 },
+    expectedObservable: "Animated renderer advances without long frame gaps.",
+    fixture: "animated renderer fixture",
+    id: "animation-frame-loop",
+    interaction: "animation-frame" as const,
+    stress: true,
+    stressFixture: createCustomStressFixture(
+      { animation: "fastest", density: 12 },
+      "Animation stress must sample the heaviest animated output.",
+    ),
+    workload: false,
+  };
+}
+
+export function createAnimationViewportDragScenario() {
+  return {
+    automated: true,
+    automatedTestName: "perf: animated canvas drag stays smooth",
+    browser: true,
+    browserTestName: "browser perf: animated canvas drag stays smooth",
+    budget: { maxFrameGapMs: 80, maxInteractionMs: 500, maxLongTaskMs: 80 },
+    expectedObservable: "Animated renderer stays smooth while the canvas viewport is dragged.",
+    fixture: "animated renderer canvas drag fixture",
+    id: "animation-viewport-drag",
+    interaction: "animation-viewport-drag" as const,
+    stress: true,
+    stressFixture: createCustomStressFixture(
+      { animation: "fastest", density: 12 },
+      "Animated viewport drag must run while the heaviest animated output is visible.",
+    ),
+    target: "canvas.viewport",
+    workload: false,
+  };
+}
+
+export function createAnimatedVectorRendererConfig(options: { includeViewportDrag: boolean }) {
+  return defineToolcraftPerformance({
+    rendererStrategy: "svg",
+    rendererTechnique: {
+      exportRenderer: "svg",
+      fidelityRisks: ["animated vector output must stay crisp while panning"],
+      performanceRisks: ["dense vector animation can jank while the viewport moves"],
+      previewRenderer: "svg",
+      productRepresentation: "vector",
+      rendererStrategy: "svg",
+      rendererWorkload: "vector-output",
+      sourceRepresentation: "procedural-data",
+      whyNotAlternativeStrategies: ["svg preserves semantic vector output for this fixture"],
+    },
+    rendererWorkload: "vector-output",
+    rendererPipeline: createAnimatedVectorRendererPipeline(),
+    scenarios: [
+      ...createTextRendererScenarios(),
+      createAnimationFrameScenario(),
+      ...(options.includeViewportDrag ? [createAnimationViewportDragScenario()] : []),
+    ],
+    usesCustomRenderer: true,
+    workloadTargets: ["render.density"],
+  });
+}