@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/testing/performance-scenario-common-validation.ts

@@ -0,0 +1,101 @@
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import { getToolcraftPerformanceProfile } from "../performance/profile-catalog";
+import { requiresConcreteUiTarget } from "./performance-scenario-validation";
+import { hasOutputDeliveryActionReference } from "./performance-schema-queries";
+import type { ToolcraftPerformanceScenario } from "./performance-types";
+
+export function hasToolcraftBrowserTestName(
+  scenario: ToolcraftPerformanceScenario,
+): boolean {
+  return scenario.browser && scenario.browserTestName.trim().length > 0;
+}
+
+export function getToolcraftPerformanceScenarioBaseErrors(
+  scenario: ToolcraftPerformanceScenario,
+): string[] {
+  const errors: string[] = [];
+
+  if (!scenario.id.trim()) {
+    errors.push("Performance scenario is missing an id.");
+  }
+  if (!scenario.fixture.trim()) {
+    errors.push(`${scenario.id} must name a representative fixture.`);
+  }
+  if (!scenario.expectedObservable.trim()) {
+    errors.push(`${scenario.id} must describe a product-level performance observable.`);
+  }
+  if (!scenario.automated || !scenario.automatedTestName.trim()) {
+    errors.push(`${scenario.id} must point to an automated performance test.`);
+  }
+  if (!hasToolcraftBrowserTestName(scenario)) {
+    errors.push(`${scenario.id} must point to a browser performance test.`);
+  }
+  return errors;
+}
+
+export function getToolcraftPerformanceScenarioInteractionErrors(
+  schema: ResolvedToolcraftAppSchema,
+  scenario: ToolcraftPerformanceScenario,
+): string[] {
+  const errors: string[] = [];
+
+  if (
+    requiresConcreteUiTarget(scenario.interaction) &&
+    !scenario.controlLabel?.trim() &&
+    !scenario.uiSelector?.trim() &&
+    !(scenario.interaction === "export" && scenario.actionValue?.trim())
+  ) {
+    errors.push(
+      `${scenario.id} ${scenario.interaction} scenario must declare controlLabel or uiSelector for its real browser interaction.`,
+    );
+  }
+
+  if (scenario.interaction !== "export") return errors;
+
+  if (!scenario.actionValue?.trim()) {
+    errors.push(
+      `${scenario.id} export scenario must declare actionValue for the exact output delivery action it exercises.`,
+    );
+  } else if (!scenario.controlLabel?.trim()) {
+    errors.push(
+      `${scenario.id} export scenario must declare controlLabel for the visible output delivery action it clicks.`,
+    );
+  } else if (
+    scenario.completionEvidence !== "download" &&
+    scenario.completionEvidence !== "clipboard"
+  ) {
+    errors.push(
+      `${scenario.id} export scenario must declare completionEvidence as download or clipboard.`,
+    );
+  } else if (!hasOutputDeliveryActionReference(schema, scenario)) {
+    errors.push(
+      `${scenario.id} export scenario references actionValue "${scenario.actionValue.trim()}" with label "${scenario.controlLabel.trim()}", but schema panelActions has no matching output delivery action.`,
+    );
+  }
+
+  const centralDeadline = getToolcraftPerformanceProfile("batch-responsive")
+    .thresholds.maxBatchCompletionMs;
+  if (
+    scenario.completionDeadlineMs !== undefined &&
+    (!Number.isFinite(scenario.completionDeadlineMs) ||
+      scenario.completionDeadlineMs <= 0 ||
+      centralDeadline === undefined ||
+      scenario.completionDeadlineMs > centralDeadline)
+  ) {
+    errors.push(
+      `${scenario.id} completionDeadlineMs must be a positive deadline no greater than the central batch profile deadline ${centralDeadline}ms.`,
+    );
+  }
+
+  return errors;
+}
+
+export function getToolcraftPerformanceScenarioCommonErrors(
+  schema: ResolvedToolcraftAppSchema,
+  scenario: ToolcraftPerformanceScenario,
+): string[] {
+  return [
+    ...getToolcraftPerformanceScenarioBaseErrors(scenario),
+    ...getToolcraftPerformanceScenarioInteractionErrors(schema, scenario),
+  ];
+}

package/templates/runtime/testing/performance-scenario-validation.ts

