@spinajs/templates-puppeteer 2.0.481 → 2.0.482

package/README.md

@@ -7,3 +7,38 @@ Base Puppeteer renderer for SpineJS templates. This package provides shared logi
 ``bash
 npm install @spinajs/templates-puppeteer
 ``
+
+## Render progress
+
+PDF/image renders can take a long time when the HTML pulls in many external
+resources (images, fonts, stylesheets). Pass an `onProgress` callback to observe
+what the render is doing - especially while resources are loading.
+
+Progress is reported through discrete phases (`starting` → `preparing` →
+`loading` → `rendering` → `done`, or `failed`) with a best-effort `percent`,
+live resource counters, and elapsed time. The callback is fire-and-forget: it is
+never awaited and its errors are swallowed, so it can neither slow nor break a
+render. Emissions are throttled, with a heartbeat during the long phases so the
+value keeps moving even when a single resource is slow.
+
+``ts
+await pdfRenderer.renderToFile('invoice.pdf', model, 'out/invoice.pdf', 'en', {
+  onProgress: (p) => {
+    // p: { phase, percent, resourcesLoaded, resourcesPending, resourcesFailed, elapsedMs, filePath, message }
+    console.log(`${p.phase} ${p.percent}% - ${p.message}`);
+  },
+});
+``
+
+The same option works on `renderHtmlToFile(html, filePath, { onProgress })` and
+flows through the `Templates` facade (`render` / `renderToFile` / `compile` /
+`compileToFile`). The CLI commands `render-pdf` / `render-image` already render a
+live progress line via the shared `cliProgressReporter()`.
+
+Reporting progress from a queue job is a one-liner - forward the percentage:
+
+``ts
+await templates.renderToFile('report.pdf', model, out, lang, {
+  onProgress: (p) => void jobProgress(p.percent),
+});
+``

package/lib/cjs/asset-server.d.ts

@@ -0,0 +1,32 @@
+import * as http from 'http';
+import { Log } from '@spinajs/log';
+/**
+ * A short-lived local static HTTP server used so headless Chromium can load
+ * relative asset URLs (images, css, fonts) - it refuses local files over the
+ * file:// protocol. Bound to loopback so the served directory is never
+ * network-exposed. One server is started per render and closed afterwards.
+ */
+export declare class LocalAssetServer {
+    private readonly log;
+    private readonly portRange;
+    /**
+     * @param log - logger for lifecycle traces
+     * @param portRange - supplies the optional [min, max] port range; when absent
+     *   an OS-assigned port (0) is used, which cannot collide.
+     */
+    constructor(log: Log, portRange: () => number[] | undefined);
+    /**
+     * Start a server for `basePath`. With an OS-assigned port a single attempt
+     * suffices; with a configured range a random pick can collide, so retry on
+     * EADDRINUSE with a different port.
+     */
+    serve(basePath: string): Promise<http.Server>;
+    /** Close a server, forcing connections closed if a graceful close times out. */
+    close(server: http.Server): Promise<void>;
+    /**
+     * Single attempt to start the static server on the given port (0 = OS-assigned).
+     * Bound to loopback so the served directory is not network-exposed.
+     */
+    private listenOnce;
+}
+//# sourceMappingURL=asset-server.d.ts.map

package/lib/cjs/asset-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-server.d.ts","sourceRoot":"","sources":["../../src/asset-server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAI7B,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AASnC;;;;;GAKG;AACH,qBAAa,gBAAgB;IAMf,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAO,OAAO,CAAC,QAAQ,CAAC,SAAS;IALjE;;;;OAIG;gBAC0B,GAAG,EAAE,GAAG,EAAmB,SAAS,EAAE,MAAM,MAAM,EAAE,GAAG,SAAS;IAE7F;;;;OAIG;IACU,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IA2B1D,gFAAgF;IACnE,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BtD;;;OAGG;IACH,OAAO,CAAC,UAAU;CAgCnB"}

