comisai 1.0.4

package/node_modules/@comis/skills/dist/browser/screenshot-normalizer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Screenshot normalization with byte-limit enforcement.
+ *
+ * Uses sharp to resize and quality-sweep screenshots to stay under a
+ * configurable byte limit. Implements a grid search approach: try
+ * decreasing quality at current maxSide, then halve maxSide and
+ * retry with reset quality.
+ *
+ * Ported from Comis's normalizeBrowserScreenshot pattern.
+ * Supports rich screenshots with viewport control.
+ *
+ * @module
+ */
+import { type Result } from "@comis/shared";
+/** Options for screenshot normalization. */
+export interface NormalizeOptions {
+    /** Maximum dimension (width or height) in pixels. Default: 2000. */
+    readonly maxSide?: number;
+    /** Maximum output size in bytes. Default: 512000 (500KB). */
+    readonly maxBytes?: number;
+    /** Output image format. Default: "jpeg". */
+    readonly format?: "jpeg" | "png" | "webp";
+    /** Starting quality for lossy formats. Default: 85. */
+    readonly qualityStart?: number;
+    /** Quality decrease per sweep attempt. Default: 10. */
+    readonly qualityStep?: number;
+    /** Minimum quality before halving maxSide. Default: 30. */
+    readonly qualityMin?: number;
+}
+/** Result of screenshot normalization. */
+export interface NormalizedScreenshot {
+    /** The normalized image buffer. */
+    readonly buffer: Buffer;
+    /** Output image width. */
+    readonly width: number;
+    /** Output image height. */
+    readonly height: number;
+    /** Output format used. */
+    readonly format: string;
+    /** Quality level used (for lossy formats). */
+    readonly quality: number;
+    /** Original input buffer size in bytes. */
+    readonly originalBytes: number;
+    /** Normalized output buffer size in bytes. */
+    readonly normalizedBytes: number;
+}
+/**
+ * Normalize a screenshot buffer to stay under a byte limit.
+ *
+ * Uses a grid search approach:
+ * 1. Start with maxSide and qualityStart
+ * 2. If output exceeds maxBytes, decrease quality by qualityStep
+ * 3. If quality drops below qualityMin, halve maxSide and reset quality
+ * 4. Repeat up to 6 total attempts (2 maxSide values x 3 quality levels)
+ * 5. If still over maxBytes, return the smallest result achieved
+ *
+ * Returns err only on processing failure, not on "still too large".
+ *
+ * @param buffer - Input screenshot buffer (PNG, JPEG, etc.)
+ * @param opts - Normalization options
+ * @returns NormalizedScreenshot with size metadata
+ */
+export declare function normalizeScreenshot(buffer: Buffer, opts?: NormalizeOptions): Promise<Result<NormalizedScreenshot, Error>>;

