aigpu 0.3.1

package/dist/cli/lib/install-dawn/run.js

@@ -0,0 +1,24 @@
+export async function runInstallDawn(args, dependencies = {}) {
+  if (args.includes("--help") || args.includes("-h")) {
+    return {
+      code: 0,
+      stdout:
+        "Usage: aigpu install-dawn\n\nDownload and verify the portable Dawn binary for this platform.\nHonors GH_TOKEN/GITHUB_TOKEN and AIGPU_CACHE_DIR.\n",
+    };
+  }
+  if (args.length > 0) return { code: 1, stderr: `Unknown install-dawn option: ${args[0]}\n` };
+
+  try {
+    const install = dependencies.installDawn ?? (await import("@aigpu/adapter-node/install-dawn")).installDawn;
+    const result = await install();
+    return {
+      code: 0,
+      stdout: `${result.downloaded ? "Downloaded" : "Verified"} Dawn prebuild: ${result.path}\n`,
+    };
+  } catch (error) {
+    const details = error && typeof error === "object" ? error : {};
+    const code = details.code ? `${details.code}: ` : "";
+    const fix = details.fix ? `\n${details.fix}` : "";
+    return { code: 1, stderr: `${code}${String(details.message ?? error)}${fix}\n` };
+  }
+}

package/dist/cli/lib/install-software-renderer/run.js

@@ -0,0 +1,17 @@
+export async function runInstallSoftwareRenderer(args, dependencies = {}) {
+  if (args.includes("--help") || args.includes("-h")) return {
+    code: 0,
+    stdout: "Usage: aigpu install-software-renderer\n\nDownload and sha256-verify the portable CPU software renderer for this platform.\nHonors AIGPU_CACHE_DIR.\n",
+  };
+  if (args.length > 0) return { code: 1, stderr: `Unknown install-software-renderer option: ${args[0]}\n` };
+  try {
+    const install = dependencies.installSoftwareRenderer ?? (await import("@aigpu/adapter-node/install-software-renderer")).installSoftwareRenderer;
+    const result = await install();
+    return { code: 0, stdout: `${result.downloaded ? "Downloaded" : "Verified"} software renderer: ${result.path}\n` };
+  } catch (error) {
+    const details = error && typeof error === "object" ? error : {};
+    const code = details.code ? `${details.code}: ` : "";
+    const fix = details.fix ? `\n${details.fix}` : "";
+    return { code: 1, stderr: `${code}${String(details.message ?? error)}${fix}\n` };
+  }
+}

package/dist/cli/lib/mcp/http.js

@@ -0,0 +1,93 @@
+import {
+  createMcpHandler,
+  originValidationResponse,
+} from "@modelcontextprotocol/server";
+import { createAIGpuMcpServer } from "./server.js";
+
+const MAX_REQUEST_BYTES = 64 * 1024;
+
+/**
+ * @param {{
+ *   version: string,
+ *   docs: { execute(input: unknown): unknown },
+ *   examples: { execute(input: unknown): unknown },
+ *   allowedOriginHostnames?: string[],
+ *   onerror?: (error: Error) => void,
+ * }} options
+ */
+export function createAIGpuMcpHttpHandler({
+  version,
+  docs,
+  examples,
+  allowedOriginHostnames = /** @type {string[]} */ ([]),
+  onerror,
+}) {
+  // This route is horizontally scaled, so process-local legacy sessions cannot be routed
+  // reliably. Modern MCP is request-scoped and keeps the public handler stateless.
+  const handler = createMcpHandler(
+    () => createAIGpuMcpServer({ version, docs, examples, allowDownload: false }),
+    { legacy: "reject", onerror },
+  );
+
+  return {
+    ...handler,
+    async fetch(request, options) {
+      const rejectedOrigin = originValidationResponse(
+        request,
+        [...new Set(allowedOriginHostnames)],
+      );
+      if (rejectedOrigin) return rejectedOrigin;
+
+      const contentLength = request.headers.get("content-length");
+      if (contentLength !== null && (!/^\d+$/u.test(contentLength) || Number(contentLength) > MAX_REQUEST_BYTES)) {
+        return new Response("MCP request body is too large.\n", { status: 413 });
+      }
+      let bounded;
+      try {
+        bounded = await bufferBoundedRequest(request);
+      } catch (error) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        try { onerror?.(normalized); } catch {}
+        return Response.json({
+          jsonrpc: "2.0",
+          error: { code: -32700, message: "Parse error: the request body could not be read" },
+          id: null,
+        }, { status: 400 });
+      }
+      if (bounded instanceof Response) return bounded;
+      return handler.fetch(bounded, options);
+    },
+    close: () => handler.close(),
+  };
+}
+
+async function bufferBoundedRequest(request) {
+  if (!request.body) return request;
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_REQUEST_BYTES) {
+        await reader.cancel().catch(() => undefined);
+        return new Response("MCP request body is too large.\n", { status: 413 });
+      }
+      chunks.push(value);
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => undefined);
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new Request(request, { body });
+}

