@agent-scope/render 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,925 @@
+import * as playwright from 'playwright';
+import { ComplexityClass, ComponentDescriptor } from '@agent-scope/manifest';
+import React from 'react';
+
+/**
+ * Types for the @agent-scope/render package.
+ *
+ * Shared types plus render-path-specific types for both:
+ *   - SatoriRenderer: Satori-based path for simple (flexbox-only) components
+ *   - BrowserPool: Playwright-based path for complex components
+ */
+/**
+ * The result produced by either render path (SatoriRenderer or BrowserPool).
+ */
+interface RenderResult {
+    /** PNG screenshot as a Buffer. */
+    screenshot: Buffer;
+    /** Pixel width of the rendered component. */
+    width: number;
+    /** Pixel height of the rendered component. */
+    height: number;
+    /** Wall-clock render duration in milliseconds. */
+    renderTimeMs: number;
+    /**
+     * Computed CSS property snapshots keyed by CSS selector or element path.
+     * E.g. `{ "root": { "display": "flex" } }` (Satori) or
+     *      `{ "[data-reactscope-root] > *": { "display": "flex" } }` (Browser)
+     */
+    computedStyles: Record<string, Record<string, string>>;
+    /** DOM tree and element count (BrowserPool only, when `captureDom` is true). */
+    dom?: {
+        tree: DOMNode;
+        elementCount: number;
+        boundingBox: BoundingBox;
+    };
+    /** Browser console output (BrowserPool only, when `captureConsole` is true). */
+    console?: {
+        errors: string[];
+        warnings: string[];
+        logs: string[];
+    };
+    /** Basic accessibility snapshot (BrowserPool only, when `captureA11y` is true). */
+    accessibility?: {
+        role: string;
+        name: string;
+        violations: string[];
+    };
+}
+/** Axis-aligned bounding box in CSS pixels. */
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A node in the extracted DOM tree. */
+interface DOMNode {
+    /** Tag name (lower-cased) or "#text" for text nodes. */
+    tag: string;
+    /** Element attributes. */
+    attrs: Record<string, string>;
+    /** Inner text content (for text/leaf nodes). */
+    text?: string;
+    /** Child nodes. */
+    children: DOMNode[];
+}
+/**
+ * Viewport configuration controlling the SVG viewBox / raster dimensions.
+ */
+interface ViewportOptions {
+    width: number;
+    height: number;
+}
+/** Available container layout presets. */
+type ContainerType = "centered" | "flex-row" | "flex-col" | "none";
+/**
+ * Wrapper container options applied around the rendered component.
+ */
+interface ContainerOptions {
+    type: ContainerType;
+    /** Padding in pixels (applied to all sides). */
+    padding: number;
+    /** Background colour (CSS colour string). */
+    background?: string;
+}
+/**
+ * Controls what is captured in the SatoriRenderer RenderResult.
+ */
+interface CaptureOptions {
+    /** Whether to capture a PNG screenshot. Default: true. */
+    screenshot: boolean;
+    /** Whether to extract computed styles. Default: true. */
+    styles: boolean;
+    /** Whether to record render timing. Default: true. */
+    timing: boolean;
+}
+/**
+ * Environment context for the Satori render.
+ */
+interface EnvironmentOptions {
+    /** Override viewport dimensions. */
+    viewport?: ViewportOptions;
+    /** Active theme name (passed to mock ThemeContext). */
+    theme?: string;
+    /** Locale string (e.g. "en-US"). */
+    locale?: string;
+}
+/**
+ * Full set of options for a SatoriRenderer render call.
+ */
+interface SatoriRenderOptions {
+    viewport?: ViewportOptions;
+    container?: Partial<ContainerOptions>;
+    capture?: Partial<CaptureOptions>;
+    environment?: EnvironmentOptions;
+}
+/** A loaded font entry suitable for passing to Satori. */
+interface FontEntry {
+    name: string;
+    data: ArrayBuffer;
+    weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    style: "normal" | "italic";
+}
+/**
+ * Construction-time configuration for SatoriRenderer.
+ */
+interface RendererConfig {
+    /**
+     * Path to a TTF/OTF/WOFF font file (NOT woff2 — opentype.js limitation).
+     * If omitted, bundled Inter woff is used via @fontsource/inter.
+     */
+    fontPath?: string;
+    /**
+     * Font family name to advertise. Defaults to "Inter".
+     */
+    fontFamily?: string;
+    /** Default viewport. */
+    defaultViewport?: ViewportOptions;
+}
+/** Per-render options controlling optional BrowserPool capture steps. */
+interface RenderOptions {
+    /** Capture and return a DOM tree snapshot. Default: false. */
+    captureDom?: boolean;
+    /** Capture computed styles for the root element. Default: true. */
+    captureStyles?: boolean;
+    /** Capture browser console output. Default: false. */
+    captureConsole?: boolean;
+    /** Capture basic accessibility role/name. Default: false. */
+    captureA11y?: boolean;
+    /** Viewport width for this render. Defaults to pool-level `viewportWidth`. */
+    viewportWidth?: number;
+    /** Viewport height for this render. Defaults to pool-level `viewportHeight`. */
+    viewportHeight?: number;
+    /** Timeout in milliseconds to wait for `window.__renderReady`. Default: 10_000. */
+    timeoutMs?: number;
+}
+/**
+ * Named pool size presets.
+ *
+ * | Preset       | browsers | pagesPerBrowser | max concurrency |
+ * |--------------|----------|-----------------|-----------------
+ * | local        | 1        | 5               | 5               |
+ * | ci-standard  | 3        | 15              | 45              |
+ * | ci-large     | 6        | 20              | 120             |
+ */
+type PoolPreset = "local" | "ci-standard" | "ci-large";
+/** Fine-grained pool sizing configuration. */
+interface PoolSizeConfig {
+    /** Number of browser instances to launch. */
+    browsers: number;
+    /** Number of page contexts per browser. */
+    pagesPerBrowser: number;
+}
+/** Full configuration for a `BrowserPool`. */
+interface BrowserPoolConfig {
+    /**
+     * Named size preset. Mutually exclusive with `size`.
+     * When both are omitted, defaults to `"local"`.
+     */
+    preset?: PoolPreset;
+    /**
+     * Custom size configuration. Overrides `preset` when provided.
+     */
+    size?: PoolSizeConfig;
+    /**
+     * Viewport width for all pages in the pool.
+     * @default 1440
+     */
+    viewportWidth?: number;
+    /**
+     * Viewport height for all pages in the pool.
+     * @default 900
+     */
+    viewportHeight?: number;
+    /**
+     * Maximum milliseconds to wait for an available page before
+     * `acquire()` rejects.
+     * @default 30_000
+     */
+    acquireTimeoutMs?: number;
+}
+/** Internal representation of a single page slot in the pool. */
+interface PageSlot {
+    /** Playwright page instance. */
+    page: playwright.Page;
+    /** Whether this slot is currently checked out. */
+    inUse: boolean;
+    /** Slot index (for debugging). */
+    index: number;
+}
+
+/**
+ * BrowserPool — Playwright-based browser pool for complex component rendering.
+ *
+ * ## Design
+ *
+ * The pool manages N browser instances, each owning M page contexts.  Pages are
+ * pre-loaded ONCE with a skeleton HTML that includes:
+ *   - A full React provider tree
+ *   - CSS / font links
+ *   - A component registry
+ *
+ * Components are swapped in via `window.__renderComponent(name, props)` — no
+ * page navigation between renders.  This "inject-don't-navigate" pattern keeps
+ * pages warm and avoids expensive browser startup on every render.
+ *
+ * ## Concurrency
+ *
+ * `acquire()` checks out a free `PageSlot`.  When all slots are busy, callers
+ * queue and are resumed FIFO once a slot becomes available.
+ * `release(slot)` returns a slot to the pool and wakes the next waiter.
+ *
+ * ## Shutdown
+ *
+ * `close()` drains all in-flight renders (waits for in-use slots) then closes
+ * every browser gracefully.
+ */
+
+/**
+ * Manages a pool of Playwright browser instances and page contexts for
+ * rendering complex React components.
+ */
+declare class BrowserPool {
+    private readonly config;
+    private readonly sizeConfig;
+    private browsers;
+    private slots;
+    private waiters;
+    private closed;
+    private initialized;
+    constructor(config?: BrowserPoolConfig);
+    /**
+     * Launch all browser instances and pre-load every page with the skeleton HTML.
+     * Must be called before `render()`.
+     */
+    init(): Promise<void>;
+    /**
+     * Acquire a free page slot.  Blocks until one is available or
+     * `acquireTimeoutMs` is exceeded.
+     */
+    acquire(): Promise<PageSlot>;
+    /**
+     * Return a page slot to the pool.  Wakes the next queued waiter, if any.
+     */
+    release(slot: PageSlot): void;
+    /**
+     * Render a component by name with the given props and return a `RenderResult`.
+     *
+     * The inject-don't-navigate pattern is used:
+     *  1. Acquire a warm page slot.
+     *  2. Call `window.__renderComponent(name, props)` — no navigation.
+     *  3. Wait for `window.__renderReady`.
+     *  4. Clip screenshot to the component bounding box.
+     *  5. Optionally capture DOM, styles, console output, and a11y info.
+     *  6. Release the slot.
+     */
+    render(componentName: string, props?: Record<string, unknown>, options?: RenderOptions): Promise<RenderResult>;
+    /**
+     * Gracefully shut down the pool.
+     *
+     * Waits for all in-use slots to be released, then closes every browser.
+     * Subsequent `acquire()` or `render()` calls will throw.
+     */
+    close(): Promise<void>;
+    /** Total number of page slots in the pool. */
+    get totalSlots(): number;
+    /** Number of currently available (free) slots. */
+    get freeSlots(): number;
+    /** Number of currently in-use slots. */
+    get activeSlots(): number;
+    /** Number of callers waiting for a free slot. */
+    get queueDepth(): number;
+    /** Whether the pool has been initialised. */
+    get isInitialized(): boolean;
+    /** Whether the pool is closed. */
+    get isClosed(): boolean;
+}
+
+/**
+ * Composition Contexts — built-in context types for use as RenderMatrix axes.
+ *
+ * Each context describes a layout environment in which a component is rendered.
+ * Pass an array of `CompositionContext` values as a matrix axis to test how a
+ * component behaves across different parent layout contexts.
+ */
+/**
+ * All built-in composition context identifiers.
+ *
+ * | ID              | Description                                                |
+ * |-----------------|------------------------------------------------------------|
+ * | centered        | Component centered inside the viewport                     |
+ * | flex-row        | Component inside a flex row with sibling placeholders      |
+ * | flex-col        | Component inside a flex column                             |
+ * | grid            | Component inside a CSS grid cell                          |
+ * | sidebar         | Narrow sidebar layout (240 px wide)                       |
+ * | scroll          | Component inside a scrollable container                    |
+ * | full-width      | Component stretches to full viewport width                 |
+ * | constrained     | Component inside a max-width centered container            |
+ * | rtl             | Right-to-left text direction (dir="rtl")                   |
+ * | nested-flex     | Deeply nested flex containers (3 levels)                   |
+ */
+type CompositionContextId = "centered" | "flex-row" | "flex-col" | "grid" | "sidebar" | "scroll" | "full-width" | "constrained" | "rtl" | "nested-flex";
+/**
+ * Describes a composition context: its ID, human-readable label,
+ * and the CSS properties to apply to the parent wrapper element.
+ */
+interface CompositionContext {
+    /** Stable identifier used as an axis value in RenderMatrix. */
+    id: CompositionContextId;
+    /** Short human-readable label (used as axis label in sprite sheets). */
+    label: string;
+    /** CSS properties applied to the wrapping container. */
+    containerStyle: Record<string, string>;
+    /** Optional HTML attributes applied to the wrapping container. */
+    containerAttrs?: Record<string, string>;
+    /** Human-readable description of what this context tests. */
+    description: string;
+}
+/**
+ * All ten built-in composition contexts.
+ */
+declare const COMPOSITION_CONTEXTS: Record<CompositionContextId, CompositionContext>;
+/** All ten built-in contexts as an ordered array. */
+declare const ALL_CONTEXTS: CompositionContext[];
+/** All context IDs. */
+declare const ALL_CONTEXT_IDS: CompositionContextId[];
+/**
+ * Retrieve a context descriptor by ID.
+ *
+ * @throws if the ID is not recognised.
+ */
+declare function getContext(id: CompositionContextId): CompositionContext;
+/**
+ * Retrieve multiple contexts by ID.
+ */
+declare function getContexts(ids: CompositionContextId[]): CompositionContext[];
+/**
+ * Returns a `MatrixAxis`-compatible object for use directly in `RenderMatrix`.
+ *
+ * ```ts
+ * const matrix = new RenderMatrix(renderer, [
+ *   contextAxis(["centered", "flex-row", "rtl"]),
+ *   { name: "variant", values: ["primary", "secondary"] },
+ * ]);
+ * ```
+ */
+declare function contextAxis(ids?: CompositionContextId[]): {
+    name: string;
+    values: CompositionContext[];
+};
+
+/**
+ * @agent-scope/render — Structured error handling for crashed renders.
+ *
+ * When a component crashes during render, this module captures rich
+ * diagnostic context instead of letting the error propagate and crash
+ * the entire batch.
+ *
+ * Usage:
+ *   import { safeRender, RenderError } from "@agent-scope/render";
+ *
+ *   const outcome = await safeRender(() => renderer.renderCell(props), {
+ *     props,
+ *     sourceLocation: { file: "Button.tsx", line: 12, column: 0 },
+ *   });
+ *
+ *   if (outcome.crashed) {
+ *     console.error(outcome.error.message);
+ *     console.error("Hints:", outcome.error.heuristicFlags);
+ *   } else {
+ *     console.log("Screenshot size:", outcome.result.screenshot.length);
+ *   }
+ */
+
+/**
+ * Automated diagnosis hints emitted when a render crashes.
+ *
+ * Each flag is a short SCREAMING_SNAKE_CASE identifier that encodes a
+ * likely root cause.  Callers can use these to surface actionable messages
+ * to the user without needing to parse raw error messages.
+ */
+type HeuristicFlag = "MISSING_PROVIDER" | "UNDEFINED_PROP" | "TYPE_MISMATCH" | "NETWORK_REQUIRED" | "ASYNC_NOT_SUSPENDED" | "HOOK_CALL_VIOLATION" | "ELEMENT_TYPE_INVALID" | "HYDRATION_MISMATCH" | "CIRCULAR_DEPENDENCY" | "UNKNOWN_ERROR";
+/**
+ * The file/line/column origin of a component as recorded in the manifest.
+ */
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * All structured fields carried by a `RenderError`.
+ * Consumers can access these directly on the error instance.
+ */
+interface RenderErrorFields {
+    /** The React component stack trace (if available). */
+    componentStack: string;
+    /** Source location from the manifest. */
+    sourceLocation: SourceLocation;
+    /** The prop values that were passed to the component when it crashed. */
+    propsAtCrash: Record<string, unknown>;
+    /** The error message (also available via `error.message`). */
+    errorMessage: string;
+    /** The error class name (e.g. "TypeError", "ReferenceError"). */
+    errorType: string;
+    /** Automated diagnosis hints. */
+    heuristicFlags: HeuristicFlag[];
+}
+/**
+ * Error thrown (or captured) when a component crashes during render.
+ *
+ * Extends the native `Error` class so it can be used with standard
+ * `instanceof` checks and `catch` clauses, while also carrying rich
+ * structured diagnostics.
+ */
+declare class RenderError extends Error implements RenderErrorFields {
+    readonly componentStack: string;
+    readonly sourceLocation: SourceLocation;
+    readonly propsAtCrash: Record<string, unknown>;
+    readonly errorMessage: string;
+    readonly errorType: string;
+    readonly heuristicFlags: HeuristicFlag[];
+    constructor(fields: RenderErrorFields);
+    /**
+     * Construct a `RenderError` from an arbitrary caught value.
+     *
+     * Extracts `componentStack` from React error boundaries when present,
+     * and runs heuristic analysis on the error message.
+     */
+    static from(caught: unknown, context?: {
+        props?: Record<string, unknown>;
+        sourceLocation?: SourceLocation;
+    }): RenderError;
+    /** Serialise to a plain object (useful for JSON output). */
+    toJSON(): RenderErrorFields & {
+        name: string;
+    };
+}
+/**
+ * Analyse an error message and component stack to produce a list of
+ * `HeuristicFlag` values that hint at likely root causes.
+ *
+ * Exported so that callers can run the analysis independently (e.g. in
+ * tests or custom error reporters).
+ */
+declare function detectHeuristicFlags(errorMessage: string, componentStack: string): HeuristicFlag[];
+/**
+ * A successful render outcome.
+ */
+interface SuccessRenderResult {
+    crashed: false;
+    result: RenderResult;
+}
+/**
+ * A crashed render outcome.  The `error` carries full diagnostic context.
+ */
+interface CrashedRenderResult {
+    crashed: true;
+    error: RenderError;
+    renderTimeMs: number;
+}
+/**
+ * The result of a `safeRender()` call: either success or a structured
+ * crash record.
+ */
+type RenderOutcome = SuccessRenderResult | CrashedRenderResult;
+/**
+ * Wraps a render function so that any thrown error is captured as a
+ * structured `CrashedRenderResult` instead of propagating.
+ *
+ * @param renderFn   — async function that produces a `RenderResult`.
+ * @param context    — optional metadata to attach to any crash record.
+ */
+declare function safeRender(renderFn: () => Promise<RenderResult>, context?: {
+    props?: Record<string, unknown>;
+    sourceLocation?: SourceLocation;
+}): Promise<RenderOutcome>;
+
+/**
+ * Font loading and caching for SatoriRenderer.
+ *
+ * Satori requires font data as ArrayBuffer and uses opentype.js internally,
+ * which supports TTF/OTF/WOFF but NOT WOFF2.
+ *
+ * This module:
+ *   - Loads a font from disk once and caches it in-process.
+ *   - Returns Satori-compatible FontEntry arrays.
+ *   - Falls back to the bundled Inter woff font (@fontsource/inter) when no
+ *     explicit path is provided.
+ */
+
+/**
+ * Load font data from the given path and return Satori-compatible entries.
+ * Results are cached by resolved path for the process lifetime.
+ *
+ * @param fontPath - Path to a TTF/OTF/WOFF font file (NOT woff2 — opentype.js
+ *                   doesn't support woff2). Pass `undefined` to use the bundled
+ *                   Inter woff font, or empty array if unavailable.
+ * @param fontFamily - Family name to advertise. Defaults to "Inter".
+ */
+declare function loadFont(fontPath: string | undefined, fontFamily?: string): Promise<FontEntry[]>;
+/**
+ * Clear the font cache. Useful in tests to ensure isolation.
+ */
+declare function clearFontCache(): void;
+/**
+ * Returns the number of distinct font paths currently cached.
+ */
+declare function fontCacheSize(): number;
+
+/**
+ * RenderMatrix — Cartesian product renderer for React component prop axes.
+ *
+ * Generates all combinations of axis values, renders each cell via either
+ * SatoriRenderer (simple components) or BrowserPool (complex components),
+ * and returns a structured grid of RenderResult objects with aggregate stats.
+ */
+
+/**
+ * A single axis in the render matrix.
+ * Each axis defines a dimension of the Cartesian product.
+ */
+interface MatrixAxis<T = unknown> {
+    /** Human-readable name for this axis (displayed as row/col label). */
+    name: string;
+    /** The values along this axis. */
+    values: T[];
+}
+/**
+ * Unified renderer interface that both SatoriRenderer and BrowserPool
+ * adapters implement. Consumers supply a `MatrixRenderer` to `RenderMatrix`.
+ */
+interface MatrixRenderer {
+    /**
+     * Render a single cell given the merged props for that cell.
+     *
+     * @param props - The combined prop snapshot for this matrix cell.
+     *               Keys are axis names; values are the axis value for this cell.
+     * @param complexityClass - Routing hint (passed through from the descriptor).
+     * @returns Resolved RenderResult.
+     */
+    renderCell(props: Record<string, unknown>, complexityClass: ComplexityClass): Promise<RenderResult>;
+}
+/**
+ * A single cell in the rendered matrix grid.
+ */
+interface MatrixCell {
+    /** The axis values that produced this cell (axis name → value). */
+    props: Record<string, unknown>;
+    /** The render result for this cell. */
+    result: RenderResult;
+    /** Flat index in the row-major grid. */
+    index: number;
+    /** Per-axis indices (parallel to axes array). */
+    axisIndices: number[];
+}
+/**
+ * Aggregate statistics over all cells in the matrix.
+ */
+interface MatrixStats {
+    /** Total number of cells rendered. */
+    totalCells: number;
+    /** Sum of all cell renderTimeMs values. */
+    totalRenderTimeMs: number;
+    /** Average renderTimeMs across all cells. */
+    avgRenderTimeMs: number;
+    /** Fastest individual cell render time. */
+    minRenderTimeMs: number;
+    /** Slowest individual cell render time. */
+    maxRenderTimeMs: number;
+    /** Total wall-clock time for the whole matrix render (ms). */
+    wallClockTimeMs: number;
+}
+/**
+ * The full result of a matrix render.
+ */
+interface MatrixResult {
+    /** Flat list of all rendered cells (row-major order). */
+    cells: MatrixCell[];
+    /** The axes used to generate this matrix. */
+    axes: MatrixAxis[];
+    /**
+     * 2-D axis label grid: `axisLabels[axisIndex][valueIndex]` → label string.
+     * For multi-value objects, we use JSON.stringify as a fallback label.
+     */
+    axisLabels: string[][];
+    /** Aggregate render statistics. */
+    stats: MatrixStats;
+    /** Number of rows in the conceptual grid (last axis cardinality). */
+    rows: number;
+    /** Number of columns in the conceptual grid (second-to-last axis cardinality, or 1). */
+    cols: number;
+}
+/**
+ * Generates the Cartesian product of an array of arrays.
+ *
+ * cartesianProduct([[1,2],[3,4]]) → [[1,3],[1,4],[2,3],[2,4]]
+ */
+declare function cartesianProduct<T>(axes: T[][]): T[][];
+/**
+ * Produce a human-readable label for an axis value.
+ * Primitives are stringified directly; objects/arrays use JSON.stringify.
+ */
+declare function labelForValue(value: unknown): string;
+/**
+ * Generates and renders a Cartesian product of prop axis values.
+ *
+ * Usage:
+ * ```ts
+ * const matrix = new RenderMatrix(renderer, [
+ *   { name: "variant", values: ["primary", "secondary"] },
+ *   { name: "size", values: ["sm", "md", "lg"] },
+ * ], { complexityClass: "simple" });
+ *
+ * const result = await matrix.render();
+ * // result.cells has 6 entries (2×3)
+ * ```
+ */
+declare class RenderMatrix {
+    private readonly renderer;
+    private readonly axes;
+    private readonly complexityClass;
+    /** Maximum number of cells to render in parallel. @default 8 */
+    private readonly concurrency;
+    constructor(renderer: MatrixRenderer, axes: MatrixAxis[], options?: {
+        complexityClass?: ComplexityClass;
+        /** Max parallel renders. Default 8. */
+        concurrency?: number;
+    });
+    /** Total number of cells (product of all axis cardinalities). */
+    get cellCount(): number;
+    /** Axis labels indexed [axisIndex][valueIndex]. */
+    get axisLabels(): string[][];
+    /**
+     * Render all cells of the matrix.
+     *
+     * Cells are dispatched with bounded parallelism (up to `concurrency` at once)
+     * and returned in row-major order (first axis iterates slowest).
+     */
+    render(): Promise<MatrixResult>;
+    private _renderWithConcurrency;
+    private _computeStats;
+}
+
+/**
+ * Mock provider helpers for SatoriRenderer.
+ *
+ * Satori renders pure React element trees to SVG — it does NOT execute hooks
+ * or context providers at runtime. The functions here produce wrapper JSX
+ * elements that supply minimal mock context values so that components that
+ * read context don't throw during the shallow JSX-to-SVG pass.
+ *
+ * Because Satori only cares about the *rendered JSX shape* (not hook side
+ * effects), we can safely supply stub contexts.
+ */
+
+/**
+ * Wrap a React element with mock providers for each requested context name.
+ *
+ * Unknown context names get a generic empty-object provider created on the
+ * fly (safe, avoids crashes for components that only call `useContext` to
+ * check if a value is defined).
+ */
+declare function wrapWithProviders(element: React.ReactElement, requiredContexts: string[], options?: {
+    theme?: string;
+    locale?: string;
+}): React.ReactElement;
+
+/**
+ * SatoriRenderer — pure Node.js render path for simple (flexbox-only) components.
+ *
+ * Pipeline:
+ *   React element → Satori SVG → @resvg/resvg-js PNG
+ *
+ * Only handles components with `complexityClass: "simple"` as classified by
+ * @agent-scope/manifest. Complex components (CSS grid, absolute positioning,
+ * animations) must be rendered via the Browser Pool path.
+ *
+ * Target performance: ~8 ms per render at 375×812 (mobile viewport).
+ */
+
+/**
+ * Satori-based renderer for simple (flexbox-only) React components.
+ *
+ * Usage:
+ * ```ts
+ * const renderer = new SatoriRenderer();
+ * const result = await renderer.render(
+ *   <Button variant="primary">Click me</Button>,
+ *   { viewport: { width: 375, height: 200 } },
+ * );
+ * ```
+ */
+declare class SatoriRenderer {
+    private readonly config;
+    private fontsPromise;
+    constructor(config?: RendererConfig);
+    /**
+     * Pre-load and cache the configured font. Calling this before `render()`
+     * ensures the first render isn't slowed by font I/O.
+     */
+    preloadFont(): Promise<void>;
+    private _getFonts;
+    /**
+     * Render a React element tree to PNG via Satori (SVG) → resvg-js (PNG).
+     *
+     * @param element   - The React element to render (pre-built, not a component class).
+     * @param options   - Viewport, container, capture, and environment overrides.
+     * @param descriptor - Optional ComponentDescriptor for provider wrapping.
+     *                    When provided, `requiredContexts` are used to inject
+     *                    mock providers around the element.
+     */
+    render(element: React.ReactElement, options?: SatoriRenderOptions, descriptor?: Pick<ComponentDescriptor, "requiredContexts">): Promise<RenderResult>;
+    /**
+     * Render at a specific viewport size. Shorthand for `render(el, { viewport })`.
+     */
+    renderAt(element: React.ReactElement, width: number, height: number, descriptor?: Pick<ComponentDescriptor, "requiredContexts">): Promise<RenderResult>;
+}
+
+/**
+ * SpriteSheetGenerator — composites a MatrixResult into a single PNG sprite sheet.
+ *
+ * Layout:
+ *   - Rows correspond to the last matrix axis values.
+ *   - Columns correspond to all remaining axis combinations.
+ *   - Axis labels are rendered on the top (column labels) and left (row labels) edges.
+ *   - Cell borders and padding separate each cell visually.
+ *
+ * Returns:
+ *   - A single PNG Buffer containing the full composite image.
+ *   - A `CellCoordinateMap` for programmatic access to individual cell positions.
+ */
+
+/**
+ * The pixel bounding box of a single cell within the sprite sheet.
+ */
+interface CellBounds {
+    /** Left edge in pixels (from sprite sheet origin). */
+    x: number;
+    /** Top edge in pixels (from sprite sheet origin). */
+    y: number;
+    /** Cell width in pixels (content only, excluding padding). */
+    width: number;
+    /** Cell height in pixels (content only, excluding padding). */
+    height: number;
+}
+/**
+ * Maps each cell's flat index to its pixel position in the sprite sheet.
+ * Access via `coordinates[cellIndex]`.
+ */
+type CellCoordinateMap = CellBounds[];
+/**
+ * The output of `SpriteSheetGenerator.generate()`.
+ */
+interface SpriteSheetResult {
+    /** Full composite PNG as a Buffer. */
+    png: Buffer;
+    /** Per-cell bounding boxes within the composite image. */
+    coordinates: CellCoordinateMap;
+    /** Total sprite sheet width in pixels. */
+    width: number;
+    /** Total sprite sheet height in pixels. */
+    height: number;
+}
+/**
+ * Configuration for `SpriteSheetGenerator`.
+ */
+interface SpriteSheetOptions {
+    /** Padding in pixels around each cell. @default 8 */
+    cellPadding?: number;
+    /** Border thickness in pixels between cells. @default 1 */
+    borderWidth?: number;
+    /** Background colour as a CSS hex string. @default "#f5f5f5" */
+    background?: string;
+    /** Border colour as a CSS hex string. @default "#cccccc" */
+    borderColor?: string;
+    /** Height in pixels reserved for column axis labels at the top. @default 32 */
+    labelHeight?: number;
+    /** Width in pixels reserved for row axis labels on the left. @default 80 */
+    labelWidth?: number;
+    /** DPI for axis label text rendering. @default 72 */
+    labelDpi?: number;
+    /** Label text colour (hex). @default "#333333" */
+    labelColor?: string;
+    /** Label area background colour (hex). @default "#e8e8e8" */
+    labelBackground?: string;
+}
+/**
+ * Composites a `MatrixResult` into a single PNG sprite sheet.
+ *
+ * Usage:
+ * ```ts
+ * const gen = new SpriteSheetGenerator({ cellPadding: 12 });
+ * const { png, coordinates } = await gen.generate(matrixResult);
+ * ```
+ */
+declare class SpriteSheetGenerator {
+    private readonly opts;
+    constructor(options?: SpriteSheetOptions);
+    /**
+     * Generate a sprite sheet from a `MatrixResult`.
+     *
+     * Grid layout:
+     *   - Rows = last axis cardinality
+     *   - Cols = product of all other axis cardinalities (or 1 if single axis)
+     *
+     * @param matrixResult - The result of `RenderMatrix.render()`.
+     */
+    generate(matrixResult: MatrixResult): Promise<SpriteSheetResult>;
+}
+
+/**
+ * Content Stress Presets — edge-case prop values for use as RenderMatrix axes.
+ *
+ * Each preset category provides an array of values (of a specific type) that
+ * exercise boundary and edge-case conditions:  empty input, overflow text,
+ * bidirectional text, numeric extremes, empty/huge lists, broken image URLs, etc.
+ *
+ * Usage:
+ * ```ts
+ * import { stressAxis } from "@agent-scope/render";
+ *
+ * const matrix = new RenderMatrix(renderer, [
+ *   stressAxis("text.short"),
+ *   { name: "disabled", values: [false, true] },
+ * ]);
+ * ```
+ */
+/**
+ * All built-in stress preset categories.
+ *
+ * | ID              | Description                                              |
+ * |-----------------|----------------------------------------------------------|
+ * | text.short      | Empty string, single char, short word                    |
+ * | text.long       | 200+ character strings, repeated words, lorem ipsum      |
+ * | text.unicode    | CJK ideographs, diacritics, emoji, zero-width chars      |
+ * | text.rtl        | Arabic and Hebrew strings                                |
+ * | number.edge     | 0, -1, NaN, Infinity, -Infinity, 999999, MAX_SAFE_INT    |
+ * | list.count      | Lists with 0, 1, 3, 10, 100, 1000 items                  |
+ * | image.states    | null URL, broken URL, 1×1 data URI, very large image URL  |
+ */
+type StressCategoryId = "text.short" | "text.long" | "text.unicode" | "text.rtl" | "number.edge" | "list.count" | "image.states";
+/**
+ * A named set of stress values for a specific data category.
+ */
+interface StressPreset<T = unknown> {
+    /** Stable category identifier. */
+    id: StressCategoryId;
+    /** Short human-readable label (used as axis name). */
+    label: string;
+    /** Human-readable description of what this preset exercises. */
+    description: string;
+    /** The stress values. */
+    values: T[];
+    /** Labels parallel to `values` for display in sprite sheets. */
+    valueLabels: string[];
+}
+/**
+ * Retrieve a stress preset by category ID.
+ *
+ * @throws if the ID is not recognised.
+ */
+declare function getStressPreset(id: StressCategoryId): StressPreset;
+/**
+ * Retrieve multiple stress presets.
+ */
+declare function getStressPresets(ids: StressCategoryId[]): StressPreset[];
+/** All built-in stress presets as an ordered array. */
+declare const ALL_STRESS_PRESETS: StressPreset[];
+/** All stress category IDs. */
+declare const ALL_STRESS_IDS: StressCategoryId[];
+/**
+ * Returns a `MatrixAxis`-compatible object for direct use in `RenderMatrix`.
+ *
+ * ```ts
+ * const matrix = new RenderMatrix(renderer, [
+ *   stressAxis("text.short"),
+ *   { name: "disabled", values: [false, true] },
+ * ]);
+ * ```
+ */
+declare function stressAxis(id: StressCategoryId): {
+    name: string;
+    values: unknown[];
+};
+
+/**
+ * Inline-style extraction utilities for SatoriRenderer.
+ *
+ * Satori accepts React elements with inline `style` props. This module walks
+ * a React element tree and extracts those styles into the ComputedStyles map
+ * that is returned as part of RenderResult.
+ */
+
+/**
+ * Walk a React element tree and collect all inline `style` objects.
+ *
+ * The key in the returned map is a dot-delimited path describing the element's
+ * position in the tree, e.g. "root", "root.0", "root.0.1".
+ *
+ * Only elements with a non-empty `style` prop are included.
+ */
+declare function extractInlineStyles(element: React.ReactNode, path?: string): Record<string, Record<string, string>>;
+
+export { ALL_CONTEXTS, ALL_CONTEXT_IDS, ALL_STRESS_IDS, ALL_STRESS_PRESETS, type BoundingBox, BrowserPool, type BrowserPoolConfig, COMPOSITION_CONTEXTS, type CaptureOptions, type CellBounds, type CellCoordinateMap, type CompositionContext, type CompositionContextId, type ContainerOptions, type ContainerType, type CrashedRenderResult, type DOMNode, type EnvironmentOptions, type FontEntry, type HeuristicFlag, type MatrixAxis, type MatrixCell, type MatrixRenderer, type MatrixResult, type MatrixStats, type PageSlot, type PoolPreset, type PoolSizeConfig, RenderError, type RenderErrorFields, RenderMatrix, type RenderOptions, type RenderOutcome, type RenderResult, type RendererConfig, type SatoriRenderOptions, SatoriRenderer, type SourceLocation, SpriteSheetGenerator, type SpriteSheetOptions, type SpriteSheetResult, type StressCategoryId, type StressPreset, type SuccessRenderResult, type ViewportOptions, cartesianProduct, clearFontCache, contextAxis, detectHeuristicFlags, extractInlineStyles, fontCacheSize, getContext, getContexts, getStressPreset, getStressPresets, labelForValue, loadFont, safeRender, stressAxis, wrapWithProviders };