dembrandt 0.19.5 → 0.19.7

package/README.md

@@ -42,7 +42,7 @@ Or add to your project's `.mcp.json`:
 }
 ```
 
-7 tools available: `get_design_tokens`, `get_color_palette`, `get_typography`, `get_component_styles`, `get_surfaces`, `get_spacing`, `get_brand_identity`.
+Available tools include `get_design_tokens`, `get_color_palette`, `get_typography`, `get_component_styles`, `get_surfaces`, `get_spacing`, and `get_brand_identity`, plus drift, report, and job-control tools.
 
 Pair with **[dembrandt-skills](https://github.com/dembrandt/dembrandt-skills)** to give your agent UX intelligence on top of extracted tokens — hierarchy, accessibility, interaction states, and a full 6-stage design pipeline orchestrator.
 
@@ -247,7 +247,28 @@ dembrandt https://app.example.com --json-only > baseline.json
 dembrandt https://app.example.com --compare baseline.json --html report.html
 ```
 
-A ready-to-use GitHub Actions workflow (preview vs production, run summary, report artifact, host-auth bypass) is in [`examples/drift-gate.yml`](examples/drift-gate.yml).
+When the change is intended, accept it as the new baseline — `--approve` overwrites the local baseline file and passes instead of failing:
+
+```bash
+dembrandt https://app.example.com --compare baseline.json --approve
+```
+
+Add `--json-only` to a `--compare` run to get the drift report as machine-readable JSON under a `drift` key — `score`, `status`, `summary`, and per-token `changes[]` (each with `category`, `kind`, `before`, `after`, `delta`). A CI gate can render exactly which tokens moved (e.g. in a PR comment) from this instead of parsing the HTML report:
+
+```bash
+dembrandt https://app.example.com --compare baseline.json --json-only
+```
+
+**Any CI.** The gate is platform-neutral — it is just the exit code plus the drift JSON, so it drops into any runner:
+
+```bash
+dembrandt "$PREVIEW/checkout" --compare base.json --json-only > drift.json
+# exit 1 = drift. Read drift.json (.drift.changes) and surface it however your
+# platform does: a GitLab MR note, an Azure DevOps PR thread, a Jenkins status,
+# a Slack message, or an auto-filed Jira/Linear ticket.
+```
+
+A ready-to-use **GitHub Actions** workflow (preview vs production, per-page PR comment with the exact tokens that changed, run summary, report artifact, host-auth bypass) is in [`examples/drift-gate.yml`](examples/drift-gate.yml) as one full reference. The result-surfacing step (annotations, PR comment) is the only platform-specific part; the extract → compare → branch-on-exit-code core is identical on GitLab CI, Jenkins, and Azure DevOps.
 
 ### Exit codes
 

package/dist/lib/exit-codes.d.ts

@@ -23,7 +23,7 @@ export type ErrorCode = "NAVIGATION_TIMEOUT" | "EXTRACTION_FAILED";
  * is a generic RUNTIME failure. Reads only `err.message`, so a bare string or a
  * malformed error never throws.
  */
