autokap 1.0.7 → 1.0.8

package/dist/dom-font-inliner.js

@@ -0,0 +1,148 @@
+/**
+ * DOM Font Inliner — AUT-121 Interactive Demos, Phase 3.4
+ *
+ * Walks captured HTML, finds `@font-face { src: url(...) }` references inside
+ * inline `<style>` blocks, fetches each font, and base64-inlines fonts whose
+ * size is below a configurable threshold (default 100kb). Larger fonts are
+ * left untouched — the Linear issue mentions "Base64 OU stockage dédié" as
+ * alternatives, so the threshold lets the caller pick whichever fits.
+ *
+ * Pure module: the actual fetching is delegated via a `fetcher` callback so
+ * this file stays dependency-free and unit-testable. Server-side wiring
+ * passes a Supabase-aware fetcher.
+ */
+import { parse, serialize } from 'parse5';
+/** Maximum bytes a font can have to be inlined as base64. */
+export const DEFAULT_FONT_INLINE_THRESHOLD = 100 * 1024;
+/**
+ * Walk an HTML document, scan every inline `<style>` block for `@font-face`
+ * `url(...)` references, fetch and base64-inline each one whose payload size
+ * is below the threshold.
+ */
+export async function inlineFontFaceUrls(html, options) {
+    const stats = {
+        scanned: 0,
+        inlined: 0,
+        skipped: 0,
+        inlinedBytes: 0,
+    };
+    const document = parse(html);
+    const styleNodes = [];
+    walk(document, (node) => {
+        if (isElement(node) && node.tagName === 'style') {
+            styleNodes.push(node);
+        }
+    });
+    for (const styleNode of styleNodes) {
+        const text = readText(styleNode);
+        if (!text || text.indexOf('@font-face') === -1)
+            continue;
+        const urls = extractFontFaceUrls(text);
+        if (urls.length === 0)
+            continue;
+        stats.scanned += urls.length;
+        const replacements = new Map();
+        for (const url of urls) {
+            try {
+                const fetched = await options.fetcher(url);
+                if (!fetched) {
+                    stats.skipped += 1;
+                    continue;
+                }
+                const limit = options.thresholdBytes ?? DEFAULT_FONT_INLINE_THRESHOLD;
+                if (fetched.buffer.length > limit) {
+                    stats.skipped += 1;
+                    continue;
+                }
+                const base64 = fetched.buffer.toString('base64');
+                replacements.set(url, `data:${fetched.mimeType};base64,${base64}`);
+                stats.inlined += 1;
+                stats.inlinedBytes += fetched.buffer.length;
+            }
+            catch {
+                stats.skipped += 1;
+            }
+        }
+        if (replacements.size > 0) {
+            const rewritten = rewriteCssUrls(text, replacements);
+            setText(styleNode, rewritten);
+        }
+    }
+    return {
+        html: serialize(document),
+        stats,
+    };
+}
+/**
+ * Extract every `url(...)` token that appears inside `@font-face { src: ... }`
+ * declarations. Returns the URLs in the order they appear.
+ */
+export function extractFontFaceUrls(css) {
+    const out = [];
+    // Match @font-face { ... } blocks (non-greedy)
+    const blockRe = /@font-face\s*\{([^}]+)\}/gi;
+    let match;
+    while ((match = blockRe.exec(css)) !== null) {
+        const body = match[1];
+        const urlRe = /url\(\s*(?:"([^"]+)"|'([^']+)'|([^\s)]+))\s*\)/gi;
+        let urlMatch;
+        while ((urlMatch = urlRe.exec(body)) !== null) {
+            const url = urlMatch[1] ?? urlMatch[2] ?? urlMatch[3] ?? '';
+            if (url && !url.startsWith('data:') && out.indexOf(url) === -1) {
+                out.push(url);
+            }
+        }
+    }
+    return out;
+}
+function rewriteCssUrls(css, replacements) {
+    return css.replace(/url\(\s*(?:"([^"]+)"|'([^']+)'|([^\s)]+))\s*\)/g, (match, quoted, quotedSingle, bare) => {
+        const original = quoted ?? quotedSingle ?? bare;
+        const replacement = replacements.get(original);
+        if (!replacement)
+            return match;
+        return `url("${replacement}")`;
+    });
+}
+// ── parse5 helpers (mirrors dom-serializer.ts / dom-css-purger.ts) ──
+function isElement(node) {
+    return node.tagName !== undefined && node.attrs !== undefined;
+}
+function isParentNode(node) {
+    return Array.isArray(node.childNodes);
+}
+function walk(root, visit) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        visit(node);
+        if (!isParentNode(node))
+            continue;
+        for (let i = node.childNodes.length - 1; i >= 0; i -= 1) {
+            stack.push(node.childNodes[i]);
+        }
+    }
+}
+function readText(element) {
+    let text = '';
+    for (const child of element.childNodes) {
+        const node = child;
+        if (node.nodeName === '#text' && typeof node.value === 'string') {
+            text += node.value;
+        }
+    }
+    return text;
+}
+function setText(element, value) {
+    for (let i = element.childNodes.length - 1; i >= 0; i -= 1) {
+        const child = element.childNodes[i];
+        child.parentNode = null;
+    }
+    element.childNodes = [];
+    element.childNodes.push({
+        nodeName: '#text',
+        value,
+        parentNode: element,
+    });
+}
+//# sourceMappingURL=dom-font-inliner.js.map

