@push.rocks/smartbrowser 2.0.8 → 2.0.11

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartbrowser',
-    version: '2.0.8',
+    version: '2.0.11',
     description: 'A simplified Puppeteer wrapper for easy automation and testing tasks.'
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSwwQkFBMEI7SUFDaEMsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVFQUF1RTtDQUNyRixDQUFBIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSwwQkFBMEI7SUFDaEMsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVFQUF1RTtDQUNyRixDQUFBIn0=

package/dist_ts/index.d.ts

@@ -10,6 +10,10 @@ export declare class SmartBrowser {
      * start the SmartBrowser instance
      */
     start(): Promise<void>;
+    /**
+     * ensure SmartPdf is initialized (lazy)
+     */
+    private ensureSmartPdf;
     /**
      * stop the SmartBrowser instance
      */

package/dist_ts/index.js

@@ -9,21 +9,33 @@ export class SmartBrowser {
      */
     async start() {
         this.headlessBrowser = await plugins.smartpuppeteer.getEnvAwareBrowserInstance();
-        this.smartpdf = new plugins.smartpdf.SmartPdf();
-        await this.smartpdf.start(this.headlessBrowser);
+        // SmartPdf is lazy-initialized only when PDF methods are called
+    }
+    /**
+     * ensure SmartPdf is initialized (lazy)
+     */
+    async ensureSmartPdf() {
+        if (!this.smartpdf) {
+            this.smartpdf = new plugins.smartpdf.SmartPdf();
+            await this.smartpdf.start(this.headlessBrowser);
+        }
     }
     /**
      * stop the SmartBrowser instance
      */
     async stop() {
+        if (this.smartpdf) {
+            await this.smartpdf.stop();
+            this.smartpdf = null;
+        }
         await this.headlessBrowser.close();
-        await this.smartpdf.stop();
     }
     /**
      * create a pdf from page
      * @param urlArg
      */
     async pdfFromPage(urlArg) {
+        await this.ensureSmartPdf();
         const result = await this.smartpdf.getFullWebsiteAsSinglePdf(urlArg);
         return result;
     }
@@ -37,9 +49,10 @@ export class SmartBrowser {
         await page.goto(urlArg, {
             waitUntil: 'networkidle2',
         });
-        const screenshotBuffer = (await page.screenshot({
+        const screenshotResult = await page.screenshot({
             encoding: 'binary',
-        }));
+        });
+        const screenshotBuffer = Buffer.from(screenshotResult);
         await page.close();
         return {
             name: pageId,
@@ -54,14 +67,21 @@ export class SmartBrowser {
      */
     async evaluateOnPage(urlArg, funcArg) {
         const page = await this.headlessBrowser.newPage();
-        await page.goto(urlArg, {
-            waitUntil: 'networkidle2',
-        });
-        const result = await page.evaluate(funcArg);
-        await page.close();
-        return result;
+        try {
+            await page.goto(urlArg, {
+                waitUntil: 'networkidle2',
+            });
+            const result = await page.evaluate(funcArg);
+            return result;
+        }
+        finally {
+            try {
+                await page.close();
+            }
+            catch (e) { /* page may already be closed */ }
+        }
     }
 }
 import { smartpuppeteer } from './smartbrowser.plugins.js';
 export { smartpuppeteer };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLDJCQUEyQixDQUFDO0FBRXJELE9BQU8sS0FBSyxVQUFVLE1BQU0sdUJBQXVCLENBQUM7QUFFcEQ7O0dBRUc7QUFDSCxNQUFNLE9BQU8sWUFBWTtJQUl2Qjs7T0FFRztJQUNJLEtBQUssQ0FBQyxLQUFLO1FBQ2hCLElBQUksQ0FBQyxlQUFlLEdBQUcsTUFBTSxPQUFPLENBQUMsY0FBYyxDQUFDLDBCQUEwQixFQUFFLENBQUM7UUFDakYsSUFBSSxDQUFDLFFBQVEsR0FBRyxJQUFJLE9BQU8sQ0FBQyxRQUFRLENBQUMsUUFBUSxFQUFFLENBQUM7UUFDaEQsTUFBTSxJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsZUFBZSxDQUFDLENBQUM7SUFDbEQsQ0FBQztJQUVEOztPQUVHO0lBQ0ksS0FBSyxDQUFDLElBQUk7UUFDZixNQUFNLElBQUksQ0FBQyxlQUFlLENBQUMsS0FBSyxFQUFFLENBQUM7UUFDbkMsTUFBTSxJQUFJLENBQUMsUUFBUSxDQUFDLElBQUksRUFBRSxDQUFDO0lBQzdCLENBQUM7SUFFRDs7O09BR0c7SUFDSSxLQUFLLENBQUMsV0FBVyxDQUFDLE1BQWM7UUFDckMsTUFBTSxNQUFNLEdBQUcsTUFBTSxJQUFJLENBQUMsUUFBUSxDQUFDLHlCQUF5QixDQUFDLE1BQU0sQ0FBQyxDQUFDO1FBQ3JFLE9BQU8sTUFBTSxDQUFDO0lBQ2hCLENBQUM7SUFFRDs7O09BR0c7SUFDSSxLQUFLLENBQUMsa0JBQWtCLENBQUMsTUFBYztRQUM1QyxNQUFNLE1BQU0sR0FBRyxPQUFPLENBQUMsV0FBVyxDQUFDLE9BQU8sRUFBRSxDQUFDO1FBQzdDLE1BQU0sSUFBSSxHQUFHLE1BQU0sSUFBSSxDQUFDLGVBQWUsQ0FBQyxPQUFPLEVBQUUsQ0FBQztRQUNsRCxNQUFNLElBQUksQ0FBQyxJQUFJLENBQUMsTUFBTSxFQUFFO1lBQ3RCLFNBQVMsRUFBRSxjQUFjO1NBQzFCLENBQUMsQ0FBQztRQUNILE1BQU0sZ0JBQWdCLEdBQUcsQ0FBQyxNQUFNLElBQUksQ0FBQyxVQUFVLENBQUM7WUFDOUMsUUFBUSxFQUFFLFFBQVE7U0FDbkIsQ0FBQyxDQUFXLENBQUM7UUFDZCxNQUFNLElBQUksQ0FBQyxLQUFLLEVBQUUsQ0FBQztRQUNuQixPQUFPO1lBQ0wsSUFBSSxFQUFFLE1BQU07WUFDWixFQUFFLEVBQUUsR0FBRyxNQUFNLEtBQUs7WUFDbEIsTUFBTSxFQUFFLGdCQUFnQjtTQUN6QixDQUFDO0lBQ0osQ0FBQztJQUVEOzs7O09BSUc7SUFDSSxLQUFLLENBQUMsY0FBYyxDQUFJLE1BQWMsRUFBRSxPQUF5QjtRQUN0RSxNQUFNLElBQUksR0FBRyxNQUFNLElBQUksQ0FBQyxlQUFlLENBQUMsT0FBTyxFQUFFLENBQUM7UUFDbEQsTUFBTSxJQUFJLENBQUMsSUFBSSxDQUFDLE1BQU0sRUFBRTtZQUN0QixTQUFTLEVBQUUsY0FBYztTQUMxQixDQUFDLENBQUM7UUFDSCxNQUFNLE1BQU0sR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsT0FBTyxDQUFDLENBQUM7UUFDNUMsTUFBTSxJQUFJLENBQUMsS0FBSyxFQUFFLENBQUM7UUFDbkIsT0FBTyxNQUFNLENBQUM7SUFDaEIsQ0FBQztDQUNGO0FBRUQsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBQzNELE9BQU8sRUFBRSxjQUFjLEVBQUUsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLDJCQUEyQixDQUFDO0FBRXJELE9BQU8sS0FBSyxVQUFVLE1BQU0sdUJBQXVCLENBQUM7QUFFcEQ7O0dBRUc7QUFDSCxNQUFNLE9BQU8sWUFBWTtJQUl2Qjs7T0FFRztJQUNJLEtBQUssQ0FBQyxLQUFLO1FBQ2hCLElBQUksQ0FBQyxlQUFlLEdBQUcsTUFBTSxPQUFPLENBQUMsY0FBYyxDQUFDLDBCQUEwQixFQUFFLENBQUM7UUFDakYsZ0VBQWdFO0lBQ2xFLENBQUM7SUFFRDs7T0FFRztJQUNLLEtBQUssQ0FBQyxjQUFjO1FBQzFCLElBQUksQ0FBQyxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDbkIsSUFBSSxDQUFDLFFBQVEsR0FBRyxJQUFJLE9BQU8sQ0FBQyxRQUFRLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDaEQsTUFBTSxJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsZUFBZSxDQUFDLENBQUM7UUFDbEQsQ0FBQztJQUNILENBQUM7SUFFRDs7T0FFRztJQUNJLEtBQUssQ0FBQyxJQUFJO1FBQ2YsSUFBSSxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDbEIsTUFBTSxJQUFJLENBQUMsUUFBUSxDQUFDLElBQUksRUFBRSxDQUFDO1lBQzNCLElBQUksQ0FBQyxRQUFRLEdBQUcsSUFBSSxDQUFDO1FBQ3ZCLENBQUM7UUFDRCxNQUFNLElBQUksQ0FBQyxlQUFlLENBQUMsS0FBSyxFQUFFLENBQUM7SUFDckMsQ0FBQztJQUVEOzs7T0FHRztJQUNJLEtBQUssQ0FBQyxXQUFXLENBQUMsTUFBYztRQUNyQyxNQUFNLElBQUksQ0FBQyxjQUFjLEVBQUUsQ0FBQztRQUM1QixNQUFNLE1BQU0sR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMseUJBQXlCLENBQUMsTUFBTSxDQUFDLENBQUM7UUFDckUsT0FBTyxNQUFNLENBQUM7SUFDaEIsQ0FBQztJQUVEOzs7T0FHRztJQUNJLEtBQUssQ0FBQyxrQkFBa0IsQ0FBQyxNQUFjO1FBQzVDLE1BQU0sTUFBTSxHQUFHLE9BQU8sQ0FBQyxXQUFXLENBQUMsT0FBTyxFQUFFLENBQUM7UUFDN0MsTUFBTSxJQUFJLEdBQUcsTUFBTSxJQUFJLENBQUMsZUFBZSxDQUFDLE9BQU8sRUFBRSxDQUFDO1FBQ2xELE1BQU0sSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUU7WUFDdEIsU0FBUyxFQUFFLGNBQWM7U0FDMUIsQ0FBQyxDQUFDO1FBQ0gsTUFBTSxnQkFBZ0IsR0FBRyxNQUFNLElBQUksQ0FBQyxVQUFVLENBQUM7WUFDN0MsUUFBUSxFQUFFLFFBQVE7U0FDbkIsQ0FBQyxDQUFDO1FBQ0gsTUFBTSxnQkFBZ0IsR0FBRyxNQUFNLENBQUMsSUFBSSxDQUFDLGdCQUFnQixDQUFDLENBQUM7UUFDdkQsTUFBTSxJQUFJLENBQUMsS0FBSyxFQUFFLENBQUM7UUFDbkIsT0FBTztZQUNMLElBQUksRUFBRSxNQUFNO1lBQ1osRUFBRSxFQUFFLEdBQUcsTUFBTSxLQUFLO1lBQ2xCLE1BQU0sRUFBRSxnQkFBZ0I7U0FDekIsQ0FBQztJQUNKLENBQUM7SUFFRDs7OztPQUlHO0lBQ0ksS0FBSyxDQUFDLGNBQWMsQ0FBSSxNQUFjLEVBQUUsT0FBeUI7UUFDdEUsTUFBTSxJQUFJLEdBQUcsTUFBTSxJQUFJLENBQUMsZUFBZSxDQUFDLE9BQU8sRUFBRSxDQUFDO1FBQ2xELElBQUksQ0FBQztZQUNILE1BQU0sSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUU7Z0JBQ3RCLFNBQVMsRUFBRSxjQUFjO2FBQzFCLENBQUMsQ0FBQztZQUNILE1BQU0sTUFBTSxHQUFHLE1BQU0sSUFBSSxDQUFDLFFBQVEsQ0FBQyxPQUFPLENBQUMsQ0FBQztZQUM1QyxPQUFPLE1BQU0sQ0FBQztRQUNoQixDQUFDO2dCQUFTLENBQUM7WUFDVCxJQUFJLENBQUM7Z0JBQUMsTUFBTSxJQUFJLENBQUMsS0FBSyxFQUFFLENBQUM7WUFBQyxDQUFDO1lBQUMsT0FBTyxDQUFDLEVBQUUsQ0FBQyxDQUFDLGdDQUFnQyxDQUFDLENBQUM7UUFDNUUsQ0FBQztJQUNILENBQUM7Q0FDRjtBQUVELE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSwyQkFBMkIsQ0FBQztBQUMzRCxPQUFPLEVBQUUsY0FBYyxFQUFFLENBQUMifQ==

package/npmextra.json

@@ -1,8 +1,5 @@
 {
-  "npmci": {
-    "npmAccessLevel": "public"
-  },
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "code.foss.global",
@@ -20,9 +17,17 @@
         "web scraping",
         "browser automation"
       ]
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
     }
   },
-  "tsdoc": {
+  "@git.zone/tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
-  }
+  },
+  "@ship.zone/szci": {}
 }

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@push.rocks/smartbrowser",
-  "version": "2.0.8",
+  "version": "2.0.11",
   "description": "A simplified Puppeteer wrapper for easy automation and testing tasks.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
