living-docs-kit 0.1.0

package/skills/docs-init/assets/site-template/engine/palette.mjs

@@ -0,0 +1,149 @@
+// Extracts raw design material (colours, fonts) that the agent then maps onto theme tokens.
+//
+//   node engine/palette.mjs --url https://example.com        CSS variables, colours by usage, fonts
+//   node engine/palette.mjs --image ./palette.png            dominant colours (path or http(s) URL)
+//   node engine/palette.mjs --image shot.png --colors 10
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { rgbToHex, luminance, contrast } from './lib.mjs';
+
+const args = process.argv.slice(2);
+const opt = (n) => { const i = args.indexOf('--' + n); return i > -1 ? args[i + 1] : undefined; };
+const UA = { 'User-Agent': 'Mozilla/5.0 (living-docs palette extractor)' };
+
+function toHex(v) {
+  v = v.trim().toLowerCase();
+  let m;
+  if ((m = v.match(/^#([0-9a-f]{3,8})$/))) {
+    let h = m[1];
+    if (h.length === 3 || h.length === 4) h = h.slice(0, 3).split('').map((c) => c + c).join('');
+    if (h.length === 8) { if (parseInt(h.slice(6), 16) < 128) return null; h = h.slice(0, 6); }
+    return h.length === 6 ? '#' + h : null;
+  }
+  if ((m = v.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/))) {
+    if (m[4] !== undefined && parseFloat(m[4]) < (m[4].endsWith('%') ? 50 : 0.5)) return null;
+    return rgbToHex([+m[1], +m[2], +m[3]]);
+  }
+  if ((m = v.match(/^hsla?\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/))) {
+    const h = +m[1] / 360, s = +m[2] / 100, l = +m[3] / 100;
+    const f = (n) => { const k = (n + h * 12) % 12; const a = s * Math.min(l, 1 - l); return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1)); };
+    return rgbToHex([f(0) * 255, f(8) * 255, f(4) * 255]);
+  }
+  const named = { white: '#ffffff', black: '#000000' };
+  return named[v] || null;
+}
+
+async function get(url) {
+  const r = await fetch(url, { headers: UA, redirect: 'follow' });
+  if (!r.ok) throw new Error(`${url} → HTTP ${r.status}`);
+  return r.text();
+}
+
+async function fromUrl(url) {
+  const html = await get(url);
+  const css = [];
+  for (const m of html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) css.push(m[1]);
+  const links = [...html.matchAll(/<link[^>]+>/gi)].map((m) => m[0]).filter((l) => /rel=["']?stylesheet/i.test(l));
+  const hrefs = links.map((l) => (l.match(/href=["']([^"']+)["']/i) || [])[1]).filter(Boolean);
+  const fontLinks = hrefs.filter((h) => /fonts\.googleapis\.com|fonts\.bunny\.net|use\.typekit\.net|fonts\.adobe\.com/.test(h));
+  for (const h of hrefs.filter((x) => !fontLinks.includes(x)).slice(0, 10)) {
+    try { css.push(await get(new URL(h, url).href)); } catch (e) { console.error('! could not read ' + h + ': ' + e.message); }
+  }
+  for (const m of html.matchAll(/style=["']([^"']+)["']/gi)) css.push(`x{${m[1]}}`);
+  const all = css.join('\n');
+
+  const vars = {};
+  for (const m of all.matchAll(/(--[\w-]+)\s*:\s*([^;}{]+)/g)) {
+    const hex = toHex(m[2]);
+    if (hex && !vars[m[1]]) vars[m[1]] = hex;
+  }
+  const usage = {};
+  const bump = (hex, role) => { if (!hex) return; usage[hex] ??= { hex, total: 0, background: 0, text: 0, border: 0, other: 0 }; usage[hex].total++; usage[hex][role]++; };
+  for (const m of all.matchAll(/([\w-]+)\s*:\s*([^;}{]+)/g)) {
+    const prop = m[1].toLowerCase();
+    if (prop.startsWith('--')) continue;
+    const role = /background/.test(prop) ? 'background' : prop === 'color' ? 'text' : /border|outline/.test(prop) ? 'border' : /fill|stroke|shadow|gradient/.test(prop) ? 'other' : null;
+    if (!role) continue;
+    for (const c of m[2].matchAll(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)|\bwhite\b|\bblack\b/g)) bump(toHex(c[0]), role);
+    const v = m[2].match(/var\((--[\w-]+)/);
+    if (v && vars[v[1]]) bump(vars[v[1]], role);
+  }
+  const fonts = {};
+  for (const m of all.matchAll(/font-family\s*:\s*([^;}{]+)/gi)) {
+    const f = m[1].trim().replace(/\s*!important/, '');
+    if (!f.startsWith('var(') && !/inherit|initial/.test(f)) fonts[f] = (fonts[f] || 0) + 1;
+  }
+  const fontVars = {};
+  for (const m of all.matchAll(/(--[\w-]*font[\w-]*)\s*:\s*([^;}{]+)/gi)) fontVars[m[1]] ||= m[2].trim();
+  const colors = Object.values(usage).sort((a, b) => b.total - a.total).slice(0, 24).map((c) => ({ ...c, luminance: +luminance(c.hex).toFixed(3) }));
+  return {
+    source: url,
+    themeColorMeta: (html.match(/<meta[^>]+name=["']theme-color["'][^>]+content=["']([^"']+)/i) || [])[1] || null,
+    hasDarkModeCss: /prefers-color-scheme:\s*dark/.test(all),
+    cssVariables: vars,
+    colorsByUsage: colors,
+    fonts: Object.entries(fonts).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([family, count]) => ({ family, count })),
+    fontVariables: fontVars,
+    fontStylesheets: fontLinks,
+    note: colors.length < 3 ? 'Very few colours found (site rendered by JavaScript?). Take a screenshot and run --image on it.' : undefined,
+  };
+}
+
+async function fromImage(src, k) {
+  let Jimp;
+  try { ({ Jimp } = await import('jimp')); } catch { throw new Error('package "jimp" is missing: run npm install in this folder'); }
+  let file = src;
+  if (/^https?:\/\//.test(src)) {
+    const r = await fetch(src, { headers: UA });
+    if (!r.ok) throw new Error(`${src} → HTTP ${r.status}`);
+    file = path.join(os.tmpdir(), 'ld-palette-' + Date.now() + path.extname(new URL(src).pathname || '.png'));
+    fs.writeFileSync(file, Buffer.from(await r.arrayBuffer()));
+  }
+  const img = await Jimp.read(file);
+  img.resize({ w: 160 });
+  const { data, width, height } = img.bitmap;
+  const px = [];
+  for (let i = 0; i < width * height; i++) {
+    if (data[i * 4 + 3] < 128) continue;
+    px.push([data[i * 4], data[i * 4 + 1], data[i * 4 + 2]]);
+  }
+  // k-means++ in RGB
+  const dist = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+  let centers = [px[Math.floor(px.length / 2)]];
+  while (centers.length < k) {
+    const d = px.map((p) => Math.min(...centers.map((c) => dist(p, c))));
+    const sum = d.reduce((a, b) => a + b, 0);
+    let r = Math.random() * sum;
+    let idx = 0;
+    while ((r -= d[idx]) > 0 && idx < d.length - 1) idx++;
+    centers.push(px[idx]);
+  }
+  let assign = new Array(px.length).fill(0);
+  for (let it = 0; it < 12; it++) {
+    assign = px.map((p) => { let best = 0, bd = Infinity; centers.forEach((c, j) => { const dd = dist(p, c); if (dd < bd) { bd = dd; best = j; } }); return best; });
+    centers = centers.map((c, j) => {
+      const mine = px.filter((_, i) => assign[i] === j);
+      if (!mine.length) return c;
+      return [0, 1, 2].map((ch) => mine.reduce((a, p) => a + p[ch], 0) / mine.length);
+    });
+  }
+  const counts = centers.map((_, j) => assign.filter((a) => a === j).length);
+  const out = centers
+    .map((c, j) => ({ hex: rgbToHex(c), share: +(counts[j] / px.length * 100).toFixed(1) }))
+    .filter((c) => c.share > 0.5)
+    .sort((a, b) => b.share - a.share)
+    .map((c) => ({ ...c, luminance: +luminance(c.hex).toFixed(3), contrastOnWhite: +contrast(c.hex, '#ffffff').toFixed(2), contrastOnBlack: +contrast(c.hex, '#000000').toFixed(2) }));
+  return { source: src, dominantColors: out, note: 'Colours are ordered by area. The lightest/darkest are candidates for background/text; saturated ones for accent and links.' };
+}
+
+try {
+  const url = opt('url');
+  const image = opt('image');
+  if (!url && !image) throw new Error('usage: --url <site> | --image <path or URL> [--colors 8]');
+  const result = url ? await fromUrl(url) : await fromImage(image, Math.max(3, Math.min(16, +(opt('colors') || 8))));
+  console.log(JSON.stringify(result, null, 2));
+} catch (e) {
+  console.error('✗ ' + e.message);
+  process.exit(1);
+}

package/skills/docs-init/assets/site-template/engine/theme-tool.mjs

@@ -0,0 +1,201 @@
+// Theme management. Themes live in themes/<id>.json; the default is "defaultTheme" in docs.config.json.
+//
+//   node engine/theme-tool.mjs list
+//   node engine/theme-tool.mjs show <id>
+//   node engine/theme-tool.mjs validate [id]              schema + WCAG contrast (exit 1 on errors)
+//   node engine/theme-tool.mjs new <id> --from <base> [--label "Nume"]
+//   node engine/theme-tool.mjs set <id> <path> <value>    e.g. set fjord typography.baseSize 18
+//   node engine/theme-tool.mjs fix <id>                  adjust failing colours (lightness only) until contrast passes
+//   node engine/theme-tool.mjs set-default <id>
+//   node engine/theme-tool.mjs remove <id>
+import fs from 'node:fs';
+import path from 'node:path';
+import { THEMES_DIR, loadConfig, saveConfig, loadThemes, resolveTheme, contrast, hexToRgb, mix, REQUIRED_COLORS, OPTIONAL_COLORS } from './lib.mjs';
+
+const [cmd, ...args] = process.argv.slice(2);
+const opt = (name) => { const i = args.indexOf('--' + name); return i > -1 ? args[i + 1] : undefined; };
+const fileOf = (id) => path.join(THEMES_DIR, id + '.json');
+const readTheme = (id) => {
+  if (!fs.existsSync(fileOf(id))) throw new Error(`theme "${id}" does not exist. Themes: ${loadThemes().map((t) => t.id).join(', ')}`);
+  return JSON.parse(fs.readFileSync(fileOf(id), 'utf8'));
+};
+const writeTheme = (t) => fs.writeFileSync(fileOf(t.id), JSON.stringify(t, null, 2) + '\n');
+
+// [foreground, background, minimum ratio, what]
+const PAIRS = [
+  ['text', 'bg', 4.5, 'body text on background'],
+  ['text', 'surface', 4.5, 'text on surfaces (tables, boxes)'],
+  ['textMuted', 'bg', 4.5, 'secondary text on background'],
+  ['textMuted', 'surface', 3.0, 'secondary text on surfaces'],
+  ['heading', 'bg', 4.5, 'headings on background'],
+  ['link', 'bg', 4.5, 'links on background'],
+  ['link', 'surface', 4.5, 'links on surfaces'],
+  ['accentText', 'accent', 4.5, 'text on the accent colour'],
+  ['codeText', 'codeBg', 4.5, 'code on code background'],
+  ['text', 'highlight', 4.5, 'text on highlight (search, current page)'],
+  ['warning', 'bg', 3.0, 'the "possibly outdated" badge'],
+  ['success', 'bg', 3.0, 'the "verified" badge'],
+  ['danger', 'bg', 3.0, 'warnings'],
+  ['accent', 'bg', 3.0, 'accent visible on background (bars, active borders)'],
+];
+
+function validate(raw) {
+  const errors = [];
+  const warnings = [];
+  if (!/^[a-z0-9-]+$/.test(raw.id || '')) errors.push('id must contain only lowercase letters, digits and hyphens');
+  if (!raw.label) warnings.push('missing "label" (the name shown in the theme picker)');
+  if (!['light', 'dark'].includes(raw.mode)) errors.push('"mode" must be "light" or "dark"');
+  const c = raw.colors || {};
+  for (const k of REQUIRED_COLORS) if (!c[k]) errors.push(`missing required colour colors.${k}`);
+  for (const [k, v] of Object.entries(c)) {
+    if (!REQUIRED_COLORS.includes(k) && !OPTIONAL_COLORS.includes(k)) warnings.push(`colors.${k} is not used by the site`);
+    if (!hexToRgb(v)) errors.push(`colors.${k} = "${v}" is not hex (#rrggbb)`);
+  }
+  for (const [k, v] of Object.entries(raw.diagram || {})) if (!hexToRgb(v)) errors.push(`diagram.${k} = "${v}" is not hex`);
+  if (errors.length) return { errors, warnings, ratios: [] };
+  const t = resolveTheme(raw);
+  const ratios = PAIRS.map(([fg, bg, min, what]) => {
+    const r = contrast(t.colors[fg], t.colors[bg]);
+    const ok = r >= min;
+    (ok ? [] : min >= 4.5 ? errors : warnings).push(`contrast ${fg}/${bg} = ${r.toFixed(2)} < ${min} (${what})`);
+    return { pair: `${fg}/${bg}`, ratio: +r.toFixed(2), min, ok };
+  });
+  const dNode = contrast(t.diagram.nodeText, t.diagram.nodeBg);
+  if (dNode < 4.5) errors.push(`contrast diagram.nodeText/nodeBg = ${dNode.toFixed(2)} < 4.5 (text inside diagram nodes)`);
+  const bs = Number(t.typography.baseSize);
+  if (!(bs >= 12 && bs <= 28)) errors.push(`typography.baseSize = ${t.typography.baseSize}; use a pixel number between 12 and 28`);
+  const lh = Number(t.typography.lineHeight);
+  if (!(lh >= 1.2 && lh <= 2.2)) warnings.push(`typography.lineHeight = ${lh}; 1.5–1.8 is comfortable for reading`);
+  if (t.fonts.googleFontsUrl && !/^https:\/\/fonts\.googleapis\.com\/css2\?/.test(t.fonts.googleFontsUrl)) warnings.push('fonts.googleFontsUrl does not look like a Google Fonts css2 URL');
+  for (const k of ['body', 'heading', 'mono']) {
+    if (t.fonts[k] && !/(sans-serif|serif|monospace|system-ui)\s*$/.test(t.fonts[k])) warnings.push(`fonts.${k} does not end with a generic family (sans-serif/serif/monospace)`);
+  }
+  if (t.extraCss && !t.extraCss.includes(`[data-theme="${t.id}"]`)) warnings.push(`extraCss should be scoped with :root[data-theme="${t.id}"] so it does not affect other themes`);
+  return { errors, warnings, ratios };
+}
+
+function setPath(obj, p, value) {
+  const keys = p.split('.');
+  let o = obj;
+  for (const k of keys.slice(0, -1)) o = o[k] ??= {};
+  let v = value;
+  if (/^-?\d+(\.\d+)?$/.test(value)) v = Number(value);
+  else if (value === 'true' || value === 'false') v = value === 'true';
+  else if (value === 'null') v = undefined;
+  if (v === undefined) delete o[keys.at(-1)];
+  else o[keys.at(-1)] = v;
+}
+
+try {
+  const cfg = loadConfig();
+  switch (cmd) {
+    case 'list': {
+      for (const t of loadThemes()) console.log(`${t.id === cfg.defaultTheme ? '★' : ' '} ${t.id.padEnd(22)} ${String(t.label || '').padEnd(26)} ${t.mode}  ${t.source ? '← ' + t.source : ''}`);
+      console.log('\n★ = default (docs.config.json → defaultTheme)');
+      break;
+    }
+    case 'show':
+      console.log(JSON.stringify(resolveTheme(readTheme(args[0])), null, 2));
+      break;
+    case 'validate': {
+      const list = args[0] ? [readTheme(args[0])] : loadThemes();
+      let bad = 0;
+      for (const t of list) {
+        const r = validate(t);
+        console.log(`\n${r.errors.length ? '✗' : '✓'} ${t.id}`);
+        for (const e of r.errors) console.log('  ✗ ' + e);
+        for (const w of r.warnings) console.log('  ! ' + w);
+        if (!r.errors.length) console.log('  contrast: ' + r.ratios.map((x) => `${x.pair} ${x.ratio}`).join(' · '));
+        if (r.errors.length) bad++;
+      }
+      if (!list.some((t) => t.id === cfg.defaultTheme)) { console.log(`\n✗ defaultTheme "${cfg.defaultTheme}" does not exist`); bad++; }
+      process.exit(bad ? 1 : 0);
+    }
+    case 'new': {
+      const [id] = args;
+      const base = opt('from');
+      if (!id || !base) throw new Error('usage: new <id> --from <existing-theme> [--label "Name"]');
+      if (fs.existsSync(fileOf(id))) throw new Error(`tema "${id}" already exists`);
+      const t = { ...readTheme(base), id, label: opt('label') || id, source: `derived from ${base}` };
+      delete t._file;
+      writeTheme(t);
+      console.log(`✓ created themes/${id}.json from ${base}. Edit the values, then run: validate ${id}`);
+      break;
+    }
+    case 'set': {
+      const [id, p, value] = args;
+      if (!id || !p || value === undefined) throw new Error('usage: set <id> <path.to.property> <value>');
+      const t = readTheme(id);
+      setPath(t, p, value);
+      const r = validate(t);
+      if (r.errors.length) throw new Error('this change would make the theme invalid:\n  ' + r.errors.join('\n  '));
+      writeTheme(t);
+      console.log(`✓ ${id}.${p} = ${value}`);
+      break;
+    }
+    case 'fix': {
+      const [id] = args;
+      const t = readTheme(id);
+      t.colors ||= {};
+      const dark = t.mode === 'dark';
+      const changes = [];
+      for (let round = 0; round < 3; round++) {
+        const r = resolveTheme(t);
+        for (const [fg, bg, min] of PAIRS) {
+          let ratio = contrast(r.colors[fg], r.colors[bg]);
+          if (ratio >= min) continue;
+          if (fg === 'accentText') {
+            // text on accent: pick white or near-black; if neither passes, darken/lighten the accent itself
+            const best = contrast('#ffffff', r.colors.accent) >= contrast('#111111', r.colors.accent) ? '#ffffff' : '#111111';
+            let acc = r.colors.accent;
+            const accStart = acc;
+            for (let i = 1; i <= 50 && contrast(best, acc) < min + 0.15; i++) acc = mix(accStart, best === '#ffffff' ? '#000000' : '#ffffff', i * 0.02);
+            if (acc !== accStart) { t.colors.accent = acc; r.colors.accent = acc; changes.push(`accent: ${accStart} → ${acc}`); }
+            changes.push(`accentText: ${r.colors.accentText} → ${best} (${contrast(best, acc).toFixed(2)})`);
+            t.colors.accentText = best;
+            r.colors.accentText = best;
+            continue;
+          }
+          // move the foreground away from the background; for highlight, move the background toward the page bg
+          const target = fg === 'text' && bg === 'highlight' ? 'highlight' : fg;
+          const toward = target === 'highlight' ? r.colors.bg : (dark ? '#ffffff' : '#000000');
+          let value = r.colors[target];
+          const start = value;
+          for (let i = 1; i <= 50 && ratio < min + 0.15; i++) {
+            value = mix(start, toward, i * 0.02);
+            ratio = target === 'highlight' ? contrast(r.colors[fg], value) : contrast(value, r.colors[bg]);
+          }
+          t.colors[target] = value;
+          r.colors[target] = value;
+          changes.push(`${target}: ${start} → ${value} (${fg}/${bg} ${ratio.toFixed(2)})`);
+        }
+      }
+      writeTheme(t);
+      console.log(changes.length ? '✓ adjusted:\n  ' + changes.join('\n  ') : '✓ nothing to adjust');
+      const v = validate(t);
+      if (v.errors.length) { console.log('✗ problems remain:\n  ' + v.errors.join('\n  ')); process.exit(1); }
+      break;
+    }
+    case 'set-default': {
+      const [id] = args;
+      readTheme(id);
+      saveConfig((c) => { c.defaultTheme = id; });
+      console.log(`✓ default theme is now "${id}"`);
+      break;
+    }
+    case 'remove': {
+      const [id] = args;
+      if (id === cfg.defaultTheme) throw new Error('cannot remove the default theme; choose another one with set-default first');
+      readTheme(id);
+      fs.unlinkSync(fileOf(id));
+      console.log(`✓ removed themes/${id}.json`);
+      break;
+    }
+    default:
+      console.log('commands: list | show <id> | validate [id] | fix <id> | new <id> --from <base> | set <id> <path> <value> | set-default <id> | remove <id>');
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (e) {
+  console.error('✗ ' + e.message);
+  process.exit(1);
+}