@lightworkai.official/debug-capture 0.19.7 → 0.19.9

package/dist/replayPack.d.ts

@@ -1,3 +1,4 @@
+import { type PictureEncoder } from "./replayPictures";
 import type { ReplayCapture, ReplayEvent, ReplaySummary } from "./types";
 /** The name the desk looks for. Changing it here changes it nowhere else. */
 export declare const REPLAY_FILENAME = "session-replay.json.gz";
@@ -6,6 +7,12 @@ export interface PackedReplay {
     filename: string;
     summary: ReplaySummary;
 }
+export interface PackOptions {
+    /** JPEG quality for a canvas picture the browser could only make as PNG. Default 0.5. */
+    quality?: number;
+    /** How such a picture is made lighter. Default the browser's own encoder; null skips the step. */
+    lighten?: PictureEncoder | null;
+}
 /** Is there something to attach, before the work of packing it. */
 export declare function hasReplayEvents(replay: ReplayCapture | null | undefined): replay is ReplayCapture;
 /**
@@ -14,9 +21,55 @@ export declare function hasReplayEvents(replay: ReplayCapture | null | undefined
  * The cap is applied to what is SENT — compressed bytes when compression is
  * available — because that is the number the server's per-file limit is
  * measured against.
+ *
+ * Over the cap, a report still carries a recording. Each step below is taken
+ * only when the one before it did not fit, and each gives up less than the
+ * next:
+ *
+ *   1. Safari's PNG canvas pictures saved again as JPEG (replayPictures) —
+ *      nothing visible is lost.
+ *   2. Canvas pictures kept from the latest moment that fits, the earlier
+ *      ones left out: the document as it last looked, over the whole
+ *      recording. A canvas whose picture went plays blank until it is next
+ *      drawn.
+ *   3. Every canvas picture left out: the canvases stay, blank; every
+ *      click, page and field is still there.
+ *   4. Large pictures embedded in the page itself (a `data:` image, a font
+ *      inlined in a stylesheet) swapped for an empty one.
+ *   5. The oldest part left out: the recording is kept in stretches that
+ *      each begin with a full picture of the page (capture/replay — a
+ *      checkout every half of the configured length), so the latest
+ *      stretches play on their own. As many as fit, newest first.
+ *   6. The latest stretch from its start, as far as fits — it then stops
+ *      before the report, and the ticket says by how much.
+ *   7. Long text and styles shortened, when not even the page's own picture
+ *      fits.
+ *
+ * Only a page whose single picture is over the cap after all of that goes
+ * without — millions of elements. CIB-5880 (2026-11-02) went without at
+ * step 3: the strip missed every canvas added after the snapshot, and
+ * Safari's pictures are PNG.
  */