package/dist/dom-patch-resolver.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Photoshop DOM patch resolver (AUT-120, Phase 1).
+ *
+ * Resolves a DomPatchSpec.target to a live element by walking the live AKTree.
+ * Returns the AKNode's sourceRef (CSS selector) for the runner to use, or
+ * `null` if the cascade exhausts all fallbacks. Resolution is non-fatal —
+ * callers convert null into a soft-skip with a warning.
+ *
+ * Cascade order:
+ *   1. fingerprint (bounds-stripped) — best, robust to layout shifts
+ *   2. sourceRef — recorded selector, cheap and direct
+ *   3. structuralPath — CSS path from root, used when sourceRef rotted
+ *   4. exactText — last-resort match against AKNode.label
+ *
+ * On multi-match at any step, picks the closest by bounds proximity using
+ * the patch's stored `target.bounds` as the anchor.
+ */
+import type { DomPatchSpec, ExecutionOpcode, RuntimeAdapter } from './execution-types.js';
+import type { AKTree } from './types.js';
+/**
+ * Walks the live AKTree and returns the sourceRef of the best match for the
+ * patch's target, or `null` if nothing matches.
+ */
+export declare function resolvePatchTarget(patch: DomPatchSpec, tree: AKTree): string | null;
+/**
+ * Builds a transient ExecutionOpcode that the runner can dispatch via
+ * `executeOpcodeCoreAction`. The opcode is marked as soft and uses the
+ * lightest postcondition so resolution failures don't propagate as errors.
+ */
+export declare function expandPatchToOpcode(patch: DomPatchSpec, selector: string): ExecutionOpcode | null;
+/**
+ * Filter patches relevant to the current variant. A NULL filter ("any value")
+ * matches everything; a specific value matches exactly. The patches are
+ * returned in `ordering` order so collisions resolve deterministically.
+ */
+export declare function filterPatchesForVariant(patches: DomPatchSpec[] | undefined, variant: {
+    locale?: string;
+    theme?: 'light' | 'dark';
+    targetId?: string;
+}): DomPatchSpec[];
+/**
+ * Resolves and applies all DOM patches matching the current variant. Each
+ * patch is independent — a resolution failure logs a warning and the next
+ * patch still runs. Returns a tally of applied / skipped counts for telemetry.
+ */
+export declare function applyDomPatches(patches: DomPatchSpec[], adapter: RuntimeAdapter, executor: (opcode: ExecutionOpcode) => Promise<{
+    success: boolean;
+    error?: string;
+}>, logger?: (level: 'warn' | 'info', msg: string) => void): Promise<{
+    applied: number;
+    skipped: number;
+}>;

package/dist/dom-patch-resolver.js

