@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/testing/performance-workload-envelope-validation.ts

@@ -0,0 +1,222 @@
+import { isToolcraftRuntimeOwnedTarget } from "../schema/runtime-targets";
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import type { ToolcraftEnvelopeValidationContext } from "./performance-envelope-validation-context";
+import { collectToolcraftWorkloadControls } from "./performance-control-classification";
+import { getSchemaBoundErrors, groupControlsByTarget } from "./performance-workload-envelope-schema-validation";
+import {
+  formatUnknownValue,
+  getDimensionLabel,
+  getEnvelopeDimensions,
+  getNumericErrors,
+  isNonNullObject,
+  isSupportedMapping,
+  isTrimmedNonEmptyString,
+  type UnknownRecord,
+} from "./performance-workload-envelope-shared";
+import { getDerivedDependencyCycleErrors } from "./performance-workload-envelope-derived-validation";
+import { getAllSchemaControls } from "./performance-schema-queries";
+import type { ToolcraftEnvelopePerformanceConfig } from "./performance-types";
+
+type RuntimeDimensionEntry = {
+  dimension: UnknownRecord;
+  index: number;
+};
+
+export function getToolcraftWorkloadEnvelopeErrors(
+  schema: ResolvedToolcraftAppSchema,
+  config: ToolcraftEnvelopePerformanceConfig,
+): string[] {
+  const envelope = getEnvelopeDimensions(config);
+  if (!envelope.dimensions) {
+    return [...envelope.errors];
+  }
+
+  const dimensions = envelope.dimensions;
+  const errors: string[] = [];
+  const schemaControlsByTarget = groupControlsByTarget(getAllSchemaControls(schema));
+  const workloadControls = collectToolcraftWorkloadControls(schema);
+  const workloadControlsByTarget = groupControlsByTarget(
+    workloadControls.map(({ control }) => control),
+  );
+  const dimensionEntries: RuntimeDimensionEntry[] = dimensions.flatMap(
+    (dimension, index) =>
+      isNonNullObject(dimension) ? [{ dimension, index }] : [],
+  );
+  const dimensionIdCounts = new Map<string, number>();
+
+  for (const { dimension } of dimensionEntries) {
+    if (isTrimmedNonEmptyString(dimension.id)) {
+      dimensionIdCounts.set(
+        dimension.id,
+        (dimensionIdCounts.get(dimension.id) ?? 0) + 1,
+      );
+    }
+  }
+
+  const knownDimensionIds = new Set(dimensionIdCounts.keys());
+  const seenDimensionIds = new Set<string>();
+  const schemaTargetCounts = new Map<string, number>();
+
+  for (const [index, rawDimension] of dimensions.entries()) {
+    if (!isNonNullObject(rawDimension)) {
+      errors.push(
+        `workloadEnvelope.dimensions[${index}] must be a non-null object.`,
+      );
+      continue;
+    }
+
+    const dimension = rawDimension;
+    const label = getDimensionLabel(dimension, index);
+
+    if (!isTrimmedNonEmptyString(dimension.id)) {
+      errors.push(
+        `workloadEnvelope.dimensions[${index}].id must be trimmed and non-empty.`,
+      );
+    } else if (seenDimensionIds.has(dimension.id)) {
+      errors.push(`Workload dimension id "${dimension.id}" must be unique.`);
+    } else {
+      seenDimensionIds.add(dimension.id);
+    }
+
+    if (!isTrimmedNonEmptyString(dimension.unit)) {
+      errors.push(`${label} unit must be trimmed and non-empty.`);
+    }
+
+    errors.push(...getNumericErrors(dimension, label));
+
+    if (!isSupportedMapping(dimension.mapping)) {
+      errors.push(
+        `${label} mapping "${formatUnknownValue(dimension.mapping)}" is not supported.`,
+      );
+    } else if (
+      dimension.mapping === "custom" &&
+      (typeof dimension.customMappingReason !== "string" ||
+        !dimension.customMappingReason.trim())
+    ) {
+      errors.push(
+        `${label} with custom mapping must provide a non-empty customMappingReason.`,
+      );
+    }
+
+    const source = dimension.source;
+    if (!isNonNullObject(source)) {
+      errors.push(`${label} source must be a non-null object.`);
+      continue;
+    }
+
+    switch (source.kind) {
+      case "runtime-state":
+        if (!isTrimmedNonEmptyString(source.path)) {
+          errors.push(`${label} runtime-state path must be trimmed and non-empty.`);
+        }
+        break;
+      case "external-input":
+        if (!isTrimmedNonEmptyString(source.id)) {
+          errors.push(`${label} external-input id must be trimmed and non-empty.`);
+        }
+        break;
+      case "derived": {
+        if (!Array.isArray(source.inputs)) {
+          errors.push(`${label} derived inputs must be an array.`);
+          break;
+        }
+
+        if (source.inputs.length === 0) {
+          errors.push(`${label} derived inputs must not be empty.`);
+        }
+
+        for (const [inputIndex, input] of source.inputs.entries()) {
+          if (!isTrimmedNonEmptyString(input)) {
+            errors.push(
+              `${label} derived input at index ${inputIndex} must be trimmed and non-empty.`,
+            );
+          } else if (input === dimension.id) {
+            errors.push(`${label} cannot reference itself as a derived input.`);
+          } else if (!knownDimensionIds.has(input)) {
+            errors.push(`${label} references unknown derived input "${input}".`);
+          }
+        }
+        break;
+      }
+      case "schema-target": {
+        const target = source.target;
+
+        if (!isTrimmedNonEmptyString(target)) {
+          errors.push(`${label} schema-target target must be trimmed and non-empty.`);
+          break;
+        }
+
+        if (isToolcraftRuntimeOwnedTarget(target)) {
+          errors.push(`${label} schema target "${target}" is runtime-owned.`);
+          break;
+        }
+
+        const targetCount = (schemaTargetCounts.get(target) ?? 0) + 1;
+        schemaTargetCounts.set(target, targetCount);
+        if (targetCount === 2) {
+          errors.push(
+            `Schema target "${target}" must not map to more than one workloadEnvelope dimension.`,
+          );
+        }
+
+        const schemaControls = schemaControlsByTarget.get(target) ?? [];
+        if (schemaControls.length === 0) {
+          errors.push(`${label} references unknown schema target "${target}".`);
+          break;
+        }
+
+        const explicitWorkloadControls = workloadControlsByTarget.get(target) ?? [];
+        if (explicitWorkloadControls.length !== 1) {
+          errors.push(
+            `${label} schema target "${target}" must reference exactly one explicit workload control.`,
+          );
+          break;
+        }
+
+        errors.push(
+          ...getSchemaBoundErrors(
+            dimension,
+            label,
+            target,
+            explicitWorkloadControls[0]!,
+            source.workloadBoundary,
+          ),
+        );
+        break;
+      }
+      default:
+        errors.push(
+          `${label} source kind "${formatUnknownValue(source.kind)}" is not supported.`,
+        );
+    }
+  }
+
+  errors.push(
+    ...getDerivedDependencyCycleErrors(
+      dimensionEntries.map(({ dimension }) => dimension),
+      dimensionIdCounts,
+    ),
+  );
+
+  const checkedWorkloadTargets = new Set<string>();
+  for (const { target } of workloadControls) {
+    if (checkedWorkloadTargets.has(target)) {
+      continue;
+    }
+    checkedWorkloadTargets.add(target);
+
+    if ((schemaTargetCounts.get(target) ?? 0) !== 1) {
+      errors.push(
+        `Workload control ${target} must map to exactly one workloadEnvelope dimension.`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+export function getToolcraftWorkloadEnvelopeErrorsForContext(
+  context: ToolcraftEnvelopeValidationContext,
+): string[] {
+  return getToolcraftWorkloadEnvelopeErrors(context.schema, context.config);
+}

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

@@ -0,0 +1,65 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import {
+  TOOLCRAFT_PERFORMANCE_PROFILE_NAMES,
+  defineToolcraftPerformance,
+  isToolcraftPerformanceProfileName,
+  type ToolcraftEnvelopePerformanceConfig,
+  type ToolcraftPerformanceProfileName,
+  type ToolcraftWorkloadDimension,
+  type ToolcraftWorkloadEnvelope,
+  type ToolcraftWorkloadSource,
+} from "./performance";
+
+describe("Toolcraft performance workload types", () => {
+  it("requires a workload envelope in the canonical config", () => {
+    const source: ToolcraftWorkloadSource = {
+      kind: "schema-target",
+      target: "render.count",
+      workloadBoundary: "maximum",
+    };
+    const dimension: ToolcraftWorkloadDimension = {
+      defaultValue: 1,
+      id: "output-units",
+      interactiveMax: 100,
+      mapping: "direct",
+      source,
+      unit: "units",
+    };
+    const envelope: ToolcraftWorkloadEnvelope = {
+      dimensions: [dimension],
+    };
+
+    const config = defineToolcraftPerformance({
+      rendererStrategy: "canvas-2d",
+      scenarios: [],
+      usesCustomRenderer: true,
+      workloadEnvelope: envelope,
+    });
+
+    expect(config.workloadEnvelope).toBe(envelope);
+    expect("rendererWorkload" in config).toBe(false);
+    expect("workloadTargets" in config).toBe(false);
+    expectTypeOf(config).toMatchTypeOf<ToolcraftEnvelopePerformanceConfig>();
+    expectTypeOf(config.rendererStrategy).toEqualTypeOf<"canvas-2d">();
+  });
+
+  it("exposes exactly the supported performance profile names", () => {
+    expect(TOOLCRAFT_PERFORMANCE_PROFILE_NAMES).toEqual([
+      "interactive-continuous",
+      "interactive-discrete",
+      "batch-responsive",
+      "initial-render",
+    ]);
+    expect(isToolcraftPerformanceProfileName("interactive-continuous")).toBe(
+      true,
+    );
+    expect(isToolcraftPerformanceProfileName("custom-profile")).toBe(false);
+    expectTypeOf<ToolcraftPerformanceProfileName>().toEqualTypeOf<
+      | "interactive-continuous"
+      | "interactive-discrete"
+      | "batch-responsive"
+      | "initial-render"
+    >();
+  });
+});

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

@@ -0,0 +1,34 @@
+export type ToolcraftWorkloadSource =
+  | {
+      kind: "schema-target";
+      target: string;
+      workloadBoundary?: "minimum" | "maximum";
+    }
+  | { kind: "runtime-state"; path: string }
+  | { kind: "external-input"; id: string }
+  | { kind: "derived"; inputs: readonly string[] };
+
+export type ToolcraftWorkloadDimension = {
+  batchMax?: number;
+  customMappingReason?: string;
+  defaultValue: number;
+  id: string;
+  interactiveMax?: number;
+  mapping: "direct" | "area" | "quadratic" | "custom";
+  source: ToolcraftWorkloadSource;
+  unit: string;
+};
+
+export type ToolcraftWorkloadEnvelope = {
+  dimensions: readonly ToolcraftWorkloadDimension[];
+};
+
+export {
+  TOOLCRAFT_PERFORMANCE_PROFILE_NAMES,
+  isToolcraftPerformanceProfileName,
+} from "../performance/profile-catalog";
+export type { ToolcraftPerformanceProfileName } from "../performance/profile-catalog";
+export type {
+  ToolcraftRenderPassCost,
+  ToolcraftRenderPassLifecycle,
+} from "../rendering/renderer-pipeline-registration";

package/templates/runtime/testing/performance.ts

@@ -1,15 +1,57 @@
 export * from "./performance-types";
+export * from "./performance-workload-types";
 export {
-  defaultToolcraftBrowserCheckPolicy,
-  defineToolcraftPerformance,
-} from "./performance-browser-policy";
+  TOOLCRAFT_MODEL_PERFORMANCE_DEVELOPMENT_PRESSURE,
+  deriveToolcraftModelPerformancePaths,
+  type ToolcraftModelPerformanceCheckpoint,
+  type ToolcraftModelPerformanceDimension,
+  type ToolcraftModelPerformanceDimensionId,
+  type ToolcraftModelPerformancePath,
+  type ToolcraftModelPerformancePathKind,
+} from "./model-import-performance-workload";
+export { defineToolcraftPerformance } from "./performance-config";
 export {
-  collectToolcraftPerformanceSensitiveControls,
   collectToolcraftUnclassifiedPerformanceControls,
+  collectToolcraftWorkloadControls,
 } from "./performance-control-classification";
 export {
   getToolcraftControlPerformanceValues,
   getToolcraftSchemaPerformanceValues,
   requireToolcraftSchemaPerformanceValues,
 } from "./performance-schema-queries";
-export { validateToolcraftPerformanceCoverage } from "./performance-coverage-validator";
+export {
+  TOOLCRAFT_FUNCTIONAL_PERFORMANCE_COVERAGE_POLICY,
+  TOOLCRAFT_STRICT_PERFORMANCE_COVERAGE_POLICY,
+  type ToolcraftPerformanceCoverageValidationPolicy,
+  validateToolcraftPerformanceCoverage,
+} from "./performance-coverage-validator";
+export { getToolcraftPerformanceProfileErrors } from "./performance-profile-validation";
+export { getToolcraftWorkloadEnvelopeErrors } from "./performance-workload-envelope-validation";
+export {
+  deriveToolcraftPerformancePaths,
+  type ToolcraftPerformancePath,
+} from "./performance-paths";
+export {
+  assessToolcraftRenderPlan,
+  type ToolcraftRenderPlanAssessment,
+  type ToolcraftRenderPlanBenchmarkRequirement,
+  type ToolcraftRenderPlanInvariants,
+} from "./performance-render-plan-assessment";
+export {
+  defineToolcraftFixtureAdapter,
+} from "./performance-fixture-adapters";
+export {
+  defineToolcraftDiscreteFixtureAdapter,
+  defineToolcraftSchemaDiscreteFixtureAdapter,
+} from "./performance-fixture-discrete-adapters";
+export {
+  toolcraftDiscreteCombinationBudget,
+  toolcraftDiscreteDimensionBudget,
+} from "./performance-fixture-discrete-search";
+export {
+  compileToolcraftPerformanceFixturePlan,
+} from "./performance-fixture-plan";
+export {
+  executeToolcraftPerformanceFixtureCheckpoint,
+} from "./performance-fixture-execution";
+export { areToolcraftFixtureValuesEqual } from "./performance-fixture-numeric";

package/templates/starter/AGENTS.md

@@ -1,5 +1,7 @@
 # Toolcraft App Template Assembly Guide
 
+<!-- toolcraft-performance-lifecycle: first-delivery=functional; later-delivery=functional-targeted; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only -->
+
 This is a standalone Toolcraft template app generated from the base starter.
 
 ## Required Preflight
@@ -12,14 +14,14 @@ Treat this `AGENTS.md` as the active project contract. Before planning or editin
 4. Read their Implementation phase immediately before editing code.
 5. Read their Verification phase before writing or running proof.
 
-Process matching routes sequentially within the current phase and skip repeated documents already read in that phase. Open exactly one listed document per terminal or tool read, including documents from the same route and phase. Do not concatenate multiple documents, routes, or phases into one large output, and never continue from truncated output. Choose and record the verification tier before implementation. Do not edit implementation files until the Plan and Implementation preflight is complete.
+Process matching routes sequentially within the current phase and skip repeated documents already read in that phase. Open exactly one listed document per terminal or tool read, including documents from the same route and phase. Do not concatenate multiple documents, routes, or phases into one large output, and never continue from truncated output. Choose and record one verification tier for the coherent user-visible delivery batch before implementation. Do not edit implementation files until the Plan and Implementation preflight is complete.
 
 ## Quick Entry Contract
 
 1. Build through `defineToolcraft` and `ToolcraftApp`.
 2. Keep app state in Toolcraft runtime schema and commands.
-3. Keep product output in `canvasContent`; never render app UI there. The signed host owns `ToolcraftApp`, bootstrap, routes, and global runtime styles; product code supplies only `ToolcraftAppComposition`. If upload/import is part of the source-material flow, do not invent canvas placeholder artwork, CTA copy, helper text, fake sample output, or preset source designs before real content exists.
-4. Use built-in Toolcraft controls before custom controls.
+3. Keep product output in `canvasContent`; never render app UI there. The signed host owns `ToolcraftApp`, bootstrap, routes, and global runtime styles; product code supplies only `ToolcraftAppComposition`. Model upload preserves supported authored appearance from standalone files, folders, and bounded ZIP packages; declare typed `modelPresentation`, using runtime presentation by default and checked consumers for custom presentation. `renderDefaultCanvasMedia={false}` never hides runtime model layers. If upload/import is part of the source-material flow, do not invent canvas placeholder artwork, CTA copy, helper text, fake sample output, or preset source designs before real content exists.
+4. Use built-in Toolcraft controls before custom controls. Before controls or canvas interactions, declare typed `interactionOwnership`: user request, inspected reference, or product usability selects one primary surface for each operation; complementary operations may share related state, but canvas and panel must not mirror the same operation. Every product also declares typed `viewInteraction` before renderer code; a visible editable spatial scene defaults to `orbit` and uses schema `orientationGizmo` plus runtime model-orbit interaction. Fixed or timeline-owned cameras require an explicit user request or inspected-reference evidence.
 5. Do not hand-compose runtime surfaces or render built-in control components directly in app code; use `ToolcraftApp`, schema controls, `canvasContent`, `controlRenderers`, `onPanelAction`, and runtime commands.
 6. Before writing controls, make and export `starterControlSectionInventory`: each product controls section declares its title, product entity or workflow stage, targets, and grouping reason. Group by product meaning, not UI component type.
 7. Keep control `label` short but semantically sufficient with the nearest visible section/group context, and put product-specific behavior help in schema `description`; runtime renders the label help tooltip only when that description adds meaning beyond the label.
@@ -27,20 +29,20 @@ Process matching routes sequentially within the current phase and skip repeated
 9. Animated preview renderers suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions, then resume without changing user playback state.
 10. If a Figma URL is provided, inspect the Figma file through MCP and rebuild from its structure; never implement from a screenshot or by eye.
 11. If a video, GIF, screen recording, contact sheet, or extracted-frame sequence is provided as a reference, write a Video Reference Study before implementation: storyboard frames, frame-to-frame transition analysis, behavior decomposition, and acceptance mapping. Do not implement video references from a single screenshot or high-level summary.
-12. Choose an explicit persistence policy; use schema `persistence` for user-edited app settings that should survive reload, and test real reload restoration when localStorage is enabled.
-13. Generated apps follow the mandatory runtime Setup, canvas sizing, render scale, Timeline switch, Background, Image Export, Video Export, and sticky action rules in `docs/toolcraft/core/setup-export.md`. Do not duplicate or reinterpret those controls in app-authored sections.
+12. Runtime workspace persistence is enabled locally by default: values, canvas, and panels are the base plan, while enabled timeline, layers, and media add their slices. `{ storage: "none" }` is the only opt-out and requires a recorded reason. Test exact resolved slices through a real reload; product code never writes localStorage or IndexedDB directly.
+13. Generated apps follow the mandatory runtime Setup, Infinity canvas/finite canvas sizing, render scale, Timeline switch, Background, Image Export, Video Export, and sticky action rules in `docs/toolcraft/core/setup-export.md`. Do not duplicate or reinterpret those controls in app-authored sections.
 14. Media uploads, image/file mode, source images, multi-upload sorting, default assets, and image transform actions follow `docs/toolcraft/core/media-upload.md`.
 15. Keep `docs/toolcraft/agent-worklog.md` current with a decision trail, product decisions, explicit reference inputs, evidence, verification, and risks. Reference-runtime-clone apps also declare `referenceStudy` plus `referenceFeatureInventory` so every inspected reference feature has feature-level behavior evidence and maps to Toolcraft implementation and acceptance coverage.
-16. Prove every visible entity through acceptance, browser, and performance coverage. Browser acceptance and performance pass only when protected helpers emit matching runtime evidence after successful assertions; source-code spelling and acceptance prose are not outcome authority. Declare typed conditional-visibility and background-output coverage, then use their fixed protected browser recipes. Generic acceptance outcomes prove command side effects only; use the fixed media, persistence, viewport, compound-control, layer, and timeline semantic recipes for specialized evidence.
-17. Performance workload, render scale, live slider responsiveness, GPU evaluation, and optimization evidence rules live in `docs/toolcraft/core/performance.md` plus `docs/toolcraft/performance.md`.
-18. Custom renderer apps declare a Render Pipeline Inventory in typed `rendererPipeline`: render passes, cache keys, execution location, preview/export quality, and interaction invalidation.
-19. Classify every implementation pass with a verification tier before editing. Use targeted checks for incremental edits and the full final gate only for final delivery, exports, or architecture/runtime/template changes.
+16. Prove every visible entity through acceptance, browser, and performance coverage. Browser acceptance and performance pass only when protected helpers emit matching runtime evidence after successful assertions; source-code spelling and acceptance prose are not outcome authority. Declare typed conditional-visibility and background-output coverage, then use their fixed protected browser recipes. Raster products with `canvas.renderScale` declare `renderScaleCoverage` for interaction and steady state, plus playback when timeline is enabled, and prove real backing pixels with `canvas-render-scale-backing`; clamping quality is a functional failure without measured performance. Generic acceptance outcomes prove command side effects only; use the fixed media, persistence, viewport, compound-control, layer, and timeline semantic recipes for specialized evidence.
+17. Performance planning follows one sequence: reachable controls and inputs; workload dimensions and enforced boundaries; pass cost, frequency, lifecycle, and invalidation; render-plan assessment and protected kernel benchmark when required; derived paths and combined fixtures; targeted functional/browser development checks; lifecycle-appropriate delivery proof. Keep `src/app/app-verification-impact.json` complete so later functional changes derive exact verification scope. Only exact request authority may create a measured targeted performance iteration. Details live in `docs/toolcraft/core/performance.md` and `docs/toolcraft/performance.md`.
+18. Custom renderer apps compile one canonical `rendererPipelineRegistration`, supply it through `ToolcraftAppComposition`, reuse that registration as `rendererPipeline` in performance assessment, and derive paths and fixtures from it. The neutral starter has no registration, runtime provider, or fixture adapters.
+19. Classify each coherent user-visible delivery batch with a verification tier before editing. Steering and fixes inside the same request stay in that batch. Use targeted checks for development feedback, then run the protected delivery gate once when the batch is ready.
 
 ## Starter Baseline
 
-The generated folder starts as a neutral Toolcraft shell: canvas upload plus toolbar. It intentionally does not include demo controls, prompt fields, layers, or timeline. Do not treat test fixtures or documentation examples as product requirements. Add controls, timeline, layers, sticky actions, persistence, and custom renderers only after the requested product or reference app requires them.
+The generated folder starts as a neutral Toolcraft shell: canvas upload plus toolbar. It intentionally does not include demo controls, prompt fields, layers, or timeline. Do not treat test fixtures or documentation examples as product requirements. Add controls, timeline, layers, sticky actions, and custom renderers only after the requested product or reference app requires them; base workspace persistence already exists.
 
-When the folder becomes a real product, update `src/app/app-acceptance-data.ts` from `appProductReadiness.mode: "starter"` to `mode: "product"` and fill `productName`, `productSummary`, and `requestedBehavior`. Renamed product folders are not allowed to keep neutral starter readiness.
+When the folder becomes a real product, update `src/app/app-acceptance-data.ts` from `appProductReadiness.mode: "starter"` to `mode: "product"` and fill `productName`, `productSummary`, `requestedBehavior`, typed `interactionOwnership`, and typed `viewInteraction`. Compare canvas and panel for each operation that could plausibly live on either surface. A visible editable 3D scene uses `orbit`; `fixed-camera` and `timeline-camera` require explicit request/reference evidence. Renamed product folders are not allowed to keep neutral starter readiness.
 
 ## License
 
@@ -55,7 +57,7 @@ Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app m
 - `docs/toolcraft/assembly-workflow.md` — runtime assembly, canvas output, and reference clone path.
 - `docs/toolcraft/decision-contract.md` — rule ids, levels, and enforcement expectations.
 - `docs/toolcraft/schema-reference.md` — schema authoring rules for `src/app/app-schema.ts`.
-- `docs/toolcraft/component-rules.md` — slider, segmented, color, upload, image picker, vector, layers, timeline, and footer action rules.
+- `docs/toolcraft/component-rules.md` — slider, segmented, color, upload, image picker, vector, orientation gizmo, layers, timeline, and footer action rules.
 - `docs/toolcraft/acceptance-testing.md` — app entity matrix and browser acceptance for `src/app/app-acceptance-data.ts`.
 - `docs/toolcraft/performance.md` — performance roles, scenarios, and workload coverage for `src/app/app-performance.ts`.
 - `docs/toolcraft/renderer-technique.md` — DOM, SVG, Canvas 2D, WebGL, and mixed renderer choices.
@@ -73,10 +75,12 @@ Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app m
 - Keep `src/app/app-acceptance-data.ts` aligned with every visible product entity.
 - Do not edit `src/app/app-acceptance.ts`, `src/app/acceptance`, supplied `app-acceptance.*` meta-tests, or the generic browser acceptance harness. They are framework-owned files covered by the signed integrity manifest; add product-specific Vitest and Playwright tests in separate app-owned files.
 - Keep `src/app/app-performance.ts` as app-specific performance matrix config only.
+- Keep `src/app/app-verification-impact.json` aligned with every product production module, nearest acceptance coverage, and renderer pass. Classify presentation, functional, and performance ownership there; do not infer verification scope from filenames during a later iteration.
+- Use `e2e/app-kernel-benchmarks.ts` only for executable candidates required by `assessToolcraftRenderPlan`, then run protected `pnpm verify:kernel`. Do not put authored timing evidence in product files.
 - Do not paste, restore, or duplicate runtime validators inside `src/app/app-performance.ts`.
 - Do not edit the generated contract files under `docs/toolcraft` or the generated `LICENSE.md` and `NOTICE.md`; they are framework-owned and covered by the signed integrity manifest. `docs/toolcraft/agent-worklog.md` is the explicit editable exception for product decisions and verification evidence.
 - Do not edit `src/toolcraft`. It is an immutable signed copy of the shared Toolcraft runtime; change the monorepo runtime and regenerate the app instead.
-- Before final delivery, replace the starter worklog with `Mode: product`, add `Decision Trail` entries for significant implementation passes, and record concrete decisions for renderer, timeline, layers, controls, export, and performance. Each decision-trail iteration must name the user-visible result, source/reference checked, contract rules applied, rejected alternatives, and state/output mapping. `pnpm test` fails if the worklog is missing, lacks the decision trail, or still describes the neutral starter.
+- Before delivery, replace the starter worklog with `Mode: product`, add one `Decision Trail` entry per coherent user-visible delivery batch, and record concrete decisions for renderer, timeline, layers, controls, export, and performance. Each entry keeps human intent: request, user-visible result, source/reference checked, contract rules applied, rejected alternatives, state/output mapping, known risks, and domain-shaped performance authority when applicable. Protected receipts own changed files, the plan, executed checks, reports, measurements, and pass/fail evidence. `pnpm test` fails if the worklog is missing, lacks the decision trail, or still describes the neutral starter.
 - `pnpm test` includes Toolcraft source integrity and local docs checks. If a desired control style is missing, fix the schema or regenerate from the upstream template/runtime; do not patch copied `src/toolcraft` files for one app.
 
 ## Decision Contract Rule IDs
@@ -87,7 +91,9 @@ These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep th
 - `runtime-shell-required`
 - `canvas-no-app-ui`
 - `canvas-surface-preserved`
+- `infinity-canvas-scene-bounds`
 - `canvas-handle-placement`
+- `interaction-surface-ownership`
 - `panel-host-behavior`
 - `layers-enable-only-when-needed`
 - `layers-enabled-behavior`
@@ -99,6 +105,8 @@ These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep th
 - `controls-component-layout-invariants`
 - `controls-layout-heuristics`
 - `renderer-technique-inventory`
+- `renderer-view-interaction`
+- `model-appearance-presentation`
 - `reference-clone-source-of-truth`
 - `video-reference-analysis`
 - `acceptance-product-observable`
@@ -111,9 +119,10 @@ These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep th
 
 - Use `defineToolcraft` from `@/toolcraft/runtime`.
 - Export an `appComposition` satisfying `ToolcraftAppComposition` from `src/app/app-composition.tsx`.
-- Keep product composition limited to `schema`, `canvasContent`, `controlRenderers`, `onPanelAction`, and `renderDefaultCanvasMedia`; host `className` and `style` are not product extension points.
+- Keep product composition limited to `schema`, `canvasContent`, `controlRenderers`, `modelPresentation`, `onPanelAction`, `renderDefaultCanvasMedia`, and optional `rendererPipelineRegistration`; host `className` and `style` are not product extension points.
+- Custom renderers use one compiled `rendererPipelineRegistration` as the canonical declaration for runtime execution and new-envelope performance assessment. Product code receives only the disposal-free pipeline client through hooks and panel action context.
 - Do not import `ToolcraftApp`, low-level runtime surfaces, or built-in controls into product modules. The signed host renders the shell; product modules use schema controls and supported composition fields.
-- Use `renderDefaultCanvasMedia={false}` when a custom renderer replaces the default media preview.
+- Use `renderDefaultCanvasMedia={false}` when a custom renderer replaces generic image/file preview. This flag does not suppress runtime model layers; use typed `modelPresentation` custom mode with checked consumers for declared model targets.
 - Use `ToolcraftApp onPanelAction` for sticky footer product actions such as Generate, Apply, Export, Copy, or Download.
 - Keep final app behavior in the schema and runtime command bus, not in isolated local control state.
 - For animated products, write an Animation Intent Inventory before coding: use top playback timeline for product transport, keyframes timeline for editable property animation, and no timeline only for explicitly autonomous decorative output with no video export. Any app with `Export Video` must enable the top Toolcraft timeline.
@@ -129,8 +138,8 @@ The signed local `AGENTS.md` and `docs/toolcraft/*` files are the mandatory work
 - Before editing code from an approved spec, use `writing-plans` to produce a deterministic implementation plan focused on app files, tests, build, and browser verification.
 - Before fixing any broken control, failed test, build failure, visual mismatch, export issue, or runtime regression, use `systematic-debugging` to find the root cause first.
 - When the prompt includes a Figma URL, use Figma MCP/design context before implementation. Read the actual node, layer, component, variable, and asset structure; screenshots are only for final visual QA, not the source of truth.
-- After implementation, use the `browser` workflow or equivalent local browser verification to test the running app, not only typecheck/build output. The default browser gate is `pnpm test:browser`; it excludes every Playwright test whose name contains `browser perf:`, including performance audit and budget scenarios. `pnpm test:browser:perf` is reserved for full performance checkpoints.
-- Run `pnpm ai:check` before app generation or major changes. It enforces local code health, the product AST boundary, and external skill availability. With an explicit `--no-install` generation the AST pass reports that it is deferred; normal `pnpm test` and every final gate require installed dependencies and run the full boundary.
+- After implementation, use the `browser` workflow or equivalent local browser verification to test the running app, not only typecheck/build output. The default browser gate is `pnpm test:browser`; it excludes every Playwright test whose name contains `browser perf:`. Protected delivery owns exact targeted performance iterations. The complete matrix is reserved for the operator/CI `pnpm verify:perf` command.
+- Run `pnpm ai:check` before app generation or major changes. It enforces local code health and the product AST boundary. With an explicit `--no-install` generation the AST pass reports that it is deferred; normal `pnpm test` and every final gate require installed dependencies and run the full boundary.
 - If a workflow skill is missing and installation is available, install it and refresh the session. If installation is unavailable or the app was generated with `--no-skills`, continue through the equivalent signed local workflow instead of stopping or weakening verification.
 - Do not silently ignore a missing workflow capability: follow the matching local requirement in this file and `docs/toolcraft/workflow.md`, and record the fallback in the implementation plan or worklog.
 - The Toolcraft app contract overrides generic brainstorming approval and visual-companion rituals. If the user asks to build or port an app, that request is approval to produce the spec, plan, implementation, tests, build, and local run unless a product-critical ambiguity remains.
@@ -140,7 +149,7 @@ The signed local `AGENTS.md` and `docs/toolcraft/*` files are the mandatory work
 
 ## Verification Tier Classifier
 
-Before editing, write a short verification note:
+Before editing, write one short verification note for the coherent delivery batch:
 
 ```md
 Verification tier: Tier N
@@ -151,39 +160,38 @@ Skip: <checks not needed for this pass and why>
 
 Choose the tier by blast radius, not by line count. If uncertain, move one tier higher, not automatically to the full final gate.
 
-| Tier | Use When | Required Checks |
-| --- | --- | --- |
-| Tier 0 — docs/copy | Documentation, comments, copy, labels, or titles change without schema targets, values, runtime behavior, renderer output, or layout mechanics. | Targeted docs/typecheck or targeted app test. Browser is not required unless visual text fitting is the risk. |
-| Tier 1 — local control presentation | One control or panel visual state changes: spacing, hover, focus, disabled, marker visibility, label fit, or component variant display. Runtime state shape and product renderer are unchanged. | Targeted unit/component test plus one focused browser check for the affected control or panel. |
-| Tier 2 — schema/product behavior | Controls, sections, defaults, persistence, panel actions, export actions, acceptance rows, or product behavior mapping changes. | `pnpm verify:quick` plus relevant browser acceptance. Run perf only when the changed control affects renderer workload or responsiveness. |
-| Tier 3 — renderer/canvas/runtime feature | Custom renderer, animation loop, canvas sizing, upload/media, timeline, layers, toolbar, export bytes, WebGL/Canvas/SVG output, zoom, radar, history, heavy control behavior changes, or a post-generation iteration that touches renderer workload or viewport stability. | `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios only for touched workload/viewport/export paths. |
-| Tier 4 — final delivery/template architecture | Fresh generated app completion, folder export, commit-ready delivery, dependency changes, runtime/template/contract/CLI changes, broad refactors, or major post-generation iterations that rewrite renderer, canvas, animation, timeline/keyframes, layers, media, export, or control mapping. | Fresh folders run `pnpm install` once. For the first working product version, run the browser performance checkpoint first and record its current-source receipt, then run `pnpm verify:final`, then start `pnpm dev` to provide the local URL. |
+| Tier                                          | Use When                                                                                                                                                                                                                                                                                       | Required Checks                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tier 0 — docs/copy                            | Documentation, comments, copy, labels, or titles change without schema targets, values, runtime behavior, renderer output, or layout mechanics.                                                                                                                                                | Targeted docs/typecheck or targeted app test. Browser is not required unless visual text fitting is the risk.                                                                                                                                                                                                                                                          |
+| Tier 1 — local control presentation           | One control or panel visual state changes: spacing, hover, focus, disabled, marker visibility, label fit, or component variant display. Runtime state shape and product renderer are unchanged.                                                                                                | Targeted unit/component test plus one focused browser check for the affected control or panel.                                                                                                                                                                                                                                                                         |
+| Tier 2 — schema/product behavior              | Controls, sections, defaults, persistence, panel actions, export actions, acceptance rows, or product behavior mapping changes.                                                                                                                                                                | During development run relevant targeted tests and browser acceptance. At delivery, bare `pnpm verify:delivery` derives the required proof.                                                                                                                                                                                                                             |
+| Tier 3 — renderer/canvas/runtime feature      | Custom renderer, animation loop, canvas sizing, upload/media, timeline, layers, toolbar, export bytes, WebGL/Canvas/SVG output, zoom, radar, history, heavy control behavior changes, or a post-generation iteration that touches renderer workload or viewport stability.                     | During development run targeted functional and browser acceptance checks. The tier and changed surface do not authorize measured performance. At delivery, `verify:delivery` runs ownership-derived functional proof unless exact request authority creates one performance iteration.                                                                                                                                                                                                 |
+| Tier 4 — final delivery/template architecture | Fresh generated app completion, folder export, commit-ready delivery, dependency changes, runtime/template/contract/CLI changes, broad refactors, or major post-generation iterations that rewrite renderer, canvas, animation, timeline/keyframes, layers, media, export, or control mapping. | Fresh folders run `pnpm install` once. Run `pnpm verify:delivery` once when the coherent batch is ready, then start `pnpm dev`. Its protected lifecycle selects functional proof or an exact targeted performance iteration from the request and prior receipt state.                                                                                                                     |
 
 Do not rerun `pnpm install` after every edit. Run it after fresh export, dependency changes, lockfile changes, or a missing package error.
 
 Do not run the full browser performance suite for Tier 0-2 edits.
 
-Run a full performance checkpoint only when the first working version of an app exists, or when the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance. Prefer the current AI agent's controlled browser. Use `pnpm verify:perf` only when no agent-controlled browser is available or when running CI/non-agent automation.
+The automatic lifecycle is sequential. First product delivery uses bare `pnpm verify:delivery` for complete product contracts, one production build, full functional acceptance, and zero measured performance. Later delivery is functional-targeted: it compares the immediately previous and current semantic functional proof models and derives exact direct-owner, domain, and affected-unit-graph proof. A performance complaint may authorize one targeted iteration; a full audit remains explicit-only. The canonical selection and evidence rules live in `docs/toolcraft/workflow.md`, `docs/toolcraft/acceptance-testing.md`, and `docs/toolcraft/performance.md`; do not duplicate their algorithm here.
 
-Feature loops after the first working version do not run the full performance suite by default. Renderer, canvas, animation, export, timeline, layers, `canvas.renderScale`, bug fixes, and performance-sensitive controls still need targeted functional/browser checks first, plus targeted performance scenarios only when they directly exercise the touched workload/viewport/export path. Record any skipped full performance run and reason in the verification note or worklog.
+Feature loops after the first working version run only the smallest focused functional and browser checks while implementation is changing, then one bare `verify:delivery` at the coherent boundary. Do not rerun aggregate, export, or performance matrices after every edit. An unchanged `sourceHash` uses the protected fast path and does not recollect semantic proof inputs.
 
-The first working product app version is not complete until `pnpm verify:perf` has produced a current-source structured receipt and `pnpm verify:final` has passed against that receipt. Agent-controlled browser checks remain useful for targeted diagnosis and visual verification, but terminal prose cannot mint the machine receipt. Worklog prose is context, not execution proof. After the first working version, a skipped full performance run is valid only through `pnpm verify:perf:record-exemption -- --tier=<0|1|2>`, backed by a prior passed receipt, for a post-first-working non-performance edit.
+The app is not complete until bare `pnpm verify:delivery` produces the lifecycle-appropriate protected receipt. An initial functional receipt proves complete functional acceptance without measured performance; later functional receipts prove exact ownership-derived checks. Agent-controlled browser checks remain useful for targeted diagnosis and visual verification, but terminal prose cannot mint or upgrade a receipt. The impact inventory derives the required checks and affected passes from the immediately previous successful delivery. Tier is human diagnostic vocabulary only and never grants execution authority.
 
 ## Required Checks
 
-For final delivery, run:
+For a coherent delivery batch, run:
 
 ```bash
-node scripts/check-toolcraft-integrity.mjs
-pnpm verify:final
+pnpm verify:delivery
 pnpm dev
 ```
 
-For the first working product delivery, run `pnpm verify:perf` before `pnpm verify:final`; its protected Playwright runner records the machine-verifiable receipt. Use the agent-controlled browser for targeted diagnosis and visual checks without treating it as a replacement receipt. The final gate rejects missing or stale receipts.
+The protected runner selects first-delivery functional proof, later `functional-targeted` ownership-derived proof, or one complaint-authorized targeted performance iteration from protected state. `pnpm verify:perf` is the separate operator/CI full-audit command; run it only after an explicit user request or accepted agent offer, never as an inferred continuation of a complaint.
 
 Use `pnpm install` before this final gate when the folder is fresh or dependencies changed.
 
-Run `node scripts/check-toolcraft-integrity.mjs` directly before the final gate; do not rely only on a package script to invoke it. `pnpm test` must also include `node scripts/check-toolcraft-docs.mjs`, `node scripts/check-toolcraft-integrity.mjs`, and app tests. `pnpm verify:ui` / `pnpm test:browser` must run against the real app UI and product output but must not run any Playwright test whose name contains `browser perf:`. `pnpm verify:perf` / `pnpm test:browser:perf` is the protected Playwright checkpoint for the two full-performance triggers; it must build and serve the current production bundle, then run the performance audit plus browser budget suite sequentially so budgets exclude dev-server transformation and unrelated parallel e2e noise.
+`verify:delivery` runs the protected integrity checker directly and does not depend only on a mutable package script. `pnpm test` includes local docs and app tests. The internal `pnpm test:browser` gate runs against the real app UI and product output but excludes Playwright tests whose names contain `browser perf:`. The protected full-audit path builds and serves the current production bundle, then runs the complete browser performance matrix sequentially so budgets exclude dev-server transformation and unrelated parallel e2e noise.
 
 Do not stop or kill existing local servers to free a port during a first start. `pnpm dev`, `pnpm preview`, and browser verification prefer port `3002`, but automatically move to the next free port only while assigning this app's first saved port. After a saved port exists, normal `pnpm dev` / `pnpm preview` uses that same port; if that port is already serving this app, report that existing URL instead of starting a duplicate. Use `TOOLCRAFT_PORT`, `TOOLCRAFT_DEV_PORT`, or `TOOLCRAFT_TEST_PORT` only to change the preferred starting port before a saved port exists. A dev/preview launch is successful only after the selected port serves this app's Toolcraft server identity endpoint plus the `toolcraft-app-title` marker from `index.html`; never report a URL just because some server is listening there. When deliberately restarting this app server, use `pnpm dev:restart` or `pnpm preview:restart`; restart mode reuses the previously saved app port, stops the listener on that exact port if it is still running, force-stops it if it does not release the port, starts on the same port again, and verifies the identity before saving/reporting the port.
 
@@ -197,15 +205,15 @@ The app is complete only when:
 - every visible control affects runtime state and product output or a command side effect;
 - reset returns schema controls to `defaultValue`;
 - sticky footer export actions operate on final product output at `state.canvas.size`;
-- still products expose Export PNG; animated products expose Export Video plus Export PNG;
-- PNG export uses the required `Background` section with `Include` plus unlabeled background color runtime controls, live preview hides product background when Include is off, and video keeps background;
+- every product exposes Export PNG; products whose requested delivery includes animation also expose Export Video;
+- PNG export uses the background controls normalized into runtime Setup: `Background` beside `Infinity canvas`, then `Background color`; live preview hides product background when Background is off, and video keeps background;
 - every PNG export includes `Image Export` format/resolution `select` controls, and passes `export.image.resolution` into `createToolcraftPngExportCanvas`;
-- animated products with both PNG and video export place `Image Export` immediately before `Video Export`;
+- products with both PNG and video export place `Image Export` immediately before `Video Export`;
 - export paths use the standard export helpers: PNG uses selected image resolution or retina fallback, while video uses current canvas/output size or the selected 4K target;
 - layers are absent for single-layer apps and fully working when enabled;
 - timeline is absent, playback, keyframes, or custom reference timeline according to product behavior;
 - performance checks cover workload and responsiveness for all relevant controls;
 - detail-heavy or animated custom renderers pass real viewport drag and zoom stress checks;
-- workload browser perf tests use the declared `stressFixture` value from `app-performance.ts`, and apply `workloadFixture` first whenever the scenario declares an independent heavy app baseline;
+- workload browser perf tests execute the compiled development or maximum fixture for the canonical derived path, apply every adapter value through the real UI, and observe every dimension before measurement;
 - bounded numeric workload ranges and hard limits are derived from schema; scenario values cannot redefine them, custom metrics cannot bypass them, many-item fixtures apply at least 10 real items, and degraded ceilings prove every exact 10 percent step with matching scenario/target identity;
 - browser tests verify upload/clear, controls, canvas sizing, toolbar, timeline/layers when enabled, sticky actions, output dimensions, and viewport stability.