@pixel-point/toolcraft 0.0.13 → 0.0.15

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

@@ -17,22 +17,30 @@ Before planning or editing app code, runtime code, controls, canvas, panels, ren
 
 Do not edit implementation files until this preflight is complete.
 
+## Local Contract Authority
+
+The signed local `AGENTS.md` plus `docs/toolcraft/*` are sufficient and mandatory workflow input for a standalone generated app. External workflow skills should be used when available, but missing skills never invalidate `--no-skills` generation and never justify skipping the equivalent local spec, plan, debugging, browser, or verification requirement. `pnpm ai:check` enforces local code health and reports missing external skills as actionable guidance rather than a build failure.
+
+Core modules are required reading when listed by the routing table. Read each listed module fully, one phase at a time. Open exactly one listed document per terminal or tool read, even when several documents belong to the same route and phase. Do not concatenate documents or rely on a truncated excerpt; finish the current phase, then open the next phase when the work reaches it. The signed host and runtime validators enforce platform boundaries, while product organization remains open inside those boundaries.
+
 ## Task Routing
 
-Use the smallest reading set that covers the changed surface. If a task touches multiple surfaces, combine every matching row instead of picking only the closest one.
-
-| Task type | Read before editing |
-| --- | --- |
-| App assembly, route structure, generated app porting | `assembly-workflow.md`, `decision-contract.md` |
-| Reference app study, audit, or port | `assembly-workflow.md`, `schema-reference.md`, `acceptance-testing.md`, `decision-contract.md` |
-| Schema, controls, defaults, persistence, actions | `schema-reference.md`, `component-rules.md`, `acceptance-testing.md` |
-| Custom controls | `custom-controls.md`, `component-rules.md`, `acceptance-testing.md` |
-| Renderer, canvas output, visual technique | `renderer-technique.md`, `performance.md`, `acceptance-testing.md` |
-| Timeline, keyframes, animation transport | `decision-contract.md`, `component-rules.md`, `acceptance-testing.md`, `performance.md` |
-| Layers | `decision-contract.md`, `component-rules.md`, `acceptance-testing.md` |
-| Export, copy, media, background | `schema-reference.md`, `component-rules.md`, `acceptance-testing.md`, `performance.md` |
-| Broken control, visual mismatch, failed build, export bug, performance issue | `decision-contract.md`, the relevant component/runtime doc, and the failing test/log first |
-| Figma implementation | Use Figma MCP/design context, then `assembly-workflow.md` and the relevant component docs |
+Use the smallest route set that covers the changed surface. When a task matches multiple routes, process them sequentially inside the phase currently in progress and skip documents already read in that phase; open each document separately and never concatenate route documents into one terminal output. Read Plan documents before the spec or implementation plan, Implementation documents immediately before code, and Verification documents immediately before writing or running proof. A broken behavior still starts with the failing test, log, or reproduction before its Plan documents; a Figma task still starts with Figma MCP/design context.
+
+[//]: # (toolcraft-workflow-routes:start)
+| Task route | Plan phase | Implementation phase | Verification phase |
+| --- | --- | --- | --- |
+| App assembly, route structure, generated app porting | `core/runtime-boundary.md`<br>`assembly-workflow.md` | `decision-contract.md` | `acceptance-testing.md` |
+| Reference app study, audit, or port | `core/reference-study.md`<br>`core/runtime-boundary.md`<br>`assembly-workflow.md` | `schema-reference.md`<br>`decision-contract.md` | `acceptance-testing.md` |
+| Schema, controls, defaults, persistence, actions | `core/control-selection.md`<br>`core/layout.md` | `schema-reference.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Custom controls | `core/control-selection.md`<br>`core/layout.md` | `custom-controls.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Renderer, canvas output, visual technique | `core/runtime-boundary.md`<br>`core/performance.md` | `renderer-technique.md`<br>`performance.md` | `acceptance-testing.md` |
+| Timeline, keyframes, animation transport | `core/timeline-animation.md`<br>`core/performance.md` | `decision-contract.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Layers | `core/runtime-boundary.md`<br>`core/layout.md` | `decision-contract.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Export, copy, media, background | `core/setup-export.md`<br>`core/media-upload.md` | `schema-reference.md`<br>`component-rules.md` | `acceptance-testing.md`<br>`performance.md` |
+| Broken control, visual mismatch, failed build, export bug, performance issue | `decision-contract.md`<br>`core/runtime-boundary.md` | `component-rules.md`<br>`renderer-technique.md` | `acceptance-testing.md`<br>`performance.md` |
+| Figma implementation | `core/reference-study.md`<br>`core/runtime-boundary.md`<br>`assembly-workflow.md` | `schema-reference.md`<br>`component-rules.md` | `acceptance-testing.md` |
+[//]: # (toolcraft-workflow-routes:end)
 
 ## Worklog Gate
 
@@ -68,6 +76,8 @@ Use the runtime extension points described in the current contracts:
 
 Do not recreate controls, panels, toolbar, timeline, layers, canvas shell, or runtime surfaces by hand. If a shared behavior is wrong, fix the shared runtime/template source and regenerate when needed.
 
+Browser verification is outcome-based. Protected helpers attach versioned evidence only after a persistent observable change, an observed fixture application, a decoded non-empty export inspection, a completed output action, an immutable scenario measurement, and its matching budget check. The signed reporter derives required evidence from acceptance and performance config and fails skipped, missing, duplicate, transient, unmeasured, or unbudgeted scenarios.
+
 ## Verification Gate
 
 Choose the tier from `AGENTS.md` before editing. Use the tier to decide checks.
@@ -75,7 +85,7 @@ Choose the tier from `AGENTS.md` before editing. Use the tier to decide checks.
 - Tier 0-1: targeted docs/typecheck/unit plus focused browser when visual.
 - Tier 2: `pnpm verify:quick` plus relevant browser acceptance.
 - Tier 3: `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios only for touched workload/viewport/export paths.
-- Tier 4: `pnpm verify:final`; for the first working product version also run and pass a browser performance checkpoint with the current AI agent's controlled browser when available, using `pnpm verify:perf` only as fallback, then start `pnpm dev` for the local URL.
+- Tier 4: run `node scripts/check-toolcraft-integrity.mjs` directly. For the first working product version, run the browser performance checkpoint and record its current-source receipt first, then run `pnpm verify:final`, then start `pnpm dev` for the local URL.
 
 Run a full performance checkpoint only when:
 
@@ -84,4 +94,4 @@ Run a full performance checkpoint only when:
 
 Fast 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 path. Record any skipped full performance run and reason in the worklog.
 
-The app is not complete when required checks are failed, incomplete, pending, blocked, or listed as skipped. First working product delivery must record `pnpm verify:final` and the browser performance checkpoint as passed in the worklog, including runner `agent-browser` or `playwright-fallback`. After the first working version, skipping the full performance suite is valid only when the worklog explicitly says the full performance checkpoint is not required for a post-first-working non-performance edit.
+The app is not complete when required checks are failed, incomplete, pending, blocked, or listed as skipped. Run the integrity checker directly before the final gate so verification does not depend only on mutable package-script dispatch. First working product delivery runs `pnpm verify:perf` before `pnpm verify:final`; the protected Playwright checkpoint records the machine receipt, while agent-controlled browser work remains targeted diagnostic evidence. `verify:final` rejects missing or stale receipts. After the first working version, use the typed `pnpm verify:perf:record-exemption -- --tier=<0|1|2>` path only for a post-first-working non-performance edit backed by a prior passed receipt.

package/templates/starter/e2e/app-browser-acceptance-evidence.spec.ts

@@ -0,0 +1,111 @@
+import { expect, test, type TestInfo } from "@playwright/test";
+
+import { expectToolcraftAcceptanceOutcome, expectToolcraftExportedArtifact } from "./browser-acceptance-outcome-helpers";
+
+test("acceptance outcome rejects a return to its baseline during stability sampling", async () => {
+  let actionStarted = false;
+  let postActionObservations = 0;
+
+  await expect(
+    expectToolcraftAcceptanceOutcome(
+      async () => {
+        if (!actionStarted) return "before";
+        postActionObservations += 1;
+        return postActionObservations === 1 ? "after" : "before";
+      },
+      async () => {
+        actionStarted = true;
+      },
+      {
+        evidenceType: "command-side-effect",
+        requirementId: "command.delayed-transient",
+        stabilityIntervalMs: 0,
+      },
+    ),
+  ).rejects.toThrow(/stability window/i);
+});
+
+test("acceptance outcome snapshots a reused mutable observation", async ({}) => {
+  const outcome = { value: "before" };
+
+  await expect(
+    expectToolcraftAcceptanceOutcome(
+      async () => outcome,
+      async () => {
+        outcome.value = "after";
+      },
+      {
+        evidenceType: "command-side-effect",
+        requirementId: "command.mutable-observation",
+        stabilityIntervalMs: 0,
+      },
+    ),
+  ).resolves.toEqual({ value: "after" });
+});
+
+test("generic acceptance outcomes cannot claim specialized runtime evidence", async ({
+  page,
+}) => {
+  await page.setContent('<div id="outcome">before</div>');
+
+  await expect(
+    expectToolcraftAcceptanceOutcome(
+      () => page.locator("#outcome").textContent(),
+      () =>
+        page.locator("#outcome").evaluate((node) => {
+          node.textContent = "after";
+        }),
+      {
+        evidenceType: "timeline-duration" as never,
+        requirementId: "timeline.duration",
+      },
+    ),
+  ).rejects.toThrow(/specialized evidence/i);
+});
+
+test("export evidence requires a typed positive artifact inspection", async ({}, testInfo: TestInfo) => {
+  const attachmentCount = testInfo.attachments.length;
+
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ ok: true }),
+      { requirementId: "export.nominal-object" },
+    ),
+  ).rejects.toThrow(/byteLength/i);
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ byteLength: 0 }),
+      { requirementId: "export.zero-bytes" },
+    ),
+  ).rejects.toThrow(/positive byteLength/i);
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ byteLength: 2.5 }),
+      { requirementId: "export.fractional-bytes" },
+    ),
+  ).rejects.toThrow(/byteLength integer/i);
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ byteLength: 3, width: 1.5 }),
+      { requirementId: "export.fractional-width" },
+    ),
+  ).rejects.toThrow(/width integer/i);
+  expect(testInfo.attachments).toHaveLength(attachmentCount);
+
+  await expectToolcraftExportedArtifact(
+    async () => new Uint8Array([1, 2, 3]),
+    async (artifact) => ({
+      byteLength: artifact.byteLength,
+      contentHash: "pixel-hash",
+      height: 1,
+      mediaType: "image/png",
+      width: 1,
+    }),
+    { requirementId: "export.valid-inspection" },
+  );
+  expect(testInfo.attachments).toHaveLength(attachmentCount + 1);
+});

package/templates/starter/e2e/app-browser-control-coverage.spec.ts

@@ -0,0 +1,118 @@
+import { expect, test } from "@playwright/test";
+import type { ToolcraftPerformanceConfig } from "@repo/toolcraft-runtime";
+
+import { parseToolcraftBrowserRuntimeEvidence } from "../src/app/test-evidence/browser-runtime-contract";
+import { expectToolcraftExportedArtifact } from "./browser-acceptance-outcome-helpers";
+import {
+  dragToolcraftSliderToPerformanceStressValue,
+  expectToolcraftSegmentedControlCellsPreservePadding,
+  getToolcraftFieldByLabel,
+} from "./performance-helpers";
+
+test("segmented layout helper catches paddingless or colliding cells", async ({ page }) => {
+  await page.setContent(`
+    <div data-slot="field">FX Preset
+      <div data-slot="toggle-group" style="display:flex;width:360px;">
+        <button data-slot="toggle-group-item" style="box-sizing:border-box;width:120px;padding:0 12px;">One</button>
+        <button data-slot="toggle-group-item" style="box-sizing:border-box;width:120px;padding:0 12px;">Two</button>
+        <button data-slot="toggle-group-item" style="box-sizing:border-box;width:120px;padding:0 12px;">Off</button>
+      </div>
+    </div>
+  `);
+
+  await expectToolcraftSegmentedControlCellsPreservePadding(page, "FX Preset");
+
+  await page.setContent(`
+    <div data-slot="field">FX Preset
+      <div data-slot="toggle-group" style="display:flex;width:180px;">
+        <button data-slot="toggle-group-item" style="box-sizing:border-box;width:60px;padding:0;">Full Stack</button>
+        <button data-slot="toggle-group-item" style="box-sizing:border-box;width:60px;padding:0;">RGB Split</button>
+        <button data-slot="toggle-group-item" style="box-sizing:border-box;width:60px;padding:0;">Lines</button>
+      </div>
+    </div>
+  `);
+
+  await expect(
+    expectToolcraftSegmentedControlCellsPreservePadding(page, "FX Preset"),
+  ).rejects.toThrow(/must preserve cell padding/);
+});
+
+test("performance helpers match control labels literally", async ({ page }) => {
+  await page.setContent(`
+    <div data-slot="field" data-testid="literal-label">Size (px)<input type="range" /></div>
+    <div data-slot="field" data-testid="regex-lookalike">Size px<input type="range" /></div>
+  `);
+
+  await expect(await getToolcraftFieldByLabel(page, "Size (px)")).toHaveAttribute(
+    "data-testid",
+    "literal-label",
+  );
+});
+
+test("slider stress helper applies the declared value and emits runtime evidence", async ({
+  page,
+}, testInfo) => {
+  await page.setContent(`
+    <div data-slot="toolcraft-runtime-app">
+      <div class="contents" data-toolcraft-control-target="density.value">
+        <div data-slot="field">Density
+          <input data-slot="slider" role="slider" type="range" min="0" max="10" value="0" style="width:200px;height:20px;" />
+        </div>
+      </div>
+    </div>
+  `);
+  const config = {
+    rendererStrategy: "none",
+    rendererWorkload: "none",
+    scenarios: [{
+      automated: true,
+      automatedTestName: "perf: density stress",
+      browser: true,
+      browserTestName: "browser perf: density stress",
+      budget: { maxInteractionMs: 500 },
+      expectedObservable: "Density drag completes.",
+      fixture: "Density stress fixture.",
+      id: "density-stress",
+      interaction: "control-drag",
+      stressFixture: { kind: "max-value", reason: "Maximum density.", value: 9 },
+      target: "density.value",
+      workload: true,
+    }],
+    usesCustomRenderer: false,
+    workloadTargets: ["density.value"],
+  } as const satisfies ToolcraftPerformanceConfig;
+
+  await dragToolcraftSliderToPerformanceStressValue(
+    page,
+    "Density",
+    config,
+    "density-stress",
+  );
+
+  expect(
+    testInfo.attachments.map((attachment) =>
+      parseToolcraftBrowserRuntimeEvidence(attachment)?.evidenceType,
+    ),
+  ).toEqual(expect.arrayContaining([
+    "performance-control-drag",
+    "performance-stress-fixture",
+  ]));
+});
+
+test("export acceptance rejects a verifier that does not return an artifact observation", async () => {
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({}),
+      { requirementId: "image-export-artifact" },
+    ),
+  ).rejects.toThrow(/artifact inspection/i);
+
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => undefined,
+      async () => ({ byteLength: 1 }),
+      { requirementId: "missing-export-artifact" },
+    ),
+  ).rejects.toThrow(/non-empty export artifact/i);
+});

package/templates/starter/e2e/app-browser-performance-evidence.spec.ts

@@ -0,0 +1,217 @@
+import { expect, test, type TestInfo } from "@playwright/test";
+
+import {
+  TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_ATTACHMENT_NAME,
+  parseToolcraftBrowserRuntimeEvidence,
+} from "../src/app/test-evidence/browser-runtime-contract";
+import {
+  applyToolcraftPerformanceStressFixture,
+  applyToolcraftPerformanceStressValue,
+} from "./performance-fixture-helpers";
+import { measureToolcraftInteraction } from "./performance-probe-helpers";
+
+const fixtureConfig = {
+  rendererStrategy: "none",
+  rendererWorkload: "none",
+  scenarios: [
+    {
+      automated: true,
+      automatedTestName: "perf: fixture outcome",
+      browser: true,
+      browserTestName: "browser perf: fixture outcome",
+      budget: { maxInteractionMs: 1_000 },
+      expectedObservable: "The fixture value is applied.",
+      fixture: "Fixture outcome",
+      id: "fixture-outcome",
+      interaction: "control-change",
+      stressFixture: { kind: "max-value", reason: "Exercise the maximum.", value: 8 },
+      workload: true,
+    },
+  ],
+  usesCustomRenderer: false,
+  workloadTargets: [],
+} as const;
+
+const objectFixtureConfig = {
+  ...fixtureConfig,
+  scenarios: [
+    {
+      ...fixtureConfig.scenarios[0],
+      id: "object-fixture-outcome",
+      stressFixture: {
+        kind: "combined",
+        reason: "Exercise the combined final state.",
+        value: { first: 1, second: 2 },
+      },
+    },
+  ],
+} as const;
+
+function evidenceTypesSince(testInfo: TestInfo, attachmentCount: number) {
+  return testInfo.attachments
+    .slice(attachmentCount)
+    .filter(
+      (attachment) =>
+        attachment.name === TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_ATTACHMENT_NAME,
+    )
+    .map((attachment) => parseToolcraftBrowserRuntimeEvidence(attachment)?.evidenceType);
+}
+
+test("performance interaction evidence requires a persistent changed outcome", async ({
+  page,
+}, testInfo) => {
+  await page.setContent('<div id="outcome">before</div>');
+  const attachmentCount = testInfo.attachments.length;
+
+  await expect(
+    measureToolcraftInteraction(page, async () => undefined, {
+      observeOutcome: () => page.locator("#outcome").textContent(),
+      outcomeTimeoutMs: 100,
+      scenarioId: "no-op-outcome",
+    }),
+  ).rejects.toThrow(/performance outcome/i);
+  expect(evidenceTypesSince(testInfo, attachmentCount)).toEqual([]);
+
+  const result = await measureToolcraftInteraction(
+    page,
+    () => page.locator("#outcome").evaluate((node) => {
+      node.textContent = "after";
+    }),
+    {
+      observeOutcome: () => page.locator("#outcome").textContent(),
+      scenarioId: "changed-outcome",
+      stabilityIntervalMs: 10,
+    },
+  );
+
+  expect(Object.isFrozen(result)).toBe(true);
+  expect(evidenceTypesSince(testInfo, attachmentCount)).toEqual([
+    "performance-product-outcome",
+    "performance-measurement",
+  ]);
+
+  const mutableOutcome = { value: "before" };
+  const mutableAttachmentCount = testInfo.attachments.length;
+  await measureToolcraftInteraction(
+    page,
+    async () => {
+      mutableOutcome.value = "after";
+    },
+    {
+      observeOutcome: async () => mutableOutcome,
+      scenarioId: "mutable-outcome",
+      stabilityIntervalMs: 0,
+    },
+  );
+  expect(evidenceTypesSince(testInfo, mutableAttachmentCount)).toEqual([
+    "performance-product-outcome",
+    "performance-measurement",
+  ]);
+});
+
+test("performance interaction rejects autonomous deltas and times an expected semantic outcome", async ({
+  page,
+}, testInfo) => {
+  await page.setContent(`
+    <div id="animated-output">0</div>
+    <div id="semantic-outcome">idle</div>
+    <script>
+      let frame = 0;
+      setInterval(() => {
+        frame += 1;
+        document.querySelector("#animated-output").textContent = String(frame);
+      }, 8);
+    </script>
+  `);
+  const attachmentCount = testInfo.attachments.length;
+
+  await expect(
+    measureToolcraftInteraction(page, async () => undefined, {
+      baselineStabilityIntervalMs: 12,
+      baselineStabilitySamples: 3,
+      observeOutcome: () => page.locator("#animated-output").textContent(),
+      outcomeTimeoutMs: 150,
+      scenarioId: "autonomous-no-op",
+    }),
+  ).rejects.toThrow(/baseline must remain stable/u);
+  expect(evidenceTypesSince(testInfo, attachmentCount)).toEqual([]);
+
+  const result = await measureToolcraftInteraction(
+    page,
+    async () => {
+      await page.waitForTimeout(40);
+      await page.locator("#semantic-outcome").evaluate((node) => {
+        node.textContent = "applied";
+      });
+    },
+    {
+      expectedOutcome: "applied",
+      observeOutcome: () => page.locator("#semantic-outcome").textContent(),
+      scenarioId: "expected-semantic-outcome",
+      stabilityIntervalMs: 10,
+    },
+  );
+
+  expect(result.durationMs).toBeGreaterThanOrEqual(30);
+  expect(evidenceTypesSince(testInfo, attachmentCount)).toEqual([
+    "performance-product-outcome",
+    "performance-measurement",
+  ]);
+});
+
+test("performance fixture evidence requires the declared value to be observable", async ({
+  page,
+}, testInfo) => {
+  await page.setContent('<div id="fixture-value">0</div>');
+  const attachmentCount = testInfo.attachments.length;
+
+  await expect(
+    applyToolcraftPerformanceStressValue(fixtureConfig, "fixture-outcome", {
+      applyValue: async () => undefined,
+      observeValue: async () => Number(await page.locator("#fixture-value").textContent()),
+    }),
+  ).rejects.toThrow(/observed fixture value/i);
+  expect(evidenceTypesSince(testInfo, attachmentCount)).toEqual([]);
+
+  await applyToolcraftPerformanceStressValue(fixtureConfig, "fixture-outcome", {
+    applyValue: (value) => page.locator("#fixture-value").evaluate((node, nextValue) => {
+      node.textContent = String(nextValue);
+    }, value),
+    observeValue: async () => Number(await page.locator("#fixture-value").textContent()),
+  });
+
+  expect(evidenceTypesSince(testInfo, attachmentCount)).toEqual([
+    "performance-stress-fixture",
+  ]);
+});
+
+test("object fixture evidence verifies the complete final state", async ({
+  page,
+}, testInfo) => {
+  const state = { first: 0, second: 0 };
+  const attachmentCount = testInfo.attachments.length;
+
+  await expect(
+    applyToolcraftPerformanceStressFixture(
+      page,
+      objectFixtureConfig,
+      "object-fixture-outcome",
+      {
+        first: {
+          applyValue: (value) => {
+            state.first = Number(value);
+          },
+          observeValue: () => state.first,
+        },
+        second: {
+          applyValue: (value) => {
+            state.second = Number(value);
+            state.first = 0;
+          },
+          observeValue: () => state.second,
+        },
+      },
+    ),
+  ).rejects.toThrow(/complete stressFixture/i);
+  expect(evidenceTypesSince(testInfo, attachmentCount)).toEqual([]);
+});