@pixel-point/toolcraft 0.0.13 → 0.0.15

package/templates/starter/docs/toolcraft/performance.md

@@ -1,5 +1,7 @@
 # Performance
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused performance reference for the topic below.
+
 Every visible non-action control needs a `performanceRole` and `performanceReason`.
 
 Performance coverage has two levels:
@@ -7,7 +9,9 @@ Performance coverage has two levels:
 - workload coverage for controls that change render cost;
 - responsiveness coverage for ordinary controls that still must not freeze input or break the viewport.
 
-The preferred browser performance runner is the current AI agent's controlled browser. Use `pnpm verify:perf` only as the Playwright fallback when no agent-controlled browser is available or in CI/non-agent automation.
+`maxInteractionMs` measures user action start through the first verified product-output/state response for mutating interactions, not merely pointer completion. Generic change measurements first prove a stable pre-action baseline. A live drag may then cross that baseline while the gesture continues: the first changed response sets latency, then the final post-action outcome must remain different through its stability window before evidence is emitted. Autonomous or animated products use a stable semantic `expectedOutcome` or a deterministic fixed playback phase; the next unrelated frame cannot count as response. Settle/stability time after the first response is not charged as first-response latency. The helper uses one runner monotonic clock and restarts frame sampling after document navigation. Non-mutating interactions use action completion.
+
+The preferred runner for targeted browser diagnosis is the current AI agent's controlled browser. The protected `pnpm verify:perf` Playwright checkpoint is the sole final machine authority that can record a passed current-source performance receipt.
 
 `app-performance.ts` must keep this policy:
 
@@ -19,7 +23,7 @@ browserCheckPolicy: {
 }
 ```
 
-Do not change the preferred runner to Playwright to make local automation easier; that reverses the contract. Playwright is portable fallback evidence, not the primary agent workflow.
+Do not change the preferred runner to Playwright merely to avoid agent-controlled diagnosis; that policy governs targeted investigation. It does not authorize a manual passed receipt: final performance proof comes only from the protected `pnpm verify:perf` checkpoint.
 
 ## Workload Coverage
 
@@ -49,9 +53,9 @@ Both fixture types must include:
 - `reason`: why this value is the heaviest useful product case;
 - `value`: the actual value the browser performance check will apply.
 
-Fixtures that represent numeric maximums, density, item counts, canvas/media size, or custom combined heavy states also declare `loadProfile`. This separates the product `hardLimit` from the `smoothTarget` that the browser performance checkpoint guarantees. `hardLimit` is the largest product range or tier the app exposes; `smoothTarget` is the value the browser performance check applies and must match `stressFixture.value` or `workloadFixture.value`.
+Fixtures that represent numeric maximums, density, item counts, canvas/media size, or custom combined heavy states also declare `loadProfile`. This separates the product `hardLimit` from the `smoothTarget` that the browser performance checkpoint guarantees. For bounded numeric controls, min/default/max and the hard limit are derived from schema; omit duplicated scenario `values`, or use `requireToolcraftSchemaPerformanceValues` when another fixture needs the same range. Supplied values must match schema exactly, and `metric: "custom"` cannot replace a numeric boundary. `smoothTarget` is the value the browser performance check applies and must match `stressFixture.value` or `workloadFixture.value`. A `many-items` fixture must apply at least 10 real items; an authored `minCount` cannot redefine a token fixture as heavy.
 
-Default to `smoothTargetRatio: 1`, which means the full hard limit must pass budgets. If the hard limit cannot pass after reasonable renderer and pipeline optimizations, lower the smooth target only in 10 percent steps (`0.9`, then `0.8`, and so on). Every lower step must include `loadProfile.evidence` with the failed higher target, measured result, optimization attempted, and decision. When `smoothTargetRatio < 1`, set `userFacingRange: "experimental-above-smooth"` so the range above the smooth target is not silently presented as guaranteed.
+Default to `smoothTargetRatio: 1`, which means the full hard limit must pass budgets. If the hard limit cannot pass after reasonable renderer and pipeline optimizations, lower the smooth target only in 10 percent steps (`0.9`, then `0.8`, and so on). Every skipped higher step has exactly one `loadProfile.evidence` entry with the exact `attemptedRatio`, schema-reachable `attemptedTarget`, matching scenario id and target, measured result, optimization attempted, and decision. When `smoothTargetRatio < 1`, set `userFacingRange: "experimental-above-smooth"` so the range above the smooth target is not silently presented as guaranteed.
 
 For multiline text, prompt, code, JSON, CSS, shader, script, or template workload controls, use `kind: "large-text"`. The fixture must contain at least `50_000` characters and `1_000` lines unless the product has a stricter real-world maximum.
 
@@ -59,17 +63,24 @@ For uploaded images, videos, source media, and image-processing workloads, use `
 
 Choose heavy fixtures from this app's real controls, not from generic examples. Derive the workload from four app-specific sources: schema controls and `performanceRole`, `rendererTechnique`, `rendererPipeline`, and real product stress values such as large text, source media dimensions, `canvas.renderScale`, canvas size, export resolution, animation speed, viewport interactions, and effect strength. Try the product hard limit first, then use a documented smooth target only when measured evidence shows the hard limit cannot be made smooth without changing product scope.
 