package/dist/cli/lib/mcp/server.js

@@ -0,0 +1,258 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+
+export const MCP_MAX_TEXT_BYTES = 256 * 1024;
+export const MCP_MAX_READ_CHARACTERS = 64 * 1024;
+export const MCP_MAX_RESULT_BYTES = 2 * 1024 * 1024;
+
+const MCP_MAX_READ_OFFSET = 2 * 1024 * 1024;
+const MCP_INLINE_JSON_BYTES = 16 * 1024;
+const MCP_MAX_ERROR_MESSAGE_CHARACTERS = 4 * 1024;
+
+const revision = z.string().regex(/^[a-f0-9]{64}$/u, "Expected a 64-character lowercase SHA-256 revision");
+const exampleId = z.string().min(1).max(128).regex(/^[a-z0-9][a-z0-9-]*$/u, "Expected an example id");
+const readWindow = {
+  offset: z.number().int().min(0).max(MCP_MAX_READ_OFFSET).default(0)
+    .describe("UTF-16 character offset for a paginated read"),
+  limit: z.number().int().min(1).max(MCP_MAX_READ_CHARACTERS).default(MCP_MAX_READ_CHARACTERS)
+    .describe(`Maximum UTF-16 characters to return (up to ${MCP_MAX_READ_CHARACTERS})`),
+};
+
+const docsInputSchema = z.discriminatedUnion("operation", [
+  z.strictObject({ operation: z.literal("search"), query: z.string().min(1).max(200) }),
+  z.strictObject({ operation: z.literal("read"), target: z.string().min(1).max(512), ...readWindow }),
+  z.strictObject({ operation: z.literal("resolve"), target: z.string().min(1).max(512) }),
+  z.strictObject({ operation: z.literal("list"), path: z.string().min(1).max(512).default("/") }),
+  z.strictObject({
+    operation: z.literal("grep"),
+    pattern: z.string().min(1).max(200),
+    ignoreCase: z.boolean().default(false),
+    package: z.string().min(1).max(128).optional(),
+    limit: z.number().int().min(1).max(200).default(50),
+  }),
+  z.strictObject({
+    operation: z.literal("symbols"),
+    query: z.string().min(1).max(200).optional(),
+    package: z.string().min(1).max(128).optional(),
+    limit: z.number().int().min(1).max(200).default(50),
+  }),
+]);
+
+function examplesInputSchema({ allowDownload, examplesOpenWorld }) {
+  const offline = examplesOpenWorld ? { offline: z.boolean().default(false) } : {};
+  const operations = [
+    z.strictObject({
+      operation: z.literal("search"),
+      query: z.string().min(1).max(200),
+      match: z.enum(["all", "any"]).default("all"),
+      limit: z.number().int().min(1).max(50).default(20),
+      revision: revision.optional(),
+      ...offline,
+    }),
+    z.strictObject({ operation: z.literal("show"), id: exampleId, revision: revision.optional(), ...offline }),
+    z.strictObject({
+      operation: z.literal("read"),
+      id: exampleId,
+      path: z.string().min(1).max(1024),
+      revision: revision.optional(),
+      ...readWindow,
+      ...offline,
+    }),
+  ];
+  if (allowDownload) {
+    operations.push(z.strictObject({
+      operation: z.literal("download"),
+      id: exampleId,
+      destination: z.string().min(1).max(1024)
+        .describe("Relative directory beneath the configured MCP output directory"),
+      revision: revision.optional(),
+      offline: z.boolean().default(false),
+    }));
+  }
+  return z.discriminatedUnion("operation", operations);
+}
+
+export function createAIGpuMcpServer({
+  version,
+  docs,
+  examples,
+  allowDownload = false,
+  examplesOpenWorld = allowDownload,
+}) {
+  const server = new McpServer(
+    { name: "aigpu", version },
+    {
+      instructions: [
+        "Use docs to discover and read AIGPU documentation. Use examples to find and inspect working examples.",
+        ...(allowDownload
+          ? ["Pass a relative destination beneath the configured MCP output directory when using examples.download."]
+          : []),
+      ].join(" "),
+    },
+  );
+
+  server.registerTool(
+    "docs",
+    {
+      title: "AIGPU documentation",
+      description: "Search, resolve, list, grep, and read the canonical AIGPU documentation corpus.",
+      inputSchema: docsInputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    (input, context) => {
+      const signal = context.mcpReq.signal;
+      return executeTool(() => docs.execute(input, { signal }), signal, { input, tool: "docs" });
+    },
+  );
+
+  server.registerTool(
+    "examples",
+    {
+      title: "AIGPU examples",
+      description: allowDownload
+        ? "Search, inspect, read, or download a verified AIGPU example beneath the configured MCP output directory."
+        : "Search, inspect, and read verified AIGPU examples.",
+      inputSchema: examplesInputSchema({ allowDownload, examplesOpenWorld }),
+      annotations: {
+        readOnlyHint: !allowDownload,
+        destructiveHint: false,
+        idempotentHint: !allowDownload,
+        openWorldHint: examplesOpenWorld,
+      },
+    },
+    (input, context) => {
+      const signal = context.mcpReq.signal;
+      return executeTool(() => examples.execute(input, { signal }), signal, { input, tool: "examples" });
+    },
+  );
+
+  return server;
+}
+
+async function executeTool(operation, signal, rendering) {
+  try {
+    const output = await operation();
+    return assertResultWithinLimit(renderToolOutput(output, rendering));
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason ?? error;
+    if (error && typeof error === "object" && error.name === "AbortError") throw error;
+    const normalized = normalizeToolError(error);
+    return assertResultWithinLimit({
+      content: [{ type: "text", text: `${normalized.code}: ${normalized.message}` }],
+      structuredContent: { error: normalized },
+      isError: true,
+    });
+  }
+}
+
+function normalizeToolError(error) {
+  const rawMessage = error instanceof Error ? error.message : "Unknown tool error";
+  const message = rawMessage.slice(0, MCP_MAX_ERROR_MESSAGE_CHARACTERS);
+  if (error && typeof error === "object" && typeof error.code === "string") {
+    const normalized = { code: error.code, message };
+    const candidates = normalizeCandidates(error.candidates);
+    const target = typeof error.target === "string" ? error.target.slice(0, 1024) : undefined;
+    const lookup = typeof error.lookup === "string" ? error.lookup.slice(0, 64) : undefined;
+    const query = typeof error.query === "string" ? error.query.slice(0, 1024) : undefined;
+    const pattern = typeof error.pattern === "string" ? error.pattern.slice(0, 1024) : undefined;
+    return {
+      ...normalized,
+      ...(target ? { target } : {}),
+      ...(lookup ? { lookup } : {}),
+      ...(query ? { query } : {}),
+      ...(pattern ? { pattern } : {}),
+      ...(candidates ? { candidates } : {}),
+    };
+  }
+  if (/not found/iu.test(message)) return { code: "AIGPU-DOCS-NOT-FOUND", message };
+  if (/^Ambiguous symbol:/u.test(message)) return { code: "AIGPU-DOCS-AMBIGUOUS", message };
+  return { code: "AIGPU-TOOL-ERROR", message };
+}
+
+function renderToolOutput(output, { input, tool }) {
+  if (output && typeof output === "object" && output.operation === "read") {
+    if (typeof output.content === "string") {
+      const { content, ...metadata } = output;
+      const page = paginateText(content, input);
+      assertTextWithinLimit(page.content);
+      return {
+        content: [{ type: "text", text: page.content }],
+        structuredContent: { ...metadata, ...page.metadata },
+      };
+    }
+    if (output.document && typeof output.document === "object" && typeof output.document.content === "string") {
+      const { content, ...document } = output.document;
+      const page = paginateText(content, input);
+      assertTextWithinLimit(page.content);
+      return {
+        content: [{ type: "text", text: page.content }],
+        structuredContent: { ...output, document, ...page.metadata },
+      };
+    }
+  }
+  const serialized = JSON.stringify(output) ?? "null";
+  const operation = typeof input.operation === "string" ? input.operation : "result";
+  const fallback = Buffer.byteLength(serialized, "utf8") <= MCP_INLINE_JSON_BYTES
+    ? serialized
+    : `Structured ${tool}.${operation} result; inspect structuredContent for details.`;
+  return {
+    content: [{ type: "text", text: fallback }],
+    structuredContent: output,
+  };
+}
+
+function paginateText(content, input) {
+  const offset = input.offset ?? 0;
+  const limit = input.limit ?? MCP_MAX_READ_CHARACTERS;
+  const page = content.slice(offset, offset + limit);
+  const end = offset + page.length;
+  const truncated = end < content.length;
+  const includeMetadata = offset > 0 || truncated;
+  return {
+    content: page,
+    metadata: includeMetadata
+      ? {
+          offset,
+          limit,
+          characters: page.length,
+          totalCharacters: content.length,
+          truncated,
+          ...(truncated ? { nextOffset: end } : {}),
+        }
+      : {},
+  };
+}
+
+function normalizeCandidates(value) {
+  if (!Array.isArray(value)) return undefined;
+  const candidates = value.slice(0, 50).flatMap((candidate) => {
+    if (typeof candidate === "string") return [candidate.slice(0, 1024)];
+    if (!candidate || typeof candidate !== "object") return [];
+    const normalized = {};
+    for (const key of ["symbol", "package", "virtualPath", "repoPath", "path", "kind"]) {
+      if (typeof candidate[key] === "string") normalized[key] = candidate[key].slice(0, 1024);
+    }
+    return Object.keys(normalized).length > 0 ? [normalized] : [];
+  });
+  return candidates.length > 0 ? candidates : undefined;
+}
+
+function assertTextWithinLimit(content) {
+  if (Buffer.byteLength(content, "utf8") <= MCP_MAX_TEXT_BYTES) return;
+  throw resultTooLarge(`Read chunk exceeds the ${MCP_MAX_TEXT_BYTES / 1024} KiB MCP text limit; request a smaller read limit.`);
+}
+
+function assertResultWithinLimit(result) {
+  const bytes = Buffer.byteLength(JSON.stringify(result), "utf8");
+  if (bytes <= MCP_MAX_RESULT_BYTES) return result;
+  throw resultTooLarge(`Tool result exceeds the ${MCP_MAX_RESULT_BYTES / (1024 * 1024)} MiB MCP response limit.`);
+}
+
+function resultTooLarge(message) {
+  return Object.assign(new Error(message), { code: "AIGPU-MCP-RESULT-TOO-LARGE" });
+}

package/dist/cli/lib/mcp/stdio.js

@@ -0,0 +1,34 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { createDocsService } from "../docs/service.js";
+import { LocalExamplesSource } from "../examples/local-source.js";
+import { createExamplesService } from "../examples/service.js";
+import { pullExample } from "../examples/pull.js";
+import { createAIGpuMcpServer } from "./server.js";
+
+export const mcpHelp = `Usage: aigpu mcp [--output-dir <absolute-directory> | --project-from-cwd]
+
+Serve AIGPU documentation and local examples over MCP stdio. No network connection
+is opened. AIGPU_EXAMPLES_DIR selects the local examples directory.
+`;
+
+export function runMcpStdio(args, { version = "0.0.0", cwd = process.cwd(), env = process.env, platform = process.platform, reportError = (error) => process.stderr.write(`aigpu mcp: ${error.message}\n`) } = {}) {
+  if (args.length === 1 && ["--help", "-h", "help"].includes(args[0])) return { code: 0, stdout: mcpHelp };
+  const usesOutputDirectory = args.length === 2 && args[0] === "--output-dir" && !!args[1];
+  const usesProjectCwd = args.length === 1 && args[0] === "--project-from-cwd";
+  if (args.length !== 0 && !usesOutputDirectory && !usesProjectCwd) return { code: 2, stderr: mcpHelp };
+  const configuredOutputDirectory = usesOutputDirectory ? args[1] : usesProjectCwd ? undefined : env.AIGPU_MCP_OUTPUT_DIR;
+  if (configuredOutputDirectory && !isAbsolute(configuredOutputDirectory)) return { code: 2, stderr: `MCP output directory must be absolute: ${configuredOutputDirectory}\n` };
+  let downloadRoot = usesProjectCwd ? cwd : configuredOutputDirectory;
+  if (downloadRoot) {
+    try { downloadRoot = realpathSync(downloadRoot); if (!statSync(downloadRoot).isDirectory()) throw new Error("not a directory"); }
+    catch { return { code: 2, stderr: `MCP output directory is not a directory: ${downloadRoot}\n` }; }
+  }
+  const source = new LocalExamplesSource({ root: env.AIGPU_EXAMPLES_DIR ?? resolve(cwd, "examples") });
+  const docs = createDocsService();
+  const allowDownload = !!downloadRoot && (platform === "linux" || platform === "darwin");
+  const examples = createExamplesService({ source, downloadRoot, downloadExample: allowDownload ? pullExample : undefined, platform });
+  serveStdio(() => createAIGpuMcpServer({ version, docs, examples, allowDownload, examplesOpenWorld: false }), { onerror: reportError });
+  return { code: 0 };
+}

package/dist/cli/lib/snapshot/png.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+
+export function rgbaToPng(bytes, width, height) {
+  const png = new PNG({ width, height });
+  png.data.set(bytes);
+  return png;
+}
+
+export async function writePng(path, bytes, width, height) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, PNG.sync.write(rgbaToPng(bytes, width, height)));
+}
+
+export async function comparePngSnapshot(path, bytes, width, height, options = {}) {
+  const actualPath = artifactPath(path, "actual");
+  const diffPath = artifactPath(path, "diff");
+
+  if (!existsSync(path)) {
+    if (!options.update) return { status: "missing", mismatchedPixels: 0, ratio: 0, actualPath, diffPath };
+    await writePng(path, bytes, width, height);
+    return { status: "created", mismatchedPixels: 0, ratio: 0, actualPath, diffPath };
+  }
+
+  const expected = PNG.sync.read(await readFile(path));
+  assertSameDimensions(path, expected, width, height);
+  const actual = rgbaToPng(bytes, width, height);
+  const diff = new PNG({ width, height });
+  const mismatchedPixels = pixelmatch(expected.data, actual.data, diff.data, width, height, { threshold: options.pixelmatchThreshold ?? 0.1 });
+  const ratio = mismatchedPixels / (width * height);
+  if (ratio <= (options.maxDiffRatio ?? 0)) return { status: "matched", mismatchedPixels, ratio, actualPath, diffPath };
+
+  if (options.update) {
+    await writePng(path, bytes, width, height);
+    return { status: "updated", mismatchedPixels, ratio, actualPath, diffPath };
+  }
+
+  await writePng(actualPath, bytes, width, height);
+  await writeFile(diffPath, PNG.sync.write(diff));
+  return { status: "different", mismatchedPixels, ratio, actualPath, diffPath };
+}
+
+export function snapshotFixit(path, actualPath, diffPath) {
+  return [
+    `Baseline: ${path}`,
+    `Actual: ${actualPath}`,
+    `Diff: ${diffPath}`,
+    "Fix: regenerate the committed baseline with `aigpu snapshot --update` inside the Docker GPU harness, then commit the PNG.",
+  ].join("\n");
+}
+
+function artifactPath(path, suffix) {
+  return path.replace(/\.png$/u, `.${suffix}.png`);
+}
+
+function assertSameDimensions(path, expected, width, height) {
+  if (expected.width === width && expected.height === height) return;
+  throw new Error(`${path} is ${expected.width}x${expected.height}; expected ${width}x${height}`);
+}