-export declare function classifyError(err: any): {
+export declare function classifyError(err: unknown): {
     code: ErrorCode;
     exit: number;
 };

package/dist/lib/exit-codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../../lib/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAW,CAAC;AAK1E;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAQ;IACpC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IACrC,IAAI,2EAA2E,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../../lib/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAW,CAAC;AAK1E;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,MAAM,CAAC,GAAG,MAAM,CAAE,GAA6B,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IAChE,IAAI,2EAA2E,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AAC3D,CAAC"}

package/dist/lib/extractors/context-config.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure parsing of CLI-supplied browser-context inputs (cookies, headers, screen
+ * size, locale) into Playwright context configuration. Split out of the
+ * extraction orchestrator so the untrusted-input surface is unit-testable and
+ * malformed input degrades to safe defaults instead of producing broken values.
+ *
+ * Written strict-clean (no implicit any, no null leaks) per the per-module
+ * strict ratchet, even though the global tsconfig is strict:false.
+ */
+import type { ExtractOptions } from '../types.js';
+export interface ParsedCookie {
+    readonly name: string;
+    readonly value: string;
+    readonly url: string;
+}
+export interface ScreenSize {
+    readonly width: number;
+    readonly height: number;
+}
+export type ColorScheme = 'light' | 'dark' | 'no-preference';
+/**
+ * The subset of Playwright's BrowserContextOptions that we set. Declared
+ * explicitly (rather than `Record<string, any>`) so the config the extraction
+ * engine depends on is type-checked at the one call site where `browser` is an
+ * untyped handle.
+ */
+export interface ContextOptions {
+    viewport: ScreenSize;
+    screen: ScreenSize;
+    userAgent: string;
+    locale: string;
+    timezoneId: string;
+    extraHTTPHeaders: Record<string, string>;
+    colorScheme: ColorScheme;
+    permissions?: string[];
+}
+export declare const DEFAULT_SCREEN: ScreenSize;
+export declare const DEFAULT_LOCALE = "en-US";
+export declare const DEFAULT_TIMEZONE = "America/New_York";
+export declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36";
+/**
+ * Parse a "Name=value; Name2=value2" cookie string. Pairs without an "=" are
+ * skipped rather than emitted with a truncated name and the whole token as the
+ * value (the previous behavior). Empty names are also dropped.
+ */
+export declare function parseCookies(cookie: string | undefined, url: string): ParsedCookie[];
+/**
+ * Parse a single "Name: value" header. Returns {} when absent or when no colon
+ * is present (an invalid header is ignored rather than guessed at).
+ */
+export declare function parseHeader(header: string | undefined): Record<string, string>;
+/**
+ * Parse a "WIDTHxHEIGHT" screen size. Falls back to the default when either
+ * dimension is missing, non-numeric, or non-positive, so a typo never produces
+ * a NaN viewport that silently breaks layout-dependent extraction. Returns a
+ * fresh object so callers can never mutate the shared default.
+ */
+export declare function parseScreenSize(screenSize: string | undefined): ScreenSize;
+/**
+ * Derive the Accept-Language header. An explicit value wins; otherwise it is
+ * built from the locale, weighting the locale and its base language ahead of
+ * English.
+ */
+export declare function deriveAcceptLanguage(locale: string, explicit?: string): string;
+/**
+ * Build the Playwright context options from CLI options. Pure: no browser
+ * access, no mutation of the input. Cookies and init scripts are applied
+ * separately by the caller because they are side effects on a live context.
+ */
+export declare function buildContextOptions(options: ExtractOptions, browserName: string): ContextOptions;

package/dist/lib/extractors/context-config.js

@@ -0,0 +1,96 @@
+export const DEFAULT_SCREEN = Object.freeze({ width: 1920, height: 1080 });
+export const DEFAULT_LOCALE = 'en-US';
+export const DEFAULT_TIMEZONE = 'America/New_York';
+export const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36';
+/**
+ * Parse a "Name=value; Name2=value2" cookie string. Pairs without an "=" are
+ * skipped rather than emitted with a truncated name and the whole token as the
+ * value (the previous behavior). Empty names are also dropped.
+ */
+export function parseCookies(cookie, url) {
+    if (!cookie)
+        return [];
+    const out = [];
+    for (const raw of cookie.split(';')) {
+        const c = raw.trim();
+        if (!c)
+            continue;
+        const eq = c.indexOf('=');
+        if (eq < 1)
+            continue; // no "=", or "=value" with an empty name
+        out.push({ name: c.slice(0, eq).trim(), value: c.slice(eq + 1).trim(), url });
+    }
+    return out;
+}
+/**
+ * Parse a single "Name: value" header. Returns {} when absent or when no colon
+ * is present (an invalid header is ignored rather than guessed at).
+ */
+export function parseHeader(header) {
+    if (!header)
+        return {};
+    const colon = header.indexOf(':');
+    if (colon < 1)
+        return {};
+    const name = header.slice(0, colon).trim();
+    if (!name)
+        return {};
+    return { [name]: header.slice(colon + 1).trim() };
+}
+/**
+ * Parse a "WIDTHxHEIGHT" screen size. Falls back to the default when either
+ * dimension is missing, non-numeric, or non-positive, so a typo never produces
+ * a NaN viewport that silently breaks layout-dependent extraction. Returns a
+ * fresh object so callers can never mutate the shared default.
+ */
+export function parseScreenSize(screenSize) {
+    if (!screenSize)
+        return { width: DEFAULT_SCREEN.width, height: DEFAULT_SCREEN.height };
+    const parts = screenSize.split('x');
+    if (parts.length !== 2)
+        return { width: DEFAULT_SCREEN.width, height: DEFAULT_SCREEN.height };
+    const width = Number(parts[0]);
+    const height = Number(parts[1]);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        return { width: DEFAULT_SCREEN.width, height: DEFAULT_SCREEN.height };
+    }
+    return { width: Math.round(width), height: Math.round(height) };
+}
+/**
+ * Derive the Accept-Language header. An explicit value wins; otherwise it is
+ * built from the locale, weighting the locale and its base language ahead of
+ * English.
+ */
+export function deriveAcceptLanguage(locale, explicit) {
+    if (explicit)
+        return explicit;
+    const base = locale.split('-')[0];
+    return `${locale},${base};q=0.9,en;q=0.8`;
+}
+/**
+ * Build the Playwright context options from CLI options. Pure: no browser
+ * access, no mutation of the input. Cookies and init scripts are applied
+ * separately by the caller because they are side effects on a live context.
+ */
+export function buildContextOptions(options, browserName) {
+    const locale = options.locale || DEFAULT_LOCALE;
+    const size = parseScreenSize(options.screenSize);
+    const extraHTTPHeaders = {
+        'Accept-Language': deriveAcceptLanguage(locale, options.acceptLanguage),
+        ...parseHeader(options.header),
+    };
+    const contextOptions = {
+        viewport: { width: size.width, height: size.height },
+        screen: { width: size.width, height: size.height },
+        userAgent: options.userAgent || DEFAULT_USER_AGENT,
+        locale,
+        timezoneId: options.timezoneId || DEFAULT_TIMEZONE,
+        extraHTTPHeaders,
+        colorScheme: 'light',
+    };
+    if (browserName === 'chromium') {
+        contextOptions.permissions = ['clipboard-read', 'clipboard-write'];
+    }
+    return contextOptions;
+}
+//# sourceMappingURL=context-config.js.map

