bluedither 1.0.0 → 1.0.1

package/cli/commands/install.js

@@ -66,6 +66,7 @@ export default async function install(args) {
     ['theme/tokens.schema.json', 'tokens.schema.json'],
     ['theme/structure.json', 'structure.json'],
     ['theme/rules.md', 'rules.md'],
+    ['theme/template/index.html', 'template/index.html'],
     ['theme/shaders/bluedither-shader.js', 'shaders/bluedither-shader.js'],
     ['theme/shaders/paper-shaders-bundle.js', 'shaders/paper-shaders-bundle.js'],
     ['skill.md', 'skill.md'],

package/cli/commands/tune.js

@@ -2,7 +2,9 @@
  * bluedither tune [--port N]
  *
  * Launches the fine-tuner dev server.
- * Finds the nearest bluedither.config.json or theme/ directory.
+ * Finds the nearest bluedither theme directory — either:
+ *   - Source repo layout: ./theme/tokens.json + ./fine-tuner/server.js
+ *   - Installed layout: ./bluedither/tokens.json (from `npx bluedither install`)
  */
 
 import { existsSync } from 'fs';
@@ -11,16 +13,7 @@ import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-
-function findThemeRoot(startDir) {
-  let dir = startDir;
-  while (dir !== dirname(dir)) {
-    if (existsSync(resolve(dir, 'bluedither.config.json'))) return dir;
-    if (existsSync(resolve(dir, 'theme', 'tokens.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return null;
-}
+const PKG_ROOT = resolve(__dirname, '..', '..');
 
 export default async function tune(args) {
   if (args.includes('--help')) {
@@ -28,7 +21,7 @@ export default async function tune(args) {
   bluedither tune [--port N]
 
   Launches the fine-tuner dev server for real-time token editing.
-  Searches upward for bluedither.config.json or theme/tokens.json.
+  Searches for a BlueDither theme in the current directory.
 
   Options:
     --port N    Port number (default: 3333)
@@ -36,28 +29,55 @@ export default async function tune(args) {
     return;
   }
 
-  const themeRoot = findThemeRoot(process.cwd());
+  const cwd = process.cwd();
+
+  // Determine where the theme files live
+  let themeDir = null;
+  let tokensPath = null;
 
-  if (!themeRoot) {
+  // Case 1: Source repo layout (theme/ at cwd root)
+  if (existsSync(resolve(cwd, 'theme', 'tokens.json'))) {
+    themeDir = resolve(cwd, 'theme');
+    tokensPath = resolve(themeDir, 'tokens.json');
+  }
+  // Case 2: Installed layout (bluedither/ subfolder from `npx bluedither install`)
+  else if (existsSync(resolve(cwd, 'bluedither', 'tokens.json'))) {
+    themeDir = resolve(cwd, 'bluedither');
+    tokensPath = resolve(themeDir, 'tokens.json');
+  }
+  // Case 3: Search upward
+  else {
+    let dir = cwd;
+    while (dir !== dirname(dir)) {
+      if (existsSync(resolve(dir, 'theme', 'tokens.json'))) {
+        themeDir = resolve(dir, 'theme');
+        tokensPath = resolve(themeDir, 'tokens.json');
+        break;
+      }
+      if (existsSync(resolve(dir, 'bluedither', 'tokens.json'))) {
+        themeDir = resolve(dir, 'bluedither');
+        tokensPath = resolve(themeDir, 'tokens.json');
+        break;
+      }
+      dir = dirname(dir);
+    }
+  }
+
+  if (!themeDir) {
     console.error('Could not find a BlueDither theme directory.');
-    console.error('Run this from a directory containing bluedither.config.json or theme/tokens.json.');
+    console.error('Run this from a project with bluedither/ or theme/ containing tokens.json.');
     process.exit(1);
   }
 
-  const serverPath = resolve(themeRoot, 'fine-tuner', 'server.js');
-
+  // The fine-tuner server lives in the npm package
+  const serverPath = resolve(PKG_ROOT, 'fine-tuner', 'server.js');
   if (!existsSync(serverPath)) {
-    // If we're in an installed theme (not the source repo), use the source repo's server
-    const sourceServer = resolve(__dirname, '..', '..', 'fine-tuner', 'server.js');
-    if (!existsSync(sourceServer)) {
-      console.error('Fine-tuner server not found.');
-      process.exit(1);
-    }
-    const child = spawn('node', [sourceServer, ...args], { cwd: themeRoot, stdio: 'inherit' });
-    child.on('exit', (code) => process.exit(code || 0));
-    return;
+    console.error('Fine-tuner server not found at: ' + serverPath);
+    process.exit(1);
   }
 
-  const child = spawn('node', [serverPath, ...args], { cwd: themeRoot, stdio: 'inherit' });
+  // Pass the theme directory to the server via env var
+  const env = { ...process.env, BD_THEME_DIR: themeDir };
+  const child = spawn('node', [serverPath, ...args], { cwd: dirname(themeDir), env, stdio: 'inherit' });
   child.on('exit', (code) => process.exit(code || 0));
 }

package/fine-tuner/server.js

@@ -0,0 +1,283 @@
+/**
+ * BlueDither Fine-Tuner Dev Server
+ *
+ * Serves the rendered theme with tuner overlay.
+ * Computes clamp() values from reference px values at render time.
+ * Handles "commit" to write tokens back to disk.
+ *
+ * Usage: node fine-tuner/server.js [--port 3333]
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { createServer } from 'http';
+import { resolve, extname, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// BD_THEME_DIR env var is set by `bluedither tune` for installed themes
+const THEME_DIR = process.env.BD_THEME_DIR || resolve(__dirname, '..', 'theme');
+const TOKENS_PATH = resolve(THEME_DIR, 'tokens.json');
+const PORT = parseInt(process.argv.find((_, i, a) => a[i - 1] === '--port') || '3333', 10);
+
+function loadTokens() {
+  return JSON.parse(readFileSync(TOKENS_PATH, 'utf-8'));
+}
+
+function resolveTokenPath(obj, path) {
+  return path.split('.').reduce((o, k) => (o && o[k] !== undefined ? o[k] : ''), obj);
+}
+
+/**
+ * Compute a clamp() value from a reference px size.
+ * Formula: clamp(minRem, vwValue, maxRem)
+ * - max = referencePx / 16 (rem at design width)
+ * - vw = referencePx / designWidth * 100
+ * - min = max * 0.55 (scales down to ~55% on small screens)
+ */
+function pxToClamp(px, designWidth) {
+  const maxRem = px / 16;
+  const vw = (px / designWidth) * 100;
+  const minRem = maxRem * 0.55;
+  return `clamp(${minRem.toFixed(4)}rem, ${vw.toFixed(4)}vw, ${maxRem.toFixed(4)}rem)`;
+}
+
+/**
+ * Build computed clamp values from tokens.
+ */
+function buildClampValues(tokens) {
+  const dw = tokens.layout.designWidth;
+  const t = tokens.typography;
+  const s = tokens.spacing;
+
+  return {
+    headline: {
+      fontSize: pxToClamp(t.headline.referencePx, dw),
+      lineHeight: pxToClamp(t.headline.lineHeightPx, dw),
+    },
+    subHeadline: {
+      fontSize: pxToClamp(t.subHeadline.referencePx, dw),
+      lineHeight: pxToClamp(t.subHeadline.lineHeightPx, dw),
+    },
+    logo: {
+      fontSize: pxToClamp(t.logo.referencePx, dw),
+      lineHeight: pxToClamp(t.logo.lineHeightPx, dw),
+    },
+    navItem: {
+      fontSize: pxToClamp(t.navItem.referencePx, dw),
+      lineHeight: pxToClamp(t.navItem.lineHeightPx, dw),
+    },
+    ctaButton: {
+      fontSize: pxToClamp(t.ctaButton.referencePx, dw),
+      lineHeight: pxToClamp(t.ctaButton.lineHeightPx, dw),
+    },
+    spacing: {
+      headerPaddingX: pxToClamp(s.headerPaddingX, dw),
+      headerPaddingY: pxToClamp(s.headerPaddingY, dw),
+      heroPaddingTop: pxToClamp(s.heroPaddingTop, dw),
+      heroPaddingBottom: pxToClamp(s.heroPaddingBottom, dw),
+      heroPaddingX: pxToClamp(s.heroPaddingX, dw),
+      navGap: pxToClamp(s.navGap, dw),
+      ctaPaddingX: pxToClamp(s.ctaPaddingX, dw),
+      ctaPaddingY: pxToClamp(s.ctaPaddingY, dw),
+      ctaBorderRadius: `${(s.ctaBorderRadius / 16).toFixed(4)}rem`,
+    },
+  };
+}
+
+function renderFullPage(tokens) {
+  let template = readFileSync(resolve(THEME_DIR, 'template', 'index.html'), 'utf-8');
+
+  // Build clamp values
+  const clamp = buildClampValues(tokens);
+  const renderData = { ...tokens, clamp };
+
+  // Handle font URL encoding for Google Fonts links
+  template = template.replace(/\{\{typography\.primaryFont\.urlEncoded\}\}/g,
+    encodeURIComponent(tokens.typography.primaryFont));
+  template = template.replace(/\{\{typography\.secondaryFont\.urlEncoded\}\}/g,
+    encodeURIComponent(tokens.typography.secondaryFont));
+
+  // Handle {{#each}} blocks
+  template = template.replace(
+    /\{\{#each\s+([^}]+)\}\}([\s\S]*?)\{\{\/each\}\}/g,
+    (_, arrayPath, inner) => {
+      const arr = resolveTokenPath(renderData, arrayPath.trim());
+      if (!Array.isArray(arr)) return '';
+      return arr.map(item => inner.replace(/\{\{this\}\}/g, item)).join('\n');
+    }
+  );
+
+  // Replace remaining {{path}} tokens
+  template = template.replace(/\{\{([^#/][^}]*)\}\}/g, (_, path) => {
+    const val = resolveTokenPath(renderData, path.trim());
+    return val !== undefined && val !== '' ? val : '';
+  });
+
+  // Fix headline newlines
+  template = template.replace(
+    /(<div class="bd-headline">)([\s\S]*?)(<\/div>)/,
+    (_, open, content, close) => open + content.replace(/\n/g, '<br>') + close
+  );
+
+  // Inject shader, tokens, and tuner
+  const shaderJS = readFileSync(resolve(THEME_DIR, 'shaders', 'bluedither-shader.js'), 'utf-8');
+  const shaderBundle = readFileSync(resolve(THEME_DIR, 'shaders', 'paper-shaders-bundle.js'), 'utf-8');
+  const tunerCSS = readFileSync(resolve(__dirname, 'tuner.css'), 'utf-8');
+  const tunerJS = readFileSync(resolve(__dirname, 'tuner.js'), 'utf-8');
+
+  const injection = `
+    <script>
+      window.__BD_TOKENS__ = ${JSON.stringify(tokens, null, 2)};
+      window.__BD_DEFAULTS__ = ${JSON.stringify(loadDefaults(), null, 2)};
+    </script>
+    <script type="module">
+      // Paper shaders bundle (inlined)
+      ${shaderBundle}
+
+      // BlueDither shader module (inlined, imports resolved above)
+      const shapeEnum = { simplex: 1, warp: 2, dots: 3, wave: 4, ripple: 5, swirl: 6, sphere: 7 };
+      const typeEnum = { random: 1, '2x2': 2, '4x4': 3, '8x8': 4 };
+
+      const parentEl = document.getElementById('bd-shader-parent');
+      const tokens = window.__BD_TOKENS__;
+
+      const uniforms = {
+        u_colorFront: getShaderColorFromString(tokens.colors.shaderFront),
+        u_colorBack: getShaderColorFromString(tokens.colors.shaderBack),
+        u_shape: shapeEnum[tokens.shader.shape] || 2,
+        u_type: typeEnum[tokens.shader.type] || 2,
+        u_pxSize: tokens.shader.size,
+        u_scale: tokens.shader.scale,
+        u_rotation: 0,
+        u_originX: 0.5,
+        u_originY: 0.5,
+        u_worldWidth: 0,
+        u_worldHeight: 0,
+        u_fit: 0,
+        u_offsetX: 0,
+        u_offsetY: 0,
+      };
+
+      const mount = new ShaderMount(
+        parentEl,
+        ditheringFragmentShader,
+        uniforms,
+        { alpha: true, premultipliedAlpha: false },
+        tokens.shader.speed,
+        0,
+        2,
+      );
+
+      // Expose for tuner
+      window.__BD_SHADER__ = {
+        updateParams(p) {
+          const u = {};
+          if (p.colorFront !== undefined) u.u_colorFront = getShaderColorFromString(p.colorFront);
+          if (p.colorBack !== undefined) u.u_colorBack = getShaderColorFromString(p.colorBack);
+          if (p.shape !== undefined) u.u_shape = shapeEnum[p.shape] || 2;
+          if (p.type !== undefined) u.u_type = typeEnum[p.type] || 2;
+          if (p.size !== undefined) u.u_pxSize = p.size;
+          if (p.scale !== undefined) u.u_scale = p.scale;
+          if (p.speed !== undefined) mount.setSpeed(p.speed);
+          if (Object.keys(u).length > 0) mount.setUniforms(u);
+        },
+        destroy() { mount.dispose(); }
+      };
+    </script>
+    <style>${tunerCSS}</style>
+    <script type="module">${tunerJS}</script>
+  `;
+
+  template = template.replace('</body>', injection + '\n</body>');
+  return template;
+}
+
+function loadDefaults() {
+  // Store the original shipped tokens as defaults for reset
+  const defaultsPath = resolve(THEME_DIR, 'tokens.defaults.json');
+  try {
+    return JSON.parse(readFileSync(defaultsPath, 'utf-8'));
+  } catch {
+    // If no defaults file, current tokens ARE the defaults
+    return loadTokens();
+  }
+}
+
+const MIME = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.svg': 'image/svg+xml',
+  '.woff2': 'font/woff2',
+};
+
+const server = createServer((req, res) => {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  if (req.method === 'POST' && req.url === '/commit') {
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', () => {
+      try {
+        const updatedTokens = JSON.parse(body);
+        writeFileSync(TOKENS_PATH, JSON.stringify(updatedTokens, null, 2) + '\n', 'utf-8');
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, message: 'Tokens committed to disk.' }));
+        console.log('[BlueDither] Tokens committed successfully.');
+      } catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: e.message }));
+      }
+    });
+    return;
+  }
+
+  if (req.method === 'GET' && req.url === '/tokens') {
+    const tokens = loadTokens();
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(tokens));
+    return;
+  }
+
+  if (req.method === 'GET' && (req.url === '/' || req.url === '/index.html')) {
+    try {
+      const tokens = loadTokens();
+      const page = renderFullPage(tokens);
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(page);
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end('Server error: ' + e.message + '\n' + e.stack);
+    }
+    return;
+  }
+
+  // Static files from assets
+  const filePath = resolve(THEME_DIR, 'assets', req.url.slice(1));
+  try {
+    const data = readFileSync(filePath);
+    const ext = extname(filePath);
+    res.writeHead(200, { 'Content-Type': MIME[ext] || 'application/octet-stream' });
+    res.end(data);
+  } catch {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`\n  BlueDither Fine-Tuner running at http://localhost:${PORT}\n`);
+  console.log(`  Tokens: ${TOKENS_PATH}`);
+  console.log(`  Edit in browser → hit Commit → tokens.json updated on disk.\n`);
+});

package/fine-tuner/tuner.css

@@ -0,0 +1,362 @@
+/* =============================================
+   BlueDither Fine-Tuner — Overlay Panel v2
+   ============================================= */
+
+#bd-tuner {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  width: 320px;
+  max-height: calc(100vh - 32px);
+  overflow-y: auto;
+  background: rgba(10, 10, 20, 0.92);
+  backdrop-filter: blur(16px);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 12px;
+  padding: 20px;
+  z-index: 9999;
+  font-family: "SF Mono", "Cascadia Code", "Consolas", monospace;
+  font-size: 12px;
+  color: #e0e0e0;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5);
+  transition: transform 0.2s ease;
+}
+
+#bd-tuner.collapsed {
+  transform: translateX(calc(100% + 32px));
+}
+
+#bd-tuner-toggle {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  z-index: 10000;
+  background: rgba(10, 10, 20, 0.92);
+  backdrop-filter: blur(16px);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 8px;
+  color: #e0e0e0;
+  padding: 8px 12px;
+  cursor: pointer;
+  font-family: "SF Mono", "Cascadia Code", "Consolas", monospace;
+  font-size: 11px;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  display: none;
+}
+
+#bd-tuner.collapsed ~ #bd-tuner-toggle {
+  display: block;
+}
+
+.bd-tuner-title {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: #888;
+  margin-bottom: 16px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.bd-tuner-title button {
+  background: none;
+  border: none;
+  color: #666;
+  cursor: pointer;
+  font-size: 16px;
+  line-height: 1;
+  padding: 0;
+}
+
+.bd-tuner-title button:hover {
+  color: #fff;
+}
+
+#bd-tuner-reset {
+  font-size: 18px !important;
+}
+
+.bd-tuner-section {
+  margin-bottom: 16px;
+  padding-bottom: 16px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.bd-tuner-section:last-of-type {
+  border-bottom: none;
+  margin-bottom: 8px;
+}
+
+.bd-tuner-section-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: #666;
+  margin-bottom: 10px;
+}
+
+/* ── Row layouts ── */
+
+.bd-tuner-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.bd-tuner-row:last-child {
+  margin-bottom: 0;
+}
+
+.bd-tuner-row-stacked {
+  flex-direction: column;
+  align-items: stretch;
+  gap: 4px;
+}
+
+.bd-tuner-row-top {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.bd-tuner-label {
+  font-size: 11px;
+  color: #999;
+  flex-shrink: 0;
+  width: 110px;
+}
+
+.bd-tuner-value {
+  font-size: 10px;
+  color: #666;
+  text-align: right;
+  flex-shrink: 0;
+}
+
+.bd-tuner-input {
+  flex: 1;
+  min-width: 0;
+}
+
+/* ── Color input ── */
+
+.bd-tuner-input input[type="color"] {
+  width: 32px;
+  height: 24px;
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 4px;
+  cursor: pointer;
+  background: none;
+  padding: 0;
+}
+
+/* ── Slider ── */
+
+.bd-tuner-slider {
+  width: 100%;
+  height: 4px;
+  -webkit-appearance: none;
+  appearance: none;
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 2px;
+  outline: none;
+}
+
+.bd-tuner-slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  background: #fff;
+  cursor: pointer;
+}
+
+/* ── Px input with number + unit ── */
+
+.bd-tuner-px-input-wrap {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+}
+
+.bd-tuner-px-num {
+  width: 56px;
+  background: rgba(255, 255, 255, 0.06);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 4px;
+  color: #e0e0e0;
+  padding: 3px 6px;
+  font-family: inherit;
+  font-size: 11px;
+  outline: none;
+  text-align: right;
+  -moz-appearance: textfield;
+}
+
+.bd-tuner-px-num::-webkit-inner-spin-button,
+.bd-tuner-px-num::-webkit-outer-spin-button {
+  -webkit-appearance: none;
+  margin: 0;
+}
+
+.bd-tuner-px-num:focus {
+  border-color: rgba(51, 0, 255, 0.5);
+}
+
+.bd-tuner-unit {
+  font-size: 10px;
+  color: #555;
+  width: 16px;
+}
+
+/* ── Font dropdown ── */
+
+.bd-tuner-font-input {
+  position: relative;
+}
+
+.bd-tuner-font-search {
+  width: 100%;
+  background: rgba(255, 255, 255, 0.06);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 4px;
+  color: #e0e0e0;
+  padding: 5px 8px;
+  font-family: inherit;
+  font-size: 11px;
+  outline: none;
+}
+
+.bd-tuner-font-search:focus {
+  border-color: rgba(51, 0, 255, 0.5);
+}
+
+.bd-tuner-font-dropdown {
+  display: none;
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  max-height: 200px;
+  overflow-y: auto;
+  background: rgba(15, 15, 25, 0.98);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 4px;
+  margin-top: 2px;
+  z-index: 100;
+}
+
+.bd-tuner-font-dropdown.open {
+  display: block;
+}
+
+.bd-tuner-font-option {
+  padding: 6px 8px;
+  font-size: 13px;
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.bd-tuner-font-option:hover {
+  background: rgba(51, 0, 255, 0.3);
+}
+
+.bd-tuner-font-dropdown::-webkit-scrollbar {
+  width: 4px;
+}
+
+.bd-tuner-font-dropdown::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 2px;
+}
+
+/* ── Segmented buttons ── */
+
+.bd-tuner-segmented {
+  display: flex;
+  gap: 1px;
+  background: rgba(255, 255, 255, 0.06);
+  border-radius: 4px;
+  overflow: hidden;
+  margin-top: 4px;
+}
+
+.bd-tuner-seg-btn {
+  flex: 1;
+  padding: 5px 4px;
+  background: transparent;
+  border: none;
+  color: #888;
+  font-family: inherit;
+  font-size: 10px;
+  cursor: pointer;
+  text-transform: capitalize;
+  transition: background 0.1s, color 0.1s;
+}
+
+.bd-tuner-seg-btn:hover {
+  background: rgba(255, 255, 255, 0.06);
+  color: #ccc;
+}
+
+.bd-tuner-seg-btn.active {
+  background: rgba(51, 0, 255, 0.5);
+  color: #fff;
+}
+
+/* ── Text inputs ── */
+
+.bd-tuner-input input[type="text"],
+.bd-tuner-input input[type="number"] {
+  width: 100%;
+  background: rgba(255, 255, 255, 0.06);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 4px;
+  color: #e0e0e0;
+  padding: 4px 8px;
+  font-family: inherit;
+  font-size: 11px;
+  outline: none;
+}
+
+.bd-tuner-input input[type="text"]:focus,
+.bd-tuner-input input[type="number"]:focus {
+  border-color: rgba(51, 0, 255, 0.5);
+}
+
+/* ── Commit button ── */
+
+#bd-tuner-commit {
+  width: 100%;
+  padding: 10px;
+  background: #3300FF;
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  cursor: pointer;
+  transition: background 0.15s ease;
+  margin-top: 8px;
+}
+
+#bd-tuner-commit:hover { background: #4400FF; }
+#bd-tuner-commit:active { background: #2200CC; }
+#bd-tuner-commit.success { background: #0a7; }
+
+/* ── Scrollbar ── */
+
+#bd-tuner::-webkit-scrollbar { width: 4px; }
+#bd-tuner::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 2px;
+}