package/dist/cli/lib/snapshot/render.js

@@ -0,0 +1,22 @@
+import { SNAPSHOT_SIZE, REPRESENTATIVE_GRADIENT_WGSL } from "./shaders.js";
+
+export const DEFAULT_SNAPSHOT_TIME = Math.PI / 4;
+export const DEFAULT_SNAPSHOT_SPEED = 2;
+
+/** @param api The `aigpu/node` module namespace: `init` plus the free functions this render needs. */
+export async function renderRepresentativeSnapshot(api) {
+  const { init, effect, frame, target } = api;
+  const gpu = await init();
+  try {
+    const colorTarget = target(gpu, { size: SNAPSHOT_SIZE, format: "rgba8unorm", label: "aigpu-snapshot-gradient" });
+    const gradient = effect(gpu, REPRESENTATIVE_GRADIENT_WGSL, {
+      label: "aigpu-snapshot-gradient",
+      set: { speed: DEFAULT_SNAPSHOT_SPEED },
+    });
+    gradient.set({ time: DEFAULT_SNAPSHOT_TIME });
+    frame(gpu, (current) => current.pass({ target: colorTarget }, (encoder) => encoder.draw(gradient)));
+    return { pixels: await colorTarget.read(), width: SNAPSHOT_SIZE[0], height: SNAPSHOT_SIZE[1] };
+  } finally {
+    gpu.dispose();
+  }
+}