+  "scripts": {
+    "test": "(tstest test/ --web)",
+    "build": "(tsbuild --web)",
+    "buildDocs": "tsdoc"
+  },
   "repository": {
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartbrowser.git"
@@ -17,16 +22,16 @@
   "homepage": "https://code.foss.global/push.rocks/smartbrowser",
   "dependencies": {
     "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartpdf": "^3.1.8",
-    "@push.rocks/smartpuppeteer": "^2.0.0",
+    "@push.rocks/smartpdf": "^4.2.0",
+    "@push.rocks/smartpuppeteer": "^2.0.5",
     "@push.rocks/smartunique": "^3.0.9"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.2.0",
-    "@git.zone/tsrun": "^1.3.3",
-    "@git.zone/tstest": "^1.0.90",
-    "@push.rocks/tapbundle": "^5.5.4",
-    "@types/node": "^22.10.4"
+    "@git.zone/tsbuild": "^4.3.0",
+    "@git.zone/tsrun": "^2.0.1",
+    "@git.zone/tstest": "^3.3.1",
+    "@push.rocks/tapbundle": "^6.0.3",
+    "@types/node": "^25.3.5"
   },
   "private": false,
   "files": [
@@ -52,10 +57,5 @@
     "screenshot",
     "web scraping",
     "browser automation"
-  ],
-  "scripts": {
-    "test": "(tstest test/ --web)",
-    "build": "(tsbuild --web --allowimplicitany)",
-    "buildDocs": "tsdoc"
-  }
-}
+  ]
+}

