@noego/wood 0.4.9 → 0.5.0

package/dist/stick/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/stick/index.ts"],"sourcesContent":["import './allow_cli.js';\n// Type-only import — erased at runtime, won't trigger module loading\nimport type { WoodStaticRenderer } from './static_renderer.js';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { resolveImageRendererTemplate } from './template_resolver.js';\n\nexport type { WoodStaticRenderer };\nexport type {\n    WoodStaticRendererConfig,\n    WoodRenderOptions,\n    WoodRenderToPageOptions,\n    WoodRenderResult,\n} from './static_renderer';\n\n// ─────────────────────────────────────────────────────────────\n// Error Classes\n// ─────────────────────────────────────────────────────────────\n\nexport class PlaywrightNotInstalledError extends Error {\n    name = 'PlaywrightNotInstalledError' as const;\n    constructor() {\n        super(\n            'ImageRenderer requires Playwright. Install it with:\\n' +\n            '  npm install playwright\\n' +\n            '  npx playwright install chromium'\n        );\n    }\n}\n\nexport class BrowserLaunchError extends Error {\n    name = 'BrowserLaunchError' as const;\n    constructor(message: string, public cause?: Error) {\n        super(message);\n    }\n}\n\nexport class RenderTimeoutError extends Error {\n    name = 'RenderTimeoutError' as const;\n    constructor(timeoutMs: number) {\n        super(`Render timed out after ${timeoutMs}ms`);\n    }\n}\n\nexport class RenderError extends Error {\n    name = 'RenderError' as const;\n    constructor(message: string, public cause?: Error) {\n        super(message);\n    }\n}\n\n// ─────────────────────────────────────────────────────────────\n// Types\n// ─────────────────────────────────────────────────────────────\n\nexport interface ImageRendererConfig {\n    /** Output directory for screenshots */\n    outputDir: string;\n    /** Default width (default: 1920) */\n    width?: number;\n    /** Default height (default: 1080) */\n    height?: number;\n    /** Device scale factor for retina (default: 1) */\n    deviceScaleFactor?: number;\n    /** Image format (default: 'png') */\n    format?: 'png' | 'jpeg';\n    /** JPEG quality 0-100 (default: 80) */\n    quality?: number;\n    /** Wait condition (default: 'networkidle') */\n    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';\n    /** Timeout in ms (default: 10000) */\n    timeoutMs?: number;\n    /** Custom HTML template with {{{HEAD}}}, {{{CSS}}}, {{{APP}}} placeholders */\n    template?: string;\n\n    // Static renderer config (one of these)\n    /** Pre-created WoodStaticRenderer instance */\n    staticRenderer?: WoodStaticRenderer;\n    /** OR: Path to views.yaml */\n    viewsConfig?: string;\n    /**\n     * Component directory (required if viewsConfig provided).\n     * When template is omitted, stick auto-loads <componentDir>/index.html and\n     * inlines <componentDir>/styles.css when present.\n     */\n    componentDir?: string;\n    /** Asset path mappings (e.g., { '/images': ['public/images'] }) */\n    assets?: Record<string, string[]>;\n}\n\nexport interface CaptureOptions {\n    /** View component data */\n    view?: any;\n    /** Layout data (one object per layout) */\n    layout?: any[];\n    /** Wood bridge object passed as a prop to layouts and views */\n    wood?: any;\n    /** Override width */\n    width?: number;\n    /** Override height */\n    height?: number;\n    /** Capture full page (default: true) */\n    fullPage?: boolean;\n    /** Callback executed after page load, before screenshot. Receives the Playwright page object. */\n    beforeCapture?: (page: any) => Promise<void>;\n}\n\nexport interface CaptureHtmlOptions {\n    /** Override width */\n    width?: number;\n    /** Override height */\n    height?: number;\n    /** Capture full page (default: true) */\n    fullPage?: boolean;\n    /** Callback executed after page load, before screenshot. Receives the Playwright page object. */\n    beforeCapture?: (page: any) => Promise<void>;\n}\n\ninterface CaptureResult {\n    /** Raw image buffer */\n    buffer: Buffer;\n    /** Path where image was saved */\n    path: string;\n}\n\n// ─────────────────────────────────────────────────────────────\n// Playwright Loader\n// ─────────────────────────────────────────────────────────────\n\ntype PlaywrightModule = typeof import('playwright');\n\nasync function loadPlaywright(): Promise<PlaywrightModule> {\n    try {\n        const playwright = await import('playwright');\n        return playwright;\n    } catch {\n        throw new PlaywrightNotInstalledError();\n    }\n}\n\n// ─────────────────────────────────────────────────────────────\n// Content Type Helper\n// ─────────────────────────────────────────────────────────────\n\nfunction getContentType(filePath: string): string {\n    const ext = path.extname(filePath).toLowerCase();\n    const types: Record<string, string> = {\n        '.png': 'image/png',\n        '.jpg': 'image/jpeg',\n        '.jpeg': 'image/jpeg',\n        '.gif': 'image/gif',\n        '.svg': 'image/svg+xml',\n        '.webp': 'image/webp',\n        '.css': 'text/css',\n        '.js': 'application/javascript',\n        '.json': 'application/json',\n        '.woff': 'font/woff',\n        '.woff2': 'font/woff2',\n        '.ttf': 'font/ttf',\n    };\n    return types[ext] || 'application/octet-stream';\n}\n\n// ─────────────────────────────────────────────────────────────\n// ImageRenderer Class\n// ─────────────────────────────────────────────────────────────\n\nexport class ImageRenderer {\n    private browser: any;\n    private staticRenderer: WoodStaticRenderer;\n    private config: Required<Omit<ImageRendererConfig, 'staticRenderer' | 'viewsConfig' | 'componentDir' | 'template' | 'assets'>> & {\n        outputDir: string;\n        template?: string;\n        assets?: Record<string, string[]>;\n    };\n\n    constructor(\n        browser: any,\n        staticRenderer: WoodStaticRenderer,\n        config: ImageRendererConfig\n    ) {\n        this.browser = browser;\n        this.staticRenderer = staticRenderer;\n        this.config = {\n            outputDir: config.outputDir,\n            width: config.width ?? 1920,\n            height: config.height ?? 1080,\n            deviceScaleFactor: config.deviceScaleFactor ?? 1,\n            format: config.format ?? 'png',\n            quality: config.quality ?? 80,\n            waitUntil: config.waitUntil ?? 'networkidle',\n            timeoutMs: config.timeoutMs ?? 10000,\n            template: config.template,\n            assets: config.assets,\n        };\n    }\n\n    /**\n     * Capture a view by dot-path key and save to outputDir\n     */\n    async capture(\n        name: string,\n        viewKey: string,\n        options?: CaptureOptions\n    ): Promise<CaptureResult> {\n        const { view, layout, wood } = options ?? {};\n        const html = await this.staticRenderer.renderToPage({\n            viewKey,\n            data: { view, layout },\n            wood,\n            template: this.config.template,\n        });\n\n        return this.captureHtmlInternal(name, html, options);\n    }\n\n    /**\n     * Capture raw HTML and save to outputDir\n     */\n    async captureHtml(\n        name: string,\n        html: string,\n        options?: CaptureHtmlOptions\n    ): Promise<CaptureResult> {\n        return this.captureHtmlInternal(name, html, options);\n    }\n\n    /**\n     * Internal method to capture HTML to image\n     */\n    private async captureHtmlInternal(\n        name: string,\n        html: string,\n        options?: CaptureHtmlOptions\n    ): Promise<CaptureResult> {\n        const width = options?.width ?? this.config.width;\n        const height = options?.height ?? this.config.height;\n\n        let context: any;\n        let page: any;\n\n        try {\n            context = await this.browser.newContext({\n                viewport: { width, height },\n                deviceScaleFactor: this.config.deviceScaleFactor,\n            });\n\n            page = await context.newPage();\n\n            // Route Interception Strategy:\n            // We use page.goto() with a fake URL instead of page.setContent() because\n            // setContent() has no base URL, so relative paths can't resolve.\n            const FAKE_BASE_URL = 'http://stick-renderer/';\n\n            await page.route(FAKE_BASE_URL, async (route: any) => {\n                await route.fulfill({\n                    body: html,\n                    contentType: 'text/html',\n                });\n            });\n\n            // Asset route interception\n            if (this.config.assets) {\n                for (const [urlPath, fsPaths] of Object.entries(this.config.assets)) {\n                    await page.route(`**${urlPath}/**`, async (route: any) => {\n                        const url = new URL(route.request().url());\n                        const relativePath = url.pathname.replace(urlPath, '');\n\n                        for (const fsPath of fsPaths) {\n                            const filePath = path.join(fsPath, relativePath);\n                            try {\n                                const body = await fs.promises.readFile(filePath);\n                                const contentType = getContentType(filePath);\n                                await route.fulfill({ body, contentType });\n                                return;\n                            } catch {\n                                // File not found in this path, try the next one\n                            }\n                        }\n\n                        await route.abort('filenotfound');\n                    });\n                }\n            }\n\n            const waitUntilMapping = {\n                'load': 'load',\n                'domcontentloaded': 'domcontentloaded',\n                'networkidle': 'networkidle',\n            } as const;\n\n            try {\n                await page.goto(FAKE_BASE_URL, {\n                    waitUntil: waitUntilMapping[this.config.waitUntil],\n                    timeout: this.config.timeoutMs,\n                });\n            } catch (error) {\n                if (error instanceof Error && error.message.includes('timeout')) {\n                    throw new RenderTimeoutError(this.config.timeoutMs);\n                }\n                throw new RenderError(\n                    'Failed to render HTML content',\n                    error instanceof Error ? error : undefined\n                );\n            }\n\n            if (options?.beforeCapture) {\n                await options.beforeCapture(page);\n            }\n\n            const screenshotOptions: {\n                type: 'png' | 'jpeg';\n                quality?: number;\n                fullPage: boolean;\n            } = {\n                type: this.config.format,\n                fullPage: options?.fullPage ?? true,\n            };\n\n            if (this.config.format === 'jpeg') {\n                screenshotOptions.quality = this.config.quality;\n            }\n\n            const screenshot = await page.screenshot(screenshotOptions);\n            const buffer = Buffer.from(screenshot);\n\n            const filename = `${name}@${width}x${height}.${this.config.format}`;\n            const outputPath = path.join(this.config.outputDir, filename);\n\n            await fs.promises.mkdir(this.config.outputDir, { recursive: true });\n            await fs.promises.writeFile(outputPath, buffer);\n\n            return { buffer, path: outputPath };\n\n        } finally {\n            if (page) {\n                await page.close().catch(() => {});\n            }\n            if (context) {\n                await context.close().catch(() => {});\n            }\n        }\n    }\n\n    /**\n     * Close browser and clean up resources\n     */\n    async close(): Promise<void> {\n        if (this.browser) {\n            await this.browser.close().catch(() => {});\n        }\n    }\n}\n\n// ─────────────────────────────────────────────────────────────\n// Factory Function\n// ─────────────────────────────────────────────────────────────\n\nexport async function createImageRenderer(\n    config: ImageRendererConfig\n): Promise<ImageRenderer> {\n    const resolvedTemplate = resolveImageRendererTemplate({\n        template: config.template,\n        componentDir: config.componentDir,\n    });\n    const resolvedConfig: ImageRendererConfig = {\n        ...config,\n        template: resolvedTemplate,\n    };\n\n    const playwright = await loadPlaywright();\n\n    let browser: any;\n    try {\n        browser = await playwright.chromium.launch({\n            headless: true,\n        });\n    } catch (error) {\n        throw new BrowserLaunchError(\n            'Failed to launch Chromium. Ensure it is installed with: npx playwright install chromium',\n            error instanceof Error ? error : undefined\n        );\n    }\n\n    let staticRenderer: WoodStaticRenderer;\n    if (resolvedConfig.staticRenderer) {\n        staticRenderer = resolvedConfig.staticRenderer;\n    } else if (resolvedConfig.viewsConfig && resolvedConfig.componentDir) {\n        const { createWoodStaticRenderer } = await import('./static_renderer.js');\n        staticRenderer = createWoodStaticRenderer({\n            viewsConfig: resolvedConfig.viewsConfig,\n            componentDir: resolvedConfig.componentDir,\n        });\n    } else {\n        throw new Error(\n            'ImageRendererConfig requires either staticRenderer or both viewsConfig and componentDir'\n        );\n    }\n\n    return new ImageRenderer(browser, staticRenderer, resolvedConfig);\n}\n"],"mappings":"AAAA,OAAO;AAGP,YAAY,QAAQ;AACpB,YAAY,UAAU;AACtB,SAAS,oCAAoC;AActC,MAAM,oCAAoC,MAAM;AAAA,EAEnD,cAAc;AACV;AAAA,MACI;AAAA,IAGJ;AANJ,gBAAO;AAAA,EAOP;AACJ;AAEO,MAAM,2BAA2B,MAAM;AAAA,EAE1C,YAAY,SAAwB,OAAe;AAC/C,UAAM,OAAO;AADmB;AADpC,gBAAO;AAAA,EAGP;AACJ;AAEO,MAAM,2BAA2B,MAAM;AAAA,EAE1C,YAAY,WAAmB;AAC3B,UAAM,0BAA0B,SAAS,IAAI;AAFjD,gBAAO;AAAA,EAGP;AACJ;AAEO,MAAM,oBAAoB,MAAM;AAAA,EAEnC,YAAY,SAAwB,OAAe;AAC/C,UAAM,OAAO;AADmB;AADpC,gBAAO;AAAA,EAGP;AACJ;AAkFA,eAAe,iBAA4C;AACvD,MAAI;AACA,UAAM,aAAa,MAAM,OAAO,YAAY;AAC5C,WAAO;AAAA,EACX,QAAQ;AACJ,UAAM,IAAI,4BAA4B;AAAA,EAC1C;AACJ;AAMA,SAAS,eAAe,UAA0B;AAC9C,QAAM,MAAM,KAAK,QAAQ,QAAQ,EAAE,YAAY;AAC/C,QAAM,QAAgC;AAAA,IAClC,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,IACT,UAAU;AAAA,IACV,QAAQ;AAAA,EACZ;AACA,SAAO,MAAM,GAAG,KAAK;AACzB;AAMO,MAAM,cAAc;AAAA,EASvB,YACI,SACA,gBACA,QACF;AACE,SAAK,UAAU;AACf,SAAK,iBAAiB;AACtB,SAAK,SAAS;AAAA,MACV,WAAW,OAAO;AAAA,MAClB,OAAO,OAAO,SAAS;AAAA,MACvB,QAAQ,OAAO,UAAU;AAAA,MACzB,mBAAmB,OAAO,qBAAqB;AAAA,MAC/C,QAAQ,OAAO,UAAU;AAAA,MACzB,SAAS,OAAO,WAAW;AAAA,MAC3B,WAAW,OAAO,aAAa;AAAA,MAC/B,WAAW,OAAO,aAAa;AAAA,MAC/B,UAAU,OAAO;AAAA,MACjB,QAAQ,OAAO;AAAA,IACnB;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QACF,MACA,SACA,SACsB;AACtB,UAAM,EAAE,MAAM,QAAQ,KAAK,IAAI,WAAW,CAAC;AAC3C,UAAM,OAAO,MAAM,KAAK,eAAe,aAAa;AAAA,MAChD;AAAA,MACA,MAAM,EAAE,MAAM,OAAO;AAAA,MACrB;AAAA,MACA,UAAU,KAAK,OAAO;AAAA,IAC1B,CAAC;AAED,WAAO,KAAK,oBAAoB,MAAM,MAAM,OAAO;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,YACF,MACA,MACA,SACsB;AACtB,WAAO,KAAK,oBAAoB,MAAM,MAAM,OAAO;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAc,oBACV,MACA,MACA,SACsB;AACtB,UAAM,QAAQ,SAAS,SAAS,KAAK,OAAO;AAC5C,UAAM,SAAS,SAAS,UAAU,KAAK,OAAO;AAE9C,QAAI;AACJ,QAAI;AAEJ,QAAI;AACA,gBAAU,MAAM,KAAK,QAAQ,WAAW;AAAA,QACpC,UAAU,EAAE,OAAO,OAAO;AAAA,QAC1B,mBAAmB,KAAK,OAAO;AAAA,MACnC,CAAC;AAED,aAAO,MAAM,QAAQ,QAAQ;AAK7B,YAAM,gBAAgB;AAEtB,YAAM,KAAK,MAAM,eAAe,OAAO,UAAe;AAClD,cAAM,MAAM,QAAQ;AAAA,UAChB,MAAM;AAAA,UACN,aAAa;AAAA,QACjB,CAAC;AAAA,MACL,CAAC;AAGD,UAAI,KAAK,OAAO,QAAQ;AACpB,mBAAW,CAAC,SAAS,OAAO,KAAK,OAAO,QAAQ,KAAK,OAAO,MAAM,GAAG;AACjE,gBAAM,KAAK,MAAM,KAAK,OAAO,OAAO,OAAO,UAAe;AACtD,kBAAM,MAAM,IAAI,IAAI,MAAM,QAAQ,EAAE,IAAI,CAAC;AACzC,kBAAM,eAAe,IAAI,SAAS,QAAQ,SAAS,EAAE;AAErD,uBAAW,UAAU,SAAS;AAC1B,oBAAM,WAAW,KAAK,KAAK,QAAQ,YAAY;AAC/C,kBAAI;AACA,sBAAM,OAAO,MAAM,GAAG,SAAS,SAAS,QAAQ;AAChD,sBAAM,cAAc,eAAe,QAAQ;AAC3C,sBAAM,MAAM,QAAQ,EAAE,MAAM,YAAY,CAAC;AACzC;AAAA,cACJ,QAAQ;AAAA,cAER;AAAA,YACJ;AAEA,kBAAM,MAAM,MAAM,cAAc;AAAA,UACpC,CAAC;AAAA,QACL;AAAA,MACJ;AAEA,YAAM,mBAAmB;AAAA,QACrB,QAAQ;AAAA,QACR,oBAAoB;AAAA,QACpB,eAAe;AAAA,MACnB;AAEA,UAAI;AACA,cAAM,KAAK,KAAK,eAAe;AAAA,UAC3B,WAAW,iBAAiB,KAAK,OAAO,SAAS;AAAA,UACjD,SAAS,KAAK,OAAO;AAAA,QACzB,CAAC;AAAA,MACL,SAAS,OAAO;AACZ,YAAI,iBAAiB,SAAS,MAAM,QAAQ,SAAS,SAAS,GAAG;AAC7D,gBAAM,IAAI,mBAAmB,KAAK,OAAO,SAAS;AAAA,QACtD;AACA,cAAM,IAAI;AAAA,UACN;AAAA,UACA,iBAAiB,QAAQ,QAAQ;AAAA,QACrC;AAAA,MACJ;AAEA,UAAI,SAAS,eAAe;AACxB,cAAM,QAAQ,cAAc,IAAI;AAAA,MACpC;AAEA,YAAM,oBAIF;AAAA,QACA,MAAM,KAAK,OAAO;AAAA,QAClB,UAAU,SAAS,YAAY;AAAA,MACnC;AAEA,UAAI,KAAK,OAAO,WAAW,QAAQ;AAC/B,0BAAkB,UAAU,KAAK,OAAO;AAAA,MAC5C;AAEA,YAAM,aAAa,MAAM,KAAK,WAAW,iBAAiB;AAC1D,YAAM,SAAS,OAAO,KAAK,UAAU;AAErC,YAAM,WAAW,GAAG,IAAI,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,OAAO,MAAM;AACjE,YAAM,aAAa,KAAK,KAAK,KAAK,OAAO,WAAW,QAAQ;AAE5D,YAAM,GAAG,SAAS,MAAM,KAAK,OAAO,WAAW,EAAE,WAAW,KAAK,CAAC;AAClE,YAAM,GAAG,SAAS,UAAU,YAAY,MAAM;AAE9C,aAAO,EAAE,QAAQ,MAAM,WAAW;AAAA,IAEtC,UAAE;AACE,UAAI,MAAM;AACN,cAAM,KAAK,MAAM,EAAE,MAAM,MAAM;AAAA,QAAC,CAAC;AAAA,MACrC;AACA,UAAI,SAAS;AACT,cAAM,QAAQ,MAAM,EAAE,MAAM,MAAM;AAAA,QAAC,CAAC;AAAA,MACxC;AAAA,IACJ;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QAAuB;AACzB,QAAI,KAAK,SAAS;AACd,YAAM,KAAK,QAAQ,MAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IAC7C;AAAA,EACJ;AACJ;AAMA,eAAsB,oBAClB,QACsB;AACtB,QAAM,mBAAmB,6BAA6B;AAAA,IAClD,UAAU,OAAO;AAAA,IACjB,cAAc,OAAO;AAAA,EACzB,CAAC;AACD,QAAM,iBAAsC;AAAA,IACxC,GAAG;AAAA,IACH,UAAU;AAAA,EACd;AAEA,QAAM,aAAa,MAAM,eAAe;AAExC,MAAI;AACJ,MAAI;AACA,cAAU,MAAM,WAAW,SAAS,OAAO;AAAA,MACvC,UAAU;AAAA,IACd,CAAC;AAAA,EACL,SAAS,OAAO;AACZ,UAAM,IAAI;AAAA,MACN;AAAA,MACA,iBAAiB,QAAQ,QAAQ;AAAA,IACrC;AAAA,EACJ;AAEA,MAAI;AACJ,MAAI,eAAe,gBAAgB;AAC/B,qBAAiB,eAAe;AAAA,EACpC,WAAW,eAAe,eAAe,eAAe,cAAc;AAClE,UAAM,EAAE,yBAAyB,IAAI,MAAM,OAAO,sBAAsB;AACxE,qBAAiB,yBAAyB;AAAA,MACtC,aAAa,eAAe;AAAA,MAC5B,cAAc,eAAe;AAAA,IACjC,CAAC;AAAA,EACL,OAAO;AACH,UAAM,IAAI;AAAA,MACN;AAAA,IACJ;AAAA,EACJ;AAEA,SAAO,IAAI,cAAc,SAAS,gBAAgB,cAAc;AACpE;","names":[]}
+{"version":3,"sources":["../../src/stick/index.ts"],"sourcesContent":["import './allow_cli.js';\n// Type-only import — erased at runtime, won't trigger module loading\nimport type { WoodStaticRenderer } from './static_renderer.js';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { resolveImageRendererTemplate } from './template_resolver.js';\n\nexport type { WoodStaticRenderer };\nexport type {\n    WoodStaticRendererConfig,\n    WoodRenderOptions,\n    WoodRenderToPageOptions,\n    WoodRenderResult,\n} from './static_renderer.js';\n\n// ─────────────────────────────────────────────────────────────\n// Error Classes\n// ─────────────────────────────────────────────────────────────\n\nexport class PlaywrightNotInstalledError extends Error {\n    name = 'PlaywrightNotInstalledError' as const;\n    constructor() {\n        super(\n            'ImageRenderer requires Playwright. Install it with:\\n' +\n            '  npm install playwright\\n' +\n            '  npx playwright install chromium'\n        );\n    }\n}\n\nexport class BrowserLaunchError extends Error {\n    name = 'BrowserLaunchError' as const;\n    constructor(message: string, public cause?: Error) {\n        super(message);\n    }\n}\n\nexport class RenderTimeoutError extends Error {\n    name = 'RenderTimeoutError' as const;\n    constructor(timeoutMs: number) {\n        super(`Render timed out after ${timeoutMs}ms`);\n    }\n}\n\nexport class RenderError extends Error {\n    name = 'RenderError' as const;\n    constructor(message: string, public cause?: Error) {\n        super(message);\n    }\n}\n\n// ─────────────────────────────────────────────────────────────\n// Types\n// ─────────────────────────────────────────────────────────────\n\nexport interface ImageRendererConfig {\n    /** Output directory for screenshots */\n    outputDir: string;\n    /** Default width (default: 1920) */\n    width?: number;\n    /** Default height (default: 1080) */\n    height?: number;\n    /** Device scale factor for retina (default: 1) */\n    deviceScaleFactor?: number;\n    /** Image format (default: 'png') */\n    format?: 'png' | 'jpeg';\n    /** JPEG quality 0-100 (default: 80) */\n    quality?: number;\n    /** Wait condition (default: 'networkidle') */\n    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';\n    /** Timeout in ms (default: 10000) */\n    timeoutMs?: number;\n    /** Custom HTML template with {{{HEAD}}}, {{{CSS}}}, {{{APP}}} placeholders */\n    template?: string;\n\n    // Static renderer config (one of these)\n    /** Pre-created WoodStaticRenderer instance */\n    staticRenderer?: WoodStaticRenderer;\n    /** OR: Path to views.yaml */\n    viewsConfig?: string;\n    /**\n     * Component directory (required if viewsConfig provided).\n     * When template is omitted, stick auto-loads <componentDir>/index.html and\n     * inlines <componentDir>/styles.css when present.\n     */\n    componentDir?: string;\n    /** Asset path mappings (e.g., { '/images': ['public/images'] }) */\n    assets?: Record<string, string[]>;\n}\n\nexport interface CaptureOptions {\n    /** View component data */\n    view?: any;\n    /** Layout data (one object per layout) */\n    layout?: any[];\n    /** Wood bridge object passed as a prop to layouts and views */\n    wood?: any;\n    /** Override width */\n    width?: number;\n    /** Override height */\n    height?: number;\n    /** Capture full page (default: true) */\n    fullPage?: boolean;\n    /** Callback executed after page load, before screenshot. Receives the Playwright page object. */\n    beforeCapture?: (page: any) => Promise<void>;\n}\n\nexport interface CaptureHtmlOptions {\n    /** Override width */\n    width?: number;\n    /** Override height */\n    height?: number;\n    /** Capture full page (default: true) */\n    fullPage?: boolean;\n    /** Callback executed after page load, before screenshot. Receives the Playwright page object. */\n    beforeCapture?: (page: any) => Promise<void>;\n}\n\ninterface CaptureResult {\n    /** Raw image buffer */\n    buffer: Buffer;\n    /** Path where image was saved */\n    path: string;\n}\n\n// ─────────────────────────────────────────────────────────────\n// Playwright Loader\n// ─────────────────────────────────────────────────────────────\n\ntype PlaywrightModule = typeof import('playwright');\n\nasync function loadPlaywright(): Promise<PlaywrightModule> {\n    try {\n        const playwright = await import('playwright');\n        return playwright;\n    } catch {\n        throw new PlaywrightNotInstalledError();\n    }\n}\n\n// ─────────────────────────────────────────────────────────────\n// Content Type Helper\n// ─────────────────────────────────────────────────────────────\n\nfunction getContentType(filePath: string): string {\n    const ext = path.extname(filePath).toLowerCase();\n    const types: Record<string, string> = {\n        '.png': 'image/png',\n        '.jpg': 'image/jpeg',\n        '.jpeg': 'image/jpeg',\n        '.gif': 'image/gif',\n        '.svg': 'image/svg+xml',\n        '.webp': 'image/webp',\n        '.css': 'text/css',\n        '.js': 'application/javascript',\n        '.json': 'application/json',\n        '.woff': 'font/woff',\n        '.woff2': 'font/woff2',\n        '.ttf': 'font/ttf',\n    };\n    return types[ext] || 'application/octet-stream';\n}\n\n// ─────────────────────────────────────────────────────────────\n// ImageRenderer Class\n// ─────────────────────────────────────────────────────────────\n\nexport class ImageRenderer {\n    private browser: any;\n    private staticRenderer: WoodStaticRenderer;\n    private config: Required<Omit<ImageRendererConfig, 'staticRenderer' | 'viewsConfig' | 'componentDir' | 'template' | 'assets'>> & {\n        outputDir: string;\n        template?: string;\n        assets?: Record<string, string[]>;\n    };\n\n    constructor(\n        browser: any,\n        staticRenderer: WoodStaticRenderer,\n        config: ImageRendererConfig\n    ) {\n        this.browser = browser;\n        this.staticRenderer = staticRenderer;\n        this.config = {\n            outputDir: config.outputDir,\n            width: config.width ?? 1920,\n            height: config.height ?? 1080,\n            deviceScaleFactor: config.deviceScaleFactor ?? 1,\n            format: config.format ?? 'png',\n            quality: config.quality ?? 80,\n            waitUntil: config.waitUntil ?? 'networkidle',\n            timeoutMs: config.timeoutMs ?? 10000,\n            template: config.template,\n            assets: config.assets,\n        };\n    }\n\n    /**\n     * Capture a view by dot-path key and save to outputDir\n     */\n    async capture(\n        name: string,\n        viewKey: string,\n        options?: CaptureOptions\n    ): Promise<CaptureResult> {\n        const { view, layout, wood } = options ?? {};\n        const html = await this.staticRenderer.renderToPage({\n            viewKey,\n            data: { view, layout },\n            wood,\n            template: this.config.template,\n        });\n\n        return this.captureHtmlInternal(name, html, options);\n    }\n\n    /**\n     * Capture raw HTML and save to outputDir\n     */\n    async captureHtml(\n        name: string,\n        html: string,\n        options?: CaptureHtmlOptions\n    ): Promise<CaptureResult> {\n        return this.captureHtmlInternal(name, html, options);\n    }\n\n    /**\n     * Internal method to capture HTML to image\n     */\n    private async captureHtmlInternal(\n        name: string,\n        html: string,\n        options?: CaptureHtmlOptions\n    ): Promise<CaptureResult> {\n        const width = options?.width ?? this.config.width;\n        const height = options?.height ?? this.config.height;\n\n        let context: any;\n        let page: any;\n\n        try {\n            context = await this.browser.newContext({\n                viewport: { width, height },\n                deviceScaleFactor: this.config.deviceScaleFactor,\n            });\n\n            page = await context.newPage();\n\n            // Route Interception Strategy:\n            // We use page.goto() with a fake URL instead of page.setContent() because\n            // setContent() has no base URL, so relative paths can't resolve.\n            const FAKE_BASE_URL = 'http://stick-renderer/';\n\n            await page.route(FAKE_BASE_URL, async (route: any) => {\n                await route.fulfill({\n                    body: html,\n                    contentType: 'text/html',\n                });\n            });\n\n            // Asset route interception\n            if (this.config.assets) {\n                for (const [urlPath, fsPaths] of Object.entries(this.config.assets)) {\n                    await page.route(`**${urlPath}/**`, async (route: any) => {\n                        const url = new URL(route.request().url());\n                        const relativePath = url.pathname.replace(urlPath, '');\n\n                        for (const fsPath of fsPaths) {\n                            const filePath = path.join(fsPath, relativePath);\n                            try {\n                                const body = await fs.promises.readFile(filePath);\n                                const contentType = getContentType(filePath);\n                                await route.fulfill({ body, contentType });\n                                return;\n                            } catch {\n                                // File not found in this path, try the next one\n                            }\n                        }\n\n                        await route.abort('filenotfound');\n                    });\n                }\n            }\n\n            const waitUntilMapping = {\n                'load': 'load',\n                'domcontentloaded': 'domcontentloaded',\n                'networkidle': 'networkidle',\n            } as const;\n\n            try {\n                await page.goto(FAKE_BASE_URL, {\n                    waitUntil: waitUntilMapping[this.config.waitUntil],\n                    timeout: this.config.timeoutMs,\n                });\n            } catch (error) {\n                if (error instanceof Error && error.message.includes('timeout')) {\n                    throw new RenderTimeoutError(this.config.timeoutMs);\n                }\n                throw new RenderError(\n                    'Failed to render HTML content',\n                    error instanceof Error ? error : undefined\n                );\n            }\n\n            if (options?.beforeCapture) {\n                await options.beforeCapture(page);\n            }\n\n            const screenshotOptions: {\n                type: 'png' | 'jpeg';\n                quality?: number;\n                fullPage: boolean;\n            } = {\n                type: this.config.format,\n                fullPage: options?.fullPage ?? true,\n            };\n\n            if (this.config.format === 'jpeg') {\n                screenshotOptions.quality = this.config.quality;\n            }\n\n            const screenshot = await page.screenshot(screenshotOptions);\n            const buffer = Buffer.from(screenshot);\n\n            const filename = `${name}@${width}x${height}.${this.config.format}`;\n            const outputPath = path.join(this.config.outputDir, filename);\n\n            await fs.promises.mkdir(this.config.outputDir, { recursive: true });\n            await fs.promises.writeFile(outputPath, buffer);\n\n            return { buffer, path: outputPath };\n\n        } finally {\n            if (page) {\n                await page.close().catch(() => {});\n            }\n            if (context) {\n                await context.close().catch(() => {});\n            }\n        }\n    }\n\n    /**\n     * Close browser and clean up resources\n     */\n    async close(): Promise<void> {\n        if (this.browser) {\n            await this.browser.close().catch(() => {});\n        }\n    }\n}\n\n// ─────────────────────────────────────────────────────────────\n// Factory Function\n// ─────────────────────────────────────────────────────────────\n\nexport async function createImageRenderer(\n    config: ImageRendererConfig\n): Promise<ImageRenderer> {\n    const resolvedTemplate = resolveImageRendererTemplate({\n        template: config.template,\n        componentDir: config.componentDir,\n    });\n    const resolvedConfig: ImageRendererConfig = {\n        ...config,\n        template: resolvedTemplate,\n    };\n\n    const playwright = await loadPlaywright();\n\n    let browser: any;\n    try {\n        browser = await playwright.chromium.launch({\n            headless: true,\n        });\n    } catch (error) {\n        throw new BrowserLaunchError(\n            'Failed to launch Chromium. Ensure it is installed with: npx playwright install chromium',\n            error instanceof Error ? error : undefined\n        );\n    }\n\n    let staticRenderer: WoodStaticRenderer;\n    if (resolvedConfig.staticRenderer) {\n        staticRenderer = resolvedConfig.staticRenderer;\n    } else if (resolvedConfig.viewsConfig && resolvedConfig.componentDir) {\n        const { createWoodStaticRenderer } = await import('./static_renderer.js');\n        staticRenderer = createWoodStaticRenderer({\n            viewsConfig: resolvedConfig.viewsConfig,\n            componentDir: resolvedConfig.componentDir,\n        });\n    } else {\n        throw new Error(\n            'ImageRendererConfig requires either staticRenderer or both viewsConfig and componentDir'\n        );\n    }\n\n    return new ImageRenderer(browser, staticRenderer, resolvedConfig);\n}\n"],"mappings":"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","names":[]}