package/dist/cli/lib/snapshot/run.js

@@ -0,0 +1,79 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { comparePngSnapshot, snapshotFixit } from "./png.js";
+import { renderRepresentativeSnapshot } from "./render.js";
+
+const DEFAULT_BASELINE = "packages/aigpu-api/tests/__snapshots__/representative-gradient.png";
+
+export async function runSnapshotCommand(options = {}) {
+  if (process.env.AIGPU_DOCKER_TEST !== "1") {
+    return { code: 1, stderr: "aigpu snapshot must run inside the Docker GPU harness with AIGPU_DOCKER_TEST=1.\n" };
+  }
+
+  const parsed = parseSnapshotArgs(options.args ?? []);
+  if (parsed.error) return { code: 1, stderr: `${parsed.error}\n${snapshotUsage()}` };
+
+  const loaded = await loadNodeInit();
+  if (loaded.error) return { code: 1, stderr: loaded.error };
+
+  const baselinePath = resolve(workspaceRoot(), parsed.baselinePath ?? options.baselinePath ?? DEFAULT_BASELINE);
+  const rendered = await renderRepresentativeSnapshot(loaded.api);
+  const result = await comparePngSnapshot(baselinePath, rendered.pixels, rendered.width, rendered.height, { update: parsed.update });
+
+  if (result.status === "missing") {
+    return { code: 1, stderr: `Snapshot baseline is missing.\n${snapshotFixit(baselinePath, result.actualPath, result.diffPath)}\n` };
+  }
+  if (result.status === "different") {
+    return { code: 1, stderr: `Snapshot mismatch: ${result.mismatchedPixels} pixels differ (ratio ${result.ratio}).\n${snapshotFixit(baselinePath, result.actualPath, result.diffPath)}\n` };
+  }
+
+  const verb = result.status === "created" ? "created" : result.status === "updated" ? "updated" : "matched";
+  return { code: 0, stdout: `Snapshot ${verb}: ${baselinePath}\n` };
+}
+
+function parseSnapshotArgs(args) {
+  const parsed = { update: false, baselinePath: undefined, error: undefined };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--update") {
+      parsed.update = true;
+    } else if (arg === "--ci") {
+      parsed.update = false;
+    } else if (arg === "--baseline") {
+      const value = args[i + 1];
+      if (value === undefined) return { ...parsed, error: "Missing value for --baseline" };
+      parsed.baselinePath = value;
+      i += 1;
+    } else {
+      return { ...parsed, error: `Unknown snapshot option: ${arg}` };
+    }
+  }
+  if (process.env.CI === "true") parsed.update = false;
+  return parsed;
+}
+
+function snapshotUsage() {
+  return "Usage: aigpu snapshot [--ci] [--update] [--baseline <path>]\n";
+}
+
+async function loadNodeInit() {
+  try {
+    // The whole namespace: the render needs `init` plus the free functions it calls.
+    const api = await import("aigpu/node");
+    return { api };
+  } catch (error) {
+    if (error?.code !== "ERR_MODULE_NOT_FOUND" && error?.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") throw error;
+    return { error: "aigpu snapshot requires the peer package `aigpu` with its `aigpu/node` entry installed. Install it with `pnpm add aigpu` or run this command from the AIGPU workspace.\n" };
+  }
+}
+
+function workspaceRoot() {
+  const initial = process.cwd();
+  let current = initial;
+  while (!existsSync(resolve(current, "pnpm-workspace.yaml"))) {
+    const parent = dirname(current);
+    if (parent === current) return initial;
+    current = parent;
+  }
+  return current;
+}

package/dist/cli/lib/snapshot/shaders.js

@@ -0,0 +1,11 @@
+export const SNAPSHOT_SIZE = [16, 16];
+
+export const REPRESENTATIVE_GRADIENT_WGSL = `
+struct Params { time: f32, speed: f32 }
+@group(0) @binding(0) var<uniform> params: Params;
+
+@fragment fn main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  let wave = sin(params.time * params.speed) * 0.5 + 0.5;
+  return vec4f(uv.x, uv.y, wave, 1.0);
+}
+`;

package/dist/cli/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "version": "0.3.1"
+}

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared client-environment typing surface. Attach it to `aigpu-env.d.ts`
+ * via `/// <reference types="aigpu/client" />` to make `.wgsl` imports legal
+ * for `tsc` while runtime reflection remains the authority for validation.
+ */
+export type AIGPUClientEnvironment = {
+    readonly gpu?: GPU;
+};
+export { wgslVitePlugin } from "@aigpu/wgsl/loader-vite";
+export type { ShaderSource } from "@aigpu/wgsl";
+export type { ViteLoadResult, WgslVitePluginOptions } from "@aigpu/wgsl/loader-vite";
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/client.js

