@push.rocks/smartbrowser 2.0.11 → 4.0.0

package/dist_ts_web/index.d.ts

@@ -0,0 +1,3 @@
+export { LiveBrowserCanvasRenderer } from './classes.livebrowsercanvasrenderer.js';
+export type * from './interfaces.livebrowsercanvas.js';
+export type { ILiveBrowserError, ILiveBrowserErrorEvent, ILiveBrowserFrame, ILiveBrowserFrameAcknowledgement, ILiveBrowserFrameAcknowledgementRequest, ILiveBrowserFrameEvent, ILiveBrowserInputBase, ILiveBrowserInsertTextInput, ILiveBrowserKeyInput, ILiveBrowserModifierState, ILiveBrowserMouseInput, ILiveBrowserScreencastMetadata, ILiveBrowserState, ILiveBrowserStateEvent, ILiveBrowserTabState, ILiveBrowserViewport, ILiveBrowserWheelInput, TLiveBrowserEvent, TLiveBrowserEventListener, TLiveBrowserImageFormat, TLiveBrowserStatus, TLiveBrowserTabStatus, } from '@push.rocks/smartpuppeteer';

package/dist_ts_web/index.js

@@ -0,0 +1,2 @@
+export { LiveBrowserCanvasRenderer } from './classes.livebrowsercanvasrenderer.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c193ZWIvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLHlCQUF5QixFQUFFLE1BQU0sd0NBQXdDLENBQUMifQ==

package/dist_ts_web/interfaces.livebrowsercanvas.d.ts

@@ -0,0 +1,41 @@
+import type { ILiveBrowserFrame, ILiveBrowserFrameAcknowledgement, ILiveBrowserFrameAcknowledgementRequest, ILiveBrowserInsertTextInput, ILiveBrowserKeyInput, ILiveBrowserMouseInput, ILiveBrowserState, ILiveBrowserViewport, ILiveBrowserWheelInput, TLiveBrowserEventListener } from '@push.rocks/smartpuppeteer';
+/**
+ * Transport adapter for one renderer. Frame events must use strictly increasing
+ * sequence values for each onEvent subscription/renderer run.
+ */
+export interface ILiveBrowserCanvasClient {
+    getState(): ILiveBrowserState;
+    onEvent(listenerArg: TLiveBrowserEventListener): () => void;
+    /**
+     * A fulfilled result, including accepted: false, settles the local attempt.
+     * It does not prove that the upstream frame was retired.
+     */
+    acknowledgeFrame(requestArg: ILiveBrowserFrameAcknowledgementRequest, optionsArg: ILiveBrowserCanvasOperationOptions): Promise<ILiveBrowserFrameAcknowledgement>;
+    setViewport(viewportArg: ILiveBrowserViewport, optionsArg: ILiveBrowserCanvasOperationOptions): Promise<void>;
+    dispatchMouse(inputArg: ILiveBrowserMouseInput, optionsArg: ILiveBrowserCanvasOperationOptions): Promise<void>;
+    dispatchWheel(inputArg: ILiveBrowserWheelInput, optionsArg: ILiveBrowserCanvasOperationOptions): Promise<void>;
+    dispatchKey(inputArg: ILiveBrowserKeyInput, optionsArg: ILiveBrowserCanvasOperationOptions): Promise<void>;
+    insertText(inputArg: ILiveBrowserInsertTextInput, optionsArg: ILiveBrowserCanvasOperationOptions): Promise<void>;
+}
+export interface ILiveBrowserCanvasOperationOptions {
+    /** Adapters must propagate this signal and reject promptly when it aborts. */
+    signal: AbortSignal;
+}
+export type TLiveBrowserCanvasErrorCode = 'frame_acknowledgement_failed' | 'frame_render_failed' | 'input_dispatch_failed' | 'input_queue_capacity_exceeded' | 'remote_browser_error' | 'renderer_callback_failed' | 'renderer_cleanup_failed' | 'viewport_update_failed';
+export interface ILiveBrowserCanvasError {
+    code: TLiveBrowserCanvasErrorCode;
+    message: string;
+    cause?: unknown;
+    frame?: ILiveBrowserFrame;
+}
+export interface ILiveBrowserCanvasRendererOptions {
+    canvas: HTMLCanvasElement;
+    client: ILiveBrowserCanvasClient;
+    focusTarget?: HTMLElement;
+    resizeTarget?: Element;
+    getDeviceScaleFactor?: () => number;
+    operationTimeoutMs?: number;
+    frameDecodeTimeoutMs?: number;
+    onError?: (errorArg: ILiveBrowserCanvasError) => void;
+    onFrameRendered?: (frameArg: ILiveBrowserFrame) => void;
+}

