designlang 12.11.0 → 12.14.0

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## [12.14.0] — 2026-05-17
+
+**Real downloadable PDFs everywhere + a one-shot agent prompt every AI can paste.**
+
+Two big shipping themes: every extraction now produces a real
+print-ready PDF on demand (not just an HTML brand book), and every
+extraction writes a self-contained agent prompt that drops into any
+LLM — Claude, GPT, Gemini, Cursor, Windsurf, v0.
+
+- **`--pdf` flag in the main `extract` command** — renders the
+  brand-book HTML to a 13-chapter PDF (chapter bookmarks, running
+  footer, embedded fonts, selectable text). Verified ~440KB per brand.
+
+  ```bash
+  npx designlang stripe.com --pdf --paper letter --landscape
+  ```
+
+- **One-shot agent prompt (`<host>-AGENT.md`)** — a single file you
+  paste into any AI agent. Includes colour roles, type, spacing, radii,
+  motion, voice (tone / pronoun / CTA verbs / real headlines),
+  component anatomy, WCAG score, 7 build rules ("never invent a hex",
+  "snap spacing to scale", etc.), and a manifest of every other
+  artefact designlang produced for context.
+
+- **Server-side PDF endpoint** — `GET /api/pdf/<hash>` renders the
+  cached extraction's brand book to PDF via the same Browserless /
+  Chromium path the `/api/extract` route uses. Cached for an hour on
+  CDN edge with 24h stale-while-revalidate.
+
+- **Website UI** — `/gallery/[slug]` hero CTA is now
+  `Download brand book PDF`; new full-width "Agent prompt" section
+  with a `Copy NN.NKB prompt` button. Post-extraction share row gains
+  `Download brand PDF` and `Copy agent prompt`.
+
+- **Pre-rendered static assets** — all 8 featured brand books in
+  `website/public/gallery/<slug>/` now include the new `.brand.pdf`,
+  `-AGENT.md`, `-reset.css`, `-gradients.css/.json` files so the
+  static gallery has working downloads from minute one.
+
+## [12.13.0] — 2026-05-16
+
+**Six new emitters + a public programmatic API.**
+
+Every extraction now writes five additional first-class files, and downstream
+tools can wire into the engine through a stable surface.
+
+- **Tailwind v4 (`<host>-tailwind-v4.css`)** — CSS-first `@theme {}` block
+  with the full HSL colour scales, neutrals, type, spacing, radii, shadows
+  and motion. Parallel to the v3 `tailwind.config.js`, so v4 users get a
+  drop-in file.
+- **TypeScript token types (`<host>-tokens.d.ts`)** — strict literal
+  unions for `ColorRole`, `ColorHex`, `FontFamilyToken`, `FontWeightToken`,
+  `SpacingToken`, `RadiusToken`, `DurationToken`, `EasingToken` plus a
+  `DesignTokens` roll-up interface. Component props typed against the real
+  extracted brand, not generic `string`.
+- **Brand-aware CSS reset (`<host>-reset.css`)** — modern reset wired to
+  the extracted background / foreground / links / accent / selection.
+  Honours `prefers-reduced-motion`.
+- **Gradients (`<host>-gradients.css` + `.json`)** — surfaces every
+  extracted gradient as `:root --grad-N` vars plus `.grad-N` background
+  and `.grad-text-N` background-clip utility classes.
+- **`--palette <n>` flag** — compresses noisy 60–200-colour extractions
+  to N perceptually-distinct tokens via weighted LAB-space k-means.
+  Returns cluster medoids — never invents a hex that wasn't on the page.
+  Verified: stripe.com 29 → 8.
+
+**Public programmatic API at `designlang/api`.**
+
+A frozen surface other packages, scripts and AI agents can import without
+reaching into internal modules.
+
+```js
+import { extract, render, renderAll, RENDERERS } from 'designlang/api';
+
+const design = await extract('https://stripe.com', { palette: 8 });
+const tailwind = render('tailwind-v4', design);
+const files = renderAll(design); // { 'stripe-com-tokens.d.ts': '...', ... }
+```
+
+`package.json` now exposes:
+- `designlang`         — main entry
+- `designlang/api`     — the new public API (19 renderer ids)
+- `designlang/mcp`     — the existing MCP server entry
+
+## [12.12.0] — 2026-05-15
+
+**Website launch — designlang.app, fully rebuilt.**
+
+The marketing/demo site at [designlang.app](https://designlang.app) has been
+rewritten from the ground up. Highlights:
+
+- **Hero with WebGL Grainient background** (red/black, ogl-powered, GPU-paused
+  when offscreen) and a terminal output card showing real CLI execution.
+- **Live demo showcase** (`See it work.`) — paste any URL into a glass
+  stage, suggestion chips for stripe.com / linear.app / vercel.com /
+  notion.so / figma.com, click-to-copy `npx designlang stripe.com` in the
+  hero.
+- **Real gallery** — eight pre-rendered brand books for stripe.com,
+  linear.app, vercel.com, notion.so, figma.com, apple.com, arc.net and
+  spotify.com. Each card is the actual extraction the CLI produced; the
+  cover gradient uses the extracted primary + accent tokens.
+- **Floating glass nav** with a custom logo, segmented pill links, real
+  GitHub star count fetched from the API (server-rendered, 30 min revalidate),
+  and an `npm i designlang` CTA matching the hero gradient.
+- **Auto-scrolling reddit testimonial marquee** (3 cols, motion/react)
+  with the real comments from the r/ClaudeAI launch thread.
+- **Polished footer** with brand block, 4 link columns, decorative giant
+  outlined wordmark, version + author + license strip.
+- **Aggressive SEO** — keyword-dense title and description, ~75-keyword
+  list; JSON-LD graph with `SoftwareApplication`, `Organization`,
+  `WebSite + SearchAction`, `BreadcrumbList`, `FAQPage`, `HowTo`;
+  `aggregateRating` from real GitHub stars; visible FAQ section + ~250-word
+  about block; sitemap includes the 8 gallery brand books; rewritten
+  `llms.txt` for AI-search citability (allows GPTBot, ClaudeBot,
+  PerplexityBot, Google-Extended, Applebot-Extended, etc.).
+
+**Web extractor parity with the CLI.**
+
+- `/api/extract`'s file output now includes the brand-book HTML
+  (`<host>.brand.html`) for every run.
+- `formatBrandBook` is shared between the CLI and the website's
+  `lib/build-files.js`.
+
+**Other**
+
+- Fixed the README so the logo and "designlang in action" image render
+  on the npm package page (relative paths swapped for raw GitHub URLs).
+- Removed all decorative status dots from the website per design feedback;
+  status indicators are now typed text chips.
+
 ## [12.11.0] — 2026-05-15
 
 **`brand --pdf` ships native PDF brand guides.**

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="website/public/logo-specimen.svg" alt="designlang — reads a website the way a developer reads a stylesheet" width="900">
+  <img src="https://raw.githubusercontent.com/Manavarya09/design-extract/main/website/public/logo-specimen.svg" alt="designlang — reads a website the way a developer reads a stylesheet" width="900">
 </p>
 
 <p align="center">
@@ -13,7 +13,7 @@
 ---
 
 <p align="center">
-  <img src="designlang.png" alt="designlang in action" width="100%">
+  <img src="https://raw.githubusercontent.com/Manavarya09/design-extract/main/designlang.png" alt="designlang in action — extracts DTCG tokens, Tailwind config, Figma variables, brand book PDF" width="100%">
 </p>
 
 [![designlang on npm](https://pkgfolio.vercel.app/embed/pkg/designlang?v=2)](https://www.npmjs.com/package/designlang)

package/bin/design-extract.js

@@ -22,6 +22,11 @@ import { formatMarkdown } from '../src/formatters/markdown.js';
 import { formatTokens } from '../src/formatters/tokens.js';
 import { formatDtcgTokens } from '../src/formatters/dtcg-tokens.js';
 import { formatTailwind } from '../src/formatters/tailwind.js';
+import { formatTailwindV4 } from '../src/formatters/tailwind-v4.js';
+import { formatTsDefs } from '../src/formatters/ts-defs.js';
+import { formatCssReset } from '../src/formatters/css-reset.js';
+import { formatGradientsCss, formatGradientsJson } from '../src/formatters/gradients.js';
+import { formatAgentPrompt } from '../src/formatters/agent-prompt.js';
 import { formatCssVars } from '../src/formatters/css-vars.js';
 import { formatPreview } from '../src/formatters/preview.js';
 import { formatFigma } from '../src/formatters/figma.js';
@@ -108,6 +113,10 @@ program
   .option('--no-design-md', 'skip writing the agent-native DESIGN.md (single-file, 8-section, YAML front matter)')
   .option('--responsive-shots', 'capture full-page PNGs at 4 breakpoints × (light,dark)')
   .option('--perf', 'measure Core Web Vitals + bundle profile (LCP/CLS/INP, JS/CSS/font/img bytes, third-party count)')
+  .option('--palette <n>', 'compress the extracted palette to N perceptually distinct colours via LAB-space k-means (default: emit every unique colour)', parseInt)
+  .option('--pdf', 'also render a print-ready brand-book PDF (chapter bookmarks, running footer, embedded tokens)')
+  .option('--paper <size>', 'PDF paper size when --pdf is set: a4 | letter | tabloid', 'a4')
+  .option('--landscape', 'PDF landscape orientation when --pdf is set')
   .option('--json', 'output raw JSON to stdout (for CI/CD)')
   .option('--json-pretty', 'output formatted JSON to stdout')
   .option('--no-history', 'skip saving to history')
@@ -307,6 +316,21 @@ program
       // Drop the internal raw stash before JSON/output serialization.
       delete design._raw;
 
+      // Optional palette compression — perceptual LAB k-means down to N colours.
+      const paletteTarget = parseInt(opts.palette, 10);
+      if (paletteTarget > 0 && Array.isArray(design.colors?.all)) {
+        try {
+          const { compressPalette } = await import('../src/utils/palette-compress.js');
+          const before = design.colors.all.length;
+          const compressed = compressPalette(design.colors.all, paletteTarget);
+          design.colors.all = compressed;
+          design.colors._compressed = { from: before, to: compressed.length, target: paletteTarget };
+          spinner.text = `Compressed palette: ${before} → ${compressed.length} colours`;
+        } catch (e) {
+          console.warn(`(palette compress skipped: ${e.message})`);
+        }
+      }
+
       // JSON mode: output and exit
       if (jsonMode) {
         const output = opts.jsonPretty ? JSON.stringify(design, null, 2) : JSON.stringify(design);
@@ -320,7 +344,13 @@ program
       const files = [
         { name: `${prefix}-design-language.md`, content: formatMarkdown(design), label: 'Markdown (AI-optimized)' },
         { name: `${prefix}-design-tokens.json`, content: merged.tokensLegacy ? formatTokens(design) : JSON.stringify(formatDtcgTokens(design), null, 2), label: merged.tokensLegacy ? 'Design Tokens (legacy)' : 'Design Tokens (DTCG v1)' },
-        { name: `${prefix}-tailwind.config.js`, content: formatTailwind(design), label: 'Tailwind Config' },
+        { name: `${prefix}-tailwind.config.js`, content: formatTailwind(design), label: 'Tailwind Config (v3)' },
+        { name: `${prefix}-tailwind-v4.css`,    content: formatTailwindV4(design), label: 'Tailwind v4 @theme (CSS-first)' },
+        { name: `${prefix}-tokens.d.ts`,        content: formatTsDefs(design),     label: 'TypeScript token types' },
+        { name: `${prefix}-reset.css`,          content: formatCssReset(design),   label: 'Brand-aware CSS reset' },
+        { name: `${prefix}-gradients.css`,      content: formatGradientsCss(design), label: 'Extracted gradients (utility classes)' },
+        { name: `${prefix}-gradients.json`,     content: formatGradientsJson(design), label: 'Extracted gradients (structured)' },
+        { name: `${prefix}-AGENT.md`,           content: formatAgentPrompt(design), label: 'Agent system prompt (paste into Claude/GPT/Cursor)' },
         { name: `${prefix}-variables.css`, content: formatCssVars(design), label: 'CSS Variables' },
         { name: `${prefix}-preview.html`, content: formatPreview(design), label: 'Visual Preview' },
         { name: `${prefix}-figma-variables.json`, content: formatFigma(design), label: 'Figma Variables' },
@@ -423,6 +453,32 @@ program
         writeFileSync(join(outDir, file.name), file.content, 'utf-8');
       }
 
+      // Brand book — always emit the HTML (cheap, ~100KB). Optionally
+      // render it to PDF behind --pdf (needs Playwright, ~3–5s).
+      try {
+        const brandHtml = formatBrandBook(design, { version: PKG_VERSION });
+        const brandHtmlPath = join(outDir, `${prefix}.brand.html`);
+        writeFileSync(brandHtmlPath, brandHtml, 'utf-8');
+        files.push({ name: `${prefix}.brand.html`, label: 'Brand book (HTML)' });
+
+        if (opts.pdf) {
+          spinner.text = 'Rendering brand book PDF...';
+          const pdfPath = join(outDir, `${prefix}.brand.pdf`);
+          await htmlToPdf(brandHtml, {
+            paper: opts.paper || 'a4',
+            landscape: !!opts.landscape,
+            outPath: pdfPath,
+            metadata: {
+              title: `${new URL(design?.meta?.url || `https://${prefix}`).hostname} brand guidelines`,
+              subject: `${prefix} brand guidelines`,
+            },
+          });
+          files.push({ name: `${prefix}.brand.pdf`, label: 'Brand book (PDF · print-ready)' });
+        }
+      } catch (e) {
+        if (!merged.quiet) console.warn(`(brand book skipped: ${e.message})`);
+      }
+
       // Multi-platform emission (v7.0). web is already emitted above.
       const platforms = merged.platforms || ['web'];
       const dtcgTokens = formatDtcgTokens(design);

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "designlang",
-  "version": "12.11.0",
+  "version": "12.14.0",
   "description": "Extract the complete design language from any website and ship it — clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {
     "designlang": "./bin/design-extract.js"
   },
   "main": "src/index.js",
+  "exports": {
+    ".":       "./src/index.js",
+    "./api":   "./src/api.js",
+    "./mcp":   "./src/mcp/index.js",
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "postinstall": "npx playwright install chromium --with-deps 2>/dev/null || npx playwright install chromium",
     "start": "node bin/design-extract.js",

package/src/api.js

@@ -0,0 +1,171 @@
+// Public programmatic API for designlang.
+//
+// Stable surface other packages / scripts / agents can import. Anything
+// not re-exported here is internal and may change without notice.
+//
+// Example:
+//   import { extract, render, RENDERERS } from 'designlang/api';
+//   const design = await extract('https://stripe.com');
+//   const tailwind = render('tailwind', design);
+//   const dts = render('ts-defs', design);
+
+import { extractDesignLanguage } from './index.js';
+
+// Formatters
+import { formatMarkdown }        from './formatters/markdown.js';
+import { formatDesignMd }        from './formatters/design-md.js';
+import { formatTokens }          from './formatters/tokens.js';
+import { formatDtcgTokens }      from './formatters/dtcg-tokens.js';
+import { formatTailwind }        from './formatters/tailwind.js';
+import { formatTailwindV4 }      from './formatters/tailwind-v4.js';
+import { formatTsDefs }          from './formatters/ts-defs.js';
+import { formatCssVars }         from './formatters/css-vars.js';
+import { formatCssReset }        from './formatters/css-reset.js';
+import { formatPreview }         from './formatters/preview.js';
+import { formatFigma }           from './formatters/figma.js';
+import { formatReactTheme,
+         formatShadcnTheme }     from './formatters/theme.js';
+import { formatVueTheme }        from './formatters/vue-theme.js';
+import { formatSvelteTheme }     from './formatters/svelte-theme.js';
+import { formatIosSwiftUI }      from './formatters/ios-swiftui.js';
+import { formatAndroidCompose }  from './formatters/android-compose.js';
+import { formatFlutterDart }     from './formatters/flutter-dart.js';
+import { formatWordPress,
+         formatWordPressTheme }  from './formatters/wordpress.js';
+import { formatBrandBook }       from './formatters/brand-book.js';
+import { formatGradientsCss,
+         formatGradientsJson }   from './formatters/gradients.js';
+import { formatAgentRules }      from './formatters/agent-rules.js';
+
+// Utils
+import { compressPalette }       from './utils/palette-compress.js';
+import { diffDesigns,
+         formatDiffMarkdown }    from './diff.js';
+
+// ─── Stable surface ───────────────────────────────────────────────
+
+/**
+ * Run the full extraction pipeline against a URL. Returns the live
+ * `design` object — every downstream renderer takes this shape.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @returns {Promise<object>}
+ */
+export async function extract(url, opts = {}) {
+  const design = await extractDesignLanguage(url, opts);
+  delete design._raw; // never leak internals over the public API
+  if (opts.palette && opts.palette > 0 && Array.isArray(design?.colors?.all)) {
+    design.colors.all = compressPalette(design.colors.all, opts.palette);
+  }
+  return design;
+}
+
+/**
+ * Map of every available renderer id → renderer function. Each function
+ * takes a `design` object and returns a string (for text formats) or
+ * an object (for multi-file payloads).
+ */
+export const RENDERERS = Object.freeze({
+  // markdown
+  'design-md':           (d) => formatDesignMd(d),
+  'design-language-md':  (d) => formatMarkdown(d),
+
+  // tokens
+  'tokens':              (d) => formatTokens(d),
+  'dtcg':                (d) => JSON.stringify(formatDtcgTokens(d), null, 2),
+
+  // web emitters
+  'tailwind':            (d) => formatTailwind(d),
+  'tailwind-v4':         (d) => formatTailwindV4(d),
+  'css-vars':            (d) => formatCssVars(d),
+  'css-reset':           (d) => formatCssReset(d),
+  'ts-defs':             (d) => formatTsDefs(d),
+  'figma':               (d) => formatFigma(d),
+  'preview-html':        (d) => formatPreview(d),
+  'brand-book-html':     (d) => formatBrandBook(d),
+  'gradients-css':       (d) => formatGradientsCss(d),
+  'gradients-json':      (d) => formatGradientsJson(d),
+
+  // frameworks
+  'react-theme':         (d) => formatReactTheme(d),
+  'shadcn-theme':        (d) => formatShadcnTheme(d),
+  'vue-theme':           (d) => formatVueTheme(d),
+  'svelte-theme':        (d) => formatSvelteTheme(d),
+
+  // native
+  'ios-swiftui':         (d) => formatIosSwiftUI(formatDtcgTokens(d)),
+  'android-compose':     (d) => formatAndroidCompose(formatDtcgTokens(d)),
+  'flutter-dart':        (d) => formatFlutterDart(formatDtcgTokens(d)),
+
+  // WordPress
+  'wordpress':           (d) => formatWordPress(d),
+  'wordpress-theme':     (d) => formatWordPressTheme(formatDtcgTokens(d), d),
+
+  // Agent rules (returns a multi-file object)
+  'agent-rules':         (d) => formatAgentRules({ design: d, tokens: formatDtcgTokens(d), url: d?.meta?.url || '' }),
+});
+
+/**
+ * Render a single emitter by id.
+ *
+ * @param {keyof typeof RENDERERS} id
+ * @param {object} design
+ * @returns {string|object}
+ */
+export function render(id, design) {
+  const fn = RENDERERS[id];
+  if (!fn) {
+    throw new Error(`Unknown renderer "${id}". Known: ${Object.keys(RENDERERS).join(', ')}.`);
+  }
+  return fn(design);
+}
+
+/**
+ * Render every emitter and return a `{ filename: contents }` map.
+ *
+ * @param {object} design
+ * @param {object} [opts]
+ * @param {string} [opts.prefix] file-name prefix (default: derived from URL or 'design')
+ * @returns {Record<string, string>}
+ */
+export function renderAll(design, opts = {}) {
+  const prefix = opts.prefix || (design?.meta?.url ? new URL(design.meta.url).hostname.replace(/\./g, '-').replace(/^www-/, '') : 'design');
+  const out = {};
+  const ext = {
+    'design-md':          'DESIGN.md',
+    'design-language-md': 'design-language.md',
+    'tokens':             'tokens.legacy.json',
+    'dtcg':               'design-tokens.json',
+    'tailwind':           'tailwind.config.js',
+    'tailwind-v4':        'tailwind-v4.css',
+    'css-vars':           'variables.css',
+    'css-reset':          'reset.css',
+    'ts-defs':            'tokens.d.ts',
+    'figma':              'figma-variables.json',
+    'preview-html':       'preview.html',
+    'brand-book-html':    'brand.html',
+    'gradients-css':      'gradients.css',
+    'gradients-json':     'gradients.json',
+    'react-theme':        'theme.js',
+    'shadcn-theme':       'shadcn-theme.css',
+    'vue-theme':          'theme.vue.js',
+    'svelte-theme':       'theme.svelte.js',
+    'wordpress':          'wordpress.json',
+  };
+  for (const [id, suffix] of Object.entries(ext)) {
+    try {
+      const body = RENDERERS[id]?.(design);
+      if (typeof body === 'string' && body.length > 0) out[`${prefix}-${suffix}`] = body;
+    } catch { /* skip emitter on error */ }
+  }
+  return out;
+}
+
+// Re-exports for advanced consumers
+export {
+  extractDesignLanguage,
+  compressPalette,
+  diffDesigns,
+  formatDiffMarkdown,
+};

package/src/formatters/agent-prompt.js

@@ -0,0 +1,214 @@
+// One-shot agent prompt — `<host>-AGENT.md`.
+//
+// Drop the contents into Claude / GPT / Gemini / Cursor / Windsurf
+// and the agent will build any UI you ask for *in the extracted brand*.
+//
+// Distinct from the existing prompt-pack (which targets v0 / Lovable /
+// Cursor with tool-specific syntax). This file is one self-contained
+// system-prompt that works in any context window — every token, every
+// component anatomy slot, every brand voice rule, ready to paste.
+
+function hex(c) { return c?.hex || c || null; }
+function pickHex(role, design) { return hex(design?.colors?.[role]) || null; }
+
+function topN(arr, n) {
+  if (Array.isArray(arr)) return arr.slice(0, n);
+  if (arr && typeof arr === 'object') return Object.values(arr).slice(0, n);
+  return [];
+}
+
+function listColors(design) {
+  const out = [];
+  for (const role of ['primary', 'secondary', 'accent', 'background', 'foreground']) {
+    const v = pickHex(role, design);
+    if (v) out.push(`- ${role.padEnd(11)} ${v}`);
+  }
+  const neutrals = topN(design?.colors?.neutrals, 6).map((n) => hex(n)).filter(Boolean);
+  if (neutrals.length) out.push(`- neutrals    ${neutrals.join(' · ')}`);
+  return out.join('\n');
+}
+
+function listType(design) {
+  const fams = topN(design?.typography?.families, 4).map((f) => f?.name || f).filter(Boolean);
+  const weights = topN(design?.typography?.weights, 6).map((w) => w?.weight || w?.value || w).filter(Boolean);
+  const base = design?.typography?.base || 16;
+  return [
+    fams.length ? `- families   ${fams.join(' · ')}` : null,
+    weights.length ? `- weights    ${weights.join(' · ')}` : null,
+    `- base size  ${base}px`,
+  ].filter(Boolean).join('\n');
+}
+
+function listSpacing(design) {
+  const scale = topN(design?.spacing?.scale, 12).map((px) => `${px}px`);
+  if (!scale.length) return null;
+  return `- scale      ${scale.join(' · ')}`;
+}
+
+function listRadii(design) {
+  const radii = topN(design?.borders?.radii, 6).map((r) => `${typeof r === 'object' ? r.value : r}px`);
+  if (!radii.length) return null;
+  return `- scale      ${radii.join(' · ')}`;
+}
+
+function listMotion(design) {
+  const durs = topN(design?.motion?.durations, 4).map((d) => `${typeof d === 'object' ? (d.value || d.ms) : d}ms`);
+  const eas = topN(design?.motion?.easings, 4).map((e) => typeof e === 'object' ? e.value : e).filter(Boolean);
+  return [
+    durs.length ? `- durations  ${durs.join(' · ')}` : null,
+    eas.length  ? `- easings    ${eas.join(' · ')}` : null,
+  ].filter(Boolean).join('\n');
+}
+
+function listVoice(design) {
+  const v = design?.voice || {};
+  const ctas = topN(v.ctaVerbs, 6).map((c) => c?.value || c).filter(Boolean);
+  const headings = topN(v.headlines || v.headings, 3).map((h) => h?.text || h).filter(Boolean);
+  return [
+    v.tone     ? `- tone       ${v.tone}` : null,
+    v.pronoun  ? `- pronoun    ${v.pronoun}` : null,
+    v.headingStyle ? `- headings   ${v.headingStyle}` : null,
+    ctas.length    ? `- CTA verbs  ${ctas.join(' · ')}` : null,
+    headings.length ? `- real headlines:\n${headings.map(h => `  > "${String(h).slice(0, 120)}"`).join('\n')}` : null,
+  ].filter(Boolean).join('\n');
+}
+
+function listAnatomy(design) {
+  const list = design?.componentAnatomy || design?.componentClusters || [];
+  if (!Array.isArray(list) || list.length === 0) return null;
+  return topN(list, 8).map((c) => {
+    const kind = String(c?.kind || c?.name || 'component');
+    const variants = topN(c?.variants, 4).map(String).join(' · ') || '—';
+    const slots    = topN(c?.slots,    4).map(String).join(' · ') || '—';
+    return `- ${kind.padEnd(10)} variants: ${variants}  ·  slots: ${slots}`;
+  }).join('\n');
+}
+
+function listA11y(design) {
+  const a = design?.accessibility || {};
+  const score = a.score ?? null;
+  const fails = a.failCount ?? (a.remediation?.length ?? 0);
+  return `- WCAG score ${score == null ? '—' : `${score}%`} · failing pairs: ${fails}`;
+}
+
+export function formatAgentPrompt(design) {
+  const host = design?.meta?.url ? new URL(design.meta.url).hostname.replace(/^www\./, '') : 'this site';
+  const title = design?.meta?.title || host;
+  const intent = design?.pageIntent?.label || 'landing';
+  const material = design?.materialLanguage?.label || 'flat';
+  const library = design?.componentLibrary?.label || null;
+  const grade = design?.score?.grade || null;
+
+  const blocks = [];
+  blocks.push(
+    `# You are building UI in the ${host} design system.`,
+    '',
+    `Source: ${design?.meta?.url || '—'}`,
+    `Extracted by designlang on ${new Date().toISOString().slice(0, 10)}.`,
+    '',
+    '## Brand at a glance',
+    '',
+    `- title         ${title}`,
+    `- page intent   ${intent}`,
+    `- material      ${material}`,
+    library ? `- library       ${library}` : null,
+    grade ? `- design grade  ${grade}` : null,
+    '',
+    '## Colour',
+    '',
+    listColors(design) || '_(no colour roles detected)_',
+    '',
+    '## Typography',
+    '',
+    listType(design),
+    '',
+  );
+
+  const spacing = listSpacing(design);
+  if (spacing) blocks.push('## Spacing', '', spacing, '');
+
+  const radii = listRadii(design);
+  if (radii) blocks.push('## Radii', '', radii, '');
+
+  const motion = listMotion(design);
+  if (motion) blocks.push('## Motion', '', motion, '');
+
+  const voice = listVoice(design);
+  if (voice) blocks.push('## Voice', '', voice, '');
+
+  const anatomy = listAnatomy(design);
+  if (anatomy) blocks.push('## Component anatomy', '', anatomy, '');
+
+  blocks.push('## Accessibility', '', listA11y(design), '');
+
+  blocks.push(
+    '## Build rules',
+    '',
+    '1. Use the colours above. **Never invent a new hex.** If you need a',
+    '   shade between two existing colours, derive it via HSL adjustment',
+    '   from the closest extracted colour and call out the derivation.',
+    '2. Use the extracted typography families. If you need a missing weight,',
+    '   pick the nearest available weight from the list and note it.',
+    '3. Snap spacing values to the scale above. No off-scale paddings or',
+    '   margins.',
+    '4. Snap border radii to the scale above.',
+    '5. Match the voice: same tone, same pronoun stance, same heading',
+    '   style. Reuse the listed CTA verbs.',
+    '6. Aim for WCAG AA contrast minimum. When the brand colours fail,',
+    '   prefer the foreground colour on the background colour rather than',
+    '   mid-tone neutrals.',
+    '7. Reuse component anatomy when it exists — do not invent novel',
+    '   structures for things the site already has.',
+    '',
+    '## Available context files',
+    '',
+    'designlang wrote these alongside this prompt. Reach for them when',
+    'you need ground truth:',
+    '',
+    '- `<host>-design-tokens.json` — DTCG primitive · semantic · composite tokens',
+    '- `<host>-tailwind.config.js`  — Tailwind v3 config',
+    '- `<host>-tailwind-v4.css`     — Tailwind v4 `@theme` block',
+    '- `<host>-tokens.d.ts`         — TypeScript literal-union types',
+    '- `<host>-variables.css`       — bare CSS custom properties',
+    '- `<host>-reset.css`           — brand-aware base styles',
+    '- `<host>-gradients.css`       — `.grad-N` utility classes',
+    '- `<host>-anatomy.tsx`         — typed React component scaffolds',
+    '- `<host>-shadcn-theme.css`    — shadcn/ui theme',
+    '- `<host>-theme.js`            — React / Vue / Svelte theme object',
+    '- `<host>-mcp.json`            — MCP server payload (load via stdio)',
+    '- `<host>.brand.pdf`           — print-ready 13-chapter brand book',
+    '',
+    'When you reference the system in code, prefer importing from these',
+    'files over hard-coding values.',
+    '',
+    '## Output expectations',
+    '',
+    'When asked to "build a pricing page" or "make a card" or any UI:',
+    '',
+    '- Produce a single self-contained component file in the appropriate',
+    '  framework (React / Vue / Svelte — match what the user is using).',
+    '- Use Tailwind utility classes wired to the v4 `@theme` if Tailwind',
+    '  is available; otherwise use the CSS custom properties from',
+    '  `variables.css`.',
+    '- Write the headline copy using the brand voice; do not invent',
+    '  generic Lorem.',
+    '- Annotate any choice where you had to bend the system, with a',
+    '  one-line `// note:` comment explaining what and why.',
+    '',
+    `## One-line install`,
+    '',
+    '```bash',
+    `npx designlang ${host}`,
+    '```',
+    '',
+    'Run this against any other URL to extract its system in the same',
+    'shape as the one above.',
+    '',
+    '---',
+    '',
+    `Generated by designlang. Re-extract by running \`npx designlang ${host}\`.`,
+    '',
+  );
+
+  return blocks.filter((b) => b !== null).join('\n');
+}

package/src/formatters/css-reset.js

@@ -0,0 +1,125 @@
+// CSS reset emitter — modern, brand-aware base styles.
+//
+// Most CSS resets (normalize, sanitize, Josh Comeau) are generic. This
+// one is wired to the brand we just extracted: body uses the brand
+// background / foreground, headings use the brand display family, links
+// use the brand primary, selection uses the brand accent.
+//
+// Drop at the top of your stylesheet, then import Tailwind / your CSS.
+
+const RESET = `/* ──────────────────────────────────────────────────────────────
+   Brand-aware reset — generated by designlang
+   {site}
+   {generated}
+   ────────────────────────────────────────────────────────────── */
+
+*, *::before, *::after { box-sizing: border-box; }
+
+html, body, h1, h2, h3, h4, h5, h6, p, ul, ol, li, blockquote, figure,
+form, fieldset, table, hr {
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+  -moz-text-size-adjust:    100%;
+  text-size-adjust:         100%;
+  -webkit-tap-highlight-color: transparent;
+  font-family: {fontSans}, system-ui, -apple-system, 'Segoe UI', sans-serif;
+  font-size: {fontBase}px;
+  line-height: 1.5;
+}
+
+body {
+  background-color: {bg};
+  color: {fg};
+  font-weight: 400;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: {fontDisplay}, system-ui, -apple-system, sans-serif;
+  font-weight: 600;
+  line-height: 1.15;
+  letter-spacing: -0.015em;
+}
+
+a {
+  color: {primary};
+  text-decoration: none;
+  background-color: transparent;
+}
+a:hover { text-decoration: underline; }
+a:focus-visible { outline: 2px solid {accent}; outline-offset: 2px; border-radius: 4px; }
+
+img, picture, video, canvas, svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+input, textarea, select, button {
+  font: inherit;
+  color: inherit;
+}
+button { cursor: pointer; background: none; border: 0; padding: 0; }
+
+code, pre, kbd, samp {
+  font-family: {fontMono}, ui-monospace, 'SF Mono', Menlo, monospace;
+}
+
+hr {
+  border: 0;
+  border-top: 1px solid {hairline};
+}
+
+::selection {
+  background: {accent};
+  color: {bg};
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.001ms !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+`;
+
+function pickFamily(design, kind) {
+  const fams = design?.typography?.families || [];
+  if (kind === 'mono') {
+    const m = fams.find((f) => /mono|code|courier/i.test(f.name || f));
+    return m ? `"${m.name || m}"` : 'ui-monospace';
+  }
+  if (kind === 'display') {
+    const d = fams.find((f) => /display|serif|headline/i.test(f.name || f));
+    return d ? `"${d.name || d}"` : `"${fams[0]?.name || fams[0] || 'system'}"`;
+  }
+  return fams[0] ? `"${fams[0].name || fams[0]}"` : 'system-ui';
+}
+
+function pickHex(design, role, fallback) {
+  return design?.colors?.[role]?.hex || fallback;
+}
+
+export function formatCssReset(design) {
+  const subs = {
+    site: design?.meta?.title || design?.meta?.url || '—',
+    generated: new Date().toISOString(),
+    fontSans:    pickFamily(design, 'sans'),
+    fontMono:    pickFamily(design, 'mono'),
+    fontDisplay: pickFamily(design, 'display'),
+    fontBase:    design?.typography?.base || 16,
+    bg:          pickHex(design, 'background', '#ffffff') || (design?.colors?.backgrounds?.[0] || '#ffffff'),
+    fg:          pickHex(design, 'foreground', '#000000') || (design?.colors?.text?.[0] || '#000000'),
+    primary:     pickHex(design, 'primary',   '#0070f3'),
+    accent:      pickHex(design, 'accent',    pickHex(design, 'primary', '#0070f3')),
+    hairline:    pickHex(design, 'secondary', '#e5e5e5'),
+  };
+  return RESET.replace(/\{(\w+)\}/g, (_, k) => subs[k] ?? `var(--${k})`);
+}

package/src/formatters/gradients.js

@@ -0,0 +1,88 @@
+// Gradients emitter — surface the gradients the colour extractor already
+// captured as a ready-to-paste CSS file with utility classes.
+//
+// Outputs two files:
+//   <host>-gradients.css   — :root vars + .grad-N utility classes
+//   <host>-gradients.json  — structured list (type, direction, stops)
+//
+// Designers like gradients. Most sites have 3–20 unique ones. Surfacing
+// them as utility classes lets engineers replicate hero / card / button
+// backgrounds without eye-balling rgba stops out of devtools.
+
+function cleanRaw(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  // Drop browser duplicates, collapse whitespace, trim quotes.
+  return raw.replace(/\s+/g, ' ').trim().replace(/^"|"$/g, '');
+}
+
+function uniqGradients(design) {
+  const list = design?.gradients?.gradients
+            || (Array.isArray(design?.gradients) ? design.gradients : [])
+            || (design?.colors?.gradients || []);
+  const out = [];
+  const seen = new Set();
+  for (const g of list) {
+    const raw = cleanRaw(g?.raw || g?.value || g);
+    if (!raw || !raw.includes('gradient')) continue;
+    if (seen.has(raw)) continue;
+    seen.add(raw);
+    out.push({
+      raw,
+      type: g?.type || (raw.match(/^(linear|radial|conic)-gradient/i)?.[1] || 'linear').toLowerCase(),
+      direction: g?.direction || null,
+      stops: Array.isArray(g?.stops) ? g.stops : [],
+      classification: g?.classification || null,
+    });
+  }
+  return out;
+}
+
+export function formatGradientsCss(design) {
+  const grads = uniqGradients(design);
+  if (grads.length === 0) {
+    return [
+      '/* designlang — no gradients detected on the source page. */',
+      '/* Run with --interactions to capture hover backgrounds. */',
+      '',
+    ].join('\n');
+  }
+
+  const lines = [
+    '/* ──────────────────────────────────────────────────────────────',
+    `   ${grads.length} gradients — generated by designlang`,
+    `   ${design?.meta?.url || ''}`,
+    `   ${new Date().toISOString()}`,
+    '   ────────────────────────────────────────────────────────────── */',
+    '',
+    ':root {',
+  ];
+  grads.forEach((g, i) => { lines.push(`  --grad-${i + 1}: ${g.raw};`); });
+  lines.push('}', '');
+
+  grads.forEach((g, i) => {
+    lines.push(
+      `/* ${g.type}${g.classification ? ` · ${g.classification}` : ''} */`,
+      `.grad-${i + 1}    { background-image: var(--grad-${i + 1}); }`,
+      `.grad-text-${i + 1} {`,
+      `  background-image: var(--grad-${i + 1});`,
+      `  -webkit-background-clip: text;`,
+      `          background-clip: text;`,
+      `  color: transparent;`,
+      `}`,
+      ''
+    );
+  });
+
+  return lines.join('\n');
+}
+
+export function formatGradientsJson(design) {
+  const grads = uniqGradients(design);
+  return JSON.stringify({
+    $schema: 'https://designlang.app/schemas/gradients.json',
+    source: design?.meta?.url || null,
+    generated: new Date().toISOString(),
+    count: grads.length,
+    gradients: grads,
+  }, null, 2);
+}

package/src/formatters/tailwind-v4.js

@@ -0,0 +1,104 @@
+// Tailwind v4 emitter — CSS-first configuration.
+//
+// Tailwind v4 moved away from the JS config file in favour of a CSS-native
+// `@theme { ... }` block. This emitter produces that block plus a `@layer
+// base` reset wired to the extracted brand. Drop the file at the top of
+// your `tailwind.css`, import Tailwind under it, done.
+//
+// See: https://tailwindcss.com/blog/tailwindcss-v4
+
+import { rgbToHsl } from '../utils.js';
+
+function scaleFromHex(hex, parsed) {
+  const { h, s } = parsed.hsl ?? rgbToHsl(parsed.rgb);
+  const levels = [
+    ['50', 97], ['100', 94], ['200', 86], ['300', 76], ['400', 64],
+    ['500', 50], ['600', 40], ['700', 32], ['800', 24], ['900', 16], ['950', 10],
+  ];
+  return Object.fromEntries(levels.map(([name, l]) => [name, `hsl(${h} ${s}% ${l}%)`]));
+}
+
+function kvBlock(prefix, obj) {
+  return Object.entries(obj)
+    .map(([k, v]) => `  ${prefix}-${k}: ${v};`)
+    .join('\n');
+}
+
+export function formatTailwindV4(design) {
+  const lines = [
+    '/* ──────────────────────────────────────────────────────────────',
+    '   Tailwind v4 @theme — generated by designlang',
+    `   site: ${design.meta?.title || design.meta?.url || '—'}`,
+    `   ${new Date().toISOString()}`,
+    '   Drop this above `@import "tailwindcss";`.',
+    '   ────────────────────────────────────────────────────────────── */',
+    '',
+    '@import "tailwindcss";',
+    '',
+    '@theme {',
+  ];
+
+  const tokens = {};
+
+  // brand colours with generated scales
+  for (const role of ['primary', 'secondary', 'accent']) {
+    const c = design.colors?.[role];
+    if (!c?.hex) continue;
+    const scale = scaleFromHex(c.hex, c);
+    for (const [step, val] of Object.entries(scale)) tokens[`color-${role}-${step}`] = val;
+    tokens[`color-${role}`] = c.hex;
+  }
+
+  // neutrals
+  (design.colors?.neutrals || []).slice(0, 10).forEach((n, i) => {
+    tokens[`color-neutral-${i * 100 || 50}`] = n.hex;
+  });
+  if (design.colors?.backgrounds?.[0]) tokens['color-background'] = design.colors.backgrounds[0];
+  if (design.colors?.text?.[0]) tokens['color-foreground'] = design.colors.text[0];
+
+  // typography
+  const fams = design.typography?.families || [];
+  if (fams[0]) tokens['font-sans'] = `"${fams[0].name || fams[0]}", system-ui, sans-serif`;
+  const mono = fams.find((f) => /mono|code|courier/i.test(f.name || f));
+  if (mono) tokens['font-mono'] = `"${mono.name || mono}", ui-monospace, monospace`;
+
+  // spacing
+  (design.spacing?.scale || []).slice(0, 12).forEach((px, i) => {
+    tokens[`spacing-${i + 1}`] = `${px}px`;
+  });
+
+  // radii
+  const radii = design.borders?.radii || [];
+  const radiusNames = ['sm', 'md', 'lg', 'xl', '2xl', 'full'];
+  radii.slice(0, radiusNames.length).forEach((r, i) => {
+    const px = typeof r === 'object' ? r.value : r;
+    tokens[`radius-${radiusNames[i]}`] = px >= 999 ? '9999px' : `${px}px`;
+  });
+
+  // shadows
+  const shadows = design.shadows?.values || design.shadows || [];
+  (Array.isArray(shadows) ? shadows : []).slice(0, 4).forEach((sh, i) => {
+    const value = typeof sh === 'object' ? sh.value || sh.raw : sh;
+    tokens[`shadow-${['sm', 'md', 'lg', 'xl'][i]}`] = String(value);
+  });
+
+  // motion
+  const durations = design.motion?.durations || [];
+  durations.slice(0, 4).forEach((d, i) => {
+    tokens[`animate-duration-${['fast', 'base', 'slow', 'slower'][i]}`] = typeof d === 'object' ? d.value : `${d}ms`;
+  });
+
+  for (const [k, v] of Object.entries(tokens)) {
+    lines.push(`  --${k}: ${v};`);
+  }
+
+  lines.push('}', '');
+  lines.push('/* Optional base reset that maps body/heading to the extracted tokens. */');
+  lines.push('@layer base {');
+  lines.push('  html { font-family: var(--font-sans); }');
+  if (tokens['color-background']) lines.push('  body { background-color: var(--color-background); color: var(--color-foreground, currentColor); }');
+  lines.push('}');
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/formatters/ts-defs.js

@@ -0,0 +1,125 @@
+// TypeScript token-types emitter.
+//
+// Writes `<host>-tokens.d.ts` — strict literal-union types for every
+// extracted token so component props like `color?: ColorToken` get
+// autocompleted and type-checked against the actual brand, not a
+// generic `string`. Pairs with the `<host>-theme.js` JS theme object.
+
+function safeKey(s) {
+  return String(s || '')
+    .replace(/[^a-zA-Z0-9_$]/g, '_')
+    .replace(/^([0-9])/, '_$1')
+    .toLowerCase();
+}
+
+function asScalar(v) {
+  if (v == null) return null;
+  if (typeof v === 'string' || typeof v === 'number') return String(v);
+  if (typeof v === 'object') {
+    if (typeof v.value  !== 'undefined') return asScalar(v.value);
+    if (typeof v.px     !== 'undefined') return String(v.px);
+    if (typeof v.weight !== 'undefined') return String(v.weight);
+    if (typeof v.ms     !== 'undefined') return String(v.ms);
+    if (typeof v.hex    !== 'undefined') return String(v.hex);
+    if (typeof v.name   !== 'undefined') return String(v.name);
+    return null; // unknown shape — drop
+  }
+  return null;
+}
+
+function quoteUnion(values) {
+  const unique = [...new Set(values.map(asScalar).filter(Boolean))];
+  if (unique.length === 0) return 'never';
+  return unique.map((v) => `'${v.replace(/'/g, "\\'")}'`).join(' | ');
+}
+
+export function formatTsDefs(design) {
+  const lines = [
+    '// Auto-generated by designlang. Do not edit by hand.',
+    '// Re-extract with `npx designlang <url>` to refresh.',
+    '//',
+    '// Import next to your token JSON to get type-safe access:',
+    '//',
+    '//   import type { ColorToken, SpacingToken } from \'./<host>-tokens\';',
+    '//   import tokens from \'./<host>-design-tokens.json\';',
+    '//',
+    `// Source: ${design.meta?.url || '—'}`,
+    `// Generated: ${new Date().toISOString()}`,
+    '',
+    'export type Hex = `#${string}`;',
+    'export type Px  = `${number}px`;',
+    'export type Ms  = `${number}ms`;',
+    '',
+  ];
+
+  // colour role union (primary | secondary | ...)
+  const colourRoles = ['primary', 'secondary', 'accent']
+    .filter((r) => design.colors?.[r]?.hex);
+  lines.push(`export type ColorRole = ${quoteUnion(colourRoles) || quoteUnion(['primary'])};`);
+
+  // every unique hex
+  const palette = (design.colors?.all || []).map((c) => c.hex).filter(Boolean);
+  lines.push(`export type ColorHex  = ${quoteUnion(palette) || 'Hex'};`);
+  lines.push('export type ColorToken = ColorRole | ColorHex;');
+  lines.push('');
+
+  // typography
+  const fonts = (design.typography?.families || []).map((f) => f.name || f).filter(Boolean);
+  lines.push(`export type FontFamilyToken = ${quoteUnion(fonts) || quoteUnion(['system'])};`);
+
+  const sizes = (design.typography?.sizes || []).map((s) => `${typeof s === 'object' ? s.value || s.px : s}px`).filter(Boolean);
+  lines.push(`export type FontSizeToken   = ${quoteUnion(sizes) || 'Px'};`);
+
+  const weights = (design.typography?.weights || []);
+  lines.push(`export type FontWeightToken = ${quoteUnion(weights) || `'400' | '500' | '600' | '700'`};`);
+  lines.push('');
+
+  // spacing
+  const spacing = (design.spacing?.scale || []).map((px) => `${px}px`).filter(Boolean);
+  lines.push(`export type SpacingToken = ${quoteUnion(spacing) || 'Px'};`);
+  lines.push('');
+
+  // radii
+  const radii = (design.borders?.radii || []).map((r) => `${typeof r === 'object' ? r.value : r}px`).filter(Boolean);
+  lines.push(`export type RadiusToken = ${quoteUnion(radii) || 'Px'};`);
+  lines.push('');
+
+  // motion
+  const durations = (design.motion?.durations || []).map((d) => `${typeof d === 'object' ? (d.value || d.ms) : d}ms`).filter(Boolean);
+  lines.push(`export type DurationToken = ${quoteUnion(durations) || 'Ms'};`);
+
+  const easings = (design.motion?.easings || []).map((e) => typeof e === 'object' ? e.value : e).filter(Boolean);
+  lines.push(`export type EasingToken   = ${quoteUnion(easings) || 'string'};`);
+  lines.push('');
+
+  // semantic intent
+  if (design.pageIntent?.label) {
+    lines.push(`export type PageIntent = ${quoteUnion([design.pageIntent.label])};`);
+  }
+  if (design.materialLanguage?.label) {
+    lines.push(`export type MaterialLanguage = ${quoteUnion([design.materialLanguage.label])};`);
+  }
+
+  // a roll-up interface for the whole token tree
+  lines.push('');
+  lines.push('export interface DesignTokens {');
+  lines.push('  color: { [role in ColorRole]: ColorHex };');
+  lines.push('  typography: {');
+  lines.push('    family: FontFamilyToken;');
+  lines.push('    size: FontSizeToken;');
+  lines.push('    weight: FontWeightToken;');
+  lines.push('  };');
+  lines.push('  spacing: ReadonlyArray<SpacingToken>;');
+  lines.push('  radius:  ReadonlyArray<RadiusToken>;');
+  lines.push('  motion: {');
+  lines.push('    duration: ReadonlyArray<DurationToken>;');
+  lines.push('    easing:   ReadonlyArray<EasingToken>;');
+  lines.push('  };');
+  lines.push('}');
+  lines.push('');
+  lines.push('declare const tokens: DesignTokens;');
+  lines.push('export default tokens;');
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/utils/palette-compress.js

@@ -0,0 +1,152 @@
+// Smart palette compression via LAB-space k-means.
+//
+// Raw extractions often yield 60–200 unique colours (every minor RGB
+// variation, every transparent overlay's blended result). That's noise,
+// not a system. This module reduces a long input list to a short,
+// perceptually distinct output palette by:
+//
+//   1. Converting every hex to CIELAB (perceptually uniform)
+//   2. Weighting each colour by its usage count (frequency)
+//   3. Running weighted k-means with k+ seeded by the most-used colours
+//   4. Returning the cluster medoids (the actual real colour closest to
+//      each cluster centre — not a synthesised average that doesn't
+//      exist on the page).
+//
+// Pure functions, no dependencies. ~150 LOC.
+
+function hexToRgb(hex) {
+  const s = String(hex || '').trim().replace(/^#/, '');
+  const full = s.length === 3 ? s.split('').map((c) => c + c).join('') : s.slice(0, 6);
+  if (!/^[0-9a-f]{6}$/i.test(full)) return null;
+  return {
+    r: parseInt(full.slice(0, 2), 16),
+    g: parseInt(full.slice(2, 4), 16),
+    b: parseInt(full.slice(4, 6), 16),
+  };
+}
+
+// sRGB → linear → XYZ → CIELAB (D65)
+function rgbToLab(rgb) {
+  const srgb = [rgb.r, rgb.g, rgb.b].map((v) => v / 255);
+  const lin = srgb.map((v) => (v > 0.04045 ? ((v + 0.055) / 1.055) ** 2.4 : v / 12.92));
+  const [r, g, b] = lin;
+  const x = (r * 0.4124564 + g * 0.3575761 + b * 0.1804375) / 0.95047;
+  const y = (r * 0.2126729 + g * 0.7151522 + b * 0.0721750) / 1.00000;
+  const z = (r * 0.0193339 + g * 0.1191920 + b * 0.9503041) / 1.08883;
+  const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);
+  const fx = f(x), fy = f(y), fz = f(z);
+  return {
+    L: 116 * fy - 16,
+    a: 500 * (fx - fy),
+    b: 200 * (fy - fz),
+  };
+}
+
+function dist2(p, q) {
+  const dL = p.L - q.L, da = p.a - q.a, db = p.b - q.b;
+  return dL * dL + da * da + db * db;
+}
+
+function weightedCentroid(members) {
+  let wL = 0, wa = 0, wb = 0, w = 0;
+  for (const m of members) {
+    w  += m.weight;
+    wL += m.lab.L * m.weight;
+    wa += m.lab.a * m.weight;
+    wb += m.lab.b * m.weight;
+  }
+  return w > 0 ? { L: wL / w, a: wa / w, b: wb / w } : members[0]?.lab || { L: 0, a: 0, b: 0 };
+}
+
+function pickFurthestSeeds(points, k) {
+  if (points.length <= k) return points.map((p) => p.lab);
+  // Seed with the most-used colour, then pick the k-1 colours furthest from
+  // any already-seeded colour (max-min). Deterministic, no randomness, so
+  // the same input gives the same output every run.
+  const seeds = [];
+  const sorted = [...points].sort((x, y) => y.weight - x.weight);
+  seeds.push(sorted[0].lab);
+  while (seeds.length < k) {
+    let best = null, bestDist = -1;
+    for (const p of points) {
+      const minD = seeds.reduce((m, s) => Math.min(m, dist2(p.lab, s)), Infinity);
+      const score = minD * Math.log1p(p.weight); // bias toward heavy + far
+      if (score > bestDist) { bestDist = score; best = p; }
+    }
+    if (!best) break;
+    seeds.push(best.lab);
+  }
+  return seeds;
+}
+
+function kmeans(points, k, { maxIter = 60 } = {}) {
+  if (points.length === 0) return [];
+  if (points.length <= k) return points.map((p) => [p]);
+
+  let centres = pickFurthestSeeds(points, k);
+  let clusters = Array.from({ length: k }, () => []);
+
+  for (let iter = 0; iter < maxIter; iter++) {
+    clusters = Array.from({ length: k }, () => []);
+    for (const p of points) {
+      let bestI = 0, bestD = Infinity;
+      for (let i = 0; i < centres.length; i++) {
+        const d = dist2(p.lab, centres[i]);
+        if (d < bestD) { bestD = d; bestI = i; }
+      }
+      clusters[bestI].push(p);
+    }
+    const newCentres = clusters.map((members, i) =>
+      members.length > 0 ? weightedCentroid(members) : centres[i]
+    );
+    // converged?
+    const moved = newCentres.reduce((sum, c, i) => sum + dist2(c, centres[i]), 0);
+    centres = newCentres;
+    if (moved < 0.5) break;
+  }
+  return clusters.filter((c) => c.length > 0);
+}
+
+/**
+ * @param {Array<{ hex: string, count?: number }>} input
+ * @param {number} k target palette size
+ */
+export function compressPalette(input, k = 12) {
+  const points = [];
+  for (const c of input || []) {
+    const rgb = hexToRgb(c.hex);
+    if (!rgb) continue;
+    points.push({
+      hex: c.hex,
+      rgb,
+      lab: rgbToLab(rgb),
+      weight: Math.max(1, c.count || c.weight || 1),
+      original: c,
+    });
+  }
+  if (points.length === 0) return [];
+  if (points.length <= k) return points.map((p) => ({ ...p.original, hex: p.hex, count: p.weight, clusterSize: 1 }));
+
+  const clusters = kmeans(points, k);
+  // For each cluster, return the medoid — the real colour in the
+  // cluster closest to the centroid. Never invent a hex that wasn't
+  // on the page.
+  return clusters
+    .map((members) => {
+      const centre = weightedCentroid(members);
+      let best = members[0], bestD = Infinity;
+      for (const m of members) {
+        const d = dist2(m.lab, centre);
+        if (d < bestD) { bestD = d; best = m; }
+      }
+      const totalCount = members.reduce((s, m) => s + m.weight, 0);
+      return {
+        ...best.original,
+        hex: best.hex,
+        count: totalCount,
+        clusterSize: members.length,
+        clusterMembers: members.map((m) => m.hex),
+      };
+    })
+    .sort((x, y) => (y.count || 0) - (x.count || 0));
+}