package/node_modules/@comis/skills/dist/browser/screenshot-normalizer.js

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Screenshot normalization with byte-limit enforcement.
+ *
+ * Uses sharp to resize and quality-sweep screenshots to stay under a
+ * configurable byte limit. Implements a grid search approach: try
+ * decreasing quality at current maxSide, then halve maxSide and
+ * retry with reset quality.
+ *
+ * Ported from Comis's normalizeBrowserScreenshot pattern.
+ * Supports rich screenshots with viewport control.
+ *
+ * @module
+ */
+import sharp from "sharp";
+import { ok, err } from "@comis/shared";
+sharp.cache(false);
+const LIMIT_INPUT_PIXELS = 268_402_689;
+// ── Implementation ───────────────────────────────────────────────────
+/**
+ * Attempt a single resize + format pass at the given maxSide and quality.
+ */
+async function attempt(inputBuffer, maxSide, quality, format) {
+    let pipeline = sharp(inputBuffer, { limitInputPixels: LIMIT_INPUT_PIXELS })
+        .resize(maxSide, maxSide, {
+        fit: "inside",
+        withoutEnlargement: true,
+    });
+    if (format === "jpeg") {
+        pipeline = pipeline.jpeg({ quality });
+    }
+    else if (format === "webp") {
+        pipeline = pipeline.webp({ quality });
+    }
+    else {
+        // PNG -- quality maps to compressionLevel (0-9), higher = more compression
+        const compressionLevel = Math.min(9, Math.max(0, Math.round((100 - quality) / 10)));
+        pipeline = pipeline.png({ compressionLevel });
+    }
+    const outputBuffer = await pipeline.toBuffer();
+    const metadata = await sharp(outputBuffer, { limitInputPixels: LIMIT_INPUT_PIXELS }).metadata();
+    return {
+        buffer: outputBuffer,
+        width: metadata.width ?? 0,
+        height: metadata.height ?? 0,
+    };
+}
+/**
+ * Normalize a screenshot buffer to stay under a byte limit.
+ *
+ * Uses a grid search approach:
+ * 1. Start with maxSide and qualityStart
+ * 2. If output exceeds maxBytes, decrease quality by qualityStep
+ * 3. If quality drops below qualityMin, halve maxSide and reset quality
+ * 4. Repeat up to 6 total attempts (2 maxSide values x 3 quality levels)
+ * 5. If still over maxBytes, return the smallest result achieved
+ *
+ * Returns err only on processing failure, not on "still too large".
+ *
+ * @param buffer - Input screenshot buffer (PNG, JPEG, etc.)
+ * @param opts - Normalization options
+ * @returns NormalizedScreenshot with size metadata
+ */
+export async function normalizeScreenshot(buffer, opts) {
+    const maxSide = opts?.maxSide ?? 2000;
+    const maxBytes = opts?.maxBytes ?? 512_000;
+    const format = opts?.format ?? "jpeg";
+    const qualityStart = opts?.qualityStart ?? 85;
+    const qualityStep = opts?.qualityStep ?? 10;
+    const qualityMin = opts?.qualityMin ?? 30;
+    const originalBytes = buffer.length;
+    try {
+        let bestResult = null;
+        let currentMaxSide = maxSide;
+        // Try up to 2 maxSide levels (original, then halved)
+        for (let sizeLevel = 0; sizeLevel < 2; sizeLevel += 1) {
+            let quality = qualityStart;
+            // Try up to 3 quality levels per maxSide
+            for (let qualityLevel = 0; qualityLevel < 3; qualityLevel += 1) {
+                const result = await attempt(buffer, currentMaxSide, quality, format);
+                // Track best (smallest) result
+                if (!bestResult || result.buffer.length < bestResult.buffer.length) {
+                    bestResult = { ...result, quality };
+                }
+                // Under budget -- done
+                if (result.buffer.length <= maxBytes) {
+                    return ok({
+                        buffer: result.buffer,
+                        width: result.width,
+                        height: result.height,
+                        format,
+                        quality,
+                        originalBytes,
+                        normalizedBytes: result.buffer.length,
+                    });
+                }
+                // Decrease quality for next attempt
+                quality -= qualityStep;
+                if (quality < qualityMin)
+                    break;
+            }
+            // Halve maxSide for next round
+            currentMaxSide = Math.max(1, Math.round(currentMaxSide / 2));
+        }
+        // Return the smallest result we achieved (still over budget but best effort)
+        if (bestResult) {
+            return ok({
+                buffer: bestResult.buffer,
+                width: bestResult.width,
+                height: bestResult.height,
+                format,
+                quality: bestResult.quality,
+                originalBytes,
+                normalizedBytes: bestResult.buffer.length,
+            });
+        }
+        // Should not reach here, but handle gracefully
+        return err(new Error("normalizeScreenshot: no output produced"));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return err(new Error(`normalizeScreenshot failed: ${msg}`));
+    }
+}