@@ -1,47 +1,10 @@
-import type { ToolcraftControlSchema } from "../schema/types";
-import type {
-  ToolcraftPerformanceInteraction,
-  ToolcraftPerformanceScenario,
-} from "./performance-types";
+import type { ToolcraftPipelineInteraction } from "./performance-types";
 
-export function hasMinDefaultMax(values: ToolcraftPerformanceScenario["values"]): boolean {
-  return values !== undefined && "default" in values && "min" in values && "max" in values;
-}
-
-export function getSliderDragControlType(
-  control: ToolcraftControlSchema | undefined,
-): "rangeSlider" | "slider" | null {
-  if (control?.type === "slider" || control?.type === "rangeSlider") {
-    return control.type;
-  }
-
-  return null;
-}
-
-export function hasControlDragScenario(scenarios: readonly ToolcraftPerformanceScenario[]): boolean {
-  return scenarios.some((scenario) => scenario.interaction === "control-drag");
-}
-
-export function isWorkloadCoverageInteraction(
-  interaction: ToolcraftPerformanceInteraction,
-  requiresControlDrag: boolean,
-): boolean {
-  if (requiresControlDrag) {
-    return interaction === "control-drag";
-  }
-
-  return (
-    interaction === "control-change" ||
-    interaction === "control-drag" ||
-    interaction === "export-copy"
-  );
-}
-
-export function requiresConcreteUiTarget(interaction: ToolcraftPerformanceInteraction): boolean {
+export function requiresConcreteUiTarget(interaction: ToolcraftPipelineInteraction): boolean {
   return (
     interaction === "control-change" ||
     interaction === "control-drag" ||
-    interaction === "export-copy" ||
+    interaction === "export" ||
     interaction === "mask-drag" ||
     interaction === "timeline-playback" ||
     interaction === "timeline-scrub"

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

@@ -58,7 +58,9 @@ export function getToolcraftControlPerformanceValues(
   }
 
   if (
-    (control.type === "select" || control.type === "segmented") &&
+    (control.type === "select" ||
+      control.type === "segmented" ||
+      control.type === "tabs") &&
     control.options &&
     control.options.length > 0
   ) {

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

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

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

@@ -1,17 +1,3 @@
-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: [

package/templates/runtime/testing/performance-types.ts

@@ -1,18 +1,38 @@
 import type { ToolcraftControlSchema } from "../schema/types";
-
-export type ToolcraftPerformanceInteraction =
-  | "animation-frame"
-  | "animation-viewport-drag"
-  | "control-change"
-  | "control-drag"
-  | "export-copy"
-  | "mask-drag"
-  | "media-import"
-  | "preview-render"
-  | "timeline-playback"
-  | "timeline-scrub"
-  | "viewport-zoom-stress"
-  | "viewport-stability";
+import type {
+  AnyToolcraftRendererPipelineRegistration,
+  ToolcraftPipelineInteraction,
+  ToolcraftRendererPipeline,
+} from "../rendering/renderer-pipeline-registration";
+import type { ToolcraftPerformanceFixtureAdapterRegistry } from "./performance-fixture-adapter-types";
+import type {
+  ToolcraftRenderPassCost,
+  ToolcraftRenderPassLifecycle,
+  ToolcraftWorkloadEnvelope,
+} from "./performance-workload-types";
+
+export type {
+  AnyToolcraftRendererPipelineRegistration,
+  ToolcraftInteractionInvalidation,
+  ToolcraftPipelineInteraction,
+  ToolcraftRenderPass,
+  ToolcraftRenderPassKind,
+  ToolcraftRenderPassOutput,
+  ToolcraftRenderPassQuality,
+  ToolcraftRenderPassRunLocation,
+  ToolcraftRendererPipeline,
+} from "../rendering/renderer-pipeline-registration";
+
+export type {
+  ToolcraftPerformanceContinuousFixtureAdapter,
+  ToolcraftPerformanceDiscreteAppliedValue,
+  ToolcraftPerformanceDiscreteFixtureAdapter,
+  ToolcraftPerformanceDiscreteFixtureDomain,
+  ToolcraftPerformanceDiscreteFixtureEntry,
+  ToolcraftPerformanceFixtureAdapter,
+  ToolcraftPerformanceFixtureAdapterRegistry,
+  ToolcraftPerformanceFixtureInverseCheckpoint,
+} from "./performance-fixture-adapter-types";
 
 export type ToolcraftOutputCompletionEvidence = "clipboard" | "download";
 
@@ -23,123 +43,95 @@ export type ToolcraftPerformanceCoverage = {
   browserTestName: string;
 };
 
-export type ToolcraftBrowserCheckPreferredRunner = "agent-browser";
-
-export type ToolcraftBrowserCheckFallbackRunner = "playwright";
-
-export type ToolcraftBrowserCheckFallbackCondition =
-  | "agent-browser-unavailable"
-  | "ci";
-
-export type ToolcraftBrowserCheckPolicy = {
-  fallbackRunner: ToolcraftBrowserCheckFallbackRunner;
-  fallbackWhen: readonly ToolcraftBrowserCheckFallbackCondition[];
-  preferredRunner: ToolcraftBrowserCheckPreferredRunner;
-};
-
-export type ToolcraftPerformanceBudget = {
-  maxExportMs?: number;
-  maxFrameGapMs?: number;
-  maxInteractionMs?: number;
-  maxLongTaskMs?: number;
-  maxPreviewMs?: number;
-  maxRenderMs?: number;
-};
-
 export type ToolcraftPerformanceValueSet = {
   default: unknown;
   max?: unknown;
   min?: unknown;
 };
 
-export type ToolcraftPerformanceFixtureKind =
-  | "custom"
-  | "high-density"
-  | "large-canvas"
-  | "large-text"
-  | "many-items"
-  | "max-value"
-  | "media";
-
-export type ToolcraftPerformanceLoadMetric =
-  | "canvas-area"
-  | "count"
-  | "custom"
-  | "media-area"
-  | "numeric-max"
-  | "numeric-min"
-  | "text-length";
-
-export type ToolcraftPerformanceUserFacingRange =
-  | "experimental-above-smooth"
-  | "fully-guaranteed";
-
-export type ToolcraftPerformanceLoadEvidence = {
-  attemptedRatio: number;
-  attemptedTarget: unknown;
-  decision: string;
-  measuredResult: string;
-  optimizationAttempted?: string;
-  result: "failed" | "passed";
-  scenarioId: string;
-  target: string;
-};
+export type ToolcraftPerformanceCompiledFixtureCheckpointKind =
+  | "development"
+  | "interactive-max"
+  | "batch-max";
 
-export type ToolcraftPerformanceLoadProfile = {
-  degradationStepPercent?: 10;
-  evidence?: readonly ToolcraftPerformanceLoadEvidence[];
-  hardLimit: unknown;
-  metric: ToolcraftPerformanceLoadMetric;
-  smoothTarget: unknown;
-  smoothTargetRatio: number;
-  target: string;
-  userFacingRange: ToolcraftPerformanceUserFacingRange;
+export type ToolcraftPerformanceCompiledFixtureCheckpoint = {
+  kind: ToolcraftPerformanceCompiledFixtureCheckpointKind;
+  normalizedPressure: number;
+  values: Readonly<Record<string, number>>;
 };
 
-export type ToolcraftPerformanceFixture = {
-  kind: ToolcraftPerformanceFixtureKind;
-  loadProfile?: ToolcraftPerformanceLoadProfile;
-  minChars?: number;
-  minCount?: number;
-  minLines?: number;
-  reason: string;
-  value?: unknown;
+export type ToolcraftPerformanceCompiledDevelopment =
+  | {
+      checkpoint: ToolcraftPerformanceCompiledFixtureCheckpoint & {
+        kind: "development";
+      };
+      status: "available";
+    }
+  | {
+      reason: string;
+      status: "unavailable";
+    };
+
+type ToolcraftPerformanceCompiledFixturePlanBase = {
+  development: ToolcraftPerformanceCompiledDevelopment;
+  dimensionIds: readonly string[];
+  pathId: string;
 };
 
-export type ToolcraftPerformanceStressFixtureKind = ToolcraftPerformanceFixtureKind;
-export type ToolcraftPerformanceStressFixture = ToolcraftPerformanceFixture;
-export type ToolcraftPerformanceWorkloadFixture = ToolcraftPerformanceFixture;
+export type ToolcraftPerformanceCompiledInteractiveFixturePlan =
+  ToolcraftPerformanceCompiledFixturePlanBase & {
+    kind: "interactive";
+    maximum: ToolcraftPerformanceCompiledFixtureCheckpoint & {
+      kind: "interactive-max";
+    };
+  };
+
+export type ToolcraftPerformanceCompiledBatchFixturePlan =
+  ToolcraftPerformanceCompiledFixturePlanBase & {
+    kind: "batch";
+    maximum: ToolcraftPerformanceCompiledFixtureCheckpoint & {
+      kind: "batch-max";
+    };
+  };
+
+export type ToolcraftPerformanceCompiledFixturePlan =
+  | ToolcraftPerformanceCompiledInteractiveFixturePlan
+  | ToolcraftPerformanceCompiledBatchFixturePlan;
+
+export type ToolcraftPerformanceExecutedFixtureCheckpoint =
+  ToolcraftPerformanceCompiledFixtureCheckpoint & {
+    applied: Readonly<Record<string, unknown>>;
+    observed: Readonly<Record<string, number>>;
+  };
 
 type ToolcraftPerformanceScenarioBase = ToolcraftPerformanceCoverage & {
-  budget: ToolcraftPerformanceBudget;
   controlLabel?: string;
+  coversTargets: readonly string[];
   expectedObservable: string;
   fixture: string;
   id: string;
+  pathId: string;
   target?: string;
-  stress?: boolean;
-  stressFixture?: ToolcraftPerformanceStressFixture;
-  workloadFixture?: ToolcraftPerformanceWorkloadFixture;
   uiSelector?: string;
-  values?: ToolcraftPerformanceValueSet;
-  workload: boolean;
 };
 
-type ToolcraftExportCopyPerformanceScenario = ToolcraftPerformanceScenarioBase & {
+type ToolcraftExportPerformanceScenario = ToolcraftPerformanceScenarioBase & {
   actionValue: string;
   completionEvidence: ToolcraftOutputCompletionEvidence;
+  completionDeadlineMs?: number;
   controlLabel: string;
-  interaction: "export-copy";
+  interaction: "export";
 };
 
 type ToolcraftNonExportPerformanceScenario = ToolcraftPerformanceScenarioBase & {
   actionValue?: never;
   completionEvidence?: never;
-  interaction: Exclude<ToolcraftPerformanceInteraction, "export-copy">;
+  completionDeadlineMs?: never;
+  interaction: Exclude<ToolcraftPipelineInteraction, "export">;
 };
 
 export type ToolcraftPerformanceScenario =
-  | ToolcraftExportCopyPerformanceScenario
+  | ToolcraftExportPerformanceScenario
   | ToolcraftNonExportPerformanceScenario;
 
 export type ToolcraftRendererStrategy =
@@ -150,12 +142,12 @@ export type ToolcraftRendererStrategy =
   | "webgl"
   | "webgpu";
 
-export type ToolcraftRendererWorkload =
-  | "none"
-  | "simple-composition"
-  | "text-output"
-  | "vector-output"
-  | "pixel-output";
+export type ToolcraftKernelBenchmarkDecision = {
+  candidates: readonly ToolcraftRendererStrategy[];
+  decision: string;
+  id: string;
+  selected: ToolcraftRendererStrategy;
+};
 
 export type ToolcraftSourceRepresentation =
   | "reference-runtime"
@@ -227,104 +219,58 @@ export type ToolcraftRendererLayer = {
   uiSelector?: string;
 };
 
-export type ToolcraftRendererMeasuredAlternativeEvidence = {
-  alternativeStrategy: "webgl" | "webgpu";
-  decision: string;
-  fixture: string;
-  measuredResult: string;
-  scenarioId: string;
-};
-
 export type ToolcraftRendererTechnique = {
   exportRenderer: ToolcraftExportRenderer;
   fidelityRisks: readonly string[];
   intentionalRasterizationReason?: string;
   layers?: readonly ToolcraftRendererLayer[];
-  measuredAlternativeEvidence?: readonly ToolcraftRendererMeasuredAlternativeEvidence[];
   performanceRisks: readonly string[];
   previewExportDifferenceReason?: string;
   previewRenderer: ToolcraftPreviewRenderer;
   productRepresentation: ToolcraftProductRepresentation;
   referenceRendererChangeReason?: string;
   rendererStrategy: ToolcraftRendererStrategy;
-  rendererWorkload: ToolcraftRendererWorkload;
   sourceRepresentation: ToolcraftSourceRepresentation;
   whyNotAlternativeStrategies: readonly string[];
 };
 
-export type ToolcraftRenderPassKind =
-  | "decode"
-  | "preprocess"
-  | "pixel-transform"
-  | "vector-build"
-  | "text-layout"
-  | "rasterize"
-  | "composite"
-  | "handles"
-  | "export";
-
-export type ToolcraftRenderPassRunLocation =
-  | "main"
-  | "worker"
-  | "gpu"
-  | "worker-or-gpu"
-  | "export-only";
-
-export type ToolcraftRenderPassOutput =
-  | "source"
-  | "intermediate"
-  | "preview"
-  | "overlay"
-  | "export";
-
-export type ToolcraftRenderPassQuality = "preview" | "full" | "retina" | "export";
-
-export type ToolcraftRenderPass = {
-  cacheKey?: readonly string[];
-  id: string;
-  inputs: readonly string[];
-  invalidatedBy: readonly string[];
-  kind: ToolcraftRenderPassKind;
-  output: ToolcraftRenderPassOutput;
-  quality: ToolcraftRenderPassQuality;
-  runsOn: ToolcraftRenderPassRunLocation;
-};
-
-export type ToolcraftPipelineInteraction =
-  | "animation-frame"
-  | "control-change"
-  | "control-drag"
-  | "media-import"
-  | "mask-drag"
-  | "viewport-drag"
-  | "viewport-zoom"
-  | "timeline-playback"
-  | "timeline-scrub"
-  | "export";
-
-export type ToolcraftInteractionInvalidation = {
-  interaction: ToolcraftPipelineInteraction;
-  invalidates: readonly string[];
-  mustNotInvalidate?: readonly string[];
-  targets: readonly string[];
-};
-
-export type ToolcraftRendererPipeline = {
-  interactionInvalidation: readonly ToolcraftInteractionInvalidation[];
-  passes: readonly ToolcraftRenderPass[];
-};
-
-export type ToolcraftPerformanceConfig = {
-  browserCheckPolicy?: ToolcraftBrowserCheckPolicy;
-  rendererPipeline?: ToolcraftRendererPipeline;
+export type ToolcraftPerformanceConfigBase = {
+  /** Product-owned numeric normalization adapters for non-numeric dimensions. */
+  fixtureAdapters?: ToolcraftPerformanceFixtureAdapterRegistry;
+  /** Pass-keyed decisions backed by protected current-source kernel receipts. */
+  kernelBenchmarkDecisions?: readonly ToolcraftKernelBenchmarkDecision[];
+  rendererPipeline?: ToolcraftRendererPipeline | AnyToolcraftRendererPipelineRegistration;
   rendererStrategy: ToolcraftRendererStrategy;
   rendererTechnique?: ToolcraftRendererTechnique;
-  rendererWorkload: ToolcraftRendererWorkload;
   scenarios: readonly ToolcraftPerformanceScenario[];
   usesCustomRenderer: boolean;
-  workloadTargets: readonly string[];
+  workloadEnvelope: ToolcraftWorkloadEnvelope;
 };
 
+export type ToolcraftPerformanceConfig = ToolcraftPerformanceConfigBase;
+export type ToolcraftEnvelopePerformanceConfig = ToolcraftPerformanceConfig;
+
+export function isToolcraftEnvelopePerformanceConfig(
+  config: unknown,
+): config is ToolcraftEnvelopePerformanceConfig {
+  if (
+    typeof config !== "object" ||
+    config === null ||
+    !Object.prototype.hasOwnProperty.call(config, "workloadEnvelope")
+  ) {
+    return false;
+  }
+
+  const envelope = (config as { workloadEnvelope?: unknown }).workloadEnvelope;
+
+  return (
+    typeof envelope === "object" &&
+    envelope !== null &&
+    !Array.isArray(envelope) &&
+    Array.isArray((envelope as { dimensions?: unknown }).dimensions)
+  );
+}
+
 export type ToolcraftPerformanceSensitiveControl = {
   control: ToolcraftControlSchema;
   controlId: string;