@pixel-point/toolcraft 0.0.16 → 0.0.17

package/templates/starter/src/app/starter-performance.lifecycle.test.ts

@@ -0,0 +1,261 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+import {
+  TOOLCRAFT_DELIVERY_VERIFICATION_COMMAND,
+  TOOLCRAFT_FULL_PERFORMANCE_VERIFICATION_COMMAND,
+} from "../../scripts/toolcraft-performance-authority-policy.mjs";
+import { requiredPackageScriptNames } from "../../scripts/toolcraft-integrity-policy.mjs";
+
+import { projectDir } from "./starter-performance-test-utils";
+
+const expectedRequiredPackageScriptNames = [
+  "ai:check", "build", "dev", "dev:restart", "docs:check", "preview",
+  "preview:restart", "test", "test:browser", "typecheck", "verify:delivery",
+  "verify:kernel", "verify:perf", "verify:receipt",
+] as const;
+
+describe("Toolcraft starter performance lifecycle", () => {
+  it("publishes separate functional acceptance and performance gates", () => {
+    const packageJson = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")) as {
+      scripts?: Record<string, string>;
+    };
+    const generatedAppTestScript =
+      packageJson.scripts?.["test:generated"] ?? packageJson.scripts?.test;
+
+    expect(requiredPackageScriptNames).toEqual(expectedRequiredPackageScriptNames);
+    for (const scriptName of requiredPackageScriptNames) {
+      expect(packageJson.scripts?.[scriptName]).toBeDefined();
+    }
+    for (const removed of [
+      "test:delivery", "verify:final", "verify:perf:record-iteration",
+      "verify:quick", "verify:ui",
+    ]) {
+      expect(packageJson.scripts?.[removed]).toBeUndefined();
+    }
+    expect(packageJson.scripts?.["ai:check"]).toBe(
+      "node scripts/check-toolcraft-code-health.mjs",
+    );
+    const sourceTestScript =
+      "node scripts/check-toolcraft-docs.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests --reporter=default --reporter=./scripts/toolcraft-vitest-runtime-evidence-reporter.mjs";
+    const generatedTestScript =
+      "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests --reporter=default --reporter=./scripts/toolcraft-vitest-runtime-evidence-reporter.mjs";
+    if (packageJson.scripts?.["test:generated"]) {
+      expect(packageJson.scripts.test).toBe(sourceTestScript);
+      expect(packageJson.scripts["test:generated"]).toBe(generatedTestScript);
+    } else {
+      expect(packageJson.scripts?.test).toBe(generatedTestScript);
+    }
+
+    expect(
+      generatedAppTestScript,
+      "Generated app tests must invoke the Toolcraft integrity checker.",
+    ).toContain("node scripts/check-toolcraft-integrity.mjs");
+    expect(
+      packageJson.scripts?.["test:browser"],
+      "Generated apps must keep measured performance and kernel benchmark scenarios out of the default browser acceptance gate.",
+    ).toBe(
+      'playwright install chromium && playwright test --grep-invert "browser perf:|toolcraft kernel:"',
+    );
+    expect(packageJson.scripts?.["test:browser:perf"]).toBeUndefined();
+    const performanceRunner = readFileSync(
+      join(projectDir, "scripts/run-browser-performance.mjs"),
+      "utf8",
+    );
+    const receiptModule = readFileSync(
+      join(projectDir, "scripts/toolcraft-verification-receipt.mjs"),
+      "utf8",
+    );
+    const deliveryRunner = readFileSync(
+      join(projectDir, "scripts/run-delivery-verification.mjs"),
+      "utf8",
+    );
+    const deliveryLifecycle = readFileSync(
+      join(projectDir, "scripts/toolcraft-delivery-lifecycle.mjs"),
+      "utf8",
+    );
+    const proofProcess = readFileSync(
+      join(projectDir, "scripts/toolcraft-proof-process.mjs"),
+      "utf8",
+    );
+    const deliveryReceiptModule = readFileSync(
+      join(projectDir, "scripts/toolcraft-delivery-receipt.mjs"),
+      "utf8",
+    );
+    expect(performanceRunner).toContain("runToolcraftFullPerformanceCertification");
+    expect(performanceRunner).not.toContain("runToolcraftDeliveryVerification");
+    expect(performanceRunner).not.toContain("--reason=");
+    expect(performanceRunner).toContain("withToolcraftVerificationLock");
+    expect(performanceRunner).toContain("measureToolcraftPerformanceCheckpoint");
+    expect(performanceRunner).not.toContain("writeCheckpointFile");
+    expect(receiptModule).not.toContain(
+      "export async function writeToolcraftPerformanceReceipt",
+    );
+    expect(deliveryReceiptModule).not.toContain(
+      "export async function writeToolcraftDeliveryReceipt",
+    );
+    expect(packageJson.scripts?.["verify:delivery"]).toBe(
+      "node scripts/run-delivery-verification.mjs",
+    );
+    expect(deliveryRunner).toContain("executeToolcraftDeliveryLifecycle");
+    expect(deliveryRunner).toContain("withToolcraftVerificationLock");
+    expect(deliveryLifecycle).toContain("executeToolcraftDeliveryLifecycleCore");
+    expect(deliveryLifecycle).toContain("executeToolcraftDeliveryPlan");
+    expect(deliveryLifecycle).not.toContain("runToolcraftFullPerformanceCertification");
+    expect(deliveryLifecycle).not.toContain("measureToolcraftPerformanceCheckpoint");
+    expect(proofProcess).toContain('from "cross-spawn"');
+    expect(proofProcess).toContain("ensureToolcraftChromium");
+    const deliverySources = `${deliveryRunner}\n${deliveryLifecycle}`;
+    expect(deliverySources).not.toContain('runPackageScript(projectDir, "verify:quick")');
+    expect(deliverySources).not.toContain('runPackageScript(projectDir, "verify:final")');
+    expect(deliverySources).not.toContain('runPackageScript(projectDir, "verify:perf")');
+    expect(packageJson.scripts?.["verify:perf"]).toBe(
+      "node scripts/run-browser-performance.mjs",
+    );
+    expect(packageJson.scripts?.["verify:perf:playwright"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:perf:refresh"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:perf:record-agent-browser"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:perf:record-iteration"]).toBeUndefined();
+    expect(packageJson.scripts?.["verify:kernel"]).toBe(
+      "node scripts/run-kernel-benchmarks.mjs",
+    );
+    const deliveryExecutor = readFileSync(
+      join(projectDir, "scripts/toolcraft-delivery-executor.mjs"),
+      "utf8",
+    );
+    const targetedPerformanceExecution = readFileSync(
+      join(projectDir, "scripts/toolcraft-targeted-performance-execution.mjs"),
+      "utf8",
+    );
+    expect(
+      deliveryExecutor.match(
+        /TOOLCRAFT_PERFORMANCE_FIXTURE_SELECTOR: "development"/g,
+      ),
+    ).toBeNull();
+    expect(
+      targetedPerformanceExecution.match(
+        /TOOLCRAFT_PERFORMANCE_FIXTURE_SELECTOR: "development"/g,
+      ),
+    ).toHaveLength(1);
+    expect(packageJson.scripts?.["verify:perf:record-exemption"]).toBeUndefined();
+    expect(receiptModule).not.toContain('command === "record-iteration"');
+    expect(packageJson.scripts?.["verify:receipt"]).toContain("validate");
+  });
+
+  it("documents adaptive delivery routing without command-shaped authority", () => {
+    const routedDocs = [
+      "AGENTS.md",
+      "docs/toolcraft/README.md",
+      "docs/toolcraft/acceptance-testing.md",
+      "docs/toolcraft/agent-worklog.md",
+      "docs/toolcraft/assembly-workflow.md",
+      "docs/toolcraft/core/performance.md",
+      "docs/toolcraft/performance.md",
+      "docs/toolcraft/workflow.md",
+    ];
+    const docSources = routedDocs.map((relativePath) => ({
+      relativePath,
+      source: readFileSync(join(projectDir, relativePath), "utf8"),
+    }));
+
+    for (const { relativePath, source } of docSources) {
+      expect(source, relativePath).toMatch(/first (?:product )?delivery/i);
+      expect(source, relativePath).toMatch(/later[^\n]{0,40}delivery/i);
+      expect(source, relativePath).toMatch(
+        /(?:performance complaint|localized complaint)/i,
+      );
+      expect(source, relativePath).toMatch(
+        /(?:full audit|complete (?:performance )?(?:audit|review))/i,
+      );
+      expect(source, relativePath).toContain(
+        TOOLCRAFT_DELIVERY_VERIFICATION_COMMAND,
+      );
+      expect(source, relativePath).toContain(
+        TOOLCRAFT_FULL_PERFORMANCE_VERIFICATION_COMMAND,
+      );
+    }
+
+    const allRoutedDocs = docSources.map(({ source }) => source).join("\n");
+    const nonAgentsDocs = docSources
+      .filter(({ relativePath }) => relativePath !== "AGENTS.md")
+      .map(({ source }) => source)
+      .join("\n");
+    expect(nonAgentsDocs).not.toMatch(/\bTier (?:N|[0-4])\b/);
+    expect(allRoutedDocs).not.toMatch(
+      /verify:quick|verify:ui|verify:final|verify:perf:record-iteration|test:delivery/,
+    );
+    expect(allRoutedDocs).not.toMatch(
+      /verify:delivery\s+--|--tier|--unit-test|--browser-test|--performance-test/,
+    );
+    expect(allRoutedDocs).not.toMatch(
+      /performance modules require protected evidence|(?:add|run)[^\n]*affected path performance checks[^\n]*when an edit changes|during development[^\n]*affected performance scenarios|targeted performance scenarios only for touched/i,
+    );
+    expect(allRoutedDocs).toMatch(
+      /only exact request authority[^\n]*measured targeted performance/i,
+    );
+    expect(allRoutedDocs).not.toMatch(/matching (?:executed )?`?Run\b`?/i);
+    expect(allRoutedDocs).not.toContain("app-performance-impact.json");
+  });
+
+  it("keeps workload guidance structural instead of prescribing domain constants", () => {
+    const monorepoRoot = join(projectDir, "..");
+    const documentation = [
+      join(projectDir, "AGENTS.md"),
+      join(projectDir, "docs/toolcraft/core/performance.md"),
+      join(projectDir, "docs/toolcraft/performance.md"),
+      join(projectDir, "docs/toolcraft/renderer-technique.md"),
+      join(projectDir, "docs/toolcraft/assembly-workflow.md"),
+      join(projectDir, "docs/toolcraft/workflow.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-core-performance.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-performance.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-renderer-technique.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-assembly-workflow.md"),
+      join(monorepoRoot, "apps/website/src/content/docs/toolcraft-workflow.md"),
+    ]
+      .filter((filePath) => existsSync(filePath))
+      .map((filePath) => readFileSync(filePath, "utf8"))
+      .join("\n");
+
+    expect(documentation).toMatch(/reachable controls and inputs/i);
+    expect(documentation).toMatch(/workload dimensions and enforced boundaries/i);
+    expect(documentation).toMatch(
+      /render-plan assessment(?: and| with).*protected kernel benchmark/i,
+    );
+    expect(documentation).toMatch(/derived paths and combined fixtures/i);
+    expect(documentation).not.toMatch(/50_000|1_000\s+lines|1920x1080-equivalent/i);
+    expect(documentation).not.toMatch(/classif(?:y|ication)[^\n]*(?:key name|key-name|keyword)/i);
+    expect(documentation).not.toMatch(
+      /bitmap-media|halftone|per-pixel|max text length|max media size/i,
+    );
+    expect(documentation).toMatch(/exact normalized development pressure `0\.8`/i);
+    expect(documentation).toMatch(/exhaustive-discrete/i);
+    expect(documentation).toMatch(/match(?:es)? every option one-to-one/i);
+    expect(documentation).toMatch(/toolcraftDiscreteCombinationBudget/);
+    expect(documentation).toMatch(/toolcraftDiscreteDimensionBudget/);
+    expect(documentation).toMatch(/bypasses search budgets because no (?:combination )?search runs/i);
+    expect(documentation).toMatch(/planning error/i);
+    expect(documentation).toMatch(/TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE/);
+    expect(documentation).toMatch(/exactly one scenario (?:for|per) (?:every )?(?:canonical |derived )?path/i);
+    expect(documentation).toMatch(/targeted failure[^\n]*(?:not|rather than)[^\n]*full[- ]suite/i);
+    expect(documentation).toMatch(
+      /first product delivery[^\n]*full functional acceptance[^\n]*no measured performance/i,
+    );
+    expect(documentation).toMatch(/later delivery[^\n]*functional-targeted/i);
+    expect(documentation).toMatch(
+      /complaint[^\n]*one-authority-targeted-performance-iteration/i,
+    );
+    expect(documentation).toMatch(/full-performance/i);
+    expect(documentation).toMatch(/needs-agent-judgment/i);
+    expect(documentation).toMatch(
+      /later[^\n]{0,40}delivery[^\n]*(?:same )?bare command[^\n]*exact ownership/i,
+    );
+    expect(documentation).not.toMatch(
+      /first stable[^\n]*(?:full performance|full checkpoint|baseline)/i,
+    );
+    expect(documentation).not.toMatch(/compatibility mode|legacy preferred|legacy-only/i);
+    expect(documentation).not.toMatch(/loadProfile|smoothTargetRatio/i);
+    expect(documentation).not.toMatch(/without exceeding development pressure/i);
+    expect(documentation).not.toMatch(/\breachableValues\b/);
+  });
+});

package/templates/starter/src/app/test-evidence/browser-runtime-contract.ts

@@ -27,6 +27,7 @@ export const TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_TYPES = [
   "infinity-mode-restoration",
   "infinity-scene-bounds-image-export",
   "infinity-scene-bounds-video-export",
+  "image-export-artifact",
   "layer-grouping",
   "layer-media-lifecycle",
   "layer-reorder",
@@ -78,6 +79,7 @@ export const TOOLCRAFT_BROWSER_RUNTIME_EVIDENCE_TYPES = [
   "timeline-pause-resume",
   "timeline-rendered-frame",
   "timeline-scrub",
+  "video-export-artifact",
   "viewport-side-effect",
 ] as const;
 

package/templates/starter/src/routes/index.tsx

@@ -8,6 +8,7 @@ export function StarterHome(): React.JSX.Element {
       canvasContent={starterComposition.canvasContent}
       className="h-dvh min-h-dvh"
       controlRenderers={starterComposition.controlRenderers}
+      exportRenderer={starterComposition.exportRenderer}
       modelPresentation={starterComposition.modelPresentation}
       onPanelAction={starterComposition.onPanelAction}
       renderDefaultCanvasMedia={starterComposition.renderDefaultCanvasMedia}

package/templates/runtime/export/export.ts

@@ -1,166 +0,0 @@
-import type { ResolvedToolcraftAppSchema } from "../schema/types";
-import type { ToolcraftState } from "../state/types";
-import {
-  resolveToolcraftExportFrame,
-  ToolcraftSceneExportError,
-  validateToolcraftArtifactSize,
-  type ToolcraftExportFrame,
-} from "./export-frame";
-import {
-  getToolcraftImageExportSize,
-  type ToolcraftImageExportResolution,
-} from "./export-sizing";
-
-export * from "./export-sizing";
-
-export type ToolcraftExportFormat = "png" | "video";
-
-export type ToolcraftExportBackgroundOptions = {
-  format: ToolcraftExportFormat;
-  schema: ResolvedToolcraftAppSchema;
-};
-
-export type ToolcraftPreviewBackgroundOptions = {
-  includeBackgroundTarget?: string;
-  state: ToolcraftState;
-};
-
-export type ToolcraftPngRenderContext = {
-  canvas: HTMLCanvasElement;
-  context: CanvasRenderingContext2D;
-  cssHeight: number;
-  cssWidth: number;
-  frame: ToolcraftExportFrame;
-  includeBackground: boolean;
-  pixelHeight: number;
-  pixelRatio: number;
-  pixelWidth: number;
-};
-
-export type ToolcraftPngExportCanvasOptions = {
-  background?: string;
-  canvasFactory?: () => HTMLCanvasElement;
-  devicePixelRatio?: number;
-  frame?: ToolcraftExportFrame;
-  includeBackground?: boolean;
-  render: (context: ToolcraftPngRenderContext) => void;
-  resolution?: ToolcraftImageExportResolution | string;
-  state: ToolcraftState;
-};
-
-export function shouldIncludeToolcraftExportBackground({
-  format,
-  schema,
-}: ToolcraftExportBackgroundOptions): boolean {
-  if (format === "video") {
-    return true;
-  }
-
-  return schema.export.png.background !== "transparent";
-}
-
-export function shouldIncludeToolcraftPreviewBackground({
-  includeBackgroundTarget = "export.includeBackground",
-  state,
-}: ToolcraftPreviewBackgroundOptions): boolean {
-  if (state.canvas.mode === "infinite") {
-    return false;
-  }
-
-  const includeBackgroundValue = state.values[includeBackgroundTarget];
-
-  if (typeof includeBackgroundValue === "boolean") {
-    return includeBackgroundValue;
-  }
-
-  if (typeof includeBackgroundValue === "string") {
-    const normalizedValue = includeBackgroundValue.trim().toLowerCase();
-
-    if (
-      normalizedValue === "false" ||
-      normalizedValue === "off" ||
-      normalizedValue === "no" ||
-      normalizedValue === "transparent" ||
-      normalizedValue === "exclude"
-    ) {
-      return false;
-    }
-
-    if (
-      normalizedValue === "true" ||
-      normalizedValue === "on" ||
-      normalizedValue === "yes" ||
-      normalizedValue === "include"
-    ) {
-      return true;
-    }
-  }
-
-  return true;
-}
-
-export function createToolcraftPngExportCanvas({
-  background = "#000000",
-  canvasFactory = () => document.createElement("canvas"),
-  devicePixelRatio,
-  frame,
-  includeBackground: includeBackgroundOverride,
-  render,
-  resolution,
-  state,
-}: ToolcraftPngExportCanvasOptions): HTMLCanvasElement {
-  const canvas = canvasFactory();
-  const frameResult = frame
-    ? { frame, ok: true as const }
-    : resolveToolcraftExportFrame(state, null);
-  if (!frameResult.ok) throw new ToolcraftSceneExportError(frameResult);
-  const resolvedFrame = frameResult.frame;
-  const { height, pixelRatio, width } = getToolcraftImageExportSize({
-    devicePixelRatio,
-    frame: resolvedFrame,
-    resolution,
-    state,
-  });
-  const artifactSize = validateToolcraftArtifactSize({ height, width });
-  if (!artifactSize.ok) throw new ToolcraftSceneExportError(artifactSize);
-  const includeBackground =
-    includeBackgroundOverride ??
-    shouldIncludeToolcraftExportBackground({
-      format: "png",
-      schema: state.schema,
-    });
-
-  canvas.width = width;
-  canvas.height = height;
-
-  const context = canvas.getContext("2d");
-
-  if (!context) {
-    throw new Error("Toolcraft PNG export requires a 2D canvas context.");
-  }
-
-  context.save();
-  context.clearRect(0, 0, width, height);
-
-  if (includeBackground) {
-    context.fillStyle = background;
-    context.fillRect(0, 0, width, height);
-  }
-
-  context.scale(pixelRatio, pixelRatio);
-  context.translate(-resolvedFrame.x, -resolvedFrame.y);
-  render({
-    canvas,
-    context,
-    cssHeight: resolvedFrame.height,
-    cssWidth: resolvedFrame.width,
-    frame: resolvedFrame,
-    includeBackground,
-    pixelHeight: height,
-    pixelRatio,
-    pixelWidth: width,
-  });
-  context.restore();
-
-  return canvas;
-}