@pixel-point/toolcraft 0.0.9 → 0.0.11

package/templates/runtime/testing/performance.ts

@@ -2,6 +2,7 @@ import type {
   ToolcraftControlSchema,
   ResolvedToolcraftAppSchema,
 } from "../schema/types";
+import { isToolcraftRuntimeOwnedTarget } from "../schema/runtime-targets";
 
 export type ToolcraftPerformanceInteraction =
   | "animation-frame"
@@ -24,6 +25,20 @@ 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;
@@ -48,8 +63,42 @@ export type ToolcraftPerformanceFixtureKind =
   | "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 = {
+  attemptedTarget: unknown;
+  decision: string;
+  measuredResult: string;
+  optimizationAttempted?: string;
+  result: "failed" | "passed";
+  scenarioId: string;
+};
+
+export type ToolcraftPerformanceLoadProfile = {
+  degradationStepPercent?: 10;
+  evidence?: readonly ToolcraftPerformanceLoadEvidence[];
+  hardLimit: unknown;
+  metric: ToolcraftPerformanceLoadMetric;
+  smoothTarget: unknown;
+  smoothTargetRatio: number;
+  target: string;
+  userFacingRange: ToolcraftPerformanceUserFacingRange;
+};
+
 export type ToolcraftPerformanceFixture = {
   kind: ToolcraftPerformanceFixtureKind;
+  loadProfile?: ToolcraftPerformanceLoadProfile;
   minChars?: number;
   minCount?: number;
   minLines?: number;
@@ -162,11 +211,20 @@ 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;
@@ -241,6 +299,7 @@ export type ToolcraftRendererPipeline = {
 };
 
 export type ToolcraftPerformanceConfig = {
+  browserCheckPolicy?: ToolcraftBrowserCheckPolicy;
   rendererPipeline?: ToolcraftRendererPipeline;
   rendererStrategy: ToolcraftRendererStrategy;
   rendererTechnique?: ToolcraftRendererTechnique;
@@ -271,10 +330,25 @@ const maxPerformanceBudgetCaps: Required<ToolcraftPerformanceBudget> = {
   maxRenderMs: 2000,
 };
 
+export const defaultToolcraftBrowserCheckPolicy: ToolcraftBrowserCheckPolicy = {
+  fallbackRunner: "playwright",
+  fallbackWhen: ["agent-browser-unavailable", "ci"],
+  preferredRunner: "agent-browser",
+};
+
 export function defineToolcraftPerformance(
   config: ToolcraftPerformanceConfig,
-): ToolcraftPerformanceConfig {
-  return config;
+): ToolcraftPerformanceConfig & { browserCheckPolicy: ToolcraftBrowserCheckPolicy } {
+  return {
+    ...config,
+    browserCheckPolicy: {
+      ...defaultToolcraftBrowserCheckPolicy,
+      ...config.browserCheckPolicy,
+      fallbackWhen:
+        config.browserCheckPolicy?.fallbackWhen ??
+        defaultToolcraftBrowserCheckPolicy.fallbackWhen,
+    },
+  };
 }
 
 const workloadControlPattern =
@@ -297,6 +371,42 @@ const performanceFixtureKinds = new Set<ToolcraftPerformanceFixtureKind>([
   "media",
 ]);
 
+const performanceLoadMetrics = new Set<ToolcraftPerformanceLoadMetric>([
+  "canvas-area",
+  "count",
+  "custom",
+  "media-area",
+  "numeric-max",
+  "numeric-min",
+  "text-length",
+]);
+
+const performanceUserFacingRanges = new Set<ToolcraftPerformanceUserFacingRange>([
+  "experimental-above-smooth",
+  "fully-guaranteed",
+]);
+
+const browserCheckPreferredRunners = new Set<ToolcraftBrowserCheckPreferredRunner>([
+  "agent-browser",
+]);
+
+const browserCheckFallbackRunners = new Set<ToolcraftBrowserCheckFallbackRunner>([
+  "playwright",
+]);
+
+const browserCheckFallbackConditions = new Set<ToolcraftBrowserCheckFallbackCondition>([
+  "agent-browser-unavailable",
+  "ci",
+]);
+
+const loadProfileRequiredFixtureKinds = new Set<ToolcraftPerformanceFixtureKind>([
+  "high-density",
+  "large-canvas",
+  "many-items",
+  "max-value",
+  "media",
+]);
+
 const renderPassKinds = new Set<ToolcraftRenderPassKind>([
   "decode",
   "preprocess",
@@ -401,7 +511,10 @@ export function collectToolcraftPerformanceSensitiveControls(
 ): ToolcraftPerformanceSensitiveControl[] {
   return (schema.panels.controls?.sections ?? []).flatMap((section) =>
     Object.entries(section.controls)
-      .filter(([, control]) => isPotentialWorkloadControl(control))
+      .filter(
+        ([, control]) =>
+          !isToolcraftRuntimeOwnedTarget(control.target) && isPotentialWorkloadControl(control),
+      )
       .map(([controlId, control]) => ({
         control,
         controlId,
@@ -417,6 +530,7 @@ function collectToolcraftPerformanceRoleConflicts(
     Object.entries(section.controls)
       .filter(
         ([, control]) =>
+          !isToolcraftRuntimeOwnedTarget(control.target) &&
           control.performanceRole === "responsiveness" &&
           isSemanticallyWorkloadControl(control),
       )
@@ -436,6 +550,8 @@ export function collectToolcraftUnclassifiedPerformanceControls(
       .filter(
         ([, control]) =>
           control.type !== "panelActions" &&
+          control.type !== "settingsTransfer" &&
+          !isToolcraftRuntimeOwnedTarget(control.target) &&
           control.performanceRole !== "workload" &&
           control.performanceRole !== "responsiveness",
       )
@@ -455,6 +571,67 @@ function hasMinDefaultMax(values: ToolcraftPerformanceScenario["values"]): boole
   return values !== undefined && "default" in values && "min" in values && "max" in values;
 }
 
+function getBrowserCheckPolicyErrors(config: ToolcraftPerformanceConfig): string[] {
+  const errors: string[] = [];
+  const policy = config.browserCheckPolicy ?? defaultToolcraftBrowserCheckPolicy;
+  const fallbackWhen = policy.fallbackWhen as unknown;
+
+  if (
+    !browserCheckPreferredRunners.has(
+      policy.preferredRunner as ToolcraftBrowserCheckPreferredRunner,
+    )
+  ) {
+    errors.push(
+      'browserCheckPolicy.preferredRunner must be "agent-browser" so AI agents use their controlled browser before fallback automation.',
+    );
+  }
+
+  if (
+    !browserCheckFallbackRunners.has(
+      policy.fallbackRunner as ToolcraftBrowserCheckFallbackRunner,
+    )
+  ) {
+    errors.push(
+      'browserCheckPolicy.fallbackRunner must be "playwright" so generated apps keep a portable CI/non-agent fallback.',
+    );
+  }
+
+  if (!Array.isArray(fallbackWhen)) {
+    errors.push(
+      'browserCheckPolicy.fallbackWhen must include "agent-browser-unavailable" and "ci".',
+    );
+    return errors;
+  }
+
+  for (const condition of fallbackWhen) {
+    if (
+      !browserCheckFallbackConditions.has(
+        condition as ToolcraftBrowserCheckFallbackCondition,
+      )
+    ) {
+      errors.push(
+        `browserCheckPolicy.fallbackWhen contains unsupported condition "${String(
+          condition,
+        )}".`,
+      );
+    }
+  }
+
+  if (!fallbackWhen.includes("agent-browser-unavailable")) {
+    errors.push(
+      'browserCheckPolicy.fallbackWhen must include "agent-browser-unavailable" so Playwright is only used when no agent browser exists.',
+    );
+  }
+
+  if (!fallbackWhen.includes("ci")) {
+    errors.push(
+      'browserCheckPolicy.fallbackWhen must include "ci" so CI/non-agent automation has a portable performance runner.',
+    );
+  }
+
+  return errors;
+}
+
 function getSliderDragControlType(
   control: ToolcraftControlSchema | undefined,
 ): "rangeSlider" | "slider" | null {
@@ -504,6 +681,503 @@ function getTextLineCount(value: string): number {
   return value.split(/\r\n|\r|\n/).length;
 }
 
+function getPerformanceFixtureLargeTextValueErrors(
+  scenarioId: string,
+  valueLabel: string,
+  value: unknown,
+  options: {
+    minChars?: number;
+    minLines?: number;
+  } = {},
+): string[] {
+  const errors: string[] = [];
+
+  if (typeof value !== "string") {
+    errors.push(`${scenarioId} ${valueLabel} must be a string.`);
+    return errors;
+  }
+
+  const minChars = options.minChars ?? largeTextStressMinChars;
+  const minLines = options.minLines ?? largeTextStressMinLines;
+
+  if (minChars < largeTextStressMinChars) {
+    errors.push(`${scenarioId} ${valueLabel}.minChars must be >= ${largeTextStressMinChars}.`);
+  }
+
+  if (minLines < largeTextStressMinLines) {
+    errors.push(`${scenarioId} ${valueLabel}.minLines must be >= ${largeTextStressMinLines}.`);
+  }
+
+  if (value.length < minChars) {
+    errors.push(`${scenarioId} ${valueLabel} must contain at least ${minChars} characters.`);
+  }
+
+  if (getTextLineCount(value) < minLines) {
+    errors.push(`${scenarioId} ${valueLabel} must contain at least ${minLines} lines.`);
+  }
+
+  return errors;
+}
+
+function getLastFixturePathSegment(path: string): string {
+  return path.split(/[._-]/).filter(Boolean).at(-1) ?? path;
+}
+
+function isCustomLargeTextFixturePath(path: string): boolean {
+  return /^(?:content|text|prompt|code|script|shader|template|json|css)$/i.test(
+    getLastFixturePathSegment(path),
+  );
+}
+
+function isCustomMediaFixturePath(path: string): boolean {
+  return /(?:^|[._-])(?:media|image|video|sourceMedia|sourceImage)(?:$|[._-])/i.test(path);
+}
+
+function isCustomRenderScaleFixturePath(path: string): boolean {
+  return /^(?:canvas\.)?renderScale$|(?:^|[._-])resolutionScale$/i.test(path);
+}
+
+function isCustomCountFixturePath(path: string): boolean {
+  return /(?:^|[._-])(?:count|items|layers|particles|points|rows|columns|density|detail|quality|samples|iterations)(?:$|[._-])/i.test(
+    path,
+  );
+}
+
+function customFixtureValueNeedsLoadProfile(value: unknown, pathPrefix = ""): boolean {
+  if (!isPerformanceFixtureObjectValue(value)) {
+    return false;
+  }
+
+  return Object.entries(value).some(([key, itemValue]) => {
+    const itemPath = pathPrefix ? `${pathPrefix}.${key}` : key;
+
+    if (
+      isCustomLargeTextFixturePath(itemPath) ||
+      isCustomMediaFixturePath(itemPath) ||
+      isCustomRenderScaleFixturePath(itemPath) ||
+      isCustomCountFixturePath(itemPath)
+    ) {
+      return true;
+    }
+
+    if (typeof itemValue === "number" && Number.isFinite(itemValue)) {
+      return true;
+    }
+
+    return customFixtureValueNeedsLoadProfile(itemValue, itemPath);
+  });
+}
+
+function getSortedJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(getSortedJsonValue);
+  }
+
+  if (isPerformanceFixtureObjectValue(value)) {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, itemValue]) => [key, getSortedJsonValue(itemValue)]),
+    );
+  }
+
+  return value;
+}
+
+function arePerformanceFixtureValuesEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(getSortedJsonValue(left)) === JSON.stringify(getSortedJsonValue(right));
+}
+
+function getNumericFixtureValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function getCountFixtureValue(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.length;
+  }
+
+  if (isPerformanceFixtureObjectValue(value)) {
+    const count = Number(value.count ?? value.items ?? value.length);
+
+    if (Number.isFinite(count)) {
+      return count;
+    }
+
+    if (Array.isArray(value.items)) {
+      return value.items.length;
+    }
+  }
+
+  return null;
+}
+
+function getAreaFixtureDimensions(value: unknown): { height: number; width: number } | null {
+  return getMediaStressFixtureDimensions(value);
+}
+
+function getAreaFixtureValue(value: unknown): number | null {
+  const dimensions = getAreaFixtureDimensions(value);
+
+  if (!dimensions) {
+    return null;
+  }
+
+  return dimensions.width * dimensions.height;
+}
+
+function formatLoadProfileRatio(value: number): string {
+  return Number(value.toFixed(4)).toString();
+}
+
+function getLoadProfileActualSmoothRatio(
+  profile: ToolcraftPerformanceLoadProfile,
+): number | null {
+  if (profile.metric === "numeric-max") {
+    const hardLimit = getNumericFixtureValue(profile.hardLimit);
+    const smoothTarget = getNumericFixtureValue(profile.smoothTarget);
+
+    return hardLimit !== null && smoothTarget !== null && hardLimit > 0
+      ? smoothTarget / hardLimit
+      : null;
+  }
+
+  if (profile.metric === "numeric-min") {
+    const hardLimit = getNumericFixtureValue(profile.hardLimit);
+    const smoothTarget = getNumericFixtureValue(profile.smoothTarget);
+
+    return hardLimit !== null && smoothTarget !== null && smoothTarget > 0
+      ? hardLimit / smoothTarget
+      : null;
+  }
+
+  if (profile.metric === "count") {
+    const hardLimit = getCountFixtureValue(profile.hardLimit);
+    const smoothTarget = getCountFixtureValue(profile.smoothTarget);
+
+    return hardLimit !== null && smoothTarget !== null && hardLimit > 0
+      ? smoothTarget / hardLimit
+      : null;
+  }
+
+  if (profile.metric === "canvas-area" || profile.metric === "media-area") {
+    const hardArea = getAreaFixtureValue(profile.hardLimit);
+    const smoothArea = getAreaFixtureValue(profile.smoothTarget);
+
+    return hardArea !== null && smoothArea !== null && hardArea > 0
+      ? smoothArea / hardArea
+      : null;
+  }
+
+  return null;
+}
+
+function getLoadProfileSmoothTargetRatioError(
+  label: string,
+  profile: ToolcraftPerformanceLoadProfile,
+): string | null {
+  const declaredRatio = profile.smoothTargetRatio;
+
+  if (
+    typeof declaredRatio !== "number" ||
+    !Number.isFinite(declaredRatio) ||
+    declaredRatio <= 0 ||
+    declaredRatio > 1
+  ) {
+    return null;
+  }
+
+  if (
+    declaredRatio === 1 &&
+    !arePerformanceFixtureValuesEqual(profile.smoothTarget, profile.hardLimit)
+  ) {
+    return `${label}.smoothTargetRatio 1 requires smoothTarget to equal hardLimit.`;
+  }
+
+  const actualRatio = getLoadProfileActualSmoothRatio(profile);
+
+  if (actualRatio === null) {
+    return null;
+  }
+
+  const tolerance = 0.0001;
+
+  if (declaredRatio === 1) {
+    return Math.abs(actualRatio - 1) <= tolerance
+      ? null
+      : `${label}.smoothTargetRatio 1 must describe the actual smooth target ratio ${formatLoadProfileRatio(actualRatio)}.`;
+  }
+
+  const previousStepRatio = Math.min(1, declaredRatio + 0.1);
+
+  return actualRatio >= declaredRatio - tolerance &&
+    actualRatio < previousStepRatio - tolerance
+    ? null
+    : `${label}.smoothTargetRatio ${formatLoadProfileRatio(declaredRatio)} must describe the actual smooth target ratio ${formatLoadProfileRatio(actualRatio)}.`;
+}
+
+function fixtureRequiresLoadProfile(fixture: ToolcraftPerformanceFixture): boolean {
+  return (
+    loadProfileRequiredFixtureKinds.has(fixture.kind) ||
+    (fixture.kind === "custom" && customFixtureValueNeedsLoadProfile(fixture.value))
+  );
+}
+
+function getLoadProfileRatioStepCount(ratio: number): number {
+  return Math.round((1 - ratio) / 0.1);
+}
+
+function isTenPercentRatioStep(ratio: number): boolean {
+  return Math.abs(ratio * 10 - Math.round(ratio * 10)) < 0.0001;
+}
+
+function getSchemaNumericHardLimit(
+  control: ToolcraftControlSchema | undefined,
+  metric: ToolcraftPerformanceLoadMetric,
+): number | null {
+  if (!control || (metric !== "numeric-max" && metric !== "numeric-min")) {
+    return null;
+  }
+
+  const value = metric === "numeric-max" ? control.max : control.min;
+
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function getPerformanceLoadProfileErrors(
+  scenario: ToolcraftPerformanceScenario,
+  fieldName: "stressFixture" | "workloadFixture",
+  fixture: ToolcraftPerformanceFixture,
+  control: ToolcraftControlSchema | undefined,
+): string[] {
+  const errors: string[] = [];
+  const profile = fixture.loadProfile;
+
+  if (!profile) {
+    return fixtureRequiresLoadProfile(fixture)
+      ? [
+          `${scenario.id} ${fieldName}.loadProfile must declare hardLimit, smoothTarget, and smoothTargetRatio so performance workload is a measured smooth target rather than a hidden toy fixture.`,
+        ]
+      : [];
+  }
+
+  const label = `${scenario.id} ${fieldName}.loadProfile`;
+
+  if (!profile.target.trim()) {
+    errors.push(`${label}.target must name the product workload target.`);
+  }
+
+  if (!performanceLoadMetrics.has(profile.metric)) {
+    errors.push(`${label}.metric "${profile.metric}" is not supported.`);
+  }
+
+  if (!performanceUserFacingRanges.has(profile.userFacingRange)) {
+    errors.push(`${label}.userFacingRange "${profile.userFacingRange}" is not supported.`);
+  }
+
+  if (
+    typeof profile.smoothTargetRatio !== "number" ||
+    !Number.isFinite(profile.smoothTargetRatio) ||
+    profile.smoothTargetRatio <= 0 ||
+    profile.smoothTargetRatio > 1
+  ) {
+    errors.push(`${label}.smoothTargetRatio must be > 0 and <= 1.`);
+  } else if (!isTenPercentRatioStep(profile.smoothTargetRatio)) {
+    errors.push(`${label}.smoothTargetRatio must use 10 percent steps such as 1, 0.9, or 0.8.`);
+  }
+
+  const smoothTargetRatioError = getLoadProfileSmoothTargetRatioError(label, profile);
+
+  if (smoothTargetRatioError) {
+    errors.push(smoothTargetRatioError);
+  }
+
+  if (!hasPerformanceFixtureValue(fixture)) {
+    errors.push(`${label}.smoothTarget cannot be checked because ${fieldName}.value is missing.`);
+  } else if (!arePerformanceFixtureValuesEqual(profile.smoothTarget, fixture.value)) {
+    errors.push(`${label}.smoothTarget must match ${fieldName}.value so browser tests apply the documented smooth workload target.`);
+  }
+
+  const schemaHardLimit = getSchemaNumericHardLimit(control, profile.metric);
+
+  if (
+    schemaHardLimit !== null &&
+    !arePerformanceFixtureValuesEqual(profile.hardLimit, schemaHardLimit)
+  ) {
+    errors.push(`${label}.hardLimit must match schema ${profile.metric === "numeric-max" ? "max" : "min"} ${schemaHardLimit}.`);
+  }
+
+  if (profile.metric === "numeric-max" || profile.metric === "numeric-min") {
+    const hardLimit = getNumericFixtureValue(profile.hardLimit);
+    const smoothTarget = getNumericFixtureValue(profile.smoothTarget);
+
+    if (hardLimit === null || smoothTarget === null) {
+      errors.push(`${label}.${profile.metric} hardLimit and smoothTarget must be numeric.`);
+    } else if (profile.metric === "numeric-max" && smoothTarget > hardLimit) {
+      errors.push(`${label}.smoothTarget must be <= hardLimit for numeric-max workloads.`);
+    } else if (profile.metric === "numeric-min" && smoothTarget < hardLimit) {
+      errors.push(`${label}.smoothTarget must be >= hardLimit for numeric-min workloads.`);
+    }
+  }
+
+  if (profile.metric === "count") {
+    const hardLimit = getCountFixtureValue(profile.hardLimit);
+    const smoothTarget = getCountFixtureValue(profile.smoothTarget);
+
+    if (hardLimit === null || smoothTarget === null) {
+      errors.push(`${label}.count hardLimit and smoothTarget must be numeric counts, arrays, or objects with count/items.`);
+    } else if (smoothTarget > hardLimit) {
+      errors.push(`${label}.smoothTarget count must be <= hardLimit count.`);
+    }
+  }
+
+  if (profile.metric === "canvas-area" || profile.metric === "media-area") {
+    const hardArea = getAreaFixtureValue(profile.hardLimit);
+    const smoothArea = getAreaFixtureValue(profile.smoothTarget);
+
+    if (hardArea === null || smoothArea === null) {
+      errors.push(`${label}.${profile.metric} hardLimit and smoothTarget must include numeric width and height.`);
+    } else if (smoothArea > hardArea) {
+      errors.push(`${label}.smoothTarget area must be <= hardLimit area.`);
+    }
+  }
+
+  if (fixture.kind === "many-items") {
+    const smoothCount = getCountFixtureValue(fixture.value);
+
+    if (typeof fixture.minCount !== "number" || fixture.minCount <= 0) {
+      errors.push(`${scenario.id} ${fieldName}.minCount must be a positive number for many-items fixtures.`);
+    } else if (smoothCount !== null && smoothCount < fixture.minCount) {
+      errors.push(`${scenario.id} ${fieldName}.value must include at least ${fixture.minCount} items for many-items fixtures.`);
+    }
+  }
+
+  if (
+    typeof profile.smoothTargetRatio === "number" &&
+    Number.isFinite(profile.smoothTargetRatio)
+  ) {
+    if (profile.smoothTargetRatio === 1) {
+      if (profile.userFacingRange !== "fully-guaranteed") {
+        errors.push(`${label}.userFacingRange must be "fully-guaranteed" when smoothTargetRatio is 1.`);
+      }
+    } else if (profile.smoothTargetRatio > 0 && profile.smoothTargetRatio < 1) {
+      if (profile.degradationStepPercent !== 10) {
+        errors.push(`${label}.degradationStepPercent must be 10 when smoothTargetRatio is below 1.`);
+      }
+
+      if (profile.userFacingRange !== "experimental-above-smooth") {
+        errors.push(`${label}.userFacingRange must be "experimental-above-smooth" when smoothTargetRatio is below 1.`);
+      }
+
+      const expectedEvidenceCount = getLoadProfileRatioStepCount(profile.smoothTargetRatio);
+      const evidence = profile.evidence ?? [];
+
+      if (evidence.length < expectedEvidenceCount) {
+        errors.push(`${label}.evidence must include failed measurements for each 10 percent step above smoothTargetRatio ${profile.smoothTargetRatio}.`);
+      }
+
+      for (const [index, entry] of evidence.entries()) {
+        const evidenceLabel = `${label}.evidence[${index}]`;
+
+        if (!entry.scenarioId.trim()) {
+          errors.push(`${evidenceLabel}.scenarioId must name the measured scenario.`);
+        }
+
+        if (entry.result !== "failed") {
+          errors.push(`${evidenceLabel}.result must be "failed" for degraded smooth targets.`);
+        }
+
+        if (!entry.measuredResult.trim()) {
+          errors.push(`${evidenceLabel}.measuredResult must include the measured budget failure.`);
+        }
+
+        if (!entry.optimizationAttempted?.trim()) {
+          errors.push(`${evidenceLabel}.optimizationAttempted must describe the optimization attempted before lowering the smooth target.`);
+        }
+
+        if (!entry.decision.trim()) {
+          errors.push(`${evidenceLabel}.decision must explain why this target was rejected or lowered.`);
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+function getCustomPerformanceFixtureSemanticErrors(
+  scenarioId: string,
+  fieldName: "stressFixture" | "workloadFixture",
+  value: Record<string, unknown>,
+  pathPrefix = "",
+): string[] {
+  const errors: string[] = [];
+
+  for (const [key, itemValue] of Object.entries(value)) {
+    const itemPath = pathPrefix ? `${pathPrefix}.${key}` : key;
+    const itemLabel = `custom ${fieldName}.${itemPath}`;
+
+    if (isCustomLargeTextFixturePath(itemPath)) {
+      errors.push(
+        ...getPerformanceFixtureLargeTextValueErrors(
+          scenarioId,
+          itemLabel,
+          itemValue,
+        ),
+      );
+      continue;
+    }
+
+    if (isCustomMediaFixturePath(itemPath)) {
+      const dimensions = getMediaStressFixtureDimensions(itemValue);
+
+      if (!dimensions) {
+        errors.push(
+          `${scenarioId} ${itemLabel} must be an object with numeric width and height so browser tests can generate or load realistic media.`,
+        );
+      } else if (
+        Math.max(dimensions.width, dimensions.height) < mediaStressMinLongEdge ||
+        dimensions.width * dimensions.height < mediaStressMinArea
+      ) {
+        errors.push(
+          `${scenarioId} ${itemLabel} must be at least 1920x1080-equivalent; received ${dimensions.width}x${dimensions.height}.`,
+        );
+      }
+      continue;
+    }
+
+    if (isCustomRenderScaleFixturePath(itemPath)) {
+      if (
+        typeof itemValue !== "number" ||
+        !Number.isFinite(itemValue) ||
+        itemValue <= 1
+      ) {
+        errors.push(
+          `${scenarioId} ${itemLabel} must be a numeric Resolution scale greater than 1 so browser tests prove high-resolution backing pixels.`,
+        );
+      }
+      continue;
+    }
+
+    if (isPerformanceFixtureObjectValue(itemValue)) {
+      errors.push(
+        ...getCustomPerformanceFixtureSemanticErrors(
+          scenarioId,
+          fieldName,
+          itemValue,
+          itemPath,
+        ),
+      );
+    }
+  }
+
+  return errors;
+}
+
 function isLargeTextWorkloadControl(
   control: ToolcraftControlSchema | undefined,
 ): boolean {
@@ -522,15 +1196,17 @@ function isLargeTextWorkloadControl(
 }
 
 function getPerformanceFixtureShapeErrors(
-  scenarioId: string,
+  scenario: ToolcraftPerformanceScenario,
   fieldName: "stressFixture" | "workloadFixture",
   fixture: ToolcraftPerformanceFixture,
+  control: ToolcraftControlSchema | undefined,
   options: {
     requireLargeText?: boolean;
     requireMedia?: boolean;
   } = {},
 ): string[] {
   const errors: string[] = [];
+  const scenarioId = scenario.id;
 
   if (!performanceFixtureKinds.has(fixture.kind)) {
     errors.push(`${scenarioId} ${fieldName}.kind "${fixture.kind}" is not supported.`);
@@ -563,6 +1239,14 @@ function getPerformanceFixtureShapeErrors(
       errors.push(
         `${scenarioId} custom ${fieldName}.value must include at least one heavy state key.`,
       );
+    } else {
+      errors.push(
+        ...getCustomPerformanceFixtureSemanticErrors(
+          scenarioId,
+          fieldName,
+          fixture.value,
+        ),
+      );
     }
   } else if (fixture.kind === "media") {
     const dimensions = getMediaStressFixtureDimensions(fixture.value);
@@ -582,6 +1266,7 @@ function getPerformanceFixtureShapeErrors(
   }
 
   if (!options.requireLargeText && fixture.kind !== "large-text") {
+    errors.push(...getPerformanceLoadProfileErrors(scenario, fieldName, fixture, control));
     return errors;
   }
 
@@ -592,37 +1277,19 @@ function getPerformanceFixtureShapeErrors(
     return errors;
   }
 
-  if (typeof fixture.value !== "string") {
-    errors.push(`${scenarioId} large-text ${fieldName}.value must be a string.`);
-    return errors;
-  }
-
-  const minChars = fixture.minChars ?? largeTextStressMinChars;
-  const minLines = fixture.minLines ?? largeTextStressMinLines;
-
-  if (minChars < largeTextStressMinChars) {
-    errors.push(
-      `${scenarioId} large-text ${fieldName}.minChars must be >= ${largeTextStressMinChars}.`,
-    );
-  }
-
-  if (minLines < largeTextStressMinLines) {
-    errors.push(
-      `${scenarioId} large-text ${fieldName}.minLines must be >= ${largeTextStressMinLines}.`,
-    );
-  }
-
-  if (fixture.value.length < minChars) {
-    errors.push(
-      `${scenarioId} large-text ${fieldName}.value must contain at least ${minChars} characters.`,
-    );
-  }
+  errors.push(
+    ...getPerformanceFixtureLargeTextValueErrors(
+      scenarioId,
+      `large-text ${fieldName}.value`,
+      fixture.value,
+      {
+        minChars: fixture.minChars,
+        minLines: fixture.minLines,
+      },
+    ),
+  );
 
-  if (getTextLineCount(fixture.value) < minLines) {
-    errors.push(
-      `${scenarioId} large-text ${fieldName}.value must contain at least ${minLines} lines.`,
-    );
-  }
+  errors.push(...getPerformanceLoadProfileErrors(scenario, fieldName, fixture, control));
 
   return errors;
 }
@@ -664,7 +1331,7 @@ function getStressFixtureErrors(
   }
 
   errors.push(
-    ...getPerformanceFixtureShapeErrors(scenario.id, "stressFixture", fixture, {
+    ...getPerformanceFixtureShapeErrors(scenario, "stressFixture", fixture, control, {
       requireLargeText: isLargeTextWorkloadControl(control),
       requireMedia: isMediaImport,
     }),
@@ -735,9 +1402,10 @@ function getWorkloadFixtureErrors(
 
   errors.push(
     ...getPerformanceFixtureShapeErrors(
-      scenario.id,
+      scenario,
       "workloadFixture",
       fixture,
+      control,
     ),
   );
 
@@ -940,19 +1608,48 @@ function hasDetailHeavyCanvas2DRendererLayer(
   );
 }
 
+function getRendererMeasuredAlternativeEvidenceErrors(
+  technique: ToolcraftRendererTechnique,
+): string[] {
+  return (technique.measuredAlternativeEvidence ?? []).flatMap((evidence, index) => {
+    const label = `rendererTechnique.measuredAlternativeEvidence[${index}]`;
+    const errors: string[] = [];
+
+    if (evidence.alternativeStrategy !== "webgl" && evidence.alternativeStrategy !== "webgpu") {
+      errors.push(`${label}.alternativeStrategy must be "webgl" or "webgpu".`);
+    }
+
+    if (!evidence.scenarioId.trim()) {
+      errors.push(`${label}.scenarioId must name the measured performance scenario.`);
+    }
+
+    if (!evidence.fixture.trim()) {
+      errors.push(`${label}.fixture must name the exact stress fixture that was measured.`);
+    }
+
+    if (!evidence.measuredResult.trim()) {
+      errors.push(`${label}.measuredResult must summarize measured frame, interaction, render, or long-task results.`);
+    }
+
+    if (!evidence.decision.trim()) {
+      errors.push(`${label}.decision must explain why the selected renderer remains appropriate.`);
+    }
+
+    return errors;
+  });
+}
+
 function hasMeasuredGpuAlternativeEvidence(
   technique: ToolcraftRendererTechnique,
 ): boolean {
-  const evidenceText = [
-    ...technique.whyNotAlternativeStrategies,
-    ...technique.performanceRisks,
-  ].join(" ");
-
-  return (
-    /\b(?:webgl|webgpu|gpu)\b/i.test(evidenceText) &&
-    /\b(?:budget|evidence|frame|long task|measure|measured|perf|performance|stress)\b/i.test(
-      evidenceText,
-    )
+  return (technique.measuredAlternativeEvidence ?? []).some(
+    (evidence) =>
+      (evidence.alternativeStrategy === "webgl" ||
+        evidence.alternativeStrategy === "webgpu") &&
+      evidence.scenarioId.trim().length > 0 &&
+      evidence.fixture.trim().length > 0 &&
+      evidence.measuredResult.trim().length > 0 &&
+      evidence.decision.trim().length > 0,
   );
 }
 
@@ -1090,6 +1787,8 @@ function getRendererTechniqueErrors(config: ToolcraftPerformanceConfig): string[
     errors.push("Custom renderer technique must list performance risks.");
   }
 
+  errors.push(...getRendererMeasuredAlternativeEvidenceErrors(technique));
+
   if (
     technique.productRepresentation === "text" &&
     technique.rendererWorkload !== "text-output" &&
@@ -1142,7 +1841,7 @@ function getRendererTechniqueErrors(config: ToolcraftPerformanceConfig): string[
     !hasMeasuredGpuAlternativeEvidence(technique)
   ) {
     errors.push(
-      "Detail-heavy Canvas 2D renderers must evaluate WebGL/WebGPU in rendererTechnique.whyNotAlternativeStrategies or performanceRisks with measured stress evidence before keeping the pixel work on CPU.",
+      "Detail-heavy Canvas 2D renderers must include rendererTechnique.measuredAlternativeEvidence for WebGL/WebGPU stress comparison before keeping the pixel work on CPU.",
     );
   }
 
@@ -1155,6 +1854,31 @@ function getPassById(
   return new Map(pipeline.passes.map((pass) => [pass.id, pass]));
 }
 
+function hasMainThreadCanvasRasterCompositePreviewPressure(
+  config: ToolcraftPerformanceConfig,
+): boolean {
+  if (config.rendererStrategy !== "canvas-2d" || !config.rendererPipeline) {
+    return false;
+  }
+
+  const hasMainThreadRasterPass = config.rendererPipeline.passes.some(
+    (pass) =>
+      pass.runsOn === "main" &&
+      (pass.kind === "rasterize" || pass.kind === "pixel-transform") &&
+      (pass.output === "intermediate" || pass.output === "preview") &&
+      (pass.quality === "full" || pass.quality === "retina"),
+  );
+  const hasMainThreadPreviewComposite = config.rendererPipeline.passes.some(
+    (pass) =>
+      pass.runsOn === "main" &&
+      pass.kind === "composite" &&
+      pass.output === "preview" &&
+      (pass.quality === "full" || pass.quality === "retina"),
+  );
+
+  return hasMainThreadRasterPass && hasMainThreadPreviewComposite;
+}
+
 function hasPipelineReference(value: string): boolean {
   return value.trim().length > 0 && !vaguePipelineReferencePattern.test(value.trim());
 }
@@ -1418,6 +2142,7 @@ export function validateToolcraftPerformanceCoverage(
     getAllSchemaControls(schema).map((control) => [control.target, control] as const),
   );
 
+  errors.push(...getBrowserCheckPolicyErrors(config));
   errors.push(...getRendererTechniqueErrors(config));
   errors.push(...getRendererPipelineErrors(schema, config));
 
@@ -1445,13 +2170,22 @@ export function validateToolcraftPerformanceCoverage(
     );
   }
 
+  if (
+    hasMainThreadCanvasRasterCompositePreviewPressure(config) &&
+    config.rendererWorkload !== "pixel-output"
+  ) {
+    errors.push(
+      `Canvas 2D pipelines with main-thread rasterize/composite preview pressure must use rendererWorkload "pixel-output" or move expensive passes off the main thread; received "${config.rendererWorkload}".`,
+    );
+  }
+
   if (
     config.rendererWorkload === "pixel-output" &&
     !gpuRendererStrategies.has(config.rendererStrategy) &&
     (!config.rendererTechnique || !hasMeasuredGpuAlternativeEvidence(config.rendererTechnique))
   ) {
     errors.push(
-      `rendererWorkload "pixel-output" should use rendererStrategy "webgl" or "webgpu", received "${config.rendererStrategy}". Keeping a CPU renderer requires measured WebGL/WebGPU evidence in rendererTechnique.whyNotAlternativeStrategies or performanceRisks.`,
+      `rendererWorkload "pixel-output" should use rendererStrategy "webgl" or "webgpu", received "${config.rendererStrategy}". Keeping a CPU renderer requires rendererTechnique.measuredAlternativeEvidence for WebGL/WebGPU stress comparison.`,
     );
   }
 
@@ -1577,7 +2311,9 @@ export function validateToolcraftPerformanceCoverage(
     ),
   );
   const sensitiveTargets = new Set(
-    collectToolcraftPerformanceSensitiveControls(schema).map((entry) => entry.target),
+    collectToolcraftPerformanceSensitiveControls(schema)
+      .map((entry) => entry.target)
+      .filter((target) => !isToolcraftRuntimeOwnedTarget(target)),
   );
   const performanceRoleConflicts = collectToolcraftPerformanceRoleConflicts(schema);
 
@@ -1623,6 +2359,10 @@ export function validateToolcraftPerformanceCoverage(
   }
 
   for (const target of getVisiblePerformanceControlTargets(schema)) {
+    if (isToolcraftRuntimeOwnedTarget(target)) {
+      continue;
+    }
+
     const targetScenarios = scenariosByTarget.get(target) ?? [];
     const targetControl = controlsByTarget.get(target);
     const sliderControlType = getSliderDragControlType(targetControl);