package/dist/testing/automation_assertions.cjs

@@ -0,0 +1,417 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var automation_assertions_exports = {};
+__export(automation_assertions_exports, {
+  automationAssertions: () => automationAssertions,
+  evenSpacing: () => evenSpacing,
+  evenSpacingRects: () => import_geometry.evenSpacing,
+  gaps: () => import_geometry.gaps,
+  hidden: () => hidden,
+  hitTestReachable: () => hitTestReachable,
+  insideViewport: () => insideViewport,
+  notClipped: () => notClipped,
+  notOverlapping: () => notOverlapping,
+  rectsOverlap: () => import_geometry.rectsOverlap,
+  sharedEdges: () => sharedEdges,
+  sharedRectEdges: () => import_geometry.sharedEdges,
+  stableAfterAnimation: () => stableAfterAnimation,
+  visible: () => visible
+});
+module.exports = __toCommonJS(automation_assertions_exports);
+var import_geometry = require("./geometry.js");
+function failure(message, details) {
+  return details ? { pass: false, message, details } : { pass: false, message };
+}
+function success(message, details) {
+  return details ? { pass: true, message, details } : { pass: true, message };
+}
+function errorDetails(error) {
+  return {
+    error: error instanceof Error ? error.message : String(error)
+  };
+}
+function locatorFor(page, target) {
+  return typeof target === "string" ? page.locator(target).first() : target.first();
+}
+function targetName(target) {
+  return typeof target === "string" ? `"${target}"` : "<locator>";
+}
+function isRectBox(target) {
+  const candidate = target;
+  return typeof candidate.top === "number" && typeof candidate.left === "number" && typeof candidate.right === "number" && typeof candidate.bottom === "number" && typeof candidate.width === "number" && typeof candidate.height === "number";
+}
+async function rectFor(page, target) {
+  if (isRectBox(target)) return target;
+  const box = await locatorFor(page, target).boundingBox();
+  if (!box) return null;
+  return {
+    top: box.y,
+    left: box.x,
+    right: box.x + box.width,
+    bottom: box.y + box.height,
+    width: box.width,
+    height: box.height
+  };
+}
+async function visible(page, target) {
+  try {
+    const pass = await locatorFor(page, target).isVisible();
+    return pass ? success(`Expected ${targetName(target)} to be visible.`) : failure(`Expected ${targetName(target)} to be visible, but it was hidden or missing.`);
+  } catch (error) {
+    return failure(
+      `Could not determine whether ${targetName(target)} is visible.`,
+      errorDetails(error)
+    );
+  }
+}
+async function hidden(page, target) {
+  try {
+    const pass = !await locatorFor(page, target).isVisible();
+    return pass ? success(`Expected ${targetName(target)} to be hidden.`) : failure(`Expected ${targetName(target)} to be hidden, but it was visible.`);
+  } catch (error) {
+    return failure(
+      `Could not determine whether ${targetName(target)} is hidden.`,
+      errorDetails(error)
+    );
+  }
+}
+async function insideViewport(page, target, options = {}) {
+  try {
+    const margin = options.margin ?? 0;
+    const rect = await rectFor(page, target);
+    if (!rect) {
+      return failure("Expected target to have a visible bounding box.", { margin });
+    }
+    const viewport = page.viewportSize() ?? await page.evaluate(() => ({
+      width: window.innerWidth,
+      height: window.innerHeight
+    }));
+    const pass = rect.left >= margin && rect.top >= margin && rect.right <= viewport.width - margin && rect.bottom <= viewport.height - margin;
+    const details = { rect, viewport, margin };
+    return pass ? success("Target is inside the viewport.", details) : failure("Target extends outside the viewport.", details);
+  } catch (error) {
+    return failure("Could not assert viewport bounds.", errorDetails(error));
+  }
+}
+async function notClipped(page, target) {
+  try {
+    const result = await locatorFor(page, target).evaluate((element) => {
+      const rect = element.getBoundingClientRect();
+      let parent = element.parentElement;
+      while (parent) {
+        const style = window.getComputedStyle(parent);
+        const clipsX = /(auto|hidden|scroll|clip)/.test(style.overflowX);
+        const clipsY = /(auto|hidden|scroll|clip)/.test(style.overflowY);
+        if (clipsX || clipsY) {
+          const parentRect = parent.getBoundingClientRect();
+          const clippedX = clipsX && (rect.left < parentRect.left || rect.right > parentRect.right);
+          const clippedY = clipsY && (rect.top < parentRect.top || rect.bottom > parentRect.bottom);
+          if (clippedX || clippedY) {
+            return {
+              pass: false,
+              ancestor: {
+                tag: parent.tagName,
+                id: parent.id || null,
+                classes: Array.from(parent.classList)
+              },
+              rect: {
+                top: rect.top,
+                left: rect.left,
+                right: rect.right,
+                bottom: rect.bottom,
+                width: rect.width,
+                height: rect.height
+              },
+              ancestorRect: {
+                top: parentRect.top,
+                left: parentRect.left,
+                right: parentRect.right,
+                bottom: parentRect.bottom,
+                width: parentRect.width,
+                height: parentRect.height
+              },
+              clippedX,
+              clippedY
+            };
+          }
+        }
+        parent = parent.parentElement;
+      }
+      return { pass: true };
+    });
+    return result.pass ? success(`Expected ${targetName(target)} not to be clipped.`) : failure(
+      `Expected ${targetName(target)} not to be clipped, but an overflow ancestor clips it.`,
+      result
+    );
+  } catch (error) {
+    return failure(
+      `Could not determine whether ${targetName(target)} is clipped.`,
+      errorDetails(error)
+    );
+  }
+}
+async function notOverlapping(page, firstTarget, secondTarget) {
+  try {
+    const [first, second] = await Promise.all([
+      rectFor(page, firstTarget),
+      rectFor(page, secondTarget)
+    ]);
+    if (!first || !second) {
+      return failure("Expected both targets to have visible bounding boxes.", {
+        first,
+        second
+      });
+    }
+    const overlap = (0, import_geometry.rectsOverlap)(first, second);
+    const details = { first, second };
+    return overlap ? failure("Expected targets not to overlap, but their border boxes intersect.", details) : success("Targets do not overlap.", details);
+  } catch (error) {
+    return failure("Could not compare target overlap.", errorDetails(error));
+  }
+}
+async function hitTestReachable(page, target) {
+  try {
+    const result = await locatorFor(page, target).evaluate((element) => {
+      if (typeof document.elementFromPoint !== "function") {
+        return {
+          supported: false,
+          capability: "DOM document.elementFromPoint"
+        };
+      }
+      const rect = element.getBoundingClientRect();
+      const point = {
+        x: rect.left + rect.width / 2,
+        y: rect.top + rect.height / 2
+      };
+      const hit = document.elementFromPoint(point.x, point.y);
+      const reachable = Boolean(
+        hit && (hit === element || element.contains(hit) || hit.contains(element))
+      );
+      return {
+        supported: true,
+        reachable,
+        point,
+        targetRect: {
+          top: rect.top,
+          left: rect.left,
+          right: rect.right,
+          bottom: rect.bottom,
+          width: rect.width,
+          height: rect.height
+        },
+        hit: hit ? {
+          tag: hit.tagName,
+          id: hit.id || null,
+          classes: Array.from(hit.classList)
+        } : null,
+        relationship: hit ? {
+          isTarget: hit === element,
+          isDescendant: element.contains(hit),
+          isAncestor: hit.contains(element)
+        } : null
+      };
+    });
+    if (!result.supported) {
+      return failure(
+        "Hit testing is unsupported on this page surface.",
+        { capability: result.capability }
+      );
+    }
+    return result.reachable ? success(`Center of ${targetName(target)} is hit-test reachable.`, result) : failure(
+      `Center of ${targetName(target)} is covered by a foreign element.`,
+      result
+    );
+  } catch (error) {
+    return failure(
+      `Could not hit-test ${targetName(target)}.`,
+      errorDetails(error)
+    );
+  }
+}
+async function sharedEdgesOnPage(page, targets, edge, options) {
+  try {
+    const rects = await Promise.all(targets.map((target) => rectFor(page, target)));
+    if (rects.some((rect) => rect === null)) {
+      return failure("Expected every target to have a visible bounding box.", {
+        missingIndices: rects.map((rect, index) => rect === null ? index : -1).filter((index) => index >= 0)
+      });
+    }
+    return (0, import_geometry.sharedEdges)(rects, edge, options);
+  } catch (error) {
+    return failure("Could not compare target edges.", errorDetails(error));
+  }
+}
+function sharedEdges(pageOrRects, targetsOrEdge, edgeOrOptions = {}, options = {}) {
+  if (Array.isArray(pageOrRects)) {
+    return (0, import_geometry.sharedEdges)(
+      pageOrRects,
+      targetsOrEdge,
+      edgeOrOptions
+    );
+  }
+  return sharedEdgesOnPage(
+    pageOrRects,
+    targetsOrEdge,
+    edgeOrOptions,
+    options
+  );
+}
+async function evenSpacingOnPage(page, targets, axis, options) {
+  try {
+    const rects = await Promise.all(targets.map((target) => rectFor(page, target)));
+    if (rects.some((rect) => rect === null)) {
+      return failure("Expected every target to have a visible bounding box.", {
+        missingIndices: rects.map((rect, index) => rect === null ? index : -1).filter((index) => index >= 0)
+      });
+    }
+    return (0, import_geometry.evenSpacing)(rects, axis, options);
+  } catch (error) {
+    return failure("Could not compare target spacing.", errorDetails(error));
+  }
+}
+function evenSpacing(pageOrRects, targetsOrAxis, axisOrOptions = {}, options = {}) {
+  if (Array.isArray(pageOrRects)) {
+    return (0, import_geometry.evenSpacing)(
+      pageOrRects,
+      targetsOrAxis,
+      axisOrOptions
+    );
+  }
+  return evenSpacingOnPage(
+    pageOrRects,
+    targetsOrAxis,
+    axisOrOptions,
+    options
+  );
+}
+async function stableAfterAnimation(page, target, options = {}) {
+  const frameCount = options.frameCount ?? 3;
+  const tolerance = options.tolerance ?? 0;
+  const timeoutMs = options.timeoutMs ?? 2e3;
+  if (!Number.isInteger(frameCount) || frameCount < 1) {
+    return failure("frameCount must be a positive integer.", { frameCount });
+  }
+  try {
+    const result = await locatorFor(page, target).evaluate(
+      async (element, input) => {
+        if (typeof window.requestAnimationFrame !== "function") {
+          return {
+            supported: false,
+            capability: "DOM window.requestAnimationFrame"
+          };
+        }
+        const read = () => {
+          const rect = element.getBoundingClientRect();
+          return {
+            top: rect.top,
+            left: rect.left,
+            right: rect.right,
+            bottom: rect.bottom,
+            width: rect.width,
+            height: rect.height
+          };
+        };
+        const samples = [read()];
+        let timedOut = false;
+        const timeout = window.setTimeout(() => {
+          timedOut = true;
+        }, input.timeoutMs);
+        for (let index = 0; index < input.frameCount && !timedOut; index += 1) {
+          await new Promise((resolve) => {
+            window.requestAnimationFrame(() => resolve());
+          });
+          samples.push(read());
+        }
+        window.clearTimeout(timeout);
+        if (timedOut) {
+          return { supported: true, timedOut: true, samples };
+        }
+        const first = samples[0];
+        const keys = ["top", "left", "right", "bottom", "width", "height"];
+        let maximumDelta = 0;
+        for (const sample of samples.slice(1)) {
+          for (const key of keys) {
+            maximumDelta = Math.max(maximumDelta, Math.abs(sample[key] - first[key]));
+          }
+        }
+        return {
+          supported: true,
+          timedOut: false,
+          stable: maximumDelta <= input.tolerance,
+          maximumDelta,
+          samples
+        };
+      },
+      { frameCount, tolerance, timeoutMs }
+    );
+    if (!result.supported) {
+      return failure(
+        "Animation stability sampling is unsupported on this page surface.",
+        { capability: result.capability }
+      );
+    }
+    if (result.timedOut) {
+      return failure(
+        `Animation stability sampling timed out after ${timeoutMs}ms.`,
+        result
+      );
+    }
+    return result.stable ? success(
+      `Bounding box stayed stable across ${frameCount} animation frames.`,
+      result
+    ) : failure(
+      `Bounding box changed across ${frameCount} animation frames.`,
+      result
+    );
+  } catch (error) {
+    return failure(
+      `Could not sample animation stability for ${targetName(target)}.`,
+      errorDetails(error)
+    );
+  }
+}
+const automationAssertions = {
+  visible,
+  hidden,
+  insideViewport,
+  notClipped,
+  notOverlapping,
+  hitTestReachable,
+  sharedEdges,
+  evenSpacing,
+  stableAfterAnimation
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  automationAssertions,
+  evenSpacing,
+  evenSpacingRects,
+  gaps,
+  hidden,
+  hitTestReachable,
+  insideViewport,
+  notClipped,
+  notOverlapping,
+  rectsOverlap,
+  sharedEdges,
+  sharedRectEdges,
+  stableAfterAnimation,
+  visible
+});
+//# sourceMappingURL=automation_assertions.cjs.map