package/readme.hints.md

@@ -1 +1,16 @@
- 
+# Smartbrowser Hints
+
+## Dependencies (as of 2026-03-09)
+- `@push.rocks/smartpdf` v4.2.x: Has `SmartPdf.create()` factory method, but `new SmartPdf()` + `start(browser)` still works. Lazy init pattern used.
+- `@push.rocks/smartpuppeteer` v2.x: `getEnvAwareBrowserInstance()` main entry point
+- `@push.rocks/tapbundle` v6.x: No longer exports `expectAsync`, only `tap`, `expect`, `TapWrap`, `webhelpers`
+- `@git.zone/tsbuild` v4.x: No `--allowimplicitany` flag (defaults to `noImplicitAny: false`), `--web` flag still passed but ignored if no ts_web
+- `@git.zone/tstest` v3.3.x: Still supports `--web` flag, file suffix conventions changed (`.chromium.ts` for browser tests)
+- `@types/node` v25.x: Latest Node.js type definitions
+- Puppeteer `page.screenshot({ encoding: 'binary' })` returns `Uint8Array`, not `Buffer` - wrap with `Buffer.from()`
+
+## Build
+- `pnpm build` uses `tsbuild --web`
+- `pnpm test` uses `tstest test/ --web`
+- No ts_web directory exists in this project
+- Duplicate dayjs versions in transitive deps cause build errors; fix with `pnpm dedupe`