@@ -0,0 +1,2 @@
+export { wgslVitePlugin } from "@aigpu/wgsl/loader-vite";
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/clock.d.ts

@@ -0,0 +1,26 @@
+import { type Gpu } from "./kernel.ts";
+export interface Clock {
+    /** Seconds since the first frame. */
+    readonly time: number;
+    /** Seconds between the last two ticks: wall-clock, or the value the last `advance()` was given. */
+    readonly deltaTime: number;
+    /** Frames opened on this gpu. Counted by `frame()`/`frameLoop()`, never by `advance()`. */
+    readonly frameCount: number;
+    /**
+     * Moves the clock forward by `dtSeconds` right now, and claims this frame's tick: the next
+     * `frame()` counts the frame but does not advance the clock again. One advance per frame, with
+     * the manual one winning — so an external ticker (GSAP, Motion, an XR frame callback), a
+     * timescale (`advance(dt * 0.5)`) or a fixed timestep drives aigpu without a second clock racing it.
+     */
+    advance(dtSeconds: number): void;
+}
+/**
+ * The frame clock of `gpu`.
+ *
+ * Without `advance()`, every `frame()` moves `time` forward by the wall-clock delta since the last
+ * frame — the default 0.1.x behavior. With `advance(dt)`, you own the clock for that frame.
+ *
+ * Throws `AIGPU-GPU-DISPOSED` after `gpu.dispose()`.
+ */
+export declare function clock(gpu: Gpu): Clock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAWA,OAAO,EAAgB,KAAK,GAAG,EAAe,MAAM,aAAa,CAAC;AAElE,MAAM,WAAW,KAAK;IACpB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAKD;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,KAAK,CAErC"}