rivet-design 0.9.2 → 0.9.4

package/dist/mcp/agent-variants/inspirationDesignContext.js

@@ -0,0 +1,2467 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standaloneDebugExtract = exports.extractPromptUrls = exports.extractInspirationDesignContext = exports.buildInspirationDesignContextMarkdown = exports.extractDesignSignals = exports.fetchLinkedStylesheets = exports.defaultLinkedCssFetcher = exports.discoverLinkedStylesheetUrls = exports.defaultInspirationFetcher = exports.classifyInspirationLinks = exports.inferLinkIntent = exports.isResolvedHostProtected = exports.isLocalLiteralHostname = exports.validateInspirationUrl = void 0;
+const dns_1 = __importDefault(require("dns"));
+const logger_1 = require("../../utils/logger");
+const sourceContext_1 = require("./sourceContext");
+Object.defineProperty(exports, "extractPromptUrls", { enumerable: true, get: function () { return sourceContext_1.extractPromptUrls; } });
+const designContextStore_1 = require("./designContextStore");
+const log = (0, logger_1.createLogger)('InspirationDesignContext');
+/**
+ * Constants. Kept above the function bodies so any tuning is in one place.
+ * Tight defaults so the 0 -> 1 flow does not stall on large or hostile pages.
+ */
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_BYTES = 1_500_000;
+// Note: Node's `fetch` follows up to undici's default redirect cap when
+// `redirect: 'follow'` is set; we additionally rely on FETCH_TIMEOUT_MS +
+// MAX_BYTES to bound pathological chains rather than enforcing a custom
+// cap here. If this moves to a lower-level HTTP client, reintroduce an
+// explicit redirect limit.
+const MAX_INSPIRATION_LINKS = 6;
+const MAX_PALETTE_COLORS = 12;
+const MAX_TYPOGRAPHY_FAMILIES = 8;
+const MAX_LIST_ITEMS_PER_SECTION = 12;
+const MAX_DESIGN_CONTEXT_LABEL_LENGTH = 60;
+const DESIGN_CONTEXT_LABEL_DEFAULT = 'Extracted from inspiration link';
+/**
+ * Caps for the new token-evidence fields. Bounded so a pathological
+ * stylesheet cannot blow up the persisted signal object or downstream
+ * markdown output.
+ */
+const MAX_SPACING_VALUES = 16;
+const MAX_ROUNDED_VALUES = 8;
+const MAX_SHADOWS = 8;
+const MAX_TRANSITIONS = 8;
+const MAX_BREAKPOINTS = 6;
+const MAX_COMPONENT_DETAILS = 8;
+const MAX_GOOGLE_FONT_FAMILIES = 12;
+const MAX_FONT_FACE_EVIDENCE = 8;
+/**
+ * Bounded discovery + fetch limits for linked stylesheets. Reuses the
+ * same SSRF / hostname checks as the HTML fetcher but applies tighter
+ * per-fetch byte and time budgets so a single inspiration link cannot
+ * stall the flow on heavy CSS bundles.
+ */
+const MAX_LINKED_STYLESHEETS = 4;
+const LINKED_CSS_FETCH_TIMEOUT_MS = 6_000;
+const LINKED_CSS_MAX_BYTES_PER_FILE = 500_000;
+const LINKED_CSS_MAX_TOTAL_BYTES = 1_500_000;
+/**
+ * Phrases in user prompts that indicate a URL is being shared as
+ * source/content reference rather than visual inspiration. When at least one
+ * of these patterns appears near a URL the link is classified as `reference`
+ * and excluded from inspiration extraction.
+ */
+const REFERENCE_INTENT_PATTERNS = [
+    /\bsource(?:s|\smaterial)?\b/i,
+    /\bcontent\s+reference\b/i,
+    /\bcontent\s+from\b/i,
+    /\bcopy\s+(?:the|from)\b/i,
+    /\bdocs?\b/i,
+    /\barticle\b/i,
+    /\bblog\s+post\b/i,
+    /\bdataset\b/i,
+    /\breference\s+only\b/i,
+];
+/**
+ * Phrases that indicate users want multiple URLs treated as alternatives,
+ * competitors, or contrasting references. When matched, multi-link extraction
+ * defaults to separate-per-slot design context instead of one merged set.
+ */
+const SEPARATE_INTENT_PATTERNS = [
+    /\balternatives?\b/i,
+    /\boptions?\b/i,
+    /\bcompetitors?\b/i,
+    /\bcontrast(?:ing)?\b/i,
+    /\bcompare\b/i,
+    /\bvs\.?\b/i,
+];
+const PRIVATE_IPV4_PATTERNS = [
+    /^10\./,
+    /^127\./,
+    /^192\.168\./,
+    /^169\.254\./,
+    /^172\.(1[6-9]|2\d|3[0-1])\./,
+    /^0\./,
+    // RFC6598 shared address space (CGNAT): 100.64.0.0/10 -> 100.64..100.127.
+    /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./,
+];
+// IPv6 private/reserved ranges.
+//   ::1         loopback
+//   fe80::/10   link-local (matches `fe80:` onwards)
+//   fc00::/7    unique-local (ULA) — first byte is `fc` OR `fd`, so the
+//               second hex pair after the prefix can be any value;
+//               previously `^fc00:` missed e.g. `fc12::1`.
+// IPv4-mapped IPv6 (`::ffff:x.x.x.x`) is handled separately via
+// `isIpv4MappedPrivateIpv6` below so the embedded v4 portion gets the
+// full v4 private-range check.
+const PRIVATE_IPV6_PATTERNS = [
+    /^::1$/i,
+    /^fe80:/i,
+    /^f[cd][0-9a-f]{2}:/i,
+];
+/**
+ * Detect an IPv4-mapped IPv6 address (`::ffff:x.x.x.x`) whose embedded
+ * IPv4 portion falls in the v4 private/reserved ranges. Returns false
+ * for non-mapped addresses so the caller can fall back to the regular
+ * v6 patterns. Without this, a dual-stack DNS lookup that returns
+ * `::ffff:127.0.0.1` or `::ffff:169.254.169.254` would slip past the v6
+ * regex set and reach the underlying private host.
+ */
+const isIpv4MappedPrivateIpv6 = (address) => {
+    const match = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+    if (!match)
+        return false;
+    const ipv4 = match[1];
+    return PRIVATE_IPV4_PATTERNS.some((pattern) => pattern.test(ipv4));
+};
+const LOCAL_HOSTNAME_PATTERNS = [
+    /^localhost$/i,
+    /\.localhost$/i,
+    /^localhost\./i,
+    /\.local$/i,
+    /\.internal$/i,
+    /\.lan$/i,
+    /\.intranet$/i,
+];
+const CSS_NAMED_COLORS = new Set([
+    'black',
+    'white',
+    'red',
+    'green',
+    'blue',
+    'yellow',
+    'orange',
+    'purple',
+    'pink',
+    'brown',
+    'gray',
+    'grey',
+    'cyan',
+    'magenta',
+    'lime',
+    'navy',
+    'teal',
+    'silver',
+    'gold',
+    'beige',
+    'maroon',
+    'olive',
+    'coral',
+    'indigo',
+    'violet',
+    'turquoise',
+]);
+const COMPONENT_HINTS = [
+    { keyword: /<button\b|class=("|')[^"']*\bbtn\b/i, label: 'buttons' },
+    { keyword: /<form\b|<input\b|<textarea\b|<select\b/i, label: 'forms' },
+    { keyword: /<nav\b|class=("|')[^"']*\bnav\b/i, label: 'navigation' },
+    { keyword: /<header\b/i, label: 'header / top bar' },
+    { keyword: /<footer\b/i, label: 'footer' },
+    { keyword: /class=("|')[^"']*\bhero\b/i, label: 'hero section' },
+    { keyword: /class=("|')[^"']*\bcard\b/i, label: 'cards' },
+    { keyword: /class=("|')[^"']*\b(badge|chip)\b/i, label: 'badges / chips' },
+    { keyword: /class=("|')[^"']*\bpricing\b/i, label: 'pricing layout' },
+    { keyword: /class=("|')[^"']*\bcta\b/i, label: 'call-to-action blocks' },
+    { keyword: /class=("|')[^"']*\btestimonial\b/i, label: 'testimonials' },
+    { keyword: /class=("|')[^"']*\b(modal|dialog)\b/i, label: 'modals / dialogs' },
+    { keyword: /class=("|')[^"']*\b(grid|columns)\b/i, label: 'grid / columnar layout' },
+    { keyword: /class=("|')[^"']*\bavatar\b/i, label: 'avatars' },
+];
+const MOTION_HINTS = [
+    { keyword: /\btransition\s*:/i, label: 'CSS transitions' },
+    { keyword: /\banimation\s*:/i, label: 'CSS keyframe animation' },
+    { keyword: /@keyframes\b/i, label: 'custom keyframes' },
+    { keyword: /\bdata-aos\b/i, label: 'scroll-driven AOS animations' },
+    { keyword: /\bmotion\.|framer-motion/i, label: 'motion library usage' },
+];
+const ICONOGRAPHY_HINTS = [
+    { keyword: /\b(?:phosphor|lucide|feather|heroicons|font-awesome|material-icons)\b/i, label: 'icon library references' },
+    { keyword: /<svg\b/i, label: 'inline SVG iconography' },
+];
+const trimWhitespace = (value) => value.replace(/\s+/g, ' ').trim();
+const dedupe = (values) => {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const cleaned = trimWhitespace(value);
+        if (!cleaned)
+            continue;
+        const key = cleaned.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(cleaned);
+    }
+    return out;
+};
+/**
+ * Synchronous URL validator: enforces HTTP/HTTPS scheme and rejects literal
+ * hostnames that match local/loopback/link-local patterns. DNS-resolved
+ * checks live in `defaultInspirationFetcher` so the simple checks here can
+ * run without IO during input validation.
+ */
+const validateInspirationUrl = (rawUrl) => {
+    const trimmed = rawUrl.trim();
+    if (!trimmed) {
+        return { ok: false, reason: 'URL is empty.' };
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return { ok: false, reason: `URL is not valid: ${trimmed}` };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return {
+            ok: false,
+            reason: `Only HTTP and HTTPS inspiration links are supported (got '${parsed.protocol.replace(/:$/, '')}').`,
+        };
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (!hostname) {
+        return { ok: false, reason: 'URL is missing a hostname.' };
+    }
+    if ((0, exports.isLocalLiteralHostname)(hostname)) {
+        return {
+            ok: false,
+            reason: `URL hostname '${hostname}' resolves to a local or private-network target.`,
+        };
+    }
+    parsed.hash = '';
+    return { ok: true, url: parsed, normalized: parsed.toString() };
+};
+exports.validateInspirationUrl = validateInspirationUrl;
+/**
+ * Returns true for hostnames that are unambiguously local or private without
+ * any DNS lookup. IPv4 / IPv6 literals get the private-range check;
+ * hostname strings get the local-domain pattern check.
+ */
+const isLocalLiteralHostname = (hostname) => {
+    const trimmed = hostname.replace(/^\[|\]$/g, '');
+    if (PRIVATE_IPV4_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+        return true;
+    }
+    if (PRIVATE_IPV6_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+        return true;
+    }
+    if (isIpv4MappedPrivateIpv6(trimmed)) {
+        return true;
+    }
+    if (LOCAL_HOSTNAME_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+        return true;
+    }
+    return false;
+};
+exports.isLocalLiteralHostname = isLocalLiteralHostname;
+/**
+ * Resolve hostname and check the resolved address against private/loopback/
+ * link-local ranges. Used inside `defaultInspirationFetcher` before issuing
+ * a fetch so users cannot point inspiration links at private network hosts
+ * via DNS rebinding-style indirection.
+ *
+ * @effect Performs a DNS lookup via dns.promises.lookup
+ */
+const isResolvedHostProtected = async (hostname) => {
+    if ((0, exports.isLocalLiteralHostname)(hostname))
+        return true;
+    try {
+        const lookup = await dns_1.default.promises.lookup(hostname, { all: true });
+        return lookup.some(({ address }) => {
+            if (address.includes(':')) {
+                if (PRIVATE_IPV6_PATTERNS.some((pattern) => pattern.test(address))) {
+                    return true;
+                }
+                return isIpv4MappedPrivateIpv6(address);
+            }
+            return PRIVATE_IPV4_PATTERNS.some((pattern) => pattern.test(address));
+        });
+    }
+    catch {
+        // Fail closed: a DNS resolution failure here must not allow the
+        // subsequent `fetch` to proceed unchecked, since a transient DNS error
+        // followed by a successful resolution to a private IP would bypass the
+        // SSRF guard. Treat lookup failures as protected.
+        return true;
+    }
+};
+exports.isResolvedHostProtected = isResolvedHostProtected;
+const isReferenceIntent = (windowText) => REFERENCE_INTENT_PATTERNS.some((pattern) => pattern.test(windowText));
+const isSeparateIntent = (text) => SEPARATE_INTENT_PATTERNS.some((pattern) => pattern.test(text));
+const normalizeRoleMatchUrl = (rawUrl) => {
+    const trimmed = rawUrl.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = new URL(trimmed);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return null;
+        }
+        parsed.hash = '';
+        return parsed.toString();
+    }
+    catch {
+        return null;
+    }
+};
+const findRoleForUrl = (url, sourceContext) => {
+    const normalizedCandidate = normalizeRoleMatchUrl(url);
+    if (!normalizedCandidate)
+        return undefined;
+    const roles = sourceContext?.artifact?.sourceRoles ?? [];
+    for (const entry of roles) {
+        if (normalizeRoleMatchUrl(entry.url) === normalizedCandidate) {
+            return entry.role;
+        }
+    }
+    return undefined;
+};
+const findArtifactLabelForUrl = (url, sourceContext) => {
+    for (const artifact of sourceContext?.sourceArtifacts ?? []) {
+        if (artifact.kind === 'urlText' && artifact.content.includes(url)) {
+            return artifact.label;
+        }
+    }
+    return undefined;
+};
+const windowAroundUrl = (text, url, span = 80) => {
+    const index = text.indexOf(url);
+    if (index < 0)
+        return '';
+    const start = Math.max(0, index - span);
+    const end = Math.min(text.length, index + url.length + span);
+    return text.slice(start, end);
+};
+/**
+ * Decide whether a URL discovered in the user message is design inspiration,
+ * source/content reference, or unrelated context. Combines local heuristics
+ * on the prompt with explicit role hints from `sourceContext.artifact`.
+ *
+ * `primary` role -> `reference` (treated as content source).
+ * `inspiration` role -> `inspiration`.
+ * `competitor` role -> `inspiration` (will merge as separate per-slot).
+ * Otherwise prompt phrasing wins; default is `inspiration` because the user
+ * provided the URL in a creation flow.
+ */
+const inferLinkIntent = (input) => {
+    const role = findRoleForUrl(input.url, input.sourceContext);
+    if (role === 'primary')
+        return 'reference';
+    if (role === 'inspiration' || role === 'competitor')
+        return 'inspiration';
+    const promptWindow = windowAroundUrl(input.prompt, input.url);
+    if (promptWindow && isReferenceIntent(promptWindow)) {
+        return 'reference';
+    }
+    return 'inspiration';
+};
+exports.inferLinkIntent = inferLinkIntent;
+/**
+ * Classify a deduped URL list against the prompt + sourceContext. Picks an
+ * overall mergeStrategy: when the user's message frames the links as
+ * alternatives/competitors/options, return `'separate'`; otherwise `'merge'`.
+ * Explicit `competitor` roles also force `'separate'`.
+ */
+const classifyInspirationLinks = (input) => {
+    const inspiration = [];
+    const reference = [];
+    let competitorOrAlternativeHint = false;
+    for (const url of input.urls.slice(0, MAX_INSPIRATION_LINKS)) {
+        const intent = (0, exports.inferLinkIntent)({
+            url,
+            prompt: input.prompt,
+            sourceContext: input.sourceContext,
+        });
+        const label = findArtifactLabelForUrl(url, input.sourceContext);
+        const entry = { url, intent, ...(label ? { label } : {}) };
+        if (intent === 'inspiration') {
+            inspiration.push(entry);
+            const role = findRoleForUrl(url, input.sourceContext);
+            if (role === 'competitor')
+                competitorOrAlternativeHint = true;
+        }
+        else if (intent === 'reference') {
+            reference.push(entry);
+        }
+    }
+    const promptHintsSeparate = isSeparateIntent(input.prompt);
+    const mergeStrategy = competitorOrAlternativeHint || promptHintsSeparate ? 'separate' : 'merge';
+    return { inspiration, reference, mergeStrategy };
+};
+exports.classifyInspirationLinks = classifyInspirationLinks;
+/**
+ * Default fetcher used by `extractInspirationDesignContext`. Performs a
+ * pre-fetch DNS check, applies a timeout, caps response size, validates the
+ * response content-type, and refuses non-HTML payloads. Treats remote page
+ * content as untrusted data — does not execute, evaluate, or inline its
+ * text as agent instructions.
+ *
+ * @effect Issues an outbound HTTPS/HTTP fetch and a DNS lookup. Aborts on
+ *         timeout, redirect limit, or oversize payloads.
+ */
+const defaultInspirationFetcher = async (rawUrl) => {
+    const validation = (0, exports.validateInspirationUrl)(rawUrl);
+    if (!validation.ok) {
+        return { ok: false, url: rawUrl, reason: validation.reason };
+    }
+    const url = validation.url;
+    const protectedTarget = await (0, exports.isResolvedHostProtected)(url.hostname);
+    if (protectedTarget) {
+        return {
+            ok: false,
+            url: validation.normalized,
+            reason: `Hostname '${url.hostname}' resolves to a protected target.`,
+        };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(validation.normalized, {
+            redirect: 'follow',
+            signal: controller.signal,
+            headers: {
+                accept: 'text/html,application/xhtml+xml',
+                'user-agent': 'rivet-inspiration-extractor/1.0 (+https://tryrivet.design)',
+            },
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                url: validation.normalized,
+                reason: `Request failed with status ${response.status}.`,
+            };
+        }
+        const finalUrlRaw = response.url || validation.normalized;
+        let finalUrlNormalized = finalUrlRaw;
+        try {
+            const finalParsed = new URL(finalUrlRaw);
+            if (await (0, exports.isResolvedHostProtected)(finalParsed.hostname)) {
+                return {
+                    ok: false,
+                    url: validation.normalized,
+                    reason: `Final hostname '${finalParsed.hostname}' resolves to a protected target after redirects.`,
+                };
+            }
+            finalUrlNormalized = finalParsed.toString();
+        }
+        catch {
+            // best-effort; fall back to the raw final URL string
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!/text\/html|application\/xhtml\+xml/i.test(contentType)) {
+            return {
+                ok: false,
+                url: validation.normalized,
+                reason: `Unsupported content type '${contentType || 'unknown'}'.`,
+            };
+        }
+        const reader = response.body?.getReader();
+        if (!reader) {
+            const text = await response.text();
+            if (text.length > MAX_BYTES) {
+                return {
+                    ok: false,
+                    url: validation.normalized,
+                    reason: 'Response exceeds size limit.',
+                };
+            }
+            return {
+                ok: true,
+                url: validation.normalized,
+                finalUrl: finalUrlNormalized,
+                html: text,
+                contentType,
+                byteLength: text.length,
+            };
+        }
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > MAX_BYTES) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // best effort
+                }
+                return {
+                    ok: false,
+                    url: validation.normalized,
+                    reason: 'Response exceeds size limit.',
+                };
+            }
+            chunks.push(value);
+        }
+        const html = new TextDecoder().decode(Buffer.concat(chunks.map((c) => Buffer.from(c))));
+        return {
+            ok: true,
+            url: validation.normalized,
+            finalUrl: finalUrlNormalized,
+            html,
+            contentType,
+            byteLength: total,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'fetch failed';
+        return { ok: false, url: validation.normalized, reason: message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+exports.defaultInspirationFetcher = defaultInspirationFetcher;
+const decodeHtmlEntities = (value) => value
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+/**
+ * Discover absolute stylesheet URLs from `<link rel="stylesheet">` tags.
+ * Resolves relative `href` values against `baseUrl`, deduplicates, and
+ * returns at most `MAX_LINKED_STYLESHEETS` entries so the caller's fetch
+ * budget stays bounded. Only HTTP/HTTPS targets are returned — `data:`,
+ * `blob:`, and other schemes are dropped before any safety checks run.
+ */
+const discoverLinkedStylesheetUrls = (html, baseUrl) => {
+    const collected = new Set();
+    const tagRegex = /<link\b[^>]*>/gi;
+    let tag;
+    while ((tag = tagRegex.exec(html)) !== null) {
+        const fragment = tag[0];
+        if (!/\brel\s*=\s*["'][^"']*\bstylesheet\b/i.test(fragment))
+            continue;
+        const hrefMatch = fragment.match(/\bhref\s*=\s*["']([^"']+)["']/i);
+        if (!hrefMatch)
+            continue;
+        const rawHref = decodeHtmlEntities(hrefMatch[1]).trim();
+        if (!rawHref)
+            continue;
+        try {
+            const resolved = new URL(rawHref, baseUrl);
+            if (resolved.protocol !== 'http:' && resolved.protocol !== 'https:') {
+                continue;
+            }
+            resolved.hash = '';
+            collected.add(resolved.toString());
+        }
+        catch {
+            // ignore malformed hrefs; skipping is the safest outcome
+        }
+        if (collected.size >= MAX_LINKED_STYLESHEETS)
+            break;
+    }
+    return Array.from(collected).slice(0, MAX_LINKED_STYLESHEETS);
+};
+exports.discoverLinkedStylesheetUrls = discoverLinkedStylesheetUrls;
+/**
+ * Default linked-stylesheet fetcher. Mirrors `defaultInspirationFetcher`'s
+ * pre-fetch DNS check, redirect-aware re-check, timeout, and byte cap, but
+ * accepts `text/css` (or `text/plain`) content and uses tighter per-file
+ * limits. Returned `css` is treated as untrusted data — callers must not
+ * evaluate it or inline it as agent instructions.
+ *
+ * @effect Issues an outbound HTTPS/HTTP fetch and a DNS lookup. Aborts on
+ *         timeout or oversize payloads.
+ */
+const defaultLinkedCssFetcher = async (rawUrl) => {
+    const validation = (0, exports.validateInspirationUrl)(rawUrl);
+    if (!validation.ok) {
+        return { ok: false, url: rawUrl, reason: validation.reason };
+    }
+    const url = validation.url;
+    const protectedTarget = await (0, exports.isResolvedHostProtected)(url.hostname);
+    if (protectedTarget) {
+        return {
+            ok: false,
+            url: validation.normalized,
+            reason: `Hostname '${url.hostname}' resolves to a protected target.`,
+        };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), LINKED_CSS_FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(validation.normalized, {
+            redirect: 'follow',
+            signal: controller.signal,
+            headers: {
+                accept: 'text/css,*/*;q=0.1',
+                'user-agent': 'rivet-inspiration-extractor/1.0 (+https://tryrivet.design)',
+            },
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                url: validation.normalized,
+                reason: `CSS request failed with status ${response.status}.`,
+            };
+        }
+        const finalUrlRaw = response.url || validation.normalized;
+        let finalUrlNormalized = finalUrlRaw;
+        try {
+            const finalParsed = new URL(finalUrlRaw);
+            if (await (0, exports.isResolvedHostProtected)(finalParsed.hostname)) {
+                return {
+                    ok: false,
+                    url: validation.normalized,
+                    reason: `Final CSS hostname '${finalParsed.hostname}' resolves to a protected target after redirects.`,
+                };
+            }
+            finalUrlNormalized = finalParsed.toString();
+        }
+        catch {
+            // best-effort; fall back to the raw final URL string
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!/text\/css|text\/plain/i.test(contentType)) {
+            return {
+                ok: false,
+                url: validation.normalized,
+                reason: `Unsupported CSS content type '${contentType || 'unknown'}'.`,
+            };
+        }
+        const reader = response.body?.getReader();
+        if (!reader) {
+            const text = await response.text();
+            if (text.length > LINKED_CSS_MAX_BYTES_PER_FILE) {
+                return {
+                    ok: false,
+                    url: validation.normalized,
+                    reason: 'CSS response exceeds size limit.',
+                };
+            }
+            return {
+                ok: true,
+                url: validation.normalized,
+                finalUrl: finalUrlNormalized,
+                css: text,
+                byteLength: text.length,
+            };
+        }
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > LINKED_CSS_MAX_BYTES_PER_FILE) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // best effort
+                }
+                return {
+                    ok: false,
+                    url: validation.normalized,
+                    reason: 'CSS response exceeds size limit.',
+                };
+            }
+            chunks.push(value);
+        }
+        const css = new TextDecoder().decode(Buffer.concat(chunks.map((c) => Buffer.from(c))));
+        return {
+            ok: true,
+            url: validation.normalized,
+            finalUrl: finalUrlNormalized,
+            css,
+            byteLength: total,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'fetch failed';
+        return { ok: false, url: validation.normalized, reason: message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+exports.defaultLinkedCssFetcher = defaultLinkedCssFetcher;
+/**
+ * Fetch up to `MAX_LINKED_STYLESHEETS` linked stylesheets discovered in
+ * the fetched HTML, honoring a cumulative byte budget. Returns the
+ * concatenated CSS text and a count of how many sheets contributed.
+ * The returned CSS is intentionally ephemeral — callers MUST NOT persist
+ * or forward it to telemetry; only derived signal extractions may be
+ * stored.
+ */
+const fetchLinkedStylesheets = async (html, baseUrl, fetcher) => {
+    const urls = (0, exports.discoverLinkedStylesheetUrls)(html, baseUrl);
+    if (urls.length === 0) {
+        return {
+            css: '',
+            fetchedCount: 0,
+            attemptedCount: 0,
+            byteTotal: 0,
+            skippedReasons: [],
+        };
+    }
+    const parts = [];
+    const skippedReasons = [];
+    let byteTotal = 0;
+    let fetchedCount = 0;
+    let attemptedCount = 0;
+    for (const url of urls) {
+        attemptedCount += 1;
+        if (byteTotal >= LINKED_CSS_MAX_TOTAL_BYTES) {
+            skippedReasons.push('total_budget_exceeded');
+            break;
+        }
+        const result = await fetcher(url);
+        if (!result.ok) {
+            skippedReasons.push(result.reason);
+            continue;
+        }
+        const remaining = LINKED_CSS_MAX_TOTAL_BYTES - byteTotal;
+        const css = result.css.length > remaining ? result.css.slice(0, remaining) : result.css;
+        parts.push(css);
+        byteTotal += css.length;
+        fetchedCount += 1;
+    }
+    return {
+        css: parts.join('\n'),
+        fetchedCount,
+        attemptedCount,
+        byteTotal,
+        skippedReasons,
+    };
+};
+exports.fetchLinkedStylesheets = fetchLinkedStylesheets;
+const stripTags = (html) => decodeHtmlEntities(html.replace(/<[^>]*>/g, ' '));
+const extractMetaContent = (html, name) => {
+    const namePattern = new RegExp(`<meta\\b[^>]*\\b(?:name|property)\\s*=\\s*["']${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["'][^>]*\\bcontent\\s*=\\s*["']([^"']+)["']`, 'i');
+    const reversedPattern = new RegExp(`<meta\\b[^>]*\\bcontent\\s*=\\s*["']([^"']+)["'][^>]*\\b(?:name|property)\\s*=\\s*["']${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']`, 'i');
+    const match = html.match(namePattern) ?? html.match(reversedPattern);
+    return match ? decodeHtmlEntities(match[1]) : undefined;
+};
+const extractTitle = (html) => {
+    const match = html.match(/<title\b[^>]*>([\s\S]*?)<\/title>/i);
+    if (!match)
+        return undefined;
+    const cleaned = trimWhitespace(decodeHtmlEntities(match[1]));
+    return cleaned || undefined;
+};
+const findFontFamilies = (block) => {
+    const families = [];
+    // Capture the entire value up to the next `;`, `}`, or newline so quoted
+    // family names (`'Inter'`, `"Space Grotesk"`) are kept intact. The
+    // per-token split below strips surrounding quotes.
+    const regex = /font-family\s*:\s*([^;}\n]+)/gi;
+    let match;
+    while ((match = regex.exec(block)) !== null) {
+        const stack = match[1]
+            .split(',')
+            .map((item) => trimWhitespace(item.replace(/^["']|["']$/g, '')))
+            .filter(Boolean);
+        families.push(...stack);
+    }
+    return families;
+};
+const GOOGLE_FONTS_HOST_PATTERN = /^fonts\.googleapis\.com$/i;
+const normalizeFontFamilyToken = (value) => trimWhitespace(value.replace(/^["']|["']$/g, ''));
+/**
+ * Parse Google Fonts families from `<link rel="stylesheet" href="...">`
+ * entries in the fetched HTML. Captures only family names; query details
+ * and raw URL payloads are intentionally discarded.
+ */
+const extractGoogleFontFamilies = (html) => {
+    const families = [];
+    const tagRegex = /<link\b[^>]*>/gi;
+    let tagMatch;
+    while ((tagMatch = tagRegex.exec(html)) !== null) {
+        const tag = tagMatch[0];
+        if (!/\brel\s*=\s*["'][^"']*\bstylesheet\b/i.test(tag))
+            continue;
+        const hrefMatch = tag.match(/\bhref\s*=\s*["']([^"']+)["']/i);
+        if (!hrefMatch)
+            continue;
+        const href = decodeHtmlEntities(hrefMatch[1]).trim();
+        if (!href)
+            continue;
+        let parsed;
+        try {
+            parsed = new URL(href);
+        }
+        catch {
+            continue;
+        }
+        if (!GOOGLE_FONTS_HOST_PATTERN.test(parsed.hostname))
+            continue;
+        for (const familyParam of parsed.searchParams.getAll('family')) {
+            const normalized = trimWhitespace(decodeURIComponent(familyParam).split(':')[0].replace(/\+/g, ' '));
+            if (normalized)
+                families.push(normalized);
+        }
+    }
+    return dedupe(families).slice(0, MAX_GOOGLE_FONT_FAMILIES);
+};
+const parseSrcHosts = (srcValue) => {
+    if (!srcValue)
+        return [];
+    const hosts = [];
+    const urlRegex = /url\(([^)]+)\)/gi;
+    let match;
+    while ((match = urlRegex.exec(srcValue)) !== null) {
+        const raw = trimWhitespace(match[1].replace(/^["']|["']$/g, ''));
+        if (!raw)
+            continue;
+        try {
+            const parsed = new URL(raw);
+            hosts.push(parsed.hostname.toLowerCase());
+        }
+        catch {
+            if (/^\/|^\.\.?\//.test(raw))
+                hosts.push('relative');
+        }
+    }
+    return dedupe(hosts);
+};
+/**
+ * Extract structured `@font-face` evidence without persisting raw CSS text.
+ */
+const extractFontFaceEvidence = (css) => {
+    const evidence = [];
+    const regex = /@font-face\s*\{([\s\S]*?)\}/gi;
+    let match;
+    while ((match = regex.exec(css)) !== null) {
+        const body = match[1];
+        const rawFamily = getCssDeclaration(body, 'font-family');
+        if (!rawFamily)
+            continue;
+        const fontFamily = normalizeFontFamilyToken(rawFamily);
+        if (!fontFamily)
+            continue;
+        evidence.push({
+            fontFamily,
+            ...(getCssDeclaration(body, 'font-weight')
+                ? { fontWeight: getCssDeclaration(body, 'font-weight') }
+                : {}),
+            ...(getCssDeclaration(body, 'font-style')
+                ? { fontStyle: getCssDeclaration(body, 'font-style') }
+                : {}),
+            ...(getCssDeclaration(body, 'font-display')
+                ? { fontDisplay: getCssDeclaration(body, 'font-display') }
+                : {}),
+            srcHosts: parseSrcHosts(getCssDeclaration(body, 'src')),
+        });
+        if (evidence.length >= MAX_FONT_FACE_EVIDENCE)
+            break;
+    }
+    return evidence;
+};
+const extractStyleBlocks = (html) => {
+    const matches = html.match(/<style\b[^>]*>([\s\S]*?)<\/style>/gi) ?? [];
+    return matches.map((block) => block.replace(/<\/?style[^>]*>/gi, '')).join('\n');
+};
+const extractInlineStyles = (html) => {
+    const matches = html.match(/style\s*=\s*["']([^"']+)["']/gi) ?? [];
+    return matches.join('\n');
+};
+const HEX_COLOR_PATTERN = /#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})\b/gi;
+const RGB_COLOR_PATTERN = /\brgba?\(\s*\d+\s*,\s*\d+\s*,\s*\d+(?:\s*,\s*[0-9.]+)?\s*\)/gi;
+const collectColors = (block) => {
+    const colors = [];
+    for (const match of block.match(HEX_COLOR_PATTERN) ?? []) {
+        colors.push(match.toLowerCase());
+    }
+    for (const match of block.match(RGB_COLOR_PATTERN) ?? []) {
+        colors.push(match.toLowerCase());
+    }
+    const namedRegex = /\b(?:color|background(?:-color)?|border(?:-color)?)\s*:\s*([a-z]+)/gi;
+    let namedMatch;
+    while ((namedMatch = namedRegex.exec(block)) !== null) {
+        const value = namedMatch[1].toLowerCase();
+        if (CSS_NAMED_COLORS.has(value))
+            colors.push(value);
+    }
+    return colors;
+};
+const collectWeights = (block) => {
+    const weights = [];
+    const regex = /font-weight\s*:\s*([^;}\n"']+)/gi;
+    let match;
+    while ((match = regex.exec(block)) !== null) {
+        weights.push(trimWhitespace(match[1]));
+    }
+    return weights;
+};
+const collectScaleSamples = (block) => {
+    const samples = [];
+    const regex = /font-size\s*:\s*([^;}\n"']+)/gi;
+    let match;
+    while ((match = regex.exec(block)) !== null) {
+        samples.push(trimWhitespace(match[1]));
+    }
+    return samples;
+};
+const detectSections = (html) => {
+    const sections = [];
+    if (/<header\b/i.test(html))
+        sections.push('Header / top bar');
+    if (/<nav\b/i.test(html))
+        sections.push('Primary navigation');
+    if (/class=("|')[^"']*\bhero\b/i.test(html))
+        sections.push('Hero section');
+    if (/class=("|')[^"']*\bfeatures?\b/i.test(html))
+        sections.push('Feature blocks');
+    if (/class=("|')[^"']*\bpricing\b/i.test(html))
+        sections.push('Pricing layout');
+    if (/class=("|')[^"']*\btestimonial\b/i.test(html))
+        sections.push('Social proof / testimonials');
+    if (/class=("|')[^"']*\bcta\b/i.test(html))
+        sections.push('Call-to-action band');
+    if (/<footer\b/i.test(html))
+        sections.push('Footer');
+    return dedupe(sections);
+};
+const detectStructureNotes = (html) => {
+    const notes = [];
+    if (/class=("|')[^"']*\b(?:container|max-w-)/i.test(html)) {
+        notes.push('Centered max-width container pattern');
+    }
+    if (/class=("|')[^"']*\b(?:grid|columns)\b/i.test(html)) {
+        notes.push('Multi-column grid sections');
+    }
+    if (/class=("|')[^"']*\b(?:flex|row|col)\b/i.test(html)) {
+        notes.push('Flexbox-driven horizontal sections');
+    }
+    if (/class=("|')[^"']*\b(?:sticky|fixed)\b/i.test(html)) {
+        notes.push('Sticky or fixed elements (likely top nav)');
+    }
+    if (/class=("|')[^"']*\b(?:dark|bg-black|bg-gray-9)\b/i.test(html)) {
+        notes.push('Dark surface usage in at least one section');
+    }
+    return dedupe(notes);
+};
+const detectComponents = (html) => dedupe(COMPONENT_HINTS.filter(({ keyword }) => keyword.test(html)).map(({ label }) => label));
+const detectMotionCues = (html) => dedupe(MOTION_HINTS.filter(({ keyword }) => keyword.test(html)).map(({ label }) => label));
+const detectIconography = (html) => dedupe(ICONOGRAPHY_HINTS.filter(({ keyword }) => keyword.test(html)).map(({ label }) => label));
+const HEX_COLOR_TEST = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB_COLOR_TEST = /^rgba?\(\s*\d+\s*,\s*\d+\s*,\s*\d+(?:\s*,\s*[0-9.]+)?\s*\)$/i;
+/**
+ * Strip CSS variables, `!important`, comments, fallback chains, and quotes
+ * from a single property value so we can keep just the primary token.
+ */
+const cleanCssValue = (raw) => trimWhitespace(raw
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/!important/gi, '')
+    .replace(/^["']|["']$/g, ''));
+/**
+ * Normalize a CSS color expression to a comparable lowercase form.
+ * Returns `undefined` for values we don't recognize as a single color
+ * literal (e.g., `var(--x)`, `linear-gradient(...)`).
+ */
+const normalizeCssColor = (raw) => {
+    const cleaned = cleanCssValue(raw).split(/\s+/)[0]?.replace(/[,;]$/, '');
+    if (!cleaned)
+        return undefined;
+    const lower = cleaned.toLowerCase();
+    if (HEX_COLOR_TEST.test(lower))
+        return lower;
+    if (RGB_COLOR_TEST.test(lower))
+        return lower;
+    if (CSS_NAMED_COLORS.has(lower))
+        return lower;
+    return undefined;
+};
+/**
+ * Light-weight CSS rule splitter. Returns top-level `selector { body }`
+ * pairs. Skips at-rule wrappers (`@media`, `@supports`, etc.) by walking
+ * the brace stream and only emitting rules whose selector does not start
+ * with `@`. Nested-inside-at-rule rules are emitted with the at-rule
+ * stripped — good enough for static token extraction without pulling in a
+ * full CSS parser.
+ */
+const extractRuleBlocks = (css) => {
+    const blocks = [];
+    const buffer = css.replace(/\/\*[\s\S]*?\*\//g, '');
+    let depth = 0;
+    let cursor = 0;
+    let selectorStart = 0;
+    for (let i = 0; i < buffer.length; i += 1) {
+        const ch = buffer[i];
+        if (ch === '{') {
+            if (depth === 0) {
+                const selector = trimWhitespace(buffer.slice(selectorStart, i));
+                cursor = i + 1;
+                if (selector.startsWith('@')) {
+                    // Skip at-rule header; iterate into its body so nested rules
+                    // still surface (treat the at-rule like a transparent wrapper).
+                    depth = 1;
+                    selectorStart = cursor;
+                    continue;
+                }
+                depth = 1;
+                // store selector + body once we hit the matching closing brace
+                const startBody = cursor;
+                let nested = 0;
+                let j = i + 1;
+                for (; j < buffer.length; j += 1) {
+                    const cj = buffer[j];
+                    if (cj === '{')
+                        nested += 1;
+                    else if (cj === '}') {
+                        if (nested === 0)
+                            break;
+                        nested -= 1;
+                    }
+                }
+                const body = buffer.slice(startBody, j);
+                if (selector)
+                    blocks.push({ selector, body });
+                i = j;
+                depth = 0;
+                selectorStart = j + 1;
+                continue;
+            }
+            depth += 1;
+        }
+        else if (ch === '}') {
+            depth = Math.max(0, depth - 1);
+            if (depth === 0)
+                selectorStart = i + 1;
+        }
+    }
+    return blocks;
+};
+const getCssDeclaration = (body, property) => {
+    const escaped = property.replace(/[-\\^$*+?.()|[\]{}]/g, '\\$&');
+    const regex = new RegExp(`(?:^|;)\\s*${escaped}\\s*:\\s*([^;]+?)(?:;|$)`, 'i');
+    const match = body.match(regex);
+    if (!match)
+        return undefined;
+    return cleanCssValue(match[1]);
+};
+const collectDeclarations = (css, property) => {
+    const escaped = property.replace(/[-\\^$*+?.()|[\]{}]/g, '\\$&');
+    const regex = new RegExp(`${escaped}\\s*:\\s*([^;}\\n]+)`, 'gi');
+    const values = [];
+    let match;
+    while ((match = regex.exec(css)) !== null) {
+        const value = cleanCssValue(match[1]);
+        if (value)
+            values.push(value);
+    }
+    return values;
+};
+const PIXEL_PARSE_REGEX = /^(-?\d*\.?\d+)(px|rem|em)?$/i;
+const parseDimensionPixels = (value) => {
+    const trimmed = value.trim().split(/\s+/)[0]?.toLowerCase();
+    if (!trimmed)
+        return undefined;
+    const match = trimmed.match(PIXEL_PARSE_REGEX);
+    if (!match)
+        return undefined;
+    const num = parseFloat(match[1]);
+    if (Number.isNaN(num))
+        return undefined;
+    const unit = match[2] ?? '';
+    if (unit === 'rem' || unit === 'em')
+        return num * 16;
+    return num;
+};
+/**
+ * Bucket a list of dimension strings into sm/md/lg by ascending pixel
+ * value. Preserves the original raw strings (so `0.5rem` stays as
+ * `0.5rem` instead of becoming `8px`). Returns `observed` containing the
+ * deduped raw values sorted by computed pixel size so callers can present
+ * a clean ladder without re-sorting.
+ */
+const bucketDimensions = (rawValues) => {
+    const parsed = rawValues
+        .map((raw) => ({ raw, px: parseDimensionPixels(raw) }))
+        .filter((entry) => entry.px !== undefined)
+        .filter((entry) => entry.px >= 0)
+        .sort((a, b) => a.px - b.px);
+    const deduped = [];
+    const seen = new Set();
+    for (const entry of parsed) {
+        if (seen.has(entry.px))
+            continue;
+        seen.add(entry.px);
+        deduped.push(entry);
+    }
+    const observed = deduped.map((entry) => entry.raw).slice(0, MAX_SPACING_VALUES);
+    if (deduped.length === 0)
+        return { observed: [] };
+    const sm = deduped[0].raw;
+    const lg = deduped[deduped.length - 1].raw;
+    const md = deduped[Math.floor(deduped.length / 2)].raw;
+    return {
+        sm,
+        md: md !== sm && md !== lg ? md : undefined,
+        lg: lg !== sm ? lg : undefined,
+        observed,
+    };
+};
+const SPACING_PROPERTIES = [
+    'padding',
+    'padding-top',
+    'padding-right',
+    'padding-bottom',
+    'padding-left',
+    'padding-inline',
+    'padding-block',
+    'margin',
+    'margin-top',
+    'margin-right',
+    'margin-bottom',
+    'margin-left',
+    'margin-inline',
+    'margin-block',
+    'gap',
+    'row-gap',
+    'column-gap',
+];
+const extractSpacingTokens = (css) => {
+    const values = [];
+    for (const property of SPACING_PROPERTIES) {
+        for (const raw of collectDeclarations(css, property)) {
+            for (const piece of raw.split(/\s+/)) {
+                const cleaned = piece.replace(/[,;]/g, '').trim();
+                if (cleaned)
+                    values.push(cleaned);
+            }
+        }
+    }
+    return bucketDimensions(values);
+};
+const extractRoundedTokens = (css) => {
+    const values = [];
+    for (const raw of collectDeclarations(css, 'border-radius')) {
+        for (const piece of raw.split(/\s+/)) {
+            const cleaned = piece.replace(/[,;]/g, '').trim();
+            if (cleaned)
+                values.push(cleaned);
+        }
+    }
+    const bucketed = bucketDimensions(values);
+    return {
+        ...bucketed,
+        observed: bucketed.observed.slice(0, MAX_ROUNDED_VALUES),
+    };
+};
+const extractShadowDeclarations = (css) => {
+    const values = collectDeclarations(css, 'box-shadow').filter((value) => value.toLowerCase() !== 'none');
+    return dedupe(values).slice(0, MAX_SHADOWS);
+};
+const extractTransitionDeclarations = (css) => {
+    const values = [
+        ...collectDeclarations(css, 'transition'),
+        ...collectDeclarations(css, 'transition-property'),
+        ...collectDeclarations(css, 'transition-duration'),
+        ...collectDeclarations(css, 'transition-timing-function'),
+        ...collectDeclarations(css, 'transition-delay'),
+    ].filter((value) => value.toLowerCase() !== 'none');
+    return dedupe(values).slice(0, MAX_TRANSITIONS);
+};
+const extractBreakpointConditions = (css) => {
+    const out = [];
+    const regex = /@media\b([^{]+)\{/gi;
+    let match;
+    while ((match = regex.exec(css)) !== null) {
+        const condition = trimWhitespace(match[1]);
+        if (condition)
+            out.push(condition);
+    }
+    return dedupe(out).slice(0, MAX_BREAKPOINTS);
+};
+const TYPOGRAPHY_DISPLAY_SELECTOR_HINTS = [
+    /(?:^|[,\s])h1\b/i,
+    /(?:^|[,\s])h2\b/i,
+    /\bdisplay\b/i,
+    /\bhero(?:[-_].*)?\b/i,
+    /\bheadline\b/i,
+    /\btitle(?:[-_].*)?\b/i,
+];
+const TYPOGRAPHY_BODY_SELECTOR_HINTS = [
+    /(?:^|[,\s])body\b/i,
+    /(?:^|[,\s])p\b/i,
+    /\btext-body\b/i,
+    /\bparagraph\b/i,
+];
+const extractTypographyTokenFromBody = (body) => {
+    const families = findFontFamilies(body);
+    const fontFamily = families.length > 0 ? families[0] : undefined;
+    return {
+        fontFamily,
+        fontSize: getCssDeclaration(body, 'font-size'),
+        fontWeight: getCssDeclaration(body, 'font-weight'),
+        lineHeight: getCssDeclaration(body, 'line-height'),
+        letterSpacing: getCssDeclaration(body, 'letter-spacing'),
+        fontVariationSettings: getCssDeclaration(body, 'font-variation-settings'),
+    };
+};
+const hasAnyTypographyMetric = (token) => Boolean(token.fontFamily ||
+    token.fontSize ||
+    token.fontWeight ||
+    token.lineHeight ||
+    token.letterSpacing ||
+    token.fontVariationSettings);
+const extractTypographyTokens = (css) => {
+    const blocks = extractRuleBlocks(css);
+    const tokens = {};
+    for (const { selector, body } of blocks) {
+        const normalized = selector.toLowerCase();
+        if (!tokens.display &&
+            TYPOGRAPHY_DISPLAY_SELECTOR_HINTS.some((re) => re.test(normalized))) {
+            const token = extractTypographyTokenFromBody(body);
+            if (hasAnyTypographyMetric(token))
+                tokens.display = token;
+        }
+        if (!tokens.body &&
+            TYPOGRAPHY_BODY_SELECTOR_HINTS.some((re) => re.test(normalized))) {
+            const token = extractTypographyTokenFromBody(body);
+            if (hasAnyTypographyMetric(token))
+                tokens.body = token;
+        }
+        if (tokens.display && tokens.body)
+            break;
+    }
+    return tokens;
+};
+const COMPONENT_SELECTOR_HINTS = [
+    { pattern: /\b(?:btn-primary|button-primary|primary-button)\b/i, name: 'button-primary' },
+    {
+        pattern: /\b(?:btn-secondary|button-secondary|secondary-button)\b/i,
+        name: 'button-secondary',
+    },
+    { pattern: /\bcard\b/i, name: 'card' },
+    { pattern: /(?:^|[,\s])input\b/i, name: 'input' },
+    { pattern: /\b(?:badge|chip)\b/i, name: 'badge' },
+    { pattern: /\b(?:nav-primary|navbar|topnav)\b/i, name: 'navigation' },
+];
+const extractComponentTokenDetails = (css) => {
+    const blocks = extractRuleBlocks(css);
+    const accum = new Map();
+    for (const { selector, body } of blocks) {
+        for (const { pattern, name } of COMPONENT_SELECTOR_HINTS) {
+            if (!pattern.test(selector))
+                continue;
+            const existing = accum.get(name) ?? { name };
+            if (!existing.backgroundColor) {
+                const value = getCssDeclaration(body, 'background-color') ??
+                    getCssDeclaration(body, 'background');
+                if (value)
+                    existing.backgroundColor = value;
+            }
+            if (!existing.textColor) {
+                const value = getCssDeclaration(body, 'color');
+                if (value)
+                    existing.textColor = value;
+            }
+            if (!existing.borderColor) {
+                const value = getCssDeclaration(body, 'border-color') ??
+                    getCssDeclaration(body, 'border');
+                if (value)
+                    existing.borderColor = value;
+            }
+            if (!existing.borderRadius) {
+                const value = getCssDeclaration(body, 'border-radius');
+                if (value)
+                    existing.borderRadius = value;
+            }
+            if (!existing.padding) {
+                const value = getCssDeclaration(body, 'padding');
+                if (value)
+                    existing.padding = value;
+            }
+            if (!existing.boxShadow) {
+                const value = getCssDeclaration(body, 'box-shadow');
+                if (value && value.toLowerCase() !== 'none')
+                    existing.boxShadow = value;
+            }
+            accum.set(name, existing);
+        }
+    }
+    return Array.from(accum.values()).slice(0, MAX_COMPONENT_DETAILS);
+};
+// D8: Role-aware palette extraction.
+// Class-keyed hints (existing) anchor `primary` to explicit primary-CTA
+// classes. Element/attribute hints (added) anchor it to the visible CSS role
+// of CTA elements even when no `.primary`/`.btn-primary` class is in play —
+// many real pages style a bare `button` or `a[class*=cta]` directly and would
+// otherwise fall through to the frequency-rank fallback (now removed) and
+// silently promote a neutral background like `#f7f7f7` to `colors.primary`.
+const PRIMARY_SELECTOR_HINTS = [
+    /\b(?:btn-primary|button-primary|primary-button|primary-cta)\b/i,
+    /\b(?:cta-primary|action-primary)\b/i,
+    /(?:^|[\s,>+~])\.primary\b/i,
+    // Element-anchored hints. Match selectors whose final compound is a
+    // `button` element, a `[role="button"]` ARIA-button anchor, a generic
+    // `.btn` class, or an anchor carrying a `cta`/`primary` substring in any
+    // class attribute. These cover the realistic patterns where the brand
+    // color lives on a bare element rule rather than a semantic class name.
+    /(?:^|[\s,>+~])button(?:[.:#[\s,]|$)/i,
+    /(?:^|[\s,>+~])\.btn(?:[.:#[\s,]|$)/i,
+    /\[role\s*=\s*("|')button\1\]/i,
+    /(?:^|[\s,>+~])a\[class\*?=("|')[^"']*(?:cta|primary)/i,
+];
+const SURFACE_SELECTOR_HINTS = [
+    /\bcard\b/i,
+    /\bpanel\b/i,
+    /\bsurface\b/i,
+    /\bsheet\b/i,
+];
+const MUTED_SELECTOR_HINTS = [
+    /\bmuted\b/i,
+    /\bsubtle\b/i,
+    /\bsecondary-text\b/i,
+    /\btext-secondary\b/i,
+    /\btext-muted\b/i,
+];
+const NEUTRAL_HEX_TEST = /^#(?:0{3,8}|f{3,8}|([0-9a-f])\1{2,7})$/i;
+const isLikelyNeutralColor = (value) => {
+    if (NEUTRAL_HEX_TEST.test(value))
+        return true;
+    const named = value.toLowerCase();
+    return named === 'black' || named === 'white' || named === 'gray' || named === 'grey';
+};
+const inferColorRoles = (css, _palette) => {
+    const blocks = extractRuleBlocks(css);
+    const roles = {};
+    for (const { selector, body } of blocks) {
+        const normalized = selector.toLowerCase();
+        const isRootScope = /(?:^|[,\s])(?:body|html|:root)\b/.test(normalized);
+        if (isRootScope) {
+            if (!roles.background) {
+                const value = getCssDeclaration(body, 'background-color') ??
+                    getCssDeclaration(body, 'background');
+                if (value) {
+                    const color = normalizeCssColor(value);
+                    if (color)
+                        roles.background = color;
+                }
+            }
+            if (!roles.text) {
+                const value = getCssDeclaration(body, 'color');
+                if (value) {
+                    const color = normalizeCssColor(value);
+                    if (color)
+                        roles.text = color;
+                }
+            }
+        }
+        if (PRIMARY_SELECTOR_HINTS.some((re) => re.test(normalized))) {
+            if (!roles.primary) {
+                const value = getCssDeclaration(body, 'background-color') ??
+                    getCssDeclaration(body, 'background');
+                if (value) {
+                    const color = normalizeCssColor(value);
+                    if (color)
+                        roles.primary = color;
+                }
+            }
+            if (!roles.onPrimary) {
+                const value = getCssDeclaration(body, 'color');
+                if (value) {
+                    const color = normalizeCssColor(value);
+                    if (color)
+                        roles.onPrimary = color;
+                }
+            }
+        }
+        if (!roles.surface &&
+            SURFACE_SELECTOR_HINTS.some((re) => re.test(normalized))) {
+            const value = getCssDeclaration(body, 'background-color') ??
+                getCssDeclaration(body, 'background');
+            if (value) {
+                const color = normalizeCssColor(value);
+                if (color)
+                    roles.surface = color;
+            }
+        }
+        if (!roles.muted &&
+            MUTED_SELECTOR_HINTS.some((re) => re.test(normalized))) {
+            const value = getCssDeclaration(body, 'color');
+            if (value) {
+                const color = normalizeCssColor(value);
+                if (color)
+                    roles.muted = color;
+            }
+        }
+        if (!roles.border) {
+            const value = getCssDeclaration(body, 'border-color') ??
+                getCssDeclaration(body, 'border');
+            if (value) {
+                const color = normalizeCssColor(value);
+                if (color)
+                    roles.border = color;
+            }
+        }
+    }
+    // D8: No frequency-rank fallback. When no role-anchored color exists,
+    // `roles.primary` stays undefined and the synthesized DESIGN.md surfaces
+    // the gap via the "colors.primary was not observed directly" caveat. This
+    // is intentional: a neutral promoted by frequency (e.g. `#f7f7f7` from
+    // card backgrounds) was the exact failure mode that motivated this
+    // change. Surfacing the gap is more useful than guessing.
+    return roles;
+};
+const clampPercentage = (value) => Math.max(0, Math.min(100, Math.round(value)));
+const hasTypographyEvidence = (tokens, headingFamilies, bodyFamilies, scaleSamples) => Boolean(tokens.display ||
+    tokens.body ||
+    headingFamilies.length > 0 ||
+    bodyFamilies.length > 0 ||
+    scaleSamples.length > 0);
+const hasComponentTokenReferenceEvidence = (input) => {
+    const hasColorToken = Boolean(input.colorRoles.primary ||
+        input.colorRoles.onPrimary ||
+        input.colorRoles.background ||
+        input.colorRoles.surface ||
+        input.colorRoles.text ||
+        input.colorRoles.muted ||
+        input.colorRoles.border);
+    const hasTypographyToken = Boolean(input.typographyTokens.body || input.typographyTokens.display);
+    const hasRoundedToken = Boolean(input.rounded.sm || input.rounded.md || input.rounded.lg);
+    return input.componentDetails.some((detail) => Boolean((detail.backgroundColor && hasColorToken) ||
+        (detail.textColor && hasColorToken) ||
+        (detail.borderColor && hasColorToken) ||
+        (detail.borderRadius && hasRoundedToken) ||
+        (detail.padding && hasTypographyToken)));
+};
+/**
+ * Fidelity-weighted coverage score for DESIGN.md readiness.
+ * Major token gaps (colors.primary, typography tokens, component token refs)
+ * incur heavy penalties. Sparse canonical-section evidence incurs additional
+ * penalties so "lots of random CSS" does not look high-confidence.
+ */
+const computeDesignFidelityScore = (input) => {
+    let score = 100;
+    if (!input.colorRoles.primary)
+        score -= 30;
+    const typographyTokenCount = (input.typographyTokens.display ? 1 : 0) +
+        (input.typographyTokens.body ? 1 : 0);
+    if (typographyTokenCount === 0)
+        score -= 30;
+    else if (typographyTokenCount === 1)
+        score -= 15;
+    if (!hasComponentTokenReferenceEvidence({
+        colorRoles: input.colorRoles,
+        typographyTokens: input.typographyTokens,
+        rounded: input.rounded,
+        componentDetails: input.componentDetails,
+    })) {
+        score -= 25;
+    }
+    const colorsSectionCovered = input.colors.length > 0 ||
+        Object.values(input.colorRoles).filter(Boolean).length > 0;
+    const typographySectionCovered = hasTypographyEvidence(input.typographyTokens, input.headingFamilies, input.bodyFamilies, input.scaleSamples);
+    const layoutSectionCovered = input.sections.length > 0 || input.structureNotes.length > 0;
+    const elevationSectionCovered = input.shadows.length > 0 || input.transitions.length > 0;
+    const shapesSectionCovered = input.rounded.observed.length > 0;
+    const componentsSectionCovered = input.components.length > 0 || input.componentDetails.length > 0;
+    const motionCovered = input.motionCues.length > 0 || input.transitions.length > 0;
+    const responsiveCovered = input.breakpoints.length > 0;
+    if (!typographySectionCovered)
+        score -= 10;
+    if (!componentsSectionCovered)
+        score -= 10;
+    if (!motionCovered)
+        score -= 8;
+    if (!responsiveCovered)
+        score -= 8;
+    if (!elevationSectionCovered)
+        score -= 8;
+    const canonicalCoverageCount = [
+        colorsSectionCovered,
+        typographySectionCovered,
+        layoutSectionCovered,
+        elevationSectionCovered,
+        shapesSectionCovered,
+        componentsSectionCovered,
+    ].filter(Boolean).length;
+    if (canonicalCoverageCount < 5) {
+        score -= (5 - canonicalCoverageCount) * 6;
+    }
+    return clampPercentage(score);
+};
+const TONE_HINTS = [
+    { keyword: /\bcraft|handmade|artisan/i, label: 'crafted / artisanal' },
+    { keyword: /\benterprise|secure|trusted/i, label: 'enterprise-grade / trustworthy' },
+    { keyword: /\bplayful|fun|delight/i, label: 'playful / delight-forward' },
+    { keyword: /\bminimal|simple|clean/i, label: 'minimal / restrained' },
+    { keyword: /\bfast|speed|performant/i, label: 'speed-led' },
+    { keyword: /\bbold|powerful|next-gen/i, label: 'bold / declarative' },
+];
+const detectTone = (html) => {
+    const text = stripTags(html).toLowerCase();
+    return dedupe(TONE_HINTS.filter(({ keyword }) => keyword.test(text)).map(({ label }) => label));
+};
+/**
+ * Pure HTML signal extractor. Operates on raw fetched HTML and pulls
+ * typography, color, layout, component, motion, brand, and tone signals
+ * via regex without instantiating a DOM. Returns deterministic ordered
+ * arrays so callers and tests can compare snapshots stably.
+ *
+ * `signalDensity` is a 0-100 fidelity-weighted score indicating how well
+ * the extracted evidence can populate canonical DESIGN.md token groups and
+ * sections. Callers can treat low scores as low-signal pages and fall back
+ * to prompt direction.
+ */
+const extractDesignSignals = (html, options) => {
+    const inlineStyles = `${extractStyleBlocks(html)}\n${extractInlineStyles(html)}`;
+    const styles = options?.extraCss
+        ? `${inlineStyles}\n${options.extraCss}`
+        : inlineStyles;
+    const googleFontFamilies = extractGoogleFontFamilies(html);
+    const fontFaces = extractFontFaceEvidence(styles);
+    const families = dedupe([
+        ...findFontFamilies(styles),
+        ...googleFontFamilies,
+        ...fontFaces.map((face) => face.fontFamily),
+    ]);
+    const weights = dedupe(collectWeights(styles)).slice(0, MAX_TYPOGRAPHY_FAMILIES);
+    const scaleSamples = dedupe(collectScaleSamples(styles)).slice(0, MAX_TYPOGRAPHY_FAMILIES);
+    const colors = dedupe(collectColors(styles)).slice(0, MAX_PALETTE_COLORS);
+    const themeColor = extractMetaContent(html, 'theme-color');
+    const accents = colors.slice(0, Math.min(4, colors.length));
+    // Word-boundary anchors keep `sans-serif` out of headings (only true
+    // display-y names like `Space Grotesk` or `Display` should land here).
+    const headingFamilyHint = families
+        .filter((family) => /\b(?:display|grotesk|black|heavy)\b/i.test(family))
+        .slice(0, MAX_TYPOGRAPHY_FAMILIES);
+    const bodyFamilyHint = families
+        .filter((family) => !/\b(?:display|grotesk|black|heavy)\b/i.test(family))
+        .slice(0, MAX_TYPOGRAPHY_FAMILIES);
+    const description = extractMetaContent(html, 'description') ??
+        extractMetaContent(html, 'og:description');
+    const siteName = extractMetaContent(html, 'og:site_name');
+    const typographyTokens = extractTypographyTokens(styles);
+    const colorRoles = inferColorRoles(styles, colors);
+    const spacing = extractSpacingTokens(styles);
+    const rounded = extractRoundedTokens(styles);
+    const shadows = extractShadowDeclarations(styles);
+    const transitions = extractTransitionDeclarations(styles);
+    const breakpoints = extractBreakpointConditions(styles);
+    const componentDetails = extractComponentTokenDetails(styles);
+    const sectionSignals = detectSections(html).slice(0, MAX_LIST_ITEMS_PER_SECTION);
+    const componentSignals = detectComponents(html).slice(0, MAX_LIST_ITEMS_PER_SECTION);
+    const motionSignals = detectMotionCues(html).slice(0, MAX_LIST_ITEMS_PER_SECTION);
+    const structureSignals = detectStructureNotes(html).slice(0, MAX_LIST_ITEMS_PER_SECTION);
+    const signalDensity = computeDesignFidelityScore({
+        colors,
+        colorRoles,
+        typographyTokens,
+        headingFamilies: families.filter((family) => /\b(?:display|grotesk|black|heavy)\b/i.test(family)),
+        bodyFamilies: families.filter((family) => !/\b(?:display|grotesk|black|heavy)\b/i.test(family)),
+        scaleSamples,
+        sections: sectionSignals,
+        structureNotes: structureSignals,
+        rounded,
+        shadows,
+        transitions,
+        breakpoints,
+        components: componentSignals,
+        componentDetails,
+        motionCues: motionSignals,
+    });
+    return {
+        brand: {
+            title: extractTitle(html),
+            description,
+            siteName,
+            tone: detectTone(html),
+        },
+        typography: {
+            headingFamilies: dedupe(headingFamilyHint),
+            bodyFamilies: dedupe(bodyFamilyHint),
+            weights,
+            scaleSamples,
+            ...(typographyTokens.display || typographyTokens.body
+                ? { tokens: typographyTokens }
+                : {}),
+            ...(googleFontFamilies.length > 0 ? { googleFontFamilies } : {}),
+            ...(fontFaces.length > 0 ? { fontFaces } : {}),
+        },
+        colors: {
+            palette: colors,
+            themeColor,
+            accents,
+            ...(Object.values(colorRoles).filter(Boolean).length > 0
+                ? { roles: colorRoles }
+                : {}),
+        },
+        layout: {
+            sections: sectionSignals,
+            structureNotes: structureSignals,
+        },
+        components: componentSignals,
+        motionCues: motionSignals,
+        iconography: detectIconography(html).slice(0, MAX_LIST_ITEMS_PER_SECTION),
+        ...(spacing.observed.length > 0 ? { spacing } : {}),
+        ...(rounded.observed.length > 0 ? { rounded } : {}),
+        ...(shadows.length > 0 ? { shadows } : {}),
+        ...(transitions.length > 0 ? { transitions } : {}),
+        ...(breakpoints.length > 0 ? { breakpoints } : {}),
+        ...(componentDetails.length > 0 ? { componentDetails } : {}),
+        signalDensity,
+    };
+};
+exports.extractDesignSignals = extractDesignSignals;
+const NOT_OBSERVED = 'Not observed';
+const formatList = (items, fallback) => items.length === 0 ? [`- ${fallback}`] : items.map((item) => `- ${item}`);
+const quoteYaml = (value) => JSON.stringify(value);
+const asTokenString = (value) => value ?? NOT_OBSERVED;
+const normalizeTokenValue = (value) => {
+    if (!value)
+        return undefined;
+    return trimWhitespace(value).toLowerCase();
+};
+const resolveColorTokenReference = (value, colors) => {
+    const normalized = normalizeTokenValue(value);
+    if (!normalized)
+        return undefined;
+    const entries = [
+        ['primary', colors.primary],
+        ['on-primary', colors.onPrimary],
+        ['background', colors.background],
+        ['surface', colors.surface],
+        ['text', colors.text],
+        ['muted', colors.muted],
+        ['border', colors.border],
+    ];
+    for (const [name, tokenValue] of entries) {
+        if (normalizeTokenValue(tokenValue) === normalized)
+            return `{colors.${name}}`;
+    }
+    return undefined;
+};
+const resolveRoundedTokenReference = (value, rounded) => {
+    const normalized = normalizeTokenValue(value);
+    if (!normalized)
+        return undefined;
+    const entries = [
+        ['sm', rounded.sm],
+        ['md', rounded.md],
+        ['lg', rounded.lg],
+    ];
+    for (const [name, tokenValue] of entries) {
+        if (normalizeTokenValue(tokenValue) === normalized)
+            return `{rounded.${name}}`;
+    }
+    return undefined;
+};
+const hasTypographyToken = (token) => Boolean(token.fontFamily ||
+    token.fontSize ||
+    token.fontWeight ||
+    token.lineHeight ||
+    token.letterSpacing ||
+    token.fontVariationSettings);
+const hasComponentTokenReference = (components) => components.some((component) => Object.values(component).some((value) => /\{(?:colors|typography|rounded)\.[^}]+\}/.test(value)));
+const formatHostForLabel = (url) => {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+};
+/**
+ * Produce reusable DESIGN.md markdown with token frontmatter plus canonical
+ * prose sections (`Overview` through `Do's and Don'ts`). The markdown avoids
+ * embedding raw fetched HTML, source code, DOM dumps, screenshots, or
+ * proprietary copied text.
+ */
+const buildInspirationDesignContextMarkdown = (input) => {
+    if (input.signals.length === 0)
+        return '';
+    const mergedSignals = mergeSignals(input.signals);
+    const sourceHosts = input.sources.map(({ url }) => formatHostForLabel(url));
+    const colors = {
+        // D8: do NOT fall back to the most prominent accent. If no role-anchored
+        // primary was found, leave the slot undefined so the Caveat line below
+        // surfaces the gap. Promoting a frequency-ranked accent here was the
+        // SellRaze failure mode this change addresses.
+        primary: mergedSignals.colors.roles?.primary,
+        onPrimary: mergedSignals.colors.roles?.onPrimary,
+        background: mergedSignals.colors.roles?.background ??
+            mergedSignals.colors.palette.find((color) => isLikelyNeutralColor(color)),
+        surface: mergedSignals.colors.roles?.surface,
+        text: mergedSignals.colors.roles?.text,
+        muted: mergedSignals.colors.roles?.muted,
+        border: mergedSignals.colors.roles?.border,
+    };
+    const displayToken = {
+        ...(mergedSignals.typography.tokens?.display ?? {}),
+        ...(!mergedSignals.typography.tokens?.display?.fontFamily &&
+            mergedSignals.typography.headingFamilies[0]
+            ? { fontFamily: mergedSignals.typography.headingFamilies[0] }
+            : {}),
+        ...(!mergedSignals.typography.tokens?.display?.fontSize &&
+            mergedSignals.typography.scaleSamples[mergedSignals.typography.scaleSamples.length - 1]
+            ? {
+                fontSize: mergedSignals.typography.scaleSamples[mergedSignals.typography.scaleSamples.length - 1],
+            }
+            : {}),
+    };
+    const bodyToken = {
+        ...(mergedSignals.typography.tokens?.body ?? {}),
+        ...(!mergedSignals.typography.tokens?.body?.fontFamily &&
+            mergedSignals.typography.bodyFamilies[0]
+            ? { fontFamily: mergedSignals.typography.bodyFamilies[0] }
+            : {}),
+        ...(!mergedSignals.typography.tokens?.body?.fontSize &&
+            mergedSignals.typography.scaleSamples[0]
+            ? { fontSize: mergedSignals.typography.scaleSamples[0] }
+            : {}),
+    };
+    const rounded = {
+        sm: mergedSignals.rounded?.sm,
+        md: mergedSignals.rounded?.md,
+        lg: mergedSignals.rounded?.lg,
+    };
+    const spacing = {
+        sm: mergedSignals.spacing?.sm,
+        md: mergedSignals.spacing?.md,
+        lg: mergedSignals.spacing?.lg,
+    };
+    const componentFrontmatterRows = [];
+    for (const detail of mergedSignals.componentDetails ?? []) {
+        const fields = {};
+        const backgroundRef = resolveColorTokenReference(detail.backgroundColor, colors);
+        if (backgroundRef)
+            fields.backgroundColor = backgroundRef;
+        else if (detail.backgroundColor)
+            fields.backgroundColor = detail.backgroundColor;
+        const textRef = resolveColorTokenReference(detail.textColor, colors);
+        if (textRef)
+            fields.textColor = textRef;
+        else if (detail.textColor)
+            fields.textColor = detail.textColor;
+        const borderRef = resolveColorTokenReference(detail.borderColor, colors);
+        if (borderRef)
+            fields.borderColor = borderRef;
+        else if (detail.borderColor)
+            fields.borderColor = detail.borderColor;
+        if (hasTypographyToken(bodyToken)) {
+            fields.typography = '{typography.body}';
+        }
+        const roundedRef = resolveRoundedTokenReference(detail.borderRadius, rounded);
+        if (roundedRef)
+            fields.rounded = roundedRef;
+        else if (detail.borderRadius)
+            fields.rounded = detail.borderRadius;
+        if (detail.padding)
+            fields.padding = detail.padding;
+        if (detail.boxShadow)
+            fields.boxShadow = detail.boxShadow;
+        if (Object.keys(fields).length > 0) {
+            componentFrontmatterRows.push({ name: detail.name, fields });
+        }
+    }
+    const hasComponentRefs = hasComponentTokenReference(componentFrontmatterRows.map((entry) => entry.fields));
+    const docName = mergedSignals.brand.siteName ??
+        mergedSignals.brand.title ??
+        (sourceHosts.length > 0 ? sourceHosts[0] : 'Inspiration');
+    const description = mergedSignals.brand.description ??
+        (mergedSignals.brand.tone.length > 0
+            ? `Visual direction leans ${mergedSignals.brand.tone.join(', ')}.`
+            : 'Static inspiration extraction with limited observable evidence.');
+    const lines = [];
+    lines.push('---');
+    lines.push(`version: ${quoteYaml('alpha')}`);
+    lines.push(`name: ${quoteYaml(docName)}`);
+    lines.push(`description: ${quoteYaml(description)}`);
+    lines.push('colors:');
+    lines.push(`  primary: ${quoteYaml(asTokenString(colors.primary))}`);
+    lines.push(`  on-primary: ${quoteYaml(asTokenString(colors.onPrimary))}`);
+    lines.push(`  background: ${quoteYaml(asTokenString(colors.background))}`);
+    lines.push(`  surface: ${quoteYaml(asTokenString(colors.surface))}`);
+    lines.push(`  text: ${quoteYaml(asTokenString(colors.text))}`);
+    lines.push(`  muted: ${quoteYaml(asTokenString(colors.muted))}`);
+    lines.push(`  border: ${quoteYaml(asTokenString(colors.border))}`);
+    lines.push('typography:');
+    lines.push('  display:');
+    lines.push(`    fontFamily: ${quoteYaml(asTokenString(displayToken.fontFamily))}`);
+    lines.push(`    fontSize: ${quoteYaml(asTokenString(displayToken.fontSize))}`);
+    lines.push(`    fontWeight: ${quoteYaml(asTokenString(displayToken.fontWeight))}`);
+    lines.push(`    lineHeight: ${quoteYaml(asTokenString(displayToken.lineHeight))}`);
+    lines.push(`    letterSpacing: ${quoteYaml(asTokenString(displayToken.letterSpacing))}`);
+    lines.push('  body:');
+    lines.push(`    fontFamily: ${quoteYaml(asTokenString(bodyToken.fontFamily))}`);
+    lines.push(`    fontSize: ${quoteYaml(asTokenString(bodyToken.fontSize))}`);
+    lines.push(`    fontWeight: ${quoteYaml(asTokenString(bodyToken.fontWeight))}`);
+    lines.push(`    lineHeight: ${quoteYaml(asTokenString(bodyToken.lineHeight))}`);
+    lines.push(`    letterSpacing: ${quoteYaml(asTokenString(bodyToken.letterSpacing))}`);
+    lines.push('rounded:');
+    lines.push(`  sm: ${quoteYaml(asTokenString(rounded.sm))}`);
+    lines.push(`  md: ${quoteYaml(asTokenString(rounded.md))}`);
+    lines.push(`  lg: ${quoteYaml(asTokenString(rounded.lg))}`);
+    lines.push('spacing:');
+    lines.push(`  sm: ${quoteYaml(asTokenString(spacing.sm))}`);
+    lines.push(`  md: ${quoteYaml(asTokenString(spacing.md))}`);
+    lines.push(`  lg: ${quoteYaml(asTokenString(spacing.lg))}`);
+    lines.push('components:');
+    if (componentFrontmatterRows.length === 0) {
+        lines.push('  not-observed:');
+        lines.push(`    note: ${quoteYaml(NOT_OBSERVED)}`);
+    }
+    else {
+        for (const component of componentFrontmatterRows) {
+            lines.push(`  ${component.name}:`);
+            for (const [field, value] of Object.entries(component.fields)) {
+                lines.push(`    ${field}: ${quoteYaml(value)}`);
+            }
+        }
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push('## Overview');
+    if (sourceHosts.length > 0) {
+        lines.push(`- Inspiration source${sourceHosts.length > 1 ? 's' : ''}: ${sourceHosts.join(', ')}.`);
+    }
+    else {
+        lines.push(`- Inspiration source: ${NOT_OBSERVED}.`);
+    }
+    lines.push(`- Visual identity summary: ${description}`);
+    if (input.merged && sourceHosts.length > 1) {
+        lines.push('- Multiple inspirations were merged; treat conflicting cues as hypotheses to validate.');
+    }
+    lines.push('');
+    lines.push('## Colors');
+    lines.push(`- Primary token: ${asTokenString(colors.primary)}`);
+    lines.push(`- Background token: ${asTokenString(colors.background)}`);
+    lines.push(`- Text token: ${asTokenString(colors.text)}`);
+    lines.push(...formatList(mergedSignals.colors.palette.slice(0, 8).map((color) => `Observed palette: ${color}`), `Observed palette: ${NOT_OBSERVED}`));
+    if (!colors.primary) {
+        lines.push('- Caveat: `colors.primary` was not observed directly; validate accent intent manually.');
+    }
+    lines.push('');
+    lines.push('## Typography');
+    lines.push(`- Display font family: ${asTokenString(displayToken.fontFamily)}`);
+    lines.push(`- Body font family: ${asTokenString(bodyToken.fontFamily)}`);
+    lines.push(...formatList(mergedSignals.typography.scaleSamples.slice(0, 6).map((sample) => `Observed scale: ${sample}`), `Observed scale: ${NOT_OBSERVED}`));
+    lines.push(...formatList((mergedSignals.typography.googleFontFamilies ?? []).map((family) => `Google Fonts evidence: ${family}`), `Google Fonts evidence: ${NOT_OBSERVED}`));
+    lines.push(...formatList((mergedSignals.typography.fontFaces ?? []).map((face) => `@font-face evidence: ${face.fontFamily}${face.fontWeight ? ` (${face.fontWeight})` : ''}`), `@font-face evidence: ${NOT_OBSERVED}`));
+    lines.push('');
+    lines.push('## Layout');
+    lines.push(...formatList(mergedSignals.layout.sections, NOT_OBSERVED));
+    lines.push(...formatList(mergedSignals.layout.structureNotes.map((note) => `Structure note: ${note}`), `Structure note: ${NOT_OBSERVED}`));
+    lines.push(`- Spacing scale (sm/md/lg): ${asTokenString(spacing.sm)} / ${asTokenString(spacing.md)} / ${asTokenString(spacing.lg)}`);
+    lines.push(...formatList((mergedSignals.breakpoints ?? []).map((breakpoint) => `Responsive breakpoint: ${breakpoint}`), `Responsive breakpoint: ${NOT_OBSERVED}`));
+    lines.push('');
+    lines.push('## Elevation & Depth');
+    lines.push(...formatList((mergedSignals.shadows ?? []).map((shadow) => `Shadow token evidence: ${shadow}`), `Shadow token evidence: ${NOT_OBSERVED}`));
+    lines.push(...formatList((mergedSignals.transitions ?? []).map((transition) => `Transition token evidence: ${transition}`), `Transition token evidence: ${NOT_OBSERVED}`));
+    lines.push('');
+    lines.push('## Shapes');
+    lines.push(`- Rounded scale (sm/md/lg): ${asTokenString(rounded.sm)} / ${asTokenString(rounded.md)} / ${asTokenString(rounded.lg)}`);
+    if (!rounded.sm && !rounded.md && !rounded.lg) {
+        lines.push('- Caveat: Rounded token evidence is not observed; shape direction is uncertain.');
+    }
+    lines.push('');
+    lines.push('## Components');
+    if (componentFrontmatterRows.length === 0) {
+        lines.push(`- ${NOT_OBSERVED}`);
+    }
+    else {
+        for (const component of componentFrontmatterRows) {
+            const summary = Object.entries(component.fields)
+                .map(([field, value]) => `${field}=${value}`)
+                .join(', ');
+            lines.push(`- ${component.name}: ${summary}`);
+        }
+    }
+    if (!hasComponentRefs) {
+        lines.push('- Caveat: Component token references are thin; map component styles back to token groups before implementation.');
+    }
+    lines.push('');
+    lines.push("## Do's and Don'ts");
+    lines.push('- Do keep implementations aligned with observed tokens and section evidence.');
+    lines.push('- Do treat any `Not observed` field as an explicit validation gap before shipping.');
+    lines.push("- Don't copy source copy, proprietary assets, or assume exact values where evidence is missing.");
+    lines.push("- Don't invent responsive, motion, or elevation behavior when those sections are `Not observed`.");
+    return `${lines.join('\n')}\n`;
+};
+exports.buildInspirationDesignContextMarkdown = buildInspirationDesignContextMarkdown;
+const mergeSignals = (signals) => {
+    if (signals.length === 1)
+        return signals[0];
+    const merge = (selector) => dedupe(signals.flatMap(selector));
+    const mergeTypographyToken = (selector) => {
+        const mergedToken = {};
+        for (const signal of signals) {
+            const token = selector(signal);
+            if (!token)
+                continue;
+            if (!mergedToken.fontFamily && token.fontFamily) {
+                mergedToken.fontFamily = token.fontFamily;
+            }
+            if (!mergedToken.fontSize && token.fontSize) {
+                mergedToken.fontSize = token.fontSize;
+            }
+            if (!mergedToken.fontWeight && token.fontWeight) {
+                mergedToken.fontWeight = token.fontWeight;
+            }
+            if (!mergedToken.lineHeight && token.lineHeight) {
+                mergedToken.lineHeight = token.lineHeight;
+            }
+            if (!mergedToken.letterSpacing && token.letterSpacing) {
+                mergedToken.letterSpacing = token.letterSpacing;
+            }
+            if (!mergedToken.fontVariationSettings && token.fontVariationSettings) {
+                mergedToken.fontVariationSettings = token.fontVariationSettings;
+            }
+        }
+        return hasTypographyToken(mergedToken) ? mergedToken : undefined;
+    };
+    const mergeColorRoles = () => {
+        const roles = {};
+        for (const signal of signals) {
+            const next = signal.colors.roles;
+            if (!next)
+                continue;
+            if (!roles.primary && next.primary)
+                roles.primary = next.primary;
+            if (!roles.onPrimary && next.onPrimary)
+                roles.onPrimary = next.onPrimary;
+            if (!roles.background && next.background)
+                roles.background = next.background;
+            if (!roles.surface && next.surface)
+                roles.surface = next.surface;
+            if (!roles.text && next.text)
+                roles.text = next.text;
+            if (!roles.muted && next.muted)
+                roles.muted = next.muted;
+            if (!roles.border && next.border)
+                roles.border = next.border;
+        }
+        return Object.values(roles).filter(Boolean).length > 0 ? roles : undefined;
+    };
+    const mergeComponentDetails = () => {
+        const byName = new Map();
+        for (const signal of signals) {
+            for (const detail of signal.componentDetails ?? []) {
+                const existing = byName.get(detail.name) ?? { name: detail.name };
+                if (!existing.backgroundColor && detail.backgroundColor) {
+                    existing.backgroundColor = detail.backgroundColor;
+                }
+                if (!existing.textColor && detail.textColor) {
+                    existing.textColor = detail.textColor;
+                }
+                if (!existing.borderColor && detail.borderColor) {
+                    existing.borderColor = detail.borderColor;
+                }
+                if (!existing.borderRadius && detail.borderRadius) {
+                    existing.borderRadius = detail.borderRadius;
+                }
+                if (!existing.padding && detail.padding)
+                    existing.padding = detail.padding;
+                if (!existing.boxShadow && detail.boxShadow) {
+                    existing.boxShadow = detail.boxShadow;
+                }
+                byName.set(detail.name, existing);
+            }
+        }
+        return Array.from(byName.values()).slice(0, MAX_COMPONENT_DETAILS);
+    };
+    const mergeDimensionScale = (selector) => {
+        const observed = dedupe(signals.flatMap((signal) => selector(signal)?.observed ?? []));
+        if (observed.length === 0)
+            return undefined;
+        return bucketDimensions(observed);
+    };
+    const mergedTypographyDisplay = mergeTypographyToken((signal) => signal.typography.tokens?.display);
+    const mergedTypographyBody = mergeTypographyToken((signal) => signal.typography.tokens?.body);
+    const mergedColorRoles = mergeColorRoles();
+    const mergedComponentDetails = mergeComponentDetails();
+    const mergedSpacing = mergeDimensionScale((signal) => signal.spacing);
+    const mergedRounded = mergeDimensionScale((signal) => signal.rounded);
+    const mergedFontFaces = signals
+        .flatMap((signal) => signal.typography.fontFaces ?? [])
+        .slice(0, MAX_FONT_FACE_EVIDENCE);
+    return {
+        brand: {
+            title: signals.find((s) => s.brand.title)?.brand.title,
+            description: signals.find((s) => s.brand.description)?.brand.description,
+            siteName: signals.find((s) => s.brand.siteName)?.brand.siteName,
+            tone: merge((s) => s.brand.tone),
+        },
+        typography: {
+            headingFamilies: merge((s) => s.typography.headingFamilies).slice(0, MAX_TYPOGRAPHY_FAMILIES),
+            bodyFamilies: merge((s) => s.typography.bodyFamilies).slice(0, MAX_TYPOGRAPHY_FAMILIES),
+            weights: merge((s) => s.typography.weights).slice(0, MAX_TYPOGRAPHY_FAMILIES),
+            scaleSamples: merge((s) => s.typography.scaleSamples).slice(0, MAX_TYPOGRAPHY_FAMILIES),
+            ...(merge((s) => s.typography.googleFontFamilies ?? []).length > 0
+                ? {
+                    googleFontFamilies: merge((s) => s.typography.googleFontFamilies ?? []).slice(0, MAX_GOOGLE_FONT_FAMILIES),
+                }
+                : {}),
+            ...(mergedFontFaces.length > 0
+                ? {
+                    fontFaces: mergedFontFaces,
+                }
+                : {}),
+            ...(mergedTypographyDisplay || mergedTypographyBody
+                ? {
+                    tokens: {
+                        ...(mergedTypographyDisplay ? { display: mergedTypographyDisplay } : {}),
+                        ...(mergedTypographyBody ? { body: mergedTypographyBody } : {}),
+                    },
+                }
+                : {}),
+        },
+        colors: {
+            palette: merge((s) => s.colors.palette).slice(0, MAX_PALETTE_COLORS),
+            themeColor: signals.find((s) => s.colors.themeColor)?.colors.themeColor,
+            accents: merge((s) => s.colors.accents).slice(0, 4),
+            ...(mergedColorRoles ? { roles: mergedColorRoles } : {}),
+        },
+        layout: {
+            sections: merge((s) => s.layout.sections).slice(0, MAX_LIST_ITEMS_PER_SECTION),
+            structureNotes: merge((s) => s.layout.structureNotes).slice(0, MAX_LIST_ITEMS_PER_SECTION),
+        },
+        components: merge((s) => s.components).slice(0, MAX_LIST_ITEMS_PER_SECTION),
+        motionCues: merge((s) => s.motionCues).slice(0, MAX_LIST_ITEMS_PER_SECTION),
+        iconography: merge((s) => s.iconography).slice(0, MAX_LIST_ITEMS_PER_SECTION),
+        ...(mergedSpacing ? { spacing: mergedSpacing } : {}),
+        ...(mergedRounded ? { rounded: mergedRounded } : {}),
+        ...(merge((s) => s.shadows ?? []).length > 0
+            ? { shadows: merge((s) => s.shadows ?? []).slice(0, MAX_SHADOWS) }
+            : {}),
+        ...(merge((s) => s.transitions ?? []).length > 0
+            ? { transitions: merge((s) => s.transitions ?? []).slice(0, MAX_TRANSITIONS) }
+            : {}),
+        ...(merge((s) => s.breakpoints ?? []).length > 0
+            ? { breakpoints: merge((s) => s.breakpoints ?? []).slice(0, MAX_BREAKPOINTS) }
+            : {}),
+        ...(mergedComponentDetails.length > 0
+            ? { componentDetails: mergedComponentDetails }
+            : {}),
+        signalDensity: Math.max(...signals.map((s) => s.signalDensity)),
+    };
+};
+const LOW_SIGNAL_THRESHOLD = 18;
+const truncateLabel = (label) => {
+    if (label.length <= MAX_DESIGN_CONTEXT_LABEL_LENGTH)
+        return label;
+    return label.slice(0, MAX_DESIGN_CONTEXT_LABEL_LENGTH);
+};
+const SOURCE_ROLE_LABELS = {
+    primary: 'Primary',
+    inspiration: 'Reference',
+    competitor: 'Reference',
+};
+const formatSourceRoleLabel = (source) => {
+    const sourceLabel = source.label ?? formatHostForLabel(source.url);
+    if (!source.role)
+        return sourceLabel;
+    return `${SOURCE_ROLE_LABELS[source.role]}: ${sourceLabel}`;
+};
+const buildLabel = (sources, merged, index) => {
+    const labels = sources.map(formatSourceRoleLabel);
+    if (labels.length === 0)
+        return DESIGN_CONTEXT_LABEL_DEFAULT;
+    if (merged) {
+        return truncateLabel(labels.join(' · '));
+    }
+    if (typeof index === 'number') {
+        return truncateLabel(`Inspiration ${index + 1}: ${labels[0]}`);
+    }
+    return truncateLabel(`Inspiration: ${labels[0]}`);
+};
+const emptyCacheCounters = (forcedRefresh) => ({
+    hitCount: 0,
+    missCount: 0,
+    staleCount: 0,
+    versionMismatchCount: 0,
+    lowConfidenceCount: 0,
+    regenerationCount: 0,
+    forcedRefresh,
+});
+/**
+ * Build a single-source markdown for a link that came from the cache so the
+ * separate-strategy path can reuse cached extractions without re-running
+ * the regex pipeline. The cached entry already encodes the per-URL signal
+ * extraction; this rebuilds the markdown with the slot's `Inspiration N:`
+ * label using the cached signals.
+ */
+const rebuildSingleSourceMarkdown = (signals, link) => (0, exports.buildInspirationDesignContextMarkdown)({
+    signals: [signals],
+    sources: [{ url: link.url, label: link.label }],
+    merged: false,
+});
+const pushCacheReuseWarning = (warnings, link, ageMs, confidence) => {
+    warnings.push(`Reusing cached design context for ${formatHostForLabel(link.url)} (age ${(0, designContextStore_1.ageBucketFor)(ageMs)}, confidence ${(0, designContextStore_1.confidenceBucketFor)(confidence)}). Ask for "fresh" or "latest" to regenerate.`);
+};
+const extractInspirationDesignContext = async (input) => {
+    const forceRefresh = Boolean(input.forceRefresh);
+    if (input.slotCount <= 0) {
+        return {
+            entries: [],
+            warnings: [],
+            telemetry: {
+                inspirationLinkCount: 0,
+                referenceLinkCount: 0,
+                successfulExtractions: 0,
+                lowSignalCount: 0,
+                fetchFailureCount: 0,
+                blockedTargetCount: 0,
+                mergeStrategy: 'none',
+                cache: emptyCacheCounters(forceRefresh),
+            },
+        };
+    }
+    const classification = (0, exports.classifyInspirationLinks)({
+        urls: input.urls,
+        prompt: input.prompt,
+        sourceContext: input.sourceContext,
+    });
+    if (classification.inspiration.length === 0) {
+        return {
+            entries: new Array(input.slotCount).fill(undefined),
+            warnings: [],
+            telemetry: {
+                inspirationLinkCount: 0,
+                referenceLinkCount: classification.reference.length,
+                successfulExtractions: 0,
+                lowSignalCount: 0,
+                fetchFailureCount: 0,
+                blockedTargetCount: 0,
+                mergeStrategy: 'none',
+                cache: emptyCacheCounters(forceRefresh),
+            },
+        };
+    }
+    const fetcher = input.fetcher ?? exports.defaultInspirationFetcher;
+    const cssFetcher = input.cssFetcher ?? exports.defaultLinkedCssFetcher;
+    const extractor = input.signalExtractor ?? exports.extractDesignSignals;
+    const store = input.store;
+    const now = input.now ?? Date.now;
+    const schemaVersion = input.schemaVersion ?? designContextStore_1.DESIGN_CONTEXT_SCHEMA_VERSION;
+    const warnings = [];
+    let fetchFailureCount = 0;
+    let blockedTargetCount = 0;
+    let lowSignalCount = 0;
+    const cacheCounters = emptyCacheCounters(forceRefresh);
+    // Track the most recent reuse age + confidence so callers can surface a
+    // single coarse summary in user-facing output.
+    let lastReuseMetadata;
+    /**
+     * Resolve a single inspiration link: prefer a compatible cache entry,
+     * otherwise fetch + extract and write the cache. Returns `undefined`
+     * signals when the source ultimately cannot produce usable design
+     * context so the caller can drop it from successful slots.
+     */
+    const resolveLink = async (link) => {
+        const cacheKey = (0, designContextStore_1.cacheKeyForUrl)(link.url);
+        // D9: When the caller supplies a `sourceContext.artifact` it represents
+        // explicit, intentional research that may contradict or augment a
+        // cached extraction. Bypassing cache reads (writes still happen) lets
+        // the override take precedence without erasing the cache for other
+        // callers. The presence of `artifact` is sufficient signal — we don't
+        // diff its contents against cached signals.
+        const artifactOverride = Boolean(input.sourceContext?.artifact);
+        if (store && cacheKey && !artifactOverride) {
+            let cached;
+            try {
+                cached = await store.get(cacheKey);
+            }
+            catch (error) {
+                log.debug(`Cache read failed for inspiration link: ${String(error)}`);
+                cached = undefined;
+            }
+            if (cached) {
+                const decision = (0, designContextStore_1.canReuseCacheEntry)(cached, {
+                    forceRefresh,
+                    schemaVersion,
+                    confidenceThreshold: LOW_SIGNAL_THRESHOLD,
+                    freshnessMs: input.freshnessMs,
+                    now: now(),
+                });
+                if (decision.reuse) {
+                    cacheCounters.hitCount += 1;
+                    pushCacheReuseWarning(warnings, link, decision.ageMs, cached.metadata.confidence);
+                    lastReuseMetadata = {
+                        ageBucket: (0, designContextStore_1.ageBucketFor)(decision.ageMs),
+                        confidenceBucket: (0, designContextStore_1.confidenceBucketFor)(cached.metadata.confidence),
+                        freshness: decision.freshness,
+                    };
+                    const refreshedEntry = {
+                        ...cached,
+                        metadata: {
+                            ...cached.metadata,
+                            lastUsedAtMs: now(),
+                        },
+                    };
+                    try {
+                        await store.put(refreshedEntry);
+                    }
+                    catch (error) {
+                        log.debug(`Cache lastUsedAt refresh failed (continuing): ${String(error)}`);
+                    }
+                    return {
+                        link,
+                        signals: cached.signals,
+                        source: 'cache',
+                        ageMs: decision.ageMs,
+                        confidence: cached.metadata.confidence,
+                    };
+                }
+                switch (decision.reason) {
+                    case 'stale':
+                        cacheCounters.staleCount += 1;
+                        cacheCounters.regenerationCount += 1;
+                        warnings.push(`Cached design context for ${formatHostForLabel(link.url)} is stale (age ${(0, designContextStore_1.ageBucketFor)(decision.ageMs)}, confidence ${(0, designContextStore_1.confidenceBucketFor)(cached.metadata.confidence)}); regenerating.`);
+                        break;
+                    case 'version_mismatch':
+                        cacheCounters.versionMismatchCount += 1;
+                        cacheCounters.regenerationCount += 1;
+                        break;
+                    case 'low_confidence':
+                        cacheCounters.lowConfidenceCount += 1;
+                        cacheCounters.regenerationCount += 1;
+                        break;
+                    case 'forced_refresh':
+                        cacheCounters.regenerationCount += 1;
+                        break;
+                    case 'corrupt':
+                        cacheCounters.regenerationCount += 1;
+                        break;
+                }
+            }
+            else {
+                cacheCounters.missCount += 1;
+            }
+        }
+        const result = await fetcher(link.url);
+        if (!result.ok) {
+            // Match both DNS-resolved protected-target reasons and literal-hostname
+            // blocks produced by `validateInspirationUrl` (e.g. localhost, .local,
+            // private IP literals). Without the second alternative, literal-hostname
+            // rejections were miscounted as generic fetch failures.
+            if (/protected target|private-network target/i.test(result.reason)) {
+                blockedTargetCount += 1;
+            }
+            else {
+                fetchFailureCount += 1;
+            }
+            warnings.push(`Could not extract design context from ${formatHostForLabel(link.url)}: ${result.reason}`);
+            return undefined;
+        }
+        // Bounded linked-stylesheet ingestion. The fetched CSS is ephemeral —
+        // we pass it to the signal extractor and discard it. Only derived
+        // signals (palette, role assignments, token scales, etc.) survive into
+        // the cache or telemetry.
+        const linkedCss = await (0, exports.fetchLinkedStylesheets)(result.html, result.finalUrl, cssFetcher);
+        if (linkedCss.skippedReasons.includes('total_budget_exceeded')) {
+            warnings.push(`Linked stylesheet ingestion for ${formatHostForLabel(link.url)} hit the total byte budget; some external stylesheets were skipped.`);
+        }
+        else if (linkedCss.attemptedCount > 0 &&
+            linkedCss.fetchedCount === 0) {
+            warnings.push(`Could not load any linked stylesheets for ${formatHostForLabel(link.url)}; using inline styles only.`);
+        }
+        const signals = extractor(result.html, {
+            sourceUrl: result.finalUrl,
+            extraCss: linkedCss.css ? linkedCss.css : undefined,
+        });
+        if (signals.signalDensity < LOW_SIGNAL_THRESHOLD) {
+            lowSignalCount += 1;
+            warnings.push(`${formatHostForLabel(link.url)} produced low design signal; consider providing more prompt direction.`);
+            return undefined;
+        }
+        if (store && cacheKey) {
+            const markdown = rebuildSingleSourceMarkdown(signals, link);
+            const label = buildLabel([
+                {
+                    url: link.url,
+                    label: link.label,
+                    role: findRoleForUrl(link.url, input.sourceContext),
+                },
+            ], false);
+            const entry = {
+                metadata: {
+                    cacheKey,
+                    schemaVersion,
+                    createdAtMs: now(),
+                    lastUsedAtMs: now(),
+                    confidence: signals.signalDensity,
+                    warningCodes: [],
+                },
+                markdown,
+                label,
+                signals,
+            };
+            try {
+                await store.put(entry);
+            }
+            catch (error) {
+                log.debug(`Cache write failed (continuing): ${String(error)}`);
+            }
+        }
+        return { link, signals, source: 'fresh', confidence: signals.signalDensity };
+    };
+    const resolved = await Promise.all(classification.inspiration.map((link) => resolveLink(link)));
+    const successful = resolved.filter((item) => item !== undefined);
+    if (successful.length === 0) {
+        const allFetchesFailed = classification.inspiration.length > 0 &&
+            fetchFailureCount === classification.inspiration.length;
+        return {
+            entries: new Array(input.slotCount).fill(undefined),
+            warnings,
+            telemetry: {
+                inspirationLinkCount: classification.inspiration.length,
+                referenceLinkCount: classification.reference.length,
+                successfulExtractions: 0,
+                lowSignalCount,
+                fetchFailureCount,
+                blockedTargetCount,
+                mergeStrategy: classification.mergeStrategy,
+                cache: cacheCounters,
+            },
+            ...(lastReuseMetadata ? { cacheReuse: lastReuseMetadata } : {}),
+            ...(allFetchesFailed
+                ? {
+                    errorCode: 'INSPIRATION_FETCH_ALL_FAILED',
+                    errorMessage: 'All supplied inspiration URLs failed to fetch (DNS, timeout, or non-2xx). ' +
+                        'Consider passing a local asset via `assetUrls` (e.g. a screenshot or sketch) ' +
+                        'so generation can still ground against a visual reference.',
+                }
+                : {}),
+        };
+    }
+    if (classification.mergeStrategy === 'merge') {
+        const markdown = (0, exports.buildInspirationDesignContextMarkdown)({
+            signals: successful.map((item) => item.signals),
+            sources: successful.map((item) => ({
+                url: item.link.url,
+                label: item.link.label,
+            })),
+            merged: true,
+        });
+        // Dedupe by URL: a link can appear in both `classification.reference`
+        // (explicitly tagged) and `successful` (extracted via inspiration
+        // pipeline). Without dedupe the merged label would list the same URL
+        // twice. Keep the first occurrence (reference) so the role label wins.
+        const mergedSources = [];
+        const seenUrls = new Set();
+        for (const link of classification.reference) {
+            if (seenUrls.has(link.url))
+                continue;
+            seenUrls.add(link.url);
+            mergedSources.push({
+                url: link.url,
+                label: link.label,
+                role: findRoleForUrl(link.url, input.sourceContext),
+            });
+        }
+        for (const item of successful) {
+            if (seenUrls.has(item.link.url))
+                continue;
+            seenUrls.add(item.link.url);
+            mergedSources.push({
+                url: item.link.url,
+                label: item.link.label,
+                role: findRoleForUrl(item.link.url, input.sourceContext),
+            });
+        }
+        const label = buildLabel(mergedSources, true);
+        // Use a factory so each slot gets its own object instance; sharing one
+        // reference via `fill()` would let any downstream mutation leak across
+        // every slot.
+        const entries = Array.from({ length: input.slotCount }, () => ({
+            kind: 'markdown',
+            label,
+            content: markdown,
+        }));
+        return {
+            entries,
+            warnings,
+            telemetry: {
+                inspirationLinkCount: classification.inspiration.length,
+                referenceLinkCount: classification.reference.length,
+                successfulExtractions: successful.length,
+                lowSignalCount,
+                fetchFailureCount,
+                blockedTargetCount,
+                mergeStrategy: 'merge',
+                cache: cacheCounters,
+            },
+            ...(lastReuseMetadata ? { cacheReuse: lastReuseMetadata } : {}),
+        };
+    }
+    const entries = new Array(input.slotCount).fill(undefined);
+    for (let i = 0; i < input.slotCount; i++) {
+        const item = successful[i % successful.length];
+        const markdown = (0, exports.buildInspirationDesignContextMarkdown)({
+            signals: [item.signals],
+            sources: [{ url: item.link.url, label: item.link.label }],
+            merged: false,
+        });
+        entries[i] = {
+            kind: 'markdown',
+            label: buildLabel([
+                {
+                    url: item.link.url,
+                    label: item.link.label,
+                    role: findRoleForUrl(item.link.url, input.sourceContext),
+                },
+            ], false, i),
+            content: markdown,
+        };
+    }
+    return {
+        entries,
+        warnings,
+        telemetry: {
+            inspirationLinkCount: classification.inspiration.length,
+            referenceLinkCount: classification.reference.length,
+            successfulExtractions: successful.length,
+            lowSignalCount,
+            fetchFailureCount,
+            blockedTargetCount,
+            mergeStrategy: 'separate',
+            cache: cacheCounters,
+        },
+        ...(lastReuseMetadata ? { cacheReuse: lastReuseMetadata } : {}),
+    };
+};
+exports.extractInspirationDesignContext = extractInspirationDesignContext;
+/**
+ * Internal debug helper for ad-hoc engineering verification. Not registered
+ * as an MCP tool, not exported from `index.ts`, and not advertised as a
+ * product surface. Routes through the same validation, fetch, and markdown
+ * generation as the MCP pipeline so debug output cannot drift from product
+ * output.
+ */
+const standaloneDebugExtract = async (url, fetcher = exports.defaultInspirationFetcher) => {
+    log.debug(`standaloneDebugExtract: ${url}`);
+    const outcome = await (0, exports.extractInspirationDesignContext)({
+        urls: [url],
+        prompt: url,
+        slotCount: 1,
+        fetcher,
+    });
+    const entry = outcome.entries[0];
+    if (!entry || entry.kind !== 'markdown') {
+        return {
+            url,
+            ok: false,
+            warnings: outcome.warnings,
+        };
+    }
+    return {
+        url,
+        ok: true,
+        warnings: outcome.warnings,
+        markdown: entry.content,
+    };
+};
+exports.standaloneDebugExtract = standaloneDebugExtract;
+//# sourceMappingURL=inspirationDesignContext.js.map