@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -0,0 +1,151 @@
+import { defineToolcraft } from "../../schema/define-toolcraft";
+
+export const testSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            density: {
+              defaultValue: 4,
+              label: "Density",
+              max: 12,
+              min: 1,
+              performanceReason: "Density changes the amount of rendered output.",
+              performanceRole: "workload",
+              target: "render.density",
+              type: "slider",
+            },
+            mode: {
+              defaultValue: "soft",
+              label: "Mode",
+              options: [
+                { label: "Soft", value: "soft" },
+                { label: "Sharp", value: "sharp" },
+              ],
+              performanceReason: "Mode changes rendering branches but not workload size.",
+              performanceRole: "responsiveness",
+              target: "render.mode",
+              type: "select",
+            },
+          },
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
+export const ordinarySliderSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            opacity: {
+              defaultValue: 50,
+              label: "Opacity",
+              max: 100,
+              min: 0,
+              performanceReason: "Opacity changes a lightweight uniform value.",
+              performanceRole: "responsiveness",
+              target: "render.opacity",
+              type: "slider",
+            },
+          },
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
+export const rangeSliderSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            band: {
+              defaultValue: [20, 80],
+              label: "Band",
+              max: 100,
+              min: 0,
+              performanceReason: "Band changes a lightweight bounded interval.",
+              performanceRole: "responsiveness",
+              target: "render.band",
+              type: "rangeSlider",
+            },
+          },
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
+export const largeTextSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            content: {
+              defaultValue: "",
+              label: "Content",
+              performanceReason: "Content length changes text layout and renderer workload.",
+              performanceRole: "workload",
+              target: "product.content",
+              type: "code",
+            },
+          },
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});
+
+export const mediaUploadSchema = defineToolcraft({
+  canvas: {
+    enabled: true,
+    sizing: { mode: "intrinsic-media" },
+    upload: true,
+  },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            source: {
+              defaultValue: null,
+              label: "Source image",
+              performanceReason: "Uploaded media dimensions change renderer workload.",
+              performanceRole: "responsiveness",
+              target: "source.image",
+              type: "fileDrop",
+            },
+          },
+          title: "Source",
+        },
+      ],
+      title: "Runtime Controls",
+    },
+  },
+});

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

@@ -0,0 +1,133 @@
+import type { ResolvedToolcraftAppSchema } from "../../schema/types";
+import { requireToolcraftSchemaPerformanceValues } from "../performance-schema-queries";
+
+export function createMaxValueStressFixture(value: unknown, reason = "Maximum workload value.") {
+  return {
+    kind: "max-value" as const,
+    loadProfile: {
+      hardLimit: value,
+      metric: "numeric-max" as const,
+      smoothTarget: value,
+      smoothTargetRatio: 1,
+      target: "render.density",
+      userFacingRange: "fully-guaranteed" as const,
+    },
+    reason,
+    value,
+  };
+}
+
+export function createSchemaMaxValueStressFixture(
+  schema: ResolvedToolcraftAppSchema,
+  target: string,
+  reason = "Schema-derived maximum workload value.",
+) {
+  const values = requireToolcraftSchemaPerformanceValues(schema, target);
+  const value = values.max;
+
+  return {
+    kind: "max-value" as const,
+    loadProfile: {
+      hardLimit: value,
+      metric: typeof value === "number" ? ("numeric-max" as const) : ("custom" as const),
+      smoothTarget: value,
+      smoothTargetRatio: 1,
+      target,
+      userFacingRange: "fully-guaranteed" as const,
+    },
+    reason,
+    value,
+  };
+}
+
+export function createCustomStressFixture(
+  value: unknown = { density: 12 },
+  reason = "Combined renderer stress state.",
+) {
+  return {
+    kind: "custom" as const,
+    loadProfile: {
+      hardLimit: value,
+      metric: "custom" as const,
+      smoothTarget: value,
+      smoothTargetRatio: 1,
+      target: "renderer.output",
+      userFacingRange: "fully-guaranteed" as const,
+    },
+    reason,
+    value,
+  };
+}
+
+export function createCombinedRendererStressFixture() {
+  return createCustomStressFixture(
+    { density: 12, zoom: "toolbar" },
+    "Stress checks must run with the densest product output visible.",
+  );
+}
+
+export function createLargeTextStressValue(): string {
+  return Array.from(
+    { length: 1_000 },
+    (_, index) =>
+      `Line ${String(index + 1).padStart(4, "0")} performance stress text with enough glyphs to exercise layout.`,
+  ).join("\n");
+}
+
+export function createLargeTextStressFixture() {
+  return {
+    kind: "large-text" as const,
+    minChars: 50_000,
+    minLines: 1_000,
+    reason: "Long multiline content is the heaviest realistic text workload.",
+    value: createLargeTextStressValue(),
+  };
+}
+
+export function createMediaStressFixture(
+  value: { height: number; width: number } = { height: 1080, width: 1920 },
+  reason = "Large uploaded source media is the heaviest realistic import fixture.",
+) {
+  return {
+    kind: "media" as const,
+    loadProfile: {
+      hardLimit: value,
+      metric: "media-area" as const,
+      smoothTarget: value,
+      smoothTargetRatio: 1,
+      target: "source.image",
+      userFacingRange: "fully-guaranteed" as const,
+    },
+    reason,
+    value,
+  };
+}
+
+export function createDegradedMaxValueStressFixture() {
+  return {
+    kind: "max-value" as const,
+    loadProfile: {
+      degradationStepPercent: 10 as const,
+      evidence: [
+        {
+          attemptedRatio: 1,
+          attemptedTarget: 12,
+          decision: "Keep 12 available as high density while guaranteeing smooth drag through 11.",
+          measuredResult: "At density 12, maxFrameGapMs 148 exceeded the 80ms budget.",
+          optimizationAttempted: "Cached glyph atlas and coalesced preview work to requestAnimationFrame.",
+          result: "failed" as const,
+          scenarioId: "density-drag",
+          target: "render.density",
+        },
+      ],
+      hardLimit: 12,
+      metric: "numeric-max" as const,
+      smoothTarget: 11,
+      smoothTargetRatio: 0.9,
+      target: "render.density",
+      userFacingRange: "experimental-above-smooth" as const,
+    },
+    reason: "Density 11 is the measured smooth target after hard-limit testing.",
+    value: 11,
+  };
+}

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