-Browser performance tests for workload and stress scenarios must read the scenario value through:
+Every `automatedTestName` and `browserTestName` must match exactly one product-owned test selected by the real Vitest or Playwright runner, and that test must finish passed. Comments, strings, local fake runners, focused/skipped tests, runtime skip/fixme/fail annotations, conditional declarations, and uncalled registration functions are not performance evidence.
+
+Browser slider stress tests apply the declared value through the protected helper:
 
 ```ts
-getToolcraftPerformanceStressValue(appPerformance, "scenario-id")
+await dragToolcraftSliderToPerformanceStressValue(
+  page,
+  "Control label",
+  appPerformance,
+  "scenario-id",
+)
 ```
 
-For workload sliders, the fallback Playwright test uses `dragToolcraftSliderToPerformanceStressValue(page, label, appPerformance, "scenario-id")` so the test applies the exact numeric value through the real slider min/max range. Agent-browser checks must apply the same value from `app-performance.ts`. Do not divide a stress value by the slider max, type a separate short value, or hardcode a runner-local ratio. If a browser check uses a toy value while `app-performance.ts` claims a heavy fixture, the performance checkpoint must fail.
+For non-slider scalar values, use `applyToolcraftPerformanceStressValue` with `{ applyValue, observeValue }`. The helper reads the exact scenario value and emits stress evidence only after `observeValue` equals that declared value. Agent-browser checks must apply the same value from `app-performance.ts`. Do not divide a stress value by the slider max, type a separate short value, hardcode a runner-local ratio, or claim application without observing the resulting UI/runtime state.
 
 Slider and range slider performance scenarios must preserve live product feedback. The browser test should drag the real thumb and verify the canvas/product output changes during drag. If that drag misses budget, keep the live control semantics and optimize the renderer path first: cache expensive inputs, update uniforms or stable buffers, coalesce preview work to `requestAnimationFrame`, cancel stale async renders, move work off React renders, reuse GPU resources, or change renderer strategy. Do not pass performance by making the slider update only after pointer release or Apply.
 
-When a scenario declares `workloadFixture`, apply it first with `getToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`, then apply `stressFixture`, then measure. A control-drag scenario that only sets its own slider value while leaving the source media, text, item count, render scale, or dense scene at defaults is invalid.
+When a scenario declares `workloadFixture`, apply it first with `applyToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`, then apply `stressFixture`, then measure. A control-drag scenario that only sets its own slider value while leaving the source media, text, item count, render scale, or dense scene at defaults is invalid.
 
 For combined worst cases, put every relevant independent baseline value in `workloadFixture.value` for control scenarios, such as `{ sourceMedia: { width: 3840, height: 2160 }, renderScale: 2 }`, and put the tested control value in `stressFixture.value`. For preview, zoom, drag, animation, or export scenarios that stress the entire state instead of one control, use `stressFixture.value`, such as `{ detail: 96, scale: 0.6, renderScale: 2 }`. Testing workload controls one-by-one is not enough when the product exposes combinations that multiply render cost.
 
@@ -77,16 +88,24 @@ Use `kind: "custom"` only for combined object fixtures. Single numeric/string he
 
 ```ts
 await applyToolcraftPerformanceStressFixture(page, appPerformance, "scenario-id", {
-  detail: async (value) => {
-    await dragToolcraftSliderToValue(page, "Detail", Number(value));
+  detail: {
+    applyValue: async (value) => {
+      await dragToolcraftSliderToValue(page, "Detail", Number(value));
+    },
+    observeValue: async () =>
+      Number(await page.getByRole("slider", { name: "Detail" }).getAttribute("aria-valuenow")),
   },
-  scale: async (value) => {
-    await dragToolcraftSliderToValue(page, "Scale", Number(value));
+  scale: {
+    applyValue: async (value) => {
+      await dragToolcraftSliderToValue(page, "Scale", Number(value));
+    },
+    observeValue: async () =>
+      Number(await page.getByRole("slider", { name: "Scale" }).getAttribute("aria-valuenow")),
   },
 });
 ```
 
-The applier object must contain exactly one entry for each key in `stressFixture.value`. Missing keys and stale extra keys are test failures, so every heavy-state part is intentionally mapped through the real UI before measurement.
+The applier object contains exactly one entry for each key in `stressFixture.value`, and each entry provides both `applyValue` and `observeValue`. Missing keys, stale extra keys, or an observed value that differs from the declared fixture are test failures, so every heavy-state part is proved through the real UI before measurement.
 
 For `workloadFixture.value` object fixtures, use `applyToolcraftPerformanceWorkloadFixture` with the same exact-key rule. `workloadFixture` is the app baseline; `stressFixture` is the action under test.
 
@@ -153,6 +172,15 @@ Use real interactions for:
 - `viewport-zoom-stress` for detail-heavy or animated custom renderers;
 - `viewport-stability`.
 