package/readme.md

@@ -1,102 +1,145 @@
 # @push.rocks/smartbrowser
-simplified puppeteer
+A simplified Puppeteer wrapper for easy browser automation, PDF generation, screenshots, and page evaluation.
 
 ## Install
-To install `@push.rocks/smartbrowser`, use the following npm command:
+
+To install `@push.rocks/smartbrowser`, use the following command with your preferred package manager:
 
 ```bash
-npm install @push.rocks/smartbrowser --save
+npm install @push.rocks/smartbrowser
+# or
+pnpm install @push.rocks/smartbrowser
 ```
 
-This will add `@push.rocks/smartbrowser` to your project's dependencies.
+This module works with Node.js and requires a Chromium-compatible browser available in the environment. It uses `@push.rocks/smartpuppeteer` under the hood, which automatically detects your environment and configures the browser accordingly (including CI/Docker scenarios).
 
 ## Usage
 
-`@push.rocks/smartbrowser` simplifies interactions with Puppeteer for tasks like generating PDFs or capturing screenshots from webpages. Below are examples illustrating how you can use `@push.rocks/smartbrowser` in your projects.
+`@push.rocks/smartbrowser` provides a high-level `SmartBrowser` class that wraps Puppeteer for common browser automation tasks: generating PDFs, capturing screenshots, and evaluating JavaScript on web pages.
 
 ### Getting Started
 
