@iflow-mcp/jakeliume-webpeel 0.22.0

package/dist/core/design-compare.js

@@ -0,0 +1,264 @@
+/**
+ * Design Compare — Structural diff between two pages' design tokens.
+ *
+ * Compares design quality of a subject URL against a reference URL,
+ * returning a structured gap list with severity ratings and CSS suggestions.
+ */
+import { extractDesignAnalysis } from './design-analysis.js';
+// ── Constants ──────────────────────────────────────────────────────────────────
+const SEVERITY_DEDUCTIONS = {
+    high: 1.5,
+    medium: 0.8,
+    low: 0.3,
+};
+// ── Pure comparison logic ──────────────────────────────────────────────────────
+/**
+ * Build a DesignComparison from two pre-extracted DesignAnalysis objects.
+ *
+ * This is a pure synchronous function — straightforward to test and reuse
+ * from both the HTTP route and the CLI command.
+ */
+export function buildDesignComparison(subjectUrl, referenceUrl, subjectAnalysis, referenceAnalysis) {
+    const gaps = [];
+    // ── 1. Color scheme ────────────────────────────────────────────────────────
+    if (subjectAnalysis.palette.scheme !== referenceAnalysis.palette.scheme) {
+        gaps.push({
+            property: 'palette.scheme',
+            description: 'Color scheme differs',
+            subject: subjectAnalysis.palette.scheme,
+            reference: referenceAnalysis.palette.scheme,
+            severity: 'medium',
+            suggestion: `Switch to a ${referenceAnalysis.palette.scheme} color scheme. Update background and text colors accordingly.`,
+        });
+    }
+    // ── 2. Primary background color ────────────────────────────────────────────
+    const subjectBg = subjectAnalysis.palette.dominant[0] ?? '';
+    const referenceBg = referenceAnalysis.palette.dominant[0] ?? '';
+    if (subjectBg && referenceBg && subjectBg.toLowerCase() !== referenceBg.toLowerCase()) {
+        gaps.push({
+            property: 'palette.dominant[0]',
+            description: 'Primary background color differs',
+            subject: subjectBg,
+            reference: referenceBg,
+            severity: 'low',
+            suggestion: `Consider using ${referenceBg} as the primary background color.`,
+        });
+    }
+    // ── 3. Layout system ───────────────────────────────────────────────────────
+    if (subjectAnalysis.layout.gridSystem !== referenceAnalysis.layout.gridSystem) {
+        gaps.push({
+            property: 'layout.gridSystem',
+            description: 'Layout system differs',
+            subject: subjectAnalysis.layout.gridSystem,
+            reference: referenceAnalysis.layout.gridSystem,
+            severity: 'medium',
+            suggestion: `Migrate to CSS ${referenceAnalysis.layout.gridSystem} to match the reference layout system.`,
+        });
+    }
+    // ── 4. Container max-width ─────────────────────────────────────────────────
+    if (subjectAnalysis.layout.maxWidth !== 'none' &&
+        referenceAnalysis.layout.maxWidth !== 'none' &&
+        subjectAnalysis.layout.maxWidth !== referenceAnalysis.layout.maxWidth) {
+        gaps.push({
+            property: 'layout.maxWidth',
+            description: 'Container max-width differs',
+            subject: subjectAnalysis.layout.maxWidth,
+            reference: referenceAnalysis.layout.maxWidth,
+            severity: 'low',
+            suggestion: `Set max-width to ${referenceAnalysis.layout.maxWidth} to match the reference layout.`,
+        });
+    }
+    // ── 5. Base font size ──────────────────────────────────────────────────────
+    const subjectBaseSize = parseFloat(subjectAnalysis.typeScale.baseSize);
+    const referenceBaseSize = parseFloat(referenceAnalysis.typeScale.baseSize);
+    if (!isNaN(subjectBaseSize) &&
+        !isNaN(referenceBaseSize) &&
+        Math.abs(subjectBaseSize - referenceBaseSize) >= 2) {
+        gaps.push({
+            property: 'typeScale.baseSize',
+            description: 'Base font size differs significantly',
+            subject: subjectAnalysis.typeScale.baseSize,
+            reference: referenceAnalysis.typeScale.baseSize,
+            severity: 'medium',
+            suggestion: `Set the root font-size to ${referenceAnalysis.typeScale.baseSize} (e.g., html { font-size: ${referenceAnalysis.typeScale.baseSize}; }).`,
+        });
+    }
+    // ── 6. Heading font family ─────────────────────────────────────────────────
+    const subjectHeadingFamily = subjectAnalysis.typeScale.headingStyle.family.toLowerCase();
+    const referenceHeadingFamily = referenceAnalysis.typeScale.headingStyle.family.toLowerCase();
+    if (subjectHeadingFamily && referenceHeadingFamily && subjectHeadingFamily !== referenceHeadingFamily) {
+        gaps.push({
+            property: 'typeScale.headingStyle.family',
+            description: 'Heading font family differs',
+            subject: subjectAnalysis.typeScale.headingStyle.family,
+            reference: referenceAnalysis.typeScale.headingStyle.family,
+            severity: 'high',
+            suggestion: `Use "${referenceAnalysis.typeScale.headingStyle.family}" as the heading font family. Add it via Google Fonts or your font provider.`,
+        });
+    }
+    // ── 7. Body font family ────────────────────────────────────────────────────
+    const subjectBodyFamily = subjectAnalysis.typeScale.bodyStyle.family.toLowerCase();
+    const referenceBodyFamily = referenceAnalysis.typeScale.bodyStyle.family.toLowerCase();
+    if (subjectBodyFamily && referenceBodyFamily && subjectBodyFamily !== referenceBodyFamily) {
+        gaps.push({
+            property: 'typeScale.bodyStyle.family',
+            description: 'Body font family differs',
+            subject: subjectAnalysis.typeScale.bodyStyle.family,
+            reference: referenceAnalysis.typeScale.bodyStyle.family,
+            severity: 'high',
+            suggestion: `Set body { font-family: "${referenceAnalysis.typeScale.bodyStyle.family}", sans-serif; }.`,
+        });
+    }
+    // ── 8. Body font weight ────────────────────────────────────────────────────
+    if (subjectAnalysis.typeScale.bodyStyle.weight !== referenceAnalysis.typeScale.bodyStyle.weight) {
+        gaps.push({
+            property: 'typeScale.bodyStyle.weight',
+            description: 'Body font weight differs',
+            subject: String(subjectAnalysis.typeScale.bodyStyle.weight),
+            reference: String(referenceAnalysis.typeScale.bodyStyle.weight),
+            severity: 'low',
+            suggestion: `Set body { font-weight: ${referenceAnalysis.typeScale.bodyStyle.weight}; }.`,
+        });
+    }
+    // ── 9. Modular type scale ──────────────────────────────────────────────────
+    if (!subjectAnalysis.typeScale.isModular && referenceAnalysis.typeScale.isModular) {
+        const referenceRatio = referenceAnalysis.typeScale.ratio;
+        gaps.push({
+            property: 'typeScale.isModular',
+            description: 'Reference uses a modular type scale; subject does not',
+            subject: 'non-modular',
+            reference: referenceRatio !== undefined ? `modular (ratio: ${referenceRatio})` : 'modular',
+            severity: 'medium',
+            suggestion: referenceRatio !== undefined
+                ? `Adopt a modular type scale with ratio ${referenceRatio}. Use a tool like https://type-scale.com to generate sizes.`
+                : 'Adopt a modular type scale for consistent typography.',
+        });
+    }
+    // ── 10. Box shadow presence ────────────────────────────────────────────────
+    const subjectHasShadows = subjectAnalysis.visualEffects.shadows.length > 0;
+    const referenceHasShadows = referenceAnalysis.visualEffects.shadows.length > 0;
+    if (!subjectHasShadows && referenceHasShadows) {
+        gaps.push({
+            property: 'visualEffects.shadows',
+            description: 'Reference uses box shadows; subject has none',
+            subject: 'no shadows',
+            reference: `${referenceAnalysis.visualEffects.shadows.length} shadow(s)`,
+            severity: 'low',
+            suggestion: 'Add subtle box-shadow to cards and interactive elements (e.g., box-shadow: 0 2px 8px rgba(0,0,0,0.1)).',
+        });
+    }
+    // ── 11. Gradient usage ─────────────────────────────────────────────────────
+    const subjectHasGradients = subjectAnalysis.visualEffects.gradients.length > 0;
+    const referenceHasGradients = referenceAnalysis.visualEffects.gradients.length > 0;
+    if (!subjectHasGradients && referenceHasGradients) {
+        gaps.push({
+            property: 'visualEffects.gradients',
+            description: 'Reference uses gradients; subject has none',
+            subject: 'no gradients',
+            reference: `${referenceAnalysis.visualEffects.gradients.length} gradient(s)`,
+            severity: 'low',
+            suggestion: 'Add CSS gradients to hero sections or accent elements to add visual depth.',
+        });
+    }
+    // ── 12. Spacing consistency quality signal ─────────────────────────────────
+    const spacingDiff = referenceAnalysis.qualitySignals.spacingConsistency -
+        subjectAnalysis.qualitySignals.spacingConsistency;
+    if (spacingDiff >= 0.2) {
+        gaps.push({
+            property: 'qualitySignals.spacingConsistency',
+            description: 'Spacing consistency is notably lower than the reference',
+            subject: String(subjectAnalysis.qualitySignals.spacingConsistency),
+            reference: String(referenceAnalysis.qualitySignals.spacingConsistency),
+            severity: spacingDiff >= 0.4 ? 'high' : 'medium',
+            suggestion: 'Align margin and padding values to a 4px or 8px grid for consistent spacing.',
+        });
+    }
+    // ── 13. Typography consistency quality signal ──────────────────────────────
+    const typoDiff = referenceAnalysis.qualitySignals.typographyConsistency -
+        subjectAnalysis.qualitySignals.typographyConsistency;
+    if (typoDiff >= 0.2) {
+        gaps.push({
+            property: 'qualitySignals.typographyConsistency',
+            description: 'Typography consistency is notably lower than the reference',
+            subject: String(subjectAnalysis.qualitySignals.typographyConsistency),
+            reference: String(referenceAnalysis.qualitySignals.typographyConsistency),
+            severity: typoDiff >= 0.4 ? 'high' : 'medium',
+            suggestion: 'Reduce the number of distinct font sizes and establish a clear type hierarchy.',
+        });
+    }
+    // ── 14. Color harmony quality signal ───────────────────────────────────────
+    const colorDiff = referenceAnalysis.qualitySignals.colorHarmony -
+        subjectAnalysis.qualitySignals.colorHarmony;
+    if (colorDiff >= 0.2) {
+        gaps.push({
+            property: 'qualitySignals.colorHarmony',
+            description: 'Color harmony is notably lower than the reference',
+            subject: String(subjectAnalysis.qualitySignals.colorHarmony),
+            reference: String(referenceAnalysis.qualitySignals.colorHarmony),
+            severity: colorDiff >= 0.4 ? 'high' : 'medium',
+            suggestion: 'Reduce the color palette to 3–5 primary colors. Use tints/shades instead of completely different hues.',
+        });
+    }
+    // ── 15. Visual hierarchy quality signal ───────────────────────────────────
+    const hierarchyDiff = referenceAnalysis.qualitySignals.visualHierarchy -
+        subjectAnalysis.qualitySignals.visualHierarchy;
+    if (hierarchyDiff >= 0.2) {
+        gaps.push({
+            property: 'qualitySignals.visualHierarchy',
+            description: 'Visual hierarchy is weaker than the reference',
+            subject: String(subjectAnalysis.qualitySignals.visualHierarchy),
+            reference: String(referenceAnalysis.qualitySignals.visualHierarchy),
+            severity: hierarchyDiff >= 0.4 ? 'high' : 'medium',
+            suggestion: 'Increase the h1 font size relative to body text (aim for 2× or more) to strengthen visual hierarchy.',
+        });
+    }
+    // ── Score calculation ──────────────────────────────────────────────────────
+    let score = 10;
+    for (const gap of gaps) {
+        score -= SEVERITY_DEDUCTIONS[gap.severity];
+    }
+    score = Math.max(1, Math.round(score * 10) / 10);
+    // ── Summary ───────────────────────────────────────────────────────────────
+    const highCount = gaps.filter((g) => g.severity === 'high').length;
+    const mediumCount = gaps.filter((g) => g.severity === 'medium').length;
+    const lowCount = gaps.filter((g) => g.severity === 'low').length;
+    let summary;
+    if (gaps.length === 0) {
+        summary = 'Subject closely matches the reference design. No significant gaps detected.';
+    }
+    else {
+        const parts = [];
+        if (highCount > 0)
+            parts.push(`${highCount} high-severity`);
+        if (mediumCount > 0)
+            parts.push(`${mediumCount} medium-severity`);
+        if (lowCount > 0)
+            parts.push(`${lowCount} low-severity`);
+        summary = `Found ${gaps.length} design gap${gaps.length === 1 ? '' : 's'} (${parts.join(', ')}) with a design score of ${score}/10.`;
+        if (highCount > 0) {
+            const highGaps = gaps.filter((g) => g.severity === 'high');
+            summary += ` Priority: ${highGaps.map((g) => g.property).join(', ')}.`;
+        }
+    }
+    return {
+        subjectUrl,
+        referenceUrl,
+        score,
+        gaps,
+        subjectAnalysis,
+        referenceAnalysis,
+        summary,
+    };
+}
+// ── Page-based wrapper ────────────────────────────────────────────────────────
+/**
+ * Compare the design of two Playwright pages by extracting design tokens from
+ * both in parallel, then diffing the tokens into a structured DesignComparison.
+ */
+export async function compareDesigns(subjectPage, referencePage) {
+    const [subjectAnalysis, referenceAnalysis] = await Promise.all([
+        extractDesignAnalysis(subjectPage),
+        extractDesignAnalysis(referencePage),
+    ]);
+    return buildDesignComparison(subjectPage.url(), referencePage.url(), subjectAnalysis, referenceAnalysis);
+}

