@pixel-point/toolcraft 0.0.2

package/templates/starter/e2e/product-observable-helpers.ts

@@ -0,0 +1,170 @@
+import { expect, type Page } from "@playwright/test";
+
+const defaultProductObservableSelector = [
+  "[data-toolcraft-product-output]",
+  "[data-toolcraft-product-text]",
+  "[data-toolcraft-canvas-slot] canvas",
+  "[data-toolcraft-canvas-slot] svg",
+  "[data-toolcraft-canvas-world] canvas",
+  "[data-toolcraft-canvas-world] svg",
+].join(", ");
+
+export type ToolcraftProductObservableSnapshotOptions = {
+  selector?: string;
+  timeoutMs?: number;
+};
+
+export type ToolcraftProductObservableChangeOptions =
+  ToolcraftProductObservableSnapshotOptions & {
+    message?: string;
+  };
+
+export async function getToolcraftProductObservableSnapshot(
+  page: Page,
+  options: ToolcraftProductObservableSnapshotOptions = {},
+): Promise<string> {
+  const selector = options.selector ?? defaultProductObservableSelector;
+  const observable = page.locator(selector).first();
+
+  await expect(
+    observable,
+    `Product observable "${selector}" must exist and be visible.`,
+  ).toBeVisible({
+    timeout: options.timeoutMs ?? 5000,
+  });
+
+  return observable.evaluate((element) => {
+    const normalizeText = (value: string) => value.replace(/\s+/g, " ").trim();
+    const hashString = (value: string) => {
+      let hash = 2166136261;
+
+      for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+      }
+
+      return (hash >>> 0).toString(16);
+    };
+    const hashBytes = (value: Uint8ClampedArray) => {
+      let hash = 2166136261;
+
+      for (let index = 0; index < value.length; index += 1) {
+        hash ^= value[index] ?? 0;
+        hash = Math.imul(hash, 16777619);
+      }
+
+      return (hash >>> 0).toString(16);
+    };
+    const snapshotCanvas = (canvas: HTMLCanvasElement) => {
+      const width = canvas.width;
+      const height = canvas.height;
+      const sampleWidth = Math.max(1, Math.min(96, width));
+      const sampleHeight = Math.max(1, Math.min(96, height));
+
+      try {
+        const sample = document.createElement("canvas");
+        sample.width = sampleWidth;
+        sample.height = sampleHeight;
+        const context = sample.getContext("2d", { willReadFrequently: true });
+
+        if (!context) {
+          return {
+            hash: "unavailable-context",
+            height,
+            sampleHeight,
+            sampleWidth,
+            width,
+          };
+        }
+
+        context.drawImage(canvas, 0, 0, sampleWidth, sampleHeight);
+        const pixels = context.getImageData(0, 0, sampleWidth, sampleHeight).data;
+
+        return {
+          hash: hashBytes(pixels),
+          height,
+          sampleHeight,
+          sampleWidth,
+          width,
+        };
+      } catch (error) {
+        return {
+          error: error instanceof Error ? error.message : "unreadable-canvas",
+          height,
+          sampleHeight,
+          sampleWidth,
+          width,
+        };
+      }
+    };
+    const snapshotElement = (node: Element) => {
+      const rect = node.getBoundingClientRect();
+      const computed = window.getComputedStyle(node);
+      const attributes = Array.from(node.attributes)
+        .filter((attribute) =>
+          /^(?:aria-|data-|role$|class$|style$|viewBox$|width$|height$)/.test(
+            attribute.name,
+          ),
+        )
+        .map((attribute) => [attribute.name, attribute.value] as const)
+        .sort(([left], [right]) => left.localeCompare(right));
+      const canvases =
+        node instanceof HTMLCanvasElement
+          ? [snapshotCanvas(node)]
+          : Array.from(node.querySelectorAll("canvas")).map(snapshotCanvas);
+      const svgs =
+        node instanceof SVGElement
+          ? [hashString(node.outerHTML)]
+          : Array.from(node.querySelectorAll("svg")).map((svg) => hashString(svg.outerHTML));
+
+      return {
+        attributes,
+        canvases,
+        childElementCount: node.childElementCount,
+        rect: {
+          height: Math.round(rect.height * 100) / 100,
+          width: Math.round(rect.width * 100) / 100,
+          x: Math.round(rect.x * 100) / 100,
+          y: Math.round(rect.y * 100) / 100,
+        },
+        style: {
+          backgroundColor: computed.backgroundColor,
+          color: computed.color,
+          fontFamily: computed.fontFamily,
+          fontSize: computed.fontSize,
+          letterSpacing: computed.letterSpacing,
+          lineHeight: computed.lineHeight,
+          opacity: computed.opacity,
+          transform: computed.transform,
+        },
+        svgs,
+        tagName: node.tagName.toLowerCase(),
+        text: normalizeText(node.textContent ?? ""),
+      };
+    };
+
+    return JSON.stringify(snapshotElement(element));
+  });
+}
+
+export async function expectToolcraftProductObservableToChange(
+  page: Page,
+  action: () => Promise<void>,
+  options: ToolcraftProductObservableChangeOptions = {},
+): Promise<void> {
+  const before = await getToolcraftProductObservableSnapshot(page, options);
+
+  await action();
+
+  await expect
+    .poll(
+      async () => getToolcraftProductObservableSnapshot(page, options),
+      {
+        message:
+          options.message ??
+          "Product output should change after the visible user interaction.",
+        timeout: options.timeoutMs ?? 5000,
+      },
+    )
+    .not.toBe(before);
+}