@@ -0,0 +1,242 @@
+/**
+ * Photoshop DOM patch resolver (AUT-120, Phase 1).
+ *
+ * Resolves a DomPatchSpec.target to a live element by walking the live AKTree.
+ * Returns the AKNode's sourceRef (CSS selector) for the runner to use, or
+ * `null` if the cascade exhausts all fallbacks. Resolution is non-fatal —
+ * callers convert null into a soft-skip with a warning.
+ *
+ * Cascade order:
+ *   1. fingerprint (bounds-stripped) — best, robust to layout shifts
+ *   2. sourceRef — recorded selector, cheap and direct
+ *   3. structuralPath — CSS path from root, used when sourceRef rotted
+ *   4. exactText — last-resort match against AKNode.label
+ *
+ * On multi-match at any step, picks the closest by bounds proximity using
+ * the patch's stored `target.bounds` as the anchor.
+ */
+import { fingerprintAKNodeForPatch, flattenAKNodes } from './ak-tree.js';
+/**
+ * Walks the live AKTree and returns the sourceRef of the best match for the
+ * patch's target, or `null` if nothing matches.
+ */
+export function resolvePatchTarget(patch, tree) {
+    const nodes = flattenAKNodes(tree.root);
+    // 1. Fingerprint match (bounds-stripped) — most resilient.
+    if (patch.target.fingerprint) {
+        const matches = nodes.filter((n) => fingerprintAKNodeForPatch(toFingerprintInput(n)) === patch.target.fingerprint);
+        const picked = pickByProximity(matches, patch.target.bounds);
+        if (picked)
+            return picked.sourceRef;
+    }
+    // 2. sourceRef match against the live AKTree.
+    if (patch.target.sourceRef) {
+        const matches = nodes.filter((n) => n.sourceRef === patch.target.sourceRef);
+        const picked = pickByProximity(matches, patch.target.bounds);
+        if (picked)
+            return picked.sourceRef;
+    }
+    // 3. Structural path match against the live AKTree.
+    if (patch.target.structuralPath && patch.target.structuralPath !== patch.target.sourceRef) {
+        const matches = nodes.filter((n) => n.sourceRef === patch.target.structuralPath);
+        const picked = pickByProximity(matches, patch.target.bounds);
+        if (picked)
+            return picked.sourceRef;
+    }
+    // 4. Exact text — find the AKNode whose label matches verbatim, or
+    //    contains the wanted text as a fallback (handles whitespace drift).
+    if (patch.target.exactText) {
+        const wanted = patch.target.exactText.trim();
+        if (wanted.length > 0) {
+            const exactMatches = nodes.filter((n) => n.label.trim() === wanted);
+            const exactPicked = pickByProximity(exactMatches, patch.target.bounds);
+            if (exactPicked)
+                return exactPicked.sourceRef;
+            const partialMatches = nodes.filter((n) => n.label && n.label.includes(wanted));
+            const partialPicked = pickByProximity(partialMatches, patch.target.bounds);
+            if (partialPicked)
+                return partialPicked.sourceRef;
+        }
+    }
+    // LAST RESORT: trust the recorded selectors even if no AKTree node carries
+    // them. The runtime will try `document.querySelector` directly. If the page
+    // has evolved structurally this may resolve to the wrong element — the
+    // calling opcode (e.g. replaceText) will then fail loudly with the live
+    // textContent so the user can see what's actually there.
+    if (patch.target.sourceRef)
+        return patch.target.sourceRef;
+    if (patch.target.structuralPath)
+        return patch.target.structuralPath;
+    return null;
+}
+/**
+ * Builds a transient ExecutionOpcode that the runner can dispatch via
+ * `executeOpcodeCoreAction`. The opcode is marked as soft and uses the
+ * lightest postcondition so resolution failures don't propagate as errors.
+ */
+export function expandPatchToOpcode(patch, selector) {
+    const base = {
+        description: `dom patch ${patch.id}`,
+        postcondition: { type: 'always' },
+        recovery: {
+            retries: 0,
+            useSelectorMemory: false,
+            useAltInteraction: false,
+            allowReload: false,
+            allowHealer: false,
+        },
+        timeoutMs: 5000,
+        maxFailures: 1,
+    };
+    switch (patch.kind) {
+        case 'REPLACE_TEXT':
+            if (patch.from === undefined || patch.to === undefined)
+                return null;
+            return {
+                kind: 'REPLACE_TEXT',
+                ...base,
+                selector,
+                fromText: patch.from,
+                toText: patch.to,
+            };
+        case 'SET_TEXT':
+            if (patch.to === undefined)
+                return null;
+            return {
+                kind: 'SET_TEXT',
+                ...base,
+                selector,
+                text: patch.to,
+            };
+        case 'HIDE':
+            return {
+                kind: 'HIDE',
+                ...base,
+                selector,
+            };
+        case 'SET_STYLE':
+            if (!patch.property || patch.styleValue === undefined)
+                return null;
+            return {
+                kind: 'SET_STYLE',
+                ...base,
+                selector,
+                property: patch.property,
+                value: patch.styleValue,
+            };
+        case 'SET_ATTRIBUTE':
+            if (!patch.attribute || patch.value === undefined)
+                return null;
+            return {
+                kind: 'SET_ATTRIBUTE',
+                ...base,
+                selector,
+                attribute: patch.attribute,
+                value: patch.value,
+            };
+        case 'REMOVE_ELEMENT':
+            return {
+                kind: 'REMOVE_ELEMENT',
+                ...base,
+                selector,
+            };
+        default: {
+            // Exhaustive check
+            const _exhaustive = patch.kind;
+            return null;
+        }
+    }
+}
+/**
+ * Filter patches relevant to the current variant. A NULL filter ("any value")
+ * matches everything; a specific value matches exactly. The patches are
+ * returned in `ordering` order so collisions resolve deterministically.
+ */
+export function filterPatchesForVariant(patches, variant) {
+    if (!patches || patches.length === 0)
+        return [];
+    return patches
+        .filter((p) => {
+        if (p.variantLang && variant.locale && p.variantLang !== variant.locale)
+            return false;
+        if (p.variantTheme && variant.theme && p.variantTheme !== variant.theme)
+            return false;
+        if (p.variantTargetId && variant.targetId && p.variantTargetId !== variant.targetId)
+            return false;
+        return true;
+    })
+        .slice()
+        .sort((a, b) => a.ordering - b.ordering);
+}
+/**
+ * Resolves and applies all DOM patches matching the current variant. Each
+ * patch is independent — a resolution failure logs a warning and the next
+ * patch still runs. Returns a tally of applied / skipped counts for telemetry.
+ */
+export async function applyDomPatches(patches, adapter, executor, logger) {
+    if (patches.length === 0)
+        return { applied: 0, skipped: 0 };
+    let tree = null;
+    try {
+        tree = await adapter.getAKTree();
+    }
+    catch (err) {
+        logger?.('warn', `dom-patches: failed to fetch AKTree, skipping ${patches.length} patch(es): ${err instanceof Error ? err.message : String(err)}`);
+        return { applied: 0, skipped: patches.length };
+    }
+    let applied = 0;
+    let skipped = 0;
+    for (const patch of patches) {
+        const selector = resolvePatchTarget(patch, tree);
+        if (!selector) {
+            skipped++;
+            logger?.('warn', `dom-patches: patch ${patch.id} (${patch.kind}) could not be resolved (no match)`);
+            continue;
+        }
+        const opcode = expandPatchToOpcode(patch, selector);
+        if (!opcode) {
+            skipped++;
+            logger?.('warn', `dom-patches: patch ${patch.id} (${patch.kind}) has incomplete payload, skipped`);
+            continue;
+        }
+        const result = await executor(opcode);
+        if (result.success) {
+            applied++;
+        }
+        else {
+            skipped++;
+            logger?.('warn', `dom-patches: patch ${patch.id} (${patch.kind}) failed: ${result.error ?? 'unknown error'}`);
+        }
+    }
+    return { applied, skipped };
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function toFingerprintInput(node) {
+    return {
+        tagName: node.attributes.tagName?.toLowerCase() || node.type,
+        role: node.attributes.role,
+        textContent: node.label,
+        ariaLabel: node.attributes['aria-label'],
+        htmlId: node.attributes.id,
+        name: node.attributes.name,
+        inputType: node.attributes.type,
+        href: node.attributes.href,
+        placeholder: node.attributes.placeholder,
+        bounds: node.bounds,
+    };
+}
+function pickByProximity(candidates, anchor) {
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length === 1)
+        return candidates[0];
+    if (!anchor)
+        return candidates[0];
+    const score = (n) => {
+        const dx = n.bounds.x - anchor.x;
+        const dy = n.bounds.y - anchor.y;
+        return dx * dx + dy * dy;
+    };
+    return candidates.slice().sort((a, b) => score(a) - score(b))[0];
+}
+//# sourceMappingURL=dom-patch-resolver.js.map

