autokap 1.0.6 → 1.0.8

package/dist/dom-serializer.js

@@ -0,0 +1,378 @@
+/**
+ * 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.
+ */
+import { parse, parseFragment, serialize, defaultTreeAdapter, } from 'parse5';
+/**
+ * Selectors of dev tooling overlays we want to strip from captured DOMs.
+ * Mirrors the list in `cookie-dismiss.ts`. Each entry is matched as either
+ * a tag name (e.g. `nextjs-portal`) or an `#id` selector — anything more
+ * complex must be added by hand to {@link matchesDevSelector}.
+ */
+const DEV_TOOL_TAGS = new Set([
+    'nextjs-portal',
+    'astro-dev-toolbar',
+    'vite-error-overlay',
+    'vite-plugin-checker-error-overlay',
+    'nuxt-devtools',
+    'nuxt-devtools-frame',
+]);
+const DEV_TOOL_IDS = new Set([
+    '__next-build-watcher',
+    'nuxt-devtools-anchor',
+    'nuxt-devtools-container',
+]);
+const DEV_TOOL_DATA_ATTRS = new Set([
+    'data-next-badge-root',
+]);
+/**
+ * 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 function rewriteAssetUrls(html, replacements) {
+    if (replacements.size === 0)
+        return html;
+    const document = parse(html);
+    walk(document, (node) => {
+        if (!isElement(node))
+            return;
+        if (node.tagName === "img" || node.tagName === "source") {
+            replaceAttr(node, "src", replacements);
+            replaceSrcset(node, replacements);
+        }
+        else if (node.tagName === "link") {
+            const rel = (getAttr(node, "rel") ?? "").toLowerCase();
+            if (rel === "stylesheet") {
+                replaceAttr(node, "href", replacements);
+            }
+        }
+    });
+    return serialize(document);
+}
+function replaceAttr(element, name, replacements) {
+    for (const attr of element.attrs) {
+        if (attr.name === name) {
+            const replacement = replacements.get(attr.value);
+            if (replacement)
+                attr.value = replacement;
+        }
+    }
+}
+function replaceSrcset(element, replacements) {
+    for (const attr of element.attrs) {
+        if (attr.name !== "srcset")
+            continue;
+        const candidates = attr.value.split(",").map((entry) => entry.trim());
+        const next = candidates.map((entry) => {
+            const parts = entry.split(/\s+/);
+            const url = parts[0];
+            const replacement = replacements.get(url);
+            if (replacement) {
+                parts[0] = replacement;
+                return parts.join(" ");
+            }
+            return entry;
+        });
+        attr.value = next.join(", ");
+    }
+}
+/** Sanitize a raw DOM snapshot and return the cleaned HTML + asset manifest. */
+export function sanitizeDom(raw) {
+    const document = parse(raw.html);
+    const result = walkAndSanitize(document, raw.baseUrl);
+    const html = serialize(document);
+    return {
+        html,
+        assetUrls: result.assetUrls,
+        htmlBytes: Buffer.byteLength(html, 'utf8'),
+        removed: result.removed,
+        neutralized: result.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 function sanitizeFragment(raw) {
+    const fragment = parseFragment(raw.html);
+    const result = walkAndSanitize(fragment, raw.baseUrl);
+    const html = serialize(fragment);
+    return {
+        html,
+        assetUrls: result.assetUrls,
+        htmlBytes: Buffer.byteLength(html, 'utf8'),
+        removed: result.removed,
+        neutralized: result.neutralized,
+    };
+}
+function walkAndSanitize(root, baseUrl) {
+    const stats = {
+        scripts: 0,
+        eventHandlers: 0,
+        iframes: 0,
+        devOverlays: 0,
+        preloads: 0,
+    };
+    const neutralized = {
+        links: 0,
+        forms: 0,
+    };
+    const assetUrls = new Set();
+    const baseOrigin = safeOrigin(baseUrl);
+    walk(root, (node, parent) => {
+        if (!isElement(node))
+            return;
+        // 1. Drop scripts entirely
+        if (node.tagName === 'script') {
+            removeChild(parent, node);
+            stats.scripts += 1;
+            return;
+        }
+        // 2. Drop dev tool overlays entirely
+        if (matchesDevSelector(node)) {
+            removeChild(parent, node);
+            stats.devOverlays += 1;
+            return;
+        }
+        // 3. Drop cross-origin iframes
+        if (node.tagName === 'iframe') {
+            const src = getAttr(node, 'src');
+            if (src && !isSameOriginUrl(src, baseOrigin)) {
+                removeChild(parent, node);
+                stats.iframes += 1;
+                return;
+            }
+        }
+        // 4. Drop preload/modulepreload links pointing to scripts, and manifest links
+        if (node.tagName === 'link') {
+            const rel = (getAttr(node, 'rel') ?? '').toLowerCase();
+            const asAttr = (getAttr(node, 'as') ?? '').toLowerCase();
+            if (rel === 'modulepreload' || (rel === 'preload' && (asAttr === 'script' || asAttr === 'font'))) {
+                removeChild(parent, node);
+                stats.preloads += 1;
+                return;
+            }
+            // Drop manifest links — they reference app-specific JSON that won't
+            // exist when the captured HTML is served from the demo player.
+            if (rel === 'manifest') {
+                removeChild(parent, node);
+                stats.preloads += 1;
+                return;
+            }
+            // Stylesheet links contribute to the asset manifest
+            if (rel === 'stylesheet') {
+                const href = getAttr(node, 'href');
+                const absolute = absolutize(href, baseUrl);
+                if (absolute)
+                    assetUrls.add(absolute);
+            }
+        }
+        // 5. Strip every on* attribute (case-insensitive)
+        const removed = stripEventHandlers(node);
+        stats.eventHandlers += removed;
+        // 6. Collect asset URLs from img/source
+        if (node.tagName === 'img' || node.tagName === 'source') {
+            const src = getAttr(node, 'src');
+            const absolute = absolutize(src, baseUrl);
+            if (absolute)
+                assetUrls.add(absolute);
+            const srcset = getAttr(node, 'srcset');
+            if (srcset) {
+                for (const candidate of parseSrcset(srcset)) {
+                    const abs = absolutize(candidate, baseUrl);
+                    if (abs)
+                        assetUrls.add(abs);
+                }
+            }
+        }
+        // 7. Neutralize anchor navigation. We keep the visual styling (cursor,
+        //    underline, etc.) but rewrite the href to a no-op so the iframe
+        //    sandbox doesn't try to navigate to a route that doesn't exist.
+        //    The original target is preserved in `data-ak-original-href` for
+        //    debugging and possible Phase 5 "open in a new tab" behavior.
+        //
+        //    In-page anchors (`#anything`) are left alone — they let the user
+        //    scroll to a section within the same captured DOM.
+        if (node.tagName === 'a') {
+            const originalHref = getAttr(node, 'href');
+            if (originalHref !== undefined && !originalHref.startsWith('#')) {
+                rewriteAttr(node, 'href', '#');
+                setAttrIfMissing(node, 'data-ak-original-href', originalHref);
+                neutralized.links += 1;
+            }
+            // Strip target so even keyboard activation can't open new tabs.
+            removeAttr(node, 'target');
+            removeAttr(node, 'rel');
+            removeAttr(node, 'download');
+        }
+        // 8. Neutralize form submissions for the same reason.
+        if (node.tagName === 'form') {
+            const action = getAttr(node, 'action');
+            if (action !== undefined) {
+                rewriteAttr(node, 'action', '#');
+                setAttrIfMissing(node, 'data-ak-original-action', action);
+                neutralized.forms += 1;
+            }
+            removeAttr(node, 'target');
+        }
+    });
+    return {
+        assetUrls: Array.from(assetUrls),
+        removed: stats,
+        neutralized,
+    };
+}
+// ── Tree helpers ────────────────────────────────────────────────────
+function isElement(node) {
+    return node.tagName !== undefined && node.attrs !== undefined;
+}
+function isParentNode(node) {
+    return Array.isArray(node.childNodes);
+}
+/**
+ * Depth-first walker. Visits each node BEFORE descending. The callback
+ * receives the node and its parent. Removed nodes are not descended into.
+ */
+function walk(root, visit) {
+    const stack = [
+        { node: root, parent: null },
+    ];
+    while (stack.length > 0) {
+        const { node, parent } = stack.pop();
+        visit(node, parent);
+        // If the node was removed during visit, parentNode is cleared.
+        if (!isParentNode(node))
+            continue;
+        // Snapshot children since visit may mutate the live array on subsequent
+        // iterations. Iterate in reverse so popped order matches document order.
+        const children = [...node.childNodes];
+        for (let i = children.length - 1; i >= 0; i -= 1) {
+            stack.push({ node: children[i], parent: node });
+        }
+    }
+}
+function removeChild(parent, child) {
+    if (!parent)
+        return;
+    defaultTreeAdapter.detachNode(child);
+}
+function getAttr(element, name) {
+    for (const attr of element.attrs) {
+        if (attr.name === name)
+            return attr.value;
+    }
+    return undefined;
+}
+function rewriteAttr(element, name, value) {
+    for (const attr of element.attrs) {
+        if (attr.name === name) {
+            attr.value = value;
+            return;
+        }
+    }
+    element.attrs.push({ name, value });
+}
+function setAttrIfMissing(element, name, value) {
+    if (getAttr(element, name) === undefined) {
+        element.attrs.push({ name, value });
+    }
+}
+function removeAttr(element, name) {
+    for (let i = element.attrs.length - 1; i >= 0; i -= 1) {
+        if (element.attrs[i].name === name) {
+            element.attrs.splice(i, 1);
+        }
+    }
+}
+function stripEventHandlers(element) {
+    let removed = 0;
+    for (let i = element.attrs.length - 1; i >= 0; i -= 1) {
+        const attr = element.attrs[i];
+        if (attr.name.length > 2 && attr.name[0] === 'o' && attr.name[1] === 'n') {
+            element.attrs.splice(i, 1);
+            removed += 1;
+        }
+    }
+    return removed;
+}
+function matchesDevSelector(element) {
+    if (DEV_TOOL_TAGS.has(element.tagName))
+        return true;
+    const id = getAttr(element, 'id');
+    if (id && DEV_TOOL_IDS.has(id))
+        return true;
+    for (const dataAttr of DEV_TOOL_DATA_ATTRS) {
+        if (getAttr(element, dataAttr) !== undefined)
+            return true;
+    }
+    return false;
+}
+// ── URL helpers ─────────────────────────────────────────────────────
+function safeOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+function isSameOriginUrl(value, baseOrigin) {
+    if (!baseOrigin)
+        return false;
+    if (value.startsWith('/') && !value.startsWith('//'))
+        return true;
+    if (!value.startsWith('http://') && !value.startsWith('https://') && !value.startsWith('//')) {
+        // relative URL — same origin
+        return true;
+    }
+    try {
+        return new URL(value, baseOrigin).origin === baseOrigin;
+    }
+    catch {
+        return false;
+    }
+}
+function absolutize(value, baseUrl) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith('data:') || trimmed.startsWith('blob:'))
+        return null;
+    try {
+        return new URL(trimmed, baseUrl).toString();
+    }
+    catch {
+        return null;
+    }
+}
+function parseSrcset(srcset) {
+    // srcset = "url1 1x, url2 2x" or "url1 480w, url2 800w"
+    return srcset
+        .split(',')
+        .map((entry) => entry.trim().split(/\s+/)[0])
+        .filter((url) => url.length > 0);
+}
+//# sourceMappingURL=dom-serializer.js.map

package/dist/element-capture.d.ts

@@ -0,0 +1,13 @@
+import { Browser } from './browser.js';
+import type { IsolatedElement, ElementCaptureResult, OutscaleConfig } from './types.js';
+export declare function isLooseElementCaptureRejectionReason(reason: string | null | undefined): boolean;
+export declare function outscaleAddsPadding(outscale: OutscaleConfig | undefined): boolean;
+export declare function buildVerificationOutscale(outscale: OutscaleConfig | undefined): OutscaleConfig;
+interface ElementCaptureOptions {
+    abortSignal?: AbortSignal;
+    distinctId?: string;
+    fallbackModel?: string;
+    uploadImage?: (buffer: Buffer, mimeType: 'image/jpeg' | 'image/png') => Promise<string>;
+}
+export declare function captureIsolatedElement(browser: Browser, element: IsolatedElement, apiKey: string, model: string, options?: ElementCaptureOptions): Promise<ElementCaptureResult>;
+export {};