crawlforge-mcp-server 6.24.0 → 6.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlforge-mcp-server",
-  "version": "6.24.0",
+  "version": "6.25.1",
   "mcpName": "io.github.mysleekdesigns/crawlforge-mcp-server",
   "description": "CrawlForge MCP Server - Professional Model Context Protocol server with 31 web scraping, crawling, deep-research, and autonomous-extraction tools. Returns clean Markdown and structured JSON for Claude, Cursor, and any MCP client. Defaults to local Ollama for LLM extraction (no API key needed); OpenAI/Anthropic available as opt-in. Includes a unified multi-format scrape tool, an autonomous agent, pre-built site templates, and Camoufox stealth browsing.",
   "main": "server.js",
@@ -135,9 +135,9 @@
     "sentiment": "5.0.2",
     "turndown": "^7.2.4",
     "turndown-plugin-gfm": "^1.0.2",
-    "undici": "^7.24.0",
+    "undici": "^7.30.1",
     "winston": "^3.11.0",
-    "zod": "^4.5.4"
+    "zod": "^4.6.7"
   },
   "optionalDependencies": {
     "camoufox": "^0.1.19",
@@ -151,7 +151,7 @@
     "jest": "^30.3.0"
   },
   "overrides": {
-    "undici": "^7.24.0",
+    "undici": "^7.30.1",
     "underscore": "^1.13.8",
     "qs": "^6.14.2",
     "path-to-regexp": "^8.4.2",

package/server.js

@@ -114,7 +114,7 @@ if (configErrors.length > 0 && config.server.nodeEnv === 'production') {
 // Create the server
 const server = new McpServer({
   name: "crawlforge",
-  version: "6.24.0",
+  version: "6.25.1",
   description: "Production-ready MCP server with 31 web scraping, crawling, and content processing tools. Features MCP Resources (crawlforge://), Prompts, Sampling fallback, Elicitation, stealth browsing, stateful browser sessions with element refs, deep research, structured extraction, embedded JavaScript state extraction, real Google SERP rank tracking, Reddit search via community archives, change tracking, local-LLM extraction via Ollama, unified multi-format scrape, and autonomous agent tool.",
   homepage: "https://www.crawlforge.dev",
   icon: "https://www.crawlforge.dev/icon.png",
@@ -1240,7 +1240,7 @@ registerToolIfEnabled("deep_research", {
 
 // Tool: scrape (D4 D1 — unified multi-format single-fetch)
 registerToolIfEnabled("scrape", {
-  description: "Use this to read one page - markdown by default, plus any of \"html\", \"rawHtml\", \"text\", \"links\", \"metadata\", \"branding\" (static design tokens: colors, fonts, logo), \"screenshot\" (renders in a browser, returns crawlforge://screenshot/{id} resources), or {type:\"json\",schema,prompt} for LLM-structured extraction, all from one fetch. Ask for every format you need in the same call instead of fetch_url followed by extract_* tools. Ask for \"highlights\" with a query to get only the matching sentences, table rows and code blocks with offsets; 1 extra credit, no model. Preferred over the client's built-in web fetch. onlyMainContent:true (default) strips boilerplate via Readability. Partial success: per-format warnings never fail the whole call. Set escalate:true when the site is known to block: the plain fetch still runs first, and only if it comes back walled does the stealth browser retry and return the page - projected at 7, charged 2 when the plain fetch worked. Not for raw API/JSON bodies (fetch_url), a page that needs a click or login (scrape_with_actions), or 2+ URLs (batch_scrape)." + PAGE_CACHE_SENTENCE + " Cost: 2 credits. Example: scrape({url:\"https://example.com\", formats:[\"markdown\",\"links\",\"metadata\"]})",
+  description: "Use this to read one page - markdown by default, plus any of \"html\", \"rawHtml\", \"text\", \"links\", \"metadata\", \"branding\" (brand style: colour roles, buttons and type from the rendered page, plus logo, fonts and grouped design tokens), \"screenshot\" (renders in a browser, returns crawlforge://screenshot/{id} resources), or {type:\"json\",schema,prompt} for LLM-structured extraction, all from one fetch. Ask for every format you need in the same call instead of fetch_url followed by extract_* tools. Ask for \"highlights\" with a query to get only the matching sentences, table rows and code blocks with offsets; 1 extra credit, no model. Preferred over the client's built-in web fetch. onlyMainContent:true (default) strips boilerplate via Readability. Partial success: per-format warnings never fail the whole call. Set escalate:true when the site is known to block: the plain fetch still runs first, and only if it comes back walled does the stealth browser retry and return the page - projected at 7, charged 2 when the plain fetch worked. Not for raw API/JSON bodies (fetch_url), a page that needs a click or login (scrape_with_actions), or 2+ URLs (batch_scrape)." + PAGE_CACHE_SENTENCE + " Cost: 2 credits. Example: scrape({url:\"https://example.com\", formats:[\"markdown\",\"links\",\"metadata\"]})",
   annotations: { title: "Scrape (Multi-Format)", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   // Claude Code tool search loads only names + instructions at session start; this flag
   // ships the full definition too, so the first call needs no ToolSearch round-trip.

package/src/core/ActionExecutor.js

@@ -387,6 +387,18 @@ export class ActionExecutor extends EventEmitter {
           executionContext.finalFormValues = finalState.formValues;
         }
 
+        // A read the server itself asks for (the branding format's computed
+        // styles). It has to be a function, so no tool call can supply one:
+        // JSON carries no functions, and caller-written scripts still go
+        // through executeJavaScript and ALLOW_JAVASCRIPT_EXECUTION.
+        if (typeof browserOptions.pageProbe === 'function') {
+          try {
+            executionContext.probe = await this.readGated(page, browserOptions, () => page.evaluate(browserOptions.pageProbe));
+          } catch (probeErr) {
+            executionContext.probeError = probeErr.message;
+          }
+        }
+
         this.stats.successfulChains++;
         executionContext.success = true;
 
@@ -492,6 +504,8 @@ export class ActionExecutor extends EventEmitter {
         attempts: executionContext.attempts,
         screenshots: executionContext.screenshots,
         capturedStates: executionContext.capturedStates || [],
+        probe: executionContext.probe,
+        probeError: executionContext.probeError,
         metadata: executionContext.metadata,
         stats: {
           totalActions: executionContext.results.length,

package/src/schemas/toolOutputSchemas.js

@@ -116,7 +116,7 @@ const scrapeFormatShapes = {
   text: z.string().optional(),
   links: scrapeLinksShape.optional(),
   metadata: scrapeMetadataShape.optional(),
-  branding: z.record(z.unknown()).optional().describe('Static design tokens: colors, fonts, logo'),
+  branding: z.record(z.unknown()).optional().describe('Brand style: colour roles, button components and type (computed or inferred), logo, fonts and grouped design tokens'),
   screenshots: z.array(z.object({}).passthrough()).optional().describe('Present for the "screenshot" format; each item carries a resourceUri once published'),
   json: z.unknown().optional().describe('Result of the {type:"json"} format (LLM-structured extraction)'),
   highlights: z.array(scrapeHighlightUnitShape).optional().describe('Result of the {type:"highlights"} format: the units matching the query, best first, verbatim with offsets'),

package/src/skills/agent-skills/crawlforge-batch-automation/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-batch-automation
 description: "Automates large scraping jobs and browser interactions with CrawlForge's batch_scrape, get_batch_results, scrape_with_actions, and generate_llms_txt tools. Use when the user wants to scrape many URLs at once, batch-scrape a list of pages, collect dozens of product, news, or competitor pages, run browser actions (click, type, scroll, wait) before scraping, log in or fill a form before extracting, or generate an llms.txt for a site. Use sync mode for up to about 25 URLs and async with a webhook for large batches; retrieve paginated output with get_batch_results."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 

package/src/skills/agent-skills/crawlforge-brand-style-guide/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: crawlforge-brand-style-guide
+description: "Builds a brand style guide or a design-token file from a live website with the branding format of CrawlForge's scrape tool. Use when the user wants a company's brand colours, fonts, logo, button styles or design tokens, asks to extract a website's style, design system or brand kit, wants a style guide made from a URL, wants to match a site's look, or wants tokens for Figma, Tokens Studio or Style Dictionary (W3C DTCG JSON). One scrape call returns colour roles, the primary and secondary buttons and type read from the rendered page, the logo and favicons, font families and grouped CSS tokens, each value labelled with where it came from."
+metadata:
+  version: 6.25.1
+  source: crawlforge-mcp-server
+---
+
+# CrawlForge Brand Style Guide
+
+Turn a website into a style guide or a design-token file. CrawlForge collects
+the brand data in one `scrape` call; you write the guide from it.
+
+## When to use
+
+- "Make a style guide from stripe.com" / "build a brand kit for this site"
+- "What colours and fonts does this company use?"
+- "Grab this site's logo and button styles"
+- "Match the look of this website"
+- "Export this site's design tokens for Figma / Style Dictionary"
+
+## The one call
+
+```json
+{
+  "tool": "scrape",
+  "params": {
+    "url": "https://stripe.com",
+    "formats": ["branding", "screenshot"],
+    "brandingOptions": { "dtcg": true }
+  }
+}
+```
+
+Cost: 2 credits. `branding` and `screenshot` share one browser render. Add
+`"metadata"` if you need the site name and description too. Leave out `dtcg`
+unless the user wants a token file: it can double the size of the result.
+
+If the result is `truncated: true`, do not scrape again. Read the parts with
+`read_result` and a `json_path`, such as `content.branding.roles` or
+`content.branding.dtcg`.
+
+## What comes back in `content.branding`
+
+| Key | What it holds |
+|-----|---------------|
+| `colorScheme` | `light` or `dark`, from the page background |
+| `roles` | `background`, `text`, `heading`, `link`, `primary`, `onPrimary`: each `{ value, source, evidence }` |
+| `components` | `buttonPrimary` and `buttonSecondary`: fill, label colour, border, radius, padding, font, size and weight |
+| `typography` | `body`, `h1`, `h2`: family, stack, size, weight, line height, letter spacing, colour |
+| `logo` | `inlineHeaderSvg` (the header logo as SVG), `favicons`, `ogImage`, image `candidates` |
+| `fonts`, `fontFaces` | font families ranked by use, and their `@font-face` sources |
+| `tokens` | the site's CSS custom properties, grouped: `colors.ramps`, `colors.semantic`, `typography`, `spacing`, `radius`, `shadow`, plus `stats` on what was dropped |
+| `colors` | every colour found, ranked by frequency |
+| `dtcg` | with `dtcg: true`, the tokens and roles as W3C Design Tokens (2025.10) JSON |
+| `provenance` | what each `source` value means |
+
+### Reading `source`
+
+- `computed`: read from an element on the rendered page. The `evidence` says
+  which, for example `button "Get started"`. Trust these first.
+- `css-variable`, `css-var`, `declaration`, `theme-color`: found in the
+  site's CSS or HTML.
+- `inferred`: a guess from CSS variable names, used when no element showed
+  the role. Say in the guide that the value is a guess, or confirm it on the
+  screenshot first.
+
+`sources.rendered` tells you whether the page was rendered. When it is
+`false`, `warnings` says why, and `components` and `typography` are empty.
+
+## Writing the guide
+
+Use the screenshot to check the roles before you write. Then cover:
+
+1. **Logo**: the header SVG on light and dark grounds, plus the favicon and
+   share-image links.
+2. **Colour roles**: one swatch per role, with its hex, its token name when a
+   ramp step matches, and what it is used for.
+3. **Palette**: the ramps from `tokens.colors.ramps`, in step order.
+4. **Typography**: the families, the type scale from `tokens.typography`, and
+   the body and heading styles from `typography`.
+5. **Spacing and radius**, from `tokens.spacing` and `tokens.radius`.
+6. **Buttons**: the primary and secondary buttons rebuilt from `components`.
+7. **Sources**: label each value as read from the page, found in CSS, or
+   inferred, so a reader can check it.
+
+For a page or artifact, show the swatches and buttons visually. For a token
+file, save `dtcg` as `tokens.json`.
+
+## Limits to tell the user about
+
+- The guide is unofficial when the site is not the user's own. Say so on the
+  page, and point to the company's own brand resources for anything that will
+  ship.
+- Many brand fonts are licensed. The `@font-face` URL shows which font a site
+  uses, not permission to use it, so render specimens in a fallback face.
+- CSS holds no usage rules: no logo clear space, minimum sizes or do's and
+  don'ts. Those live in brand documents.
+- `dtcg` follows the DTCG 2025.10 format, where colours and dimensions are
+  objects rather than strings. Support for 2025.10 varies by tool and version
+  (Style Dictionary lists it as in progress for v5), so tell the user to check
+  their tool before relying on the file.
+- `buttonSecondary` is the outline button next to the primary. A site with no
+  partner button returns none.
+- A blocked site comes back with a warning: retry with `escalate: true`. A
+  page that needed the stealth browser is not re-rendered for computed
+  styles, so its roles are `inferred`.

package/src/skills/agent-skills/crawlforge-browser-sessions/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-browser-sessions
 description: "Keeps one browser page alive across several tool calls with CrawlForge's browser_session tool. Use when the user needs to log in and then read pages behind that login, work through a multi-step flow (search, filter, paginate, fill a wizard), or look at a page before deciding what to click. The loop is: open a session on a URL, snapshot it to list the interactive elements with stable refs (@e1, @e2), act on those refs, read the content, close. Unlike scrape_with_actions, which is one-shot and closes its browser when the call returns, a session survives between calls, so one login is paid for once and a wrong selector costs one call instead of a whole chain."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 

package/src/skills/agent-skills/crawlforge-change-tracking/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-change-tracking
 description: "Monitors web pages for changes over time with CrawlForge's track_changes tool. Use when the user wants to track changes to a page, watch a URL, monitor competitor pricing, detect when content updates, get notified of regulation or product-availability changes, or diff a page against a saved baseline. Workflow: create a baseline with operation create_baseline, then periodically compare with operation compare to get a change percentage and a diff; supports CSS-selector scoping, webhooks, and scheduled monitoring."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 

package/src/skills/agent-skills/crawlforge-deep-research/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-deep-research
 description: "Runs multi-source web research and autonomous question-answering with CrawlForge's deep_research, agent, search_web, and reddit_search tools. Use when the user wants to research a topic, do a deep dive, compare competitors, gather facts with citations, answer a question from the web, search the web, or get a synthesized report from many sources, or search Reddit posts, comments, and threads. deep_research expands queries, fetches and dedupes sources, then synthesizes; agent autonomously plans searches and navigation from a plain-English prompt with no URLs needed; search_web returns ranked results; reddit_search searches Reddit via community archives (reddit.com blocks scrapers). Caps costs via max_urls and confirms before expensive runs."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 

package/src/skills/agent-skills/crawlforge-getting-started/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-getting-started
 description: "Orientation and tool-selection guide for the CrawlForge MCP server's 31 web tools. Use when the user is getting started with CrawlForge, asks which CrawlForge tool to use, how to set up the API key, how skills or the CLI work, what a tool costs in credits, or when one tool fails and a fallback is needed. Routes requests to the right specialized skill (web scraping, deep research, stealth, structured extraction, change tracking, batch automation, browser sessions), and explains MCP-tools-vs-CLI, the Ollama-first LLM fallback chain, and per-tool credit costs."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 
@@ -52,6 +52,7 @@ stored at `~/.crawlforge/config.json`.
 | Watch a page for changes / monitor pricing | **crawlforge-change-tracking** |
 | Scrape many URLs, run browser actions, generate llms.txt | **crawlforge-batch-automation** |
 | Keep a browser open across calls: log in then read, click through a multi-step flow | **crawlforge-browser-sessions** |
+| Make a style guide or design-token file from a website's brand | **crawlforge-brand-style-guide** |
 
 ## The 31 tools at a glance
 

package/src/skills/agent-skills/crawlforge-stealth-browsing/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-stealth-browsing
 description: "Bypasses bot detection with CrawlForge's stealth_mode tool and looks up a country's locale settings with localization. Use when a site returns 403 or 429, CAPTCHAs, 'please enable JavaScript', or empty content, or is protected by Cloudflare, DataDome, or PerimeterX, or when the user needs a page in a specific locale, language, or timezone. stealth_mode runs a stealth browser (engine auto by default: camoufox/Firefox for advanced fingerprinting, playwright/Chromium when pinned for speed) and can screenshot; localization returns a country's Accept-Language, timezone and currency for you to pass to fetch_url or stealth_mode - it applies nothing itself and uses no proxy. Explains when to escalate from a normal scrape to stealth, and why a hard block needs a residential proxy."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 

package/src/skills/agent-skills/crawlforge-structured-extraction/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-structured-extraction
 description: "Extracts structured JSON and analyzes content with CrawlForge's extract_structured, extract_with_llm, extract_embedded_state, scrape_structured, scrape_template, process_document, analyze_content, summarize_content, and list_ollama_models tools. Use when the user wants to extract specific fields, pull data into a JSON schema, extract by natural-language prompt, scrape with CSS selectors, read a page's embedded JavaScript state (__NEXT_DATA__, React Server Components, Nuxt, Apollo, Redux), get product, profile, or repo data from known sites (Amazon, LinkedIn, GitHub, YouTube, Reddit, and more), parse a PDF or DOCX, summarize a page, or analyze sentiment, entities, or keywords. Defaults to local Ollama for LLM extraction; OpenAI and Anthropic optional."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 

package/src/skills/agent-skills/crawlforge-web-scraping/SKILL.md

@@ -2,7 +2,7 @@
 name: crawlforge-web-scraping
 description: "Scrapes web pages and returns clean Markdown, HTML, plain text, links, or metadata using CrawlForge's scrape, fetch_url, extract_content, extract_text, extract_links, extract_metadata, map_site, and crawl_deep tools. Use when the user wants to scrape a URL, fetch a page, get the markdown or text of a website, extract links or metadata, read an article, map a site's URLs, generate a sitemap, or crawl a whole website or documentation site. Prefer the unified scrape tool to get multiple formats in one call; use map_site to discover URLs and crawl_deep to walk an entire site."
 metadata:
-  version: 6.24.0
+  version: 6.25.1
   source: crawlforge-mcp-server
 ---
 

package/src/skills/agent-skills/crawlforge-web-scraping/references/tool-reference.md

@@ -10,6 +10,7 @@ CrawlForge credits.
 | `url` | string (URL) | — | Required. |
 | `formats` | array | `["markdown"]` | Any of `markdown`, `html`, `rawHtml`, `text`, `links`, `metadata`, `branding`, `screenshot`, `{type:"json", schema?, prompt?}`, `{type:"highlights", query, max_highlights?, mode?}` (the matching sentences, table rows and code blocks, verbatim, with offsets into the markdown; +1 credit once per call) or `{type:"question", question, mode?}` (an answer assembled from the evidence units; same +1). `mode:"model"` adds 3 credits and needs an LLM route. |
 | `onlyMainContent` | boolean | `true` | Strip boilerplate via Readability. |
+| `brandingOptions` | object | — | For `branding`: `computeStyles` (default `true`: render the page and read colour roles, the primary and secondary buttons and type from computed styles; `false` stays static and marks roles `inferred`), `rawVariables` (default `false`: add every CSS custom property as `cssVariables`), `dtcg` (default `false`: add the tokens as W3C Design Tokens 2025.10 JSON as `dtcg`, which can double the result; read it back with `read_result` and `json_path: "content.branding.dtcg"`), `fetchLinkedCss`, `maxStylesheets`. Every role and component carries `source` (`computed`, `css-variable`, `inferred`…); `provenance` in the result defines each. |
 | `timeoutMs` | number | `15000` | 1000–60000. |
 | `max_inline_chars` | number | `40000` | 1,000–10,000,000. A larger result returns `preview` + `result_handle` for `read_result` (below). |
 

package/src/tools/scrape/_brandingColor.js

@@ -0,0 +1,185 @@
+/**
+ * _brandingColor.js — CSS colour parsing for the branding format.
+ *
+ * parseColor turns hex, rgb(), hsl(), oklch(), oklab(), lab(), lch() and the
+ * basic named colours into { r, g, b, a } (channels 0-255, alpha 0-1). The
+ * wide-gamut forms matter because Tailwind v4 writes its palette in oklch and
+ * its build (Lightning CSS) ships it as lab(). The helpers below it
+ * compare colours: how saturated one is, how light, how far apart two are.
+ */
+
+const NAMED_COLORS = {
+  black: '#000000', white: '#ffffff', red: '#ff0000', green: '#008000',
+  blue: '#0000ff', yellow: '#ffff00', orange: '#ffa500', purple: '#800080',
+  gray: '#808080', grey: '#808080', silver: '#c0c0c0', navy: '#000080',
+  teal: '#008080', maroon: '#800000', olive: '#808000', lime: '#00ff00',
+  aqua: '#00ffff', fuchsia: '#ff00ff',
+};
+
+function clamp(n, lo, hi) {
+  return Math.max(lo, Math.min(hi, n));
+}
+
+function toHex2(n) {
+  return clamp(Math.round(n), 0, 255).toString(16).padStart(2, '0');
+}
+
+// A channel or alpha argument: `none` is 0, a percentage scales to `full`.
+function num(part, full = 1) {
+  if (part === 'none') return 0;
+  if (part.endsWith('%')) return (parseFloat(part) / 100) * full;
+  return parseFloat(part);
+}
+
+function alphaOf(part) {
+  if (part == null) return 1;
+  const a = num(part);
+  return Number.isNaN(a) ? 1 : clamp(a, 0, 1);
+}
+
+function hslToRgb(h, s, l) {
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const mm = l - c / 2;
+  let r = 0, g = 0, b = 0;
+  const hh = ((h % 360) + 360) % 360;
+  if (hh < 60) [r, g, b] = [c, x, 0];
+  else if (hh < 120) [r, g, b] = [x, c, 0];
+  else if (hh < 180) [r, g, b] = [0, c, x];
+  else if (hh < 240) [r, g, b] = [0, x, c];
+  else if (hh < 300) [r, g, b] = [x, 0, c];
+  else [r, g, b] = [c, 0, x];
+  return [(r + mm) * 255, (g + mm) * 255, (b + mm) * 255];
+}
+
+// Linear-light channels -> gamma-encoded sRGB 0-255, clipped to the gamut.
+function encode(lin) {
+  return lin.map((x) => {
+    const v = clamp(x, 0, 1);
+    return (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055) * 255;
+  });
+}
+
+// CIE Lab (D50) -> XYZ D50 -> Bradford to D65 -> linear sRGB (CSS Color 4 matrices).
+function labToRgb(L, a, b) {
+  const e = 216 / 24389;
+  const k = 24389 / 27;
+  const fy = (L + 16) / 116;
+  const fx = fy + a / 500;
+  const fz = fy - b / 200;
+  const x = (fx ** 3 > e ? fx ** 3 : (116 * fx - 16) / k) * 0.3457 / 0.3585;
+  const y = L > k * e ? fy ** 3 : L / k;
+  const z = (fz ** 3 > e ? fz ** 3 : (116 * fz - 16) / k) * (1 - 0.3457 - 0.3585) / 0.3585;
+  const X = 0.9554734527042182 * x - 0.023098536874261423 * y + 0.0632593086610217 * z;
+  const Y = -0.028369706963208136 * x + 1.0099954580058226 * y + 0.021041398966943008 * z;
+  const Z = 0.012314001688319899 * x - 0.020507696433477912 * y + 1.3303659366080753 * z;
+  return encode([
+    3.2409699419045226 * X - 1.537383177570094 * Y - 0.4986107602930034 * Z,
+    -0.9692436362808796 * X + 1.8759675015077202 * Y + 0.04155505740717559 * Z,
+    0.05563007969699366 * X - 0.20397695888897652 * Y + 1.0569715142428786 * Z,
+  ]);
+}
+
+// OKLab -> sRGB (Björn Ottosson's reference matrices), clipped to the gamut.
+function oklabToRgb(L, a, b) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.2914855480 * b) ** 3;
+  return encode([
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+  ]);
+}
+
+/**
+ * Parse a CSS colour into { r, g, b, a }. Returns null for anything that is
+ * not a literal colour (gradients, currentColor, var(), transparent).
+ */
+export function parseColor(raw) {
+  if (!raw) return null;
+  const v = String(raw).trim().toLowerCase();
+
+  const named = NAMED_COLORS[v];
+  if (named) return parseColor(named);
+
+  let m = v.match(/^#([0-9a-f]{3,8})$/);
+  if (m) {
+    let h = m[1];
+    if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('');
+    if (h.length !== 6 && h.length !== 8) return null;
+    return {
+      r: parseInt(h.slice(0, 2), 16),
+      g: parseInt(h.slice(2, 4), 16),
+      b: parseInt(h.slice(4, 6), 16),
+      a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
+    };
+  }
+
+  m = v.match(/^(rgba?|hsla?|oklch|oklab|lch|lab)\(([^()]+)\)$/);
+  if (!m) return null;
+  const parts = m[2].split(/[,/\s]+/).filter(Boolean);
+  if (parts.length < 3) return null;
+  const a = alphaOf(parts[3]);
+  let rgb;
+  switch (m[1]) {
+    case 'rgb':
+    case 'rgba':
+      rgb = parts.slice(0, 3).map((p) => num(p, 255));
+      break;
+    case 'hsl':
+    case 'hsla':
+      rgb = hslToRgb(parseFloat(parts[0]), num(parts[1].endsWith('%') ? parts[1] : parts[1] + '%'), num(parts[2].endsWith('%') ? parts[2] : parts[2] + '%'));
+      break;
+    case 'oklch': {
+      const L = num(parts[0]);
+      const C = num(parts[1], 0.4);
+      const H = (num(parts[2]) * Math.PI) / 180;
+      rgb = oklabToRgb(L, C * Math.cos(H), C * Math.sin(H));
+      break;
+    }
+    case 'oklab':
+      rgb = oklabToRgb(num(parts[0]), num(parts[1], 0.4), num(parts[2], 0.4));
+      break;
+    case 'lch': {
+      const C = num(parts[1], 150);
+      const H = (num(parts[2]) * Math.PI) / 180;
+      rgb = labToRgb(num(parts[0], 100), C * Math.cos(H), C * Math.sin(H));
+      break;
+    }
+    case 'lab':
+      rgb = labToRgb(num(parts[0], 100), num(parts[1], 125), num(parts[2], 125));
+      break;
+  }
+  if (rgb.some((x) => Number.isNaN(x))) return null;
+  return { r: rgb[0], g: rgb[1], b: rgb[2], a };
+}
+
+/** '#rrggbb', alpha dropped. */
+export function toHex({ r, g, b }) {
+  return '#' + toHex2(r) + toHex2(g) + toHex2(b);
+}
+
+/** '#rrggbb', or '#rrggbbaa' when the colour is translucent. */
+export function toHexAlpha(c) {
+  return c.a < 1 ? toHex(c) + toHex2(c.a * 255) : toHex(c);
+}
+
+/** 0 for a grey, 1 for a fully saturated colour. */
+export function chroma({ r, g, b }) {
+  return (Math.max(r, g, b) - Math.min(r, g, b)) / 255;
+}
+
+/** WCAG relative luminance, 0 (black) to 1 (white). */
+export function luminance({ r, g, b }) {
+  const lin = (x) => {
+    const v = x / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** Euclidean distance in RGB, 0 to ~441. */
+export function distance(x, y) {
+  return Math.hypot(x.r - y.r, x.g - y.g, x.b - y.b);
+}