+Every `export-copy` scenario declares `actionValue` with the exact `panelActions`
+value, `controlLabel` for its visible button, and `completionEvidence` set to
+`download` or `clipboard`. Its browser test uses the corresponding protected
+`measureToolcraftDownloadActionByLabel` or
+`measureToolcraftClipboardActionByLabel` helper with `scenarioId`. The helper
+owns the real click and completion event; the signed runtime-evidence reporter
+rejects missing completion, skipped/failed tests, and evidence from failed
+retries.
+
 For `slider` and `rangeSlider`, the required performance scenario is `control-drag`. A `control-change` scenario can cover selects, inputs, toggles, and other non-drag controls, but it does not prove live canvas feedback or drag smoothness for sliders.
 
 Animated custom renderers also need `animation-viewport-drag`. Animation-only frame sampling and viewport-only stability are not enough: the browser test must sample frames while physically dragging or panning the canvas viewport. If SVG/DOM cannot pass that combined budget, choose a different renderer strategy from evidence instead of loosening the budget.
@@ -165,16 +193,16 @@ During canvas drag, pan, pinch, zoom, and radar/center interactions, animated pr
 
 Animation checks should sample enough frames to catch jank. Interaction budgets must match scenario type rather than using one universal number.
 
-Use `app-performance.ts` as the single budget and fixture source. Browser performance tests must call `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` for workload values and `expectToolcraftScenarioPerformanceBudget(..., appPerformance, scenarioId)` for budgets.
+Use `app-performance.ts` as the single budget and fixture source. Mutating measurements pass `scenarioId` and a structured-cloneable `observeOutcome`; generic change mode proves a stable baseline before the action, its first changed response sets latency, and its final post-action outcome must remain different through the stability window. For autonomous output, pass `expectedOutcome` and observe a stable semantic state, or fix playback to a deterministic phase; latency is measured to that expected result. Scalar fixtures are applied and observed through `applyToolcraftPerformanceStressValue` / `applyToolcraftPerformanceWorkloadValue`; object fixtures use `applyToolcraftPerformanceStressFixture` / `applyToolcraftPerformanceWorkloadFixture`, apply every declared key, then re-observe the complete final state before evidence can attach. Budget checks await `expectToolcraftScenarioPerformanceBudget`. Completed measurements are frozen and branded for one scenario, so a mutable literal or another scenario's result cannot satisfy the gate.
 
-Run targeted performance scenarios for Tier 3 performance-sensitive edits when they directly exercise the touched workload, viewport, or export path. The default `pnpm test:browser` / `pnpm verify:ui` gate excludes every Playwright test whose name contains `browser perf:`, including the performance audit and budget scenarios. The full performance checkpoint prefers the current AI agent's controlled browser. `pnpm verify:perf` is the Playwright fallback suite; it runs every `browser perf:` scenario with one worker so budget failures are not hidden or created by unrelated parallel browser tests.
+Run targeted performance scenarios for Tier 3 performance-sensitive edits when they directly exercise the touched workload, viewport, or export path. The default `pnpm test:browser` / `pnpm verify:ui` gate excludes every Playwright test whose name contains `browser perf:`, including the performance audit and budget scenarios. Use the current AI agent's controlled browser for targeted diagnosis. `pnpm verify:perf` is the protected final Playwright checkpoint; it builds the current production bundle, serves it through Vite preview, and runs every `browser perf:` scenario with one worker so budgets measure shipped runtime work instead of dev-server transformation and are not distorted by unrelated parallel browser tests.
 
 Run a full performance checkpoint only when:
 
 - the first working version of the app exists;
 - the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
 
-For the first working product app, this checkpoint is mandatory: the app is not complete until `pnpm verify:final` and the browser performance checkpoint have both passed and the worklog records the runner as `agent-browser` or `playwright-fallback`. Use `pnpm verify:perf` only as the fallback when no agent-controlled browser is available or in CI/non-agent automation.
+For the first working product app, this checkpoint is mandatory and runs before `pnpm verify:final`. Run `pnpm verify:perf`; its protected Playwright runner records the current-source machine receipt automatically. Agent-controlled browser checks remain preferred for quick diagnosis and visual investigation, but they cannot mint or replace the final receipt. The final gate rejects a missing or stale receipt. Worklog prose remains decision context and cannot substitute for the structured receipt. A post-first-working non-performance exemption must use `pnpm verify:perf:record-exemption -- --tier=<0|1|2>` and requires a prior passed receipt.
 
 Performance fixes must preserve selected output and preview quality. Do not pass budgets by lowering image quality, selected `canvas.renderScale`, export resolution, source media fidelity, or canvas backing pixels unless the user explicitly chooses that lower-quality value through a visible control. Prefer coalescing slider updates, caching expensive inputs, moving work off the React render path, reusing GPU resources, or changing renderer strategy over reducing visual fidelity.
 

package/templates/starter/docs/toolcraft/renderer-technique.md

@@ -1,5 +1,7 @@
 # Renderer Technique
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused renderer reference for the topic below.
+
 Choose render technology per product layer. Do not choose a renderer because it is convenient; choose it from product output semantics, reference behavior, fidelity, and workload.
 
 The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery. Do not make a renderer look fast by silently reducing the selected preview scale, backing pixels, source media quality, or export fidelity.