package/dist/core/diff.d.ts

@@ -0,0 +1,61 @@
+/**
+ * WebPeel Diff - Semantic content diff against stored snapshots
+ *
+ * Fetches the current content of a URL, loads the previous snapshot from the
+ * change-tracking store, computes a structured diff (field-by-field for JSON,
+ * section-by-section for text/markdown), saves the new snapshot, and returns
+ * a structured {@link DiffResult}.
+ */
+export interface DiffOptions {
+    /** Compare against the last tracked snapshot (default behaviour). */
+    last?: boolean;
+    /** Only compare these dot-notation fields (for JSON responses only). */
+    fields?: string[];
+    /** Use browser rendering for the fetch. */
+    render?: boolean;
+    /** Per-request timeout in milliseconds (default: 30 000). */
+    timeout?: number;
+}
+export interface DiffResult {
+    url: string;
+    /** Whether any changes were detected. */
+    changed: boolean;
+    /** ISO-8601 timestamp of the current fetch. */
+    timestamp: string;
+    /** ISO-8601 timestamp of the previous snapshot (undefined if none). */
+    previousTimestamp?: string;
+    changes: DiffChange[];
+    /** Human-readable summary sentence. */
+    summary: string;
+}
+export interface DiffChange {
+    type: 'added' | 'removed' | 'modified';
+    /** For JSON diffs: dot-notation path to the changed field. */
+    field?: string;
+    /** For text diffs: nearest section heading or line reference. */
+    path?: string;
+    before?: string;
+    after?: string;
+}
+/**
+ * Fetch a URL and compute a semantic diff against the last tracked snapshot.
+ *
+ * The function:
+ * 1. Loads the previous snapshot (if any) from the change-tracking store.
+ * 2. Fetches the current content via {@link peel}.
+ * 3. Saves the current content as the new snapshot (auto-tracking).
+ * 4. Computes a structured diff — field-by-field for JSON, section-by-section
+ *    for text/markdown.
+ * 5. Returns a {@link DiffResult}.
+ *
+ * @example
+ * ```typescript
+ * const result = await diffUrl('https://api.example.com/health', { last: true });
+ * console.log(result.summary);
+ * result.changes.forEach(c => {
+ *   if (c.field) console.log(`${c.type}: ${c.field}  ${c.before} → ${c.after}`);
+ * });
+ * ```
+ */
+export declare function diffUrl(url: string, options?: DiffOptions): Promise<DiffResult>;
+export { trackChange, getSnapshot } from './change-tracking.js';