@@ -0,0 +1 @@
+export * from "./performance-test-fixtures/index";

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

@@ -0,0 +1,338 @@
+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";
+
+export type ToolcraftOutputCompletionEvidence = "clipboard" | "download";
+
+export type ToolcraftPerformanceCoverage = {
+  automated: boolean;
+  automatedTestName: string;
+  browser: boolean;
+  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 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;
+  reason: string;
+  value?: unknown;
+};
+
+export type ToolcraftPerformanceStressFixtureKind = ToolcraftPerformanceFixtureKind;
+export type ToolcraftPerformanceStressFixture = ToolcraftPerformanceFixture;
+export type ToolcraftPerformanceWorkloadFixture = ToolcraftPerformanceFixture;
+
+type ToolcraftPerformanceScenarioBase = ToolcraftPerformanceCoverage & {
+  budget: ToolcraftPerformanceBudget;
+  controlLabel?: string;
+  expectedObservable: string;
+  fixture: string;
+  id: string;
+  target?: string;
+  stress?: boolean;
+  stressFixture?: ToolcraftPerformanceStressFixture;
+  workloadFixture?: ToolcraftPerformanceWorkloadFixture;
+  uiSelector?: string;
+  values?: ToolcraftPerformanceValueSet;
+  workload: boolean;
+};
+
+type ToolcraftExportCopyPerformanceScenario = ToolcraftPerformanceScenarioBase & {
+  actionValue: string;
+  completionEvidence: ToolcraftOutputCompletionEvidence;
+  controlLabel: string;
+  interaction: "export-copy";
+};
+
+type ToolcraftNonExportPerformanceScenario = ToolcraftPerformanceScenarioBase & {
+  actionValue?: never;
+  completionEvidence?: never;
+  interaction: Exclude<ToolcraftPerformanceInteraction, "export-copy">;
+};
+
+export type ToolcraftPerformanceScenario =
+  | ToolcraftExportCopyPerformanceScenario
+  | ToolcraftNonExportPerformanceScenario;
+
+export type ToolcraftRendererStrategy =
+  | "none"
+  | "dom"
+  | "svg"
+  | "canvas-2d"
+  | "webgl"
+  | "webgpu";
+
+export type ToolcraftRendererWorkload =
+  | "none"
+  | "simple-composition"
+  | "text-output"
+  | "vector-output"
+  | "pixel-output";
+
+export type ToolcraftSourceRepresentation =
+  | "reference-runtime"
+  | "dom-text"
+  | "svg"
+  | "canvas-2d"
+  | "webgl-texture"
+  | "webgpu-texture"
+  | "image-media"
+  | "video-media"
+  | "procedural-data"
+  | "mixed";
+
+export type ToolcraftProductRepresentation =
+  | "text"
+  | "vector"
+  | "pixel"
+  | "video"
+  | "mixed";
+
+export type ToolcraftPreviewRenderer =
+  | "dom"
+  | "svg"
+  | "canvas-2d"
+  | "webgl"
+  | "webgpu";
+
+export type ToolcraftExportRenderer =
+  | "none"
+  | "dom"
+  | "svg"
+  | "canvas-2d"
+  | "webgl"
+  | "webgpu"
+  | "media-recorder"
+  | "webcodecs";
+
+export type ToolcraftRendererLayerKind =
+  | "background"
+  | "product-foreground"
+  | "editing-handles"
+  | "export-composite";
+
+export type ToolcraftRendererLayerContent =
+  | "bitmap-media"
+  | "composite"
+  | "dense-pattern"
+  | "geometry"
+  | "handles"
+  | "noise"
+  | "shader"
+  | "text";
+
+export type ToolcraftRendererLayerPrimitiveCount = "low" | "medium" | "high";
+
+export type ToolcraftRendererLayerExportMode =
+  | "included"
+  | "excluded"
+  | "composited";
+
+export type ToolcraftRendererLayer = {
+  content: readonly ToolcraftRendererLayerContent[];
+  exportMode: ToolcraftRendererLayerExportMode;
+  id: string;
+  intentionalRasterizationReason?: string;
+  kind: ToolcraftRendererLayerKind;
+  primitiveCount: ToolcraftRendererLayerPrimitiveCount;
+  renderer: Exclude<ToolcraftRendererStrategy, "none">;
+  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;
+  rendererStrategy: ToolcraftRendererStrategy;
+  rendererTechnique?: ToolcraftRendererTechnique;
+  rendererWorkload: ToolcraftRendererWorkload;
+  scenarios: readonly ToolcraftPerformanceScenario[];
+  usesCustomRenderer: boolean;
+  workloadTargets: readonly string[];
+};
+
+export type ToolcraftPerformanceSensitiveControl = {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  target: string;
+};
+
+export type ToolcraftUnclassifiedPerformanceControl = {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  target: string;
+};