-First, import `SmartBrowser` from `@push.rocks/smartbrowser`:
+Import and initialize a `SmartBrowser` instance:
 
 ```typescript
 import { SmartBrowser } from '@push.rocks/smartbrowser';
-```
-
-Then, initialize and start the `SmartBrowser` instance:
 
-```typescript
 const smartBrowser = new SmartBrowser();
 await smartBrowser.start();
 ```
 
 ### Generating a PDF from a Webpage
 
-You can generate a PDF from any webpage URL. This can be particularly useful for generating reports, invoices, or snapshot captures of web content.
+Generate a full-page PDF from any URL. The result includes a `Buffer` with the PDF contents:
 
 ```typescript
-// Generate a PDF from a page
 const pdfResult = await smartBrowser.pdfFromPage('https://example.com');
-console.log(pdfResult.buffer); // This holds the PDF file's buffer
+console.log(pdfResult.buffer); // PDF file buffer
+console.log(pdfResult.name);   // Generated name identifier
 ```
 
+The PDF generation is powered by `@push.rocks/smartpdf`, which is lazily initialized on first use. This means the SmartPdf server is only started when you actually call `pdfFromPage()`, keeping resource usage minimal.
+
 ### Capturing a Screenshot of a Webpage
 
-Similarly, you can capture a screenshot of a webpage by passing the URL. This is useful for capturing the current state of a web application, for audits, or for keeping visual records.
+Capture a PNG screenshot of any webpage:
 
 ```typescript
-// Capture a screenshot from a page
 const screenshotResult = await smartBrowser.screenshotFromPage('https://example.com');
-console.log(screenshotResult.buffer); // This is the screenshot's buffer
+console.log(screenshotResult.buffer); // Screenshot buffer (PNG)
+console.log(screenshotResult.name);   // Short unique identifier
+console.log(screenshotResult.id);     // Identifier with extension
 ```
 
 ### Evaluating JavaScript on a Webpage
 
-`SmartBrowser` also allows you to evaluate JavaScript on the webpage. This can be useful for scraping data, testing web applications, or automating interactions with webpages.
+Run arbitrary JavaScript inside a page context and retrieve the result:
 
 ```typescript
-// Evaluate JavaScript on a page
-const pageTitle = await smartBrowser.evaluateOnPage('https://example.com', () => {
-  return document.title; // Gets the title of the page
+const pageTitle = await smartBrowser.evaluateOnPage('https://example.com', async () => {
+  return document.title;
 });
-console.log(pageTitle); // Logs the page title to the console
+console.log(pageTitle); // "Example Domain"
+```
+
+The `evaluateOnPage` method supports generic return types:
+
+```typescript
+const metrics = await smartBrowser.evaluateOnPage<{ width: number; height: number }>(
+  'https://example.com',
+  async () => {
+    return {
+      width: window.innerWidth,
+      height: window.innerHeight,
+    };
+  }
+);
+console.log(metrics.width, metrics.height);
+```
+
+Pages are automatically closed after evaluation, even if an error occurs.
+
+### Accessing the Underlying Puppeteer Browser
+
+For advanced use cases, you can access the Puppeteer browser instance directly:
+
+```typescript
+const page = await smartBrowser.headlessBrowser.newPage();
+await page.goto('https://example.com');
+// ... custom Puppeteer operations
+await page.close();
+```
+
+You can also import the `smartpuppeteer` module directly for lower-level browser management:
+
+```typescript
+import { smartpuppeteer } from '@push.rocks/smartbrowser';
+
+const browser = await smartpuppeteer.getEnvAwareBrowserInstance();
 ```
 
 ### Shutting Down
 
-Once your tasks are complete, it's important to properly shut down the `SmartBrowser` instance to free up resources:
+Always stop the browser instance when done to free resources:
 
 ```typescript
 await smartBrowser.stop();
 ```
 
