fix(deps): upgrade dependencies and adapt code, tests, and docs for new upstream versions

changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2026-03-09 - 2.0.11 - fix(deps)
+upgrade dependencies and adapt code, tests, and docs for new upstream versions
+
+- Bump runtime deps: @push.rocks/smartpdf -> ^4.2.0, @push.rocks/smartpuppeteer -> ^2.0.5
+- Bump devDependencies to modern majors: @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
+- Remove --allowimplicitany from build script to match tsbuild v4 behavior
+- Fix Puppeteer screenshot handling: convert returned Uint8Array to Buffer via Buffer.from()
+- Update tests to match tapbundle v6 API (remove expectAsync) and export tap.start()
+- Add/expand documentation (readme.md and readme.hints.md) with dependency notes and usage examples
+
 ## 2026-03-09 - 2.0.10 - fix(config(npmextra))
 normalize npmextra.json keys to namespaced entries and add release registries
 

package.json

@@ -7,7 +7,7 @@
   "type": "module",
   "scripts": {
     "test": "(tstest test/ --web)",
-    "build": "(tsbuild --web --allowimplicitany)",
+    "build": "(tsbuild --web)",
     "buildDocs": "tsdoc"
   },
   "repository": {
@@ -22,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": [

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`

readme.md

@@ -1,99 +1,142 @@
 # @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');
 
-  const screenshotResult = await smartBrowser.screenshotFromPage('https://example.com');
-  console.log('Screenshot Captured:', screenshotResult.buffer);
+  // Take a screenshot
+  const screenshot = await smartBrowser.screenshotFromPage('https://example.com');
+  console.log('Screenshot size:', screenshot.buffer.length, 'bytes');
+
+  // 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.

test/test.ts

@@ -1,4 +1,4 @@
-import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
+import { tap, expect } from '@push.rocks/tapbundle';
 
 import * as smartbrowser from '../ts/index.js';
 let testSmartBrowser: smartbrowser.SmartBrowser;
@@ -33,4 +33,4 @@ tap.test('should stop the browser ', async () => {
   await testSmartBrowser.stop();
 });
 
-tap.start();
+export default tap.start();

ts/00_commitinfo_data.ts

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

ts/index.ts

@@ -58,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,