package/dist/lib/extractors/context-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-config.js","sourceRoot":"","sources":["../../../lib/extractors/context-config.ts"],"names":[],"mappings":"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"}

package/dist/lib/extractors/guard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fault isolation for the parallel extractors. Each extractor runs inside
+ * guardExtractor so a single throw degrades only its own category — recording
+ * { stage, reason } and returning a fallback — instead of rejecting Promise.all
+ * and aborting the entire run. Kept in its own module so the isolation contract
+ * is unit-testable without a browser.
+ */
+import type { ExtractorError } from '../types.js';
+export declare function guardExtractor<T>(stage: string, run: Promise<T>, fallback: T, sink: ExtractorError[]): Promise<T>;

package/dist/lib/extractors/guard.js

@@ -0,0 +1,10 @@
+export async function guardExtractor(stage, run, fallback, sink) {
+    try {
+        return await run;
+    }
+    catch (err) {
+        sink.push({ stage, reason: err instanceof Error ? err.message : String(err) });
+        return fallback;
+    }
+}
+//# sourceMappingURL=guard.js.map

package/dist/lib/extractors/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../../lib/extractors/guard.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAa,EACb,GAAe,EACf,QAAW,EACX,IAAsB;IAEtB,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,CAAC;IACnB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/E,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/lib/extractors/index.d.ts

@@ -1,3 +1,4 @@
+import type { Browser } from 'playwright';
 import type { ExtractOptions, BrandingResult, Spinner } from '../types.js';
 /**
  * @param {string} url
@@ -6,4 +7,4 @@ import type { ExtractOptions, BrandingResult, Spinner } from '../types.js';
  * @param {{ slow?: boolean, darkMode?: boolean, mobile?: boolean, wcag?: boolean, screenshotPath?: string, discoverLinks?: number|null, navigationTimeout?: number, stealth?: boolean, userAgent?: string, locale?: string, timezoneId?: string, acceptLanguage?: string, screenSize?: string }} [options]
  * @returns {Promise<BrandingResult>}
  */
-export declare function extractBranding(url: string, spinner: Spinner, browser: any, options?: ExtractOptions): Promise<BrandingResult>;
+export declare function extractBranding(url: string, spinner: Spinner, browser: Browser, options?: ExtractOptions): Promise<BrandingResult>;

