shadertown 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,78 @@ deploys, not by this file.
 This project follows [semantic versioning](https://semver.org). Before 1.0 the
 minor number carries breaking changes, so pin it if that matters to you.
 
+## 0.7.0 — 2026-09-01
+
+Fifteen shaders that draw places instead of patterns, in two new families.
+The `pixel` family is real pixel art — every cell a whole number of device
+pixels, every colour one of a handful of stops, every move a whole cell on a
+sprite-sheet clock. The `scene` family paints islands, water and skies at
+hero quality: a marched ocean, rolling grassland, an atoll from above.
+
+### Added
+
+- **Five `pixel` shaders.** `pixel-sea` is a 16-bit seascape with a dithered
+  sky and the sun's reflection breaking into dashes; `pixel-isle` generates
+  one to three islands per seed, one hard biome per cell; `pixel-clouds`
+  marches terraced clouds past a hard sun; `pixel-fire` reproduces the Doom
+  fire's statistics without its feedback buffer; `pixel-rain` rains on a
+  sleeping skyline, one lit window at a time. All five share
+  `st_pixelSize()`, a new prelude helper that keeps every virtual cell a
+  whole number of device pixels.
+- **Ten `scene` shaders.** Islands: `lagoon` (an atoll from above),
+  `archipelago` (a nautical chart on a slow drift), `island` (sea to the
+  horizon, land in the haze), `shore` (the swash zone from above), and
+  `caldera` (a volcano at night, lit by its own veins). Heroes: `meadow`
+  (a silhouette flower field at golden hour), `blossom` (one flower, drawn
+  large, with a true phyllotaxis seed head), `hills` (grassland marched as a
+  heightfield), `swell` (open ocean marched so waves hide waves), and
+  `cumulus` (fair-weather cloud shaded by one extra sample).
+- **Colour presets.** A shader may declare `presets` — curated colour trios
+  with names. All fifteen new shaders ship four each. On the site, Randomise
+  picks between a shader's presets instead of rolling hues, and the picker
+  offers them as one-click starting points; every well stays individually
+  editable, and the share URL still carries plain colours.
+
+### Changed
+
+- **A canvas compiles when it is nearly in view.** `ShaderCanvas` used to
+  build its renderer the moment it mounted, so a page of cards paid for every
+  pipeline on load whether or not the reader ever scrolled that far. It now
+  waits until the canvas is within a screen of the viewport, and holds the
+  renderer once built — scrolling back over a card redraws it rather than
+  recompiling. `play` is unchanged and still decides when a built renderer
+  animates. A browser with no `IntersectionObserver` starts every canvas at
+  once, as before.
+
+### Fixed
+
+- **Lazy canvases start in the right play state.** A canvas with
+  `play="always"` no longer draws one frozen frame when it first comes near the
+  viewport. Hover, visible, and reduced-motion modes keep their existing
+  behaviour.
+- **One request per source image, however many canvases read it.** A grid
+  whose shaders share a photograph fetched that photograph once per canvas,
+  all in flight together and none of them able to use the others' response.
+  The fetch is now shared per URL; each canvas still decodes its own bitmap.
+
+## 0.6.0 — 2026-08-30
+
+The CLI learns to talk to coding agents. `npx shadertown mcp` serves the
+catalogue over the Model Context Protocol, so an agent can search shaders,
+read every control with its range and meaning, and vendor tuned source into
+the project it is working on — through the same registry route and the same
+licence rules as `shadertown add`.
+
+### Added
+
+- **`shadertown mcp`.** A dependency-free MCP server over stdio with four
+  tools: `search_shaders`, `get_shader`, `install_shader`, and
+  `account_status`. Discovery and control schemas are answered locally from
+  the registry this package already ships; installing goes through
+  `/r/<slug>.json`, so Free shaders vendor for anyone and Professional
+  source asks for the paid plan exactly as the CLI does. Connect an agent
+  with `npx add-mcp "npx -y shadertown@latest mcp" -n shadertown`.
+
 ## 0.5.0 — 2026-08-30
 
 Three shaders that remember: a `compute` kind whose state lives in GPU

package/README.md

@@ -27,10 +27,21 @@ repository, as files you own:
 npx shadertown add aurora
 ```
 
+## Give it to your coding agent
+
+The CLI is also an MCP server. One command configures Claude Code, Cursor,
+VS Code, Windsurf, Codex, and friends, and the agent can search the
+catalogue, read every control, and vendor tuned source into the project on
+its own:
+
+```bash
+npx add-mcp "npx -y shadertown@latest mcp" -n shadertown
+```
+
 ## Licensing
 
-This package is MIT, and it draws all 45 shaders. What a licence buys is the
-readable source: 3 shaders hand theirs to anyone, the other 15 need
+This package is MIT, and it draws all 60 shaders. What a licence buys is the
+readable source: 15 shaders hand theirs to anyone, the other 45 need
 [Professional](https://www.shadertown.com/pricing). Source you have already
 vendored keeps working either way.
 

package/cli/cli.mjs

@@ -1,19 +1,17 @@
-import { mkdir, readFile, writeFile, access, chmod, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { homedir } from "node:os";
 import { spawn } from "node:child_process";
-
-const DEFAULT_REGISTRY = process.env.SHADERTOWN_REGISTRY ?? "https://www.shadertown.com";
-const DEFAULT_OUT = "src/shaders";
-
-const esc = (code, text) => `\u001b[${code}m${text}\u001b[0m`;
-const c = {
-  dim: (s) => esc(2, s),
-  bold: (s) => esc(1, s),
-  green: (s) => esc(32, s),
-  cyan: (s) => esc(36, s),
-  yellow: (s) => esc(33, s),
-};
+import {
+  c,
+  CREDENTIALS_PATH,
+  DEFAULT_OUT,
+  DEFAULT_REGISTRY,
+  exists,
+  readProjectConfig,
+  readToken,
+  relative,
+  writeToken,
+} from "./shared.mjs";
 
 export async function run(argv) {
   const [command, ...rest] = argv;
@@ -30,6 +28,10 @@ export async function run(argv) {
       return logout();
     case "whoami":
       return whoami();
+    // Imported when asked for: the MCP server is the rare path, and `add`
+    // should not pay for it at startup.
+    case "mcp":
+      return (await import("./mcp.mjs")).serve();
     case undefined:
     case "help":
     case "--help":
@@ -63,42 +65,6 @@ function parseFlags(args) {
   return { flags, positional };
 }
 
-/** Reads shadertown.config.ts without executing it - only the fields we need. */
-async function readProjectConfig(cwd) {
-  for (const file of ["shadertown.config.ts", "shadertown.config.js", "shadertown.config.mjs"]) {
-    try {
-      const source = await readFile(join(cwd, file), "utf8");
-      const pick = (key) => source.match(new RegExp(`${key}\\s*:\\s*["\'\`]([^"\'\`]+)`))?.[1];
-      return { outDir: pick("outDir"), registry: pick("registry"), license: pick("license") };
-    } catch {
-      // Try the next candidate.
-    }
-  }
-  return {};
-}
-
-// --- credentials ----------------------------------------------------------
-
-const CREDENTIALS_PATH = join(homedir(), ".shadertown", "credentials.json");
-
-async function readToken() {
-  // An explicit environment variable wins, so CI needs no interactive login.
-  if (process.env.SHADERTOWN_TOKEN) return process.env.SHADERTOWN_TOKEN;
-  try {
-    const raw = await readFile(CREDENTIALS_PATH, "utf8");
-    return JSON.parse(raw).token ?? undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-async function writeToken(token, licensee, registry) {
-  await mkdir(dirname(CREDENTIALS_PATH), { recursive: true });
-  await writeFile(CREDENTIALS_PATH, JSON.stringify({ token, licensee, registry }, null, 2));
-  // The token is a bearer credential; keep it off other accounts on the box.
-  await chmod(CREDENTIALS_PATH, 0o600);
-}
-
 function openBrowser(url) {
   const command =
     process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
@@ -198,15 +164,6 @@ async function fetchJson(url, key) {
   return response.json();
 }
 
-async function exists(path) {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function add(args) {
   const { flags, positional } = parseFlags(args);
   if (positional.length === 0) {
@@ -302,10 +259,6 @@ export default defineShadertownConfig({
   console.log(`\n  ${c.green("add")}   shadertown.config.ts\n`);
 }
 
-function relative(from, to) {
-  return to.startsWith(from) ? to.slice(from.length + 1) : to;
-}
-
 function help() {
   console.log(`
   ${c.bold("shadertown")} - vendor WebGPU shaders into your codebase
@@ -320,6 +273,7 @@ function help() {
     add <slug...>    Write a shader's WGSL and typed preset into your repo
     list             Print the catalogue
     init             Create shadertown.config.ts
+    mcp              Serve the catalogue to a coding agent over MCP (stdio)
 
   ${c.dim("Options")}
     --out <dir>      Output directory            ${c.dim(`(default: ${DEFAULT_OUT})`)}

package/cli/mcp.mjs

@@ -0,0 +1,438 @@
+import { createInterface } from "node:readline";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { shaderNames, shaderRegistry, isShaderName, shaderKind } from "../dist/registry.js";
+import { encodeParams } from "../dist/params.js";
+import {
+  DEFAULT_OUT,
+  DEFAULT_REGISTRY,
+  decodeTokenPayload,
+  exists,
+  readCredentials,
+  readProjectConfig,
+  readToken,
+  relative,
+} from "./shared.mjs";
+
+/**
+ * The MCP server: `npx shadertown mcp`, speaking JSON-RPC over stdio.
+ *
+ * It is a different door into the same building. Discovery and the control
+ * schemas are answered from the registry module this package already ships,
+ * so they need no network; installing goes through the same `/r/<slug>.json`
+ * route as `shadertown add`, so the paywall and the licence issuance cannot
+ * be different for an agent than for a person.
+ *
+ * Hand-rolled rather than pulling in an SDK: the protocol surface this server
+ * needs is four methods, and the CLI's one promise is that it stays
+ * dependency-free.
+ */
+
+const PROTOCOL_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
+const LATEST_PROTOCOL = "2025-06-18";
+
+// stdout is the protocol channel, so anything human goes to stderr.
+const send = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
+
+export async function serve() {
+  const rl = createInterface({ input: process.stdin, terminal: false });
+
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+      return;
+    }
+    for (const single of Array.isArray(message) ? message : [message]) {
+      void handle(single);
+    }
+  });
+
+  // Serve until the client hangs up.
+  await new Promise((done) => rl.on("close", done));
+}
+
+async function handle(message) {
+  const { id, method, params } = message ?? {};
+
+  // Notifications get no reply, whatever they say.
+  if (id === undefined || id === null) return;
+
+  try {
+    switch (method) {
+      case "initialize": {
+        const requested = params?.protocolVersion;
+        return send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: PROTOCOL_VERSIONS.has(requested) ? requested : LATEST_PROTOCOL,
+            capabilities: { tools: {} },
+            serverInfo: { name: "shadertown", version: await packageVersion() },
+            instructions: [
+              `shadertown is a catalogue of ${shaderNames.length} production WebGPU shaders: animated backgrounds and image effects with typed parameters.`,
+              "The flow: `search_shaders` to find candidates, `get_shader` for a shader's controls and usage, `install_shader` to vendor its source into this project.",
+              "Free-tier shaders install for anyone. Professional source needs the account this machine signed in with (`npx shadertown login`) to hold a paid plan.",
+            ].join(" "),
+          },
+        });
+      }
+      case "ping":
+        return send({ jsonrpc: "2.0", id, result: {} });
+      case "tools/list":
+        return send({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+      case "tools/call":
+        return send({ jsonrpc: "2.0", id, result: await callTool(params?.name, params?.arguments ?? {}) });
+      default:
+        return send({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        });
+    }
+  } catch (error) {
+    // A tool that throws is a failed call, not a broken server.
+    send({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+    });
+  }
+}
+
+async function packageVersion() {
+  const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  return pkg.version;
+}
+
+// --- tools -----------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: "search_shaders",
+    description:
+      "Search the shadertown catalogue of WebGPU shaders (animated backgrounds and image effects). Matches name, tagline, description, family, and tags. Call with no query to list the whole catalogue. Returns slugs for use with get_shader and install_shader.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "Free-text filter, e.g. \"gradient\", \"pointer\", \"dark hero\". Omit to list everything.",
+        },
+      },
+    },
+  },
+  {
+    name: "get_shader",
+    description:
+      "Everything about one shader: what it looks like, every tunable control with its range, default and meaning, the colours it takes, framework usage, and a browser URL where a human can tune it live. Call this before installing or customizing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "The shader's slug, from search_shaders." },
+      },
+      required: ["slug"],
+    },
+  },
+  {
+    name: "install_shader",
+    description:
+      "Vendor a shader into this project: writes the complete WGSL, a typed preset pinned to the params you pass, a ready-to-paste example, a README, and the LICENSE. Free-tier shaders install for anyone; Professional ones need the signed-in account to hold a paid plan (the call explains how when it applies).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "The shader's slug, from search_shaders." },
+        params: {
+          type: "object",
+          description:
+            "Tuned values to pin into the preset, keyed by control name from get_shader. Numbers for controls, hex strings for colorA/colorB/colorC. Omitted controls keep their defaults.",
+          additionalProperties: true,
+        },
+        directory: {
+          type: "string",
+          description: `Where to write, relative to the project root. Defaults to the shadertown.config outDir, or "${DEFAULT_OUT}".`,
+        },
+        force: {
+          type: "boolean",
+          description: "Overwrite files that already exist. Off by default.",
+        },
+      },
+      required: ["slug"],
+    },
+  },
+  {
+    name: "account_status",
+    description:
+      "Who this machine is signed in to shadertown as, on which plan, and what that unlocks. Use it to explain a licence error or to check before installing a Professional shader.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+async function callTool(name, args) {
+  switch (name) {
+    case "search_shaders":
+      return searchShaders(args);
+    case "get_shader":
+      return getShader(args);
+    case "install_shader":
+      return installShader(args);
+    case "account_status":
+      return accountStatus();
+    default:
+      return failure(`No tool named "${name}".`);
+  }
+}
+
+const success = (text) => ({ content: [{ type: "text", text }] });
+const failure = (text) => ({ content: [{ type: "text", text }], isError: true });
+
+async function registryBase() {
+  const config = await readProjectConfig(process.cwd());
+  return config.registry ?? DEFAULT_REGISTRY;
+}
+
+/**
+ * Which shaders are free is a pricing decision, and pricing lives on the
+ * site, not in this package. Asked once per process; when the network is
+ * away, tiers are reported as unknown rather than guessed.
+ */
+let tierPromise;
+function tierMap(registry) {
+  tierPromise ??= (async () => {
+    try {
+      const response = await fetch(new URL("/r/", registry));
+      if (!response.ok) return null;
+      const index = await response.json();
+      return new Map(index.items.map((item) => [item.slug, item.tier]));
+    } catch {
+      return null;
+    }
+  })();
+  return tierPromise;
+}
+
+async function searchShaders({ query }) {
+  const registry = await registryBase();
+  const tiers = await tierMap(registry);
+
+  const needle = (query ?? "").trim().toLowerCase();
+  const matches = shaderNames.filter((name) => {
+    if (!needle) return true;
+    const def = shaderRegistry[name];
+    const haystack = [name, def.name, def.tagline, def.description, def.family, ...def.tags]
+      .join(" ")
+      .toLowerCase();
+    return needle.split(/\s+/).every((word) => haystack.includes(word));
+  });
+
+  if (matches.length === 0) {
+    return success(
+      `No shader matches "${query}". Families to try: ${[...new Set(shaderNames.map((n) => shaderRegistry[n].family))].join(", ")}. Call search_shaders without a query for the full catalogue.`,
+    );
+  }
+
+  const lines = matches.map((name) => {
+    const def = shaderRegistry[name];
+    const tier = tiers?.get(name);
+    const badge = tier === "free" ? " [free]" : tier === "professional" ? " [pro]" : "";
+    return `- ${name}${badge} — ${def.name}: ${def.tagline} (${def.family}, ${def.cost} cost; tags: ${def.tags.join(", ")})`;
+  });
+
+  const footer = tiers
+    ? "\n[free] installs for anyone; [pro] source needs a paid plan (browsing and tuning are always free)."
+    : "\nTiers unavailable offline: some of these need a paid plan for their source.";
+
+  return success(
+    `${matches.length} of ${shaderNames.length} shaders${needle ? ` match "${query}"` : ""}:\n${lines.join("\n")}\n${footer}\nNext: get_shader for controls, install_shader to vendor one.`,
+  );
+}
+
+async function getShader({ slug }) {
+  if (!isShaderName(slug)) {
+    return failure(`No shader named "${slug}". Use search_shaders to find the right slug.`);
+  }
+
+  const registry = await registryBase();
+  const def = shaderRegistry[slug];
+  const kind = shaderKind(slug);
+  const tiers = await tierMap(registry);
+  const tier = tiers?.get(slug);
+
+  const controls = Object.entries(def.controls).map(
+    ([key, control]) =>
+      `- ${key} ("${control.label}"): number, ${control.min} to ${control.max}, default ${control.default}.${control.hint ? ` ${control.hint}` : ""}`,
+  );
+  const colors = Object.entries(def.colors).map(
+    ([key, color]) =>
+      `- ${key} ("${color.label}"): hex color, default "${color.default}".${color.hint ? ` ${color.hint}` : ""}`,
+  );
+
+  const kindNote =
+    kind === "source"
+      ? "Kind: source — it renders on top of an image or layer you give it."
+      : kind === "compute"
+        ? "Kind: compute — a GPU simulation that carries state between frames."
+        : "Kind: generative — it draws its picture from the params alone.";
+
+  const tierNote =
+    tier === "professional"
+      ? "Tier: Professional — install_shader needs the signed-in account to hold a paid plan."
+      : tier === "free"
+        ? "Tier: Free — install_shader works without an account."
+        : "Tier: unknown (catalogue index unreachable).";
+
+  return success(
+    [
+      `# ${def.name} (${slug})`,
+      def.tagline,
+      "",
+      def.description,
+      "",
+      `Family: ${def.family}. Cost per frame: ${def.cost}. Tags: ${def.tags.join(", ")}.`,
+      kindNote,
+      tierNote,
+      "",
+      "## Controls (keys for the `params` argument and the runtime)",
+      ...controls,
+      ...colors,
+      "",
+      "## Using it",
+      `Tune it live in a browser: ${registry}/shaders/${slug} — the sliders write the same params, and the URL carries them.`,
+      `Install into this project: install_shader with slug "${slug}" and any tuned params.`,
+      `React (runtime from npm): <ShaderCanvas shader="${slug}" params={{ ... }} /> from "shadertown/react".`,
+      `Anything else: createShaderRenderer(canvas, { shader: "${slug}", params }) from "shadertown".`,
+    ].join("\n"),
+  );
+}
+
+async function installShader({ slug, params, directory, force }) {
+  if (!isShaderName(slug)) {
+    return failure(`No shader named "${slug}". Use search_shaders to find the right slug.`);
+  }
+
+  const def = shaderRegistry[slug];
+  const valid = new Set([...Object.keys(def.controls), ...Object.keys(def.colors)]);
+  const cleaned = {};
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (!valid.has(key)) {
+      return failure(
+        `"${key}" is not a control on ${slug}. Valid keys: ${[...valid].join(", ")}. Call get_shader for ranges and meanings.`,
+      );
+    }
+    const coerced = key.startsWith("color") ? String(value) : Number(value);
+    if (typeof coerced === "number" && !Number.isFinite(coerced)) {
+      return failure(`"${key}" must be a number; got ${JSON.stringify(value)}. Call get_shader for its range.`);
+    }
+    cleaned[key] = coerced;
+  }
+
+  const cwd = process.cwd();
+  const config = await readProjectConfig(cwd);
+  const registry = config.registry ?? DEFAULT_REGISTRY;
+  const outDir = resolve(cwd, directory ?? config.outDir ?? DEFAULT_OUT);
+  const token = await readToken();
+
+  const url = new URL(`/r/${slug}.json`, registry);
+  for (const [key, value] of new URLSearchParams(encodeParams(slug, cleaned))) {
+    url.searchParams.set(key, value);
+  }
+
+  const response = await fetch(url, {
+    headers: token ? { authorization: `Bearer ${token}` } : undefined,
+  });
+
+  if (response.status === 402) {
+    const body = await response.json().catch(() => ({}));
+    return failure(
+      [
+        body.message ?? `"${def.name}" is a Professional shader.`,
+        body.reason,
+        token
+          ? "This machine is signed in, but the account holds no paid plan (or the token predates one — sign in again after upgrading)."
+          : "This machine is not signed in.",
+        "To unlock it: run `npx shadertown login` in a terminal on this machine, with an account that holds a Silver or Gold plan — then call install_shader again.",
+        body.upgrade ? `Plans: ${body.upgrade}` : undefined,
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    );
+  }
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    return failure(body.message ?? `${url} responded ${response.status}.`);
+  }
+
+  const item = await response.json();
+  await mkdir(outDir, { recursive: true });
+
+  const written = [];
+  const skipped = [];
+  for (const file of item.files) {
+    const target = join(outDir, file.path);
+    if ((await exists(target)) && !force) {
+      skipped.push(relative(cwd, target));
+      continue;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file.content);
+    written.push(relative(cwd, target));
+  }
+
+  const tuned = encodeParams(slug, cleaned);
+  return success(
+    [
+      `Installed ${item.name} (${slug}).`,
+      written.length ? `Written:\n${written.map((f) => `- ${f}`).join("\n")}` : "Nothing written.",
+      skipped.length
+        ? `Skipped (already exist — pass force: true to overwrite):\n${skipped.map((f) => `- ${f}`).join("\n")}`
+        : undefined,
+      `Next: import the preset from ${slug}/${slug}.ts and pass it to <ShaderCanvas preset={...} /> (React) or createShaderRenderer. ${slug}/README.md documents every control; ${slug}/example.tsx is ready to paste.`,
+      `Preview in a browser: ${registry}/shaders/${slug}${tuned ? `?${tuned}` : ""}`,
+    ]
+      .filter(Boolean)
+      .join("\n\n"),
+  );
+}
+
+async function accountStatus() {
+  const credentials = await readCredentials();
+  if (!credentials) {
+    return success(
+      [
+        "Not signed in. Free-tier shaders still install; Professional source answers 402.",
+        "To sign in: run `npx shadertown login` in a terminal on this machine (it opens a browser). A Silver or Gold plan on that account unlocks Professional source.",
+        "Plans: https://www.shadertown.com/pricing",
+      ].join("\n"),
+    );
+  }
+
+  const payload = decodeTokenPayload(credentials.token);
+  const lines = [
+    credentials.viaEnv
+      ? "Signed in via the SHADERTOWN_TOKEN environment variable."
+      : `Signed in as ${credentials.licensee ?? payload?.licensee ?? "an account"} (registry: ${credentials.registry ?? DEFAULT_REGISTRY}).`,
+  ];
+
+  if (payload) {
+    lines.push(
+      payload.plan === "professional"
+        ? "Plan: paid — Professional shaders install from this machine."
+        : "Plan: free — Professional source will answer 402. Upgrading? Run `npx shadertown login` again afterwards; the plan is carried in the token.",
+    );
+    if (payload.exp) {
+      lines.push(
+        payload.exp < Date.now()
+          ? "The token has expired. Run `npx shadertown login` again."
+          : `Token valid until ${new Date(payload.exp).toISOString().slice(0, 10)}.`,
+      );
+    }
+  }
+
+  lines.push("This reads the stored token; the registry has the final say on every install.");
+  return success(lines.join("\n"));
+}