@push.rocks/smartbrowser 2.0.11 → 3.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,29 @@
+import type { ILiveBrowserFrame, ILiveBrowserFrameAcknowledgement, ILiveBrowserFrameAcknowledgementRequest, ILiveBrowserInsertTextInput, ILiveBrowserKeyInput, ILiveBrowserMouseInput, ILiveBrowserState, ILiveBrowserViewport, ILiveBrowserWheelInput, TLiveBrowserEventListener } from '@push.rocks/smartpuppeteer';
+export interface ILiveBrowserCanvasClient {
+    getState(): ILiveBrowserState;
+    onEvent(listenerArg: TLiveBrowserEventListener): () => void;
+    acknowledgeFrame(requestArg: ILiveBrowserFrameAcknowledgementRequest): Promise<ILiveBrowserFrameAcknowledgement>;
+    setViewport(viewportArg: ILiveBrowserViewport): Promise<void>;
+    dispatchMouse(inputArg: ILiveBrowserMouseInput): Promise<void>;
+    dispatchWheel(inputArg: ILiveBrowserWheelInput): Promise<void>;
+    dispatchKey(inputArg: ILiveBrowserKeyInput): Promise<void>;
+    insertText(inputArg: ILiveBrowserInsertTextInput): Promise<void>;
+}
+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": "3.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.1.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.1.2"
   },
   "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,25 @@
-# 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-05)
+- `@push.rocks/smartpdf` v5.x uses SmartPuppeteer 2.1/Puppeteer 25 browser types. `SmartPdf` remains lazy and starts only for PDF methods.
+- `@push.rocks/smartpuppeteer` v2.1 owns `LiveBrowserSession` and the canonical transport-neutral live browser contracts.
+- 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. The renderer makes at most one acknowledgement request for each drawn, stale, superseded, failed, or shutdown-retired frame; failures and capacity exhaustion are reported and stop the renderer.
+- Renderer starts and explicit stops are serialized by run epoch. A renderer can restart after an explicit stop. Acknowledgement failures, input-release failures, capacity exhaustion, and client/decode timeouts terminally stop the instance because underlying work is not cancellable through the client interface; create a new renderer and client after those failures.
+- Repeated blur, visibility, and pointer-loss resets coalesce into one bounded reset operation.
+- Pressed input is retained until release succeeds, with one retry for transient release failures. Input remains blocked while a release is unresolved.
+- 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.1, Puppeteer 25, and SmartPDF 5. SmartPuppeteer detects common local, CI, and container environments and configures Chromium accordingly.
 
 ## Usage
 
@@ -98,6 +102,74 @@ 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()`. 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 queued frames can be acknowledged.
+    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()`
+
+The renderer keeps at most one frame decoding and one newest frame queued. It makes one acknowledgement attempt after a frame is drawn, deliberately dropped, found stale, or fails decoding. A failed or timed-out acknowledgement is reported through `onError` and terminally stops the renderer because frame flow control is no longer reliable. Acknowledgement capacity exhaustion also terminally stops the renderer. 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.
+
+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`: timeout for client acknowledgements, viewport updates, and input operations; defaults to 10 seconds. A timeout terminally stops the renderer because the underlying adapter operation cannot be cancelled through this interface.
+- `frameDecodeTimeoutMs`: image decode timeout; defaults to `operationTimeoutMs`. A timeout terminally stops the renderer and closes the decoded bitmap if it completes late.
+- `onError`: receives typed `ILiveBrowserCanvasError` values without interrupting renderer cleanup.
+- `onFrameRendered`: called after a current frame has been drawn.
+
+The renderer exposes `start()`, `stop()`, `insertText()`, `syncViewport()`, and the `isRunning` getter. `syncViewport()` requests a fresh measurement of the configured `resizeTarget`; it is a no-op when no target is configured or the renderer is stopped. An explicitly stopped renderer can be started again. After an acknowledgement failure, input-release failure, capacity exhaustion, or operation/decode timeout, create a new renderer and client instead; the failed instance rejects future `start()` calls because its non-cancellable underlying work may still affect the old client session. The `/web` entry also exports `ILiveBrowserCanvasClient`, `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 +211,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: '3.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: '3.0.0',
+  description: 'A simplified Puppeteer wrapper for easy automation and testing tasks.'
+}