package/dist/dom-serializer.d.ts

@@ -0,0 +1,82 @@
+/**
+ * DOM Serializer — AUT-121 Interactive Demos
+ *
+ * Pure functions that take a raw HTML snapshot from Playwright
+ * (`document.documentElement.outerHTML`) and produce a sanitized HTML string
+ * suitable for client-side replay by the demo player.
+ *
+ * Phase 1 responsibilities:
+ *   - Strip every `<script>` element (security + we never replay JS)
+ *   - Strip every `on*` event handler attribute
+ *   - Strip cross-origin `<iframe>` elements (XSS surface)
+ *   - Strip `<link rel="modulepreload">` and `<link rel="preload" as="script">`
+ *   - Strip framework dev overlays (Next.js, Vite, Astro, Nuxt) — same set as
+ *     `cookie-dismiss.ts`'s `DEV_TOOL_SELECTORS`, just removed instead of hidden
+ *   - Collect every asset URL referenced from `<img src|srcset>`,
+ *     `<source src|srcset>`, `<link rel="stylesheet" href>`. Phase 3 will
+ *     resolve these via CAS — Phase 1 only records them for telemetry.
+ *
+ * Out of scope for Phase 1: PurgeCSS, font inlining, CSS `url(...)` extraction,
+ * Brotli. Those land in Phase 3.
+ */
+export interface RawDomCapture {
+    /** Raw HTML, typically `document.documentElement.outerHTML` from Playwright */
+    html: string;
+    /** Page URL at the moment of capture, used to resolve relative asset URLs and same-origin iframes */
+    baseUrl: string;
+    /** Viewport dimensions of the captured page */
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export interface SerializedDom {
+    /** Post-sanitization HTML, ready to be replayed by the demo player */
+    html: string;
+    /** Absolute URLs of assets referenced by the captured DOM */
+    assetUrls: string[];
+    /** Byte length of the sanitized HTML */
+    htmlBytes: number;
+    /** Stats counters for telemetry */
+    removed: {
+        scripts: number;
+        eventHandlers: number;
+        iframes: number;
+        devOverlays: number;
+        preloads: number;
+    };
+    /** How many `<a>` / `<form>` navigation targets were neutralized */
+    neutralized: {
+        links: number;
+        forms: number;
+    };
+}
+/**
+ * Rewrite asset URLs (img/source/srcset, link rel=stylesheet) inside an HTML
+ * string using a `originalUrl → replacementUrl` map. URLs not in the map are
+ * left untouched. Used by Phase 3 to point captured DOMs at CAS-backed
+ * permanent URLs after asset extraction.
+ */
+export declare function rewriteAssetUrls(html: string, replacements: Map<string, string>): string;
+/** Sanitize a raw DOM snapshot and return the cleaned HTML + asset manifest. */
+export declare function sanitizeDom(raw: RawDomCapture): SerializedDom;
+export interface RawFragmentCapture {
+    /** Raw `outerHTML` of the captured subtree (a single root element). */
+    html: string;
+    /** Page URL at the moment of capture, used to resolve relative asset URLs. */
+    baseUrl: string;
+}
+export interface SerializedFragment {
+    html: string;
+    assetUrls: string[];
+    htmlBytes: number;
+    removed: SerializedDom['removed'];
+    neutralized: SerializedDom['neutralized'];
+}
+/**
+ * Sanitize a single subtree captured via `CAPTURE_FRAGMENT`. Same passes as
+ * {@link sanitizeDom} (strip scripts, on*, dev overlays, third-party iframes,
+ * neutralize anchors / forms, collect asset URLs) but operates on a fragment
+ * — no `<html>` / `<head>` / `<body>` shell. Phase 5 of AUT-121.
+ */
+export declare function sanitizeFragment(raw: RawFragmentCapture): SerializedFragment;