shadertown 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shadertown
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# shadertown
+
+Production WebGPU shader backgrounds for the web, drawn by
+[vgpu](https://vgpu.sh).
+
+```bash
+npm install shadertown
+```
+
+```tsx
+import { ShaderCanvas } from "shadertown/react";
+
+<ShaderCanvas shader="aurora" params={{ speed: 0.4 }} play="visible" />;
+```
+
+No WGSL loader, no bundler plugin: shader sources ship as strings. Every
+renderer on a page shares one GPU context and one frame loop, and the loop stops
+when nothing is animating.
+
+Full documentation: https://www.shadertown.com/docs

package/cli/cli.mjs

@@ -0,0 +1,341 @@
+import { mkdir, readFile, writeFile, access, chmod, 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),
+};
+
+export async function run(argv) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "add":
+      return add(rest);
+    case "list":
+      return list(rest);
+    case "init":
+      return init();
+    case "login":
+      return login(rest);
+    case "logout":
+      return logout();
+    case "whoami":
+      return whoami();
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return help();
+    case "--version":
+    case "-v":
+      return version();
+    default:
+      throw new Error(`Unknown command "${command}". Run \`shadertown help\`.`);
+  }
+}
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (key === "force") {
+        flags.force = true;
+      } else {
+        flags[key] = args[i + 1];
+        i += 1;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  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";
+  try {
+    spawn(command, [url], { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // Printing the URL is the fallback, and it is always printed anyway.
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function login(args) {
+  const { flags } = parseFlags(args);
+  const config = await readProjectConfig(process.cwd());
+  const registry = flags.registry ?? config.registry ?? DEFAULT_REGISTRY;
+
+  const startResponse = await fetch(new URL("/api/device/start", registry), { method: "POST" });
+  if (!startResponse.ok) {
+    throw new Error(`${registry} did not start a login (${startResponse.status}).`);
+  }
+  const flow = await startResponse.json();
+
+  console.log(`\n  ${c.bold("shadertown")} ${c.dim(`- ${registry}`)}\n`);
+  console.log(`  Open  ${c.cyan(flow.verification_uri)}`);
+  console.log(`  Code  ${c.bold(flow.user_code)}\n`);
+  console.log(`  ${c.dim("Waiting for approval...")}`);
+
+  if (!flags["no-browser"]) openBrowser(flow.verification_uri_complete ?? flow.verification_uri);
+
+  const deadline = Date.now() + (flow.expires_in ?? 600) * 1000;
+  let interval = (flow.interval ?? 2) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    const response = await fetch(new URL("/api/device/poll", registry), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ device_code: flow.device_code }),
+    });
+    const body = await response.json().catch(() => ({}));
+
+    if (response.ok && body.access_token) {
+      await writeToken(body.access_token, body.licensee, registry);
+      console.log(`\n  ${c.green("ok")}    Signed in as ${c.bold(body.licensee ?? "your account")}`);
+      console.log(`        ${c.dim(`Token stored in ${CREDENTIALS_PATH}`)}\n`);
+      return;
+    }
+    if (body.error === "slow_down") interval = (body.interval ?? 4) * 1000;
+    if (body.error === "expired_token") break;
+  }
+
+  throw new Error("That login expired before it was approved. Run `shadertown login` again.");
+}
+
+async function logout() {
+  await rm(CREDENTIALS_PATH, { force: true });
+  console.log(`\n  ${c.green("ok")}    Signed out.\n`);
+}
+
+async function whoami() {
+  const token = await readToken();
+  if (!token) {
+    console.log(`\n  ${c.dim("Not signed in. Run `shadertown login`.")}\n`);
+    return;
+  }
+  try {
+    const raw = await readFile(CREDENTIALS_PATH, "utf8");
+    const saved = JSON.parse(raw);
+    console.log(`\n  ${c.bold(saved.licensee ?? "signed in")} ${c.dim(`- ${saved.registry ?? DEFAULT_REGISTRY}`)}\n`);
+  } catch {
+    console.log(`\n  ${c.dim("Signed in via SHADERTOWN_TOKEN.")}\n`);
+  }
+}
+
+async function fetchJson(url, key) {
+  const response = await fetch(url, {
+    headers: key ? { authorization: `Bearer ${key}` } : undefined,
+  });
+
+  if (response.status === 402) {
+    const body = await response.json().catch(() => ({}));
+    const lines = [
+      body.message ?? "This shader requires a licence.",
+      body.reason ? c.dim(body.reason) : null,
+      body.hint ? c.dim(body.hint) : null,
+      body.upgrade ? c.cyan(body.upgrade) : null,
+    ].filter(Boolean);
+    throw new Error(lines.join("\n         "));
+  }
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    throw new Error(body.message ?? `${url} responded ${response.status}`);
+  }
+
+  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) {
+    throw new Error("Give at least one shader slug. Try `shadertown list`.");
+  }
+
+  const cwd = process.cwd();
+  const config = await readProjectConfig(cwd);
+  const registry = flags.registry ?? config.registry ?? DEFAULT_REGISTRY;
+  const outDir = resolve(cwd, flags.out ?? config.outDir ?? DEFAULT_OUT);
+  const key = await readToken();
+
+  console.log(`\n  ${c.bold("shadertown")} ${c.dim(`- ${registry}`)}\n`);
+
+  for (const slug of positional) {
+    const url = new URL(`/r/${slug}.json`, registry);
+    if (flags.params) {
+      for (const [k, v] of new URLSearchParams(flags.params)) url.searchParams.set(k, v);
+    }
+    if (flags.licensee) url.searchParams.set("licensee", flags.licensee);
+
+    const item = await fetchJson(url.toString(), key);
+    await mkdir(outDir, { recursive: true });
+
+    let written = 0;
+    let skipped = 0;
+    for (const file of item.files) {
+      const target = join(outDir, file.path);
+      if ((await exists(target)) && !flags.force) {
+        skipped += 1;
+        continue;
+      }
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, file.content);
+      written += 1;
+      console.log(`  ${c.green("add")}   ${relative(cwd, target)}`);
+    }
+
+    if (skipped > 0) {
+      console.log(`  ${c.yellow("skip")}  ${skipped} existing file(s) ${c.dim("- pass --force to overwrite")}`);
+    }
+    console.log(`        ${c.dim(`${item.name} - ${item.tagline}`)}`);
+    if (written > 0) {
+      console.log(`        ${c.dim(`Read ${slug}/README.md for every control.`)}`);
+    }
+    console.log("");
+  }
+
+  console.log(`  ${c.dim("Next: import the preset and pass it to <ShaderCanvas preset={...} />")}\n`);
+}
+
+async function list(args) {
+  const { flags } = parseFlags(args);
+  const config = await readProjectConfig(process.cwd());
+  const registry = flags.registry ?? config.registry ?? DEFAULT_REGISTRY;
+  const index = await fetchJson(new URL("/r/", registry).toString());
+
+  console.log(`\n  ${c.bold("shadertown")} ${c.dim(`- ${index.items.length} shaders`)}\n`);
+  const width = Math.max(...index.items.map((item) => item.slug.length));
+  let free = 0;
+  for (const item of index.items) {
+    const isFree = item.tier === "free";
+    if (isFree) free += 1;
+    // Only free is marked. Professional is the default, so marking it would
+    // put a badge on almost every row and say nothing.
+    const gate = isFree ? c.green(" free") : "     ";
+    console.log(`  ${item.slug.padEnd(width)}${gate}  ${c.dim(item.tagline)}`);
+  }
+  if (free < index.items.length) {
+    console.log(
+      `\n  ${c.dim("Unmarked shaders need the Professional plan for their source. Tuning is free on all of them.")}`,
+    );
+  }
+  console.log("");
+}
+
+async function init() {
+  const target = resolve(process.cwd(), "shadertown.config.ts");
+  if (await exists(target)) throw new Error("shadertown.config.ts already exists.");
+
+  await writeFile(
+    target,
+    `import { defineShadertownConfig } from "shadertown";
+
+export default defineShadertownConfig({
+  outDir: "${DEFAULT_OUT}",
+  registry: "${DEFAULT_REGISTRY}",
+  // Name of the environment variable holding your key - never the key itself.
+  license: "SHADERTOWN_KEY",
+});
+`,
+  );
+  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
+
+  ${c.dim("Usage")}
+    npx shadertown <command> [options]
+
+  ${c.dim("Commands")}
+    login            Connect this terminal to your shadertown account
+    logout           Forget the stored token
+    whoami           Show who this terminal is signed in as
+    add <slug...>    Write a shader's WGSL and typed preset into your repo
+    list             Print the catalogue
+    init             Create shadertown.config.ts
+
+  ${c.dim("Options")}
+    --out <dir>      Output directory            ${c.dim(`(default: ${DEFAULT_OUT})`)}
+    --params <query> Tuned values from a detail page URL
+    --registry <url> Registry base URL           ${c.dim(`(default: ${DEFAULT_REGISTRY})`)}
+    --licensee <name> Name to issue the LICENSE to
+    --force          Overwrite existing files
+
+  ${c.dim("Examples")}
+    npx shadertown add aurora
+    npx shadertown add aurora --params "speed=0.42&exposure=1.6"
+    npx shadertown add voronoi tunnel --out app/shaders
+`);
+}
+
+async function version() {
+  const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  console.log(pkg.version);
+}

package/cli/shadertown.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "./cli.mjs";
+
+run(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`\n  \u001b[31merror\u001b[0m  ${message}\n`);
+  process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+import type { ShaderName, ShaderParams } from "./registry.js";
+import type { PlayMode, QualityOptions } from "./types.js";
+/**
+ * A tuned shader, ready to hand to `<ShaderCanvas />` or `createShaderRenderer`.
+ * This object is the thing you actually author: the slider positions you
+ * settled on, in a form your editor can type-check.
+ */
+export interface ShaderConfig<K extends ShaderName = ShaderName> {
+    readonly shader: K;
+    readonly params?: ShaderParams<K>;
+    readonly quality?: QualityOptions;
+    readonly play?: PlayMode;
+    /** Free-text note, kept so exported presets can explain themselves. */
+    readonly note?: string;
+}
+/** Identity at runtime; it exists so `params` is checked against `shader`. */
+export declare function defineShader<const K extends ShaderName>(config: ShaderConfig<K>): ShaderConfig<K>;
+export interface ShadertownConfig {
+    /** Where `shadertown add` writes vendored shaders. */
+    readonly outDir?: string;
+    /** Registry base URL. Point this at a fork to serve your own catalogue. */
+    readonly registry?: string;
+    /** License key, or the name of the env var holding it. */
+    readonly license?: string;
+    /** Named presets, so a project refers to `presets.hero` rather than a slug. */
+    readonly presets?: Readonly<Record<string, ShaderConfig>>;
+}
+export declare function defineShadertownConfig(config: ShadertownConfig): ShadertownConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAC7D,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEjG;AAED,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC3D;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEjF"}

package/dist/config.js

@@ -0,0 +1,8 @@
+/** Identity at runtime; it exists so `params` is checked against `shader`. */
+export function defineShader(config) {
+    return config;
+}
+export function defineShadertownConfig(config) {
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAiBA,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAA6B,MAAuB;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC;AAaD,MAAM,UAAU,sBAAsB,CAAC,MAAwB;IAC7D,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/export.d.ts

@@ -0,0 +1,30 @@
+import { type ShaderName, type ShaderParams } from "./registry.js";
+/**
+ * Only the values that differ from the registry defaults. Exported snippets
+ * stay short, and a shader's defaults can improve later without silently
+ * changing anyone's pinned look.
+ */
+export declare function diffParams<K extends ShaderName>(name: K, params: ShaderParams<K>): Record<string, number | string>;
+/** A `shader.config.ts` module: the tuned preset, typed against the registry. */
+export declare function toConfigSource<K extends ShaderName>(name: K, params: ShaderParams<K>): string;
+/** A drop-in React usage snippet for the current settings. */
+export declare function toReactSource<K extends ShaderName>(name: K, params: ShaderParams<K>): string;
+/** The imperative form, for codebases that are not React. */
+export declare function toVanillaSource<K extends ShaderName>(name: K, params: ShaderParams<K>): string;
+/** The complete, self-contained WGSL for this shader. */
+export declare function toWgslSource<K extends ShaderName>(name: K): string;
+export declare function toInstallCommand<K extends ShaderName>(name: K): string;
+/** A paste-ready component wired with the tuned parameters. */
+export declare function toExampleSource<K extends ShaderName>(name: K, params: ShaderParams<K>): string;
+/**
+ * Per-shader documentation, generated from the registry rather than written by
+ * hand — the control table cannot drift out of date with the shader.
+ */
+export declare function toReadme<K extends ShaderName>(name: K, params: ShaderParams<K>): string;
+export interface LicenceHolder {
+    readonly name?: string;
+    readonly order?: string;
+}
+/** The licence that ships with a purchased shader, issued to the buyer. */
+export declare function toLicense<K extends ShaderName>(name: K, holder?: LicenceHolder): string;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,UAAU,EAC7C,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAQjC;AAgBD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAW7F;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAoB5F;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAkB9F;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAElE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAEtE;AAOD,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAwB9F;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CA6FvF;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAE,aAAkB,GAAG,MAAM,CAwB3F"}