package/dist/lib/extractors/index.js

@@ -10,6 +10,8 @@ import { extractBreakpoints, detectIconSystem, detectFrameworks, extractGradient
 import { extractTeach } from './teach.js';
 import { extractWcagPairs } from './colors.js';
 import { SCHEMA_VERSION } from '../version.js';
+import { buildContextOptions, parseCookies, parseScreenSize, DEFAULT_LOCALE } from './context-config.js';
+import { guardExtractor } from './guard.js';
 // Gaussian noise via Box-Muller
 function gaussian(mean = 0, std = 1) {
     let u, v;
@@ -45,7 +47,7 @@ function velocityProfile(t, overshootProb = 0.3) {
     return 0.15 + Math.random() * 0.1; // corrective micro-movements
 }
 // Sleep helper
-const sleep = ms => new Promise(r => setTimeout(r, ms));
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
 /**
  * Adaptive readiness: resolve as soon as the page is actually settled — network
  * quiet, web fonts loaded, and the DOM done mutating — instead of always waiting
@@ -252,49 +254,21 @@ export async function extractBranding(url, spinner, browser, options = {}) {
     const timeoutMultiplier = options.slow ? 3 : 1;
     const timeouts = [];
     const degraded = []; // post-extraction stages that failed but did not abort the run
+    const extractorErrors = []; // scoped failures of the parallel extractors
     // Progress lines print only in verbose mode (the main `dembrandt <url>`
     // command). Report commands (drift/init/conformance) pass no verbose flag and
     // stay clean. Warnings are NOT routed through this — they always print.
     const log = (...args) => { if (options.verbose)
         console.log(...args); };
     spinner.text = "Creating browser context...";
-    const locale = options.locale || "en-US";
-    const timezoneId = options.timezoneId || "America/New_York";
-    const acceptLanguage = options.acceptLanguage || `${locale},${locale.split('-')[0]};q=0.9,en;q=0.8`;
-    const [screenW, screenH] = options.screenSize
-        ? options.screenSize.split('x').map(Number)
-        : [1920, 1080];
-    // Parse "Name=value; Name2=value2" cookie string into Playwright format
-    const parsedCookies = options.cookie
-        ? options.cookie.split(";").map((c) => c.trim()).filter(Boolean).map((c) => {
-            const eq = c.indexOf("=");
-            return {
-                name: c.slice(0, eq).trim(),
-                value: c.slice(eq + 1).trim(),
-                url,
-            };
-        })
-        : [];
-    const extraHeaders = { "Accept-Language": acceptLanguage };
-    if (options.header) {
-        const colon = options.header.indexOf(":");
-        if (colon > -1) {
-            extraHeaders[options.header.slice(0, colon).trim()] = options.header.slice(colon + 1).trim();
-        }
-    }
-    const contextOptions = {
-        viewport: { width: screenW, height: screenH },
-        screen: { width: screenW, height: screenH },
-        userAgent: options.userAgent || "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
-        locale,
-        timezoneId,
-        extraHTTPHeaders: extraHeaders,
-        colorScheme: "light",
-    };
-    if (browser.browserType().name() === 'chromium') {
-        contextOptions.permissions = ["clipboard-read", "clipboard-write"];
-    }
+    // locale, screenW and screenH are still needed below for the stealth init
+    // script; the rest of the context configuration is built purely in
+    // context-config.ts and unit-tested there.
+    const locale = options.locale || DEFAULT_LOCALE;
+    const { width: screenW, height: screenH } = parseScreenSize(options.screenSize);
+    const contextOptions = buildContextOptions(options, browser.browserType().name());
     const context = await browser.newContext(contextOptions);
+    const parsedCookies = parseCookies(options.cookie, url);
     if (parsedCookies.length > 0) {
         await context.addCookies(parsedCookies);
     }
@@ -694,27 +668,33 @@ export async function extractBranding(url, spinner, browser, options = {}) {
         log(color.info("\n  Extracting design tokens...\n"));
         spinner.start("Analyzing design system (17 parallel tasks)...");
         const [logoResult, colors, typography, spacing, borderRadius, borders, shadows, buttons, inputs, links, badges, breakpoints, iconSystem, frameworks, siteNameRaw, gradients, motion,] = await Promise.all([
-            extractLogo(page, url).catch(() => ({ logo: null, instances: [], favicons: [], manifest: null })),
-            extractColors(page).catch(() => ({ semantic: {}, palette: [], cssVariables: [], _raw: [] })),
-            extractTypography(page).catch(() => ({ styles: [], sources: {} })),
-            extractSpacing(page).catch(() => ({ scaleType: 'unknown', commonValues: [] })),
-            extractBorderRadius(page).catch(() => ({ values: [] })),
-            extractBorders(page).catch(() => ({ combinations: [] })),
-            extractShadows(page).catch(() => []),
-            extractButtonStyles(page).catch(() => []),
-            extractInputStyles(page).catch(() => []),
-            extractLinkStyles(page).catch(() => []),
-            extractBadgeStyles(page).catch(() => ({ all: [], byVariant: {} })),
-            extractBreakpoints(page).catch(() => []),
-            detectIconSystem(page).catch(() => []),
-            detectFrameworks(page).catch(() => []),
-            extractSiteName(page).catch(() => null),
-            extractGradients(page).catch(() => []),
-            extractMotion(page).catch(() => ({ durations: [], easings: [], byContext: {} })),
+            guardExtractor('logo', extractLogo(page, url), { logo: null, instances: [], favicons: [], manifest: null }, extractorErrors),
+            guardExtractor('colors', extractColors(page), { semantic: {}, palette: [], cssVariables: [], _raw: [] }, extractorErrors),
+            guardExtractor('typography', extractTypography(page), { styles: [], sources: {} }, extractorErrors),
+            guardExtractor('spacing', extractSpacing(page), { scaleType: 'unknown', commonValues: [] }, extractorErrors),
+            guardExtractor('borderRadius', extractBorderRadius(page), { values: [] }, extractorErrors),
+            guardExtractor('borders', extractBorders(page), { combinations: [] }, extractorErrors),
+            guardExtractor('shadows', extractShadows(page), [], extractorErrors),
+            guardExtractor('buttons', extractButtonStyles(page), [], extractorErrors),
+            guardExtractor('inputs', extractInputStyles(page), [], extractorErrors),
+            guardExtractor('links', extractLinkStyles(page), [], extractorErrors),
+            guardExtractor('badges', extractBadgeStyles(page), { all: [], byVariant: {} }, extractorErrors),
+            guardExtractor('breakpoints', extractBreakpoints(page), [], extractorErrors),
+            guardExtractor('iconSystem', detectIconSystem(page), [], extractorErrors),
+            guardExtractor('frameworks', detectFrameworks(page), [], extractorErrors),
+            guardExtractor('siteName', extractSiteName(page), null, extractorErrors),
+            guardExtractor('gradients', extractGradients(page), [], extractorErrors),
+            guardExtractor('motion', extractMotion(page), { durations: [], easings: [], byContext: {} }, extractorErrors),
         ]);
         const { logo, instances: logoInstances, favicons, manifest } = logoResult;
         let siteName = siteNameRaw;
         spinner.stop();
+        // Per-extractor failures are fault-isolated above and surface in meta.errors
+        // during result assembly. Print them once now, after the spinner stops, so a
+        // broken extractor is visible during a verbose run without clobbering it.
+        for (const e of extractorErrors) {
+            log(color.warning(`  ! ${e.stage}: extraction failed (continuing) — ${e.reason}`));
+        }
         // Inject manifest theme_color / background_color as high-confidence palette entries
         try {
             if (manifest) {
@@ -894,7 +874,8 @@ export async function extractBranding(url, spinner, browser, options = {}) {
                     }
                     if (['input', 'textarea', 'select', 'button', 'a'].includes(beforeState.tag)) {
                         try {
-                            await element.focus({ timeout: 500 * timeoutMultiplier });
+                            // ElementHandle.focus() takes no options; the focus is synchronous.
+                            await element.focus();
                             await page.waitForTimeout(100 * timeoutMultiplier);
                             const afterFocus = await element.evaluate(el => {
                                 function findBg(node) {
@@ -1244,6 +1225,8 @@ export async function extractBranding(url, spinner, browser, options = {}) {
         }
         if (degraded.length)
             result.meta.degraded = degraded;
+        if (extractorErrors.length)
+            result.meta.errors = extractorErrors;
         return result;
     }
     catch (error) {