@push.rocks/smartbrowser 3.0.0 → 4.0.0

package/dist_ts_web/interfaces.livebrowsercanvas.d.ts

@@ -1,13 +1,25 @@
 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;
-    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>;
+    /**
+     * 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartbrowser",
-  "version": "3.0.0",
+  "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",
@@ -31,14 +31,14 @@
   "dependencies": {
     "@push.rocks/smartdelay": "^3.1.0",
     "@push.rocks/smartpdf": "^5.0.1",
-    "@push.rocks/smartpuppeteer": "^2.1.0",
+    "@push.rocks/smartpuppeteer": "^2.4.0",
     "@push.rocks/smartunique": "^3.0.10"
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsrun": "^2.0.6",
     "@git.zone/tstest": "^4.0.0",
-    "@types/node": "^26.1.2"
+    "@types/node": "^26.2.0"
   },
   "private": false,
   "files": [

package/readme.hints.md

@@ -1,8 +1,8 @@
 # SmartBrowser Hints
 
-## 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.
+## 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()`
@@ -16,10 +16,15 @@
 - 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.
+- 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.
-- Pressed input is retained until release succeeds, with one retry for transient release failures. Input remains blocked while a release is unresolved.
+- 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

@@ -15,7 +15,7 @@ Install the package with pnpm:
 pnpm add @push.rocks/smartbrowser
 ```
 
-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.
+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
 
@@ -106,7 +106,7 @@ const browser = await smartpuppeteer.getEnvAwareBrowserInstance();
 
 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.
+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 {
@@ -128,7 +128,7 @@ export async function mountLiveBrowser(client: ILiveBrowserCanvasClient) {
 
   await renderer.start();
   return async () => {
-    // Stop the renderer before closing its transport so queued frames can be acknowledged.
+    // Stop the renderer before closing its transport so cancellation reaches the adapter.
     await renderer.stop();
   };
 }
@@ -149,7 +149,19 @@ A minimal host keeps CSS sizing independent from the canvas's encoded backing di
 - 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.
+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.
 
@@ -161,12 +173,12 @@ When `resizeTarget` is supplied, resize updates are deduplicated, serialized, an
 - `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.
+- `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()`, `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.
+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.
 

package/ts/00_commitinfo_data.ts

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

package/ts_web/00_commitinfo_data.ts

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