package/dist/core/diff.js

@@ -0,0 +1,289 @@
+/**
+ * WebPeel Diff - Semantic content diff against stored snapshots
+ *
+ * Fetches the current content of a URL, loads the previous snapshot from the
+ * change-tracking store, computes a structured diff (field-by-field for JSON,
+ * section-by-section for text/markdown), saves the new snapshot, and returns
+ * a structured {@link DiffResult}.
+ */
+import { peel } from '../index.js';
+import { getSnapshot } from './change-tracking.js';
+// ─── JSON diffing ──────────────────────────────────────────────────────────────
+/**
+ * Compare two JSON values recursively, returning structured {@link DiffChange}
+ * objects.  Non-object values (numbers, strings, arrays) are reported as atomic
+ * modifications.
+ *
+ * @param before   - Previous JSON value
+ * @param after    - Current JSON value
+ * @param path     - Current dot-notation path (for recursion; start with "")
+ * @param fields   - Optional allowlist of dot-notation paths to compare
+ */
+function diffJson(before, after, path = '', fields) {
+    const changes = [];
+    const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+    if (!isPlainObject(before) || !isPlainObject(after)) {
+        // Atomic comparison.
+        if (JSON.stringify(before) !== JSON.stringify(after)) {
+            if (!fields || fields.length === 0 || fields.some(f => f === path || path.startsWith(f + '.'))) {
+                changes.push({
+                    type: 'modified',
+                    field: path || '(root)',
+                    before: stringify(before),
+                    after: stringify(after),
+                });
+            }
+        }
+        return changes;
+    }
+    const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of allKeys) {
+        const fullPath = path ? `${path}.${key}` : key;
+        // Apply field filter when specified.
+        if (fields && fields.length > 0) {
+            const inScope = fields.some(f => fullPath === f || fullPath.startsWith(f + '.') || f.startsWith(fullPath + '.'));
+            if (!inScope)
+                continue;
+        }
+        const bVal = before[key];
+        const aVal = after[key];
+        if (bVal === undefined && aVal !== undefined) {
+            changes.push({ type: 'added', field: fullPath, after: stringify(aVal) });
+        }
+        else if (bVal !== undefined && aVal === undefined) {
+            changes.push({ type: 'removed', field: fullPath, before: stringify(bVal) });
+        }
+        else if (JSON.stringify(bVal) !== JSON.stringify(aVal)) {
+            // Recurse into nested objects.
+            if (isPlainObject(bVal) && isPlainObject(aVal)) {
+                changes.push(...diffJson(bVal, aVal, fullPath, fields));
+            }
+            else {
+                changes.push({
+                    type: 'modified',
+                    field: fullPath,
+                    before: stringify(bVal),
+                    after: stringify(aVal),
+                });
+            }
+        }
+    }
+    return changes;
+}
+/** Serialize a JSON value concisely for display. */
+function stringify(v) {
+    if (typeof v === 'string')
+        return v;
+    return JSON.stringify(v) ?? 'undefined';
+}
+/**
+ * Diff two text blobs line-by-line using LCS (Longest Common Subsequence).
+ * Groups consecutive additions/deletions into sections keyed by the nearest
+ * Markdown heading.
+ */
+function diffText(beforeText, afterText) {
+    const MAX_LINES = 5_000;
+    const bLines = beforeText.split('\n').slice(0, MAX_LINES);
+    const aLines = afterText.split('\n').slice(0, MAX_LINES);
+    // Build LCS table.
+    const m = bLines.length;
+    const n = aLines.length;
+    const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (bLines[i - 1] === aLines[j - 1]) {
+                lcs[i][j] = lcs[i - 1][j - 1] + 1;
+            }
+            else {
+                lcs[i][j] = Math.max(lcs[i - 1][j], lcs[i][j - 1]);
+            }
+        }
+    }
+    const ops = [];
+    let bi = m;
+    let ai = n;
+    while (bi > 0 || ai > 0) {
+        if (bi > 0 && ai > 0 && bLines[bi - 1] === aLines[ai - 1]) {
+            ops.unshift({ op: 'same', line: aLines[ai - 1] });
+            bi--;
+            ai--;
+        }
+        else if (ai > 0 && (bi === 0 || lcs[bi][ai - 1] >= lcs[bi - 1][ai])) {
+            ops.unshift({ op: 'add', line: aLines[ai - 1] });
+            ai--;
+        }
+        else {
+            ops.unshift({ op: 'del', line: bLines[bi - 1] });
+            bi--;
+        }
+    }
+    // Group consecutive non-same ops into sections.
+    const changes = [];
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    let i = 0;
+    while (i < ops.length) {
+        if (ops[i].op === 'same') {
+            i++;
+            continue;
+        }
+        // Collect the run of changes.
+        const added = [];
+        const removed = [];
+        while (i < ops.length && ops[i].op !== 'same') {
+            if (ops[i].op === 'add')
+                added.push(ops[i].line);
+            if (ops[i].op === 'del')
+                removed.push(ops[i].line);
+            i++;
+        }
+        linesAdded += added.length;
+        linesRemoved += removed.length;
+        // Find nearest Markdown heading in the 'same' lines before this block.
+        let sectionLabel = `line ~${i}`;
+        for (let k = i - added.length - removed.length - 1; k >= 0; k--) {
+            const prevOp = ops[k];
+            if (prevOp && prevOp.op === 'same' && /^#{1,6}\s/.test(prevOp.line)) {
+                sectionLabel = prevOp.line.trim();
+                break;
+            }
+        }
+        if (removed.length > 0 && added.length > 0) {
+            changes.push({ type: 'modified', path: sectionLabel, before: removed.join('\n'), after: added.join('\n') });
+        }
+        else if (added.length > 0) {
+            changes.push({ type: 'added', path: sectionLabel, after: added.join('\n') });
+        }
+        else if (removed.length > 0) {
+            changes.push({ type: 'removed', path: sectionLabel, before: removed.join('\n') });
+        }
+    }
+    return { changes, stats: { linesAdded, linesRemoved } };
+}
+// ─── Summary generation ────────────────────────────────────────────────────────
+function buildSummary(changes, mode, jsonTotalFields, textStats) {
+    if (changes.length === 0)
+        return 'No changes detected.';
+    if (mode === 'json') {
+        const unchanged = Math.max(0, (jsonTotalFields ?? 0) - changes.length);
+        const parts = [
+            `${changes.length} field${changes.length === 1 ? '' : 's'} changed`,
+        ];
+        if (unchanged > 0)
+            parts.push(`${unchanged} unchanged`);
+        return parts.join(', ') + '.';
+    }
+    // Text mode.
+    const sections = changes.length;
+    const added = textStats?.linesAdded ?? 0;
+    const removed = textStats?.linesRemoved ?? 0;
+    return (`${sections} section${sections === 1 ? '' : 's'} changed` +
+        (added > 0 ? `, ${added} lines added` : '') +
+        (removed > 0 ? `, ${removed} removed` : '') +
+        '.');
+}
+// ─── Key counting helpers ──────────────────────────────────────────────────────
+/** Count the total number of leaf-level keys (dot-notation) in two JSON objects combined. */
+function countTotalFields(a, b) {
+    const keys = new Set();
+    collectKeys(a, '', keys);
+    collectKeys(b, '', keys);
+    return keys.size;
+}
+function collectKeys(obj, prefix, acc) {
+    if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+        if (prefix)
+            acc.add(prefix);
+        return;
+    }
+    for (const key of Object.keys(obj)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        acc.add(path);
+        collectKeys(obj[key], path, acc);
+    }
+}
+// ─── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Fetch a URL and compute a semantic diff against the last tracked snapshot.
+ *
+ * The function:
+ * 1. Loads the previous snapshot (if any) from the change-tracking store.
+ * 2. Fetches the current content via {@link peel}.
+ * 3. Saves the current content as the new snapshot (auto-tracking).
+ * 4. Computes a structured diff — field-by-field for JSON, section-by-section
+ *    for text/markdown.
+ * 5. Returns a {@link DiffResult}.
+ *
+ * @example
+ * ```typescript
+ * const result = await diffUrl('https://api.example.com/health', { last: true });
+ * console.log(result.summary);
+ * result.changes.forEach(c => {
+ *   if (c.field) console.log(`${c.type}: ${c.field}  ${c.before} → ${c.after}`);
+ * });
+ * ```
+ */
+export async function diffUrl(url, options = {}) {
+    const { fields, render = false, timeout = 30_000 } = options;
+    // 1. Load previous snapshot before fetching (fetch overwrites it).
+    const prevSnapshot = await getSnapshot(url);
+    // 2. Fetch current content.  changeTracking: true auto-saves the new snapshot.
+    const result = await peel(url, {
+        render,
+        timeout,
+        format: 'markdown',
+        changeTracking: true,
+    });
+    const now = new Date().toISOString();
+    // 3. No baseline → return an informational result.
+    if (!prevSnapshot) {
+        return {
+            url: result.url,
+            changed: false,
+            timestamp: now,
+            changes: [],
+            summary: 'No previous snapshot found. Current content saved as baseline.',
+        };
+    }
+    const previousTimestamp = new Date(prevSnapshot.timestamp).toISOString();
+    const previousContent = prevSnapshot.content;
+    const currentContent = result.content;
+    // 4. Detect content type and compute appropriate diff.
+    let mode = 'text';
+    let changes = [];
+    let jsonTotalFields = 0;
+    let textStats;
+    let prevJson = null;
+    let currJson = null;
+    try {
+        prevJson = JSON.parse(previousContent);
+        currJson = JSON.parse(currentContent);
+        mode = 'json';
+    }
+    catch (e) {
+        if (process.env.DEBUG)
+            console.debug('[webpeel]', 'json parse failed:', e instanceof Error ? e.message : e);
+    }
+    if (mode === 'json' && prevJson !== null && currJson !== null) {
+        changes = diffJson(prevJson, currJson, '', fields);
+        jsonTotalFields = countTotalFields(prevJson, currJson);
+    }
+    else {
+        const { changes: textChanges, stats } = diffText(previousContent, currentContent);
+        changes = textChanges;
+        textStats = stats;
+    }
+    // 5. Handle edge case: content changed but we couldn't detect it (e.g. fingerprint
+    //    mismatch recorded by peel, but diff shows no changes at field level).
+    const changed = changes.length > 0;
+    return {
+        url: result.url,
+        changed,
+        timestamp: now,
+        previousTimestamp,
+        changes,
+        summary: buildSummary(changes, mode, jsonTotalFields, textStats),
+    };
+}
+// ─── Re-export trackChange for CLI convenience ─────────────────────────────────
+export { trackChange, getSnapshot } from './change-tracking.js';

package/dist/core/dns-cache.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DNS Pre-Resolution Cache
+ *
+ * Warms a local Map<hostname, ip[]> on startup for the top ~50 popular domains
+ * and exposes a custom lookup function compatible with undici's Agent `connect.lookup`.
+ */
+import dns from 'node:dns';
+export declare function getCachedDns(hostname: string): string[] | null;
+export declare function resolveAndCache(hostname: string): Promise<string[]>;
+/**
+ * Custom lookup function compatible with undici's Agent `connect.lookup`.
+ *
+ * undici passes `{ hints: 1024, all: true }` — so when `all` is true the
+ * callback must receive `(err, entries: { address, family }[])`.
+ * When `all` is false (or absent), the callback is `(err, address, family)`.
+ */
+export declare function cachedLookup(hostname: string, options: dns.LookupOptions, callback: (...args: any[]) => void): void;
+export declare function warmupDnsCache(domains?: string[]): Promise<void>;
+export declare function startDnsWarmup(): void;
+export declare function clearDnsCache(): void;