@pixel-point/toolcraft 0.0.12 → 0.0.14

package/src/generate.test.mjs

@@ -73,6 +73,7 @@ describe("generateToolcraft", () => {
     assert.equal(packageJson.dependencies["@repo/toolcraft-runtime"], undefined);
     assert.equal(packageJson.dependencies["@tanstack/react-router"], "1.170.6");
     assert.equal(packageJson.dependencies.cmdk, "^1.1.1");
+    assert.equal(packageJson.dependencies["cross-spawn"], "^7.0.6");
     assert.equal(packageJson.dependencies["react-resizable-panels"], "^4.10.0");
     assert.equal(packageJson.dependencies.sonner, "^2.0.7");
     assert.equal(packageJson.devDependencies["@repo/typescript-config"], undefined);
@@ -101,13 +102,13 @@ describe("generateToolcraft", () => {
       packageJson.scripts["test:browser:perf"],
       "playwright install chromium && playwright test --grep \"browser perf:\" --workers=1 --pass-with-no-tests",
     );
-    assert.equal(packageJson.scripts["verify:quick"], "pnpm ai:check && pnpm test");
-    assert.equal(packageJson.scripts["verify:ui"], "pnpm test:browser");
-    assert.equal(packageJson.scripts["verify:perf"], "pnpm test:browser:perf");
-    assert.equal(packageJson.scripts["verify:perf:playwright"], "pnpm test:browser:perf");
+    assert.equal(packageJson.scripts["verify:quick"], "npm run ai:check && npm run test");
+    assert.equal(packageJson.scripts["verify:ui"], "npm run test:browser");
+    assert.equal(packageJson.scripts["verify:perf"], "npm run test:browser:perf");
+    assert.equal(packageJson.scripts["verify:perf:playwright"], "npm run test:browser:perf");
     assert.equal(
       packageJson.scripts["verify:final"],
-      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
+      "npm run ai:check && npm run test && npm run build && npm run test:browser",
     );
 
     const indexHtmlSource = await fs.readFile(path.join(targetDir, "index.html"), "utf8");
@@ -145,6 +146,15 @@ describe("generateToolcraft", () => {
     assert.ok(await fs.stat(path.join(targetDir, "scripts/check-toolcraft-docs.mjs")));
     assert.ok(await fs.stat(path.join(targetDir, "scripts/check-toolcraft-integrity.mjs")));
     assert.ok(await fs.stat(path.join(targetDir, "scripts/run-vite-on-free-port.mjs")));
+    const runViteSource = await fs.readFile(
+      path.join(targetDir, "scripts/run-vite-on-free-port.mjs"),
+      "utf8",
+    );
+    assert.match(runViteSource, /node_modules/);
+    assert.match(runViteSource, /\.bin/);
+    assert.match(runViteSource, /vite\.cmd/);
+    assert.match(runViteSource, /from "cross-spawn"/);
+    assert.doesNotMatch(runViteSource, /pnpmCommand|pnpm\.cmd|pnpm",/);
     assert.ok(await fs.stat(path.join(targetDir, "LICENSE.md")));
     assert.ok(await fs.stat(path.join(targetDir, "NOTICE.md")));
     assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/README.md")));
@@ -156,6 +166,14 @@ describe("generateToolcraft", () => {
     assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/renderer-technique.md")));
     assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/custom-controls.md")));
     assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/component-rules.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/runtime-boundary.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/setup-export.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/control-selection.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/layout.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/media-upload.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/timeline-animation.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/performance.md")));
+    assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/core/reference-study.md")));
     assert.ok(await fs.stat(path.join(targetDir, "src/toolcraft/.toolcraft-manifest.json")));
 
     const appPerformanceSource = await fs.readFile(
@@ -214,6 +232,15 @@ describe("generateToolcraft", () => {
     const licenseSource = await fs.readFile(path.join(targetDir, "LICENSE.md"), "utf8");
     const noticeSource = await fs.readFile(path.join(targetDir, "NOTICE.md"), "utf8");
     const localDocPaths = [
+      "workflow.md",
+      "core/runtime-boundary.md",
+      "core/setup-export.md",
+      "core/control-selection.md",
+      "core/layout.md",
+      "core/media-upload.md",
+      "core/timeline-animation.md",
+      "core/performance.md",
+      "core/reference-study.md",
       "assembly-workflow.md",
       "decision-contract.md",
       "schema-reference.md",
@@ -232,14 +259,14 @@ describe("generateToolcraft", () => {
     assert.match(agentsSource, /Required AI Workflow Skills/);
     assert.match(agentsSource, /Verification Tier Classifier/);
     assert.match(agentsSource, /Verification tier: Tier N/);
-    assert.match(agentsSource, /pnpm verify:quick/);
-    assert.match(agentsSource, /pnpm verify:final/);
-    assert.match(agentsSource, /pnpm ai:check/);
+    assert.match(agentsSource, /npm run verify:quick/);
+    assert.match(agentsSource, /npm run verify:final/);
+    assert.match(agentsSource, /npm run ai:check/);
     assert.match(agentsSource, /use `brainstorming`/);
     assert.match(agentsSource, /use `writing-plans`/);
     assert.match(agentsSource, /use `systematic-debugging`/);
     assert.match(agentsSource, /browser` workflow/);
-    assert.match(agentsSource, /pnpm test:browser/);
+    assert.match(agentsSource, /npm run test:browser/);
     assert.match(agentsSource, /Do not silently skip required workflow skills/);
     assert.match(agentsSource, /Toolcraft app contract overrides generic brainstorming approval/);
     assert.match(agentsSource, /Do not ask the user to confirm decisions already covered/);
@@ -272,17 +299,43 @@ describe("generateToolcraft", () => {
       path.join(targetDir, "docs/toolcraft/component-rules.md"),
       "utf8",
     );
+    const coreControlSelectionSource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/core/control-selection.md"),
+      "utf8",
+    );
+    const coreLayoutSource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/core/layout.md"),
+      "utf8",
+    );
+    const coreMediaUploadSource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/core/media-upload.md"),
+      "utf8",
+    );
+    const coreRuntimeBoundarySource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/core/runtime-boundary.md"),
+      "utf8",
+    );
+    const coreSetupExportSource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/core/setup-export.md"),
+      "utf8",
+    );
+    const coreTimelineSource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/core/timeline-animation.md"),
+      "utf8",
+    );
     assert.match(componentRulesSource, /Slider `step` means numeric snapping only/);
     assert.match(componentRulesSource, /variant: "discrete"/);
     assert.match(componentRulesSource, /Keep large or precision stepped ranges visually continuous/);
     assert.match(componentRulesSource, /Segmented Controls/);
-    assert.match(componentRulesSource, /Never generate a section titled `Color` or `Colors`/);
-    assert.match(componentRulesSource, /Use `fileDrop` for source material uploads/);
+    assert.match(coreLayoutSource, /Bad titles: `Controls`, `Settings`, `Options`, `Sliders`, `Inputs`, `Buttons`, `Color`, `Colors`/);
+    assert.match(coreMediaUploadSource, /Use `fileDrop` for source material uploads/);
+    assert.match(coreControlSelectionSource, /Use `fileDrop` for source material uploads/);
+    assert.match(coreRuntimeBoundarySource, /appSchema\.assembly/);
     assert.match(componentRulesSource, /Do not show Layers for a single-layer app/);
-    assert.match(componentRulesSource, /Use playback timeline/);
-    assert.match(componentRulesSource, /Still-output product apps include one primary `Export PNG` action/);
-    assert.match(componentRulesSource, /Animated product apps include `Export Video`/);
-    assert.match(componentRulesSource, /Copy never replaces export/);
+    assert.match(coreTimelineSource, /Any app with `Export Video` must enable the top Toolcraft timeline/);
+    assert.match(coreSetupExportSource, /Still products expose `Export PNG`/);
+    assert.match(coreSetupExportSource, /Animated products expose `Export Video` plus `Export PNG`/);
+    assert.match(coreSetupExportSource, /Clipboard copy is optional and never replaces export/);
 
     const assemblyDocsSource = await fs.readFile(
       path.join(targetDir, "docs/toolcraft/assembly-workflow.md"),
@@ -346,6 +399,54 @@ describe("generateToolcraft", () => {
     );
   });
 
+  it("generates package-manager-specific commands for pnpm apps", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-cli-"));
+    tempRoots.push(tempRoot);
+    const targetDir = path.join(tempRoot, "pnpm-app");
+
+    await generateToolcraft({
+      cwd: tempRoot,
+      force: true,
+      name: "Pnpm App",
+      packageManager: "pnpm",
+      targetDir: "pnpm-app",
+    });
+
+    const packageJson = JSON.parse(await fs.readFile(path.join(targetDir, "package.json"), "utf8"));
+    assert.equal(packageJson.scripts["verify:quick"], "pnpm ai:check && pnpm test");
+    assert.equal(packageJson.scripts["verify:ui"], "pnpm test:browser");
+    assert.equal(packageJson.scripts["verify:perf"], "pnpm test:browser:perf");
+    assert.equal(packageJson.scripts["verify:perf:playwright"], "pnpm test:browser:perf");
+    assert.equal(
+      packageJson.scripts["verify:final"],
+      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
+    );
+
+    const playwrightConfigSource = await fs.readFile(
+      path.join(targetDir, "playwright.config.ts"),
+      "utf8",
+    );
+    assert.match(playwrightConfigSource, /pnpm exec vite dev/);
+    assert.doesNotMatch(playwrightConfigSource, /npm exec -- vite/);
+
+    const agentsSource = await fs.readFile(path.join(targetDir, "AGENTS.md"), "utf8");
+    assert.match(agentsSource, /pnpm verify:quick/);
+    assert.match(agentsSource, /pnpm verify:final/);
+    assert.match(agentsSource, /pnpm test:browser/);
+    assert.doesNotMatch(agentsSource, /npm run verify:quick/);
+
+    const worklogSource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/agent-worklog.md"),
+      "utf8",
+    );
+    assert.match(worklogSource, /pnpm verify:quick/);
+    assert.match(worklogSource, /pnpm verify:final/);
+
+    await execFileAsync(process.execPath, [path.join(targetDir, "scripts/check-toolcraft-docs.mjs")], {
+      cwd: targetDir,
+    });
+  });
+
   it("writes the app identity marker when the generated title matches the template title", async () => {
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-cli-"));
     tempRoots.push(tempRoot);

package/src/package-json.mjs

@@ -1,3 +1,5 @@
+import { DEFAULT_PACKAGE_MANAGER, createVerificationScripts } from "./package-manager.mjs";
+
 export function sanitizePackageName(value) {
   const sanitized = String(value ?? "")
     .trim()
@@ -44,7 +46,11 @@ function addDependencyGroup(packageJson, groupName, dependencies) {
   }
 }
 
-export function createGeneratedPackageJson({ name, starterPackageJson }) {
+export function createGeneratedPackageJson({
+  name,
+  packageManager = DEFAULT_PACKAGE_MANAGER,
+  starterPackageJson,
+}) {
   if (!starterPackageJson || typeof starterPackageJson !== "object") {
     throw new Error("starterPackageJson is required to create a generated package manifest.");
   }
@@ -54,7 +60,10 @@ export function createGeneratedPackageJson({ name, starterPackageJson }) {
     private: true,
     license: starterPackageJson.license,
     type: starterPackageJson.type ?? "module",
-    scripts: starterPackageJson.scripts ?? {},
+    scripts: {
+      ...(starterPackageJson.scripts ?? {}),
+      ...createVerificationScripts(packageManager),
+    },
   };
 
   addDependencyGroup(packageJson, "dependencies", starterPackageJson.dependencies);

package/src/package-json.test.mjs

@@ -58,6 +58,12 @@ describe("createGeneratedPackageJson", () => {
       scripts: {
         dev: "vite dev",
         test: "vitest run",
+        "verify:final":
+          "npm run ai:check && npm run test && npm run build && npm run test:browser",
+        "verify:perf": "npm run test:browser:perf",
+        "verify:perf:playwright": "npm run test:browser:perf",
+        "verify:quick": "npm run ai:check && npm run test",
+        "verify:ui": "npm run test:browser",
       },
       dependencies: {
         "@tanstack/react-router": "1.170.6",
@@ -77,4 +83,25 @@ describe("createGeneratedPackageJson", () => {
       /starterPackageJson is required/,
     );
   });
+
+  it("generates verification scripts for the selected package manager", () => {
+    const packageJson = createGeneratedPackageJson({
+      name: "Generated App",
+      packageManager: "pnpm",
+      starterPackageJson: {
+        scripts: {
+          dev: "vite dev",
+        },
+      },
+    });
+
+    assert.deepEqual(packageJson.scripts, {
+      dev: "vite dev",
+      "verify:final": "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
+      "verify:perf": "pnpm test:browser:perf",
+      "verify:perf:playwright": "pnpm test:browser:perf",
+      "verify:quick": "pnpm ai:check && pnpm test",
+      "verify:ui": "pnpm test:browser",
+    });
+  });
 });

package/src/package-manager.mjs

@@ -0,0 +1,123 @@
+export const DEFAULT_PACKAGE_MANAGER = "npm";
+
+const PACKAGE_MANAGER_SPECS = {
+  npm: {
+    installHelp: ["  Install Node.js from https://nodejs.org/"],
+    installArgs: ["install"],
+    runScript(scriptName) {
+      return `npm run ${scriptName}`;
+    },
+    exec(binaryName, args = []) {
+      return ["npm", "exec", "--", binaryName, ...args].join(" ");
+    },
+  },
+  pnpm: {
+    installHelp: ["  corepack enable", "  corepack prepare pnpm@latest --activate"],
+    installArgs: ["install"],
+    runScript(scriptName) {
+      return `pnpm ${scriptName}`;
+    },
+    exec(binaryName, args = []) {
+      return ["pnpm", "exec", binaryName, ...args].join(" ");
+    },
+  },
+};
+
+const PACKAGE_MANAGER_NAMES = new Set(Object.keys(PACKAGE_MANAGER_SPECS));
+
+const GENERATED_SCRIPT_COMMANDS = [
+  "ai:check",
+  "build",
+  "dev",
+  "dev:restart",
+  "preview",
+  "preview:restart",
+  "test",
+  "test:browser",
+  "test:browser:perf",
+  "verify:final",
+  "verify:perf",
+  "verify:perf:playwright",
+  "verify:quick",
+  "verify:ui",
+];
+
+function getSpec(packageManager) {
+  return PACKAGE_MANAGER_SPECS[normalizePackageManager(packageManager)];
+}
+
+function replaceAllExact(source, replacements) {
+  let next = String(source);
+
+  for (const [from, to] of replacements) {
+    next = next.split(from).join(to);
+  }
+
+  return next;
+}
+
+export function normalizePackageManager(value, fallback = DEFAULT_PACKAGE_MANAGER) {
+  return PACKAGE_MANAGER_NAMES.has(value) ? value : fallback;
+}
+
+export function detectPackageManager(env = process.env) {
+  const userAgent = String(env.npm_config_user_agent ?? "");
+  const [packageManager] = userAgent.split("/", 1);
+  return normalizePackageManager(packageManager);
+}
+
+export function createInstallCommand(packageManager) {
+  const spec = getSpec(packageManager);
+
+  return {
+    args: [...spec.installArgs],
+    command: normalizePackageManager(packageManager),
+  };
+}
+
+export function createInstallHelp(packageManager) {
+  return [...getSpec(packageManager).installHelp];
+}
+
+export function createRunScriptCommand(packageManager, scriptName) {
+  return getSpec(packageManager).runScript(scriptName);
+}
+
+export function createExecCommand(packageManager, binaryName, args = []) {
+  return getSpec(packageManager).exec(binaryName, args);
+}
+
+export function createVerificationScripts(packageManager) {
+  return {
+    "verify:quick": [
+      createRunScriptCommand(packageManager, "ai:check"),
+      createRunScriptCommand(packageManager, "test"),
+    ].join(" && "),
+    "verify:ui": createRunScriptCommand(packageManager, "test:browser"),
+    "verify:perf": createRunScriptCommand(packageManager, "test:browser:perf"),
+    "verify:perf:playwright": createRunScriptCommand(packageManager, "test:browser:perf"),
+    "verify:final": [
+      createRunScriptCommand(packageManager, "ai:check"),
+      createRunScriptCommand(packageManager, "test"),
+      createRunScriptCommand(packageManager, "build"),
+      createRunScriptCommand(packageManager, "test:browser"),
+    ].join(" && "),
+  };
+}
+
+export function createGeneratedCommandReplacements(packageManager) {
+  const replacements = [
+    ["pnpm exec vite", createExecCommand(packageManager, "vite")],
+    ["pnpm install", `${normalizePackageManager(packageManager)} install`],
+  ];
+
+  for (const scriptName of GENERATED_SCRIPT_COMMANDS) {
+    replacements.push([`pnpm ${scriptName}`, createRunScriptCommand(packageManager, scriptName)]);
+  }
+
+  return replacements.sort(([left], [right]) => right.length - left.length);
+}
+
+export function replaceGeneratedCommandReferences(source, packageManager) {
+  return replaceAllExact(source, createGeneratedCommandReplacements(packageManager));
+}

package/src/package-manager.test.mjs

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  createExecCommand,
+  createInstallCommand,
+  createRunScriptCommand,
+  createVerificationScripts,
+  detectPackageManager,
+  replaceGeneratedCommandReferences,
+} from "./package-manager.mjs";
+
+describe("detectPackageManager", () => {
+  it("uses the npm user agent when the CLI is launched through npx", () => {
+    assert.equal(
+      detectPackageManager({
+        npm_config_user_agent: "npm/10.9.4 node/v24.4.1 darwin arm64 workspaces/false",
+      }),
+      "npm",
+    );
+  });
+
+  it("detects supported package manager launchers", () => {
+    assert.equal(detectPackageManager({ npm_config_user_agent: "pnpm/10.12.4 npm/? node/v24.4.1" }), "pnpm");
+  });
+
+  it("falls back to npm when no supported package manager is detected", () => {
+    assert.equal(detectPackageManager({}), "npm");
+    assert.equal(detectPackageManager({ npm_config_user_agent: "unknown/1.0.0" }), "npm");
+    assert.equal(detectPackageManager({ npm_config_user_agent: "yarn/1.22.22 npm/? node/v24.4.1" }), "npm");
+    assert.equal(detectPackageManager({ npm_config_user_agent: "bun/1.2.0 npm/? node/v24.4.1" }), "npm");
+  });
+});
+
+describe("package manager commands", () => {
+  it("formats install, run, exec, and verification commands for npm", () => {
+    assert.deepEqual(createInstallCommand("npm"), {
+      args: ["install"],
+      command: "npm",
+    });
+    assert.equal(createRunScriptCommand("npm", "dev"), "npm run dev");
+    assert.equal(createExecCommand("npm", "vite", ["dev"]), "npm exec -- vite dev");
+    assert.deepEqual(createVerificationScripts("npm"), {
+      "verify:final":
+        "npm run ai:check && npm run test && npm run build && npm run test:browser",
+      "verify:perf": "npm run test:browser:perf",
+      "verify:perf:playwright": "npm run test:browser:perf",
+      "verify:quick": "npm run ai:check && npm run test",
+      "verify:ui": "npm run test:browser",
+    });
+  });
+
+  it("formats run and exec commands for pnpm", () => {
+    assert.equal(createRunScriptCommand("pnpm", "dev"), "pnpm dev");
+    assert.equal(createExecCommand("pnpm", "vite", ["dev"]), "pnpm exec vite dev");
+  });
+
+  it("replaces known generated command references for npm", () => {
+    const source = [
+      "pnpm install",
+      "pnpm verify:final",
+      "pnpm verify:perf",
+      "pnpm test:browser",
+      "pnpm dev",
+      "pnpm exec vite dev --host 127.0.0.1",
+    ].join("\n");
+
+    assert.equal(
+      replaceGeneratedCommandReferences(source, "npm"),
+      [
+        "npm install",
+        "npm run verify:final",
+        "npm run verify:perf",
+        "npm run test:browser",
+        "npm run dev",
+        "npm exec -- vite dev --host 127.0.0.1",
+      ].join("\n"),
+    );
+  });
+});

package/templates/runtime/contracts/component-contracts.test.ts

@@ -929,7 +929,7 @@ describe("Toolcraft template component contracts", () => {
       "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
     );
     expect(contract.aiUsageRules).toContain(
-      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and pnpm verify:perf only as the Playwright fallback.",
+      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and this app's verify:perf script only as the Playwright fallback.",
     );
     expect(contract.aiUsageRules).toContain(
       "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",

package/templates/runtime/contracts/component-contracts.ts

@@ -1186,7 +1186,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Expensive renderers must cache decoded media, source pixels, glyph atlases, gradients, and other reusable inputs by media id, canvas size, and stable control keys.",
       "Slider drags and high-frequency controls must debounce or coalesce preview work, cancel stale async renders, and avoid re-decoding media on every control change.",
       "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
-      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and pnpm verify:perf only as the Playwright fallback.",
+      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and this app's verify:perf script only as the Playwright fallback.",
       "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",
       "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
       "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",

package/templates/starter/AGENTS.md

@@ -24,11 +24,11 @@ Then follow `workflow.md` to choose the required contract docs and verification
 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 keep a controls panel so runtime `Setup` is visible from the first run; product sections are added after it. Runtime `Setup` is the first visible headerless controls block, is not collapsible, and always contains `Export Settings` and `Import Settings`; never implement settings import/export through `panelActions` or route-local file inputs, and never gate this block by app complexity. Visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are owned by `editable-output` canvas sizing and merge into the same Setup block after settings transfer. App-authored sections must not declare runtime Setup targets such as `runtime.settingsTransfer`, `canvas.aspectRatio`, `canvas.size.width`, `canvas.size.height`, `canvas.renderScale`, or `panels.timeline.extended`; those controls never suppress the mandatory runtime Setup controls. Runtime aspect presets apply canonical canvas sizes, with `16:9` equal to `1920x1080`; manual Canvas width/height edits keep the typed dimension, keep the other dimension unchanged, switch Aspect ratio to Custom, and show the reduced current ratio in custom ratio inputs; when no explicit product size is provided, the runtime default canvas size is also `1920x1080`. Product-output, exportable, shader, procedural, and reference-clone apps use `editable-output`; uploaded background/source images inside product canvases also use `editable-output`, keep the current canvas size, and render as cover/crop inside the current canvas bounds. Fixed/reference/base dimensions are initial `canvas.size` values, not reasons to hide `Aspect ratio`, `Canvas width`, or `Canvas height`. Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`; Setup then appends `Resolution scale` after canvas sizing so backing pixels can increase up to scale 2 without changing CSS/output size. Performance fixes must preserve the selected render scale and keep canvas preview responsive to sliders/high-frequency controls at that scale; diagnose the bottleneck before reducing quality. Do not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping `canvas.renderScale` below the user's chosen value. When `panels.timeline` is enabled, runtime appends a `Timeline` switch as the last Setup control; off shows compact Play-only transport, on shows the extended timeline with scrubber, duration, loop, and keyframe UI, and the switch never changes product values, playback, keyframes, export, or Reset controls. When `panels.timeline` is omitted, the Timeline switch must not appear.
-14. Product apps expose a required `Background` section directly before export settings. It contains a Switch labeled `Include` and a background color control with `label: false` in one equal-width inline row; PNG export wires those runtime values into the standard export helper, live preview uses `shouldIncludeToolcraftPreviewBackground(state)` so Include can hide the product background, and video export keeps the background. Every app with `Export PNG` exposes `Image Export` with `export.image.format` and `export.image.resolution` as two `select` controls in one compact two-column inline row, and passes the selected resolution to `createToolcraftPngExportCanvas({ resolution })` so 2K/4K/8K change actual PNG dimensions. Animated apps with video export enable the top Toolcraft timeline and place `Image Export` immediately before `Video Export`.
+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.
+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.
-17. Workload performance scenarios must declare `stressFixture` for the tested control value; browser perf tests must use `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` so heavy-case tests cannot use toy values. When the tested control is not itself the whole heavy source, declare `workloadFixture` and apply it first with `getToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`; this is the app baseline such as large media, long text, many items, or high render scale, and it must be paired with the measured `stressFixture`. Numeric maximums, density, item counts, canvas/media size, and combined heavy states declare `loadProfile` with `hardLimit`, `smoothTarget`, and `smoothTargetRatio`; try the hard limit first, and lower the guaranteed smooth target only in 10 percent steps with failed-measurement and optimization evidence. Ranges above `smoothTarget` are experimental, not silently guaranteed. Media import and image-processing workloads use `kind: "media"` fixtures at least `1920x1080`-equivalent, and heavy pixel/media Canvas 2D must evaluate WebGL/WebGPU with measured evidence before staying on CPU.
+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.
 
@@ -47,6 +47,7 @@ This project includes Toolcraft source code governed by the Toolcraft Designer L
 Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app must remain buildable without the website.
 
 - `docs/toolcraft/workflow.md` — required preflight, task routing, worklog gate, and verification routing.
+- `docs/toolcraft/core/runtime-boundary.md`, `docs/toolcraft/core/setup-export.md`, `docs/toolcraft/core/control-selection.md`, `docs/toolcraft/core/layout.md`, `docs/toolcraft/core/media-upload.md`, `docs/toolcraft/core/timeline-animation.md`, `docs/toolcraft/core/performance.md`, `docs/toolcraft/core/reference-study.md` — focused core modules routed by `workflow.md`.
 - `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`.

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

@@ -6,6 +6,21 @@ Use `../../AGENTS.md` as the entry contract, then read `workflow.md` before plan
 
 The starter app itself is intentionally neutral. It should show the Toolcraft canvas/upload/toolbar baseline only until the product schema is authored. Demo controls, prompt inputs, layers, and timeline belong in tests/docs or in a real generated product that needs them.
 
+## Core modules
+
+`workflow.md` routes agents to these focused modules. Read every module listed for the task type; each module is intended to be small enough to read fully without relying on truncated terminal output.
+
+- `core/runtime-boundary.md` — Toolcraft shell, allowed extension points, canvas boundary, and generated-app source boundary.
+- `core/setup-export.md` — required Setup, canvas sizing, render scale, Timeline switch, Background, Image Export, Video Export, and sticky export actions.
+- `core/control-selection.md` — built-in control fit, exact owners, compound controls, actions, collection actions, vector ownership, and custom control gate.
+- `core/layout.md` — sections, dependency cohesion, headers, reset, spacing, dividers, labels, inline rows, actions layout, colors, select, and segmented fit.
+- `core/media-upload.md` — file/image upload, multi-upload, sorting, transform actions, canvas source images, default assets, and source material behavior.
+- `core/timeline-animation.md` — animation intent, timeline requirement, compact/extended timeline, seamless forward loops, duration changes, keyframes, and video timing.
+- `core/performance.md` — verification triggers, workload fixtures, media/pixel workloads, render scale, live slider responsiveness, renderer pipeline inventory, and optimization evidence.
+- `core/reference-study.md` — reference-runtime clone, feature inventory, reference study, Figma source, video references, acceptance mapping, and worklog evidence.
+
+The broad docs below remain compatibility and topic references. They do not replace `workflow.md` routing or the `core/*` modules.
+
 1. `workflow.md` — required preflight, task routing, worklog gate, and verification routing.
 2. `assembly-workflow.md` — how the app must be assembled.
 3. `decision-contract.md` — hard rules, defaults, heuristics, and escape hatches.

package/templates/starter/docs/toolcraft/acceptance-testing.md

@@ -1,5 +1,7 @@
 # Acceptance Testing
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused acceptance reference for the topic below.
+
 Every visible product entity must prove it works. A control is not accepted because it renders; it is accepted only when tests prove user interaction changes runtime state and the final product output, command side effect, timeline frame, layer result, media lifecycle, or canvas viewport.
 
 ## Required Files