package/dist_ts_web/interfaces.livebrowsercanvas.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5saXZlYnJvd3NlcmNhbnZhcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3dlYi9pbnRlcmZhY2VzLmxpdmVicm93c2VyY2FudmFzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/license.md

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Task Venture Capital GmbH <hello@task.vc>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,49 +1,56 @@
 {
   "name": "@push.rocks/smartbrowser",
-  "version": "2.0.11",
+  "version": "4.0.0",
   "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"
+  "exports": {
+    ".": {
+      "import": "./dist_ts/index.js",
+      "types": "./dist_ts/index.d.ts"
+    },
+    "./web": {
+      "import": "./dist_ts_web/index.js",
+      "types": "./dist_ts_web/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=22.12.0"
   },
   "repository": {
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartbrowser.git"
   },
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
   "bugs": {
-    "url": "https://gitlab.com/pushrocks/smartbrowser/issues"
+    "url": "https://code.foss.global/push.rocks/smartbrowser/issues"
   },
   "homepage": "https://code.foss.global/push.rocks/smartbrowser",
   "dependencies": {
-    "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartpdf": "^4.2.0",
-    "@push.rocks/smartpuppeteer": "^2.0.5",
-    "@push.rocks/smartunique": "^3.0.9"
+    "@push.rocks/smartdelay": "^3.1.0",
+    "@push.rocks/smartpdf": "^5.0.1",
+    "@push.rocks/smartpuppeteer": "^2.4.0",
+    "@push.rocks/smartunique": "^3.0.10"
   },
   "devDependencies": {
-    "@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"
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^4.0.0",
+    "@types/node": "^26.2.0"
   },
   "private": false,
   "files": [
     "ts/**/*",
     "ts_web/**/*",
-    "dist/**/*",
     "dist_*/**/*",
     "dist_ts/**/*",
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
+    "license.md",
     "readme.md"
   ],
   "browserslist": [
@@ -57,5 +64,10 @@
     "screenshot",
     "web scraping",
     "browser automation"
-  ]
-}
+  ],
+  "scripts": {
+    "test": "tstest test/",
+    "build": "tsbuild tsfolders",
+    "buildDocs": "tsdoc"
+  }
+}

package/readme.hints.md