-### Full Example
+This cleanly shuts down the SmartPdf server (if it was initialized) and closes the browser.
 
-Combining the above steps, here's a full example of using `@push.rocks/smartbrowser` to generate a PDF and capture a screenshot of a webpage:
+### Full Example
 
 ```typescript
 import { SmartBrowser } from '@push.rocks/smartbrowser';
 
-async function generateWebAssets() {
+async function main() {
   const smartBrowser = new SmartBrowser();
   await smartBrowser.start();
 
+  // Generate a PDF
   const pdfResult = await smartBrowser.pdfFromPage('https://example.com');
-  console.log('PDF Generated:', pdfResult.buffer);
+  console.log('PDF size:', pdfResult.buffer.length, 'bytes');
+
+  // Take a screenshot
+  const screenshot = await smartBrowser.screenshotFromPage('https://example.com');
+  console.log('Screenshot size:', screenshot.buffer.length, 'bytes');
 
-  const screenshotResult = await smartBrowser.screenshotFromPage('https://example.com');
-  console.log('Screenshot Captured:', screenshotResult.buffer);
+  // Evaluate JavaScript
+  const title = await smartBrowser.evaluateOnPage('https://example.com', async () => {
+    return document.title;
+  });
+  console.log('Page title:', title);
 
   await smartBrowser.stop();
 }
 
-generateWebAssets();
+main();
 ```
 
-In this guide, you've learned how to use `@push.rocks/smartbrowser` for common browser automation tasks. Follow this pattern to incorporate web automation into your applications efficiently.
-
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
@@ -106,7 +149,7 @@ This project is owned and maintained by Task Venture Capital GmbH. The names and
 
 ### Company Information
 
-Task Venture Capital GmbH  
+Task Venture Capital GmbH
 Registered at District court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartbrowser',
-  version: '2.0.8',
+  version: '2.0.11',
   description: 'A simplified Puppeteer wrapper for easy automation and testing tasks.'
 }

package/ts/index.ts

@@ -14,16 +14,28 @@ export class SmartBrowser {
    */
   public async start() {
     this.headlessBrowser = await plugins.smartpuppeteer.getEnvAwareBrowserInstance();
-    this.smartpdf = new plugins.smartpdf.SmartPdf();
-    await this.smartpdf.start(this.headlessBrowser);
+    // SmartPdf is lazy-initialized only when PDF methods are called
+  }
+
+  /**
+   * ensure SmartPdf is initialized (lazy)
+   */
+  private async ensureSmartPdf() {
+    if (!this.smartpdf) {
+      this.smartpdf = new plugins.smartpdf.SmartPdf();
+      await this.smartpdf.start(this.headlessBrowser);
+    }
   }
 
   /**
    * stop the SmartBrowser instance
    */
   public async stop() {
+    if (this.smartpdf) {
+      await this.smartpdf.stop();
+      this.smartpdf = null;
+    }
     await this.headlessBrowser.close();
-    await this.smartpdf.stop();
   }
 
   /**
@@ -31,6 +43,7 @@ export class SmartBrowser {
    * @param urlArg
    */
   public async pdfFromPage(urlArg: string): Promise<plugins.smartpdf.IPdf> {
+    await this.ensureSmartPdf();
     const result = await this.smartpdf.getFullWebsiteAsSinglePdf(urlArg);
     return result;
   }
@@ -45,9 +58,10 @@ export class SmartBrowser {
     await page.goto(urlArg, {
       waitUntil: 'networkidle2',
     });
-    const screenshotBuffer = (await page.screenshot({
+    const screenshotResult = await page.screenshot({
       encoding: 'binary',
-    })) as Buffer;
+    });
+    const screenshotBuffer = Buffer.from(screenshotResult);
     await page.close();
     return {
       name: pageId,
@@ -63,12 +77,15 @@ export class SmartBrowser {
    */
   public async evaluateOnPage<T>(urlArg: string, funcArg: () => Promise<T>) {
     const page = await this.headlessBrowser.newPage();
-    await page.goto(urlArg, {
-      waitUntil: 'networkidle2',
-    });
-    const result = await page.evaluate(funcArg);
-    await page.close();
-    return result;
+    try {
+      await page.goto(urlArg, {
+        waitUntil: 'networkidle2',
+      });
+      const result = await page.evaluate(funcArg);
+      return result;
+    } finally {
+      try { await page.close(); } catch (e) { /* page may already be closed */ }
+    }
   }
 }