package/templates/starter/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Toolcraft Starter</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/starter/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "toolcraft-starter",
+  "private": true,
+  "license": "SEE LICENSE IN LICENSE.md",
+  "type": "module",
+  "scripts": {
+    "ai:check": "node scripts/check-ai-skills.mjs",
+    "dev": "node scripts/run-vite-on-free-port.mjs dev",
+    "build": "tsc -p tsconfig.json --noEmit && vite build",
+    "preview": "node scripts/run-vite-on-free-port.mjs preview",
+    "docs:check": "node scripts/check-toolcraft-docs.mjs",
+    "test": "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests",
+    "test:browser": "playwright install chromium && playwright test",
+    "test:browser:perf": "playwright install chromium && playwright test e2e/app-performance.spec.ts --workers=1 && playwright test --grep \"browser perf:\" --workers=1 --pass-with-no-tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify:quick": "pnpm ai:check && pnpm test",
+    "verify:ui": "pnpm test:browser",
+    "verify:perf": "pnpm test:browser:perf",
+    "verify:final": "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser && pnpm test:browser:perf"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.4.1",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@phosphor-icons/react": "^2.1.10",
+    "@repo/toolcraft-runtime": "workspace:*",
+    "@repo/ui": "workspace:*",
+    "@tanstack/react-router": "1.170.6",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "lucide-react": "^0.511.0",
+    "motion": "^11.16.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-resizable-panels": "^4.10.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.51.1",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/node": "22.19.19",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.0",
+    "vitest": "^3.0.5"
+  }
+}

package/templates/starter/playwright.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig, devices } from "@playwright/test";
+
+import { findAvailablePort, readPreferredPort } from "./scripts/toolcraft-port.mjs";
+
+const resolvedTestPortEnvName = "TOOLCRAFT_RESOLVED_TEST_PORT";
+const resolvedTestPort = Number(process.env[resolvedTestPortEnvName]);
+const preferredTestPort = readPreferredPort([
+  resolvedTestPortEnvName,
+  "TOOLCRAFT_TEST_PORT",
+  "TOOLCRAFT_PORT",
+  "PORT",
+]);
+const testPort =
+  Number.isInteger(resolvedTestPort) && resolvedTestPort > 0 && resolvedTestPort <= 65_535
+    ? resolvedTestPort
+    : await findAvailablePort(preferredTestPort);
+const testBaseUrl = `http://localhost:${testPort}`;
+process.env[resolvedTestPortEnvName] = String(testPort);
+
+if (!resolvedTestPort && testPort !== preferredTestPort) {
+  console.log(`[toolcraft] Browser test port ${preferredTestPort} is busy; using ${testPort} instead.`);
+}
+
+export default defineConfig({
+  testDir: "./e2e",
+  timeout: 30_000,
+  expect: {
+    timeout: 5_000,
+  },
+  fullyParallel: false,
+  reporter: [["list"]],
+  use: {
+    ...devices["Desktop Chrome"],
+    baseURL: testBaseUrl,
+    trace: "retain-on-failure",
+  },
+  webServer: {
+    command: `pnpm exec vite dev --port ${testPort}`,
+    reuseExistingServer: false,
+    timeout: 60_000,
+    url: testBaseUrl,
+  },
+});

