ghost-qa 0.0.0-stage → 1.3.1

package/dist/src/engine/browser-session.js

@@ -0,0 +1,114 @@
+import { chromium } from 'playwright';
+export const VIEWPORT_PROFILES = {
+    desktop: {
+        name: 'desktop',
+        width: 1440,
+        height: 900,
+        isMobile: false,
+        hasTouch: false,
+        deviceScaleFactor: 1,
+    },
+    mobile: {
+        name: 'mobile',
+        width: 390,
+        height: 844,
+        isMobile: true,
+        hasTouch: true,
+        deviceScaleFactor: 3,
+        userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+    },
+};
+export class BrowserNotInstalledError extends Error {
+    constructor(cause) {
+        super('ghost-qa could not launch Chromium. Playwright browsers are not installed yet.\n' +
+            'Fix (one-time):  npx playwright install chromium\n' +
+            (cause instanceof Error ? `Underlying error: ${cause.message}` : ''));
+        this.name = 'BrowserNotInstalledError';
+    }
+}
+/**
+ * Owns the headless Chromium lifecycle: one browser, one isolated context per
+ * viewport profile, pages created on demand. Always `close()` (or use
+ * `await using`-style try/finally) — leaked browsers hang CI.
+ */
+export class BrowserSession {
+    browser = null;
+    contexts = new Map();
+    headless;
+    constructor(headless = true) {
+        this.headless = headless;
+    }
+    async launch() {
+        if (this.browser)
+            return;
+        // GHOST_QA_CHROMIUM_PATH lets CI / serverless environments point ghost-qa
+        // at a pre-provisioned Chromium (e.g. @sparticuz/chromium) instead of the
+        // Playwright-managed download.
+        const executablePath = process.env.GHOST_QA_CHROMIUM_PATH;
+        try {
+            this.browser = await chromium.launch({
+                headless: this.headless,
+                ...(executablePath ? { executablePath } : {}),
+            });
+        }
+        catch (error) {
+            throw new BrowserNotInstalledError(error);
+        }
+    }
+    get isLaunched() {
+        return this.browser !== null;
+    }
+    async contextFor(viewport) {
+        if (!this.browser)
+            await this.launch();
+        const existing = this.contexts.get(viewport);
+        if (existing)
+            return existing;
+        const profile = VIEWPORT_PROFILES[viewport];
+        const context = await this.browser.newContext({
+            viewport: { width: profile.width, height: profile.height },
+            isMobile: profile.isMobile,
+            hasTouch: profile.hasTouch,
+            deviceScaleFactor: profile.deviceScaleFactor,
+            ...(profile.userAgent ? { userAgent: profile.userAgent } : {}),
+        });
+        this.contexts.set(viewport, context);
+        return context;
+    }
+    async newPage(viewport) {
+        const context = await this.contextFor(viewport);
+        return context.newPage();
+    }
+    async close() {
+        for (const context of this.contexts.values()) {
+            await context.close().catch(() => undefined);
+        }
+        this.contexts.clear();
+        if (this.browser) {
+            await this.browser.close().catch(() => undefined);
+            this.browser = null;
+        }
+    }
+}
+/** Lightweight launch smoke-test used by `ghost-qa doctor`. */
+export async function smokeTestBrowser() {
+    let session = null;
+    try {
+        session = new BrowserSession(true);
+        const page = await session.newPage('desktop');
+        await page.goto('about:blank');
+        const title = await page.evaluate(() => document.title);
+        void title;
+        return { ok: true, detail: 'Chromium launched and rendered about:blank successfully.' };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        await session?.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=browser-session.js.map

package/dist/src/engine/browser-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.js","sourceRoot":"","sources":["../../../src/engine/browser-session.ts"],"names":[],"mappings":"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"}

package/dist/src/engine/interaction-runner.d.ts

@@ -0,0 +1,41 @@
+import type { Page } from 'playwright';
+import { type InteractionAction, type QAIssue, type ViewportName } from '../types.js';
+/**
+ * True when an anchor points at a different route than the page under test.
+ * The crawler already covers those routes with their own traps attached.
+ */
+export declare function isOtherRouteLink(href: string, currentRoute: string, currentUrl: string): boolean;
+export declare function isDestructiveLabel(label: string): boolean;
+/** Pure safety gate for a candidate interactive element. */
+export declare function isSafeInteraction(input: {
+    label: string;
+    href?: string | null;
+    type?: string | null;
+    disabled?: boolean;
+}): {
+    safe: boolean;
+    reason?: string;
+};
+export interface InteractionRunResult {
+    actions: InteractionAction[];
+    issues: QAIssue[];
+    /** Hrefs visible after interactions (modals/menus may reveal new routes). */
+    discoveredHrefs: string[];
+}
+/**
+ * Safely exercises the interactive surface of one loaded page:
+ * fills form fields with inert test data, clicks non-destructive buttons,
+ * opens tabs and modals, then closes dialogs / navigates back so the page is
+ * left roughly as it was found. Never submits destructive flows.
+ */
+export declare class InteractionRunner {
+    private readonly maxInteractions;
+    private readonly settleMs;
+    constructor(maxInteractions?: number, settleMs?: number);
+    run(page: Page, route: string, viewport: ViewportName): Promise<InteractionRunResult>;
+    private fillField;
+    private clickElement;
+    /** Close any dialog we opened and return from accidental navigations. */
+    private recover;
+}
+//# sourceMappingURL=interaction-runner.d.ts.map

package/dist/src/engine/interaction-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-runner.d.ts","sourceRoot":"","sources":["../../../src/engine/interaction-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAa,KAAK,iBAAiB,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAkBjG;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAShG;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAoBrC;AAkED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,eAAe,SAAK,EAAE,QAAQ,SAAM;IAK1C,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC;YA0G7E,SAAS;YAmCT,YAAY;IAO1B,yEAAyE;YAC3D,OAAO;CActB"}

package/dist/src/engine/interaction-runner.js

@@ -0,0 +1,274 @@
+import { makeIssue } from '../types.js';
+/**
+ * Labels whose click could mutate real data, spend money, end a session or
+ * leave the test environment. The runner never clicks these — ghost-qa tests
+ * locally, but habits formed here should be safe anywhere.
+ */
+const DESTRUCTIVE_PATTERNS = [
+    /\b(delete|remove|destroy|erase|wipe|purge|drop)\b/i,
+    /\b(checkout|pay(ment)?|purchase|buy now|place order|subscribe|donate)\b/i,
+    /\b(log ?out|sign ?out|sign ?in|log ?in|register|sign ?up)\b/i,
+    /\b(send|submit order|confirm order|publish|deploy|release)\b/i,
+    /\b(unsubscribe|close account|deactivate)\b/i,
+    /\b(github|google|apple|facebook|twitter|x\.com)\b.*\b(continue|login|sign)/i,
+];
+const EXTERNAL_HREF = /^https?:\/\//i;
+/**
+ * True when an anchor points at a different route than the page under test.
+ * The crawler already covers those routes with their own traps attached.
+ */
+export function isOtherRouteLink(href, currentRoute, currentUrl) {
+    try {
+        const target = new URL(href, currentUrl);
+        const targetRoute = (target.pathname || '/') + target.search;
+        const normalizedCurrent = currentRoute === '' ? '/' : currentRoute;
+        return targetRoute !== normalizedCurrent;
+    }
+    catch {
+        return false;
+    }
+}
+export function isDestructiveLabel(label) {
+    return DESTRUCTIVE_PATTERNS.some((p) => p.test(label));
+}
+/** Pure safety gate for a candidate interactive element. */
+export function isSafeInteraction(input) {
+    if (input.disabled)
+        return { safe: false, reason: 'element is disabled' };
+    const label = (input.label ?? '').trim();
+    if (isDestructiveLabel(label)) {
+        return { safe: false, reason: `destructive label blocked: "${label.slice(0, 60)}"` };
+    }
+    if (input.type === 'file')
+        return { safe: false, reason: 'file inputs are never exercised' };
+    if (input.href && EXTERNAL_HREF.test(input.href)) {
+        try {
+            // External navigations are exercised only by the crawler's origin check
+            // upstream; the interaction runner stays on-page.
+            const url = new URL(input.href);
+            if (!['localhost', '127.0.0.1', '::1'].includes(url.hostname)) {
+                return { safe: false, reason: 'external link not exercised' };
+            }
+        }
+        catch {
+            return { safe: false, reason: 'unparseable href' };
+        }
+    }
+    return { safe: true };
+}
+function collectCandidates() {
+    const describe = (el) => {
+        const tag = el.tagName.toLowerCase();
+        const id = el.id ? `#${el.id}` : '';
+        const role = el.getAttribute('role');
+        return `${tag}${id}${role ? `[role=${role}]` : ''}`;
+    };
+    const labelOf = (el) => (el.getAttribute('aria-label') ||
+        el.innerText ||
+        el.getAttribute('value') ||
+        el.getAttribute('placeholder') ||
+        '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 80);
+    const results = [];
+    const seen = new Set();
+    const push = (el, kind) => {
+        if (seen.has(el) || results.length >= 60)
+            return;
+        seen.add(el);
+        // Tag the live node so the runner can re-locate this exact element with
+        // a Playwright locator, regardless of how the DOM re-renders afterwards.
+        el.setAttribute('data-ghost-qa-target', String(results.length));
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden')
+            return;
+        results.push({
+            index: results.length,
+            descriptor: describe(el),
+            label: labelOf(el),
+            kind,
+            href: el instanceof HTMLAnchorElement ? el.href : null,
+            inputType: el instanceof HTMLInputElement ? el.type : null,
+            disabled: el.disabled === true || el.getAttribute('aria-disabled') === 'true',
+        });
+    };
+    document
+        .querySelectorAll('input:not([type="hidden"]), textarea, select')
+        .forEach((el) => push(el, 'fill'));
+    document
+        .querySelectorAll('[role="tab"], [data-toggle="tab"], .tab')
+        .forEach((el) => push(el, 'tab'));
+    document
+        .querySelectorAll('button, [role="button"], a[href], summary, [data-toggle="modal"]')
+        .forEach((el) => push(el, el.tagName.toLowerCase() === 'a' ? 'click' : 'click'));
+    return results;
+}
+/**
+ * Safely exercises the interactive surface of one loaded page:
+ * fills form fields with inert test data, clicks non-destructive buttons,
+ * opens tabs and modals, then closes dialogs / navigates back so the page is
+ * left roughly as it was found. Never submits destructive flows.
+ */
+export class InteractionRunner {
+    maxInteractions;
+    settleMs;
+    constructor(maxInteractions = 12, settleMs = 300) {
+        this.maxInteractions = maxInteractions;
+        this.settleMs = settleMs;
+    }
+    async run(page, route, viewport) {
+        const actions = [];
+        const issues = [];
+        const startUrl = page.url();
+        const attempted = new Set();
+        const candidateKey = (c) => [c.kind, c.descriptor, c.label, c.href ?? '', c.inputType ?? ''].join('|');
+        // Candidates are re-collected before every action: clicks can navigate,
+        // re-render or open dialogs, which invalidates both element handles and
+        // the data-ghost-qa-target tags from the previous snapshot.
+        for (let step = 0; step < this.maxInteractions * 3; step++) {
+            if (actions.filter((a) => a.outcome !== 'skipped').length >= this.maxInteractions)
+                break;
+            let candidates = [];
+            try {
+                candidates = await page.evaluate(collectCandidates);
+            }
+            catch {
+                break;
+            }
+            const candidate = candidates.find((c) => !attempted.has(candidateKey(c)));
+            if (!candidate)
+                break;
+            attempted.add(candidateKey(candidate));
+            const target = candidate.label
+                ? `${candidate.descriptor} "${candidate.label}"`
+                : candidate.descriptor;
+            // Route links are the crawler's job — clicking them here would load a
+            // different page under this route's traps and pollute its report.
+            if (candidate.href && isOtherRouteLink(candidate.href, route, startUrl)) {
+                actions.push({
+                    kind: candidate.kind,
+                    target,
+                    route,
+                    viewport,
+                    outcome: 'skipped',
+                    reason: 'route link covered by the crawler',
+                });
+                continue;
+            }
+            const safety = isSafeInteraction({
+                label: candidate.label,
+                href: candidate.href,
+                type: candidate.inputType,
+                disabled: candidate.disabled,
+            });
+            if (!safety.safe) {
+                actions.push({
+                    kind: candidate.kind,
+                    target,
+                    route,
+                    viewport,
+                    outcome: 'skipped',
+                    ...(safety.reason ? { reason: safety.reason } : {}),
+                });
+                continue;
+            }
+            try {
+                if (candidate.kind === 'fill') {
+                    await this.fillField(page, candidate);
+                }
+                else {
+                    await this.clickElement(page, candidate);
+                }
+                actions.push({ kind: candidate.kind, target, route, viewport, outcome: 'passed' });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                actions.push({
+                    kind: candidate.kind,
+                    target,
+                    route,
+                    viewport,
+                    outcome: 'failed',
+                    reason: message.slice(0, 200),
+                });
+                issues.push(makeIssue({
+                    category: 'interaction',
+                    severity: 'major',
+                    type: 'interaction-failed',
+                    message: `Interaction failed on ${target}: ${message.replace(/\s+/g, ' ').slice(0, 240)}`,
+                    route,
+                    viewport,
+                    details: { target },
+                }));
+            }
+            await page.waitForTimeout(this.settleMs).catch(() => undefined);
+            await this.recover(page, startUrl);
+        }
+        let discoveredHrefs = [];
+        try {
+            discoveredHrefs = await page.evaluate(() => Array.from(document.querySelectorAll('a[href]')).map((a) => a.href));
+        }
+        catch {
+            /* page navigated away mid-run */
+        }
+        return { actions, issues, discoveredHrefs };
+    }
+    async fillField(page, candidate) {
+        const locator = page.locator(`[data-ghost-qa-target="${candidate.index}"]`).first();
+        const tag = await locator.evaluate((el) => el.tagName.toLowerCase()).catch(() => '');
+        if (tag === 'select') {
+            const value = await locator
+                .evaluate((el) => {
+                const select = el;
+                const option = Array.from(select.options).find((o) => o.value);
+                return option?.value ?? null;
+            })
+                .catch(() => null);
+            if (value)
+                await locator.selectOption(value, { timeout: 2000 });
+            return;
+        }
+        const type = candidate.inputType ?? 'text';
+        if (['checkbox', 'radio'].includes(type)) {
+            await locator.click({ timeout: 2000 });
+            return;
+        }
+        if (['password', 'file'].includes(type))
+            return;
+        const sample = type === 'email'
+            ? 'ghost-qa@example.com'
+            : type === 'number'
+                ? '42'
+                : type === 'tel'
+                    ? '5550100'
+                    : type === 'url'
+                        ? 'https://example.com'
+                        : type === 'date'
+                            ? '2026-01-15'
+                            : 'ghost-qa test';
+        await locator.fill(sample, { timeout: 2000 });
+    }
+    async clickElement(page, candidate) {
+        await page
+            .locator(`[data-ghost-qa-target="${candidate.index}"]`)
+            .first()
+            .click({ timeout: 2500 });
+    }
+    /** Close any dialog we opened and return from accidental navigations. */
+    async recover(page, startUrl) {
+        await page.keyboard.press('Escape').catch(() => undefined);
+        const closeButton = page
+            .locator('[role="dialog"] button[aria-label*="close" i], [role="dialog"] .close, dialog button')
+            .first();
+        if (await closeButton.isVisible().catch(() => false)) {
+            await closeButton.click({ timeout: 1000 }).catch(() => undefined);
+        }
+        if (page.url() !== startUrl) {
+            await page.goBack({ timeout: 5000 }).catch(async () => {
+                await page.goto(startUrl, { timeout: 5000 }).catch(() => undefined);
+            });
+        }
+    }
+}
+//# sourceMappingURL=interaction-runner.js.map

package/dist/src/engine/interaction-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-runner.js","sourceRoot":"","sources":["../../../src/engine/interaction-runner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAA2D,MAAM,aAAa,CAAC;AAEjG;;;;GAIG;AACH,MAAM,oBAAoB,GAAa;IACrC,oDAAoD;IACpD,0EAA0E;IAC1E,8DAA8D;IAC9D,+DAA+D;IAC/D,6CAA6C;IAC7C,6EAA6E;CAC9E,CAAC;AAEF,MAAM,aAAa,GAAG,eAAe,CAAC;AAEtC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,YAAoB,EAAE,UAAkB;IACrF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7D,MAAM,iBAAiB,GAAG,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACnE,OAAO,WAAW,KAAK,iBAAiB,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,iBAAiB,CAAC,KAKjC;IACC,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAC1E,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzC,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,+BAA+B,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC;IACvF,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,iCAAiC,EAAE,CAAC;IAC7F,IAAI,KAAK,CAAC,IAAI,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,wEAAwE;YACxE,kDAAkD;YAClD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC9D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;YAChE,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAYD,SAAS,iBAAiB;IACxB,MAAM,QAAQ,GAAG,CAAC,EAAW,EAAU,EAAE;QACvC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO,GAAG,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACtD,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,EAAW,EAAU,EAAE,CACtC,CACE,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC;QAC5B,EAAkB,CAAC,SAAS;QAC7B,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC;QACxB,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC;QAC9B,EAAE,CACH;SACE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE;SACN,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAElB,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;IAEhC,MAAM,IAAI,GAAG,CAAC,EAAW,EAAE,IAA8B,EAAE,EAAE;QAC3D,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,EAAE;YAAE,OAAO;QACjD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,wEAAwE;QACxE,yEAAyE;QACzE,EAAE,CAAC,YAAY,CAAC,sBAAsB,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAChE,MAAM,KAAK,GAAG,MAAM,CAAC,gBAAgB,CAAC,EAAiB,CAAC,CAAC;QACzD,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,QAAQ;YAAE,OAAO;QACtE,OAAO,CAAC,IAAI,CAAC;YACX,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC;YACxB,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;YAClB,IAAI;YACJ,IAAI,EAAE,EAAE,YAAY,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;YACtD,SAAS,EAAE,EAAE,YAAY,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;YAC1D,QAAQ,EACL,EAAwB,CAAC,QAAQ,KAAK,IAAI,IAAI,EAAE,CAAC,YAAY,CAAC,eAAe,CAAC,KAAK,MAAM;SAC7F,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,QAAQ;SACL,gBAAgB,CAAC,8CAA8C,CAAC;SAChE,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACrC,QAAQ;SACL,gBAAgB,CAAC,yCAAyC,CAAC;SAC3D,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;IACpC,QAAQ;SACL,gBAAgB,CAAC,kEAAkE,CAAC;SACpF,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACnF,OAAO,OAAO,CAAC;AACjB,CAAC;AASD;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IACX,eAAe,CAAS;IACxB,QAAQ,CAAS;IAElC,YAAY,eAAe,GAAG,EAAE,EAAE,QAAQ,GAAG,GAAG;QAC9C,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAU,EAAE,KAAa,EAAE,QAAsB;QACzD,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;QACpC,MAAM,YAAY,GAAG,CAAC,CAAmB,EAAU,EAAE,CACnD,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAE7E,wEAAwE;QACxE,wEAAwE;QACxE,4DAA4D;QAC5D,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,eAAe,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;YAC3D,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,eAAe;gBAAE,MAAM;YAEzF,IAAI,UAAU,GAAuB,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM;YACR,CAAC;YACD,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1E,IAAI,CAAC,SAAS;gBAAE,MAAM;YACtB,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;YAEvC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK;gBAC5B,CAAC,CAAC,GAAG,SAAS,CAAC,UAAU,KAAK,SAAS,CAAC,KAAK,GAAG;gBAChD,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC;YAEzB,sEAAsE;YACtE,kEAAkE;YAClE,IAAI,SAAS,CAAC,IAAI,IAAI,gBAAgB,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;gBACxE,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,SAAS,CAAC,IAAI;oBACpB,MAAM;oBACN,KAAK;oBACL,QAAQ;oBACR,OAAO,EAAE,SAAS;oBAClB,MAAM,EAAE,mCAAmC;iBAC5C,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,MAAM,MAAM,GAAG,iBAAiB,CAAC;gBAC/B,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,IAAI,EAAE,SAAS,CAAC,IAAI;gBACpB,IAAI,EAAE,SAAS,CAAC,SAAS;gBACzB,QAAQ,EAAE,SAAS,CAAC,QAAQ;aAC7B,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACjB,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,SAAS,CAAC,IAAI;oBACpB,MAAM;oBACN,KAAK;oBACL,QAAQ;oBACR,OAAO,EAAE,SAAS;oBAClB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpD,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;oBAC9B,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBACxC,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBAC3C,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;YACrF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,SAAS,CAAC,IAAI;oBACpB,MAAM;oBACN,KAAK;oBACL,QAAQ;oBACR,OAAO,EAAE,QAAQ;oBACjB,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;iBAC9B,CAAC,CAAC;gBACH,MAAM,CAAC,IAAI,CACT,SAAS,CAAC;oBACR,QAAQ,EAAE,aAAa;oBACvB,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,oBAAoB;oBAC1B,OAAO,EAAE,yBAAyB,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;oBACzF,KAAK;oBACL,QAAQ;oBACR,OAAO,EAAE,EAAE,MAAM,EAAE;iBACpB,CAAC,CACH,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAChE,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,eAAe,GAAa,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,eAAe,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CACzC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAuB,CAAC,IAAI,CAAC,CAC3F,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC9C,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,IAAU,EAAE,SAA2B;QAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,0BAA0B,SAAS,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QACpF,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QACrF,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,MAAM,OAAO;iBACxB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE;gBACf,MAAM,MAAM,GAAG,EAAuB,CAAC;gBACvC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;gBAC/D,OAAO,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC;YAC/B,CAAC,CAAC;iBACD,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YACrB,IAAI,KAAK;gBAAE,MAAM,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAChE,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,IAAI,MAAM,CAAC;QAC3C,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO;QAChD,MAAM,MAAM,GACV,IAAI,KAAK,OAAO;YACd,CAAC,CAAC,sBAAsB;YACxB,CAAC,CAAC,IAAI,KAAK,QAAQ;gBACjB,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,IAAI,KAAK,KAAK;oBACd,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,IAAI,KAAK,KAAK;wBACd,CAAC,CAAC,qBAAqB;wBACvB,CAAC,CAAC,IAAI,KAAK,MAAM;4BACf,CAAC,CAAC,YAAY;4BACd,CAAC,CAAC,eAAe,CAAC;QAC9B,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAU,EAAE,SAA2B;QAChE,MAAM,IAAI;aACP,OAAO,CAAC,0BAA0B,SAAS,CAAC,KAAK,IAAI,CAAC;aACtD,KAAK,EAAE;aACP,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,yEAAyE;IACjE,KAAK,CAAC,OAAO,CAAC,IAAU,EAAE,QAAgB;QAChD,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,IAAI;aACrB,OAAO,CAAC,sFAAsF,CAAC;aAC/F,KAAK,EAAE,CAAC;QACX,IAAI,MAAM,WAAW,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YACrD,MAAM,WAAW,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE;gBACpD,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACtE,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF"}

package/dist/src/engine/route-crawler.d.ts

@@ -0,0 +1,31 @@
+import type { Page } from 'playwright';
+/**
+ * Normalises a URL for de-duplication: strips the hash and trailing slash,
+ * keeps the query string (query-driven views are distinct routes).
+ * Returns `null` for unparseable input.
+ */
+export declare function normalizeUrl(raw: string, base?: string): string | null;
+export declare function isSameOrigin(candidate: string, origin: string): boolean;
+/** True when an href points at a crawlable, same-origin application route. */
+export declare function isCrawlableHref(href: string, origin: string): boolean;
+export declare function pathOf(url: string): string;
+export interface DiscoveredRoute {
+    url: string;
+    path: string;
+    depth: number;
+}
+/**
+ * Breadth-first route discovery. The `visit` callback loads a URL (with all
+ * traps attached) and returns the raw hrefs found on it; the crawler owns the
+ * queue, depth limit, route cap and de-duplication so traversal policy is
+ * testable without a browser.
+ */
+export declare class RouteCrawler {
+    private readonly maxDepth;
+    private readonly maxRoutes;
+    constructor(maxDepth?: number, maxRoutes?: number);
+    crawl(startUrl: string, visit: (route: DiscoveredRoute) => Promise<string[]>): Promise<DiscoveredRoute[]>;
+    /** Extracts every anchor href currently in the DOM of a loaded page. */
+    static extractLinks(page: Page): Promise<string[]>;
+}
+//# sourceMappingURL=route-crawler.d.ts.map

package/dist/src/engine/route-crawler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-crawler.d.ts","sourceRoot":"","sources":["../../../src/engine/route-crawler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAMvC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWtE;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAMvE;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAUrE;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO1C;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,QAAQ,SAAI,EAAE,SAAS,SAAK;IAKlC,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GACnD,OAAO,CAAC,eAAe,EAAE,CAAC;IA6B7B,wEAAwE;WAC3D,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAWzD"}

package/dist/src/engine/route-crawler.js

@@ -0,0 +1,110 @@
+/** Extensions and protocols that are never crawlable application routes. */
+const SKIP_EXTENSIONS = /\.(?:png|jpe?g|gif|svg|webp|avif|ico|css|js|mjs|map|json|xml|txt|pdf|zip|gz|woff2?|ttf|otf|mp4|webm|mp3|wav)$/i;
+const SKIP_PREFIXES = ['mailto:', 'tel:', 'javascript:', 'data:', 'blob:', '#'];
+/**
+ * Normalises a URL for de-duplication: strips the hash and trailing slash,
+ * keeps the query string (query-driven views are distinct routes).
+ * Returns `null` for unparseable input.
+ */
+export function normalizeUrl(raw, base) {
+    try {
+        const url = base ? new URL(raw, base) : new URL(raw);
+        url.hash = '';
+        if (url.pathname.length > 1 && url.pathname.endsWith('/')) {
+            url.pathname = url.pathname.replace(/\/+$/, '');
+        }
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+export function isSameOrigin(candidate, origin) {
+    try {
+        return new URL(candidate).origin === new URL(origin).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when an href points at a crawlable, same-origin application route. */
+export function isCrawlableHref(href, origin) {
+    if (!href)
+        return false;
+    const trimmed = href.trim();
+    if (SKIP_PREFIXES.some((p) => trimmed.toLowerCase().startsWith(p)))
+        return false;
+    const normalized = normalizeUrl(trimmed, origin);
+    if (!normalized)
+        return false;
+    if (!/^https?:$/.test(new URL(normalized).protocol))
+        return false;
+    if (!isSameOrigin(normalized, origin))
+        return false;
+    if (SKIP_EXTENSIONS.test(new URL(normalized).pathname))
+        return false;
+    return true;
+}
+export function pathOf(url) {
+    try {
+        const parsed = new URL(url);
+        return (parsed.pathname || '/') + parsed.search;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Breadth-first route discovery. The `visit` callback loads a URL (with all
+ * traps attached) and returns the raw hrefs found on it; the crawler owns the
+ * queue, depth limit, route cap and de-duplication so traversal policy is
+ * testable without a browser.
+ */
+export class RouteCrawler {
+    maxDepth;
+    maxRoutes;
+    constructor(maxDepth = 2, maxRoutes = 25) {
+        this.maxDepth = maxDepth;
+        this.maxRoutes = maxRoutes;
+    }
+    async crawl(startUrl, visit) {
+        const start = normalizeUrl(startUrl);
+        if (!start)
+            throw new Error(`Invalid target URL: ${startUrl}`);
+        const origin = new URL(start).origin;
+        const visited = new Set();
+        const completed = [];
+        const queue = [{ url: start, path: pathOf(start), depth: 0 }];
+        while (queue.length > 0 && completed.length < this.maxRoutes) {
+            const route = queue.shift();
+            if (visited.has(route.url))
+                continue;
+            visited.add(route.url);
+            completed.push(route);
+            const hrefs = await visit(route);
+            if (route.depth >= this.maxDepth)
+                continue;
+            for (const href of hrefs) {
+                if (!isCrawlableHref(href, origin))
+                    continue;
+                const normalized = normalizeUrl(href, origin);
+                if (visited.has(normalized) || queue.some((q) => q.url === normalized))
+                    continue;
+                if (completed.length + queue.length >= this.maxRoutes)
+                    break;
+                queue.push({ url: normalized, path: pathOf(normalized), depth: route.depth + 1 });
+            }
+        }
+        return completed;
+    }
+    /** Extracts every anchor href currently in the DOM of a loaded page. */
+    static async extractLinks(page) {
+        try {
+            return await page.evaluate(() => Array.from(document.querySelectorAll('a[href]')).map((a) => a.href));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=route-crawler.js.map

package/dist/src/engine/route-crawler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-crawler.js","sourceRoot":"","sources":["../../../src/engine/route-crawler.ts"],"names":[],"mappings":"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"}

package/dist/src/engine/server-lifecycle.d.ts

@@ -0,0 +1,41 @@
+/** Polls a URL until it answers with any HTTP status (even 404 = server up). */
+export declare function waitForUrl(url: string, timeoutMs?: number, pollIntervalMs?: number): Promise<void>;
+export interface ManagedServerOptions {
+    /** Working directory for the command (default: process.cwd()). */
+    cwd?: string;
+    /** Extra environment variables merged over process.env. */
+    env?: Record<string, string>;
+    /** How many characters of server output to keep for error reporting. */
+    outputBufferChars?: number;
+}
+/**
+ * Owns a spawned dev-server process tree: `start()` spawns it through the
+ * platform shell in its own process group, `waitUntilReady()` polls the
+ * target URL, and `stop()` terminates the whole tree (SIGTERM, then SIGKILL)
+ * so no orphaned dev servers survive a ghost-qa run.
+ */
+export declare class ManagedDevServer {
+    private child;
+    private output;
+    readonly command: string;
+    private readonly options;
+    constructor(command: string, options?: ManagedServerOptions);
+    get isRunning(): boolean;
+    get pid(): number | undefined;
+    /** Last chunk of captured stdout+stderr (for "server failed to start" errors). */
+    get outputTail(): string;
+    start(): void;
+    /** Resolves once the URL responds; rejects with the server output on timeout/early exit. */
+    waitUntilReady(url: string, timeoutMs?: number): Promise<void>;
+    /** Terminates the spawned process tree. Safe to call multiple times. */
+    stop(graceMs?: number): Promise<void>;
+    private signalTree;
+}
+/**
+ * Convenience wrapper: spawn `command`, wait for `url`, run `fn`, and always
+ * tear the server down afterwards — even when `fn` throws.
+ */
+export declare function withManagedDevServer<T>(command: string, url: string, fn: () => Promise<T>, options?: ManagedServerOptions & {
+    readyTimeoutMs?: number;
+}): Promise<T>;
+//# sourceMappingURL=server-lifecycle.d.ts.map