package/dist/testing/automation_assertions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/automation_assertions.ts"],"sourcesContent":["import type { Locator, Page } from 'playwright';\nimport {\n  evenSpacing as evenSpacingRects,\n  gaps,\n  rectsOverlap,\n  sharedEdges as sharedRectEdges,\n  type GeometryVerdict,\n  type RectAxis,\n  type RectBox,\n  type RectEdge,\n} from './geometry.js';\n\nexport {\n  gaps,\n  rectsOverlap,\n  evenSpacingRects,\n  sharedRectEdges,\n};\nexport type {\n  GeometryVerdict,\n  RectAxis,\n  RectBox,\n  RectEdge,\n};\n\nexport interface AssertionVerdict {\n  pass: boolean;\n  message: string;\n  details?: Record<string, unknown>;\n}\n\nexport type AutomationTarget = string | Locator;\nexport type AutomationRectTarget = AutomationTarget | RectBox;\n\nfunction failure(\n  message: string,\n  details?: Record<string, unknown>,\n): AssertionVerdict {\n  return details ? { pass: false, message, details } : { pass: false, message };\n}\n\nfunction success(\n  message: string,\n  details?: Record<string, unknown>,\n): AssertionVerdict {\n  return details ? { pass: true, message, details } : { pass: true, message };\n}\n\nfunction errorDetails(error: unknown): Record<string, unknown> {\n  return {\n    error: error instanceof Error ? error.message : String(error),\n  };\n}\n\nfunction locatorFor(page: Page, target: AutomationTarget): Locator {\n  return typeof target === 'string' ? page.locator(target).first() : target.first();\n}\n\nfunction targetName(target: AutomationTarget): string {\n  return typeof target === 'string' ? `\"${target}\"` : '<locator>';\n}\n\nfunction isRectBox(target: AutomationRectTarget): target is RectBox {\n  const candidate = target as Partial<RectBox>;\n  return typeof candidate.top === 'number'\n    && typeof candidate.left === 'number'\n    && typeof candidate.right === 'number'\n    && typeof candidate.bottom === 'number'\n    && typeof candidate.width === 'number'\n    && typeof candidate.height === 'number';\n}\n\nasync function rectFor(\n  page: Page,\n  target: AutomationRectTarget,\n): Promise<RectBox | null> {\n  if (isRectBox(target)) return target;\n  const box = await locatorFor(page, target).boundingBox();\n  if (!box) return null;\n  return {\n    top: box.y,\n    left: box.x,\n    right: box.x + box.width,\n    bottom: box.y + box.height,\n    width: box.width,\n    height: box.height,\n  };\n}\n\nexport async function visible(\n  page: Page,\n  target: AutomationTarget,\n): Promise<AssertionVerdict> {\n  try {\n    const pass = await locatorFor(page, target).isVisible();\n    return pass\n      ? success(`Expected ${targetName(target)} to be visible.`)\n      : failure(`Expected ${targetName(target)} to be visible, but it was hidden or missing.`);\n  } catch (error) {\n    return failure(\n      `Could not determine whether ${targetName(target)} is visible.`,\n      errorDetails(error),\n    );\n  }\n}\n\nexport async function hidden(\n  page: Page,\n  target: AutomationTarget,\n): Promise<AssertionVerdict> {\n  try {\n    const pass = !(await locatorFor(page, target).isVisible());\n    return pass\n      ? success(`Expected ${targetName(target)} to be hidden.`)\n      : failure(`Expected ${targetName(target)} to be hidden, but it was visible.`);\n  } catch (error) {\n    return failure(\n      `Could not determine whether ${targetName(target)} is hidden.`,\n      errorDetails(error),\n    );\n  }\n}\n\nexport async function insideViewport(\n  page: Page,\n  target: AutomationRectTarget,\n  options: { margin?: number } = {},\n): Promise<AssertionVerdict> {\n  try {\n    const margin = options.margin ?? 0;\n    const rect = await rectFor(page, target);\n    if (!rect) {\n      return failure('Expected target to have a visible bounding box.', { margin });\n    }\n    const viewport = page.viewportSize() ?? await page.evaluate(() => ({\n      width: window.innerWidth,\n      height: window.innerHeight,\n    }));\n    const pass = rect.left >= margin\n      && rect.top >= margin\n      && rect.right <= viewport.width - margin\n      && rect.bottom <= viewport.height - margin;\n    const details = { rect, viewport, margin };\n    return pass\n      ? success('Target is inside the viewport.', details)\n      : failure('Target extends outside the viewport.', details);\n  } catch (error) {\n    return failure('Could not assert viewport bounds.', errorDetails(error));\n  }\n}\n\nexport async function notClipped(\n  page: Page,\n  target: AutomationTarget,\n): Promise<AssertionVerdict> {\n  try {\n    const result = await locatorFor(page, target).evaluate((element: Element) => {\n      const rect = element.getBoundingClientRect();\n      let parent = element.parentElement;\n      while (parent) {\n        const style = window.getComputedStyle(parent);\n        const clipsX = /(auto|hidden|scroll|clip)/.test(style.overflowX);\n        const clipsY = /(auto|hidden|scroll|clip)/.test(style.overflowY);\n        if (clipsX || clipsY) {\n          const parentRect = parent.getBoundingClientRect();\n          const clippedX = clipsX\n            && (rect.left < parentRect.left || rect.right > parentRect.right);\n          const clippedY = clipsY\n            && (rect.top < parentRect.top || rect.bottom > parentRect.bottom);\n          if (clippedX || clippedY) {\n            return {\n              pass: false,\n              ancestor: {\n                tag: parent.tagName,\n                id: parent.id || null,\n                classes: Array.from(parent.classList),\n              },\n              rect: {\n                top: rect.top,\n                left: rect.left,\n                right: rect.right,\n                bottom: rect.bottom,\n                width: rect.width,\n                height: rect.height,\n              },\n              ancestorRect: {\n                top: parentRect.top,\n                left: parentRect.left,\n                right: parentRect.right,\n                bottom: parentRect.bottom,\n                width: parentRect.width,\n                height: parentRect.height,\n              },\n              clippedX,\n              clippedY,\n            };\n          }\n        }\n        parent = parent.parentElement;\n      }\n      return { pass: true };\n    });\n\n    return result.pass\n      ? success(`Expected ${targetName(target)} not to be clipped.`)\n      : failure(\n        `Expected ${targetName(target)} not to be clipped, but an overflow ancestor clips it.`,\n        result,\n      );\n  } catch (error) {\n    return failure(\n      `Could not determine whether ${targetName(target)} is clipped.`,\n      errorDetails(error),\n    );\n  }\n}\n\nexport async function notOverlapping(\n  page: Page,\n  firstTarget: AutomationRectTarget,\n  secondTarget: AutomationRectTarget,\n): Promise<AssertionVerdict> {\n  try {\n    const [first, second] = await Promise.all([\n      rectFor(page, firstTarget),\n      rectFor(page, secondTarget),\n    ]);\n    if (!first || !second) {\n      return failure('Expected both targets to have visible bounding boxes.', {\n        first,\n        second,\n      });\n    }\n    const overlap = rectsOverlap(first, second);\n    const details = { first, second };\n    return overlap\n      ? failure('Expected targets not to overlap, but their border boxes intersect.', details)\n      : success('Targets do not overlap.', details);\n  } catch (error) {\n    return failure('Could not compare target overlap.', errorDetails(error));\n  }\n}\n\nexport async function hitTestReachable(\n  page: Page,\n  target: AutomationTarget,\n): Promise<AssertionVerdict> {\n  try {\n    const result = await locatorFor(page, target).evaluate((element: Element) => {\n      if (typeof document.elementFromPoint !== 'function') {\n        return {\n          supported: false as const,\n          capability: 'DOM document.elementFromPoint',\n        };\n      }\n      const rect = element.getBoundingClientRect();\n      const point = {\n        x: rect.left + rect.width / 2,\n        y: rect.top + rect.height / 2,\n      };\n      const hit = document.elementFromPoint(point.x, point.y);\n      const reachable = Boolean(\n        hit\n        && (hit === element || element.contains(hit) || hit.contains(element)),\n      );\n      return {\n        supported: true as const,\n        reachable,\n        point,\n        targetRect: {\n          top: rect.top,\n          left: rect.left,\n          right: rect.right,\n          bottom: rect.bottom,\n          width: rect.width,\n          height: rect.height,\n        },\n        hit: hit ? {\n          tag: hit.tagName,\n          id: hit.id || null,\n          classes: Array.from(hit.classList),\n        } : null,\n        relationship: hit ? {\n          isTarget: hit === element,\n          isDescendant: element.contains(hit),\n          isAncestor: hit.contains(element),\n        } : null,\n      };\n    });\n\n    if (!result.supported) {\n      return failure(\n        'Hit testing is unsupported on this page surface.',\n        { capability: result.capability },\n      );\n    }\n    return result.reachable\n      ? success(`Center of ${targetName(target)} is hit-test reachable.`, result)\n      : failure(\n        `Center of ${targetName(target)} is covered by a foreign element.`,\n        result,\n      );\n  } catch (error) {\n    return failure(\n      `Could not hit-test ${targetName(target)}.`,\n      errorDetails(error),\n    );\n  }\n}\n\ntype GeometryOptions = { tolerance?: number };\n\nasync function sharedEdgesOnPage(\n  page: Page,\n  targets: readonly AutomationRectTarget[],\n  edge: RectEdge,\n  options: GeometryOptions,\n): Promise<AssertionVerdict> {\n  try {\n    const rects = await Promise.all(targets.map((target) => rectFor(page, target)));\n    if (rects.some((rect) => rect === null)) {\n      return failure('Expected every target to have a visible bounding box.', {\n        missingIndices: rects\n          .map((rect, index) => rect === null ? index : -1)\n          .filter((index) => index >= 0),\n      });\n    }\n    return sharedRectEdges(rects as RectBox[], edge, options);\n  } catch (error) {\n    return failure('Could not compare target edges.', errorDetails(error));\n  }\n}\n\nexport function sharedEdges(\n  rects: readonly RectBox[],\n  edge: RectEdge,\n  options?: GeometryOptions,\n): GeometryVerdict;\nexport function sharedEdges(\n  page: Page,\n  targets: readonly AutomationRectTarget[],\n  edge: RectEdge,\n  options?: GeometryOptions,\n): Promise<AssertionVerdict>;\nexport function sharedEdges(\n  pageOrRects: Page | readonly RectBox[],\n  targetsOrEdge: readonly AutomationRectTarget[] | RectEdge,\n  edgeOrOptions: RectEdge | GeometryOptions = {},\n  options: GeometryOptions = {},\n): GeometryVerdict | Promise<AssertionVerdict> {\n  if (Array.isArray(pageOrRects)) {\n    return sharedRectEdges(\n      pageOrRects,\n      targetsOrEdge as RectEdge,\n      edgeOrOptions as GeometryOptions,\n    );\n  }\n  return sharedEdgesOnPage(\n    pageOrRects as Page,\n    targetsOrEdge as readonly AutomationRectTarget[],\n    edgeOrOptions as RectEdge,\n    options,\n  );\n}\n\nasync function evenSpacingOnPage(\n  page: Page,\n  targets: readonly AutomationRectTarget[],\n  axis: RectAxis,\n  options: GeometryOptions,\n): Promise<AssertionVerdict> {\n  try {\n    const rects = await Promise.all(targets.map((target) => rectFor(page, target)));\n    if (rects.some((rect) => rect === null)) {\n      return failure('Expected every target to have a visible bounding box.', {\n        missingIndices: rects\n          .map((rect, index) => rect === null ? index : -1)\n          .filter((index) => index >= 0),\n      });\n    }\n    return evenSpacingRects(rects as RectBox[], axis, options);\n  } catch (error) {\n    return failure('Could not compare target spacing.', errorDetails(error));\n  }\n}\n\nexport function evenSpacing(\n  rects: readonly RectBox[],\n  axis: RectAxis,\n  options?: GeometryOptions,\n): GeometryVerdict;\nexport function evenSpacing(\n  page: Page,\n  targets: readonly AutomationRectTarget[],\n  axis: RectAxis,\n  options?: GeometryOptions,\n): Promise<AssertionVerdict>;\nexport function evenSpacing(\n  pageOrRects: Page | readonly RectBox[],\n  targetsOrAxis: readonly AutomationRectTarget[] | RectAxis,\n  axisOrOptions: RectAxis | GeometryOptions = {},\n  options: GeometryOptions = {},\n): GeometryVerdict | Promise<AssertionVerdict> {\n  if (Array.isArray(pageOrRects)) {\n    return evenSpacingRects(\n      pageOrRects,\n      targetsOrAxis as RectAxis,\n      axisOrOptions as GeometryOptions,\n    );\n  }\n  return evenSpacingOnPage(\n    pageOrRects as Page,\n    targetsOrAxis as readonly AutomationRectTarget[],\n    axisOrOptions as RectAxis,\n    options,\n  );\n}\n\nexport async function stableAfterAnimation(\n  page: Page,\n  target: AutomationTarget,\n  options: { frameCount?: number; tolerance?: number; timeoutMs?: number } = {},\n): Promise<AssertionVerdict> {\n  const frameCount = options.frameCount ?? 3;\n  const tolerance = options.tolerance ?? 0;\n  const timeoutMs = options.timeoutMs ?? 2000;\n  if (!Number.isInteger(frameCount) || frameCount < 1) {\n    return failure('frameCount must be a positive integer.', { frameCount });\n  }\n\n  try {\n    const result = await locatorFor(page, target).evaluate(\n      async (element: Element, input: {\n        frameCount: number;\n        tolerance: number;\n        timeoutMs: number;\n      }) => {\n        if (typeof window.requestAnimationFrame !== 'function') {\n          return {\n            supported: false as const,\n            capability: 'DOM window.requestAnimationFrame',\n          };\n        }\n        const read = () => {\n          const rect = element.getBoundingClientRect();\n          return {\n            top: rect.top,\n            left: rect.left,\n            right: rect.right,\n            bottom: rect.bottom,\n            width: rect.width,\n            height: rect.height,\n          };\n        };\n        const samples = [read()];\n        let timedOut = false;\n        const timeout = window.setTimeout(() => {\n          timedOut = true;\n        }, input.timeoutMs);\n        for (let index = 0; index < input.frameCount && !timedOut; index += 1) {\n          await new Promise<void>((resolve) => {\n            window.requestAnimationFrame(() => resolve());\n          });\n          samples.push(read());\n        }\n        window.clearTimeout(timeout);\n        if (timedOut) {\n          return { supported: true as const, timedOut: true, samples };\n        }\n\n        const first = samples[0];\n        const keys = ['top', 'left', 'right', 'bottom', 'width', 'height'] as const;\n        let maximumDelta = 0;\n        for (const sample of samples.slice(1)) {\n          for (const key of keys) {\n            maximumDelta = Math.max(maximumDelta, Math.abs(sample[key] - first[key]));\n          }\n        }\n        return {\n          supported: true as const,\n          timedOut: false,\n          stable: maximumDelta <= input.tolerance,\n          maximumDelta,\n          samples,\n        };\n      },\n      { frameCount, tolerance, timeoutMs },\n    );\n\n    if (!result.supported) {\n      return failure(\n        'Animation stability sampling is unsupported on this page surface.',\n        { capability: result.capability },\n      );\n    }\n    if (result.timedOut) {\n      return failure(\n        `Animation stability sampling timed out after ${timeoutMs}ms.`,\n        result,\n      );\n    }\n    return result.stable\n      ? success(\n        `Bounding box stayed stable across ${frameCount} animation frames.`,\n        result,\n      )\n      : failure(\n        `Bounding box changed across ${frameCount} animation frames.`,\n        result,\n      );\n  } catch (error) {\n    return failure(\n      `Could not sample animation stability for ${targetName(target)}.`,\n      errorDetails(error),\n    );\n  }\n}\n\nexport const automationAssertions = {\n  visible,\n  hidden,\n  insideViewport,\n  notClipped,\n  notOverlapping,\n  hitTestReachable,\n  sharedEdges,\n  evenSpacing,\n  stableAfterAnimation,\n};\n"],"mappings":"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","names":["evenSpacingRects","sharedRectEdges"]}