package/lib/cjs/asset-server.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalAssetServer = void 0;
+const express_1 = __importDefault(require("express"));
+const cors_1 = __importDefault(require("cors"));
+const lodash_1 = __importDefault(require("lodash"));
+/** How long to wait for the local static server to start before giving up (ms). */
+const SERVER_STARTUP_TIMEOUT_MS = 10000;
+/** How long to wait for the local static server to close before forcing it (ms). */
+const SERVER_CLOSE_TIMEOUT_MS = 5000;
+/** Attempts to find a free port when a range is configured (a random pick can collide). */
+const MAX_PORT_ATTEMPTS = 10;
+/**
+ * A short-lived local static HTTP server used so headless Chromium can load
+ * relative asset URLs (images, css, fonts) - it refuses local files over the
+ * file:// protocol. Bound to loopback so the served directory is never
+ * network-exposed. One server is started per render and closed afterwards.
+ */
+class LocalAssetServer {
+    /**
+     * @param log - logger for lifecycle traces
+     * @param portRange - supplies the optional [min, max] port range; when absent
+     *   an OS-assigned port (0) is used, which cannot collide.
+     */
+    constructor(log, portRange) {
+        this.log = log;
+        this.portRange = portRange;
+    }
+    /**
+     * Start a server for `basePath`. With an OS-assigned port a single attempt
+     * suffices; with a configured range a random pick can collide, so retry on
+     * EADDRINUSE with a different port.
+     */
+    async serve(basePath) {
+        const range = this.portRange();
+        const hasRange = !!range && range.length > 0;
+        const maxAttempts = hasRange ? MAX_PORT_ATTEMPTS : 1;
+        let lastErr;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const port = hasRange ? lodash_1.default.random(range[0], range[1]) : 0;
+            try {
+                return await this.listenOnce(basePath, port);
+            }
+            catch (err) {
+                lastErr = err;
+                if (err?.code === 'EADDRINUSE' && hasRange) {
+                    this.log.trace(`Puppeteer asset server port ${port} in use, retrying (${attempt + 1}/${maxAttempts})`);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        this.log.error(lastErr, `Puppeteer asset server cannot start - no free port in range after ${maxAttempts} attempts`);
+        throw lastErr;
+    }
+    /** Close a server, forcing connections closed if a graceful close times out. */
+    async close(server) {
+        try {
+            await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    reject(new Error('Server close timeout'));
+                }, SERVER_CLOSE_TIMEOUT_MS);
+                server.close((err) => {
+                    clearTimeout(timeout);
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        }
+        catch (err) {
+            this.log.warn(`Error closing server: ${err.message}`);
+            // Force close connections if available
+            try {
+                if ('closeAllConnections' in server) {
+                    server.closeAllConnections();
+                }
+            }
+            catch (forceErr) {
+                this.log.error(`Error force closing server connections: ${forceErr.message}`);
+            }
+        }
+    }
+    /**
+     * Single attempt to start the static server on the given port (0 = OS-assigned).
+     * Bound to loopback so the served directory is not network-exposed.
+     */
+    listenOnce(basePath, port) {
+        const log = this.log;
+        const app = (0, express_1.default)();
+        app.use((0, cors_1.default)());
+        app.use(express_1.default.static(basePath));
+        return new Promise((resolve, reject) => {
+            const server = app
+                .listen(port, '127.0.0.1')
+                .on('listening', function () {
+                log.trace(`Puppeteer asset server started on port ${this.address().port}`);
+                log.trace(`Puppeteer static file dir at ${basePath}`);
+                resolve(this);
+            })
+                .on('error', (err) => {
+                // Clean up the failed server, then reject so the caller can retry.
+                if (server) {
+                    server.close(() => reject(err));
+                }
+                else {
+                    reject(err);
+                }
+            });
+            // Set a timeout for server startup
+            setTimeout(() => {
+                if (!server.listening) {
+                    server.close();
+                    reject(new Error('Server startup timeout'));
+                }
+            }, SERVER_STARTUP_TIMEOUT_MS);
+        });
+    }
+}
+exports.LocalAssetServer = LocalAssetServer;
+//# sourceMappingURL=asset-server.js.map

package/lib/cjs/asset-server.js.map

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

package/lib/cjs/browser-pool.d.ts

@@ -0,0 +1,31 @@
+import { Browser, LaunchOptions } from 'puppeteer';
+import { Log } from '@spinajs/log';
+/**
+ * Lazily launches and pools a single Chromium browser, reused across renders and
+ * relaunched if it crashes/disconnects. Concurrent first-callers share one launch.
+ * The browser is closed only on {@link dispose}.
+ */
+export declare class BrowserPool {
+    private readonly log;
+    private readonly launchOptions;
+    private pooled;
+    private launchPromise;
+    /**
+     * @param log - logger for lifecycle warnings
+     * @param launchOptions - supplies puppeteer launch options at acquire time
+     *   (resolved lazily so DI-injected config is available).
+     */
+    constructor(log: Log, launchOptions: () => LaunchOptions);
+    /** The currently pooled browser, or null when none is live. */
+    get browser(): Browser | null;
+    /**
+     * Return the pooled browser, launching it on first use and relaunching if it
+     * has crashed/disconnected. Concurrent callers share a single launch.
+     */
+    acquire(): Promise<Browser>;
+    /** Close and drop the pooled browser. Best-effort: force-kills if a graceful close fails. */
+    dispose(): Promise<void>;
+    private safeClose;
+    private forceClose;
+}
+//# sourceMappingURL=browser-pool.d.ts.map

package/lib/cjs/browser-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.d.ts","sourceRoot":"","sources":["../../src/browser-pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAwB,aAAa,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC;;;;GAIG;AACH,qBAAa,WAAW;IASV,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAO,OAAO,CAAC,QAAQ,CAAC,aAAa;IARrE,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,aAAa,CAAiC;IAEtD;;;;OAIG;gBAC0B,GAAG,EAAE,GAAG,EAAmB,aAAa,EAAE,MAAM,aAAa;IAE1F,+DAA+D;IAC/D,IAAW,OAAO,IAAI,OAAO,GAAG,IAAI,CAEnC;IAED;;;OAGG;IACU,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAmBxC,6FAA6F;IAChF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAUvB,SAAS;IAiBvB,OAAO,CAAC,UAAU;CAOnB"}

package/lib/cjs/browser-pool.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserPool = void 0;
+const puppeteer_1 = __importDefault(require("puppeteer"));
+/**
+ * Lazily launches and pools a single Chromium browser, reused across renders and
+ * relaunched if it crashes/disconnects. Concurrent first-callers share one launch.
+ * The browser is closed only on {@link dispose}.
+ */
+class BrowserPool {
+    /**
+     * @param log - logger for lifecycle warnings
+     * @param launchOptions - supplies puppeteer launch options at acquire time
+     *   (resolved lazily so DI-injected config is available).
+     */
+    constructor(log, launchOptions) {
+        this.log = log;
+        this.launchOptions = launchOptions;
+        this.pooled = null;
+        this.launchPromise = null;
+    }
+    /** The currently pooled browser, or null when none is live. */
+    get browser() {
+        return this.pooled;
+    }
+    /**
+     * Return the pooled browser, launching it on first use and relaunching if it
+     * has crashed/disconnected. Concurrent callers share a single launch.
+     */
+    async acquire() {
+        if (this.pooled?.connected) {
+            return this.pooled;
+        }
+        // drop a disconnected/crashed browser so we relaunch a fresh one
+        this.pooled = null;
+        if (!this.launchPromise) {
+            this.launchPromise = puppeteer_1.default
+                .launch(this.launchOptions())
+                .then((b) => (this.pooled = b))
+                // reset so a failed launch is retried on the next call
+                .finally(() => (this.launchPromise = null));
+        }
+        return this.launchPromise;
+    }
+    /** Close and drop the pooled browser. Best-effort: force-kills if a graceful close fails. */
+    async dispose() {
+        if (!this.pooled) {
+            return;
+        }
+        const browser = this.pooled;
+        this.pooled = null;
+        await this.safeClose(browser);
+    }
+    async safeClose(browser) {
+        try {
+            // close all pages first, then the browser itself
+            const pages = await browser.pages();
+            await Promise.allSettled(pages.map((page) => page.close()));
+            await browser.close();
+        }
+        catch (err) {
+            this.log.warn(`Error during normal browser cleanup: ${err.message}`);
+            try {
+                this.forceClose(browser);
+            }
+            catch (killErr) {
+                this.log.error(`Failed to force kill browser: ${killErr.message}`);
+            }
+        }
+    }
+    forceClose(browser) {
+        const proc = browser.process();
+        if (proc) {
+            proc.kill('SIGKILL');
+            this.log.warn('Browser process force killed');
+        }
+    }
+}
+exports.BrowserPool = BrowserPool;
+//# sourceMappingURL=browser-pool.js.map

package/lib/cjs/browser-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.js","sourceRoot":"","sources":["../../src/browser-pool.ts"],"names":[],"mappings":";;;;;;AAAA,0DAAyE;AAGzE;;;;GAIG;AACH,MAAa,WAAW;IAItB;;;;OAIG;IACH,YAA6B,GAAQ,EAAmB,aAAkC;QAA7D,QAAG,GAAH,GAAG,CAAK;QAAmB,kBAAa,GAAb,aAAa,CAAqB;QARlF,WAAM,GAAmB,IAAI,CAAC;QAC9B,kBAAa,GAA4B,IAAI,CAAC;IAOuC,CAAC;IAE9F,+DAA+D;IAC/D,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,OAAO;QAClB,IAAI,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC,MAAM,CAAC;QACrB,CAAC;QAED,iEAAiE;QACjE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAEnB,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,IAAI,CAAC,aAAa,GAAG,mBAAS;iBAC3B,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;iBAC5B,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBAC/B,uDAAuD;iBACtD,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,6FAA6F;IACtF,KAAK,CAAC,OAAO;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,OAAgB;QACtC,IAAI,CAAC;YACH,iDAAiD;YACjD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;YACpC,MAAM,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC5D,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,wCAAwC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAErE,IAAI,CAAC;gBACH,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,OAAO,EAAE,CAAC;gBACjB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,iCAAiC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,OAAgB;QACjC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACrB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;CACF;AA1ED,kCA0EC"}

package/lib/cjs/index.d.ts

@@ -1,8 +1,13 @@
-import { Browser, Page, LaunchOptions } from 'puppeteer';
-import { TemplateRenderer, Templates } from '@spinajs/templates';
+import { Page, LaunchOptions } from 'puppeteer';
+import { TemplateRenderer, Templates, IRenderOptions, RenderProgressCallback } from '@spinajs/templates';
+import { IInstanceCheck } from '@spinajs/di';
 import { Log } from '@spinajs/log';
-import * as http from 'http';
 import '@spinajs/templates-pug';
+import { LocalAssetServer } from './asset-server.js';
+import { BrowserPool } from './browser-pool.js';
+export * from './progress.js';
+export * from './asset-server.js';
+export * from './browser-pool.js';
 export interface IPuppeteerRendererOptions {
     static: {
         portRange: number[];
@@ -22,39 +27,99 @@ export interface IPuppeteerRendererOptions {
      */
     debug?: {
         /**
-         * If true, browser will remain open after rendering for inspection
-         * Use it with headless: false in args to see the browser window ( puppetter.launch args )
+         * Controls whether the browser is closed after rendering.
+         * Defaults to closing. Set to `false` to keep the browser open after rendering
+         * for inspection ( use with headless: false in args to see the browser window ).
          */
         close?: boolean;
     };
 }
-export declare abstract class PuppeteerRenderer extends TemplateRenderer {
+export declare abstract class PuppeteerRenderer extends TemplateRenderer implements IInstanceCheck {
     protected abstract Options: IPuppeteerRendererOptions;
+    /**
+     * Per-instance options that give this renderer its identity for the DI
+     * @PerInstanceCheck pooling (see subclasses). Renderers that are not pooled
+     * per-instance inherit the `undefined` default.
+     */
+    protected get instanceOptions(): unknown;
+    /**
+     * DI @PerInstanceCheck hook: an existing instance is reused only when it was
+     * created with the same options.
+     */
+    __checkInstance__(creationOptions: any): boolean;
     protected Log: Log;
     protected TemplatingService: Templates;
-    renderToFile(template: string, model: any, filePath: string, language?: string): Promise<void>;
+    private _assetServer?;
+    private _browserPool?;
+    /** Local static server used so Chromium can load relative asset URLs. Lazily created. */
+    protected get assetServer(): LocalAssetServer;
     /**
-     * Abstract method to perform specific rendering (PDF or image)
+     * Pooled browser, launched lazily and reused across renders, closed on dispose().
+     * One pool per options-set (see @PerInstanceCheck on subclasses). Lazily created.
      */
-    protected abstract performRender(page: Page, filePath: string): Promise<void>;
-    render(_templateName: string, _model: unknown, _language?: string): Promise<string>;
-    protected compile(_path: string): Promise<void>;
-    protected runLocalServer(basePath: string): Promise<http.Server>;
+    protected get browserPool(): BrowserPool;
+    private buildLaunchOptions;
+    renderToFile(template: string, model: any, filePath: string, language?: string, options?: IRenderOptions): Promise<void>;
+    /**
+     * Render a raw HTML string to a file (image/pdf per the concrete renderer).
+     * Intended for CI (e.g. screenshot comparison) where HTML is already produced.
+     *
+     * @param html - the HTML content to render
+     * @param filePath - output file path
+     * @param options.assetBasePath - directory served over the local http server so
+     *   relative asset URLs in the HTML resolve (defaults to the output file's dir)
+     * @param options.viewport - fixed viewport for deterministic captures
+     */
+    renderHtmlToFile(html: string, filePath: string, options?: {
+        assetBasePath?: string;
+        viewport?: {
+            width: number;
+            height: number;
+            deviceScaleFactor?: number;
+        };
+        onProgress?: RenderProgressCallback;
+    }): Promise<void>;
+    /**
+     * Shared render orchestration: local static server + pooled browser + page +
+     * timeout watchdog + cleanup. `prepare` populates the page content (template-compiled
+     * HTML, or raw HTML). The pooled browser survives; only the page is closed.
+     */
+    protected renderContentToFile(filePath: string, opts: {
+        assetBasePath?: string;
+        onProgress?: RenderProgressCallback;
+    }, prepare: (page: Page, httpPort: number, markLoading: () => void) => Promise<void>): Promise<void>;
+    /** Effective render timeout: configured value, else the default. */
+    protected get renderTimeoutMs(): number;
+    /** Apply the configured (or default) navigation and render timeouts to a page. */
+    protected configurePageTimeouts(page: Page): void;
+    /**
+     * Arm a watchdog that closes the page if a render exceeds the configured
+     * timeout - only the page is closed, the pooled browser may be serving other
+     * concurrent renders. Returns a function that cancels the watchdog.
+     */
+    protected armRenderWatchdog(page: Page): () => void;
+    /** Warn if a render took longer than the configured warning threshold. */
+    protected warnIfSlow(filePath: string, duration: number): void;
+    /** Close a page, downgrading any close error to a warning (best-effort cleanup). */
+    protected closePage(page: Page): Promise<void>;
     /**
-     * Enhanced browser cleanup with error handling
+     * Insert a <base href> into the HTML <head> so relative asset URLs resolve
+     * against the local static server. No-op if the HTML already declares a <base>.
      */
-    protected safeBrowserCleanup(browser: Browser): Promise<void>;
+    protected injectBaseHref(html: string, baseUrl: string): string;
     /**
-     * Force close browser with process termination
+     * Close the pooled browser when the service is disposed (e.g. DI.dispose() at shutdown).
+     * Callers that render one-shot (CLI, single email) should dispose so the process can exit.
      */
-    protected forceCloseBrowser(browser: Browser): Promise<void>;
+    dispose(): Promise<void>;
     /**
-     * Enhanced server cleanup with timeout
+     * Abstract method to perform specific rendering (PDF or image)
      */
-    protected safeServerCleanup(server: http.Server): Promise<void>;
+    protected abstract performRender(page: Page, filePath: string): Promise<void>;
+    render(_templateName: string, _model: unknown, _language?: string): Promise<string>;
     /**
      * Add page event listeners with cleanup function
      */
-    protected addPageEventListeners(page: any): () => void;
+    protected addPageEventListeners(page: Page): () => void;
 }
 //# sourceMappingURL=index.d.ts.map

package/lib/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAwB,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGjE,OAAO,EAAE,GAAG,EAAU,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAG7B,OAAO,wBAAwB,CAAC;AAIhC,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE;QACN,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,IAAI,EAAE,aAAa,CAAC;IAEpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,KAAK,CAAC,EAAE;QAEN;;;WAGG;QACH,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAA;CACF;AAED,8BAAsB,iBAAkB,SAAQ,gBAAgB;IAC9D,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAGtD,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;IAGnB,SAAS,CAAC,iBAAiB,EAAE,SAAS,CAAC;IAE1B,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgH3G;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;cAKhF,OAAO,CAAC,KAAK,EAAE,MAAM;cAErB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IA2CtE;;OAEG;cACa,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnE;;OAEG;cACa,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlE;;OAEG;cACa,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BrE;;OAEG;IACH,SAAS,CAAC,qBAAqB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,IAAI;CA0BvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}