@@ -1,16 +1,30 @@
-# Smartbrowser Hints
+# 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
+## Dependencies (as of 2026-08-15)
+- `@push.rocks/smartpdf` v5.x uses SmartPuppeteer 2/Puppeteer 25 browser types. `SmartPdf` remains lazy and starts only for PDF methods.
+- `@push.rocks/smartpuppeteer` v2.4 owns `LiveBrowserSession`, the canonical transport-neutral live browser contracts, and bounded CDP frame acknowledgement flow.
+- Tests import `@git.zone/tstest/tapbundle`; browser tests use the `.chromium.ts` suffix.
+- The Node.js entry requires Node.js 22.12 or newer. This repository uses pnpm 11.20 for development and release tooling.
 - 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`
+- `pnpm run build` uses `tsbuild tsfolders` and emits both `dist_ts` and `dist_ts_web`.
+- `@push.rocks/smartbrowser/web` must remain runtime-isolated from Puppeteer, SmartPDF, Buffer, and Node.js built-ins. Only type imports from SmartPuppeteer are allowed.
+- `pnpm test` runs Node and Chromium files through tstest 4.
+
+## Canvas Renderer Invariants
+- The client facade is transport-neutral. Authentication, authorization, binary wire encoding, session ownership, and egress policy belong to the consuming adapter.
+- Input always carries the identity of the actually displayed frame, never merely the newest state event.
+- Cached state may lag a new frame generation. A state identity ahead of the displayed frame invalidates it; same-identity metadata updates do not.
+- One frame may decode while only the newest subsequent frame waits. Active-run frames must pass full static validation and then have a sequence strictly above the per-run high-water value. Duplicate and out-of-order frames suspend without acknowledgement; resume resets the high-water value.
+- The renderer makes at most one acknowledgement request for each valid drawn, stale, superseded, or decode-failed frame while its run remains active. Interrupted and invalid-protocol frames do not start acknowledgement work. An acknowledgement that throws, rejects, or times out suspends the run; `{ accepted: false }` settles the local attempt and does not prove upstream retirement.
+- Every asynchronous client method receives `ILiveBrowserCanvasOperationOptions` with a renderer-owned `AbortSignal`. Operation deadline, run suspension, and stop all abort the signal; adapters must propagate it through the underlying transport.
+- Renderer starts, suspensions, resumes, and stops are serialized by run epoch. Suspension aborts owned work and drops state, frames, queued input, pressed state, and old-generation recovery. Resume creates a fresh epoch and requires newly read state plus a newly displayed frame before input.
+- Native `createImageBitmap()` jobs are tracked outside per-run cleanup. A new start or resume waits for every prior raw decode to settle, and late bitmaps are closed after timeout or interruption. Start or resume can remain pending indefinitely if the browser never settles native decode work.
+- Acknowledgement failures, input-release failures, capacity exhaustion, and client/decode timeouts suspend only the current run. Malformed, oversized, or inconsistent frame protocol and deterministic decode-integrity failures are also terminal to that run. Recovery is explicit through `resume()`; none of these paths retries automatically.
+- Internal renderer ceilings are 16 pending acknowledgements; 12,288 per frame dimension and 8,294,400 frame pixels; 34,226,176 encoded bytes; and a 4,096 x 4,096 viewport, device scale factor 3, and 8,294,400 physical pixels.
+- Repeated blur, visibility, and pointer-loss resets coalesce into one bounded reset operation.
+- During an active run, pressed input is retained until release succeeds, with one retry for transient release failures. Input remains blocked while a release is unresolved. Suspension discards pressed state without dispatching releases into a later run.
+- Resize uses a caller-supplied stable CSS element. Requests are latest-only and serialized; input is released before resizing and remains blocked until a frame meeting the target revision fence is drawn.
+- Intrinsic canvas dimensions come from encoded frame dimensions. Pointer coordinates map to the frame's logical CSS viewport.
+- Pointer and wheel listeners remain on the canvas. Keyboard and composition listeners use `focusTarget`, which defaults to the canvas. Call `insertText()` for text committed by an external IME or dedicated input control.

package/readme.md

@@ -1,17 +1,21 @@
 # @push.rocks/smartbrowser
 A simplified Puppeteer wrapper for easy browser automation, PDF generation, screenshots, and page evaluation.
 
+The package also provides an isolated browser-side entry at `@push.rocks/smartbrowser/web`. Its `LiveBrowserCanvasRenderer` displays SmartPuppeteer live-session frames in a canvas and maps local input back to transport-neutral browser commands without bundling Puppeteer or Node.js code into the web application.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
 ## Install
 
-To install `@push.rocks/smartbrowser`, use the following command with your preferred package manager:
+Install the package with pnpm:
 
 ```bash
-npm install @push.rocks/smartbrowser
-# or
-pnpm install @push.rocks/smartbrowser
+pnpm add @push.rocks/smartbrowser
 ```
 
-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).
+The Node.js entry requires Node.js 22.12 or newer and a Chromium-compatible browser. It uses SmartPuppeteer 2.4, Puppeteer 25, and SmartPDF 5. SmartPuppeteer detects common local, CI, and container environments and configures Chromium accordingly.
 
 ## Usage
 
@@ -98,6 +102,86 @@ import { smartpuppeteer } from '@push.rocks/smartbrowser';
 const browser = await smartpuppeteer.getEnvAwareBrowserInstance();
 ```
 