package/templates/starter/scripts/check-ai-skills.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const codexHome = process.env.CODEX_HOME
+  ? path.resolve(process.env.CODEX_HOME)
+  : path.join(os.homedir(), ".codex");
+
+const requiredSkills = [
+  {
+    name: "brainstorming",
+    purpose: "shape the app behavior, panels, controls, canvas, media, export, and ambiguity before code",
+    paths: [path.join(codexHome, "skills/brainstorming/SKILL.md")],
+  },
+  {
+    name: "writing-plans",
+    purpose: "turn the approved app spec into a deterministic Toolcraft implementation plan",
+    paths: [path.join(codexHome, "skills/writing-plans/SKILL.md")],
+  },
+  {
+    name: "systematic-debugging",
+    purpose: "investigate root cause before fixing broken controls, tests, builds, visual regressions, or runtime bugs",
+    paths: [path.join(codexHome, "skills/systematic-debugging/SKILL.md")],
+  },
+  {
+    name: "browser",
+    purpose: "verify the generated UI in a running local browser after implementation",
+    paths: [
+      path.join(codexHome, "skills/browser/SKILL.md"),
+      path.join(codexHome, "skills/browser/browser/SKILL.md"),
+      path.join(codexHome, "plugins/cache/openai-bundled/browser/0.1.0-alpha2/skills/browser/SKILL.md"),
+      path.join(codexHome, "plugins/cache/openai-bundled/browser/*/skills/browser/SKILL.md"),
+      path.join(codexHome, "plugins/cache/openai-bundled/browser/*/skills/control-in-app-browser/SKILL.md"),
+    ],
+  },
+];
+
+function pathPatternExists(candidatePath) {
+  if (!candidatePath.includes("*")) {
+    return fs.existsSync(candidatePath);
+  }
+
+  const { root } = path.parse(candidatePath);
+  const segments = candidatePath.slice(root.length).split(path.sep).filter(Boolean);
+
+  function walk(index, currentPath) {
+    if (index >= segments.length) {
+      return fs.existsSync(currentPath);
+    }
+
+    const segment = segments[index];
+
+    if (segment !== "*") {
+      return walk(index + 1, path.join(currentPath, segment));
+    }
+
+    if (!fs.existsSync(currentPath)) {
+      return false;
+    }
+
+    return fs
+      .readdirSync(currentPath, { withFileTypes: true })
+      .some((entry) => entry.isDirectory() && walk(index + 1, path.join(currentPath, entry.name)));
+  }
+
+  return walk(0, root);
+}
+
+function hasAnyPath(paths) {
+  return paths.some((candidatePath) => pathPatternExists(candidatePath));
+}
+
+const missingSkills = requiredSkills.filter((skill) => !hasAnyPath(skill.paths));
+
+if (missingSkills.length === 0) {
+  console.log("AI workflow skills are installed:");
+  for (const skill of requiredSkills) {
+    console.log(`- ${skill.name}: ${skill.purpose}`);
+  }
+  process.exit(0);
+}
+
+console.error("Missing required AI workflow skills:");
+for (const skill of missingSkills) {
+  console.error(`- ${skill.name}: ${skill.purpose}`);
+}
+
+console.error("");
+console.error("If your AI environment supports Codex skills, install the missing skills before implementation.");
+console.error("If installation is not available, stop and ask the user to install them.");
+console.error(`Checked CODEX_HOME: ${codexHome}`);
+
+process.exit(1);

package/templates/starter/scripts/check-toolcraft-docs.mjs