package/node_modules/@comis/skills/dist/browser/screenshots.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Screenshot capture and PDF generation.
+ *
+ * Takes page screenshots via Playwright with size normalization (resize
+ * images exceeding screenshotMaxSide), supports element-scoped capture,
+ * and generates PDFs.
+ *
+ * Ported from Comis browser/screenshot.ts +
+ * pw-tools-core.interactions.ts (takeScreenshotViaPlaywright, pdfViaPlaywright),
+ * simplified without sharp-based resize (uses Playwright's built-in capture).
+ *
+ * @module
+ */
+import type { Page } from "playwright-core";
+export type ScreenshotOptions = {
+    /** Capture full page (scrolling). */
+    fullPage?: boolean;
+    /** Element ref from snapshot (e.g., "e12"). */
+    ref?: string;
+    /** CSS selector for element-scoped screenshot. */
+    element?: string;
+    /** Image type: "png" or "jpeg". */
+    type?: "png" | "jpeg";
+    /** JPEG quality (0-100). Only used for jpeg type. */
+    quality?: number;
+};
+export type ScreenshotResult = {
+    buffer: Buffer;
+    mimeType: string;
+    width?: number;
+    height?: number;
+};
+export type PdfResult = {
+    buffer: Buffer;
+    mimeType: "application/pdf";
+};
+/**
+ * Take a screenshot of a page, optionally scoped to an element.
+ *
+ * @param page - Playwright Page instance
+ * @param options - Screenshot options (fullPage, ref, element, type, quality)
+ * @returns Buffer with screenshot data and MIME type
+ */
+export declare function takeScreenshot(page: Page, options?: ScreenshotOptions): Promise<ScreenshotResult>;
+/**
+ * Generate a PDF of a page.
+ *
+ * @param page - Playwright Page instance
+ * @returns Buffer with PDF data
+ */
+export declare function generatePdf(page: Page): Promise<PdfResult>;

package/node_modules/@comis/skills/dist/browser/screenshots.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Screenshot capture and PDF generation.
+ *
+ * Takes page screenshots via Playwright with size normalization (resize
+ * images exceeding screenshotMaxSide), supports element-scoped capture,
+ * and generates PDFs.
+ *
+ * Ported from Comis browser/screenshot.ts +
+ * pw-tools-core.interactions.ts (takeScreenshotViaPlaywright, pdfViaPlaywright),
+ * simplified without sharp-based resize (uses Playwright's built-in capture).
+ *
+ * @module
+ */
+import { ensurePageState, refLocator } from "./playwright-session.js";
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Take a screenshot of a page, optionally scoped to an element.
+ *
+ * @param page - Playwright Page instance
+ * @param options - Screenshot options (fullPage, ref, element, type, quality)
+ * @returns Buffer with screenshot data and MIME type
+ */
+export async function takeScreenshot(page, options = {}) {
+    ensurePageState(page);
+    const type = options.type ?? "png";
+    const quality = type === "jpeg" ? (options.quality ?? 80) : undefined;
+    const mimeType = type === "jpeg" ? "image/jpeg" : "image/png";
+    // Element screenshot by ref
+    if (options.ref) {
+        if (options.fullPage) {
+            throw new Error("fullPage is not supported for element screenshots");
+        }
+        const locator = refLocator(page, options.ref);
+        const buffer = await locator.screenshot({ type, quality });
+        return { buffer, mimeType };
+    }
+    // Element screenshot by CSS selector
+    if (options.element) {
+        if (options.fullPage) {
+            throw new Error("fullPage is not supported for element screenshots");
+        }
+        const locator = page.locator(options.element).first();
+        const buffer = await locator.screenshot({ type, quality });
+        return { buffer, mimeType };
+    }
+    // Full-page or viewport screenshot
+    const buffer = await page.screenshot({
+        type,
+        quality,
+        fullPage: Boolean(options.fullPage),
+    });
+    return { buffer, mimeType };
+}
+/**
+ * Generate a PDF of a page.
+ *
+ * @param page - Playwright Page instance
+ * @returns Buffer with PDF data
+ */
+export async function generatePdf(page) {
+    ensurePageState(page);
+    const buffer = await page.pdf({ printBackground: true });
+    return { buffer, mimeType: "application/pdf" };
+}

package/node_modules/@comis/skills/dist/browser/smart-waits.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Smart wait conditions for browser automation.
+ *
+ * Dispatches to Playwright's native waitFor methods for multiple
+ * condition types: static delay, text visible/gone, CSS selector,
+ * URL pattern, load state, and JS function evaluation.
+ *
+ * Provides AI-driven actions with smart wait conditions.
+ *
+ * @module
+ */
+import type { Page } from "playwright-core";
+import { type Result } from "@comis/shared";
+/** Options for smartWait -- each field is an independent wait condition. */
+export interface WaitOptions {
+    /** Static delay in milliseconds (sleep). */
+    readonly timeMs?: number;
+    /** Wait for text to become visible on the page. */
+    readonly text?: string;
+    /** Wait for text to disappear from the page. */
+    readonly textGone?: string;
+    /** Wait for a CSS selector to be visible. */
+    readonly selector?: string;
+    /** Wait for the URL to contain this string. */
+    readonly url?: string;
+    /** Wait for a specific load state. */
+    readonly loadState?: "load" | "domcontentloaded" | "networkidle";
+    /** Wait for a JS expression to evaluate to a truthy value. */
+    readonly fn?: string;
+    /** Overall timeout per condition in milliseconds (default 20000, clamped 1000-60000). */
+    readonly timeoutMs?: number;
+}
+/**
+ * Execute one or more wait conditions sequentially on a Playwright Page.
+ *
+ * Each condition dispatches to the corresponding Playwright native
+ * waitFor method. If any condition fails (e.g., timeout), returns an
+ * err with a descriptive message identifying which condition failed.
+ *
+ * @param page - Playwright Page instance
+ * @param opts - Wait conditions to process
+ * @returns ok(undefined) when all conditions pass, err on failure
+ */
+export declare function smartWait(page: Page, opts: WaitOptions): Promise<Result<void, Error>>;

package/node_modules/@comis/skills/dist/browser/smart-waits.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Smart wait conditions for browser automation.
+ *
+ * Dispatches to Playwright's native waitFor methods for multiple
+ * condition types: static delay, text visible/gone, CSS selector,
+ * URL pattern, load state, and JS function evaluation.
+ *
+ * Provides AI-driven actions with smart wait conditions.
+ *
+ * @module
+ */
+import { ok, err } from "@comis/shared";
+// ── Implementation ───────────────────────────────────────────────────
+/**
+ * Execute one or more wait conditions sequentially on a Playwright Page.
+ *
+ * Each condition dispatches to the corresponding Playwright native
+ * waitFor method. If any condition fails (e.g., timeout), returns an
+ * err with a descriptive message identifying which condition failed.
+ *
+ * @param page - Playwright Page instance
+ * @param opts - Wait conditions to process
+ * @returns ok(undefined) when all conditions pass, err on failure
+ */
+export async function smartWait(page, opts) {
+    const timeoutMs = Math.max(1000, Math.min(60_000, opts.timeoutMs ?? 20_000));
+    try {
+        // 1. Static delay
+        if (opts.timeMs !== undefined) {
+            const clampedMs = Math.min(30_000, Math.max(0, opts.timeMs));
+            await page.waitForTimeout(clampedMs);
+        }
+        // 2. Wait for text visible
+        if (opts.text !== undefined) {
+            await page
+                .locator(`text=${opts.text}`)
+                .first()
+                .waitFor({ state: "visible", timeout: timeoutMs });
+        }
+        // 3. Wait for text gone
+        if (opts.textGone !== undefined) {
+            await page
+                .locator(`text=${opts.textGone}`)
+                .first()
+                .waitFor({ state: "hidden", timeout: timeoutMs });
+        }
+        // 4. Wait for CSS selector visible
+        if (opts.selector !== undefined) {
+            await page
+                .locator(opts.selector)
+                .first()
+                .waitFor({ state: "visible", timeout: timeoutMs });
+        }
+        // 5. Wait for URL pattern
+        if (opts.url !== undefined) {
+            await page.waitForURL(`**/*${opts.url}*`, { timeout: timeoutMs });
+        }
+        // 6. Wait for load state
+        if (opts.loadState !== undefined) {
+            await page.waitForLoadState(opts.loadState, { timeout: timeoutMs });
+        }
+        // 7. Wait for JS function
+        if (opts.fn !== undefined) {
+            await page.waitForFunction(opts.fn, undefined, { timeout: timeoutMs });
+        }
+        return ok(undefined);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        // Identify which condition likely failed from the error message
+        return err(new Error(`smartWait failed: ${msg}`));
+    }
+}

package/node_modules/@comis/skills/dist/browser/viewport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Viewport control for browser automation.
+ *
+ * Provides viewport resizing with safe bounds clamping and device
+ * presets for common screen sizes (mobile through 4K).
+ *
+ * Supports rich screenshots with viewport control.
+ *
+ * @module
+ */
+import type { Page } from "playwright-core";
+import { type Result } from "@comis/shared";
+/** Named device viewport preset. */
+export type DevicePreset = "mobile" | "tablet" | "desktop" | "fullhd" | "4k";
+/**
+ * Resize the browser viewport to specific dimensions.
+ *
+ * Dimensions are clamped to safe bounds:
+ * - Width: 1 to 7680 (8K horizontal)
+ * - Height: 1 to 4320 (8K vertical)
+ *
+ * @param page - Playwright Page instance
+ * @param width - Desired viewport width in pixels
+ * @param height - Desired viewport height in pixels
+ * @returns ok(undefined) on success, err on failure
+ */
+export declare function resizeViewport(page: Page, width: number, height: number): Promise<Result<void, Error>>;
+/**
+ * Set the viewport to a named device preset.
+ *
+ * Available presets:
+ * - mobile: 375x812
+ * - tablet: 768x1024
+ * - desktop: 1280x720
+ * - fullhd: 1920x1080
+ * - 4k: 3840x2160
+ *
+ * @param page - Playwright Page instance
+ * @param preset - Device preset name
+ * @returns ok with dimensions on success, err on failure
+ */
+export declare function setDevice(page: Page, preset: DevicePreset): Promise<Result<{
+    width: number;
+    height: number;
+}, Error>>;

package/node_modules/@comis/skills/dist/browser/viewport.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Viewport control for browser automation.
+ *
+ * Provides viewport resizing with safe bounds clamping and device
+ * presets for common screen sizes (mobile through 4K).
+ *
+ * Supports rich screenshots with viewport control.
+ *
+ * @module
+ */
+import { ok, err } from "@comis/shared";
+/** Viewport dimensions for each device preset. */
+const DEVICE_PRESETS = {
+    mobile: { width: 375, height: 812 },
+    tablet: { width: 768, height: 1024 },
+    desktop: { width: 1280, height: 720 },
+    fullhd: { width: 1920, height: 1080 },
+    "4k": { width: 3840, height: 2160 },
+};
+// ── Implementation ───────────────────────────────────────────────────
+/**
+ * Resize the browser viewport to specific dimensions.
+ *
+ * Dimensions are clamped to safe bounds:
+ * - Width: 1 to 7680 (8K horizontal)
+ * - Height: 1 to 4320 (8K vertical)
+ *
+ * @param page - Playwright Page instance
+ * @param width - Desired viewport width in pixels
+ * @param height - Desired viewport height in pixels
+ * @returns ok(undefined) on success, err on failure
+ */
+export async function resizeViewport(page, width, height) {
+    try {
+        const clampedWidth = Math.max(1, Math.min(7680, Math.round(width)));
+        const clampedHeight = Math.max(1, Math.min(4320, Math.round(height)));
+        await page.setViewportSize({
+            width: clampedWidth,
+            height: clampedHeight,
+        });
+        return ok(undefined);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return err(new Error(`resizeViewport failed: ${msg}`));
+    }
+}
+/**
+ * Set the viewport to a named device preset.
+ *
+ * Available presets:
+ * - mobile: 375x812
+ * - tablet: 768x1024
+ * - desktop: 1280x720
+ * - fullhd: 1920x1080
+ * - 4k: 3840x2160
+ *
+ * @param page - Playwright Page instance
+ * @param preset - Device preset name
+ * @returns ok with dimensions on success, err on failure
+ */
+export async function setDevice(page, preset) {
+    const dims = DEVICE_PRESETS[preset];
+    if (!dims) {
+        return err(new Error(`Unknown device preset: ${String(preset)}`));
+    }
+    const result = await resizeViewport(page, dims.width, dims.height);
+    if (!result.ok) {
+        return result;
+    }
+    return ok({ width: dims.width, height: dims.height });
+}