+## Live Browser Canvas
+
+Import the browser-only renderer from `@push.rocks/smartbrowser/web`. The Node.js root entry is intentionally separate and must not be imported into a frontend bundle.
+
+The renderer receives a caller-provided `ILiveBrowserCanvasClient`. An application adapter implements that interface using its authenticated transport and keeps the latest `ILiveBrowserState` available through `getState()`. The adapter must emit frame events with strictly increasing `frame.sequence` values for each `onEvent()` subscription/renderer run. SmartBrowser does not prescribe TypedSocket, WebSocket framing, base64 conversion, authentication, authorization, or session ownership.
+
+```typescript
+import {
+  LiveBrowserCanvasRenderer,
+  type ILiveBrowserCanvasClient,
+} from '@push.rocks/smartbrowser/web';
+
+export async function mountLiveBrowser(client: ILiveBrowserCanvasClient) {
+  const viewport = document.querySelector<HTMLElement>('[data-live-browser-viewport]')!;
+  const canvas = viewport.querySelector<HTMLCanvasElement>('canvas')!;
+
+  const renderer = new LiveBrowserCanvasRenderer({
+    canvas,
+    client,
+    // Observe a stable CSS-sized element, not the canvas backing bitmap.
+    resizeTarget: viewport,
+    onError: (error) => console.error(error.code, error.message),
+  });
+
+  await renderer.start();
+  return async () => {
+    // Stop the renderer before closing its transport so cancellation reaches the adapter.
+    await renderer.stop();
+  };
+}
+```
+
+A minimal host keeps CSS sizing independent from the canvas's encoded backing dimensions:
+
+```html
+<div data-live-browser-viewport style="width: 100%; height: 600px; overflow: hidden">
+  <canvas style="display: block; width: 100%; height: 100%"></canvas>
+</div>
+```
+
+`ILiveBrowserCanvasClient` exposes the renderer-facing subset of the canonical SmartPuppeteer live-session API:
+
+- Cached state and events: `getState()` and `onEvent()`
+- Frame flow control: `acknowledgeFrame()`
+- Viewport synchronization: `setViewport()`
+- Input: `dispatchMouse()`, `dispatchWheel()`, `dispatchKey()`, and `insertText()`
+
+Every asynchronous client method receives a required second `ILiveBrowserCanvasOperationOptions` argument containing `signal: AbortSignal`. Adapters must pass that signal through to their transport operation and reject promptly when it aborts. The renderer aborts it at the operation deadline and when the current run is suspended or stopped. There is no compatibility path for adapters that omit cancellation.
+
+The renderer keeps at most one frame decoding and one newest frame queued. For an active run it validates the complete static frame protocol before requiring `frame.sequence` to be strictly greater than that run's high-water sequence. Duplicate or out-of-order frames are terminal `frame_render_failed` protocol errors and are not acknowledged. A resumed run creates a new subscription and resets the high-water sequence by design.
+
+The renderer makes one acknowledgement attempt after a valid frame is drawn, deliberately dropped, found stale, superseded, or fails decoding while its run remains active. SmartPuppeteer may fulfill an acknowledgement with `{ accepted: false }` for stale, retired, duplicate, or identity-mismatched frames. That result settles the renderer's local attempt without suspending or retrying, and it does not prove upstream retirement. Only an acknowledgement operation that throws, rejects, or times out suspends the run; reaching acknowledgement capacity does the same. Input identity always comes from the frame actually displayed, so tab, generation, and viewport changes block stale clicks and keystrokes. Encoded `frame.width` and `frame.height` set the canvas backing bitmap, while pointer coordinates map through the displayed canvas rectangle into the frame's logical CSS viewport.
+
+Call `suspend()` when the adapter observes a transport interruption, then call `resume()` after the adapter has established a fresh transport. Suspension aborts active work, removes listeners, drops queued input and pressed-input recovery, and clears state and the displayed frame. `resume()` creates a new renderer run generation, re-subscribes to events, reads state again, and keeps input blocked until a new matching frame is displayed. Old input and release transitions are never replayed into the new generation. Operation timeouts request this same suspended lifecycle, so one transient acknowledgement timeout does not permanently poison the renderer instance.
+
+Malformed frame identities, metadata, viewport values, formats, MIME pairings, dimensions, pixel areas, byte lengths, and deterministic image decode or dimension-integrity failures are terminal to the current run. Decoded dimensions are checked before supersession and currentness, so a mismatched decoded bitmap remains terminal even when a newer frame arrived during decoding. These failures are reported as `frame_render_failed` and require an explicit `resume()`; the renderer does not retry them automatically. The renderer only schedules rendering, acknowledgements, viewport synchronization, and direct input. Navigation scheduling remains the responsibility of the server runtime and application adapter.
+
+The renderer's fixed internal protocol ceilings are 16 pending frame acknowledgement operations; frame dimensions of at most 12,288 on either axis and 8,294,400 pixels; encoded frame data of at most 34,226,176 bytes; and viewports of at most 4,096 x 4,096 CSS pixels, device scale factor 3, and 8,294,400 physical pixels (`width * height * deviceScaleFactor^2`).
+
+Browser-native `createImageBitmap()` work is not abortable. After a wrapper timeout or run interruption, the renderer closes a bitmap that resolves late and waits for all prior raw decode jobs to settle before `start()` or `resume()` starts another run. Consequently, `start()` or `resume()` can remain pending indefinitely if the browser platform never settles a prior `createImageBitmap()` call.
+
+Pointer and wheel input are captured from the canvas. Keyboard and best-effort `compositionend` input are captured from `focusTarget`, which defaults to the canvas and receives focus on pointer down. The renderer temporarily makes an unfocusable focus target focusable and restores its prior `tabindex` on stop. Applications with a dedicated text or IME control can call `renderer.insertText(text)` explicitly.
+
+When `resizeTarget` is supplied, resize updates are deduplicated, serialized, and fenced by viewport revision. The target must have stable CSS dimensions that do not depend on `canvas.width` or `canvas.height`; this prevents intrinsic canvas updates from causing resize feedback.
+
+`ILiveBrowserCanvasRendererOptions` supports:
+
+- `canvas` and `client`: required rendering and transport-adapter dependencies.
+- `focusTarget`: optional keyboard and composition event target; defaults to `canvas`.
+- `resizeTarget`: optional stable CSS-sized element observed for remote viewport updates.
+- `getDeviceScaleFactor`: optional scale provider; defaults to `window.devicePixelRatio` and is useful when the application controls remote scaling explicitly.
+- `operationTimeoutMs`: deadline for client acknowledgements, viewport updates, and input operations; defaults to 10 seconds. Reaching it aborts the operation signal and suspends the run.
+- `frameDecodeTimeoutMs`: image decode wrapper deadline; defaults to `operationTimeoutMs`. Reaching it suspends the run and closes the decoded bitmap if it completes late, but cannot force the browser's native decode job to settle.
+- `onError`: receives typed `ILiveBrowserCanvasError` values without interrupting renderer cleanup.
+- `onFrameRendered`: called after a current frame has been drawn.
+
+The renderer exposes `start()`, `suspend()`, `resume()`, `stop()`, `insertText()`, `syncViewport()`, and the `isRunning` and `isSuspended` getters. `start()` begins a stopped renderer, while `resume()` is required for a suspended renderer. `syncViewport()` requests a fresh measurement of the configured `resizeTarget`; it is a no-op when no target is configured or the renderer is not running. An explicitly stopped renderer can be started again. The `/web` entry also exports `ILiveBrowserCanvasClient`, `ILiveBrowserCanvasOperationOptions`, `ILiveBrowserCanvasRendererOptions`, `ILiveBrowserCanvasError`, `TLiveBrowserCanvasErrorCode`, and the canonical SmartPuppeteer live-browser contract types.
+
+`LiveBrowserCanvasRenderer` is not a security boundary. The application adapter must authenticate viewers, authorize control, restrict navigation, enforce browser-session ownership, and apply network/egress policy before forwarding commands. The renderer displays webpage viewport pixels only. It does not provide native Chrome UI, audio, extensions, file transfer, clipboard, camera, microphone, or touch emulation.
+
 ### Shutting Down
 
 Always stop the browser instance when done to free resources:
@@ -139,19 +223,21 @@ main();
 
 ## 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 licensed under the MIT License. A copy of the license can be found in the [license](license.md) file.
 
 **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.
 
 ### Trademarks
 
-This 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.
+This 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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
-Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Task Venture Capital GmbH<br>
+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.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By 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.

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -6,8 +6,8 @@ import * as interfaces from './interfaces/index.js';
  * SmartBrowser
  */
 export class SmartBrowser {
-  public headlessBrowser: plugins.smartpuppeteer.puppeteer.Browser;
-  public smartpdf: plugins.smartpdf.SmartPdf;
+  public headlessBrowser!: plugins.smartpuppeteer.puppeteer.Browser;
+  public smartpdf: plugins.smartpdf.SmartPdf | null = null;
 
   /**
    * start the SmartBrowser instance
@@ -20,11 +20,12 @@ export class SmartBrowser {
   /**
    * ensure SmartPdf is initialized (lazy)
    */
-  private async ensureSmartPdf() {
+  private async ensureSmartPdf(): Promise<plugins.smartpdf.SmartPdf> {
     if (!this.smartpdf) {
       this.smartpdf = new plugins.smartpdf.SmartPdf();
       await this.smartpdf.start(this.headlessBrowser);
     }
+    return this.smartpdf;
   }
 
   /**
@@ -43,8 +44,8 @@ export class SmartBrowser {
    * @param urlArg
    */
   public async pdfFromPage(urlArg: string): Promise<plugins.smartpdf.IPdf> {
-    await this.ensureSmartPdf();
-    const result = await this.smartpdf.getFullWebsiteAsSinglePdf(urlArg);
+    const smartpdf = await this.ensureSmartPdf();
+    const result = await smartpdf.getFullWebsiteAsSinglePdf(urlArg);
     return result;
   }
 
@@ -90,4 +91,4 @@ export class SmartBrowser {
 }
 
 import { smartpuppeteer } from './smartbrowser.plugins.js';
-export { smartpuppeteer };
+export { smartpuppeteer };

package/ts_web/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smartbrowser',
+  version: '4.0.0',
+  description: 'A simplified Puppeteer wrapper for easy automation and testing tasks.'
+}