@@ -0,0 +1,159 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(scriptDir, "..");
+
+const requiredDocs = [
+  "README.md",
+  "workflow.md",
+  "assembly-workflow.md",
+  "decision-contract.md",
+  "schema-reference.md",
+  "acceptance-testing.md",
+  "performance.md",
+  "renderer-technique.md",
+  "agent-worklog.md",
+  "custom-controls.md",
+  "component-rules.md",
+];
+
+const requiredProjectFiles = ["LICENSE.md", "NOTICE.md"];
+
+const requiredRuleIds = [
+  "runtime-shell-required",
+  "canvas-no-app-ui",
+  "canvas-surface-preserved",
+  "canvas-handle-placement",
+  "panel-host-behavior",
+  "layers-enable-only-when-needed",
+  "layers-enabled-behavior",
+  "timeline-mode-choice",
+  "timeline-enabled-behavior",
+  "controls-product-coverage",
+  "output-export-required",
+  "controls-layout-heuristics",
+  "renderer-technique-inventory",
+  "reference-clone-source-of-truth",
+  "acceptance-product-observable",
+  "performance-coverage-levels",
+  "persistence-policy-explicit",
+  "workflow-required",
+];
+
+const requiredAgentsLinks = [
+  "workflow.md",
+  "assembly-workflow.md",
+  "decision-contract.md",
+  "schema-reference.md",
+  "acceptance-testing.md",
+  "performance.md",
+  "renderer-technique.md",
+  "agent-worklog.md",
+  "custom-controls.md",
+  "component-rules.md",
+];
+
+const requiredWorkflowTerms = [
+  "Verification Tier Classifier",
+  "Verification tier: Tier N",
+  "pnpm verify:quick",
+  "pnpm verify:perf",
+  "pnpm verify:final",
+];
+
+const repoScope = "@repo";
+const workspaceProtocol = "workspace";
+const forbiddenTextPatterns = [
+  new RegExp(`${repoScope}/ui`),
+  new RegExp(`${repoScope}/toolcraft-runtime`),
+  new RegExp(`${workspaceProtocol}:`),
+  /toolcraft-ai-assembly/,
+  /\bAI Assembly\b/,
+  /How AI/,
+];
+
+async function readText(relativePath) {
+  return fs.readFile(path.join(projectRoot, relativePath), "utf8");
+}
+
+async function fileExists(relativePath) {
+  try {
+    const stat = await fs.stat(path.join(projectRoot, relativePath));
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+const failures = [];
+
+for (const fileName of requiredDocs) {
+  const relativePath = `docs/toolcraft/${fileName}`;
+
+  if (!(await fileExists(relativePath))) {
+    failures.push(`missing local Toolcraft doc: ${relativePath}`);
+  }
+}
+
+for (const relativePath of requiredProjectFiles) {
+  if (!(await fileExists(relativePath))) {
+    failures.push(`missing required project file: ${relativePath}`);
+  }
+}
+
+const agentsSource = await readText("AGENTS.md");
+const decisionSource = await readText("docs/toolcraft/decision-contract.md");
+const docsSources = [agentsSource, decisionSource];
+
+for (const ruleId of requiredRuleIds) {
+  if (!agentsSource.includes(ruleId)) {
+    failures.push(`AGENTS.md must list decision rule "${ruleId}"`);
+  }
+
+  if (!decisionSource.includes(ruleId)) {
+    failures.push(`docs/toolcraft/decision-contract.md must list decision rule "${ruleId}"`);
+  }
+}
+
+for (const fileName of requiredDocs) {
+  const source = await readText(`docs/toolcraft/${fileName}`);
+  docsSources.push(source);
+}
+
+const combinedSource = docsSources.join("\n");
+
+for (const pattern of forbiddenTextPatterns) {
+  if (pattern.test(combinedSource)) {
+    failures.push(`local Toolcraft docs contain forbidden text pattern ${pattern}`);
+  }
+}
+
+for (const localDoc of requiredAgentsLinks) {
+  if (!agentsSource.includes(`docs/toolcraft/${localDoc}`)) {
+    failures.push(`AGENTS.md must link docs/toolcraft/${localDoc}`);
+  }
+}
+
+for (const term of requiredWorkflowTerms) {
+  if (!agentsSource.includes(term)) {
+    failures.push(`AGENTS.md must mention "${term}"`);
+  }
+
+  if (!combinedSource.includes(term)) {
+    failures.push(`local Toolcraft docs must mention "${term}"`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("Toolcraft local docs check failed:");
+
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+
+  process.exit(1);
+}
+
+console.log("Toolcraft local docs check passed.");