package/dist/testing/automation_assertions.d.cts

@@ -0,0 +1,44 @@
+import { Locator, Page } from 'playwright';
+import { RectBox, RectEdge, GeometryVerdict, RectAxis } from './geometry.cjs';
+export { evenSpacing as evenSpacingRects, gaps, rectsOverlap, sharedEdges as sharedRectEdges } from './geometry.cjs';
+
+interface AssertionVerdict {
+    pass: boolean;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type AutomationTarget = string | Locator;
+type AutomationRectTarget = AutomationTarget | RectBox;
+declare function visible(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+declare function hidden(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+declare function insideViewport(page: Page, target: AutomationRectTarget, options?: {
+    margin?: number;
+}): Promise<AssertionVerdict>;
+declare function notClipped(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+declare function notOverlapping(page: Page, firstTarget: AutomationRectTarget, secondTarget: AutomationRectTarget): Promise<AssertionVerdict>;
+declare function hitTestReachable(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+type GeometryOptions = {
+    tolerance?: number;
+};
+declare function sharedEdges(rects: readonly RectBox[], edge: RectEdge, options?: GeometryOptions): GeometryVerdict;
+declare function sharedEdges(page: Page, targets: readonly AutomationRectTarget[], edge: RectEdge, options?: GeometryOptions): Promise<AssertionVerdict>;
+declare function evenSpacing(rects: readonly RectBox[], axis: RectAxis, options?: GeometryOptions): GeometryVerdict;
+declare function evenSpacing(page: Page, targets: readonly AutomationRectTarget[], axis: RectAxis, options?: GeometryOptions): Promise<AssertionVerdict>;
+declare function stableAfterAnimation(page: Page, target: AutomationTarget, options?: {
+    frameCount?: number;
+    tolerance?: number;
+    timeoutMs?: number;
+}): Promise<AssertionVerdict>;
+declare const automationAssertions: {
+    visible: typeof visible;
+    hidden: typeof hidden;
+    insideViewport: typeof insideViewport;
+    notClipped: typeof notClipped;
+    notOverlapping: typeof notOverlapping;
+    hitTestReachable: typeof hitTestReachable;
+    sharedEdges: typeof sharedEdges;
+    evenSpacing: typeof evenSpacing;
+    stableAfterAnimation: typeof stableAfterAnimation;
+};
+
+export { type AssertionVerdict, type AutomationRectTarget, type AutomationTarget, GeometryVerdict, RectAxis, RectBox, RectEdge, automationAssertions, evenSpacing, hidden, hitTestReachable, insideViewport, notClipped, notOverlapping, sharedEdges, stableAfterAnimation, visible };

package/dist/testing/automation_assertions.d.ts

@@ -0,0 +1,44 @@
+import { Locator, Page } from 'playwright';
+import { RectBox, RectEdge, GeometryVerdict, RectAxis } from './geometry.js';
+export { evenSpacing as evenSpacingRects, gaps, rectsOverlap, sharedEdges as sharedRectEdges } from './geometry.js';
+
+interface AssertionVerdict {
+    pass: boolean;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type AutomationTarget = string | Locator;
+type AutomationRectTarget = AutomationTarget | RectBox;
+declare function visible(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+declare function hidden(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+declare function insideViewport(page: Page, target: AutomationRectTarget, options?: {
+    margin?: number;
+}): Promise<AssertionVerdict>;
+declare function notClipped(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+declare function notOverlapping(page: Page, firstTarget: AutomationRectTarget, secondTarget: AutomationRectTarget): Promise<AssertionVerdict>;
+declare function hitTestReachable(page: Page, target: AutomationTarget): Promise<AssertionVerdict>;
+type GeometryOptions = {
+    tolerance?: number;
+};
+declare function sharedEdges(rects: readonly RectBox[], edge: RectEdge, options?: GeometryOptions): GeometryVerdict;
+declare function sharedEdges(page: Page, targets: readonly AutomationRectTarget[], edge: RectEdge, options?: GeometryOptions): Promise<AssertionVerdict>;
+declare function evenSpacing(rects: readonly RectBox[], axis: RectAxis, options?: GeometryOptions): GeometryVerdict;
+declare function evenSpacing(page: Page, targets: readonly AutomationRectTarget[], axis: RectAxis, options?: GeometryOptions): Promise<AssertionVerdict>;
+declare function stableAfterAnimation(page: Page, target: AutomationTarget, options?: {
+    frameCount?: number;
+    tolerance?: number;
+    timeoutMs?: number;
+}): Promise<AssertionVerdict>;
+declare const automationAssertions: {
+    visible: typeof visible;
+    hidden: typeof hidden;
+    insideViewport: typeof insideViewport;
+    notClipped: typeof notClipped;
+    notOverlapping: typeof notOverlapping;
+    hitTestReachable: typeof hitTestReachable;
+    sharedEdges: typeof sharedEdges;
+    evenSpacing: typeof evenSpacing;
+    stableAfterAnimation: typeof stableAfterAnimation;
+};
+
+export { type AssertionVerdict, type AutomationRectTarget, type AutomationTarget, GeometryVerdict, RectAxis, RectBox, RectEdge, automationAssertions, evenSpacing, hidden, hitTestReachable, insideViewport, notClipped, notOverlapping, sharedEdges, stableAfterAnimation, visible };