-export declare function packReplay(replay: ReplayCapture | null | undefined, maxBytes: number): Promise<PackedReplay | {
+export declare function packReplay(replay: ReplayCapture | null | undefined, maxBytes: number, options?: PackOptions): Promise<PackedReplay | {
     summary: ReplaySummary;
 }>;
-/** The same replay with every canvas picture removed — the canvases stay, blank. */
-export declare function stripCanvas(events: readonly ReplayEvent[]): ReplayEvent[];
+/**
+ * Every canvas picture removed, in place — the canvases stay, blank. The
+ * snapshot's and those on a canvas added later alike: missing the second
+ * kind is how CIB-5749 went out marked `canvasDropped` with 1.05 MB of
+ * pictures on fourteen canvases still in it. Canvas frames are dropped by
+ * the caller (`isCanvasFrame`). Whether there was anything to remove.
+ */
+export declare function stripCanvas(events: readonly ReplayEvent[]): boolean;
+/**
+ * Large pictures the page itself holds — an `<img src="data:…">`, a font or
+ * background inlined in a stylesheet — swapped for an empty one, in place,
+ * wherever the events carry them: attributes, styles, style rules.
+ */
+export declare function dropEmbedded(events: readonly ReplayEvent[]): boolean;
+/**
+ * The recording in its stretches, each from a Meta and full snapshot to the
+ * next — the units it can be shortened by and still play. Anything before
+ * the first Meta rides with the first stretch.
+ */
+export declare function splitWindows(events: readonly ReplayEvent[]): ReplayEvent[][];

package/dist/replayPictures.d.ts

@@ -0,0 +1,33 @@
+import type { ReplayEvent } from "./types";
+export interface Picture {
+    base64: string;
+    type: string;
+}
+/** A picture as JPEG, or null to keep it as it is. */
+export type PictureEncoder = (picture: Picture) => Promise<Picture | null>;
+/** One place a picture is kept, and how to put a new one there. */
+interface Slot {
+    picture: Picture;
+    put: (next: Picture) => void;
+}
+/** Every canvas picture in the events, wherever the recorder put it. */
+export declare function pictureSlots(events: readonly ReplayEvent[]): Slot[];
+/** Every picture's base64, as often as it occurs — gzip's 32 KB window never sees a picture's earlier copy. */
+export declare function pictureStrings(events: readonly ReplayEvent[]): string[];
+/** Whether there is anything for `lightenPictures` to do — before the work of decoding. */
+export declare function hasHeavyPngs(events: readonly ReplayEvent[]): boolean;
+/**
+ * Each large PNG replaced by what `encode` makes of it, when that is smaller.
+ * The same picture is encoded once however often it recurs — a page's
+ * picture is in every snapshot the recording holds. Returns how many changed.
+ * A picture the encoder fails on stays as it was: this never throws.
+ */
+export declare function lightenPictures(events: ReplayEvent[], encode: PictureEncoder): Promise<number>;
+/**
+ * The browser's own encoder: the PNG decoded, checked opaque pixel by pixel,
+ * and saved as JPEG at `quality`. Null where the browser lacks what it takes
+ * (no `createImageBitmap`), for a picture anything shows through, and for a
+ * browser that hands back something other than a JPEG.
+ */
+export declare function browserJpeg(quality: number): PictureEncoder | null;
+export {};

package/dist/types.d.ts

@@ -189,7 +189,7 @@ export interface ReplayCapture {
  * attachment loads — or say why there is none.
  */
 export interface ReplaySummary {
-    /** Whole seconds covered, when one was attached. */
+    /** Whole seconds covered by what was attached (or, with `omitted`, by what was recorded). */
     seconds?: number;
     events?: number;
     startedAt?: string;
@@ -197,8 +197,16 @@ export interface ReplaySummary {
     /** Size of the attachment as sent, and whether it is gzip. */
     bytes?: number;
     compressed?: boolean;
-    /** The canvas frames were left out to fit under the size cap. */
+    /** Canvas pictures left out: the canvases play blank. */
     canvasDropped?: boolean;
+    /** Large pictures embedded in the page (a `data:` image, an inlined font) left out. */
+    picturesDropped?: boolean;
+    /** Long text and styles shortened — only when not even one picture of the page fitted otherwise. */
+    simplified?: boolean;
+    /** Only part of the recording went: how long the whole was. `seconds` is what was sent. */
+    recordedSeconds?: number;
+    /** The part sent stops this many seconds before the report was made. */
+    endsEarlySeconds?: number;
     /** Present when the host records but this report carries no replay. */
     omitted?: "too-large" | "empty";
 }

package/dist/ui/bubblePlace.d.ts

@@ -14,13 +14,14 @@
  *   Content that scrolls under is not: a floating button over content is what a floating button is. A host may name
  *   more (`chat.avoid: "<selector>"`) or turn it off (`false`).
  *
- *   THE NEAREST FREE PLACE. Up or down its own side first; the other side when that is nearer than a long climb
- *   (`SWITCH_COST`) — a column the height of the window sends it to the other corner, a FAB lifts it above. When a
- *   nearer place frees up it goes back (`settleSpot`): the tray shut, it is above the toggle again. 0.19.6 stayed
- *   where it had stepped to for the rest of the page, which on the real เอกสาร page left it high on the right over
- *   the viewer's ยังไม่มีการวางตรา once the tray was shut. A shift of less than STAY_MARGIN does not move it — no
- *   jitter as the page settles.
- *
+ *   THE NEAREST FREE PLACE (`placeSpot`). What a place costs is the climb plus the move in from its edge, and
+ *   SWITCH_COST more on the other side. Up or down its own column; or a column further in, just past what stands in
+ *   the way; or the other corner. A FAB lifts it above. A toolbar column as tall as the window puts it just inside the
+ *   toolbar, at the same height. 0.19.7 only knew the two corner columns, so on a short window, with the ERP's tray
+ *   filling the right edge and its sidebar the left, it found no free place and stayed on the tray (the owner's
+ *   screenshot, 11-02). When a nearer place frees up it goes back: the tray shut, it is home again. A shift of less than
+ *   STAY_MARGIN does not move it, so it does not jitter as the page settles.
+
  *   A PAGE'S OWN PLACE. The desk's rules (ปุ่มแชท › ตำแหน่งปุ่ม): pages whose path starts so — hidden there, or
  *   started in a corner at a height. The most specific rule wins; a person who moved it keeps their place.
  *
@@ -51,31 +52,28 @@ export declare function blockedRanges(obstacles: readonly Rect[], col: {
 }, viewH: number, size: number): [number, number][];
 /** The free height nearest `want` within [min, max], outside every range (open ends) — null when none. Up wins a tie. Pure. */
 export declare function nearestFreeY(want: number, ranges: readonly [number, number][], min: number, max: number): number | null;
-/**
- * Where the bubble stands: `want` on its side when free, else the nearest free height there — or the other side's when
- * that is cheaper (SWITCH_COST plus its own move). Nothing free anywhere: `want`, as it was. Pure.
- */
-export declare function chooseSpot(want: {
-    side: Side;
-    y: number;
-}, free: Record<Side, readonly [number, number][]>, min: number, max: number): {
+export interface Spot {
     side: Side;
+    /** From its side's edge, px. */
+    x: number;
+    /** Up from the bottom, px. */
     y: number;
-};
+}
+/** The page's boxes across the bubble's column at `x` from `side`'s edge — read off the page, or given in the tests. */
+export type ReadColumn = (side: Side, x: number) => readonly Rect[];
+/** How many columns further in it looks on a side, past what stands in the way. */
+export declare const MAX_SHIFTS = 3;
 /**
- * Where it stands now, given where it stood: the best place (`chooseSpot`), unless where it stands is still free and
- * within STAY_MARGIN of it (`prev` is null when the wish, the page or the person's own place changed). Pure.
+ * Where the bubble stands: `want` when it is free there; else the cheapest free place — up or down its column, a column
+ * further in just past what stands in the way (a toolbar column as tall as the window: just left of it, at the same
+ * height), or the other side's (SWITCH_COST more). What a place costs is the climb plus the move in. A place it already
+ * stands in (`prev`), still free and within STAY_MARGIN of the best, is kept — no jitter as the page settles. Columns
+ * are read only as needed (`read`), and never past the middle of the window. Nothing free anywhere: `want`. Pure.
  */
-export declare function settleSpot(prev: {
-    side: Side;
-    y: number;
-} | null, want: {
-    side: Side;
-    y: number;
-}, free: Record<Side, readonly [number, number][]>, min: number, max: number): {
-    side: Side;
-    y: number;
-};
+export declare function placeSpot(want: Spot, read: ReadColumn, view: {
+    w: number;
+    h: number;
+}, size: number, min: number, max: number, prev?: Spot | null): Spot;
 export interface PlaceRule {
     /** "/saraban/edoc-management" — the page and every page under it; `*` one segment, `**` any. */
     path: string;
@@ -93,7 +91,9 @@ export declare function placeFor(pathname: string, rules: readonly PlaceRule[] |
  * - a host's selector (`extra`): what it names, whole, wherever it is;
  * - in a small floating box (its nearest `fixed`, or `sticky` stuck at its edge): what shows there, by its own box —
  *   the control it is part of, else itself;
- * - in a box as big as the window, or on a page that does not scroll: a control not inside a scroller;
+ * - in a box as big as the window, or on a page that does not scroll: a control not inside a scroller — a disabled one
+ *   too, found by its own selector, as no hit test reaches it (the ERP's ผลการจำแนก panel on a phone, 11-02: its
+ *   greyed มอบหมายผู้ดำเนินการ was under the bubble);
  * - anything else scrolls with the page, and is not.
  */
 export declare function scanColumns(cols: readonly {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightworkai.official/debug-capture",
-  "version": "0.19.7",
+  "version": "0.19.9",
   "description": "Report-a-problem widget: rolling network/console/action capture, optional rrweb session replay, annotated screenshot, and submission to a Lightwork Support host",
   "type": "module",
   "module": "./dist/index.mjs",