package/fine-tuner/tuner.js

@@ -0,0 +1,445 @@
+/**
+ * BlueDither Fine-Tuner — Overlay UI v2
+ *
+ * Features:
+ * - Google Fonts searchable dropdown for font selection
+ * - Slider + arrow key support for numeric/px fields
+ * - Responsive clamp() computation from reference px
+ * - Reset button to restore shipped defaults
+ * - Real-time shader parameter updates
+ */
+
+const tokens = structuredClone(
+  window.__BD_TOKENS__ ||
+  JSON.parse(document.querySelector('script[type="application/json"][data-bluedither-tokens]')?.textContent || '{}')
+);
+const defaults = structuredClone(
+  window.__BD_DEFAULTS__ ||
+  JSON.parse(document.querySelector('script[type="application/json"][data-bluedither-defaults]')?.textContent || '{}')
+);
+
+/** True when served by fine-tuner/server.js (has /commit endpoint) */
+const __serverMode = !!(window.__BD_TOKENS__ && window.__BD_DEFAULTS__);
+
+// ── System fonts (always available, no loading needed) ──
+const SYSTEM_FONTS = [
+  'Arial', 'Arial Black', 'Bebas Neue Pro', 'Consolas', 'Courier New',
+  'Georgia', 'Helvetica', 'Impact', 'Lucida Console', 'Segoe UI',
+  'Tahoma', 'Times New Roman', 'Trebuchet MS', 'Verdana',
+  'SF Pro Display', 'SF Mono', 'Cascadia Code', 'Menlo', 'Monaco',
+];
+
+// ── Google Fonts (loaded on demand) ──
+const GOOGLE_FONTS = [
+  'Bebas Neue', 'Space Mono', 'Inter', 'Roboto', 'Roboto Mono', 'Roboto Condensed',
+  'Open Sans', 'Montserrat', 'Lato', 'Oswald', 'Raleway', 'Poppins',
+  'Nunito', 'Playfair Display', 'Merriweather', 'Source Sans 3', 'Source Code Pro',
+  'PT Sans', 'PT Serif', 'PT Mono', 'Ubuntu', 'Ubuntu Mono', 'Fira Sans',
+  'Fira Code', 'Fira Mono', 'Work Sans', 'Noto Sans', 'Noto Serif',
+  'DM Sans', 'DM Serif Display', 'DM Mono', 'IBM Plex Sans', 'IBM Plex Mono',
+  'IBM Plex Serif', 'JetBrains Mono', 'Inconsolata', 'Space Grotesk',
+  'Archivo', 'Archivo Black', 'Barlow', 'Barlow Condensed', 'Lexend',
+  'Outfit', 'Sora', 'Manrope', 'Bitter', 'Crimson Text', 'Libre Baskerville',
+  'Abril Fatface', 'Anton', 'Permanent Marker', 'Righteous', 'Orbitron',
+  'Teko', 'Rubik', 'Quicksand', 'Cabin', 'Karla', 'Josefin Sans',
+  'Comfortaa', 'Fredoka', 'Geologica', 'Instrument Sans', 'Instrument Serif',
+];
+
+// Combined and deduplicated
+const ALL_FONTS = [...new Set([...SYSTEM_FONTS, ...GOOGLE_FONTS])].sort();
+
+// ── Helpers ──
+
+function setTokenPath(obj, path, value) {
+  const keys = path.split('.');
+  let o = obj;
+  for (let i = 0; i < keys.length - 1; i++) o = o[keys[i]];
+  o[keys[keys.length - 1]] = value;
+}
+
+function getTokenPath(obj, path) {
+  return path.split('.').reduce((o, k) => o?.[k], obj);
+}
+
+function setCSSVar(name, value) {
+  document.documentElement.style.setProperty(name, value);
+}
+
+function updateShader(key, value) {
+  const renderer = window.__BD_SHADER__;
+  if (renderer) renderer.updateParams({ [key]: value });
+}
+
+function pxToClamp(px) {
+  const dw = tokens.layout.designWidth;
+  const maxRem = px / 16;
+  const vw = (px / dw) * 100;
+  const minRem = maxRem * 0.55;
+  return `clamp(${minRem.toFixed(4)}rem, ${vw.toFixed(4)}vw, ${maxRem.toFixed(4)}rem)`;
+}
+
+function loadGoogleFont(family) {
+  const id = 'bd-gf-' + family.replace(/\s+/g, '-').toLowerCase();
+  if (document.getElementById(id)) return;
+  const link = document.createElement('link');
+  link.id = id;
+  link.rel = 'stylesheet';
+  link.href = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family)}:wght@400;700&display=swap`;
+  document.head.appendChild(link);
+}
+
+// ── Build the tuner panel ──
+
+const panel = document.createElement('div');
+panel.id = 'bd-tuner';
+
+const toggle = document.createElement('button');
+toggle.id = 'bd-tuner-toggle';
+toggle.textContent = 'Tuner';
+toggle.onclick = () => panel.classList.remove('collapsed');
+
+document.body.appendChild(panel);
+document.body.appendChild(toggle);
+
+// Title bar
+panel.innerHTML = `
+  <div class="bd-tuner-title">
+    <span>BlueDither Tuner</span>
+    <div style="display:flex;gap:8px;align-items:center;">
+      <button id="bd-tuner-reset" title="Reset to defaults">&#8635;</button>
+      <button id="bd-tuner-close" title="Close">&times;</button>
+    </div>
+  </div>
+`;
+panel.querySelector('#bd-tuner-close').onclick = () => panel.classList.add('collapsed');
+panel.querySelector('#bd-tuner-reset').onclick = () => {
+  if (!confirm('Reset all tokens to defaults?')) return;
+  Object.assign(tokens, structuredClone(defaults));
+  if (__serverMode) {
+    fetch('/commit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(tokens, null, 2)
+    }).then(() => location.reload());
+  } else {
+    location.reload();
+  }
+};
+
+// ── Section builders ──
+
+function addSection(label) {
+  const sec = document.createElement('div');
+  sec.className = 'bd-tuner-section';
+  sec.innerHTML = `<div class="bd-tuner-section-label">${label}</div>`;
+  panel.appendChild(sec);
+  return sec;
+}
+
+function addColor(section, label, tokenPath, cssVar, extraCb) {
+  const val = getTokenPath(tokens, tokenPath) || '#000000';
+  const row = document.createElement('div');
+  row.className = 'bd-tuner-row';
+  row.innerHTML = `
+    <span class="bd-tuner-label">${label}</span>
+    <span class="bd-tuner-input"><input type="color" value="${val.substring(0, 7)}"></span>
+    <span class="bd-tuner-value">${val.substring(0, 7)}</span>
+  `;
+  const input = row.querySelector('input');
+  const display = row.querySelector('.bd-tuner-value');
+  input.addEventListener('input', (e) => {
+    const v = e.target.value;
+    setTokenPath(tokens, tokenPath, v);
+    display.textContent = v;
+    if (cssVar) setCSSVar(cssVar, v);
+    if (extraCb) extraCb(v);
+  });
+  section.appendChild(row);
+
+  // Return a handle so linked controls can programmatically update this row
+  return {
+    setValue(v) {
+      setTokenPath(tokens, tokenPath, v);
+      input.value = v.substring(0, 7);
+      display.textContent = v.substring(0, 7);
+      if (cssVar) setCSSVar(cssVar, v);
+    }
+  };
+}
+
+/**
+ * Numeric px field with slider + arrow key support.
+ * The displayed value is in px (reference), but CSS uses clamp().
+ */
+function addPxField(section, label, tokenPath, min, max, step, cssVars) {
+  const val = getTokenPath(tokens, tokenPath);
+  const row = document.createElement('div');
+  row.className = 'bd-tuner-row bd-tuner-row-stacked';
+  row.innerHTML = `
+    <div class="bd-tuner-row-top">
+      <span class="bd-tuner-label">${label}</span>
+      <div class="bd-tuner-px-input-wrap">
+        <input type="number" class="bd-tuner-px-num" value="${val}" min="${min}" max="${max}" step="${step}">
+        <span class="bd-tuner-unit">px</span>
+      </div>
+    </div>
+    <input type="range" class="bd-tuner-slider" min="${min}" max="${max}" step="${step}" value="${val}">
+  `;
+  const numInput = row.querySelector('.bd-tuner-px-num');
+  const slider = row.querySelector('.bd-tuner-slider');
+
+  function apply(v) {
+    v = Math.max(min, Math.min(max, v));
+    setTokenPath(tokens, tokenPath, v);
+    numInput.value = v;
+    slider.value = v;
+    if (cssVars) {
+      const clampVal = pxToClamp(v);
+      (Array.isArray(cssVars) ? cssVars : [cssVars]).forEach(cv => setCSSVar(cv, clampVal));
+    }
+  }
+
+  numInput.addEventListener('input', (e) => apply(parseFloat(e.target.value) || 0));
+  slider.addEventListener('input', (e) => apply(parseFloat(e.target.value)));
+
+  // Arrow keys on the number input: +/- step, shift for 10x
+  numInput.addEventListener('keydown', (e) => {
+    if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
+      e.preventDefault();
+      const mult = e.shiftKey ? 10 : 1;
+      const delta = (e.key === 'ArrowUp' ? step : -step) * mult;
+      apply(parseFloat(numInput.value) + delta);
+    }
+  });
+
+  section.appendChild(row);
+}
+
+/**
+ * Shader-specific range slider (not px-based).
+ */
+function addRange(section, label, tokenPath, min, max, step, extraCb) {
+  const val = getTokenPath(tokens, tokenPath);
+  const row = document.createElement('div');
+  row.className = 'bd-tuner-row bd-tuner-row-stacked';
+  row.innerHTML = `
+    <div class="bd-tuner-row-top">
+      <span class="bd-tuner-label">${label}</span>
+      <span class="bd-tuner-value">${val}</span>
+    </div>
+    <input type="range" class="bd-tuner-slider" min="${min}" max="${max}" step="${step}" value="${val}">
+  `;
+  const slider = row.querySelector('.bd-tuner-slider');
+  const display = row.querySelector('.bd-tuner-value');
+  slider.addEventListener('input', (e) => {
+    const v = parseFloat(e.target.value);
+    setTokenPath(tokens, tokenPath, v);
+    display.textContent = v;
+    if (extraCb) extraCb(v);
+  });
+  section.appendChild(row);
+}
+
+/**
+ * Font family dropdown with Google Fonts.
+ */
+function addFontDropdown(section, label, tokenPath, cssVar) {
+  const currentFont = getTokenPath(tokens, tokenPath);
+  const row = document.createElement('div');
+  row.className = 'bd-tuner-row';
+  row.innerHTML = `
+    <span class="bd-tuner-label">${label}</span>
+    <span class="bd-tuner-input bd-tuner-font-input">
+      <input type="text" class="bd-tuner-font-search" value="${currentFont}" placeholder="Search fonts...">
+      <div class="bd-tuner-font-dropdown"></div>
+    </span>
+  `;
+
+  const searchInput = row.querySelector('.bd-tuner-font-search');
+  const dropdown = row.querySelector('.bd-tuner-font-dropdown');
+
+  const isSystemFont = (f) => SYSTEM_FONTS.some(s => s.toLowerCase() === f.toLowerCase());
+
+  function populateDropdown(filter = '') {
+    const filtered = ALL_FONTS.filter(f =>
+      f.toLowerCase().includes(filter.toLowerCase())
+    ).slice(0, 20);
+
+    dropdown.innerHTML = filtered.map(f => {
+      const badge = isSystemFont(f) ? ' <span style="opacity:0.4;font-size:9px">SYSTEM</span>' : '';
+      return `<div class="bd-tuner-font-option" data-font="${f}" style="font-family:'${f}',system-ui">${f}${badge}</div>`;
+    }).join('');
+
+    // Preload only Google Fonts (system fonts are already available)
+    filtered.filter(f => !isSystemFont(f)).forEach(loadGoogleFont);
+
+    dropdown.querySelectorAll('.bd-tuner-font-option').forEach(opt => {
+      opt.addEventListener('mousedown', (e) => {
+        e.preventDefault();
+        const font = opt.dataset.font;
+        searchInput.value = font;
+        setTokenPath(tokens, tokenPath, font);
+        if (!isSystemFont(font)) loadGoogleFont(font);
+        setCSSVar(cssVar, `"${font}", system-ui, sans-serif`);
+        dropdown.classList.remove('open');
+      });
+    });
+  }
+
+  searchInput.addEventListener('focus', () => {
+    populateDropdown(searchInput.value);
+    dropdown.classList.add('open');
+  });
+
+  searchInput.addEventListener('input', () => {
+    populateDropdown(searchInput.value);
+    dropdown.classList.add('open');
+  });
+
+  searchInput.addEventListener('blur', () => {
+    setTimeout(() => dropdown.classList.remove('open'), 150);
+  });
+
+  // Also update on Enter
+  searchInput.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') {
+      const font = searchInput.value.trim();
+      if (font) {
+        setTokenPath(tokens, tokenPath, font);
+        if (!isSystemFont(font)) loadGoogleFont(font);
+        setCSSVar(cssVar, `"${font}", system-ui, sans-serif`);
+        dropdown.classList.remove('open');
+        searchInput.blur();
+      }
+    }
+  });
+
+  section.appendChild(row);
+}
+
+/**
+ * Segmented button control (for shader type/shape).
+ */
+function addSegmented(section, label, tokenPath, options, extraCb) {
+  const val = getTokenPath(tokens, tokenPath);
+  const row = document.createElement('div');
+  row.className = 'bd-tuner-row bd-tuner-row-stacked';
+  row.innerHTML = `
+    <span class="bd-tuner-label">${label}</span>
+    <div class="bd-tuner-segmented">
+      ${options.map(o => `<button class="bd-tuner-seg-btn${o === val ? ' active' : ''}" data-val="${o}">${o}</button>`).join('')}
+    </div>
+  `;
+  row.querySelectorAll('.bd-tuner-seg-btn').forEach(btn => {
+    btn.addEventListener('click', () => {
+      row.querySelectorAll('.bd-tuner-seg-btn').forEach(b => b.classList.remove('active'));
+      btn.classList.add('active');
+      const v = btn.dataset.val;
+      setTokenPath(tokens, tokenPath, v);
+      if (extraCb) extraCb(v);
+    });
+  });
+  section.appendChild(row);
+}
+
+// ══════════════════════════════════════════════
+// Build sections
+// ══════════════════════════════════════════════
+
+// ── Colors ──
+const colorsSection = addSection('Colors');
+addColor(colorsSection, 'Background', 'colors.background', '--bd-color-background');
+// Shader Front is declared first (but appended later) so Primary can reference it
+let shaderFrontHandle;
+addColor(colorsSection, 'Primary', 'colors.primary', '--bd-color-primary', (v) => {
+  // Sync shader front color: update token, UI, and live shader
+  shaderFrontHandle.setValue(v);
+  updateShader('colorFront', v);
+});
+addColor(colorsSection, 'Text', 'colors.text', '--bd-color-text');
+addColor(colorsSection, 'CTA Background', 'colors.ctaBackground', '--bd-color-cta-bg');
+addColor(colorsSection, 'CTA Text', 'colors.ctaText', '--bd-color-cta-text');
+shaderFrontHandle = addColor(colorsSection, 'Shader Front', 'colors.shaderFront', null, (v) => updateShader('colorFront', v));
+
+// ── Typography ──
+const typoSection = addSection('Typography');
+addFontDropdown(typoSection, 'Primary Font', 'typography.primaryFont', '--bd-font-primary');
+addFontDropdown(typoSection, 'Secondary Font', 'typography.secondaryFont', '--bd-font-secondary');
+addPxField(typoSection, 'Headline Size', 'typography.headline.referencePx', 32, 300, 1, '--bd-headline-size');
+addPxField(typoSection, 'Headline LH', 'typography.headline.lineHeightPx', 24, 280, 1, '--bd-headline-lh');
+addPxField(typoSection, 'Sub Size', 'typography.subHeadline.referencePx', 10, 48, 1, '--bd-subheadline-size');
+addPxField(typoSection, 'Sub LH', 'typography.subHeadline.lineHeightPx', 12, 80, 1, '--bd-subheadline-lh');
+addPxField(typoSection, 'Logo Size', 'typography.logo.referencePx', 12, 80, 1, '--bd-logo-size');
+addPxField(typoSection, 'Nav Size', 'typography.navItem.referencePx', 10, 48, 1, '--bd-nav-size');
+
+// ── Spacing ──
+const spacingSection = addSection('Spacing');
+addPxField(spacingSection, 'Header Pad X', 'spacing.headerPaddingX', 0, 80, 1, '--bd-header-px');
+addPxField(spacingSection, 'Header Pad Y', 'spacing.headerPaddingY', 0, 60, 1, '--bd-header-py');
+addPxField(spacingSection, 'Hero Pad Top', 'spacing.heroPaddingTop', 0, 120, 1, '--bd-hero-pt');
+addPxField(spacingSection, 'Hero Pad Bottom', 'spacing.heroPaddingBottom', 0, 120, 1, '--bd-hero-pb');
+addPxField(spacingSection, 'Hero Pad X', 'spacing.heroPaddingX', 0, 120, 1, '--bd-hero-px');
+addPxField(spacingSection, 'Nav Gap', 'spacing.navGap', 0, 100, 1, '--bd-nav-gap');
+addPxField(spacingSection, 'CTA Pad X', 'spacing.ctaPaddingX', 0, 60, 1, '--bd-cta-px');
+addPxField(spacingSection, 'CTA Pad Y', 'spacing.ctaPaddingY', 0, 30, 1, '--bd-cta-py');
+addPxField(spacingSection, 'CTA Radius', 'spacing.ctaBorderRadius', 0, 32, 1, '--bd-cta-radius');
+
+// ── Shader ──
+const shaderSection = addSection('Shader');
+addSegmented(shaderSection, 'Shape', 'shader.shape',
+  ['warp', 'simplex', 'dots', 'wave', 'ripple', 'swirl', 'sphere'],
+  (v) => updateShader('shape', v));
+addSegmented(shaderSection, 'Dither Type', 'shader.type',
+  ['random', '2x2', '4x4', '8x8'],
+  (v) => updateShader('type', v));
+addRange(shaderSection, 'Speed', 'shader.speed', 0, 2, 0.01, (v) => updateShader('speed', v));
+addRange(shaderSection, 'Scale', 'shader.scale', 0.1, 5, 0.01, (v) => updateShader('scale', v));
+addRange(shaderSection, 'Dither Size', 'shader.size', 0.5, 10, 0.1, (v) => updateShader('size', v));
+
+// ── Opacity ──
+const opacitySection = addSection('Opacity');
+addRange(opacitySection, 'Nav Links', 'opacity.navLinks', 0, 1, 0.01, (v) => setCSSVar('--bd-nav-opacity', v));
+
+// ── Commit button ──
+const commitBtn = document.createElement('button');
+commitBtn.id = 'bd-tuner-commit';
+commitBtn.textContent = 'Commit Changes';
+const commitLabel = __serverMode ? 'Commit Changes' : 'Export Tokens';
+commitBtn.textContent = commitLabel;
+commitBtn.onclick = async () => {
+  commitBtn.textContent = __serverMode ? 'Committing...' : 'Exporting...';
+  commitBtn.disabled = true;
+  try {
+    if (__serverMode) {
+      const res = await fetch('/commit', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(tokens, null, 2)
+      });
+      const data = await res.json();
+      if (!data.ok) throw new Error(data.error);
+      commitBtn.textContent = 'Committed!';
+    } else {
+      // Standalone: download tokens as JSON file
+      const blob = new Blob([JSON.stringify(tokens, null, 2)], { type: 'application/json' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = 'tokens.json';
+      a.click();
+      URL.revokeObjectURL(url);
+      commitBtn.textContent = 'Downloaded!';
+    }
+    commitBtn.classList.add('success');
+    setTimeout(() => {
+      commitBtn.textContent = commitLabel;
+      commitBtn.classList.remove('success');
+      commitBtn.disabled = false;
+    }, 2000);
+  } catch (e) {
+    commitBtn.textContent = 'Error: ' + e.message;
+    commitBtn.disabled = false;
+    setTimeout(() => { commitBtn.textContent = commitLabel; }, 3000);
+  }
+};
+panel.appendChild(commitBtn);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluedither",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A bold, dithered-shader hero theme for Claude Code — skill + fine-tuner",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "theme/",
     "cli/",
     "lib/",
+    "fine-tuner/",
     "skill.md",
     "bluedither.config.json"
   ],